@proveanything/smartlinks 2.0.55 → 2.0.56

package/dist/api/realtime.d.ts

@@ -1,103 +1,46 @@
-import type { AblyTokenRequest, RealtimeTokenRequest } from "../types/realtime.js";
+import type { AblyTokenRequest, RealtimeTokenRequest, RealtimeChangeEvent, RealtimeChangeFilter, RealtimeMessage, RealtimeScope } from "../types/realtime.js";
 /**
- * Real-Time Communications API
+ * One of your app's declared channels (manifest `realtime.channels`).
  *
- * Provides access to real-time communication channels using Ably.
- * Supports both public (user-scoped) and admin tokens for different permission levels.
- *
- * Channel Patterns:
- * - With appId: collection:{collectionId}:app:{appId}:*
- * - Without appId: collection:{collectionId}:*
- *
- * @example
  * ```ts
- * import { realtime } from '@proveanything/smartlinks'
- *
- * // Get token for public user
- * const tokenRequest = await realtime.getPublicToken({
- *   collectionId: 'abc123',
- *   appId: 'xyz789'
- * })
- *
- * // Initialize Ably client
- * const ably = new Ably.Realtime.Promise({
- *   authCallback: async (data, callback) => {
- *     callback(null, tokenRequest)
- *   }
- * })
- *
- * // Subscribe to a channel
- * const channel = ably.channels.get('collection:abc123:app:xyz789:chat:room-1')
- * await channel.subscribe((message) => {
- *   console.log('Received:', message.data)
- * })
- *
- * // Publish a message
- * await channel.publish('message', { text: 'Hello!', userId: '123' })
+ * const draw = realtime.channel({ collectionId, appId }, "draw")
+ * const off = draw.subscribe("status", (m) => setStatus(m.data))
+ * await draw.publish("status", { phase: "spinning" }) // if the channel lets this viewer publish
  * ```
  */
+export declare function channel(scope: RealtimeScope & {
+    appId: string;
+}, name: string): {
+    /** Listen for an event (or "*" for every event). Returns a function that stops listening. */
+    subscribe(event: string, onMessage: (msg: RealtimeMessage) => void): () => void;
+    /** Send a message. Refused (403) unless the channel's `publish` rule allows this viewer. */
+    publish(event: string, data?: unknown): Promise<{
+        ok: true;
+    }>;
+};
 /**
- * Get an Ably token for public (user-scoped) real-time communication.
+ * Something changed: refetch it. IDs only — never data.
  *
- * This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client
- * with appropriate permissions for the specified collection and optional app.
+ * Admins of the collection see every change; everyone else sees changes to public things (public app
+ * records, products). Filter by `type` ('product' | 'proof' | 'asset' | 'record' | 'collection' |
+ * 'collection.apps' | 'settings'), `id`, `appId`, `recordType`, `productId`, `proofId`.
  *
- * Requires user authentication (Bearer token).
- *
- * @param params - Token request parameters
- * @param params.collectionId - The collection scope (required)
- * @param params.appId - Optional app scope for more specific permissions
- * @returns Ably TokenRequest that can be used with Ably.Realtime client
- *
- * @example
  * ```ts
- * const tokenRequest = await realtime.getPublicToken({
- *   collectionId: 'my-collection-id',
- *   appId: 'my-app-id'
- * })
- *
- * // Use with Ably
- * const ably = new Ably.Realtime.Promise({
- *   authCallback: async (data, callback) => {
- *     callback(null, tokenRequest)
- *   }
- * })
- *
- * // Subscribe to channels matching the pattern
- * const channel = ably.channels.get('collection:my-collection-id:app:my-app-id:chat:general')
- * await channel.subscribe('message', (msg) => console.log(msg.data))
+ * const off = realtime.onChange({ collectionId }, { type: "record", appId, recordType: "entry" }, () => refetch())
  * ```
  */
+export declare function onChange(scope: RealtimeScope, filter: RealtimeChangeFilter, onChangeFn: (change: RealtimeChangeEvent) => void): () => void;
+/**
+ * Messages for the signed-in person only (e.g. "scan" — a tag they just scanned on another device).
+ */
+export declare function onMine(scope: RealtimeScope, onMessage: (msg: RealtimeMessage) => void): () => void;
+/**
+ * @deprecated Use `realtime.channel()` / `realtime.onChange()`. Returns a raw Ably TokenRequest for
+ * `collection:{collectionId}:*` (subscribe; publish only for the collection's admins).
+ */
 export declare function getPublicToken(params: RealtimeTokenRequest): Promise<AblyTokenRequest>;
 /**
- * Get an Ably token for admin real-time communication.
- *
- * This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client
- * with admin permissions to receive system notifications and alerts.
- *
- * Admin users get subscribe-only (read-only) access to the interaction:{userId} channel pattern.
- *
- * Requires admin authentication (Bearer token).
- *
- * @returns Ably TokenRequest that can be used with Ably.Realtime client
- *
- * @example
- * ```ts
- * const tokenRequest = await realtime.getAdminToken()
- *
- * // Use with Ably
- * const ably = new Ably.Realtime.Promise({
- *   authCallback: async (data, callback) => {
- *     callback(null, tokenRequest)
- *   }
- * })
- *
- * // Subscribe to admin interaction channel
- * const userId = 'my-user-id'
- * const channel = ably.channels.get(`interaction:${userId}`)
- * await channel.subscribe((message) => {
- *   console.log('Admin notification:', message.data)
- * })
- * ```
+ * @deprecated Use `realtime.onMine()`. Returns a raw Ably TokenRequest for `interaction:{userId}`
+ * (subscribe only).
  */
 export declare function getAdminToken(): Promise<AblyTokenRequest>;

package/dist/api/realtime.js

@@ -1,113 +1,259 @@
 // src/api/realtime.ts
-import { request } from "../http.js";
+import { request, post } from "../http.js";
+/** One live stream per (collection, app): every listener on this page shares it. */
+class Stream {
+    constructor(collectionId, appId, onEmpty) {
+        this.collectionId = collectionId;
+        this.appId = appId;
+        this.onEmpty = onEmpty;
+        this.listeners = new Map(); // logical name ("draw", "feed:admin") → listeners
+        this.physical = new Map(); // physical channel → logical name
+        this.granted = new Set();
+        this.source = null;
+        this.lastEvent = null;
+        this.refreshTimer = null;
+        this.retryTimer = null;
+        this.pending = null;
+        this.retries = 0;
+        this.closed = false;
+    }
+    add(name, listener) {
+        let set = this.listeners.get(name);
+        const isNew = !set;
+        if (!set)
+            this.listeners.set(name, (set = new Set()));
+        set.add(listener);
+        if (isNew || !this.source)
+            this.schedule();
+        return () => {
+            const s = this.listeners.get(name);
+            if (!s)
+                return;
+            s.delete(listener);
+            if (!s.size)
+                this.listeners.delete(name);
+            if (!this.listeners.size)
+                this.close();
+        };
+    }
+    /** What was granted (empty until connected). */
+    has(name) {
+        return this.granted.has(name);
+    }
+    schedule(delay = 30) {
+        if (this.pending)
+            clearTimeout(this.pending);
+        this.pending = setTimeout(() => {
+            this.pending = null;
+            void this.open();
+        }, delay);
+    }
+    async open() {
+        var _a;
+        if (this.closed || typeof EventSource === "undefined")
+            return;
+        const names = [...this.listeners.keys()];
+        const feeds = names.filter((n) => n.startsWith("feed:")).map((n) => n.slice(5));
+        const channels = names.filter((n) => !n.startsWith("feed:"));
+        let reply;
+        try {
+            reply = await post("/public/realtime/connect", Object.assign(Object.assign({ collectionId: this.collectionId }, (this.appId ? { appId: this.appId } : {})), { feeds,
+                channels }));
+        }
+        catch (err) {
+            return this.retryLater(err);
+        }
+        if (this.closed)
+            return;
+        (_a = this.source) === null || _a === void 0 ? void 0 : _a.close();
+        this.source = null;
+        this.physical.clear();
+        this.granted = new Set(reply.channels.map((c) => c.name));
+        for (const c of reply.channels)
+            this.physical.set(c.channel, c.name);
+        if (reply.transport !== "sse" || !reply.url)
+            return; // nothing this viewer may see
+        const url = this.lastEvent ? `${reply.url}&lastEvent=${encodeURIComponent(this.lastEvent)}` : reply.url;
+        const source = new EventSource(url);
+        this.source = source;
+        source.addEventListener("message", (e) => this.deliver(e));
+        source.addEventListener("error", (e) => {
+            const data = e.data;
+            // A stream error with a body (e.g. the token expired): get a fresh token and resume.
+            if (data || source.readyState === EventSource.CLOSED)
+                this.retryLater(data);
+        });
+        source.addEventListener("open", () => {
+            this.retries = 0;
+        });
+        // Renew a minute before the token expires (the stream can't renew its own token).
+        if (this.refreshTimer)
+            clearTimeout(this.refreshTimer);
+        if (reply.expiresAt) {
+            const ms = Math.max(10000, reply.expiresAt - Date.now() - 60000);
+            this.refreshTimer = setTimeout(() => this.schedule(0), ms);
+        }
+    }
+    retryLater(_why) {
+        var _a;
+        if (this.closed)
+            return;
+        (_a = this.source) === null || _a === void 0 ? void 0 : _a.close();
+        this.source = null;
+        if (this.retryTimer)
+            clearTimeout(this.retryTimer);
+        const ms = Math.min(30000, 1000 * 2 ** this.retries++);
+        this.retryTimer = setTimeout(() => this.schedule(0), ms);
+    }
+    deliver(e) {
+        var _a, _b;
+        if (e.lastEventId)
+            this.lastEvent = e.lastEventId;
+        let env;
+        try {
+            env = JSON.parse(String(e.data));
+        }
+        catch (_c) {
+            return;
+        }
+        const name = env.channel ? this.physical.get(env.channel) : undefined;
+        if (!name)
+            return;
+        let data = env.data;
+        if (typeof data === "string" && env.encoding && /json/.test(env.encoding)) {
+            try {
+                data = JSON.parse(data);
+            }
+            catch (_d) {
+                /* leave as the string */
+            }
+        }
+        const msg = { channel: name, event: (_a = env.name) !== null && _a !== void 0 ? _a : "", data, at: env.timestamp };
+        for (const l of [...((_b = this.listeners.get(name)) !== null && _b !== void 0 ? _b : [])]) {
+            try {
+                l(msg);
+            }
+            catch (err) {
+                console.error("[SmartLinks realtime] a listener threw", err);
+            }
+        }
+    }
+    close() {
+        var _a;
+        this.closed = true;
+        for (const t of [this.pending, this.refreshTimer, this.retryTimer])
+            if (t)
+                clearTimeout(t);
+        (_a = this.source) === null || _a === void 0 ? void 0 : _a.close();
+        this.source = null;
+        this.onEmpty();
+    }
+}
+const streams = new Map();
+function streamFor(scope) {
+    var _a, _b;
+    if (!(scope === null || scope === void 0 ? void 0 : scope.collectionId))
+        throw new Error("realtime: collectionId is required");
+    const key = `${scope.collectionId}|${(_a = scope.appId) !== null && _a !== void 0 ? _a : ""}`;
+    let s = streams.get(key);
+    if (!s) {
+        s = new Stream(scope.collectionId, (_b = scope.appId) !== null && _b !== void 0 ? _b : null, () => streams.delete(key));
+        streams.set(key, s);
+    }
+    return s;
+}
 /**
- * Real-Time Communications API
- *
- * Provides access to real-time communication channels using Ably.
- * Supports both public (user-scoped) and admin tokens for different permission levels.
- *
- * Channel Patterns:
- * - With appId: collection:{collectionId}:app:{appId}:*
- * - Without appId: collection:{collectionId}:*
+ * One of your app's declared channels (manifest `realtime.channels`).
  *
- * @example
  * ```ts
- * import { realtime } from '@proveanything/smartlinks'
- *
- * // Get token for public user
- * const tokenRequest = await realtime.getPublicToken({
- *   collectionId: 'abc123',
- *   appId: 'xyz789'
- * })
- *
- * // Initialize Ably client
- * const ably = new Ably.Realtime.Promise({
- *   authCallback: async (data, callback) => {
- *     callback(null, tokenRequest)
- *   }
- * })
- *
- * // Subscribe to a channel
- * const channel = ably.channels.get('collection:abc123:app:xyz789:chat:room-1')
- * await channel.subscribe((message) => {
- *   console.log('Received:', message.data)
- * })
- *
- * // Publish a message
- * await channel.publish('message', { text: 'Hello!', userId: '123' })
+ * const draw = realtime.channel({ collectionId, appId }, "draw")
+ * const off = draw.subscribe("status", (m) => setStatus(m.data))
+ * await draw.publish("status", { phase: "spinning" }) // if the channel lets this viewer publish
  * ```
  */
+export function channel(scope, name) {
+    return {
+        /** Listen for an event (or "*" for every event). Returns a function that stops listening. */
+        subscribe(event, onMessage) {
+            return streamFor(scope).add(name, (m) => {
+                if (event === "*" || m.event === event)
+                    onMessage(m);
+            });
+        },
+        /** Send a message. Refused (403) unless the channel's `publish` rule allows this viewer. */
+        publish(event, data) {
+            return post("/public/realtime/publish", {
+                collectionId: scope.collectionId,
+                appId: scope.appId,
+                channel: name,
+                event,
+                data: data === undefined ? null : data,
+            });
+        },
+    };
+}
+function matches(change, filter) {
+    for (const k of ["type", "id", "appId", "recordType", "productId", "proofId"]) {
+        if (filter[k] !== undefined && change[k] !== filter[k])
+            return false;
+    }
+    return true;
+}
 /**
- * Get an Ably token for public (user-scoped) real-time communication.
+ * Something changed: refetch it. IDs only — never data.
  *
- * This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client
- * with appropriate permissions for the specified collection and optional app.
+ * Admins of the collection see every change; everyone else sees changes to public things (public app
+ * records, products). Filter by `type` ('product' | 'proof' | 'asset' | 'record' | 'collection' |
+ * 'collection.apps' | 'settings'), `id`, `appId`, `recordType`, `productId`, `proofId`.
  *
- * Requires user authentication (Bearer token).
- *
- * @param params - Token request parameters
- * @param params.collectionId - The collection scope (required)
- * @param params.appId - Optional app scope for more specific permissions
- * @returns Ably TokenRequest that can be used with Ably.Realtime client
- *
- * @example
  * ```ts
- * const tokenRequest = await realtime.getPublicToken({
- *   collectionId: 'my-collection-id',
- *   appId: 'my-app-id'
- * })
- *
- * // Use with Ably
- * const ably = new Ably.Realtime.Promise({
- *   authCallback: async (data, callback) => {
- *     callback(null, tokenRequest)
- *   }
- * })
- *
- * // Subscribe to channels matching the pattern
- * const channel = ably.channels.get('collection:my-collection-id:app:my-app-id:chat:general')
- * await channel.subscribe('message', (msg) => console.log(msg.data))
+ * const off = realtime.onChange({ collectionId }, { type: "record", appId, recordType: "entry" }, () => refetch())
  * ```
  */
+export function onChange(scope, filter, onChangeFn) {
+    const s = streamFor({ collectionId: scope.collectionId });
+    // Ask for both feeds; an admin is granted both (public changes reach the admin feed too), so the
+    // public feed is ignored once the admin feed is granted — no change arrives twice.
+    const handle = (fromAdminFeed) => (m) => {
+        if (m.event !== "change" || !m.data || typeof m.data !== "object")
+            return;
+        if (!fromAdminFeed && s.has("feed:admin"))
+            return;
+        const change = m.data;
+        if (matches(change, filter))
+            onChangeFn(change);
+    };
+    const offAdmin = s.add("feed:admin", handle(true));
+    const offPublic = s.add("feed:public", handle(false));
+    return () => {
+        offAdmin();
+        offPublic();
+    };
+}
+/**
+ * Messages for the signed-in person only (e.g. "scan" — a tag they just scanned on another device).
+ */
+export function onMine(scope, onMessage) {
+    return streamFor({ collectionId: scope.collectionId }).add("feed:me", onMessage);
+}
+// ---------------------------------------------------------------------------------------------------
+// Legacy (raw Ably tokens). New code uses channel / onChange above — no provider in your app.
+// ---------------------------------------------------------------------------------------------------
+/**
+ * @deprecated Use `realtime.channel()` / `realtime.onChange()`. Returns a raw Ably TokenRequest for
+ * `collection:{collectionId}:*` (subscribe; publish only for the collection's admins).
+ */
 export async function getPublicToken(params) {
     const queryParams = new URLSearchParams();
-    queryParams.append('collectionId', params.collectionId);
-    if (params.appId) {
-        queryParams.append('appId', params.appId);
-    }
+    queryParams.append("collectionId", params.collectionId);
+    if (params.appId)
+        queryParams.append("appId", params.appId);
     return request(`/public/push/token?${queryParams.toString()}`);
 }
 /**
- * Get an Ably token for admin real-time communication.
- *
- * This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client
- * with admin permissions to receive system notifications and alerts.
- *
- * Admin users get subscribe-only (read-only) access to the interaction:{userId} channel pattern.
- *
- * Requires admin authentication (Bearer token).
- *
- * @returns Ably TokenRequest that can be used with Ably.Realtime client
- *
- * @example
- * ```ts
- * const tokenRequest = await realtime.getAdminToken()
- *
- * // Use with Ably
- * const ably = new Ably.Realtime.Promise({
- *   authCallback: async (data, callback) => {
- *     callback(null, tokenRequest)
- *   }
- * })
- *
- * // Subscribe to admin interaction channel
- * const userId = 'my-user-id'
- * const channel = ably.channels.get(`interaction:${userId}`)
- * await channel.subscribe((message) => {
- *   console.log('Admin notification:', message.data)
- * })
- * ```
+ * @deprecated Use `realtime.onMine()`. Returns a raw Ably TokenRequest for `interaction:{userId}`
+ * (subscribe only).
  */
 export async function getAdminToken() {
-    return request('/admin/auth/push');
+    return request("/admin/auth/push");
 }

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.55  |  Generated: 2026-10-12T20:04:55.294Z
+Version: 2.0.56  |  Generated: 2026-10-12T20:58:59.335Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2850,6 +2850,7 @@ interface AppManifest {
   publicViews?: PublicView[];
   executor?: AppManifestExecutor;
   functions?: AppManifestFunctions;
+  realtime?: { channels: RealtimeChannelDeclaration[] };
   data?: AppDataDeclaration;
   headless?: AppHeadlessDeclaration;
   [key: string]: any;
@@ -9141,6 +9142,59 @@ interface AblyTokenRequest {
 }
 ```
 
+**RealtimeScope** (interface)
+```typescript
+interface RealtimeScope {
+  collectionId: string
+  appId?: string
+}
+```
+
+**RealtimeMessage** (interface)
+```typescript
+interface RealtimeMessage {
+  channel: string
+  event: string
+  data: unknown
+  at?: number
+}
+```
+
+**RealtimeChangeEvent** (interface)
+```typescript
+interface RealtimeChangeEvent {
+  type: string
+  id?: string
+  appId?: string
+  recordType?: string
+  productId?: string
+  proofId?: string
+  status?: string
+  at: number
+}
+```
+
+**RealtimeChangeFilter** (interface)
+```typescript
+interface RealtimeChangeFilter {
+  type?: string
+  id?: string
+  appId?: string
+  recordType?: string
+  productId?: string
+  proofId?: string
+}
+```
+
+**RealtimeChannelDeclaration** (interface)
+```typescript
+interface RealtimeChannelDeclaration {
+  name: string
+  subscribe?: "public" | "signedIn" | "admin"
+  publish?: "public" | "signedIn" | "admin" | "server"
+}
+```
+
 **RealtimeChannelPattern** = `string`
 
 ### research
@@ -12168,11 +12222,20 @@ Reset rate limit for a user
 
 ### realtime
 
+**channel**(scope: RealtimeScope & { appId: string }, name: string) → `void`
+One of your app's declared channels (manifest `realtime.channels`). ```ts const draw = realtime.channel({ collectionId, appId }, "draw") const off = draw.subscribe("status", (m) => setStatus(m.data)) await draw.publish("status", { phase: "spinning" }) // if the channel lets this viewer publish ```
+
+**onChange**(scope: RealtimeScope, filter: RealtimeChangeFilter, onChangeFn: (change: RealtimeChangeEvent) → `void`
+Something changed: refetch it. IDs only — never data. Admins of the collection see every change; everyone else sees changes to public things (public app records, products). Filter by `type` ('product' | 'proof' | 'asset' | 'record' | 'collection' | 'collection.apps' | 'settings'), `id`, `appId`, `recordType`, `productId`, `proofId`. ```ts const off = realtime.onChange({ collectionId }, { type: "record", appId, recordType: "entry" }, () => refetch()) ```
+
+**onMine**(scope: RealtimeScope, onMessage: (msg: RealtimeMessage) → `void`
+Messages for the signed-in person only (e.g. "scan" — a tag they just scanned on another device).
+
 **getPublicToken**(params: RealtimeTokenRequest) → `Promise<AblyTokenRequest>`
-Get an Ably token for public (user-scoped) real-time communication. This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client with appropriate permissions for the specified collection and optional app. Requires user authentication (Bearer token). ```ts const tokenRequest = await realtime.getPublicToken({ collectionId: 'my-collection-id', appId: 'my-app-id' }) // Use with Ably const ably = new Ably.Realtime.Promise({ authCallback: async (data, callback) => { callback(null, tokenRequest) } }) // Subscribe to channels matching the pattern const channel = ably.channels.get('collection:my-collection-id:app:my-app-id:chat:general') await channel.subscribe('message', (msg) => console.log(msg.data)) ```
+`collection:{collectionId}:*` (subscribe; publish only for the collection's admins).
 
 **getAdminToken**() → `Promise<AblyTokenRequest>`
-Get an Ably token for admin real-time communication. This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client with admin permissions to receive system notifications and alerts. Admin users get subscribe-only (read-only) access to the interaction:{userId} channel pattern. Requires admin authentication (Bearer token). ```ts const tokenRequest = await realtime.getAdminToken() // Use with Ably const ably = new Ably.Realtime.Promise({ authCallback: async (data, callback) => { callback(null, tokenRequest) } }) // Subscribe to admin interaction channel const userId = 'my-user-id' const channel = ably.channels.get(`interaction:${userId}`) await channel.subscribe((message) => { console.log('Admin notification:', message.data) }) ```
+(subscribe only).
 
 ### research
 

package/dist/docs/overview.md

@@ -69,7 +69,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Portal Request Action** | `docs/portal-request-action.md` | Triggering portal built-in actions (__qrScanner, __share, __logout, etc.) from sub-apps |
 | **Interactions** | `docs/interactions.md` | Business events, outcomes, voting, competitions, and journey triggers |
 | **App Config Files** | `docs/app-manifest.md` | Full field-by-field reference for both JSON config files |
-| **Real-time Messaging** | `docs/realtime.md` | Adding Ably real-time features (chat, live updates) |
+| **Realtime** | `docs/realtime.md` | Live updates: change events (refetch when something changes) and declared app channels (a draw, a status) — no provider library or keys |
 | **Liquid Templates** | `docs/liquid-templates.md` | Dynamic content rendering with LiquidJS |
 | **Iframe Responder** | `docs/iframe-responder.md` | Iframe communication and proxy mode internals |
 | **AI Guide Template** | `docs/ai-guide-template.md` | Template for creating `public/ai-guide.md` — customise per app |
@@ -358,7 +358,7 @@ The SmartLinks SDK is organised into namespaces. See `docs/API_SUMMARY.md` for t
 - `contact` — Customer contact management
 - `comms` / `broadcasts` — Notifications and campaigns
 - `asset` — File/image uploads
-- `realtime` — Ably real-time messaging (see `docs/realtime.md`)
+- `realtime` — SmartLinks Realtime: `onChange`, `channel`, `onMine` (see `docs/realtime.md`)
 
 ---