@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 { initXola, XolaEvent } from "@xola/embedded-app-sdk";

const xola = initXola();

// Wait for handshake with the host
const { sellerId, userId, apiUrl } = await xola.handshake();

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

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

// Subscribe to host events
xola.events.subscribe([XolaEvent.PURCHASE_UPDATE, XolaEvent.CONTEXT_CHANGE]);
const off = xola.events.on(XolaEvent.PURCHASE_UPDATE, ({ 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

initXola()

Returns an XolaSDK instance. Call once at app startup.

| Method | Description | | --------------------------- | ---------------------------------------------------- | | handshake(opts?) | Completes host handshake, returns HandshakePayload | | 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 | | ----------------------- | ------------------------ | -------------------- | | CONTEXT_CHANGE | "context.change" | { route, context } | | CANVAS_OPEN | "canvas.open" | { route, context } | | EXPERIENCE_UPDATE | "experience.update" | { id } | | PURCHASE_UPDATE | "purchase.update" | { id } | | PACKAGE_UPDATE | "package.update" | { id } | | EVENT_UPDATE | "event.update" | { id } | | LIVE_CHAT_UPDATE | "liveChat.update" | {} | | XCHAT_DISABLED_UPDATE | "xchatDisabled.update" | { enabled } | | ALL | "*" | { event, data } |

Development

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