@rentaltide/app-sdk 0.1.0

package/src/scopes.ts

@@ -0,0 +1,158 @@
+/**
+ * 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 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',
+] as const;
+
+export type Scope = (typeof SCOPES)[number];
+
+export interface ScopeMeta {
+  scope: Scope;
+  label: string;
+  description: string;
+}
+
+export const SCOPE_CATALOG: ScopeMeta[] = [
+  {
+    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.',
+  },
+];
+
+type ScopeResource =
+  | 'bookings'
+  | 'customers'
+  | 'inventory'
+  | 'pos'
+  | 'transactions'
+  | 'analytics'
+  | 'reports';
+
+interface ResourceRule {
+  pattern: RegExp;
+  resource: ScopeResource;
+  /** Some resources are read-only (no write scope exists). */
+  readOnly?: boolean;
+}
+
+/** Ordered most-specific-first; the first match wins. */
+const RESOURCE_RULES: ResourceRule[] = [
+  { 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: ApiMethod, path: string): Scope | null {
+  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}` as Scope;
+  return (SCOPES as readonly string[]).includes(candidate)
+    ? candidate
+    : (`read:${rule.resource}` as Scope);
+}
+
+/** Whether a granted scope set satisfies a required scope (default-deny on null). */
+export function hasScope(granted: string[] | undefined, required: Scope | null): boolean {
+  if (!required) return false;
+  return Array.isArray(granted) && granted.includes(required);
+}

package/src/types.ts

@@ -0,0 +1,115 @@
+/**
+ * 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';