@maravilla-labs/platform 0.1.41 → 0.1.44

package/dist/push.js

@@ -1,7 +1,8 @@
 // src/push.ts
-var DEFAULT_BASE_PATH = "/_platform/push";
-var DEFAULT_SW_PATH = "/_platform/push/sw.js";
+var DEFAULT_BASE_PATH = "/_rt/push";
+var DEFAULT_SW_PATH = "/_rt/push/sw.js";
 var VISITOR_STORAGE_KEY = "maravilla.push.visitorId";
+var REGISTER_TIMEOUT_MS = 1e4;
 function assertPushSupported() {
   if (typeof navigator === "undefined" || !("serviceWorker" in navigator)) {
     throw new Error("Web Push is not supported: serviceWorker is unavailable");
@@ -87,37 +88,45 @@ async function registerPush(opts = {}) {
   const topics = opts.topics ?? [];
   const userId = opts.userId ?? null;
   const visitorId = resolveVisitorId(userId, opts.visitorId);
-  const publicKey = await fetchVapidPublicKey(basePath);
-  const registration = await navigator.serviceWorker.register(swPath);
-  await navigator.serviceWorker.ready;
-  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();
-  if (!saved || typeof saved.id !== "string" || saved.id.length === 0) {
-    throw new Error("Subscribe response is missing `id`");
-  }
-  return { subscription, subscriptionId: saved.id };
+  const timeout = new Promise(
+    (_, reject) => setTimeout(
+      () => reject(new Error(`registerPush timed out after ${REGISTER_TIMEOUT_MS}ms`)),
+      REGISTER_TIMEOUT_MS
+    )
+  );
+  const flow = (async () => {
+    const publicKey = await fetchVapidPublicKey(basePath);
+    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();
+    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]);
 }
 async function unregisterPush(subscriptionId, opts = {}) {
   if (!subscriptionId) {
@@ -134,7 +143,30 @@ async function unregisterPush(subscriptionId, opts = {}) {
     throw new Error(`Unsubscribe failed: ${res.status} ${res.statusText}`);
   }
 }
+function offsetBefore(anchor, offset) {
+  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}" \u2014 expected something like "30m", "1h", "2d", "1w"`
+    );
+  }
+  const amount = Number(match[1]);
+  const unit = match[2].toLowerCase();
+  const UNIT_MS = {
+    s: 1e3,
+    m: 6e4,
+    h: 36e5,
+    d: 864e5,
+    w: 6048e5
+  };
+  return new Date(anchorDate.getTime() - amount * UNIT_MS[unit]);
+}
 export {
+  offsetBefore,
   registerPush,
   unregisterPush
 };

package/dist/push.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.1.41",
+  "version": "0.1.44",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/push.ts

@@ -1,18 +1,19 @@
 /**
  * @fileoverview Web Push client SDK for Maravilla tenants.
  *
- * Talks to the tenant-origin `/_platform/push` endpoints served by delivery:
+ * 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 `/_platform/push/sw.js` on the
+ * 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 = '/_platform/push';
-const DEFAULT_SW_PATH = '/_platform/push/sw.js';
+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. */
@@ -144,45 +145,62 @@ export async function registerPush(
   const userId = opts.userId ?? null;
   const visitorId = resolveVisitorId(userId, opts.visitorId);
 
-  const publicKey = await fetchVapidPublicKey(basePath);
-  const registration = await navigator.serviceWorker.register(swPath);
-  await navigator.serviceWorker.ready;
+  // 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 existing = await registration.pushManager.getSubscription();
-  const subscription =
-    existing ??
-    (await registration.pushManager.subscribe({
-      userVisibleOnly: true,
-      applicationServerKey: base64UrlToArrayBuffer(publicKey),
-    }));
+  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 { p256dh, auth } = extractKeys(subscription);
+    const existing = await registration.pushManager.getSubscription();
+    const subscription =
+      existing ??
+      (await registration.pushManager.subscribe({
+        userVisibleOnly: true,
+        applicationServerKey: base64UrlToArrayBuffer(publicKey),
+      }));
 
-  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,
-    }),
-  });
+    const { p256dh, auth } = extractKeys(subscription);
 
-  if (!res.ok) {
-    throw new Error(`Subscribe failed: ${res.status} ${res.statusText}`);
-  }
+    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,
+      }),
+    });
 
-  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`');
-  }
+    if (!res.ok) {
+      throw new Error(`Subscribe failed: ${res.status} ${res.statusText}`);
+    }
 
-  return { subscription, subscriptionId: saved.id };
+    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(
@@ -205,3 +223,58 @@ export async function unregisterPush(
     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/types.ts

@@ -931,6 +931,233 @@ export interface PolicyService {
   isEnabled(): boolean;
 }
 
+/**
+ * Target selector for Web Push sends. Combine fields to narrow — all
+ * specified conditions must match for a subscription to receive the push.
+ *
+ * @example
+ * ```typescript
+ * // Every subscription tagged with "waitlist"
+ * await platform.push.send({ topic: 'waitlist' }, notification);
+ *
+ * // Every device belonging to one authenticated user
+ * await platform.push.send({ userId: 'u_42' }, notification);
+ *
+ * // "This specific user's subscription for this specific invite"
+ * await platform.push.send({ userId: 'u_42', topic: 'invite:abc:rsvp' }, notification);
+ * ```
+ */
+export interface PushTarget {
+  userId?: string;
+  visitorId?: string;
+  topic?: string;
+  userIds?: string[];
+  topics?: string[];
+  onlyActive?: boolean;
+}
+
+/** Shape of a Web Push notification payload. */
+export interface NotificationPayload {
+  /** Required — the notification headline shown on lock screens and the notification shade. */
+  title: string;
+  body?: string;
+  icon?: string;
+  badge?: string;
+  image?: string;
+  /** Browsers dedupe notifications sharing a tag. */
+  tag?: string;
+  /** Where to navigate when the notification is clicked. */
+  url?: string;
+  /** Arbitrary JSON delivered to the service worker alongside the notification. */
+  data?: Record<string, unknown>;
+  /** Seconds the push service holds the message if the device is offline. */
+  ttl?: number;
+  urgency?: 'very-low' | 'low' | 'normal' | 'high';
+}
+
+/**
+ * Options for `platform.push.schedule(...)`.
+ *
+ * @example
+ * ```typescript
+ * // Remind every RSVP'd guest one hour before the event.
+ * 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`,
+ *   }
+ * );
+ * ```
+ */
+export interface ScheduleOptions {
+  /**
+   * When to send. Absolute `Date` or ISO-8601 string; the server treats
+   * bare (no-offset) strings as UTC.
+   */
+  at: Date | string;
+  /**
+   * Idempotency key scoped to your project. Re-calling `schedule` with the
+   * same key atomically replaces the prior pending job — safe to call on
+   * every save of an invite whose event date may change.
+   */
+  key: string;
+  /** Maximum delivery attempts before the job is marked failed. Defaults to 3. */
+  maxAttempts?: number;
+  /**
+   * If set, the job re-queues after every successful send and fires again
+   * this many seconds later. Use for daily digests (`86400`), weekly
+   * updates (`604800`), or any fixed-interval loop. `cancelScheduled(key)`
+   * stops the loop.
+   */
+  everySeconds?: number;
+}
+
+/** A single scheduled push job as returned by `listScheduled` / `getScheduled`. */
+export interface ScheduledJob {
+  jobId: string;
+  key?: string;
+  /** Next fire time — unix seconds. Convert with `new Date(scheduledFor * 1000)`. */
+  scheduledFor: number;
+  status: 'pending' | 'running' | 'succeeded' | 'failed';
+  attempts: number;
+  maxAttempts: number;
+  lastError?: string;
+  createdAt: number;
+  updatedAt: number;
+  /** Populated once the job has fired at least once. */
+  sentAt?: number;
+  /** Set when the job recurs — `schedule()` was called with `everySeconds`. */
+  recurringIntervalSecs?: number;
+}
+
+/** Filter passed to `listScheduled`. */
+export interface ListScheduledFilter {
+  status?: 'pending' | 'running' | 'succeeded' | 'failed';
+  limit?: number;
+  offset?: number;
+}
+
+/** Counts by status, as returned by `queueStats`. */
+export interface QueueStats {
+  pending: number;
+  running: number;
+  succeeded: number;
+  failed: number;
+}
+
+/** Outcome of a single `platform.push.send(...)` fan-out. */
+export interface SendReport {
+  attempted: number;
+  succeeded: number;
+  gone: number;
+  failed: number;
+  errors?: Array<{ subscriptionId: string; message: string }>;
+}
+
+/** Shape of a stored Web Push subscription. */
+export interface StoredPushSubscription {
+  id: string;
+  provider: 'web-push' | 'apns' | 'fcm';
+  endpoint: string;
+  p256dh?: string | null;
+  auth?: string | null;
+  userId?: string | null;
+  visitorId?: string | null;
+  userAgent?: string | null;
+  topics: string[];
+  createdAt: number;
+  lastSeenAt?: number | null;
+  expiresAt?: number | null;
+  isActive: boolean;
+}
+
+/** Aggregate counts across every subscription in the project. */
+export interface SubscriptionCounts {
+  total: number;
+  byTopic: Array<[string, number]>;
+  byProvider: Array<[string, number]>;
+}
+
+/** Public VAPID config for the current project. */
+export interface PublicPushConfig {
+  vapidPublic: string;
+  contactEmail: string;
+  updatedAt: number;
+}
+
+/**
+ * Server-side Web Push service. Access via `platform.push` inside your
+ * runtime code.
+ */
+export interface PushService {
+  /**
+   * Fan out a notification to every active subscription matching `target`.
+   * Blocks until every device has been tried.
+   */
+  send(target: PushTarget, notification: NotificationPayload): Promise<SendReport>;
+
+  /**
+   * Fire-and-forget variant. The request handler can return immediately;
+   * the dispatch continues in the background. Best-effort — a delivery
+   * restart mid-dispatch loses in-flight sends.
+   */
+  sendBackground(target: PushTarget, notification: NotificationPayload): Promise<void>;
+
+  /**
+   * Queue a notification for a future time. Idempotent by `key` — repeated
+   * calls with the same key replace the prior pending job. Set `everySeconds`
+   * for recurring digests.
+   */
+  schedule(
+    target: PushTarget,
+    notification: NotificationPayload,
+    opts: ScheduleOptions,
+  ): Promise<{ jobId: string }>;
+
+  /** Cancel the pending scheduled job with this idempotency key. */
+  cancelScheduled(key: string): Promise<{ canceled: number }>;
+
+  /** List scheduled jobs for this project, optionally filtered by status. */
+  listScheduled(filter?: ListScheduledFilter): Promise<ScheduledJob[]>;
+
+  /** Look up a single scheduled job by idempotency key. */
+  getScheduled(key: string): Promise<ScheduledJob | null>;
+
+  /** Per-status counts for the scheduled queue. */
+  queueStats(): Promise<QueueStats>;
+
+  /** List subscriptions — useful for admin UIs and debugging. */
+  list(filter?: {
+    topic?: string;
+    userId?: string;
+    visitorId?: string;
+    onlyActive?: boolean;
+    limit?: number;
+    offset?: number;
+  }): Promise<StoredPushSubscription[]>;
+
+  /** Aggregate counts grouped by topic and provider. */
+  counts(): Promise<SubscriptionCounts>;
+
+  /** Remove a subscription by id. */
+  unsubscribe(subscriptionId: string): Promise<void>;
+
+  /** Remove a subscription by its push service endpoint URL. */
+  unsubscribeByEndpoint(endpoint: string): Promise<void>;
+
+  /** Fetch the project's current VAPID public key + contact email. */
+  getVapidConfig(): Promise<PublicPushConfig>;
+
+  /**
+   * Rotate the project's VAPID keypair. **Every existing subscription
+   * silently stops working** — browsers bind subscriptions to the key they
+   * saw at subscribe time. Confirm with your users before calling.
+   */
+  rotateVapidKeys(): Promise<PublicPushConfig>;
+}
+
 export interface Platform {
   /** Environment containing all available platform services */
   env: PlatformEnv;
@@ -942,4 +1169,11 @@ export interface Platform {
   auth: AuthService;
   /** Per-request Layer 2 policy toggle (Layer 1 isolation always applies) */
   policy: PolicyService;
+  /**
+   * Web Push — send, schedule, or query browser push notifications for
+   * logged-in users and anonymous visitors. Available when Push is enabled
+   * in project settings; `undefined` when running against the dev-server
+   * fallback that doesn't proxy to delivery.
+   */
+  push?: PushService;
 }