@cloudinary/apps-sdk

Shared utilities for Cloudinary widget and app components: API gateway client, analytics, auth helpers, and related types (re-exports from @cloudinary/apps-api).

Installation

Published to the public npm registry — no custom registry or auth required:

pnpm add @cloudinary/apps-sdk

Dist-tags:

pnpm add @cloudinary/apps-sdk          # latest (production)
pnpm add @cloudinary/apps-sdk@staging  # staging

Quick usage

ApiGateway

import { ApiGateway } from "@cloudinary/apps-sdk";

const gateway = ApiGateway.create({
  appName: "my-app",
  appVersion: "1.0.0",
});

// Typed OpenAPI clients
const { platform, media, assetManagement } = gateway;

To call the gateway on the console's domain, which authenticates with the console session cookie, set basePath and credentials: "include":

const gateway = ApiGateway.create({
  appName: "my-app",
  appVersion: "1.0.0",
  basePath: "https://gw.console.cloudinary.com/apps",
  credentials: "include",
});

Without credentials: "include" the browser doesn't send the cookie, and the gateway answers 401. Leave it unset for gateways that don't use the cookie: the browser blocks requests made with credentials when the gateway answers Access-Control-Allow-Origin: *.

Analytics

import { ApiGateway, Dispatcher } from "@cloudinary/apps-sdk";

const gateway = ApiGateway.create({
  appName: "my-app",
  appVersion: "1.0.0",
});

const analytics = new Dispatcher(gateway);
analytics.set({ source: "my-widget" });
analytics.collect({ event_name: "widget_opened" });

Login

import {
  CldAuthentication,
  LocalStoragePersistenceProvider,
} from "@cloudinary/apps-sdk";

const auth = new CldAuthentication({
  persistenceProvider: new LocalStoragePersistenceProvider(),
});

const token = await auth.login();