@proveanything/smartlinks 2.0.50 → 2.0.52

package/dist/api/sequence.d.ts

@@ -30,6 +30,9 @@ export declare namespace sequence {
      *   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

@@ -18,6 +18,9 @@ export var sequence;
      *   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);

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.50  |  Generated: 2026-10-09T10:28:38.661Z
+Version: 2.0.52  |  Generated: 2026-10-11T13:21:58.062Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2600,10 +2600,73 @@ interface AppDataHandle {
 }
 ```
 
+**AppRecordClaimResult<T = any>** (interface)
+```typescript
+interface AppRecordClaimResult<T = any> {
+  record: T;
+  created: boolean;
+  conflict?: 'singleton' | 'customId';
+}
+```
+
+**ServerFunctionCounters** (interface)
+```typescript
+interface ServerFunctionCounters {
+  next(name: string, opts?: { start?: number; by?: number }): Promise<number>;
+  get(name: string): Promise<number | null>;
+}
+```
+
+**ResolvedTag** (interface)
+```typescript
+interface ResolvedTag {
+  id: string;
+  claimSetId: string;
+  code: string;
+}
+```
+
+**ContactUpsertDetails** (interface)
+```typescript
+interface ContactUpsertDetails {
+  email?: string;
+  phone?: string;
+  firstName?: string;
+  lastName?: string;
+  displayName?: string;
+  company?: string;
+  locale?: string;
+  timezone?: string;
+  customFields?: Record<string, string | number | boolean>;
+}
+```
+
+**ServerFunctionInteractionEvent** (interface)
+```typescript
+interface ServerFunctionInteractionEvent {
+  interactionId: string;
+  contactId?: string | null;
+  outcome?: string;
+  metadata?: Record<string, any>;
+  productId?: string;
+  proofId?: string;
+  variantId?: string;
+  batchId?: string;
+  eventType?: string;
+}
+```
+
 **ServerFunctionSl** (interface)
 ```typescript
 interface ServerFunctionSl {
-  appRecords: any;
+  appRecords: { claim(fields: Record<string, any>): Promise<AppRecordClaimResult>; [method: string]: any };
+  counters: ServerFunctionCounters;
+  tags: { resolve(id: string): Promise<ResolvedTag | null> };
+  contacts: {
+  upsert(details: ContactUpsertDetails): Promise<{ contactId: string; created: boolean }>;
+  forCaller(): Promise<{ contactId: string } | null>;
+  };
+  interactions: { record(event: ServerFunctionInteractionEvent): Promise<{ eventId: string }> };
   products: any;
   attestations: any;
   appData: AppDataHandle & { global: AppDataHandle; collection: AppDataHandle };
@@ -5229,8 +5292,11 @@ interface UnsubscribeResponse {
 ```typescript
 interface CommsSignupRequest {
   email: string
+  templateId: string
   topics?: string[]
   firstName?: string
+  fields?: { firstName?: string; lastName?: string; displayName?: string; company?: string; locale?: string; timezone?: string; customFields?: Record<string, string | number | boolean> }
+  appId?: string
 }
 ```
 
@@ -5597,9 +5663,23 @@ export interface UnsubscribeResponse { ok: true; applied?: { channels?: Record<s
 // Public sign-up (double opt-in)
 export interface CommsSignupRequest {
   email: string
+  /**
+   * Required: YOUR app's confirmation email — a template in this collection (SL.template) whose body
+   * uses `{{ action_url }}` for the confirm link (`{{ topics }}` lists what they signed up for). The
+   * platform sends no default sign-up email.
+   */
+  templateId: string
   /** Topic ids from the collection's comm settings (e.g. ["newsletter"]). */
   topics?: string[]
   firstName?: string
+  /**
+   * The form's other answers — firstName/lastName/displayName/company/locale/timezone and
+   * `customFields`. Applied to the contact when the address is confirmed, and only where the contact
+   * has no value yet (never overwritten). Small: ~2 KB.
+   */
+  fields?: { firstName?: string; lastName?: string; displayName?: string; company?: string; locale?: string; timezone?: string; customFields?: Record<string, string | number | boolean> }
+  /** Your app id, recorded with the sent email. */
+  appId?: string
 }
 export interface CommsSignupResponse { ok: true; pending: true }
 
@@ -12157,7 +12237,7 @@ Soft-delete a secret. DELETE /secrets/:ref
 ### sequence
 
 **allocate**(collectionId: string, input: AllocateSequenceInput) → `Promise<AllocatedSequence>`
-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`. const { number, isNew } = await sequence.allocate(collectionId, { appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId, })
+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`. const { number, isNew } = await sequence.allocate(collectionId, { appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId, }) `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
 
 ### sessions
 

package/dist/docs/comms.md

@@ -320,14 +320,30 @@ link; nothing is consented until it's clicked. The answer is always the same, so
 used to find out who's registered.
 
 ```typescript
-await comms.signup('collectionId', { email: 'sam@example.com', topics: ['newsletter'] })
+await comms.signup('collectionId', {
+  email: 'sam@example.com',
+  topics: ['newsletter'],
+  templateId: config.confirmationTemplateId, // YOUR confirmation email (required)
+  fields: { firstName: 'Sam', customFields: { favouriteStore: 'Leeds' } }, // optional
+  appId: 'my-newsletter',
+})
 // → { ok: true, pending: true }  — tell the visitor to check their inbox
 ```
 
+- **The confirmation email is the app's own** (emails belong to the app that runs the flow — there is
+  no platform default): a template in the collection, created and edited in the app's admin, e.g.
+  `SL.template.create(collectionId, { name: 'Confirm your subscription', type: 'email', engine: 'liquid',
+  subject: 'Please confirm your subscription', body: '…<a href="{{ action_url }}">Yes, subscribe me</a>…' })`.
+  It gets `{{ action_url }}` (the confirm link), `{{ topics }}` (labels) and `{{ contact.firstName }}`.
+- **Form answers** (`fields`) are applied only once the address is confirmed, and only to the
+  contact's empty fields — a sign-up can never overwrite someone else's details.
+
 - Topics must exist in the collection's comm settings. Give a newsletter topic
   `defaults.policy: 'opt-in'`: broadcasts on an opt-in topic only reach people who said yes
   (confirmed sign-ups), never the whole contact list.
 - Confirming turns on the email channel and the topics, and marks the address verified.
+- Don't use `contact.publicUpsert` + `comms.upsertConsent` for a signed-out form: consent calls act only
+  for the signed-in contact. `comms.signup` is the signed-out path.
 - Set comm settings `signup.confirmedUrl` (https) to send people to your own "thanks" page after
   they confirm (`?confirmed=1`, or `0` for an expired link); otherwise SmartLinks shows a short page.
 

package/dist/docs/containers.md

@@ -62,7 +62,39 @@ Iframe Mode:
 **Where routing goes:**
 - ✅ Your **iframe entry point** (`App.tsx` / `main.tsx`) should use `HashRouter` 
 - ✅ Your **exported container** (`PublicContainer.tsx`) should include `<Routes>` and `<Route>` elements
-- ❌ Your **exported container** should NOT include any `<Router>` wrapper
+- ❌ Your **exported container** should NOT include any `<Router>` wrapper — *unless isolated* (below)
+
+### Pages that read their context from the URL: an isolated router
+
+The example app's pages read `collectionId` / `productId` / `proofId` from the URL. The framework's
+router starts at `/` without them, so the example's container keeps **its own** `MemoryRouter` (seeded
+with those params) — and **isolates** it from the host's router first. Since R5, `react-router-dom` is a
+shared dependency (the host's copy), so a plain nested router is the same library as the host's and
+throws _"You cannot render a `<Router>` inside another `<Router>`"_. Resetting the parent's location and
+navigation context gives your container a router of its own — the same isolation portal-framework puts
+around every direct component:
+
+```tsx
+import { MemoryRouter, Routes, Route, UNSAFE_LocationContext, UNSAFE_NavigationContext } from 'react-router-dom';
+
+export const PublicContainer = ({ collectionId, appId, productId, proofId }: SmartLinksContainerProps) => {
+  const q = new URLSearchParams({ collectionId, appId, ...(productId ? { productId } : {}), ...(proofId ? { proofId } : {}) });
+  return (
+    <UNSAFE_LocationContext.Provider value={null as any}>
+      <UNSAFE_NavigationContext.Provider value={null as any}>
+        <MemoryRouter initialEntries={[`/?${q}`]}>
+          <Routes>
+            <Route path="/*" element={<PublicPage />} />
+          </Routes>
+        </MemoryRouter>
+      </UNSAFE_NavigationContext.Provider>
+    </UNSAFE_LocationContext.Provider>
+  );
+};
+```
+
+Your container's own navigation then stays inside it (it isn't mirrored into the portal's deep link).
+`smartlinks-doctor` warns when a containers bundle uses a router without this isolation.
 
 ### The Router Contract
 

package/dist/docs/overview.md

@@ -93,7 +93,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Container Tracking** | `docs/container-tracking.md` | Physical/logical **item** container groupings — *not* app containers (see containers.md) |
 | **Lots** | `docs/lots.md` | Cross-SKU production "Lot" entity |
 | **Loyalty** | `docs/loyalty.md` | Points, members, earning rules |
-| **Sequences** | `docs/sequences.md` | Atomic monotonic number allocation (raffle / queue / edition) |
+| **Sequences** | `docs/sequences.md` | RETIRING — number things in your own server function: `ctx.sl.counters` + `appRecords.claim` (server-functions.md) |
 | **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
 | **Item Context** | `docs/item-context.md` | The `itemContext` container prop (serial / NFC authenticity context) |
 | **Native Facade** | `docs/native-facade.md` | `host.native` / `SL.native` device-capability facade |

package/dist/docs/sequences.md

@@ -1,5 +1,11 @@
 # 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

package/dist/docs/server-functions.md

@@ -182,8 +182,9 @@ interface ServerFunctionContext {
   appId: string
 
   /** SmartLinks SDK, pre-scoped to your declared `authority`. Capabilities cap what it may do.
-   *  Key resources: `sl.appRecords` (per-app records), `sl.appData` (general/app-wide config +
-   *  data — URLs, flags, counters, arrays), `sl.products`, `sl.attestations`. */
+   *  Key resources: `sl.appRecords` (per-app records, incl. race-safe `claim`), `sl.appData`
+   *  (general/app-wide config + data — URLs, flags, arrays), `sl.counters` (atomic numbering),
+   *  `sl.tags`, `sl.contacts`, `sl.interactions`, `sl.products`, `sl.attestations`. */
   sl: SmartLinks
 
   /** Capability-gated secrets (need `secrets:<name>`). `get(name)` reads this app's own secret on the
@@ -506,7 +507,11 @@ Prefer the platform primitives above over a dependency; when you do need one, pi
 | Read or write SmartLinks data | `ctx.sl.*` (records, products, attestations, …) | the matching `sl:<res>:<read\|write>` |
 | Read/write your app's own data (config, URLs, counters, arrays) | `ctx.sl.appData.get()` / `ctx.sl.appData.set({…})` — collection-scoped by default; `ctx.sl.appData.global.*` (or `{ scope:'global' }`, or declare `dataScope:'global'`) for the app-wide bucket. It's your OWN namespace, so **any** authority may read/write it | `sl:data:read` / `sl:data:write` |
 | Read ANOTHER app's data (as the caller may see it) | `ctx.sl.app('other-app').data.get()` — caller-authority, this collection, public-filtered, read-only | `sl:data:read` |
-| Guarantee a UNIQUE claim (pool of numbers, one-per-user, idempotency key) | `ctx.sl.appRecords.create({ ref: 'ball:57' })` — the DB unique index rejects a duplicate `ref` (catch = "already taken") | `sl:records:write` |
+| Guarantee a UNIQUE claim (one entry per tag, one-per-user, idempotency key, a number nobody else holds) | `ctx.sl.appRecords.claim({ …, singletonPer, customId })` → `{ record, created, conflict? }` — see below | `sl:records:write` |
+| Hand out the next number (tickets, order numbers) | `ctx.sl.counters.next('tickets')` — atomic, distinct per caller | `sl:data:write` |
+| Check a tapped tag is real | `ctx.sl.tags.resolve(proofId)` → `{ id, claimSetId, code }` or `null` | `sl:tags:read` |
+| Put a visitor's details on a contact | `ctx.sl.contacts.upsert({ email, firstName, … })` → `{ contactId, created }` (fills empty fields only) | `sl:contacts:write` |
+| Record "they did X" | `ctx.sl.interactions.record({ interactionId, contactId, outcome, metadata })` | `sl:interactions:write` |
 
 Notes:
 - **Talking to the SmartLinks core is `ctx.sl`, not HTTP.** The common pattern — *validate /
@@ -525,6 +530,81 @@ Notes:
 
 ---
 
+## Uniqueness, numbering and people — the race-safe primitives
+
+A public function is called by many people at once. These primitives make the outcome right no matter
+how the calls interleave — the **database** decides, never a read-then-write in your code.
+
+### `appRecords.claim(fields)` — a unique create
+
+Like `create`, but the record names a **unique key**, and it's inserted only if that key is free.
+Otherwise you get the record already holding it back, **unchanged** (never updated):
+
+```ts
+const { record, created, conflict } = await ctx.sl.appRecords.claim({
+  recordType: 'entry',
+  singletonPer: 'proof', proofId: tag.id,   // key 1: one live entry per tag
+  customId: String(number),                 // key 2: one record per number, ever
+  data: { number },
+})
+// created: true  → you got it
+// created: false → conflict 'singleton' (this tag already has an entry: `record` is it)
+//                  or 'customId' (that number is held by someone else: take another)
+```
+
+- **`singletonPer`** — `'collection' | 'product' | 'variant' | 'batch' | 'proof'`, with its anchor id
+  (`productId`, `proofId`, …). One **live** record per key; deleting it frees the key.
+- **`customId`** — unique per `(recordType, scopeType, scopeId, sourceSystem)`, case-insensitive, and
+  **never reused** (deleted records keep theirs). Right for numbers that must never be handed out twice.
+- Give at least one; with both, the record is created only if both are free.
+- Of any number of concurrent claims on one key, **exactly one** gets `created: true`.
+
+### `counters.next(name, { start?, by? })` — the next number
+
+An atomic counter for your app in this collection: every caller gets a distinct value, even under a
+burst (one row, incremented in one statement). The first call returns `start` (default 1). Counters only
+move forward and live apart from your config, so no config save can rewind one. `counters.get(name)`
+reads the last value handed out (`null` before the first). Name a new counter to start again from `start`.
+
+**Counter + claim = a number nobody else can ever hold.** Take `next()`, then `claim` with
+`customId: String(n)`. If the claim says `conflict: 'customId'`, take `next()` again. A failed or raced
+attempt only leaves a gap — never a duplicate.
+
+### `tags.resolve(id)` — is this tap real?
+
+A tap hands your app the virtual-proof id `<claimSetId>-<code>`. `resolve` returns
+`{ id, claimSetId, code }` when that code exists in a claim set of **this** collection, else `null`.
+Key records to the returned canonical `id`, and refuse `null` — otherwise anyone can invent ids.
+
+### `contacts.upsert(details)` / `contacts.forCaller()`
+
+`upsert` finds the contact by `email` or `phone` (one is required) or creates it, and only **fills
+empty fields** — it never overwrites a name or field the contact already has, because a visitor's typed
+details are unverified. It's race-safe: two simultaneous entries with one email end on one contact.
+Returns `{ contactId, created }`. `forCaller()` is the signed-in caller's own contact (`null` when
+anonymous). **Never return contact ids to public callers** — keep them on your records.
+
+This is not consent. A ticked "keep me updated" box is evidence you can record (below); subscribing
+someone to marketing is the double opt-in flow (`comms.signup`, see comms.md).
+
+### `interactions.record(event)` — "they did X"
+
+Records an event of one of **your app's interaction types**: create the type once in admin with
+`SL.interactions.ensureType(collectionId, { appId, key: 'raffle-entry' })`, keep its id in your app
+config, and pass that id. Unknown ids are refused (`INTERACTION_TYPE_NOT_FOUND`). The event runs the
+type's effects and emits `interaction.submitted`, like any submission.
+
+```ts
+await ctx.sl.interactions.record({
+  interactionId: config.interactionIds.entered,
+  contactId,                         // optional
+  outcome: 'entered',
+  metadata: { number, consent: true },
+})
+```
+
+---
+
 ## Worked example — a public competition entry
 
 ```ts
@@ -756,6 +836,9 @@ const ctx = createFunctionTestContext({
 
 const res = await submitCompetitionEntry(ctx, { method: 'POST', body: { email: 'a@b.com', answer: '42' } })
 // ctx.sl.appRecords.create(...) throws CapabilityError unless `def` declares sl:records:write
+// With no `sl` impl, records / counters / contacts / interactions run in memory with the platform's
+// uniqueness rules — assert on ctx.memory. Share createFunctionTestMemory() between contexts to
+// simulate concurrent callers; restrict ids with knownTags / knownInteractionTypes.
 ```
 
 Pass the **`def`** (not a hand-typed capability list) so "tested" can't drift from

package/dist/openapi.yaml

@@ -19218,16 +19218,113 @@ components:
     AppDataHandle:
       type: object
       properties: {}
+    AppRecordClaimResult:
+      type: object
+      properties:
+        record:
+          type: object
+          additionalProperties: true
+        created:
+          type: boolean
+        conflict:
+          type: string
+          enum:
+            - singleton
+            - customId
+      required:
+        - record
+        - created
+    ServerFunctionCounters:
+      type: object
+      properties: {}
+    ResolvedTag:
+      type: object
+      properties:
+        id:
+          type: string
+        claimSetId:
+          type: string
+        code:
+          type: string
+      required:
+        - id
+        - claimSetId
+        - code
+    ContactUpsertDetails:
+      type: object
+      properties:
+        email:
+          type: string
+        phone:
+          type: string
+        firstName:
+          type: string
+        lastName:
+          type: string
+        displayName:
+          type: string
+        company:
+          type: string
+        locale:
+          type: string
+        timezone:
+          type: string
+        customFields:
+          type: object
+          additionalProperties:
+            type: object
+            additionalProperties: true
+    ServerFunctionInteractionEvent:
+      type: object
+      properties:
+        interactionId:
+          type: string
+        contactId:
+          type: string
+        outcome:
+          type: string
+        metadata:
+          type: object
+          additionalProperties: true
+        productId:
+          type: string
+        proofId:
+          type: string
+        variantId:
+          type: string
+        batchId:
+          type: string
+        eventType:
+          type: string
+      required:
+        - interactionId
     ServerFunctionSl:
       type: object
       properties:
-        appRecords: {}
+        appRecords:
+          type: object
+          additionalProperties: true
+        counters:
+          $ref: "#/components/schemas/ServerFunctionCounters"
+        tags:
+          type: object
+          additionalProperties: true
+        contacts:
+          type: object
+          additionalProperties: true
+        interactions:
+          type: object
+          additionalProperties: true
         products: {}
         attestations: {}
         appData:
           $ref: "#/components/schemas/AppDataHandle"
       required:
         - appRecords
+        - counters
+        - tags
+        - contacts
+        - interactions
         - products
         - attestations
         - appData
@@ -23658,14 +23755,22 @@ components:
       properties:
         email:
           type: string
+        templateId:
+          type: string
         topics:
           type: array
           items:
             type: string
         firstName:
           type: string
+        fields:
+          type: object
+          additionalProperties: true
+        appId:
+          type: string
       required:
         - email
+        - templateId
     CommsSignupResponse:
       type: object
       properties:

package/dist/testing/index.d.ts

@@ -8,6 +8,7 @@ export declare class CapabilityError extends Error {
 export interface TestSlImpl {
     appRecords?: {
         create?(fields: any): any;
+        claim?(fields: any): any;
         update?(id: string, fields: any): any;
         upsert?(fields: any): any;
         delete?(id: string): any;
@@ -15,6 +16,21 @@ export interface TestSlImpl {
         query?(params: any): any;
         listTypes?(): any;
     };
+    counters?: {
+        next?(name: string, opts?: any): any;
+        get?(name: string): any;
+    };
+    /** Tag lookup. Default: any `<claimSetId>-<code>` resolves (pass `knownTags` to restrict). */
+    tags?: {
+        resolve?(id: string): any;
+    };
+    contacts?: {
+        upsert?(details: any): any;
+        forCaller?(): any;
+    };
+    interactions?: {
+        record?(event: any): any;
+    };
     products?: {
         get?(id: string, opts?: any): any;
         query?(body?: any, opts?: any): any;
@@ -64,7 +80,27 @@ export interface CreateFunctionTestContextOptions {
     fetch?: typeof fetch;
     /** What the platform would have prefetched as `ctx.inputs` (e.g. `{ entity: product }`). Default `{}`. */
     inputs?: ServerFunctionInputs;
+    /** Tags that exist, as `<claimSetId>-<code>` ids — `ctx.sl.tags.resolve` returns null for any other. */
+    knownTags?: string[];
+    /** Interaction type ids that exist for this app — `interactions.record` refuses others. Default: any. */
+    knownInteractionTypes?: string[];
+    /** Share one in-memory store between several contexts (e.g. concurrent callers in one test). */
+    memory?: FunctionTestMemory;
+}
+/** The harness's in-memory platform state (when no impl is injected). */
+export interface FunctionTestMemory {
+    records: any[];
+    counters: Record<string, number>;
+    contacts: Array<{
+        contactId: string;
+        email?: string;
+        phone?: string;
+        [k: string]: any;
+    }>;
+    interactions: any[];
 }
+/** A fresh in-memory store — pass the same one to several test contexts to simulate concurrent callers. */
+export declare function createFunctionTestMemory(): FunctionTestMemory;
 export interface FunctionTestContext extends ServerFunctionContext {
     /** Captured log lines (also written via ctx.log). */
     logs: Array<{
@@ -72,6 +108,8 @@ export interface FunctionTestContext extends ServerFunctionContext {
         message: string;
         data?: Record<string, any>;
     }>;
+    /** The in-memory platform state this context reads and writes. */
+    memory: FunctionTestMemory;
 }
 /**
  * Build a capability-enforcing test ctx for a server function. Run your handler with it: