@maravilla-labs/platform 0.2.1 → 0.2.4

package/src/events.ts

@@ -0,0 +1,283 @@
+/**
+ * @fileoverview Event handler registration helpers for Maravilla.
+ *
+ * User apps declare event handlers in `events.ts` or `events/*.ts`:
+ *
+ * ```ts
+ * import { onKvChange, defineEvent } from '@maravilla-labs/platform/events';
+ *
+ * export const invalidateCache = onKvChange(
+ *   { namespace: 'config', keyPattern: 'feature:*' },
+ *   async (event, ctx) => { await ctx.kv.delete('cache', event.key!); },
+ * );
+ * ```
+ *
+ * These helpers are pure factories. They produce a `RegisteredHandler`
+ * marker object that the build pipeline (`@maravilla-labs/functions`
+ * `discoverEvents`) detects by its `__maravilla_trigger` property.
+ * The Rust event dispatcher uses the trigger config from the manifest
+ * and invokes the bundled handler via `globalThis.handleEvent(id, event)`.
+ */
+
+import type { RenEvent } from './ren.js';
+
+// ============ Trigger descriptors ============
+// Kept structurally identical to adapter-core's `EventTrigger` — duplicated
+// here so the runtime SDK has no build-time dep on adapter-core. Keep in sync.
+
+export type EventTrigger =
+  | EventTriggerKv
+  | EventTriggerDb
+  | EventTriggerAuth
+  | EventTriggerSchedule
+  | EventTriggerQueue
+  | EventTriggerChannel
+  | EventTriggerDeploy
+  | EventTriggerRen;
+
+export interface EventTriggerKv {
+  kind: 'kv';
+  namespace?: string;
+  keyPattern?: string;
+  op?: 'put' | 'delete' | 'expired';
+}
+
+export interface EventTriggerDb {
+  kind: 'db';
+  collection: string;
+  op?: 'insert' | 'update' | 'delete';
+}
+
+export type AuthOp =
+  | 'registered'
+  | 'logged_in'
+  | 'logged_out'
+  | 'logged_out_all'
+  | 'deleted'
+  | 'updated';
+
+export interface EventTriggerAuth {
+  kind: 'auth';
+  op?: AuthOp;
+}
+
+export interface EventTriggerSchedule {
+  kind: 'schedule';
+  cron: string;
+}
+
+export interface EventTriggerQueue {
+  kind: 'queue';
+  name: string;
+  batch?: number;
+  maxAttempts?: number;
+}
+
+export interface EventTriggerChannel {
+  kind: 'channel';
+  channel: string;
+  type?: string;
+}
+
+export interface EventTriggerDeploy {
+  kind: 'deploy';
+  phase: 'ready' | 'draining' | 'stopped';
+}
+
+export interface EventTriggerRen {
+  kind: 'ren';
+  match: { r?: string; t?: string; ns?: string };
+}
+
+// ============ Event payload shapes ============
+
+export interface KvChangeEvent {
+  op: 'put' | 'delete' | 'expired';
+  namespace: string;
+  key: string;
+  /** Present on `put`. */
+  value?: unknown;
+  ts: number;
+}
+
+export interface DbChangeEvent {
+  op: 'insert' | 'update' | 'delete';
+  collection: string;
+  id: string;
+  doc?: unknown;
+  before?: unknown;
+  after?: unknown;
+  ts: number;
+}
+
+export interface AuthEvent {
+  op: AuthOp;
+  userId: string;
+  /**
+   * Op-specific payload:
+   * - `registered` → `{ email, provider, profile }` where `profile` is the
+   *   app's custom fields passed to `platform.auth.register({ profile: {...} })`.
+   * - `logged_in` → `{ email }`
+   * - `logged_out` → `{ sessionId }`
+   * - `logged_out_all` / `deleted` / `updated` → null or empty.
+   */
+  data?: {
+    email?: string;
+    provider?: string;
+    profile?: Record<string, unknown> | null;
+    sessionId?: string;
+    [k: string]: unknown;
+  };
+  ts: number;
+}
+
+export interface ScheduleEvent {
+  cron: string;
+  scheduledAt: number;
+  firedAt: number;
+}
+
+export interface QueueMessage<T = unknown> {
+  id: string;
+  payload: T;
+  attempt: number;
+  enqueuedAt: number;
+}
+
+export interface ChannelEvent<T = unknown> {
+  channel: string;
+  type: string;
+  data?: T;
+  uid?: string;
+  ts: number;
+}
+
+export interface DeployEvent {
+  phase: 'ready' | 'draining' | 'stopped';
+  ts: number;
+}
+
+// ============ Handler context ============
+
+export interface EventCtx {
+  /** Per-tenant env vars. */
+  env: Record<string, string>;
+  /** KV store — same shape as `getPlatform().env.KV` / `platform.kv`. */
+  kv?: unknown;
+  /** MongoDB-style database — same shape as `getPlatform().env.DB`. */
+  database?: unknown;
+  /** Object storage. */
+  storage?: unknown;
+  /** Durable queue producer (`.send(name, payload, opts?)`). */
+  queue?: { send: (name: string, payload: unknown, opts?: unknown) => Promise<string> };
+  /** Auth service — register/login/logout/user CRUD/etc. */
+  auth?: unknown;
+  /** Web Push service. */
+  push?: unknown;
+  /** Full platform object — escape hatch for services not surfaced above. */
+  platform?: unknown;
+  /** Trace correlation id — propagate through logs. */
+  traceId: string;
+  tenant: string;
+  handlerId: string;
+}
+
+// ============ Registered handler marker ============
+
+export const TRIGGER_SYMBOL = '__maravilla_trigger' as const;
+
+export interface RegisteredHandler<Event = unknown, Ctx = EventCtx> {
+  readonly [TRIGGER_SYMBOL]: EventTrigger;
+  readonly handler: (event: Event, ctx: Ctx) => unknown | Promise<unknown>;
+}
+
+function register<Event, Ctx = EventCtx>(
+  trigger: EventTrigger,
+  handler: (event: Event, ctx: Ctx) => unknown | Promise<unknown>,
+): RegisteredHandler<Event, Ctx> {
+  return { [TRIGGER_SYMBOL]: trigger, handler };
+}
+
+// ============ Public factory helpers ============
+
+export function onKvChange(
+  config: Omit<EventTriggerKv, 'kind'>,
+  handler: (event: KvChangeEvent, ctx: EventCtx) => unknown | Promise<unknown>,
+): RegisteredHandler<KvChangeEvent> {
+  return register({ kind: 'kv', ...config }, handler);
+}
+
+export function onDbChange(
+  config: Omit<EventTriggerDb, 'kind'>,
+  handler: (event: DbChangeEvent, ctx: EventCtx) => unknown | Promise<unknown>,
+): RegisteredHandler<DbChangeEvent> {
+  return register({ kind: 'db', ...config }, handler);
+}
+
+/**
+ * React to user authentication events: registration, login, logout,
+ * deletion, update. Omit `op` to match all auth events; set it to
+ * narrow to a specific lifecycle transition.
+ *
+ * ```ts
+ * export const welcomeEmail = onAuth(
+ *   { op: 'registered' },
+ *   async (event, ctx) => {
+ *     await sendWelcomeEmail(event.data?.email);
+ *   },
+ * );
+ * ```
+ */
+export function onAuth(
+  config: Omit<EventTriggerAuth, 'kind'>,
+  handler: (event: AuthEvent, ctx: EventCtx) => unknown | Promise<unknown>,
+): RegisteredHandler<AuthEvent> {
+  return register({ kind: 'auth', ...config }, handler);
+}
+
+export function onSchedule(
+  cron: string,
+  handler: (event: ScheduleEvent, ctx: EventCtx) => unknown | Promise<unknown>,
+): RegisteredHandler<ScheduleEvent> {
+  return register({ kind: 'schedule', cron }, handler);
+}
+
+export function onQueue<T = unknown>(
+  name: string,
+  config: Omit<EventTriggerQueue, 'kind' | 'name'>,
+  handler: (messages: QueueMessage<T>[], ctx: EventCtx) => unknown | Promise<unknown>,
+): RegisteredHandler<QueueMessage<T>[]> {
+  return register({ kind: 'queue', name, ...config }, handler);
+}
+
+export function onChannel<T = unknown>(
+  config: Omit<EventTriggerChannel, 'kind'>,
+  handler: (event: ChannelEvent<T>, ctx: EventCtx) => unknown | Promise<unknown>,
+): RegisteredHandler<ChannelEvent<T>> {
+  return register({ kind: 'channel', ...config }, handler);
+}
+
+export function onDeploy(
+  phase: EventTriggerDeploy['phase'],
+  handler: (event: DeployEvent, ctx: EventCtx) => unknown | Promise<unknown>,
+): RegisteredHandler<DeployEvent> {
+  return register({ kind: 'deploy', phase }, handler);
+}
+
+/** Escape hatch for arbitrary `RenEvent` matches. */
+export function defineEvent(
+  config: Omit<EventTriggerRen, 'kind'>,
+  handler: (event: RenEvent, ctx: EventCtx) => unknown | Promise<unknown>,
+): RegisteredHandler<RenEvent> {
+  return register({ kind: 'ren', ...config }, handler);
+}
+
+/** Type guard used by the build-time discoverer and the runtime registry. */
+export function isRegisteredHandler(value: unknown): value is RegisteredHandler {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    TRIGGER_SYMBOL in value &&
+    typeof (value as Record<string, unknown>).handler === 'function'
+  );
+}

package/src/index.ts

@@ -51,6 +51,7 @@ export * from './ren.js';
 export * from './realtime.js';
 export * from './media.js';
 export * from './media-room.js';
+export * from './push.js';
 
 /**
  * Global platform instance injected by Maravilla runtime or development tools.

package/src/push.ts

@@ -0,0 +1,280 @@
+/**
+ * @fileoverview Web Push client SDK for Maravilla tenants.
+ *
+ * Talks to the tenant-origin `/_rt/push` endpoints served by delivery:
+ *   - GET  /vapid-public-key  — fetch the VAPID public key for subscribe
+ *   - POST /subscribe         — create a subscription
+ *   - POST /unsubscribe       — delete a subscription by id (or endpoint)
+ *
+ * The matching service worker is served from `/_rt/push/sw.js` on the
+ * same tenant origin (browsers require same-origin SW registration).
+ */
+
+const DEFAULT_BASE_PATH = '/_rt/push';
+const DEFAULT_SW_PATH = '/_rt/push/sw.js';
+const VISITOR_STORAGE_KEY = 'maravilla.push.visitorId';
+const REGISTER_TIMEOUT_MS = 10_000;
+
+export interface RegisterPushOptions {
+  /** Free-form topic strings to tag this subscription with. */
+  topics?: string[];
+  /** Authenticated user id, if any. Takes precedence over visitorId. */
+  userId?: string | null;
+  /** Anonymous visitor id. If omitted and userId is also omitted, one
+   *  is generated and persisted to localStorage under `maravilla.push.visitorId`. */
+  visitorId?: string | null;
+  /** Override the sw.js path (defaults to `/_platform/push/sw.js`). */
+  swPath?: string;
+  /** Override the API base path (defaults to `/_platform/push`). */
+  basePath?: string;
+}
+
+export interface RegisterPushResult {
+  /** The browser PushSubscription (see Web Push spec). */
+  subscription: PushSubscription;
+  /** Server-issued subscription id — pass this back to unregisterPush. */
+  subscriptionId: string;
+}
+
+interface VapidPublicKeyResponse {
+  publicKey: string;
+  contactEmail?: string;
+}
+
+interface ServerSubscription {
+  id: string;
+  [key: string]: unknown;
+}
+
+function assertPushSupported(): void {
+  if (typeof navigator === 'undefined' || !('serviceWorker' in navigator)) {
+    throw new Error('Web Push is not supported: serviceWorker is unavailable');
+  }
+  if (typeof window === 'undefined' || !('PushManager' in window)) {
+    throw new Error('Web Push is not supported: PushManager is unavailable');
+  }
+}
+
+function base64UrlToArrayBuffer(input: string): ArrayBuffer {
+  const padding = '='.repeat((4 - (input.length % 4)) % 4);
+  const base64 = (input + padding).replace(/-/g, '+').replace(/_/g, '/');
+  const raw = atob(base64);
+  const buffer = new ArrayBuffer(raw.length);
+  const view = new Uint8Array(buffer);
+  for (let i = 0; i < raw.length; i++) {
+    view[i] = raw.charCodeAt(i);
+  }
+  return buffer;
+}
+
+function arrayBufferToBase64Url(buffer: ArrayBuffer | null): string | undefined {
+  if (!buffer) return undefined;
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function randomUuid(): string {
+  const c = typeof crypto !== 'undefined' ? crypto : undefined;
+  if (c && typeof c.randomUUID === 'function') {
+    return c.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (c && typeof c.getRandomValues === 'function') {
+    c.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function resolveVisitorId(
+  userId: string | null | undefined,
+  visitorId: string | null | undefined,
+): string | null {
+  if (visitorId) return visitorId;
+  if (userId) return null;
+  try {
+    const stored = window.localStorage.getItem(VISITOR_STORAGE_KEY);
+    if (stored) return stored;
+    const fresh = randomUuid();
+    window.localStorage.setItem(VISITOR_STORAGE_KEY, fresh);
+    return fresh;
+  } catch {
+    return randomUuid();
+  }
+}
+
+async function fetchVapidPublicKey(basePath: string): Promise<string> {
+  const res = await fetch(`${basePath}/vapid-public-key`, {
+    method: 'GET',
+    credentials: 'same-origin',
+    headers: { Accept: 'application/json' },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch VAPID public key: ${res.status} ${res.statusText}`);
+  }
+  const body = (await res.json()) as VapidPublicKeyResponse;
+  if (!body || typeof body.publicKey !== 'string' || body.publicKey.length === 0) {
+    throw new Error('VAPID public key response is missing `publicKey`');
+  }
+  return body.publicKey;
+}
+
+function extractKeys(sub: PushSubscription): { p256dh?: string; auth?: string } {
+  return {
+    p256dh: arrayBufferToBase64Url(sub.getKey('p256dh')),
+    auth: arrayBufferToBase64Url(sub.getKey('auth')),
+  };
+}
+
+export async function registerPush(
+  opts: RegisterPushOptions = {},
+): Promise<RegisterPushResult> {
+  assertPushSupported();
+
+  const basePath = opts.basePath ?? DEFAULT_BASE_PATH;
+  const swPath = opts.swPath ?? DEFAULT_SW_PATH;
+  const topics = opts.topics ?? [];
+  const userId = opts.userId ?? null;
+  const visitorId = resolveVisitorId(userId, opts.visitorId);
+
+  // Whole-flow timeout. Without this, a stuck pushManager.subscribe() or a
+  // misbehaving push service can leave the UI hanging forever.
+  const timeout = new Promise<never>((_, reject) =>
+    setTimeout(
+      () => reject(new Error(`registerPush timed out after ${REGISTER_TIMEOUT_MS}ms`)),
+      REGISTER_TIMEOUT_MS,
+    ),
+  );
+
+  const flow = (async (): Promise<RegisterPushResult> => {
+    const publicKey = await fetchVapidPublicKey(basePath);
+    // Register the SW. We deliberately do NOT `await navigator.serviceWorker.ready`
+    // here — that promise only resolves when an active SW's scope covers the
+    // current page, but our SW is scoped to `/_rt/push/` and the page is at
+    // `/`. `pushManager.subscribe()` works against the registration returned
+    // by `register()` without needing the SW to control the page.
+    const registration = await navigator.serviceWorker.register(swPath);
+
+    const existing = await registration.pushManager.getSubscription();
+    const subscription =
+      existing ??
+      (await registration.pushManager.subscribe({
+        userVisibleOnly: true,
+        applicationServerKey: base64UrlToArrayBuffer(publicKey),
+      }));
+
+    const { p256dh, auth } = extractKeys(subscription);
+
+    const res = await fetch(`${basePath}/subscribe`, {
+      method: 'POST',
+      credentials: 'same-origin',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: JSON.stringify({
+        provider: 'web-push',
+        endpoint: subscription.endpoint,
+        p256dh,
+        auth,
+        userId,
+        visitorId,
+        topics,
+      }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`Subscribe failed: ${res.status} ${res.statusText}`);
+    }
+
+    const saved = (await res.json()) as ServerSubscription;
+    if (!saved || typeof saved.id !== 'string' || saved.id.length === 0) {
+      throw new Error('Subscribe response is missing `id`');
+    }
+
+    return { subscription, subscriptionId: saved.id };
+  })();
+
+  return Promise.race([flow, timeout]);
+}
+
+export async function unregisterPush(
+  subscriptionId: string,
+  opts: { basePath?: string } = {},
+): Promise<void> {
+  if (!subscriptionId) {
+    throw new Error('subscriptionId is required');
+  }
+  const basePath = opts.basePath ?? DEFAULT_BASE_PATH;
+
+  const res = await fetch(`${basePath}/unsubscribe`, {
+    method: 'POST',
+    credentials: 'same-origin',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ subscriptionId }),
+  });
+
+  if (!res.ok && res.status !== 404) {
+    throw new Error(`Unsubscribe failed: ${res.status} ${res.statusText}`);
+  }
+}
+
+/**
+ * Compute a `Date` that is `offset` before `anchor` — handy for
+ * "X minutes/hours/days before the event" scheduling.
+ *
+ * `offset` is a short duration string:
+ *   - `"30s"` — 30 seconds
+ *   - `"15m"` — 15 minutes
+ *   - `"1h"`  — 1 hour
+ *   - `"2d"`  — 2 days
+ *   - `"1w"`  — 1 week
+ *
+ * Pure function — safe to call on the client. Works with `platform.push.schedule`:
+ *
+ * @example
+ * ```typescript
+ * import { offsetBefore } from '@maravilla-labs/platform';
+ *
+ * await platform.push.schedule(
+ *   { topic: `invite:${invite.id}` },
+ *   { title: invite.title, body: 'Your event is in one hour' },
+ *   {
+ *     at: offsetBefore(invite.event_date, '1h'),
+ *     key: `invite:${invite.id}:reminder-1h`,
+ *   }
+ * );
+ * ```
+ *
+ * @throws if `anchor` is an invalid date string or `offset` isn't a
+ *         recognised duration.
+ */
+export function offsetBefore(anchor: Date | string, offset: string): Date {
+  const anchorDate = anchor instanceof Date ? anchor : new Date(anchor);
+  if (Number.isNaN(anchorDate.getTime())) {
+    throw new Error(`offsetBefore: invalid anchor "${String(anchor)}"`);
+  }
+
+  const match = /^(\d+)\s*(s|m|h|d|w)$/i.exec(offset.trim());
+  if (!match) {
+    throw new Error(
+      `offsetBefore: invalid offset "${offset}" — expected something like "30m", "1h", "2d", "1w"`,
+    );
+  }
+
+  const amount = Number(match[1]);
+  const unit = match[2].toLowerCase();
+  const UNIT_MS: Record<string, number> = {
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+  };
+  return new Date(anchorDate.getTime() - amount * UNIT_MS[unit]);
+}

package/src/remote-client.ts

@@ -1,4 +1,4 @@
-import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, UserListFilter, UserListResponse, UpdateUserOptions } from './types.js';
+import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthCaller, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, UserListFilter, UserListResponse, UpdateUserOptions, PolicyService, VectorIndexSpec, VectorIndexDescriptor, VectorQueryWithFilter, VectorSearchHit, IndexSpec, IndexDescriptor } from './types.js';
 import { RemoteMediaService } from './media.js';
 
 /**
@@ -152,6 +152,59 @@ class RemoteDatabase implements Database {
     // This would need to be implemented properly in the dev server
     return this.deleteOne(collection, filter);
   }
+
+  async createVectorIndex(collection: string, spec: VectorIndexSpec): Promise<void> {
+    await this.fetch(`${this.baseUrl}/api/db/${collection}/vectorIndexes`, {
+      method: 'POST',
+      body: JSON.stringify(spec),
+    });
+  }
+
+  async dropVectorIndex(collection: string, field: string): Promise<{ removed: boolean }> {
+    const response = await this.fetch(
+      `${this.baseUrl}/api/db/${collection}/vectorIndexes/${encodeURIComponent(field)}`,
+      { method: 'DELETE' },
+    );
+    return response.json() as Promise<{ removed: boolean }>;
+  }
+
+  async listVectorIndexes(collection: string): Promise<VectorIndexDescriptor[]> {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/vectorIndexes`, {
+      method: 'GET',
+    });
+    return response.json() as Promise<VectorIndexDescriptor[]>;
+  }
+
+  async findSimilar(collection: string, query: VectorQueryWithFilter): Promise<VectorSearchHit[]> {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/vectorSearch`, {
+      method: 'POST',
+      body: JSON.stringify(query),
+    });
+    return response.json() as Promise<VectorSearchHit[]>;
+  }
+
+  async createIndex(collection: string, spec: IndexSpec): Promise<IndexDescriptor> {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/indexes`, {
+      method: 'POST',
+      body: JSON.stringify(spec),
+    });
+    return response.json() as Promise<IndexDescriptor>;
+  }
+
+  async dropIndex(collection: string, name: string): Promise<{ removed: boolean }> {
+    const response = await this.fetch(
+      `${this.baseUrl}/api/db/${collection}/indexes/${encodeURIComponent(name)}`,
+      { method: 'DELETE' },
+    );
+    return response.json() as Promise<{ removed: boolean }>;
+  }
+
+  async listIndexes(collection: string): Promise<IndexDescriptor[]> {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/indexes`, {
+      method: 'GET',
+    });
+    return response.json() as Promise<IndexDescriptor[]>;
+  }
 }
 
 /**
@@ -528,6 +581,51 @@ class RemoteAuthService implements AuthService {
       }
     };
   }
+
+  // ── Request-scoped identity + authorization ──
+  //
+  // These APIs operate on per-request state inside the platform runtime and
+  // don't have a remote equivalent. Throw so callers get a clear message
+  // instead of silently wrong behavior.
+
+  setCurrentUser(_token: string | null): Promise<void> {
+    return Promise.reject(new Error(
+      'platform.auth.setCurrentUser is only available inside the Maravilla runtime. ' +
+      'Remote clients should pass the Authorization header with each request instead.'
+    ));
+  }
+
+  getCurrentUser(): AuthCaller {
+    throw new Error(
+      'platform.auth.getCurrentUser is only available inside the Maravilla runtime. ' +
+      'Remote clients have no per-request caller context.'
+    );
+  }
+
+  can(_action: string, _resourceId: string, _node?: Record<string, unknown> | null): Promise<boolean> {
+    return Promise.reject(new Error(
+      'platform.auth.can is only available inside the Maravilla runtime. ' +
+      'Remote clients cannot evaluate per-request policies because there is no bound caller.'
+    ));
+  }
+}
+
+/**
+ * Remote stub for the per-request Layer 2 policy toggle. The toggle lives in
+ * per-request state inside the runtime and has no remote equivalent.
+ */
+class RemotePolicyService implements PolicyService {
+  setEnabled(_enabled: boolean): void {
+    throw new Error(
+      'platform.policy.setEnabled is only available inside the Maravilla runtime.'
+    );
+  }
+
+  isEnabled(): boolean {
+    throw new Error(
+      'platform.policy.isEnabled is only available inside the Maravilla runtime.'
+    );
+  }
 }
 
 /**
@@ -572,6 +670,7 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
   const media = new RemoteMediaService(baseUrl, headers);
   const realtime = new RemoteRealtimeService(baseUrl, headers);
   const auth = new RemoteAuthService(baseUrl, headers);
+  const policy = new RemotePolicyService();
 
   return {
     env: {
@@ -582,5 +681,6 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
     media,
     realtime,
     auth,
+    policy,
   };
 }