@proveanything/smartlinks 2.0.49 → 2.0.51

package/dist/testing/index.js

@@ -14,6 +14,21 @@
 //  - `ctx.secrets` are FIXTURES you provide; real sealed secrets are server-only and
 //    never resolvable locally.
 //  - `ctx.fetch` is gated by the `network` capability just like production.
+//  - Without an injected impl, appRecords / counters / contacts / interactions run against an
+//    in-memory store with the platform's uniqueness rules (claim: singletonPer + customId; contacts by
+//    email/phone, fill-empty only), so idempotency and "never two of the same number" are testable.
+//    Inspect it via `ctx.memory`.
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 export class CapabilityError extends Error {
     constructor(capability, message) {
         super(message || `capability not granted: ${capability}`);
@@ -58,6 +73,10 @@ function allowsSl(p, resource, op) {
         return true; // write implies read
     return false;
 }
+/** A fresh in-memory store — pass the same one to several test contexts to simulate concurrent callers. */
+export function createFunctionTestMemory() {
+    return { records: [], counters: {}, contacts: [], interactions: [] };
+}
 const stub = (method, args) => ({ __stub: true, method, args });
 /**
  * Build a capability-enforcing test ctx for a server function. Run your handler with it:
@@ -79,18 +98,75 @@ export function createFunctionTestContext(opts) {
             throw new CapabilityError(`sl:${resource}:${op}`);
         return fn ? fn(...args) : stub(`${resource}.${name}`, args);
     };
+    const mem = opts.memory || createFunctionTestMemory();
     const ar = impl.appRecords || {};
     const pr = impl.products || {};
     const at = impl.attestations || {};
+    // In-memory records with the platform's unique keys (used when no appRecords impl is injected).
+    const singletonKey = (f) => {
+        const t = f.recordType || 'default';
+        switch (f.singletonPer) {
+            case 'collection': return `${t}:collection`;
+            case 'product': return f.productId ? `${t}:product:${f.productId}` : null;
+            case 'variant': return f.productId && f.variantId ? `${t}:variant:${f.productId}:${f.variantId}` : null;
+            case 'batch': return f.productId && f.batchId ? `${t}:batch:${f.productId}:${f.batchId}` : null;
+            case 'proof': return f.proofId ? `${t}:proof:${f.proofId}` : null;
+            default: return null;
+        }
+    };
+    const customKey = (f) => {
+        const c = f.customId == null ? '' : String(f.customId).trim().toLowerCase();
+        return c ? [f.recordType || 'default', f.scopeType || '', f.scopeId || '', f.sourceSystem || '', c].join('|') : null;
+    };
+    let nextRecordId = 1;
+    const memRecords = {
+        create: async (fields) => {
+            const rec = Object.assign({ id: `rec-${nextRecordId++}`, recordType: 'default', data: {}, admin: {}, status: 'active', createdAt: new Date().toISOString() }, fields);
+            mem.records.push(rec);
+            return Object.assign({}, rec);
+        },
+        claim: async (fields) => {
+            const sk = singletonKey(fields);
+            const ck = customKey(fields);
+            if (fields.singletonPer && !sk)
+                throw Object.assign(new Error(`claim: singletonPer "${fields.singletonPer}" needs its anchor id`), { code: 'INVALID_CLAIM' });
+            if (!sk && !ck)
+                throw Object.assign(new Error('claim: give the record a unique key — singletonPer (+ anchor) or customId'), { code: 'INVALID_CLAIM' });
+            const bySingleton = sk ? mem.records.find((r) => !r.deletedAt && singletonKey(r) === sk) : null;
+            if (bySingleton)
+                return { record: Object.assign({}, bySingleton), created: false, conflict: 'singleton' };
+            const byCustom = ck ? mem.records.find((r) => customKey(r) === ck) : null; // deleted records keep their customId
+            if (byCustom)
+                return { record: Object.assign({}, byCustom), created: false, conflict: 'customId' };
+            return { record: await memRecords.create(fields), created: true };
+        },
+        get: async (id) => { const r = mem.records.find((x) => x.id === id); return r ? Object.assign({}, r) : null; },
+        update: async (id, fields) => { const r = mem.records.find((x) => x.id === id); if (!r)
+            return null; Object.assign(r, fields); return Object.assign({}, r); },
+        delete: async (id) => { const r = mem.records.find((x) => x.id === id); if (r)
+            r.deletedAt = new Date().toISOString(); return {}; },
+        // Simple equality filter on top-level fields (recordType, proofId, customId, status, …).
+        query: async (params = {}) => {
+            const _a = params || {}, { limit, offset, sort } = _a, where = __rest(_a, ["limit", "offset", "sort"]);
+            const all = mem.records.filter((r) => !r.deletedAt && Object.entries(where).every(([k, v]) => r[k] === v));
+            const from = offset || 0;
+            const size = limit || 200;
+            const data = all.slice(from, from + size).map((r) => (Object.assign({}, r)));
+            // Same envelope as the platform: { data, pagination }.
+            return { data, pagination: { total: all.length, limit: size, offset: from, hasMore: from + data.length < all.length } };
+        },
+    };
+    const recordsFn = (name) => ar[name] ? ar[name].bind(ar) : (impl.appRecords ? undefined : memRecords[name]);
     const sl = {
         appRecords: {
-            create: gated('records', 'write', ar.create && ar.create.bind(ar), 'create'),
-            update: gated('records', 'write', ar.update && ar.update.bind(ar), 'update'),
-            upsert: gated('records', 'write', ar.upsert && ar.upsert.bind(ar), 'upsert'),
-            delete: gated('records', 'write', ar.delete && ar.delete.bind(ar), 'delete'),
-            get: gated('records', 'read', ar.get && ar.get.bind(ar), 'get'),
-            query: gated('records', 'read', ar.query && ar.query.bind(ar), 'query'),
-            listTypes: gated('records', 'read', ar.listTypes && ar.listTypes.bind(ar), 'listTypes'),
+            create: gated('records', 'write', recordsFn('create'), 'create'),
+            claim: gated('records', 'write', recordsFn('claim'), 'claim'),
+            update: gated('records', 'write', recordsFn('update'), 'update'),
+            upsert: gated('records', 'write', recordsFn('upsert'), 'upsert'),
+            delete: gated('records', 'write', recordsFn('delete'), 'delete'),
+            get: gated('records', 'read', recordsFn('get'), 'get'),
+            query: gated('records', 'read', recordsFn('query'), 'query'),
+            listTypes: gated('records', 'read', recordsFn('listTypes'), 'listTypes'),
         },
         products: {
             get: gated('products', 'read', pr.get && pr.get.bind(pr), 'get'),
@@ -122,6 +198,62 @@ export function createFunctionTestContext(opts) {
                 delete memConfig[k]; }), 'delete'),
     });
     sl.appData = Object.assign(makeAppData(), { global: makeAppData(), collection: makeAppData() });
+    const cn = impl.counters || {};
+    sl.counters = {
+        next: gated('data', 'write', cn.next ? cn.next.bind(cn) : (async (name, o = {}) => {
+            var _a, _b;
+            const start = (_a = o.start) !== null && _a !== void 0 ? _a : 1;
+            const by = (_b = o.by) !== null && _b !== void 0 ? _b : 1;
+            mem.counters[name] = mem.counters[name] == null ? start : mem.counters[name] + by;
+            return mem.counters[name];
+        }), 'counters.next'),
+        get: gated('data', 'read', cn.get ? cn.get.bind(cn) : (async (name) => { var _a; return (_a = mem.counters[name]) !== null && _a !== void 0 ? _a : null; }), 'counters.get'),
+    };
+    const tg = impl.tags || {};
+    sl.tags = {
+        resolve: gated('tags', 'read', tg.resolve ? tg.resolve.bind(tg) : (async (id) => {
+            const s = String(id || '');
+            const i = s.indexOf('-');
+            if (i <= 0 || i >= s.length - 1)
+                return null;
+            if (opts.knownTags && !opts.knownTags.includes(s))
+                return null;
+            return { id: s, claimSetId: s.slice(0, i), code: s.slice(i + 1) };
+        }), 'tags.resolve'),
+    };
+    const ct = impl.contacts || {};
+    const fillable = ['firstName', 'lastName', 'displayName', 'company', 'locale', 'timezone'];
+    sl.contacts = {
+        upsert: gated('contacts', 'write', ct.upsert ? ct.upsert.bind(ct) : (async (d = {}) => {
+            const email = d.email ? String(d.email).trim().toLowerCase() : undefined;
+            const phone = d.phone ? String(d.phone).replace(/[^\d+]/g, '') : undefined;
+            if (!email && !phone)
+                throw Object.assign(new Error('contacts.upsert: an email or phone is required'), { code: 'CONTACT_IDENTITY_REQUIRED' });
+            const found = mem.contacts.find((c) => (email && c.email === email) || (phone && c.phone === phone));
+            if (found) {
+                for (const k of fillable)
+                    if (d[k] && !found[k])
+                        found[k] = d[k];
+                found.customFields = Object.assign(Object.assign({}, (d.customFields || {})), (found.customFields || {}));
+                return { contactId: found.contactId, created: false };
+            }
+            const contactId = `contact-${mem.contacts.length + 1}`;
+            mem.contacts.push(Object.assign(Object.assign({}, d), { email, phone, contactId }));
+            return { contactId, created: true };
+        }), 'contacts.upsert'),
+        forCaller: gated('contacts', 'write', ct.forCaller ? ct.forCaller.bind(ct) : (async () => (opts.caller && opts.caller.userId ? { contactId: `contact-of-${opts.caller.userId}` } : null)), 'contacts.forCaller'),
+    };
+    const it = impl.interactions || {};
+    sl.interactions = {
+        record: gated('interactions', 'write', it.record ? it.record.bind(it) : (async (event = {}) => {
+            if (!event.interactionId || (opts.knownInteractionTypes && !opts.knownInteractionTypes.includes(event.interactionId))) {
+                throw Object.assign(new Error(`"${event.interactionId}" is not an interaction type of this app`), { code: 'INTERACTION_TYPE_NOT_FOUND' });
+            }
+            const eventId = `event-${mem.interactions.length + 1}`;
+            mem.interactions.push(Object.assign(Object.assign({}, event), { eventId, userId: (opts.caller && opts.caller.userId) || null }));
+            return { eventId };
+        }), 'interactions.record'),
+    };
     sl.app = (appId) => {
         const other = (impl.app && impl.app(appId)) || {};
         const od = other.data || {};
@@ -178,5 +310,6 @@ export function createFunctionTestContext(opts) {
         },
         inputs: Object.freeze(Object.assign({}, (opts.inputs || {}))),
         logs,
+        memory: mem,
     };
 }

package/dist/types/ai.d.ts

@@ -679,7 +679,7 @@ export interface AgentRunRequest {
     prompt?: string;
     /** System instructions. */
     instructions?: string;
-    /** Model id, e.g. 'openai/gpt-5.6-terra'. */
+    /** Model id, e.g. 'openai/gpt-6.1-sol'. */
     model?: string;
     /** Safety cap on model round-trips. */
     maxSteps?: number;

package/dist/types/appManifest.d.ts

@@ -365,9 +365,96 @@ export interface AppDataHandle {
  *  - by CALLER identity — everything else (products, attestations, and `app(id)` cross-app reads)
  *    is bounded by what the invoking user could do through the permissioned API.
  */
+/** `ctx.sl.appRecords.claim` result. `conflict` says which unique key was already held. */
+export interface AppRecordClaimResult<T = any> {
+    record: T;
+    created: boolean;
+    conflict?: 'singleton' | 'customId';
+}
+/** `ctx.sl.counters` — this app's atomic named counters in the collection. */
+export interface ServerFunctionCounters {
+    /** The next value — distinct for every caller, even under a burst. First call returns `start` (default 1). */
+    next(name: string, opts?: {
+        start?: number;
+        by?: number;
+    }): Promise<number>;
+    /** The last value handed out, or `null` before the first `next`. */
+    get(name: string): Promise<number | null>;
+}
+/** A tap's tag, resolved and checked to belong to this collection. */
+export interface ResolvedTag {
+    /** Canonical virtual-proof id `<claimSetId>-<code>` — key things to THIS, not the raw input. */
+    id: string;
+    claimSetId: string;
+    code: string;
+}
+/** Contact details a function may pass to `ctx.sl.contacts.upsert` (plain strings, capped). */
+export interface ContactUpsertDetails {
+    email?: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
+    company?: string;
+    locale?: string;
+    timezone?: string;
+    customFields?: Record<string, string | number | boolean>;
+}
+/** An interaction event recorded from a server function. */
+export interface ServerFunctionInteractionEvent {
+    /** The interaction TYPE id — created first in admin with `interactions.ensureType`, kept in config. */
+    interactionId: string;
+    contactId?: string | null;
+    /** e.g. 'entered'. Letters, digits, `. : - _`. Default 'submitted'. */
+    outcome?: string;
+    metadata?: Record<string, any>;
+    productId?: string;
+    proofId?: string;
+    variantId?: string;
+    batchId?: string;
+    eventType?: string;
+}
 export interface ServerFunctionSl {
-    /** THIS app's records (own namespace). */
-    appRecords: any;
+    /**
+     * THIS app's records (own namespace): create / update / upsert / delete / get / query / listTypes,
+     * plus `claim(fields)` — a race-safe UNIQUE create. The record names a unique key — `singletonPer`
+     * (+ its anchor, e.g. `{ singletonPer: 'proof', proofId }`) and/or `customId` — and is inserted only
+     * if the key is free; otherwise the record holding it comes back UNCHANGED with `created: false`.
+     * Of any number of concurrent claims on one key, exactly one is created (the database decides).
+     */
+    appRecords: {
+        claim(fields: Record<string, any>): Promise<AppRecordClaimResult>;
+        [method: string]: any;
+    };
+    /** Atomic named counters for this app in this collection (`sl:data:write` / `sl:data:read`). */
+    counters: ServerFunctionCounters;
+    /** Tags (`sl:tags:read`): `resolve(id)` → the real tag in THIS collection, or `null` for a made-up id. */
+    tags: {
+        resolve(id: string): Promise<ResolvedTag | null>;
+    };
+    /**
+     * Contacts (`sl:contacts:write`). `upsert` finds by email/phone or creates, and only FILLS EMPTY
+     * fields — never overwrites (details typed by a visitor are unverified). `forCaller` is the signed-in
+     * caller's own contact (null when anonymous). Never return contact ids to public callers.
+     */
+    contacts: {
+        upsert(details: ContactUpsertDetails): Promise<{
+            contactId: string;
+            created: boolean;
+        }>;
+        forCaller(): Promise<{
+            contactId: string;
+        } | null>;
+    };
+    /**
+     * Interactions (`sl:interactions:write`). `record` stores an event of one of THIS app's interaction
+     * types (refused if the type doesn't exist), runs the type's effects and emits `interaction.submitted`.
+     */
+    interactions: {
+        record(event: ServerFunctionInteractionEvent): Promise<{
+            eventId: string;
+        }>;
+    };
     /** Products, scoped by caller authority + declared capability. */
     products: any;
     /** Attestations, scoped by caller authority + declared capability. */

package/dist/types/comms.d.ts

@@ -184,9 +184,31 @@ export interface UnsubscribeResponse {
 }
 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;

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.49  |  Generated: 2026-10-09T10:14:16.325Z
+Version: 2.0.51  |  Generated: 2026-10-10T07:57:23.889Z
 
 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/docs/ai.md

@@ -408,15 +408,21 @@ Discover tools two ways:
 
 ### Recommended Models
 
-For agentic workflows on `v1/responses`, GPT-5.6 ships in three tiers. Pass either the full model
-id (`openai/gpt-5.6-sol`) or the shorthand tier alias (`'cheap'`, `'balanced'`, `'premium'`) as
-`model` — both resolve through the same server-side model registry.
-
-| Tier | Model | Alias | Use for |
-|------|-------|-------|---------|
-| Cheapest (default) | `openai/gpt-5.6-luna` | `'cheap'` / omit `model` | Everyday chat, high-volume/simple turns |
-| Balanced | `openai/gpt-5.6-terra` | `'balanced'` | Admin agent / tool-heavy setup workflows (route default) |
-| Flagship | `openai/gpt-5.6-sol` | `'premium'` | Most demanding reasoning, coding, and multi-step tool use |
+Pass either a full model id (`openai/gpt-6.1-sol`) or a tier alias (`'cheap'`, `'balanced'`,
+`'premium'`) as `model` — both resolve through the same server-side model registry. The tiers are the
+GPT-6 family (prices per 1M tokens, input / output, OpenAI list price):
+
+| Tier | Model | Alias | Price | Use for |
+|------|-------|-------|-------|---------|
+| Cheapest (default) | `openai/gpt-6-luna` | `'cheap'` / omit `model` | $0.10 / $0.50 | Everyday chat, high-volume/simple turns |
+| Balanced | `openai/gpt-6.1-sol` | `'balanced'` | $2 / $10 | Admin agent / tool-heavy workflows (the `v1/responses` default) |
+| Most capable | `openai/gpt-6-astra` | `'premium'` | $10 / $50 | The hardest reasoning, coding and long multi-step tool use |
+
+The previous generation stays available by id — `openai/gpt-5.6-luna` ($0.20 / $1.20),
+`openai/gpt-5.6-terra` ($2 / $12) and `openai/gpt-5.6-sol` ($4 / $20) — and `ai.models.list(collectionId)` returns
+the full current set. GPT-6.1 Sol is the same input price as GPT-5.6 Terra with cheaper output, so prefer
+the tiers. If OpenAI refuses a GPT-6 request for a model/option reason, SmartLinks retries it once on the
+GPT-5.6 equivalent, so a call never fails just because a GPT-6 model doesn't accept something yet.
 
 Every tier supports function/tool calling, Programmatic Tool Calling, and Multi-agent (see below), and all
 three accept `service_tier: 'flex'` (≈50% cheaper, Batch-API rates, slower) or `'priority'` (premium, guaranteed

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