@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

npm install @rentaltide/app-sdk

Quick start

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

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:

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 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:

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.