@rentaltide/app-sdk 0.1.0

package/README.md

@@ -0,0 +1,150 @@
+# @rentaltide/app-sdk
+
+The official SDK for building **embedded apps** on the RentalTide platform.
+
+An embedded app is a web page you host. RentalTide loads it in a sandboxed
+iframe at one of several **embed locations** (a booking page, the dashboard, the
+POS cart, …). The SDK gives your app a typed, secure bridge to the host:
+
+- **Context** — who the app is installed for, the current location, the resource
+  the user is looking at, the active theme, and the granted scopes.
+- **Scoped API** — make RentalTide API calls proxied through the host. Your app
+  never handles raw tokens, and every call is checked against the scopes the
+  merchant granted.
+- **Host UI** — show toasts, navigate the host, and auto-resize your iframe.
+
+It works with any framework (or none) — it's plain DOM `postMessage` under the
+hood, with zero runtime dependencies.
+
+---
+
+## Install
+
+```bash
+npm install @rentaltide/app-sdk
+```
+
+## Quick start
+
+```ts
+import { createApp } from '@rentaltide/app-sdk';
+
+const app = await createApp();
+
+// 1. Read context the host shared with you
+const { account, location, resource, theme, grantedScopes } = app.context;
+console.log(`Installed for ${account.businessName} (${account.customerId})`);
+if (resource?.type === 'booking') {
+  console.log(`Viewing booking ${resource.id}`);
+}
+
+// 2. Call the RentalTide API — proxied + scope-checked by the host
+const res = await app.api.get('/bookings', { query: { limit: 5 } });
+if (res.ok) renderBookings(res.data);
+
+// 3. Drive the host UI
+app.toast('Synced!', 'success');
+
+// 4. React to changes (dark mode, user navigates to another booking)
+app.onContextChange((ctx) => rerender(ctx));
+app.onThemeChange((t) => applyTheme(t));
+
+// 5. Tell the host you're done loading (also triggers an auto-resize)
+app.ready();
+```
+
+That's the entire surface most apps need.
+
+## The context object
+
+```ts
+interface HostContext {
+  embedLocation: EmbedLocation;        // where you're mounted
+  host: { app: 'rentaltide'; environment: 'production' | 'sandbox'; ... };
+  account: { customerId: string; businessName?: string };
+  location: { locationId: string; name?: string; timezone?: string } | null;
+  user: { id: string; role: string; name?: string } | null;
+  resource: { type: 'booking' | 'order' | 'customer' | ...; id: string } | null;
+  theme: ThemeTokens;                  // match the surrounding UI
+  locale: string;
+  grantedScopes: string[];             // what the merchant granted you
+}
+```
+
+Which `resource` you get depends on the embed location — see
+`EMBED_LOCATIONS` in this package for the full registry.
+
+## Scopes
+
+Declare the scopes your app needs when you register it. The host enforces them
+on every proxied API call. The catalog and the default path → scope policy live
+in this package:
+
+```ts
+import { SCOPE_CATALOG, requiredScope, hasScope } from '@rentaltide/app-sdk';
+
+requiredScope('GET', '/bookings/123'); // 'read:bookings'
+requiredScope('POST', '/customers'); // 'write:customers'
+```
+
+If your app calls an endpoint it wasn't granted, the host rejects the request
+with a `403`-style error — handle it gracefully.
+
+## Theming
+
+`app.context.theme` gives you the host's resolved design tokens (`mode`,
+`primary`, `background`, `paper`, `text`, `radius`, `fontFamily`, …). Apply them
+on load and re-apply in `onThemeChange` so your app follows the merchant's
+light/dark preference seamlessly.
+
+## Local development
+
+Run your app locally and preview it inside a simulated RentalTide using the
+**developer sandbox** in the partner portal — point it at `http://localhost:5173`
+(or wherever your dev server runs), pick an embed location, and watch the live
+message log. See the [starter template](../RentalTide-App-Examples) for a
+ready-to-run project.
+
+## API reference
+
+| Method                                   | Description                                        |
+| ---------------------------------------- | -------------------------------------------------- |
+| `app.context`                            | Latest `HostContext` (updated in place).           |
+| `app.ready()`                            | Signal initial render complete.                    |
+| `app.onContextChange(cb)`                | Subscribe to context updates. Returns unsubscribe. |
+| `app.onThemeChange(cb)`                  | Subscribe to theme updates. Returns unsubscribe.   |
+| `app.api.get/post/put/patch/delete(...)` | Scoped, host-proxied API calls.                    |
+| `app.api.request(req)`                   | Low-level form taking a full `ApiRequest`.         |
+| `app.toast(message, severity?)`          | Show a host snackbar.                              |
+| `app.navigate(path)`                     | Navigate the host app.                             |
+| `app.resize(height?)`                    | Report height (auto by default).                   |
+| `app.refreshContext()`                   | Re-fetch context from the host.                    |
+| `app.destroy()`                          | Tear down the bridge.                              |
+
+## Building the host (RentalTide internal)
+
+The same package exports the host side of the bridge, used by RentalTide and the
+sandbox to mount apps:
+
+```ts
+import { createHostBridge } from '@rentaltide/app-sdk';
+
+const bridge = createHostBridge({
+  iframe,
+  appOrigin, // validated on every message
+  getContext: () => hostContext,
+  onApiRequest: async (req, ctx) => {
+    // enforce ctx.grantedScopes, then proxy to the API
+  },
+  onToast,
+  onNavigate,
+  onResize,
+});
+
+bridge.pushContext(); // when host state changes
+bridge.pushTheme(nextTheme); // on dark-mode toggle
+```
+
+---
+
+MIT © RentalTide Inc.

package/dist/app.d.ts

@@ -0,0 +1,64 @@
+/**
+ * App-side client. Runs inside the embedded iframe and is the only thing most
+ * developers import:
+ *
+ * ```ts
+ * import { createApp } from '@rentaltide/app-sdk';
+ * const app = await createApp();
+ * console.log(app.context.account.customerId);
+ * const res = await app.api.get('/bookings?limit=5');
+ * app.toast('Loaded!', 'success');
+ * ```
+ */
+import type { ApiRequest, ApiResponse, HostContext, ThemeTokens, ToastSeverity } from './types';
+export declare const SDK_VERSION = "0.1.0";
+export interface CreateAppOptions {
+    /**
+     * Origins of the RentalTide host(s) allowed to talk to this app. Defaults to
+     * the document referrer's origin. Set this in production for defense in depth.
+     */
+    hostOrigins?: string[];
+    /** Auto-report content height to the host so the iframe grows to fit. Default true. */
+    autoResize?: boolean;
+    /** Per-request timeout in ms. Default 15000. */
+    timeoutMs?: number;
+    /** Your app's client id, sent on handshake (optional, useful in logs). */
+    appId?: string;
+}
+export interface ApiCallOptions {
+    query?: Record<string, string | number | boolean | undefined>;
+}
+export interface RentalTideApp {
+    /** The latest host context. Updated in place as the host pushes changes. */
+    readonly context: HostContext;
+    /** Tell the host the app has finished its initial render. */
+    ready(): void;
+    /** Subscribe to context changes (e.g. user navigates to another booking). Returns an unsubscribe fn. */
+    onContextChange(cb: (ctx: HostContext) => void): () => void;
+    /** Subscribe to host theme changes (e.g. dark-mode toggle). Returns an unsubscribe fn. */
+    onThemeChange(cb: (theme: ThemeTokens) => void): () => void;
+    /** Scoped, host-proxied RentalTide API. The app never sees raw credentials. */
+    api: {
+        request<T = unknown>(req: ApiRequest): Promise<ApiResponse<T>>;
+        get<T = unknown>(path: string, opts?: ApiCallOptions): Promise<ApiResponse<T>>;
+        post<T = unknown>(path: string, body?: unknown, opts?: ApiCallOptions): Promise<ApiResponse<T>>;
+        put<T = unknown>(path: string, body?: unknown, opts?: ApiCallOptions): Promise<ApiResponse<T>>;
+        patch<T = unknown>(path: string, body?: unknown, opts?: ApiCallOptions): Promise<ApiResponse<T>>;
+        delete<T = unknown>(path: string, opts?: ApiCallOptions): Promise<ApiResponse<T>>;
+    };
+    /** Show a snackbar in the host UI. */
+    toast(message: string, severity?: ToastSeverity): void;
+    /** Ask the host to navigate to an in-app path. */
+    navigate(path: string): void;
+    /** Manually report height (or omit to measure the document). */
+    resize(height?: number): void;
+    /** Re-fetch the current context from the host. */
+    refreshContext(): Promise<HostContext>;
+    /** Tear down listeners and reject any in-flight requests. */
+    destroy(): void;
+}
+/**
+ * Initialize the app bridge. Resolves once the host handshake completes and the
+ * initial {@link HostContext} is available.
+ */
+export declare function createApp(options?: CreateAppOptions): Promise<RentalTideApp>;

package/dist/app.js

@@ -0,0 +1,184 @@
+/**
+ * App-side client. Runs inside the embedded iframe and is the only thing most
+ * developers import:
+ *
+ * ```ts
+ * import { createApp } from '@rentaltide/app-sdk';
+ * const app = await createApp();
+ * console.log(app.context.account.customerId);
+ * const res = await app.api.get('/bookings?limit=5');
+ * app.toast('Loaded!', 'success');
+ * ```
+ */
+import { envelope, isBridgeEnvelope } from './protocol';
+export const SDK_VERSION = '0.1.0';
+function safeOrigin(url) {
+    try {
+        return url ? new URL(url).origin : '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Initialize the app bridge. Resolves once the host handshake completes and the
+ * initial {@link HostContext} is available.
+ */
+export async function createApp(options = {}) {
+    var _a, _b, _c;
+    if (typeof window === 'undefined' || window.parent === window) {
+        throw new Error('[rentaltide-app-sdk] createApp() must run inside the RentalTide host iframe.');
+    }
+    const timeoutMs = (_a = options.timeoutMs) !== null && _a !== void 0 ? _a : 15000;
+    const autoResize = (_b = options.autoResize) !== null && _b !== void 0 ? _b : true;
+    const referrerOrigin = safeOrigin(document.referrer);
+    const allowedOrigins = (_c = options.hostOrigins) !== null && _c !== void 0 ? _c : (referrerOrigin ? [referrerOrigin] : []);
+    let hostOrigin = referrerOrigin || '*';
+    let context = null;
+    const pending = new Map();
+    const contextListeners = new Set();
+    const themeListeners = new Set();
+    const originAllowed = (origin) => allowedOrigins.length === 0 || allowedOrigins.includes(origin);
+    const post = (env) => {
+        window.parent.postMessage(env, hostOrigin);
+    };
+    const sendRequest = (type, payload) => {
+        const env = envelope('request', type, { payload });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pending.delete(env.id);
+                reject(new Error(`[rentaltide-app-sdk] "${type}" timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            pending.set(env.id, { resolve: resolve, reject, timer });
+            post(env);
+        });
+    };
+    const reportHeight = () => {
+        var _a, _b;
+        const height = Math.ceil(((_a = document.documentElement) === null || _a === void 0 ? void 0 : _a.scrollHeight) || ((_b = document.body) === null || _b === void 0 ? void 0 : _b.scrollHeight) || 0);
+        post(envelope('request', 'ui.resize', { payload: { height } }));
+    };
+    const handleMessage = (event) => {
+        var _a;
+        if (event.source !== window.parent)
+            return;
+        if (!isBridgeEnvelope(event.data))
+            return;
+        if (!originAllowed(event.origin))
+            return;
+        // Lock onto the first valid host origin so subsequent posts are targeted.
+        if (hostOrigin === '*')
+            hostOrigin = event.origin;
+        const env = event.data;
+        if (env.kind === 'response' && env.replyTo) {
+            const p = pending.get(env.replyTo);
+            if (!p)
+                return;
+            clearTimeout(p.timer);
+            pending.delete(env.replyTo);
+            if (env.ok === false) {
+                p.reject(new Error(((_a = env.error) === null || _a === void 0 ? void 0 : _a.message) || `Request "${env.type}" failed`));
+            }
+            else {
+                p.resolve(env.payload);
+            }
+            return;
+        }
+        if (env.kind === 'event') {
+            if (env.type === 'context.changed') {
+                context = env.payload;
+                contextListeners.forEach((cb) => cb(context));
+            }
+            else if (env.type === 'theme.changed') {
+                const theme = env.payload;
+                if (context)
+                    context = { ...context, theme };
+                themeListeners.forEach((cb) => cb(theme));
+            }
+            else if (env.type === 'host.closing') {
+                destroy();
+            }
+        }
+    };
+    window.addEventListener('message', handleMessage);
+    let resizeObserver = null;
+    const destroy = () => {
+        window.removeEventListener('message', handleMessage);
+        resizeObserver === null || resizeObserver === void 0 ? void 0 : resizeObserver.disconnect();
+        pending.forEach((p) => {
+            clearTimeout(p.timer);
+            p.reject(new Error('[rentaltide-app-sdk] app bridge destroyed'));
+        });
+        pending.clear();
+        contextListeners.clear();
+        themeListeners.clear();
+    };
+    // Handshake — establishes the host origin and initial context.
+    context = await sendRequest('handshake', {
+        appId: options.appId,
+        sdkVersion: SDK_VERSION,
+    });
+    if (autoResize && typeof ResizeObserver !== 'undefined') {
+        resizeObserver = new ResizeObserver(() => reportHeight());
+        resizeObserver.observe(document.documentElement);
+        reportHeight();
+    }
+    const buildReq = (method, path, body, opts) => ({ method, path, body, query: opts === null || opts === void 0 ? void 0 : opts.query });
+    const api = {
+        request(req) {
+            return sendRequest('api.request', req);
+        },
+        get(path, opts) {
+            return sendRequest('api.request', buildReq('GET', path, undefined, opts));
+        },
+        post(path, body, opts) {
+            return sendRequest('api.request', buildReq('POST', path, body, opts));
+        },
+        put(path, body, opts) {
+            return sendRequest('api.request', buildReq('PUT', path, body, opts));
+        },
+        patch(path, body, opts) {
+            return sendRequest('api.request', buildReq('PATCH', path, body, opts));
+        },
+        delete(path, opts) {
+            return sendRequest('api.request', buildReq('DELETE', path, undefined, opts));
+        },
+    };
+    return {
+        get context() {
+            return context;
+        },
+        ready() {
+            reportHeight();
+        },
+        onContextChange(cb) {
+            contextListeners.add(cb);
+            return () => contextListeners.delete(cb);
+        },
+        onThemeChange(cb) {
+            themeListeners.add(cb);
+            return () => themeListeners.delete(cb);
+        },
+        api,
+        toast(message, severity = 'info') {
+            sendRequest('ui.toast', { message, severity }).catch(() => undefined);
+        },
+        navigate(path) {
+            sendRequest('host.navigate', { path }).catch(() => undefined);
+        },
+        resize(height) {
+            if (typeof height === 'number') {
+                post(envelope('request', 'ui.resize', { payload: { height } }));
+            }
+            else {
+                reportHeight();
+            }
+        },
+        async refreshContext() {
+            const next = await sendRequest('context.get');
+            context = next;
+            return next;
+        },
+        destroy,
+    };
+}

package/dist/embedLocations.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Registry of every surface where an app can embed, with the resource the host
+ * provides there and sensible scope suggestions. Drives the app-creation form,
+ * the sandbox location picker, and the developer docs — one source of truth.
+ */
+import type { EmbedLocation, EmbedResourceType } from './types';
+import type { Scope } from './scopes';
+export interface EmbedLocationMeta {
+    id: EmbedLocation;
+    label: string;
+    description: string;
+    /** Resource type the host provides in `context.resource` here (null if none). */
+    resourceType: EmbedResourceType | null;
+    /** Scopes an app embedding here will typically need. */
+    suggestedScopes: Scope[];
+    /** Rough shape of the embed surface, for layout hints. */
+    surface: 'sidebar' | 'panel' | 'card' | 'fullwidth';
+}
+export declare const EMBED_LOCATIONS: Record<EmbedLocation, EmbedLocationMeta>;
+export declare const EMBED_LOCATION_LIST: EmbedLocationMeta[];
+export declare function getEmbedLocationMeta(id: string): EmbedLocationMeta | undefined;

package/dist/embedLocations.js

@@ -0,0 +1,83 @@
+/**
+ * Registry of every surface where an app can embed, with the resource the host
+ * provides there and sensible scope suggestions. Drives the app-creation form,
+ * the sandbox location picker, and the developer docs — one source of truth.
+ */
+export const EMBED_LOCATIONS = {
+    'dashboard-widget': {
+        id: 'dashboard-widget',
+        label: 'Dashboard widget',
+        description: 'A card on the main operator dashboard. No specific resource in context.',
+        resourceType: null,
+        suggestedScopes: ['read:analytics', 'read:bookings'],
+        surface: 'card',
+    },
+    'order-details': {
+        id: 'order-details',
+        label: 'Order details',
+        description: 'Sidebar panel on an order page. Receives the current order.',
+        resourceType: 'order',
+        suggestedScopes: ['read:bookings'],
+        surface: 'sidebar',
+    },
+    'booking-details': {
+        id: 'booking-details',
+        label: 'Booking details',
+        description: 'Panel on a single booking. Receives the current booking.',
+        resourceType: 'booking',
+        suggestedScopes: ['read:bookings'],
+        surface: 'sidebar',
+    },
+    'customer-profile': {
+        id: 'customer-profile',
+        label: 'Customer profile',
+        description: 'Panel on a customer profile. Receives the current customer.',
+        resourceType: 'customer',
+        suggestedScopes: ['read:customers'],
+        surface: 'panel',
+    },
+    'inventory-detail': {
+        id: 'inventory-detail',
+        label: 'Inventory detail',
+        description: 'Panel on an inventory item. Receives the current inventory item.',
+        resourceType: 'inventory',
+        suggestedScopes: ['read:inventory'],
+        surface: 'panel',
+    },
+    'asset-tracking': {
+        id: 'asset-tracking',
+        label: 'Asset tracking',
+        description: 'Panel on the asset/nav board. Receives the current asset.',
+        resourceType: 'asset',
+        suggestedScopes: ['read:inventory', 'read:bookings'],
+        surface: 'panel',
+    },
+    'checkout-flow': {
+        id: 'checkout-flow',
+        label: 'Checkout flow',
+        description: 'Step injected into the booking checkout. Receives the in-progress cart.',
+        resourceType: 'cart',
+        suggestedScopes: ['read:bookings', 'read:pos'],
+        surface: 'fullwidth',
+    },
+    'pos-cart': {
+        id: 'pos-cart',
+        label: 'POS cart',
+        description: 'Panel beside the point-of-sale cart. Receives the active cart.',
+        resourceType: 'cart',
+        suggestedScopes: ['read:pos', 'write:pos'],
+        surface: 'sidebar',
+    },
+    'settings-panel': {
+        id: 'settings-panel',
+        label: 'Settings panel',
+        description: 'A configuration page reachable from the app-store entry. No resource.',
+        resourceType: null,
+        suggestedScopes: [],
+        surface: 'fullwidth',
+    },
+};
+export const EMBED_LOCATION_LIST = Object.values(EMBED_LOCATIONS);
+export function getEmbedLocationMeta(id) {
+    return EMBED_LOCATIONS[id];
+}

package/dist/events.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Catalog of outbound webhook events RentalTide can send to your app.
+ *
+ * Register a webhook URL + secret and request the `webhooks:receive` scope to
+ * receive these. Each delivery is signed (see the developer docs for
+ * verification). This list mirrors the server's emitter.
+ */
+export interface WebhookEventMeta {
+    event: string;
+    description: string;
+}
+export declare const WEBHOOK_EVENT_CATALOG: WebhookEventMeta[];
+export declare const WEBHOOK_EVENTS: string[];
+export type WebhookEventName = (typeof WEBHOOK_EVENT_CATALOG)[number]['event'];
+/** Shape of every webhook request body RentalTide POSTs to your endpoint. */
+export interface WebhookPayload<T = Record<string, unknown>> {
+    event: string;
+    /** ISO-8601 timestamp the payload was created. */
+    timestamp: string;
+    data: T;
+}

package/dist/events.js

@@ -0,0 +1,22 @@
+/**
+ * Catalog of outbound webhook events RentalTide can send to your app.
+ *
+ * Register a webhook URL + secret and request the `webhooks:receive` scope to
+ * receive these. Each delivery is signed (see the developer docs for
+ * verification). This list mirrors the server's emitter.
+ */
+export const WEBHOOK_EVENT_CATALOG = [
+    { event: 'booking.created', description: 'A new booking/order was created.' },
+    { event: 'booking.updated', description: 'A booking changed (notes, timing, add-ons, assets).' },
+    { event: 'booking.status_changed', description: 'A booking moved to a new status.' },
+    { event: 'booking.checked_in', description: 'A booking was checked in.' },
+    { event: 'booking.cancelled', description: 'A booking was cancelled.' },
+    { event: 'booking.rescheduled', description: 'A booking was rescheduled.' },
+    { event: 'payment.received', description: 'A payment was recorded against a booking.' },
+    { event: 'payment.refunded', description: 'A refund was issued.' },
+    { event: 'customer.created', description: 'A new customer was created.' },
+    { event: 'customer.updated', description: 'A customer record was updated.' },
+    { event: 'app.installed', description: 'Your app was installed by a merchant.' },
+    { event: 'app.uninstalled', description: 'Your app was uninstalled (deprovision here).' },
+];
+export const WEBHOOK_EVENTS = WEBHOOK_EVENT_CATALOG.map((e) => e.event);

package/dist/host.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Host-side bridge. Runs in the RentalTide host (the main app and the developer
+ * sandbox) — one instance per embedded iframe. It answers the app's handshake,
+ * proxies scoped API calls, and forwards UI intents (toast/navigate/resize).
+ *
+ * Security model:
+ *  - Only messages from this iframe's `contentWindow` are accepted.
+ *  - Only messages from the declared `appOrigin` are accepted.
+ *  - `onApiRequest` is responsible for enforcing the installation's granted
+ *    scopes (see {@link requiredScope}/{@link hasScope} in `./scopes`).
+ */
+import { BridgeEnvelope } from './protocol';
+import type { ApiRequest, ApiResponse, HostContext, ThemeTokens, ToastSeverity } from './types';
+export interface CreateHostBridgeOptions {
+    /** The iframe element the app is mounted in. */
+    iframe: HTMLIFrameElement;
+    /**
+     * The exact origin the app is served from (validated on every message).
+     * Use `'*'` only for trusted local sandboxes; never in production.
+     */
+    appOrigin: string;
+    /** Returns the current host context (called on handshake/context.get). */
+    getContext: () => HostContext;
+    /**
+     * Handle a proxied API request. MUST enforce the installation's granted
+     * scopes before performing the call.
+     */
+    onApiRequest: (req: ApiRequest, ctx: HostContext) => Promise<ApiResponse>;
+    onResize?: (height: number) => void;
+    onToast?: (message: string, severity: ToastSeverity) => void;
+    onNavigate?: (path: string) => void;
+    onClose?: () => void;
+    /** Optional observer of all traffic — used by the sandbox message log. */
+    onMessage?: (direction: 'in' | 'out', env: BridgeEnvelope) => void;
+}
+export interface HostBridge {
+    /** Push a fresh context to the app (defaults to `getContext()`). */
+    pushContext(ctx?: HostContext): void;
+    /** Notify the app that the host theme changed. */
+    pushTheme(theme: ThemeTokens): void;
+    /** Tear down the listener and tell the app it's closing. */
+    destroy(): void;
+}
+export declare function createHostBridge(options: CreateHostBridgeOptions): HostBridge;