@proveanything/smartlinks 2.0.55 → 2.0.56

package/dist/http.js

@@ -210,6 +210,9 @@ function shouldSkipCache(path) {
     // Never cache auth, account, or user-identity endpoints — they depend on session state.
     if (/\/(auth|account)\//i.test(path))
         return true;
+    // Realtime tokens are single-use (a reused one is rejected by the provider) — never cache them.
+    if (/\/(push\/token|realtime\/)/i.test(path))
+        return true;
     // Never cache /me endpoints (contact/me, loyalty/me, etc.) — always user-specific.
     if (/\/me(\?|$)/i.test(path))
         return true;

package/dist/openapi.yaml

@@ -123,7 +123,7 @@ paths:
     get:
       tags:
         - realtime
-      summary: Get an Ably token for admin real-time communication.
+      summary: (subscribe only).
       operationId: realtime_getAdminToken
       security:
         - bearerAuth: []
@@ -13960,7 +13960,7 @@ paths:
     get:
       tags:
         - realtime
-      summary: realtime.getPublicToken
+      summary: "`collection:{collectionId}:*` (subscribe; publish only for the collection's admins)."
       operationId: realtime_getPublicToken
       security: []
       parameters:
@@ -14018,6 +14018,33 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /public/realtime/publish:
+    post:
+      tags:
+        - realtime
+      summary: "One of your app's declared channels (manifest `realtime.channels`)."
+      operationId: realtime_channel
+      security: []
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RealtimeScope"
   /public/tags/{tagId}:
     get:
       tags:
@@ -19618,6 +19645,9 @@ components:
           $ref: "#/components/schemas/AppManifestExecutor"
         functions:
           $ref: "#/components/schemas/AppManifestFunctions"
+        realtime:
+          type: object
+          additionalProperties: true
         data:
           $ref: "#/components/schemas/AppDataDeclaration"
         headless:
@@ -29830,6 +29860,79 @@ components:
         - nonce
         - mac
         - clientId
+    RealtimeScope:
+      type: object
+      properties:
+        collectionId:
+          type: string
+        appId:
+          type: string
+      required:
+        - collectionId
+    RealtimeMessage:
+      type: object
+      properties:
+        channel:
+          type: string
+        event:
+          type: string
+        data: {}
+        at:
+          type: number
+      required:
+        - channel
+        - event
+        - data
+    RealtimeChangeEvent:
+      type: object
+      properties:
+        type:
+          type: string
+        id:
+          type: string
+        appId:
+          type: string
+        recordType:
+          type: string
+        productId:
+          type: string
+        proofId:
+          type: string
+        status:
+          type: string
+        at:
+          type: number
+      required:
+        - type
+        - at
+    RealtimeChangeFilter:
+      type: object
+      properties:
+        type:
+          type: string
+        id:
+          type: string
+        appId:
+          type: string
+        recordType:
+          type: string
+        productId:
+          type: string
+        proofId:
+          type: string
+    RealtimeChannelDeclaration:
+      type: object
+      properties:
+        name:
+          type: string
+        subscribe:
+          type: object
+          additionalProperties: true
+        publish:
+          type: object
+          additionalProperties: true
+      required:
+        - name
     RealtimeChannelPattern:
       type: string
     ResearchFetchRequest:

package/dist/types/appManifest.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="node" />
 /// <reference types="node" />
 import type { AppDataDeclaration, AppHeadlessDeclaration } from './headless.js';
+import type { RealtimeChannelDeclaration } from './realtime.js';
 /**
  * A bundle (widget or container) as returned by the collection widgets endpoint.
  *
@@ -806,6 +807,16 @@ export interface AppManifest {
      * @see AppManifestFunctions
      */
     functions?: AppManifestFunctions;
+    /**
+     * SmartLinks Realtime: the live channels this app uses, with who may listen and who may send
+     * (docs/realtime.md). Only declared channels exist — anything else is refused.
+     * ```json
+     * "realtime": { "channels": [ { "name": "draw", "subscribe": "public", "publish": "admin" } ] }
+     * ```
+     */
+    realtime?: {
+        channels: RealtimeChannelDeclaration[];
+    };
     /**
      * The app's public data model: its data types, how each is stored, fields, examples and read
      * recipes. Required for `headless`. @see AppDataDeclaration · docs/headless-providers.md

package/dist/types/realtime.d.ts

@@ -42,3 +42,47 @@ export interface AblyTokenRequest {
  *   - collection:abc:users:active
  */
 export type RealtimeChannelPattern = string;
+/** Where a realtime listener lives: the collection, and (for app channels) the app. */
+export interface RealtimeScope {
+    collectionId: string;
+    appId?: string;
+}
+/** A message on a channel. `channel` is the logical name ("draw", "feed:admin"). */
+export interface RealtimeMessage {
+    channel: string;
+    event: string;
+    data: unknown;
+    /** When it was sent (ms since epoch), when known. */
+    at?: number;
+}
+/** "This changed" — ids only; refetch through the normal API. */
+export interface RealtimeChangeEvent {
+    /** 'product' | 'proof' | 'asset' | 'record' | 'collection' | 'collection.apps' | 'settings' | … */
+    type: string;
+    id?: string;
+    appId?: string;
+    recordType?: string;
+    productId?: string;
+    proofId?: string;
+    /** 'created' | 'updated' | 'deleted' (records) or 'create' | 'update' | 'delete' (products, proofs…) */
+    status?: string;
+    at: number;
+}
+/** Which changes to hear about — every field given must match. */
+export interface RealtimeChangeFilter {
+    type?: string;
+    id?: string;
+    appId?: string;
+    recordType?: string;
+    productId?: string;
+    proofId?: string;
+}
+/** A channel an app declares in its manifest (`realtime.channels`). */
+export interface RealtimeChannelDeclaration {
+    /** Lowercase letters, numbers, - and _; up to 40 characters. */
+    name: string;
+    /** Who may listen. Default 'admin'. */
+    subscribe?: "public" | "signedIn" | "admin";
+    /** Who may send: those levels, or 'server' (only the app's server functions). Default 'server'. */
+    publish?: "public" | "signedIn" | "admin" | "server";
+}

package/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/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`)
 
 ---