@maravilla-labs/platform 0.1.41 → 0.1.44

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { LocalParticipant } from 'livekit-client';
-export { RegisterPushOptions, RegisterPushResult, registerPush, unregisterPush } from './push.js';
+export { RegisterPushOptions, RegisterPushResult, offsetBefore, registerPush, unregisterPush } from './push.js';
 
 /**
  * Media service for video/audio room management.
@@ -947,6 +947,213 @@ interface PolicyService {
     /** `true` when Layer 2 is active for this request. */
     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);
+ * ```
+ */
+interface PushTarget {
+    userId?: string;
+    visitorId?: string;
+    topic?: string;
+    userIds?: string[];
+    topics?: string[];
+    onlyActive?: boolean;
+}
+/** Shape of a Web Push notification payload. */
+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`,
+ *   }
+ * );
+ * ```
+ */
+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`. */
+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`. */
+interface ListScheduledFilter {
+    status?: 'pending' | 'running' | 'succeeded' | 'failed';
+    limit?: number;
+    offset?: number;
+}
+/** Counts by status, as returned by `queueStats`. */
+interface QueueStats {
+    pending: number;
+    running: number;
+    succeeded: number;
+    failed: number;
+}
+/** Outcome of a single `platform.push.send(...)` fan-out. */
+interface SendReport {
+    attempted: number;
+    succeeded: number;
+    gone: number;
+    failed: number;
+    errors?: Array<{
+        subscriptionId: string;
+        message: string;
+    }>;
+}
+/** Shape of a stored Web Push subscription. */
+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. */
+interface SubscriptionCounts {
+    total: number;
+    byTopic: Array<[string, number]>;
+    byProvider: Array<[string, number]>;
+}
+/** Public VAPID config for the current project. */
+interface PublicPushConfig {
+    vapidPublic: string;
+    contactEmail: string;
+    updatedAt: number;
+}
+/**
+ * Server-side Web Push service. Access via `platform.push` inside your
+ * runtime code.
+ */
+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>;
+}
 interface Platform {
     /** Environment containing all available platform services */
     env: PlatformEnv;
@@ -958,6 +1165,13 @@ 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;
 }
 
 interface RenEvent {
@@ -1320,4 +1534,4 @@ declare function getPlatform(options?: {
  */
 declare function clearPlatformCache(): void;
 
-export { type AuthCaller, type AuthField, type AuthService, type AuthSession, type AuthUser, type Database, type DbFindOptions, type KvListResult, type KvNamespace, type LoginOptions, MediaLocalParticipant, type MediaParticipant, type MediaParticipantInfo, MediaRoom, MediaRoomEvent, type MediaRoomInfo, type MediaRoomInfoSettings, type MediaRoomOptions, type MediaService, type MediaTokenResult, type MediaTrackPublication, type Platform, type PlatformEnv, type PolicyService, type PresenceMember, type PresenceService, RealtimeClient, type RealtimeClientOptions, type RealtimeEvent, type RealtimeService, type RegisterOptions, RemoteMediaService, RenClient, type RenClientOptions, type RenEvent, type Storage$1 as Storage, type StoragePutStreamSource, type TrackKind, type TrackSource, type UpdateUserOptions, type UserListFilter, type UserListResponse, type VideoResolution, attachTrack, clearPlatformCache, detachTrack, getOrCreateClientId, getPlatform, renFetch, storageDelete, storageUpload };
+export { type AuthCaller, type AuthField, type AuthService, type AuthSession, type AuthUser, type Database, type DbFindOptions, type KvListResult, type KvNamespace, type ListScheduledFilter, type LoginOptions, MediaLocalParticipant, type MediaParticipant, type MediaParticipantInfo, MediaRoom, MediaRoomEvent, type MediaRoomInfo, type MediaRoomInfoSettings, type MediaRoomOptions, type MediaService, type MediaTokenResult, type MediaTrackPublication, type NotificationPayload, type Platform, type PlatformEnv, type PolicyService, type PresenceMember, type PresenceService, type PublicPushConfig, type PushService, type PushTarget, type QueueStats, RealtimeClient, type RealtimeClientOptions, type RealtimeEvent, type RealtimeService, type RegisterOptions, RemoteMediaService, RenClient, type RenClientOptions, type RenEvent, type ScheduleOptions, type ScheduledJob, type SendReport, type Storage$1 as Storage, type StoragePutStreamSource, type StoredPushSubscription, type SubscriptionCounts, type TrackKind, type TrackSource, type UpdateUserOptions, type UserListFilter, type UserListResponse, type VideoResolution, attachTrack, clearPlatformCache, detachTrack, getOrCreateClientId, getPlatform, renFetch, storageDelete, storageUpload };

package/dist/index.js

@@ -1208,9 +1208,10 @@ var MediaRoom = class _MediaRoom {
 };
 
 // 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");
@@ -1296,37 +1297,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) {
@@ -1343,6 +1352,28 @@ 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]);
+}
 
 // src/index.ts
 var cachedPlatform = void 0;
@@ -1389,6 +1420,7 @@ export {
   detachTrack,
   getOrCreateClientId,
   getPlatform,
+  offsetBefore,
   registerPush,
   renFetch,
   storageDelete,