@rentaltide/app-sdk 0.1.0

package/dist/host.js

@@ -0,0 +1,91 @@
+/**
+ * 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 { envelope, isBridgeEnvelope } from './protocol';
+export function createHostBridge(options) {
+    const { iframe, appOrigin, getContext, onApiRequest, onResize, onToast, onNavigate, onClose, onMessage, } = options;
+    // `srcdoc`/sandboxed iframes report a `null` origin; postMessage must use '*'.
+    const postTarget = appOrigin === 'null' ? '*' : appOrigin;
+    const send = (env) => {
+        var _a;
+        onMessage === null || onMessage === void 0 ? void 0 : onMessage('out', env);
+        (_a = iframe.contentWindow) === null || _a === void 0 ? void 0 : _a.postMessage(env, postTarget);
+    };
+    const respond = (replyTo, type, payload) => {
+        send(envelope('response', type, { replyTo, ok: true, payload }));
+    };
+    const respondError = (replyTo, type, code, message) => {
+        send(envelope('response', type, { replyTo, ok: false, error: { code, message } }));
+    };
+    const handleMessage = async (event) => {
+        var _a;
+        if (event.source !== iframe.contentWindow)
+            return;
+        if (appOrigin !== '*' && appOrigin !== 'null' && event.origin !== appOrigin)
+            return;
+        if (!isBridgeEnvelope(event.data))
+            return;
+        const env = event.data;
+        if (env.kind !== 'request')
+            return;
+        onMessage === null || onMessage === void 0 ? void 0 : onMessage('in', env);
+        try {
+            switch (env.type) {
+                case 'handshake':
+                case 'context.get':
+                    respond(env.id, env.type, getContext());
+                    break;
+                case 'api.request': {
+                    const res = await onApiRequest(env.payload, getContext());
+                    respond(env.id, env.type, res);
+                    break;
+                }
+                case 'ui.resize':
+                    // Fire-and-forget; the app does not await a response.
+                    onResize === null || onResize === void 0 ? void 0 : onResize(env.payload.height);
+                    break;
+                case 'ui.toast': {
+                    const p = env.payload;
+                    onToast === null || onToast === void 0 ? void 0 : onToast(p.message, (_a = p.severity) !== null && _a !== void 0 ? _a : 'info');
+                    respond(env.id, env.type);
+                    break;
+                }
+                case 'host.navigate':
+                    onNavigate === null || onNavigate === void 0 ? void 0 : onNavigate(env.payload.path);
+                    respond(env.id, env.type);
+                    break;
+                case 'host.close':
+                    onClose === null || onClose === void 0 ? void 0 : onClose();
+                    respond(env.id, env.type);
+                    break;
+                default:
+                    respondError(env.id, env.type, 'unknown_method', `Unknown method: ${env.type}`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Host error';
+            respondError(env.id, env.type, 'host_error', message);
+        }
+    };
+    window.addEventListener('message', handleMessage);
+    return {
+        pushContext(ctx) {
+            send(envelope('event', 'context.changed', { payload: ctx !== null && ctx !== void 0 ? ctx : getContext() }));
+        },
+        pushTheme(theme) {
+            send(envelope('event', 'theme.changed', { payload: theme }));
+        },
+        destroy() {
+            send(envelope('event', 'host.closing'));
+            window.removeEventListener('message', handleMessage);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @rentaltide/app-sdk — Official SDK for building embedded apps on RentalTide.
+ *
+ * App developers import the app-side client:
+ *   import { createApp } from '@rentaltide/app-sdk';
+ *
+ * The RentalTide host (and the developer sandbox) import the host bridge:
+ *   import { createHostBridge } from '@rentaltide/app-sdk';
+ */
+export * from './types';
+export * from './protocol';
+export * from './scopes';
+export * from './embedLocations';
+export * from './events';
+export { createApp, SDK_VERSION } from './app';
+export type { CreateAppOptions, ApiCallOptions, RentalTideApp } from './app';
+export { createHostBridge } from './host';
+export type { CreateHostBridgeOptions, HostBridge } from './host';

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * @rentaltide/app-sdk — Official SDK for building embedded apps on RentalTide.
+ *
+ * App developers import the app-side client:
+ *   import { createApp } from '@rentaltide/app-sdk';
+ *
+ * The RentalTide host (and the developer sandbox) import the host bridge:
+ *   import { createHostBridge } from '@rentaltide/app-sdk';
+ */
+// Data shapes
+export * from './types';
+// Wire protocol (envelopes, request/event maps, helpers)
+export * from './protocol';
+// OAuth scopes + the API-proxy scope policy
+export * from './scopes';
+// Embed-location registry
+export * from './embedLocations';
+// Webhook event catalog
+export * from './events';
+// App-side client (runs in the iframe)
+export { createApp, SDK_VERSION } from './app';
+// Host-side bridge (runs in RentalTide / the sandbox)
+export { createHostBridge } from './host';

package/dist/protocol.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The wire protocol for the RentalTide App Bridge.
+ *
+ * Host and embedded app communicate exclusively over `window.postMessage`.
+ * Every message is a {@link BridgeEnvelope} stamped with a namespace marker and
+ * protocol version so unrelated `message` events (and other postMessage users on
+ * the page) are ignored.
+ */
+import type { ApiRequest, ApiResponse, HostContext, ThemeTokens, ToastSeverity } from './types';
+export declare const PROTOCOL_VERSION = "1";
+/** Marker present on every bridge message; used to filter foreign messages. */
+export declare const BRIDGE_NAMESPACE = "rentaltide-app-bridge";
+export type MessageKind = 'request' | 'response' | 'event';
+export interface BridgeError {
+    code: string;
+    message: string;
+}
+export interface BridgeEnvelope<P = unknown> {
+    /** Always {@link BRIDGE_NAMESPACE}. */
+    __rt: typeof BRIDGE_NAMESPACE;
+    /** Protocol version (see {@link PROTOCOL_VERSION}). */
+    v: string;
+    /** Unique message id used to correlate responses to requests. */
+    id: string;
+    kind: MessageKind;
+    /** Method name (requests/responses) or event name (events). */
+    type: string;
+    payload?: P;
+    /** Present on responses. */
+    ok?: boolean;
+    /** Present on failed responses. */
+    error?: BridgeError;
+    /** Id of the request a response is answering. */
+    replyTo?: string;
+}
+/**
+ * App → Host request methods, with their request and response payload types.
+ * This is the canonical reference for what an app may ask the host to do.
+ */
+export interface RequestMap {
+    handshake: {
+        req: {
+            appId?: string;
+            sdkVersion: string;
+        };
+        res: HostContext;
+    };
+    'context.get': {
+        req: void;
+        res: HostContext;
+    };
+    'api.request': {
+        req: ApiRequest;
+        res: ApiResponse;
+    };
+    'ui.toast': {
+        req: {
+            message: string;
+            severity?: ToastSeverity;
+        };
+        res: void;
+    };
+    'ui.resize': {
+        req: {
+            height: number;
+        };
+        res: void;
+    };
+    'host.navigate': {
+        req: {
+            path: string;
+        };
+        res: void;
+    };
+    'host.close': {
+        req: void;
+        res: void;
+    };
+}
+export type RequestType = keyof RequestMap;
+/** Host → App events, with their payload types. */
+export interface EventMap {
+    'context.changed': HostContext;
+    'theme.changed': ThemeTokens;
+    'host.closing': void;
+}
+export type EventType = keyof EventMap;
+/** Narrowing type guard for incoming `message` events. */
+export declare function isBridgeEnvelope(data: unknown): data is BridgeEnvelope;
+/** Generates a correlation id (RFC4122 v4 when crypto is available). */
+export declare function newId(): string;
+/** Builds a well-formed envelope. */
+export declare function envelope<P>(kind: MessageKind, type: string, parts?: Partial<BridgeEnvelope<P>>): BridgeEnvelope<P>;

package/dist/protocol.js

@@ -0,0 +1,44 @@
+/**
+ * The wire protocol for the RentalTide App Bridge.
+ *
+ * Host and embedded app communicate exclusively over `window.postMessage`.
+ * Every message is a {@link BridgeEnvelope} stamped with a namespace marker and
+ * protocol version so unrelated `message` events (and other postMessage users on
+ * the page) are ignored.
+ */
+export const PROTOCOL_VERSION = '1';
+/** Marker present on every bridge message; used to filter foreign messages. */
+export const BRIDGE_NAMESPACE = 'rentaltide-app-bridge';
+/** Narrowing type guard for incoming `message` events. */
+export function isBridgeEnvelope(data) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const env = data;
+    return (env.__rt === BRIDGE_NAMESPACE &&
+        typeof env.id === 'string' &&
+        typeof env.kind === 'string' &&
+        typeof env.type === 'string');
+}
+/** Generates a correlation id (RFC4122 v4 when crypto is available). */
+export function newId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/** Builds a well-formed envelope. */
+export function envelope(kind, type, parts = {}) {
+    var _a;
+    return {
+        __rt: BRIDGE_NAMESPACE,
+        v: PROTOCOL_VERSION,
+        id: (_a = parts.id) !== null && _a !== void 0 ? _a : newId(),
+        kind,
+        type,
+        ...parts,
+    };
+}

package/dist/scopes.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OAuth scope catalog and the default scope policy for the API proxy.
+ *
+ * The host enforces scopes on every proxied API call. The mapping below is the
+ * canonical default (also rendered in the developer docs and the app-creation
+ * form). The host may layer additional, stricter rules on top — but it should
+ * never grant access broader than what's declared here.
+ */
+import type { ApiMethod } from './types';
+export declare const SCOPES: readonly ["read:bookings", "write:bookings", "read:customers", "write:customers", "read:inventory", "write:inventory", "read:pos", "write:pos", "read:transactions", "write:transactions", "read:analytics", "read:reports", "read:geofence", "write:geofence", "audio_calling", "webhooks:receive"];
+export type Scope = (typeof SCOPES)[number];
+export interface ScopeMeta {
+    scope: Scope;
+    label: string;
+    description: string;
+}
+export declare const SCOPE_CATALOG: ScopeMeta[];
+/**
+ * Resolve the scope a given API call requires. Returns `null` for paths that
+ * don't match any rule — callers should treat `null` as "deny unless explicitly
+ * allowed" rather than "no scope needed".
+ */
+export declare function requiredScope(method: ApiMethod, path: string): Scope | null;
+/** Whether a granted scope set satisfies a required scope (default-deny on null). */
+export declare function hasScope(granted: string[] | undefined, required: Scope | null): boolean;

package/dist/scopes.js

@@ -0,0 +1,129 @@
+/**
+ * OAuth scope catalog and the default scope policy for the API proxy.
+ *
+ * The host enforces scopes on every proxied API call. The mapping below is the
+ * canonical default (also rendered in the developer docs and the app-creation
+ * form). The host may layer additional, stricter rules on top — but it should
+ * never grant access broader than what's declared here.
+ */
+export const SCOPES = [
+    'read:bookings',
+    'write:bookings',
+    'read:customers',
+    'write:customers',
+    'read:inventory',
+    'write:inventory',
+    'read:pos',
+    'write:pos',
+    'read:transactions',
+    'write:transactions',
+    'read:analytics',
+    'read:reports',
+    'read:geofence',
+    'write:geofence',
+    'audio_calling',
+    'webhooks:receive',
+];
+export const SCOPE_CATALOG = [
+    {
+        scope: 'read:bookings',
+        label: 'Read bookings',
+        description: 'View bookings, orders, and rental schedules.',
+    },
+    {
+        scope: 'write:bookings',
+        label: 'Manage bookings',
+        description: 'Create, update, and cancel bookings and orders.',
+    },
+    {
+        scope: 'read:customers',
+        label: 'Read customers',
+        description: 'View customer and renter profiles.',
+    },
+    {
+        scope: 'write:customers',
+        label: 'Manage customers',
+        description: 'Create and update customer records.',
+    },
+    {
+        scope: 'read:inventory',
+        label: 'Read inventory',
+        description: 'View inventory, assets, and availability.',
+    },
+    {
+        scope: 'write:inventory',
+        label: 'Manage inventory',
+        description: 'Update inventory, assets, and pricing.',
+    },
+    { scope: 'read:pos', label: 'Read POS', description: 'View point-of-sale catalog and carts.' },
+    { scope: 'write:pos', label: 'Manage POS', description: 'Create POS orders and carts.' },
+    {
+        scope: 'read:transactions',
+        label: 'Read transactions',
+        description: 'View payments and transaction history.',
+    },
+    {
+        scope: 'write:transactions',
+        label: 'Manage transactions',
+        description: 'Initiate payments and refunds.',
+    },
+    {
+        scope: 'read:analytics',
+        label: 'Read analytics',
+        description: 'View aggregated metrics and dashboards.',
+    },
+    { scope: 'read:reports', label: 'Read reports', description: 'View and export reports.' },
+    {
+        scope: 'read:geofence',
+        label: 'Read locations',
+        description: 'View geofences and asset/staff GPS positions.',
+    },
+    {
+        scope: 'write:geofence',
+        label: 'Manage locations',
+        description: 'Create and update geofences / push telematics.',
+    },
+    {
+        scope: 'audio_calling',
+        label: 'Voice calls',
+        description: 'Initiate and manage voice calls (AI phone).',
+    },
+    {
+        scope: 'webhooks:receive',
+        label: 'Receive webhooks',
+        description: 'Receive event notifications from RentalTide.',
+    },
+];
+/** Ordered most-specific-first; the first match wins. */
+const RESOURCE_RULES = [
+    { pattern: /^\/(transactions|pos-transactions|payments|refunds)\b/, resource: 'transactions' },
+    { pattern: /^\/(pos|carts)\b/, resource: 'pos' },
+    { pattern: /^\/(bookings|orders|inventory-schedules|schedules|rentals)\b/, resource: 'bookings' },
+    { pattern: /^\/(customers|renters|booking-customers)\b/, resource: 'customers' },
+    { pattern: /^\/(inventory|pos-inventory|assets|availability)\b/, resource: 'inventory' },
+    { pattern: /^\/(analytics|metrics|dashboard)\b/, resource: 'analytics', readOnly: true },
+    { pattern: /^\/(reports|exports)\b/, resource: 'reports', readOnly: true },
+];
+/**
+ * Resolve the scope a given API call requires. Returns `null` for paths that
+ * don't match any rule — callers should treat `null` as "deny unless explicitly
+ * allowed" rather than "no scope needed".
+ */
+export function requiredScope(method, path) {
+    const clean = (path.split('?')[0] || '').replace(/\/+$/, '') || '/';
+    const normalized = clean.startsWith('/') ? clean : `/${clean}`;
+    const rule = RESOURCE_RULES.find((r) => r.pattern.test(normalized));
+    if (!rule)
+        return null;
+    const isWrite = method !== 'GET' && !rule.readOnly;
+    const candidate = `${isWrite ? 'write' : 'read'}:${rule.resource}`;
+    return SCOPES.includes(candidate)
+        ? candidate
+        : `read:${rule.resource}`;
+}
+/** Whether a granted scope set satisfies a required scope (default-deny on null). */
+export function hasScope(granted, required) {
+    if (!required)
+        return false;
+    return Array.isArray(granted) && granted.includes(required);
+}

package/dist/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Core data shapes exchanged between the RentalTide host and an embedded app.
+ *
+ * These types are the public contract for app developers. They are intentionally
+ * conservative: the host only ever shares non-sensitive identifiers and the
+ * resource the user is currently looking at. Anything else must be fetched
+ * through the scoped {@link ApiRequest} proxy.
+ */
+/** Surfaces inside RentalTide where an app's iframe can be mounted. */
+export type EmbedLocation = 'dashboard-widget' | 'order-details' | 'booking-details' | 'customer-profile' | 'inventory-detail' | 'asset-tracking' | 'checkout-flow' | 'pos-cart' | 'settings-panel';
+export type ThemeMode = 'light' | 'dark';
+/**
+ * The host's resolved design tokens. Embedded apps should consume these so they
+ * visually match the surrounding RentalTide UI (and react to dark-mode toggles).
+ */
+export interface ThemeTokens {
+    mode: ThemeMode;
+    primary: string;
+    primaryContrast: string;
+    /** Page background behind the embed surface. */
+    background: string;
+    /** Card / surface background. */
+    paper: string;
+    text: string;
+    textSecondary: string;
+    divider: string;
+    /** Base border radius in pixels. */
+    radius: number;
+    fontFamily: string;
+}
+export interface HostInfo {
+    app: 'rentaltide';
+    environment: 'production' | 'sandbox';
+    hostVersion: string;
+    protocolVersion: string;
+}
+export interface AccountContext {
+    /** The RentalTide customer (business) the app is installed for. */
+    customerId: string;
+    businessName?: string;
+}
+export interface LocationContext {
+    locationId: string;
+    name?: string;
+    timezone?: string;
+    currency?: string;
+}
+/** Non-sensitive details about the staff user currently viewing the embed. */
+export interface UserContext {
+    id: string;
+    role: string;
+    name?: string;
+}
+export type EmbedResourceType = 'booking' | 'order' | 'customer' | 'inventory' | 'asset' | 'cart';
+/**
+ * The entity the user is currently looking at, when the embed location implies
+ * one (e.g. a booking on `booking-details`). `data` is a lightweight summary;
+ * use the API proxy for the full record.
+ */
+export type EmbedResource = {
+    type: EmbedResourceType;
+    id: string;
+    summary?: Record<string, unknown>;
+} | null;
+/** The full snapshot of host state handed to an app on handshake. */
+export interface HostContext {
+    embedLocation: EmbedLocation;
+    host: HostInfo;
+    account: AccountContext;
+    location: LocationContext | null;
+    user: UserContext | null;
+    resource: EmbedResource;
+    theme: ThemeTokens;
+    locale: string;
+    /** OAuth scopes this installation was actually granted. */
+    grantedScopes: string[];
+}
+export type ApiMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** A request the app asks the host to proxy against the RentalTide API. */
+export interface ApiRequest {
+    method: ApiMethod;
+    /** API path relative to the RentalTide API root, e.g. `/bookings/123`. */
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+}
+export interface ApiResponse<T = unknown> {
+    status: number;
+    ok: boolean;
+    data: T;
+}
+export type ToastSeverity = 'success' | 'info' | 'warning' | 'error';

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Core data shapes exchanged between the RentalTide host and an embedded app.
+ *
+ * These types are the public contract for app developers. They are intentionally
+ * conservative: the host only ever shares non-sensitive identifiers and the
+ * resource the user is currently looking at. Anything else must be fetched
+ * through the scoped {@link ApiRequest} proxy.
+ */
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@rentaltide/app-sdk",
+  "version": "0.1.0",
+  "description": "Official SDK for building embedded apps on the RentalTide platform.",
+  "license": "MIT",
+  "author": "RentalTide Inc.",
+  "homepage": "https://docs.rentaltide.com/developers/app-sdk/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RentalTide/RentalTide.git",
+    "directory": "packages/RentalTide-App-SDK"
+  },
+  "bugs": {
+    "url": "https://github.com/RentalTide/RentalTide/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "rentaltide",
+    "app-sdk",
+    "oauth",
+    "embed",
+    "marketplace",
+    "postmessage"
+  ],
+  "sideEffects": false
+}