@xola/embedded-app-sdk

SDK for third-party apps embedded inside the Xola seller dashboard via iframe. Provides postMessage RPC, authentication, fetch, navigation, and event subscriptions.

Standalone package. Not registered as an npm workspace in this monorepo. No internal apps consume it directly. Build and publish it independently to npm.

Install

npm install @xola/embedded-app-sdk

Usage

import { initialize, XolaEvent } from "@xola/embedded-app-sdk";

// Single entry point: sets up the SDK and completes the host handshake.
// Resolves with the ready SDK and the handshake `session`.
const { xola, session } = await initialize({ apiVersion: "2025-07-07" });
const { sellerId, userId, apiUrl } = session;

// Make authenticated API calls
const data = await xola.fetch("/api/experiences");

// Get a fresh auth token
const token = await xola.auth.getToken();

// Subscribe to host events
xola.events.subscribe([XolaEvent.DATA_PURCHASE, XolaEvent.UI_NAVIGATE]);
const off = xola.events.on(XolaEvent.DATA_PURCHASE, ({ id }) => {
    console.log("Purchase updated:", id);
});

// UI utilities
xola.ui.toast("success", "Saved!");
xola.ui.drawer.close();

// Show this app as a canvas (for canvasType=none apps)
await xola.ui.canvas.show({ canvasType: "drawer", canvasSize: "large" });

API

initialize({ apiVersion })

Async. Sets up the SDK, completes the host handshake, and resolves with { xola, session }: the XolaSDK instance and the HandshakePayload. Rejects if the handshake fails/times out (e.g. opened outside the host). Call once at app startup.

| Method | Description | | --------------------------- | ---------------------------------------------------- | | context.get() | Fetches current route + context from host | | events.on(name, cb) | Registers a local listener, returns unsubscribe fn | | events.subscribe(names) | Tells host to push named events to this app | | events.unsubscribe(names) | Stops host from pushing named events | | auth.getToken(opts?) | Returns cached or fresh auth token | | apps.listInstalled() | Lists plugins installed on the seller account | | fetch(path, init?) | Authenticated fetch via host proxy | | navigate(route, opts?) | Navigates host app to route | | ui.toast(type, msg) | Shows toast in host UI | | ui.drawer.close() | Closes host drawer | | ui.canvas.show(config?) | Shows app as canvas (drawer/modal) | | ui.canvas.hide() | Hides the canvas |

XolaEvent

Event name constants for events.subscribe / events.on:

| Constant | Value | Payload | | ----------------- | ------------------- | -------------------------------------------------- | | UI_NAVIGATE | "ui.navigate" | { route, context } | | UI_CANVAS_OPEN | "ui.canvas.open" | { route, context } | | UI_CANVAS_CLOSE | "ui.canvas.close" | { canvasType } | | UI_TRIGGER | "ui.trigger" | { location, triggerType, route, context } | | DATA_EXPERIENCE | "data.experience" | { id } | | DATA_PURCHASE | "data.purchase" | { id } | | DATA_PACKAGE | "data.package" | { id } | | DATA_EVENT | "data.event" | { id } | | ALL | "*" | { event, data } |

Development

npm ci             # install deps
npm run typecheck  # type-check without emit
npm run test       # run tests
npm run build      # compile to dist/