@proveanything/smartlinks 2.0.54 → 2.0.56

package/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:
@@ -30958,28 +31061,3 @@ components:
       properties:
         appId:
           type: string
-    AllocateSequenceInput:
-      type: object
-      properties:
-        appId:
-          type: string
-        sequenceId:
-          type: string
-        subjectId:
-          type: string
-        productId:
-          type: string
-      required:
-        - appId
-        - sequenceId
-        - subjectId
-    AllocatedSequence:
-      type: object
-      properties:
-        number:
-          type: number
-        isNew:
-          type: boolean
-      required:
-        - number
-        - isNew

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.54",
+  "version": "2.0.56",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",

package/scripts/doctor.mjs

@@ -313,6 +313,31 @@ if (meta.respectsHostTheme) {
   if (embeds && !handRolled.length && !blocked.size) console.log(`${GREEN}✓${RESET} embedded widgets ${DIM}— ${embeds} via the host's EmbeddedWidget${RESET}`);
 }
 
+// ---- realtime: SL.realtime, never a provider library or key in the app ---------------------------
+// SmartLinks Realtime (docs/realtime.md) hands out the stream and checks every publish; an app that talks
+// to the provider directly bypasses the channel rules (and a provider key in a bundle is a key for all).
+{
+  const EXT = /\.(tsx|ts|jsx|js)$/;
+  const SKIP = new Set(['node_modules', 'dist', '.git', 'public']);
+  const hitsRt = [];
+  (function walkRt(dir) {
+    let entries = [];
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isDirectory()) { if (!SKIP.has(e.name)) walkRt(join(dir, e.name)); }
+      else if (EXT.test(e.name)) {
+        const f = join(dir, e.name);
+        const text = readFileSync(f, 'utf8');
+        if (/from\s+['"]ably(\/[^'"]*)?['"]|require\(\s*['"]ably['"]\s*\)|ABLY_(API_)?KEY/.test(text)) hitsRt.push(f.startsWith(appDir) ? f.slice(appDir.length + 1) : f);
+      }
+    }
+  })(existsSync(join(appDir, 'src')) ? join(appDir, 'src') : appDir);
+  if (hitsRt.length) {
+    console.log(`${YELLOW}⚠${RESET} realtime — talks to the realtime provider directly in ${hitsRt.slice(0, 3).join(', ')}`);
+    warnings.push(`${hitsRt.join(', ')} use${hitsRt.length === 1 ? 's' : ''} the realtime provider (Ably) directly. Use SL.realtime instead — declare channels in the manifest (realtime.channels) and use realtime.channel() / onChange() (docs/realtime.md); never put a provider key in an app.`);
+  }
+}
+
 // ---- package.json scripts point at files that exist ------------------------------------------
 // An upgrade that copies a script LINE but not the script FILE breaks every build at that step
 // (e.g. `postbuild: node scripts/smartlinks-deploy.mjs` with no scripts/smartlinks-deploy.mjs).

package/dist/api/sequence.d.ts

@@ -1,38 +0,0 @@
-export interface AllocateSequenceInput {
-    /** The app that owns the sequence config. */
-    appId: string;
-    /** The configured sequence id — the key of data.sequenceConfigs on the app config. */
-    sequenceId: string;
-    /**
-     * The STABLE subject identity. For a `claimSet` sequence, pass the tap's virtual-proof id
-     * `<claimSetId>-<code>` (e.g. "23-oOkf8o") for a per-wristband raffle — the code is the tag's
-     * permanent id, so re-taps of the same wristband return the same number; the number is stamped
-     * on that code's doc and surfaces in `tagData`. Pass a bare claim-set id for one number per
-     * group. Never a value that changes per tap.
-     */
-    subjectId: string;
-    /** Optional product scope, when the sequence config is scoped per product. */
-    productId?: string;
-}
-export interface AllocatedSequence {
-    /** The allocated (or already-held) number. */
-    number: number;
-    /** True when this call allocated a new number; false when the subject already had one. */
-    isNew: boolean;
-}
-export declare namespace sequence {
-    /**
-     * Allocate (or return the existing) sequence number for a subject. Idempotent — safe to
-     * call on load (auto-enter) and on a button tap; a subject that already has a number gets
-     * it back with `isNew: false`.
-     *
-     * @example
-     *   const { number, isNew } = await sequence.allocate(collectionId, {
-     *     appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId,
-     *   })
-      *
-     * @deprecated Being removed. Number things in your app's own server function with
-     * `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
-     */
-    function allocate(collectionId: string, input: AllocateSequenceInput): Promise<AllocatedSequence>;
-}

package/dist/api/sequence.js

@@ -1,29 +0,0 @@
-// src/api/sequence.ts
-//
-// Sequences — allocate a guaranteed-unique, monotonic number (raffle tickets, "Nth to
-// claim", queue positions) and stamp it onto a record. The sequence (counter key, target,
-// field, scope) is configured server-side in app config (data.sequenceConfigs[sequenceId]);
-// this call supplies only the subject and is idempotent — a re-tap returns the same number.
-// See docs/sequences.md.
-import { post } from "../http.js";
-export var sequence;
-(function (sequence) {
-    const base = (collectionId) => `/public/collection/${encodeURIComponent(collectionId)}/sequence`;
-    /**
-     * Allocate (or return the existing) sequence number for a subject. Idempotent — safe to
-     * call on load (auto-enter) and on a button tap; a subject that already has a number gets
-     * it back with `isNew: false`.
-     *
-     * @example
-     *   const { number, isNew } = await sequence.allocate(collectionId, {
-     *     appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId,
-     *   })
-      *
-     * @deprecated Being removed. Number things in your app's own server function with
-     * `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
-     */
-    async function allocate(collectionId, input) {
-        return post(`${base(collectionId)}/allocate`, input);
-    }
-    sequence.allocate = allocate;
-})(sequence || (sequence = {}));

package/dist/docs/sequences.md

@@ -1,125 +0,0 @@
-# Sequences & claim-order allocation
-
-> **Retiring — don't build on this.** `SL.sequence.allocate` is being removed. Number things in your
-> app's own server function instead: `ctx.sl.counters.next()` for the next number and
-> `ctx.sl.appRecords.claim()` to key it to a tag/person and make sure no number is ever held twice —
-> see server-functions.md → "Uniqueness, numbering and people". (The counter here lived inside the
-> app config doc, where an admin save could rewind it.)
-
-> **SmartLinks SDK 2.x** (current `latest`). Install `@proveanything/smartlinks@^2`.
-
-A **sequence** hands out a guaranteed-unique, monotonic number — `1, 2, 3, …` — and stamps it
-onto a record. It's the primitive behind raffle tickets, "you're the Nth to claim", queue
-positions, and limited-edition numbering: cases where you need *the next number*, exactly
-once per subject, even with a whole room (or stadium) acting at the same instant.
-
-## The model: allocate, then stamp — and the target is the ledger
-
-Two steps, one call:
-
-1. **Allocate** — get the next number from an **atomic counter**. The counter lives inside
-   your **app-config** doc at `data.sequences.<key>`, so it's scoped exactly like your other
-   app config (per collection / product / variant / batch) and needs no dedicated storage.
-   It's incremented in a single statement, so 250 simultaneous taps each get a distinct
-   number in microseconds — never two the same.
-2. **Stamp** — write that number onto the **subject's own record** (a claim set, a proof, or
-   an app record). **That record is the ledger** — there's no separate bookkeeping table.
-   Next time you read the subject, the number is just there.
-
-Because the target is the ledger, allocation is **idempotent**: on a re-tap we read the
-subject first and return the number it already has, rather than allocating a second one.
-
-## Guarantees
-
-- **Unique + monotonic** — the counter is an atomic increment, never a read-modify-write, so
-  there are no duplicates and no lost updates under load.
-- **Idempotent per subject** — one number per subject; a re-tap returns the same number.
-- **Concurrency-safe at scale** — the only shared hot spot is the one counter row (Postgres
-  serializes it); the stamp is per-subject (its own record), so the model holds from 250 in a
-  room to 60,000 in a stadium. A concurrent double-tap on the *same* subject at worst skips
-  one number (a harmless gap) — never puts two numbers on one person.
-
-## Scoping
-
-- **Counter scope** — the app-config doc it lives on: collection-wide, or per product /
-  variant / batch. All wristbands mapped to one product? Scope the counter to that product.
-- **`key`** — a name within that doc (e.g. `raffle:2026-cup`), so one config doc can hold
-  several independent sequences.
-- **`start`** — the first number (default `1`); use it to reserve a block (start at `51` and
-  tell people it's `1`, or just filter `< N` at draw time).
-
-## Idempotency subject — use a *stable* id
-
-The number is deduped by the **subject id** you pass, so it must be the **stable** identity:
-- **Virtual-proof id `<claimSetId>-<code>`** (e.g. `23-oOkf8o`) — the right key for a
-  per-wristband raffle. The `code` is the physical tag's permanent id, so a re-tap of the same
-  wristband resolves to the same code doc → same number. The virtual proof record is transient,
-  but the **code** inside its id is stable — that's what the sink keys on (it splits the id and
-  uses only `<claimSetId>` + `<code>`).
-- **Bare claim-set id** — when one number per *group* is intended.
-- The authenticated **user/contact** — if they sign in / claim.
-
-Do **not** key on the transient part of a per-tap identity (a freshly-minted virtual proof
-record) — key on the stable **code**, which is exactly what the `<claimSetId>-<code>` subject
-carries.
-
-## Where the number is stored (the sink)
-
-The stamp target is configurable — the number lives wherever you'll read it:
-
-| Target | Subject id | Use |
-|---|---|---|
-| `claimSet` | the virtual-proof id `<claimSetId>-<code>` (e.g. `23-oOkf8o`) **or** a bare `<claimSetId>` | The Firestore claim-set world. **The subject decides the exact doc:** a `<claimSetId>-<code>` id stamps the individual **code** doc (per-wristband — rides back as `tagData` on the next tap, every wristband its own number); a bare id stamps the whole **set** doc (one shared value). Claim-set ids are hyphen-free, so a hyphen unambiguously means the per-code form. |
-| `proof` | the proof id | A minted proof (value or attestation) — when the number should travel with the proof. |
-| `appRecord` | the record id | A structured app record — for queryable, per-app data. |
-
-## Configure the sequence (once, server-side)
-
-You define the sequence **in your app config**, under `data.sequenceConfigs`. This is what
-makes the public endpoint safe: the target/field/scope are set by you, not the caller.
-
-```jsonc
-// app config: data.sequenceConfigs
-{
-  "raffle": {
-    "key":     "raffle:2026-cup",   // the named counter (data.sequences.<key>)
-    "target":  "claimSet",          // claimSet | proof | appRecord — the ledger domain
-    "field":   "raffleNumber",      // the property written on the target (comes back in tagData)
-    "start":   1                    // first number (optional, default 1)
-    // no productId → one collection-wide counter (all wristbands share the sequence)
-  }
-}
-```
-
-> **Per-wristband raffle.** Keep `target: "claimSet"` and pass the tap's virtual-proof id
-> (`<claimSetId>-<code>`) as the subject — the sink writes the individual tag's **code** doc, so
-> each wristband gets its own number and it surfaces in `tagData` on the next tap. Pass a bare
-> claim-set id instead only if you want one number for the whole group.
-
-## Call it (the widget)
-
-Your widget calls one bounded, public endpoint on tap. It passes only the **subject id** —
-never the target/field:
-
-```
-POST /api/v1/public/collection/:collectionId/sequence/allocate
-{ "appId": "liveWidgets", "sequenceId": "raffle", "subjectId": "23-oOkf8o" }
-→ { "number": 42, "isNew": true }        // re-tap → { "number": 42, "isNew": false }
-```
-
-- **`subjectId`** is the STABLE identity. For `claimCode` it's the virtual-proof id
-  `<claimSetId>-<code>` (e.g. `23-oOkf8o`) straight off the tap — re-taps of the same wristband
-  collapse to one number. (For `claimSet` it's the claim-set id.)
-- **Idempotent**, so both your flows are the *same call*:
-  - **Auto:** on load, call allocate → get your number (existing or freshly minted).
-  - **Button:** click → animate → same call → "Your raffle number is 42."
-- **Refresh:** just read the `raffleNumber` field back off the claim set (or proof) — it's the
-  ledger. Or call allocate again; you'll get the same number with `isNew: false`.
-
-Errors: `404 SEQUENCE_NOT_FOUND` (not configured), `404 CLAIMSET_NOT_FOUND` (bad subject),
-`400 BAD_REQUEST` (missing fields).
-
-## Drawing the winner
-
-No separate ledger — query the claim sets (or proofs) where `raffleNumber` is set; that field
-is your entry list, in allocation order.

package/docs/sequences.md

@@ -1,125 +0,0 @@
-# Sequences & claim-order allocation
-
-> **Retiring — don't build on this.** `SL.sequence.allocate` is being removed. Number things in your
-> app's own server function instead: `ctx.sl.counters.next()` for the next number and
-> `ctx.sl.appRecords.claim()` to key it to a tag/person and make sure no number is ever held twice —
-> see server-functions.md → "Uniqueness, numbering and people". (The counter here lived inside the
-> app config doc, where an admin save could rewind it.)
-
-> **SmartLinks SDK 2.x** (current `latest`). Install `@proveanything/smartlinks@^2`.
-
-A **sequence** hands out a guaranteed-unique, monotonic number — `1, 2, 3, …` — and stamps it
-onto a record. It's the primitive behind raffle tickets, "you're the Nth to claim", queue
-positions, and limited-edition numbering: cases where you need *the next number*, exactly
-once per subject, even with a whole room (or stadium) acting at the same instant.
-
-## The model: allocate, then stamp — and the target is the ledger
-
-Two steps, one call:
-
-1. **Allocate** — get the next number from an **atomic counter**. The counter lives inside
-   your **app-config** doc at `data.sequences.<key>`, so it's scoped exactly like your other
-   app config (per collection / product / variant / batch) and needs no dedicated storage.
-   It's incremented in a single statement, so 250 simultaneous taps each get a distinct
-   number in microseconds — never two the same.
-2. **Stamp** — write that number onto the **subject's own record** (a claim set, a proof, or
-   an app record). **That record is the ledger** — there's no separate bookkeeping table.
-   Next time you read the subject, the number is just there.
-
-Because the target is the ledger, allocation is **idempotent**: on a re-tap we read the
-subject first and return the number it already has, rather than allocating a second one.
-
-## Guarantees
-
-- **Unique + monotonic** — the counter is an atomic increment, never a read-modify-write, so
-  there are no duplicates and no lost updates under load.
-- **Idempotent per subject** — one number per subject; a re-tap returns the same number.
-- **Concurrency-safe at scale** — the only shared hot spot is the one counter row (Postgres
-  serializes it); the stamp is per-subject (its own record), so the model holds from 250 in a
-  room to 60,000 in a stadium. A concurrent double-tap on the *same* subject at worst skips
-  one number (a harmless gap) — never puts two numbers on one person.
-
-## Scoping
-
-- **Counter scope** — the app-config doc it lives on: collection-wide, or per product /
-  variant / batch. All wristbands mapped to one product? Scope the counter to that product.
-- **`key`** — a name within that doc (e.g. `raffle:2026-cup`), so one config doc can hold
-  several independent sequences.
-- **`start`** — the first number (default `1`); use it to reserve a block (start at `51` and
-  tell people it's `1`, or just filter `< N` at draw time).
-
-## Idempotency subject — use a *stable* id
-
-The number is deduped by the **subject id** you pass, so it must be the **stable** identity:
-- **Virtual-proof id `<claimSetId>-<code>`** (e.g. `23-oOkf8o`) — the right key for a
-  per-wristband raffle. The `code` is the physical tag's permanent id, so a re-tap of the same
-  wristband resolves to the same code doc → same number. The virtual proof record is transient,
-  but the **code** inside its id is stable — that's what the sink keys on (it splits the id and
-  uses only `<claimSetId>` + `<code>`).
-- **Bare claim-set id** — when one number per *group* is intended.
-- The authenticated **user/contact** — if they sign in / claim.
-
-Do **not** key on the transient part of a per-tap identity (a freshly-minted virtual proof
-record) — key on the stable **code**, which is exactly what the `<claimSetId>-<code>` subject
-carries.
-
-## Where the number is stored (the sink)
-
-The stamp target is configurable — the number lives wherever you'll read it:
-
-| Target | Subject id | Use |
-|---|---|---|
-| `claimSet` | the virtual-proof id `<claimSetId>-<code>` (e.g. `23-oOkf8o`) **or** a bare `<claimSetId>` | The Firestore claim-set world. **The subject decides the exact doc:** a `<claimSetId>-<code>` id stamps the individual **code** doc (per-wristband — rides back as `tagData` on the next tap, every wristband its own number); a bare id stamps the whole **set** doc (one shared value). Claim-set ids are hyphen-free, so a hyphen unambiguously means the per-code form. |
-| `proof` | the proof id | A minted proof (value or attestation) — when the number should travel with the proof. |
-| `appRecord` | the record id | A structured app record — for queryable, per-app data. |
-
-## Configure the sequence (once, server-side)
-
-You define the sequence **in your app config**, under `data.sequenceConfigs`. This is what
-makes the public endpoint safe: the target/field/scope are set by you, not the caller.
-
-```jsonc
-// app config: data.sequenceConfigs
-{
-  "raffle": {
-    "key":     "raffle:2026-cup",   // the named counter (data.sequences.<key>)
-    "target":  "claimSet",          // claimSet | proof | appRecord — the ledger domain
-    "field":   "raffleNumber",      // the property written on the target (comes back in tagData)
-    "start":   1                    // first number (optional, default 1)
-    // no productId → one collection-wide counter (all wristbands share the sequence)
-  }
-}
-```
-
-> **Per-wristband raffle.** Keep `target: "claimSet"` and pass the tap's virtual-proof id
-> (`<claimSetId>-<code>`) as the subject — the sink writes the individual tag's **code** doc, so
-> each wristband gets its own number and it surfaces in `tagData` on the next tap. Pass a bare
-> claim-set id instead only if you want one number for the whole group.
-
-## Call it (the widget)
-
-Your widget calls one bounded, public endpoint on tap. It passes only the **subject id** —
-never the target/field:
-
-```
-POST /api/v1/public/collection/:collectionId/sequence/allocate
-{ "appId": "liveWidgets", "sequenceId": "raffle", "subjectId": "23-oOkf8o" }
-→ { "number": 42, "isNew": true }        // re-tap → { "number": 42, "isNew": false }
-```
-
-- **`subjectId`** is the STABLE identity. For `claimCode` it's the virtual-proof id
-  `<claimSetId>-<code>` (e.g. `23-oOkf8o`) straight off the tap — re-taps of the same wristband
-  collapse to one number. (For `claimSet` it's the claim-set id.)
-- **Idempotent**, so both your flows are the *same call*:
-  - **Auto:** on load, call allocate → get your number (existing or freshly minted).
-  - **Button:** click → animate → same call → "Your raffle number is 42."
-- **Refresh:** just read the `raffleNumber` field back off the claim set (or proof) — it's the
-  ledger. Or call allocate again; you'll get the same number with `isNew: false`.
-
-Errors: `404 SEQUENCE_NOT_FOUND` (not configured), `404 CLAIMSET_NOT_FOUND` (bad subject),
-`400 BAD_REQUEST` (missing fields).
-
-## Drawing the winner
-
-No separate ledger — query the claim sets (or proofs) where `raffleNumber` is set; that field
-is your entry list, in allocation order.