@proveanything/smartlinks 1.16.3 → 1.16.5

package/dist/api/proof.d.ts

@@ -1,4 +1,4 @@
-import { ProofResponse, ProofCreateRequest, ProofUpdateRequest, ProofValuesUpdateRequest, ProofClaimRequest, ProofGrant, CreateGrantOptions, RedeemGrantOptions, RedeemGrantResult, ProofTransfer, TransferProofOptions, TransferProofResult } from "../types/proof";
+import { ProofResponse, ProofCreateRequest, ProofUpdateRequest, ProofValuesUpdateRequest, ProofClaimRequest, ProofGrant, CreateGrantOptions, RedeemGrantOptions, RedeemGrantResult, ProofTransfer, TransferProofOptions, TransferProofResult, AcceptTransferOptions, CancelTransferOptions } from "../types/proof";
 export declare namespace proof {
     /**
      * Retrieves a single Proof by Collection ID, Product ID, and Proof ID.
@@ -177,6 +177,23 @@ export declare namespace proof {
      * ```ts
      * await proof.transfer(collectionId, productId, proofId, { release: true })
      * ```
+     * Send comms by naming templates per role (server decides who receives each):
+     * ```ts
+     * await proof.transfer(collectionId, productId, proofId, {
+     *   toEmail: 'buyer@example.com',
+     *   comms: {
+     *     recipient: { templateId: 'transfer-incoming', props: { note: 'Enjoy!' } },
+     *     sender:    { templateId: 'transfer-sent' },
+     *   },
+     * })
+     * ```
+     * Direct to an SMS recipient by phone (E.164) and notify them by text:
+     * ```ts
+     * await proof.transfer(collectionId, productId, proofId, {
+     *   toPhone: '+14155551234',
+     *   comms: { recipient: { templateId: 'transfer-incoming', channel: 'sms' } },
+     * })
+     * ```
      */
     function transfer(collectionId: string, productId: string, proofId: string, options: TransferProofOptions): Promise<TransferProofResult>;
     /**
@@ -184,12 +201,12 @@ export declare namespace proof {
      * move — the proof's `userId` becomes the caller and the previous owner's private
      * data and share grants are cleared/voided.
      */
-    function acceptTransfer(collectionId: string, productId: string, proofId: string): Promise<{
+    function acceptTransfer(collectionId: string, productId: string, proofId: string, options?: AcceptTransferOptions): Promise<{
         ok: boolean;
         proof: ProofResponse;
     }>;
     /** Cancel a pending push transfer (current owner / collection admin only). */
-    function cancelTransfer(collectionId: string, productId: string, proofId: string): Promise<{
+    function cancelTransfer(collectionId: string, productId: string, proofId: string, options?: CancelTransferOptions): Promise<{
         ok: boolean;
     }>;
     /**

package/dist/api/proof.js

@@ -270,6 +270,23 @@ export var proof;
      * ```ts
      * await proof.transfer(collectionId, productId, proofId, { release: true })
      * ```
+     * Send comms by naming templates per role (server decides who receives each):
+     * ```ts
+     * await proof.transfer(collectionId, productId, proofId, {
+     *   toEmail: 'buyer@example.com',
+     *   comms: {
+     *     recipient: { templateId: 'transfer-incoming', props: { note: 'Enjoy!' } },
+     *     sender:    { templateId: 'transfer-sent' },
+     *   },
+     * })
+     * ```
+     * Direct to an SMS recipient by phone (E.164) and notify them by text:
+     * ```ts
+     * await proof.transfer(collectionId, productId, proofId, {
+     *   toPhone: '+14155551234',
+     *   comms: { recipient: { templateId: 'transfer-incoming', channel: 'sms' } },
+     * })
+     * ```
      */
     async function transfer(collectionId, productId, proofId, options) {
         return post(transferBase(collectionId, productId, proofId), Object.assign({}, options));
@@ -280,13 +297,13 @@ export var proof;
      * move — the proof's `userId` becomes the caller and the previous owner's private
      * data and share grants are cleared/voided.
      */
-    async function acceptTransfer(collectionId, productId, proofId) {
-        return post(`${transferBase(collectionId, productId, proofId)}/accept`, {});
+    async function acceptTransfer(collectionId, productId, proofId, options = {}) {
+        return post(`${transferBase(collectionId, productId, proofId)}/accept`, Object.assign({}, options));
     }
     proof.acceptTransfer = acceptTransfer;
     /** Cancel a pending push transfer (current owner / collection admin only). */
-    async function cancelTransfer(collectionId, productId, proofId) {
-        return post(`${transferBase(collectionId, productId, proofId)}/cancel`, {});
+    async function cancelTransfer(collectionId, productId, proofId, options = {}) {
+        return post(`${transferBase(collectionId, productId, proofId)}/cancel`, Object.assign({}, options));
     }
     proof.cancelTransfer = cancelTransfer;
     /**

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.16.3  |  Generated: 2026-09-05T10:57:07.719Z
+Version: 1.16.5  |  Generated: 2026-09-05T15:46:49.017Z
 
 This is a concise summary of all available API functions and types.
 
@@ -35,6 +35,7 @@ For detailed guides on specific features:
 - **[Proof Claiming Methods](proof-claiming-methods.md)** - All methods for claiming/registering product ownership (NFC tags, serial numbers, auto-generated claims)
 - **[Proof Share Grants](proof-share-grants.md)** - Delegated, scoped, revocable bearer access to a single proof (read/comment/verify-owner links)
 - **[Proof Ownership Transfer](proof-ownership-transfer.md)** - Moving a proof to a new owner: directed transfer, open release, accept/cancel, and the state machine
+- **[Comms Triggers](proof-comms-triggers.md)** - Sending transactional comms from proof actions (claim/transfer/accept/cancel): the role→template map, per-action roles, and the trust boundary
 - **[Lots](lots.md)** - Collection-scoped production groupings spanning many SKUs; facet/product selectors, member resolution, and GS1 AI(10) batch-then-lot resolution
 - **[Item Context](item-context.md)** - The `itemContext` container prop derived from a serial-proof URL or NFC tap (what item the URL points at)
 - **[Product Facets SDK](PRODUCT_FACETS_SDK.md)** - Admin and public product facet endpoints and TypeScript interfaces
@@ -7508,6 +7509,15 @@ interface ProofValuesUpdateRequest {
 }
 ```
 
+**ProofClaimRequest** (interface)
+```typescript
+interface ProofClaimRequest {
+  data?: Record<string, any>
+  comms?: CommsTriggerMap
+  [key: string]: any
+}
+```
+
 **ProofFieldsConfig** (interface)
 ```typescript
 interface ProofFieldsConfig {
@@ -7580,13 +7590,34 @@ interface ProofTransfer {
 }
 ```
 
+**CommsTrigger** (interface)
+```typescript
+interface CommsTrigger {
+  templateId: string
+  channel?: 'preferred' | 'email' | 'sms' | 'push' | 'wallet' | 'whatsapp'
+  props?: Record<string, any>
+  notify?: boolean
+  appId?: string
+}
+```
+
 **TransferProofOptions** (interface)
 ```typescript
 interface TransferProofOptions {
+  * Comms to send. Roles: `recipient` (the named new owner) and `sender` (the
+  * initiator) for a directed transfer; `owner` for an open release. For an
+  * SMS recipient, set `comms.recipient.channel = 'sms'`.
+  comms?: CommsTriggerMap
   toEmail?: string
+  * Directed: recipient phone in E.164 (e.g. `+14155551234`). Resolves to the same
+  * user they log in as via SMS OTP (created if needed). Pair with an SMS comms
+  * trigger to notify them: `comms.recipient.channel = 'sms'`.
+  toPhone?: string
   toUserId?: string
   toName?: string
   release?: boolean
+  * @deprecated The legacy fixed transfer email is gone. Put a note in a comms
+  * trigger's props instead, e.g. `comms.recipient.props.note`.
   message?: string
   notify?: boolean
 }
@@ -7601,12 +7632,26 @@ interface TransferProofResult {
 }
 ```
 
+**AcceptTransferOptions** (interface)
+```typescript
+interface AcceptTransferOptions {
+  comms?: CommsTriggerMap
+  notify?: boolean
+}
+```
+
+**CancelTransferOptions** (interface)
+```typescript
+interface CancelTransferOptions {
+  comms?: CommsTriggerMap
+  notify?: boolean
+}
+```
+
 **ProofResponse** = `Proof`
 
 **ProofUpdateRequest** = `Partial<ProofWrite> & { proof?: ProofWrite }`
 
-**ProofClaimRequest** = `Record<string, any>`
-
 **ProofFieldScope** = `'public' | 'owner' | 'personal' | 'admin'`
 
 **ProofFieldDef** = `ScopedFieldDef & { scope?: ProofFieldScope }`
@@ -7619,6 +7664,8 @@ interface TransferProofResult {
 
 **ProofTransferState** = ``
 
+**CommsTriggerMap** = `Record<string, CommsTrigger>`
+
 ### qr
 
 **QrShortCodeLookupResponse** (interface)
@@ -10428,16 +10475,18 @@ Redeem a grant token (anonymous or signed-in). Records the redemption and return
     productId: string,
     proofId: string,
     options: TransferProofOptions) → `Promise<TransferProofResult>`
-Start a push transfer of a proof (current owner / collection admin only). Directed — hand it to a named recipient who then calls {@link acceptTransfer}: ```ts await proof.transfer(collectionId, productId, proofId, { toEmail: 'buyer@example.com' }) ``` Open release — make the proof claimable by anyone: ```ts await proof.transfer(collectionId, productId, proofId, { release: true }) ```
+Start a push transfer of a proof (current owner / collection admin only). Directed — hand it to a named recipient who then calls {@link acceptTransfer}: ```ts await proof.transfer(collectionId, productId, proofId, { toEmail: 'buyer@example.com' }) ``` Open release — make the proof claimable by anyone: ```ts await proof.transfer(collectionId, productId, proofId, { release: true }) ``` Send comms by naming templates per role (server decides who receives each): ```ts await proof.transfer(collectionId, productId, proofId, { toEmail: 'buyer@example.com', comms: { recipient: { templateId: 'transfer-incoming', props: { note: 'Enjoy!' } }, sender:    { templateId: 'transfer-sent' }, }, }) ``` Direct to an SMS recipient by phone (E.164) and notify them by text: ```ts await proof.transfer(collectionId, productId, proofId, { toPhone: '+14155551234', comms: { recipient: { templateId: 'transfer-incoming', channel: 'sms' } }, }) ```
 
 **acceptTransfer**(collectionId: string,
     productId: string,
-    proofId: string) → `Promise<`
+    proofId: string,
+    options: AcceptTransferOptions = {}) → `Promise<`
 Accept a directed transfer (the named recipient only). Completes the ownership move — the proof's `userId` becomes the caller and the previous owner's private data and share grants are cleared/voided.
 
 **cancelTransfer**(collectionId: string,
     productId: string,
-    proofId: string) → `Promise<`
+    proofId: string,
+    options: CancelTransferOptions = {}) → `Promise<`
 Cancel a pending push transfer (current owner / collection admin only).
 
 **getTransfer**(collectionId: string,

package/dist/docs/proof-claiming-methods.md

@@ -289,6 +289,22 @@ try {
 
 ---
 
+## Sending a claim confirmation
+
+Claims can send a transactional confirmation once the proof is committed to the
+ledger. Pass a `comms` map (role `claimer`) alongside `data` — you author the
+template, the server hydrates `{{ proof }}` / `{{ product }}` / `{{ contact }}`:
+
+```ts
+await proof.claim(collectionId, productId, proofId, {
+  data: { store: 'Regent St' },
+  comms: { claimer: { templateId: 'welcome-owner', channel: 'preferred' } },
+})
+```
+
+Omit `comms` and nothing is sent (opt-in). Full detail:
+[Comms Triggers](./proof-comms-triggers.md).
+
 ## API Reference
 
 ### `proof.claim(collectionId, productId, proofId, data?)`

package/dist/docs/proof-comms-triggers.md

@@ -0,0 +1,142 @@
+# Comms Triggers
+
+The standard way to send a **transactional message** as a side-effect of a proof
+action — a claim confirmation, a "you've received a transfer" email, a
+cancellation notice. You pass a **comms trigger** into the action; the server
+sends it once the action's write is durable.
+
+This replaces the old fixed SendGrid proof emails (`createProof` / `transferProof`).
+Instead of a hardcoded template baked into the backend, **you author the template**
+(in the template editor) and **name it per action**. The copy, branding, channel,
+and merge fields are yours.
+
+---
+
+## The shape
+
+An action takes a `comms` object: a **role → `CommsTrigger`** map.
+
+```ts
+interface CommsTrigger {
+  templateId: string        // the template to render + send (you author it)
+  channel?: 'preferred' | 'email' | 'sms' | 'push' | 'wallet' | 'whatsapp'
+  props?: Record<string, any>   // merge data: a note, a message, custom fields
+  notify?: boolean          // false → do the action, send nothing for this role
+  appId?: string            // your app id, recorded in comms history
+}
+
+// role → trigger
+type CommsTriggerMap = Record<string, CommsTrigger>
+```
+
+Each action documents the **roles** it exposes (who can be messaged). You supply a
+trigger only for the roles you want to notify.
+
+---
+
+## What you control vs what the server owns
+
+You name a template and supply soft data. The server owns everything that decides
+**who** receives it and **what context** the template can see. A caller can never
+redirect a message to a contact of its choosing.
+
+| You supply (per role) | The server injects |
+|---|---|
+| `templateId` | which contact the role resolves to (recipient / sender / claimer / owner) |
+| `props` (note, message, custom) | `{{ proof }}`, `{{ product }}`, `{{ contact }}` hydration |
+| `channel`, `notify`, `appId` | the proof/product ids, the portal URL (`{{ proofUrl }}`) |
+
+Templates are rendered with **Liquid**, so a template body can read
+`{{ proof.values.owner.name }}`, `{{ product.title }}`, `{{ contact.firstName }}`,
+`{{ proofUrl }}`, and any `props` you passed (`{{ note }}`). See
+[Liquid Templates](./liquid-templates.md) and [Comms](./comms.md) for the template
+model and channel resolution.
+
+> This is a **1:1 transactional** send. It goes straight through the transactional
+> comms path — it does **not** touch the interactions → segments → broadcasts
+> (marketing/audience) pipeline. Recording a CRM interaction or awarding loyalty is
+> a separate, independent concern; don't route those through the comms trigger.
+
+---
+
+## Roles by action
+
+| Action | Roles | Fired when |
+|--------|-------|-----------|
+| `claim` / `claimProduct` | `claimer` | after the proof is committed to the ledger |
+| `transfer` (directed) | `recipient`, `sender` | on initiation |
+| `transfer` (`release: true`) | `owner` | on initiation |
+| `acceptTransfer` | `recipient` (new owner), `sender` (previous owner) | after the ownership move completes |
+| `cancelTransfer` | `owner` (canceller), `recipient` (earmarked, directed only) | after the transfer is cancelled |
+
+Timing is deliberate: comms fire **only after the durable write** (the ledger
+commit for a claim, the ownership move for an accept). A failed action sends
+nothing; a comms failure never breaks the action (best-effort).
+
+---
+
+## Examples
+
+Directed transfer — notify the buyer, confirm to the seller:
+
+```ts
+await proof.transfer(collectionId, productId, proofId, {
+  toEmail: 'buyer@example.com',
+  comms: {
+    recipient: { templateId: 'transfer-incoming', props: { note: 'Enjoy the watch!' } },
+    sender:    { templateId: 'transfer-sent' },
+  },
+})
+```
+
+Claim — confirm to the claimer:
+
+```ts
+await proof.claim(collectionId, productId, proofId, {
+  data: { purchaseStore: 'Regent St' },
+  comms: {
+    claimer: { templateId: 'welcome-owner', channel: 'preferred' },
+  },
+})
+```
+
+Accept — completion confirmation to both parties:
+
+```ts
+await proof.acceptTransfer(collectionId, productId, proofId, {
+  comms: {
+    recipient: { templateId: 'transfer-complete-owner' },
+    sender:    { templateId: 'transfer-complete-previous' },
+  },
+})
+```
+
+Suppress comms for one role while still messaging another:
+
+```ts
+comms: {
+  recipient: { templateId: 'transfer-incoming' },
+  sender:    { notify: false },   // do the transfer, don't email the seller
+}
+```
+
+Omit `comms` entirely and nothing is sent — comms are **opt-in**.
+
+---
+
+## Notes
+
+- **Email-only recipients work.** A directed transfer to a `toEmail` that isn't a
+  contact yet resolves/creates a contact before sending.
+- **SMS recipients work the same way.** A directed transfer to a `toPhone` (E.164)
+  resolves the recipient by phone and gives their contact a phone identity, so an
+  SMS-channel trigger (`channel: 'sms'`) reaches them. Because the phone maps to a
+  stable Firebase uid, they accept by logging in via SMS OTP — the accept is still
+  auth-gated exactly as with email.
+- **Consent + suppression apply.** Transactional sends still respect the contact's
+  channel consent and suppression list; a template's `topic` governs this.
+- **Delivery is logged** to comms history (with your `appId` and a `ref`), so sends
+  are auditable per contact.
+
+See also [Proof Ownership Transfer](./proof-ownership-transfer.md),
+[Proof Claiming Methods](./proof-claiming-methods.md), and [Comms](./comms.md).

package/dist/docs/proof-ownership-transfer.md

@@ -15,9 +15,20 @@ reserves states for them.
 
 | Mode | How | Who completes it |
 |------|-----|------------------|
-| **Directed** | Owner names a recipient (`toEmail` / `toUserId`). The proof is earmarked for them (`claimUserId`) and they're emailed a link. | The named recipient calls `acceptTransfer`. |
+| **Directed** | Owner names a recipient (`toEmail` / `toPhone` / `toUserId`). The proof is earmarked for them (`claimUserId`); you notify them with a comms trigger. | The named recipient calls `acceptTransfer`. |
 | **Open release** | Owner marks the proof `claimable`. | Anyone claims it via the normal claim flow. |
 
+A `toPhone` recipient (E.164) resolves to the **same user they log in as via SMS
+OTP** — Firebase keys the uid by phone number, so the earmark matches when they
+sign in. Pair it with an SMS comms trigger to notify them by text:
+
+```ts
+await proof.transfer(collectionId, productId, proofId, {
+  toPhone: '+14155551234',
+  comms: { recipient: { templateId: 'transfer-incoming', channel: 'sms' } },
+})
+```
+
 Only the current owner (or a collection admin) can start a transfer. A proof can
 have **one active transfer at a time**.
 
@@ -41,10 +52,14 @@ authoritative and atomic:
 ```ts
 import { proof } from '@proveanything/smartlinks'
 
-// Directed — hand it to a named buyer (they must accept)
+// Directed — hand it to a named buyer (they must accept). Notify each party with a
+// comms trigger naming a template you authored (see Comms Triggers below).
 const { transfer } = await proof.transfer(collectionId, productId, proofId, {
   toEmail: 'buyer@example.com',
-  message: 'Enjoy the watch!',
+  comms: {
+    recipient: { templateId: 'transfer-incoming', props: { note: 'Enjoy the watch!' } },
+    sender:    { templateId: 'transfer-sent' },
+  },
 })
 
 // …or an open release — anyone can now claim it
@@ -60,12 +75,18 @@ await proof.cancelTransfer(collectionId, productId, proofId)
 ## Recipient flow (directed)
 
 ```ts
-// Only the named recipient can accept — a third party is rejected.
-const { proof: mine } = await proof.acceptTransfer(collectionId, productId, proofId)
+// Only the named recipient can accept — a third party is rejected. Optionally
+// send completion comms to both parties.
+const { proof: mine } = await proof.acceptTransfer(collectionId, productId, proofId, {
+  comms: {
+    recipient: { templateId: 'transfer-complete-owner' },     // the new owner
+    sender:    { templateId: 'transfer-complete-previous' },  // the previous owner
+  },
+})
 ```
 
 The recipient sees the pending transfer on their account (a pending claim) and via
-the email link. Until they accept, the proof still belongs to the seller.
+the notification you sent. Until they accept, the proof still belongs to the seller.
 
 ---
 
@@ -101,14 +122,34 @@ the email link. Until they accept, the proof still belongs to the seller.
   added, are dispute-protected and never auto-transfer by default).
 - **Every state change is audited** as an append-only attestation on the proof.
 
+## Comms
+
+Every transfer action takes an optional `comms` map (role → comms trigger) that
+sends a transactional message once the action's write is durable. Roles:
+
+| Action | Roles |
+|--------|-------|
+| `transfer` (directed) | `recipient`, `sender` |
+| `transfer` (`release: true`) | `owner` |
+| `acceptTransfer` | `recipient` (new owner), `sender` (previous owner) |
+| `cancelTransfer` | `owner`, `recipient` (directed only) |
+
+You author each template; the server owns who each role resolves to and hydrates
+`{{ proof }}` / `{{ product }}` / `{{ contact }}` / `{{ proofUrl }}`. Pass
+`notify: false` on a role (or omit `comms`) to send nothing. Full detail:
+[Comms Triggers](./proof-comms-triggers.md).
+
 ## API
 
 | Method | Endpoint |
 |--------|----------|
 | `proof.transfer(c, p, id, opts)` | `POST …/proof/:id/transfer` |
-| `proof.acceptTransfer(c, p, id)` | `POST …/proof/:id/transfer/accept` |
-| `proof.cancelTransfer(c, p, id)` | `POST …/proof/:id/transfer/cancel` |
+| `proof.acceptTransfer(c, p, id, opts?)` | `POST …/proof/:id/transfer/accept` |
+| `proof.cancelTransfer(c, p, id, opts?)` | `POST …/proof/:id/transfer/cancel` |
 | `proof.getTransfer(c, p, id)` | `GET …/proof/:id/transfer` |
 
-See also [Proof Share Grants](./proof-share-grants.md) and
+`opts` on transfer/accept/cancel carries the `comms` map (and `notify`).
+
+See also [Comms Triggers](./proof-comms-triggers.md),
+[Proof Share Grants](./proof-share-grants.md) and
 [Proof Claiming Methods](./proof-claiming-methods.md).

package/dist/openapi.yaml

@@ -25717,6 +25717,14 @@ components:
           type: object
           additionalProperties:
             $ref: "#/components/schemas/JsonValue"
+    ProofClaimRequest:
+      type: object
+      properties:
+        data:
+          type: object
+          additionalProperties: true
+        comms:
+          $ref: "#/components/schemas/CommsTriggerMap"
     ProofFieldsConfig:
       type: object
       properties:
@@ -25844,11 +25852,38 @@ components:
         - state
         - createdAt
         - updatedAt
+    CommsTrigger:
+      type: object
+      properties:
+        templateId:
+          type: string
+        channel:
+          type: string
+          enum:
+            - preferred
+            - email
+            - sms
+            - push
+            - wallet
+            - whatsapp
+        props:
+          type: object
+          additionalProperties: true
+        notify:
+          type: boolean
+        appId:
+          type: string
+      required:
+        - templateId
     TransferProofOptions:
       type: object
       properties:
+        comms:
+          $ref: "#/components/schemas/CommsTriggerMap"
         toEmail:
           type: string
+        toPhone:
+          type: string
         toUserId:
           type: string
         toName:
@@ -25875,6 +25910,20 @@ components:
         - ok
         - mode
         - transfer
+    AcceptTransferOptions:
+      type: object
+      properties:
+        comms:
+          $ref: "#/components/schemas/CommsTriggerMap"
+        notify:
+          type: boolean
+    CancelTransferOptions:
+      type: object
+      properties:
+        comms:
+          $ref: "#/components/schemas/CommsTriggerMap"
+        notify:
+          type: boolean
     ProofTransferType:
       type: string
       enum:

package/dist/types/proof.d.ts

@@ -136,7 +136,20 @@ export interface ProofValuesUpdateRequest {
     /** The caller's own private slot, merged into `proof.values.personal[callerUid]`. */
     personal?: Record<string, JsonValue>;
 }
-export type ProofClaimRequest = Record<string, any>;
+/**
+ * Claim/mint payload. Remains open (server-side rules vary), but two keys are
+ * recognised across the claim endpoints:
+ * - `data`  — claim values written to the proof
+ * - `comms` — comms to send once the proof is committed to the ledger. Role:
+ *   `claimer` (the claiming user). See {@link CommsTrigger}.
+ */
+export interface ProofClaimRequest {
+    /** Claim values written to the proof. */
+    data?: Record<string, any>;
+    /** Comms to send on claim; role `claimer`. Fired only after the ledger write. */
+    comms?: CommsTriggerMap;
+    [key: string]: any;
+}
 /**
  * `'public'` (default, omitted) reads/writes `proof.values[key]`.
  * `'owner'` reads/writes `proof.values.owner[key]`.
@@ -238,23 +251,65 @@ export interface ProofTransfer {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * A comms trigger — the standard way to have an action send a transactional
+ * message as a side-effect of doing its work. You name a template (authored in
+ * the template editor) and optionally supply merge props; the server owns who
+ * receives it and injects the authoritative context ({{ proof }}, {{ product }},
+ * the target contact). This is a 1:1 transactional send — it does not touch the
+ * interactions → segments → broadcasts (marketing) pipeline.
+ */
+export interface CommsTrigger {
+    /** The comms template to render and send. */
+    templateId: string;
+    /** Delivery channel; defaults to the contact's preferred channel. */
+    channel?: 'preferred' | 'email' | 'sms' | 'push' | 'wallet' | 'whatsapp';
+    /** Freeform merge data for the template (note, message, custom fields). */
+    props?: Record<string, any>;
+    /** Set false to skip this message while still performing the action. */
+    notify?: boolean;
+    /** Owning app id, recorded in comms history. */
+    appId?: string;
+}
+/**
+ * A role → {@link CommsTrigger} map passed into an action. Each action documents
+ * the roles it exposes (e.g. a transfer exposes `recipient` and `sender`); only
+ * roles the action recognises are sent. The server decides which contact each
+ * role resolves to — the caller only names templates, never recipients.
+ */
+export type CommsTriggerMap = Record<string, CommsTrigger>;
 /**
  * Start a push transfer. Provide **one** of:
- * - `toEmail` / `toUserId` — a directed transfer to a named recipient (they accept).
+ * - `toEmail` / `toPhone` / `toUserId` — a directed transfer to a named recipient (they accept).
  * - `release: true`        — an open release (the proof becomes claimable by anyone).
  */
 export interface TransferProofOptions {
+    /**
+     * Comms to send. Roles: `recipient` (the named new owner) and `sender` (the
+     * initiator) for a directed transfer; `owner` for an open release. For an
+     * SMS recipient, set `comms.recipient.channel = 'sms'`.
+     */
+    comms?: CommsTriggerMap;
     /** Directed: recipient email (created/looked up if needed). */
     toEmail?: string;
+    /**
+     * Directed: recipient phone in E.164 (e.g. `+14155551234`). Resolves to the same
+     * user they log in as via SMS OTP (created if needed). Pair with an SMS comms
+     * trigger to notify them: `comms.recipient.channel = 'sms'`.
+     */
+    toPhone?: string;
     /** Directed: recipient user id, if already known. */
     toUserId?: string;
     /** Directed: display name for a newly-created recipient. */
     toName?: string;
     /** Open release: mark the proof claimable instead of directing it. */
     release?: boolean;
-    /** Optional note included in the recipient email. */
+    /**
+     * @deprecated The legacy fixed transfer email is gone. Put a note in a comms
+     * trigger's props instead, e.g. `comms.recipient.props.note`.
+     */
     message?: string;
-    /** Set `false` to skip the recipient notification email (directed only). */
+    /** Set `false` to skip ALL comms for this action (per-role: `comms.<role>.notify`). */
     notify?: boolean;
 }
 /** Result of initiating a push transfer. */
@@ -263,3 +318,22 @@ export interface TransferProofResult {
     mode: 'directed' | 'open_release';
     transfer: ProofTransfer;
 }
+/**
+ * Options for accepting a directed transfer. Comms roles: `recipient` (the
+ * accepting new owner) and `sender` (the previous owner) — the completion
+ * confirmation for each party.
+ */
+export interface AcceptTransferOptions {
+    comms?: CommsTriggerMap;
+    /** Set false to skip all completion comms. */
+    notify?: boolean;
+}
+/**
+ * Options for cancelling a pending transfer. Comms roles: `owner` (the canceller)
+ * and, for a directed transfer, `recipient` (whose earmarked transfer is withdrawn).
+ */
+export interface CancelTransferOptions {
+    comms?: CommsTriggerMap;
+    /** Set false to skip all cancellation comms. */
+    notify?: boolean;
+}

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.16.3  |  Generated: 2026-09-05T10:57:07.719Z
+Version: 1.16.5  |  Generated: 2026-09-05T15:46:49.017Z
 
 This is a concise summary of all available API functions and types.
 
@@ -35,6 +35,7 @@ For detailed guides on specific features:
 - **[Proof Claiming Methods](proof-claiming-methods.md)** - All methods for claiming/registering product ownership (NFC tags, serial numbers, auto-generated claims)
 - **[Proof Share Grants](proof-share-grants.md)** - Delegated, scoped, revocable bearer access to a single proof (read/comment/verify-owner links)
 - **[Proof Ownership Transfer](proof-ownership-transfer.md)** - Moving a proof to a new owner: directed transfer, open release, accept/cancel, and the state machine
+- **[Comms Triggers](proof-comms-triggers.md)** - Sending transactional comms from proof actions (claim/transfer/accept/cancel): the role→template map, per-action roles, and the trust boundary
 - **[Lots](lots.md)** - Collection-scoped production groupings spanning many SKUs; facet/product selectors, member resolution, and GS1 AI(10) batch-then-lot resolution
 - **[Item Context](item-context.md)** - The `itemContext` container prop derived from a serial-proof URL or NFC tap (what item the URL points at)
 - **[Product Facets SDK](PRODUCT_FACETS_SDK.md)** - Admin and public product facet endpoints and TypeScript interfaces
@@ -7508,6 +7509,15 @@ interface ProofValuesUpdateRequest {
 }
 ```
 
+**ProofClaimRequest** (interface)
+```typescript
+interface ProofClaimRequest {
+  data?: Record<string, any>
+  comms?: CommsTriggerMap
+  [key: string]: any
+}
+```
+
 **ProofFieldsConfig** (interface)
 ```typescript
 interface ProofFieldsConfig {
@@ -7580,13 +7590,34 @@ interface ProofTransfer {
 }
 ```
 
+**CommsTrigger** (interface)
+```typescript
+interface CommsTrigger {
+  templateId: string
+  channel?: 'preferred' | 'email' | 'sms' | 'push' | 'wallet' | 'whatsapp'
+  props?: Record<string, any>
+  notify?: boolean
+  appId?: string
+}
+```
+
 **TransferProofOptions** (interface)
 ```typescript
 interface TransferProofOptions {
+  * Comms to send. Roles: `recipient` (the named new owner) and `sender` (the
+  * initiator) for a directed transfer; `owner` for an open release. For an
+  * SMS recipient, set `comms.recipient.channel = 'sms'`.
+  comms?: CommsTriggerMap
   toEmail?: string
+  * Directed: recipient phone in E.164 (e.g. `+14155551234`). Resolves to the same
+  * user they log in as via SMS OTP (created if needed). Pair with an SMS comms
+  * trigger to notify them: `comms.recipient.channel = 'sms'`.
+  toPhone?: string
   toUserId?: string
   toName?: string
   release?: boolean
+  * @deprecated The legacy fixed transfer email is gone. Put a note in a comms
+  * trigger's props instead, e.g. `comms.recipient.props.note`.
   message?: string
   notify?: boolean
 }
@@ -7601,12 +7632,26 @@ interface TransferProofResult {
 }
 ```
 
+**AcceptTransferOptions** (interface)
+```typescript
+interface AcceptTransferOptions {
+  comms?: CommsTriggerMap
+  notify?: boolean
+}
+```
+
+**CancelTransferOptions** (interface)
+```typescript
+interface CancelTransferOptions {
+  comms?: CommsTriggerMap
+  notify?: boolean
+}
+```
+
 **ProofResponse** = `Proof`
 
 **ProofUpdateRequest** = `Partial<ProofWrite> & { proof?: ProofWrite }`
 
-**ProofClaimRequest** = `Record<string, any>`
-
 **ProofFieldScope** = `'public' | 'owner' | 'personal' | 'admin'`
 
 **ProofFieldDef** = `ScopedFieldDef & { scope?: ProofFieldScope }`
@@ -7619,6 +7664,8 @@ interface TransferProofResult {
 
 **ProofTransferState** = ``
 
+**CommsTriggerMap** = `Record<string, CommsTrigger>`
+
 ### qr
 
 **QrShortCodeLookupResponse** (interface)
@@ -10428,16 +10475,18 @@ Redeem a grant token (anonymous or signed-in). Records the redemption and return
     productId: string,
     proofId: string,
     options: TransferProofOptions) → `Promise<TransferProofResult>`
-Start a push transfer of a proof (current owner / collection admin only). Directed — hand it to a named recipient who then calls {@link acceptTransfer}: ```ts await proof.transfer(collectionId, productId, proofId, { toEmail: 'buyer@example.com' }) ``` Open release — make the proof claimable by anyone: ```ts await proof.transfer(collectionId, productId, proofId, { release: true }) ```
+Start a push transfer of a proof (current owner / collection admin only). Directed — hand it to a named recipient who then calls {@link acceptTransfer}: ```ts await proof.transfer(collectionId, productId, proofId, { toEmail: 'buyer@example.com' }) ``` Open release — make the proof claimable by anyone: ```ts await proof.transfer(collectionId, productId, proofId, { release: true }) ``` Send comms by naming templates per role (server decides who receives each): ```ts await proof.transfer(collectionId, productId, proofId, { toEmail: 'buyer@example.com', comms: { recipient: { templateId: 'transfer-incoming', props: { note: 'Enjoy!' } }, sender:    { templateId: 'transfer-sent' }, }, }) ``` Direct to an SMS recipient by phone (E.164) and notify them by text: ```ts await proof.transfer(collectionId, productId, proofId, { toPhone: '+14155551234', comms: { recipient: { templateId: 'transfer-incoming', channel: 'sms' } }, }) ```
 
 **acceptTransfer**(collectionId: string,
     productId: string,
-    proofId: string) → `Promise<`
+    proofId: string,
+    options: AcceptTransferOptions = {}) → `Promise<`
 Accept a directed transfer (the named recipient only). Completes the ownership move — the proof's `userId` becomes the caller and the previous owner's private data and share grants are cleared/voided.
 
 **cancelTransfer**(collectionId: string,
     productId: string,
-    proofId: string) → `Promise<`
+    proofId: string,
+    options: CancelTransferOptions = {}) → `Promise<`
 Cancel a pending push transfer (current owner / collection admin only).
 
 **getTransfer**(collectionId: string,

package/docs/proof-claiming-methods.md

@@ -289,6 +289,22 @@ try {
 
 ---
 
+## Sending a claim confirmation
+
+Claims can send a transactional confirmation once the proof is committed to the
+ledger. Pass a `comms` map (role `claimer`) alongside `data` — you author the
+template, the server hydrates `{{ proof }}` / `{{ product }}` / `{{ contact }}`:
+
+```ts
+await proof.claim(collectionId, productId, proofId, {
+  data: { store: 'Regent St' },
+  comms: { claimer: { templateId: 'welcome-owner', channel: 'preferred' } },
+})
+```
+
+Omit `comms` and nothing is sent (opt-in). Full detail:
+[Comms Triggers](./proof-comms-triggers.md).
+
 ## API Reference
 
 ### `proof.claim(collectionId, productId, proofId, data?)`

package/docs/proof-comms-triggers.md

@@ -0,0 +1,142 @@
+# Comms Triggers
+
+The standard way to send a **transactional message** as a side-effect of a proof
+action — a claim confirmation, a "you've received a transfer" email, a
+cancellation notice. You pass a **comms trigger** into the action; the server
+sends it once the action's write is durable.
+
+This replaces the old fixed SendGrid proof emails (`createProof` / `transferProof`).
+Instead of a hardcoded template baked into the backend, **you author the template**
+(in the template editor) and **name it per action**. The copy, branding, channel,
+and merge fields are yours.
+
+---
+
+## The shape
+
+An action takes a `comms` object: a **role → `CommsTrigger`** map.
+
+```ts
+interface CommsTrigger {
+  templateId: string        // the template to render + send (you author it)
+  channel?: 'preferred' | 'email' | 'sms' | 'push' | 'wallet' | 'whatsapp'
+  props?: Record<string, any>   // merge data: a note, a message, custom fields
+  notify?: boolean          // false → do the action, send nothing for this role
+  appId?: string            // your app id, recorded in comms history
+}
+
+// role → trigger
+type CommsTriggerMap = Record<string, CommsTrigger>
+```
+
+Each action documents the **roles** it exposes (who can be messaged). You supply a
+trigger only for the roles you want to notify.
+
+---
+
+## What you control vs what the server owns
+
+You name a template and supply soft data. The server owns everything that decides
+**who** receives it and **what context** the template can see. A caller can never
+redirect a message to a contact of its choosing.
+
+| You supply (per role) | The server injects |
+|---|---|
+| `templateId` | which contact the role resolves to (recipient / sender / claimer / owner) |
+| `props` (note, message, custom) | `{{ proof }}`, `{{ product }}`, `{{ contact }}` hydration |
+| `channel`, `notify`, `appId` | the proof/product ids, the portal URL (`{{ proofUrl }}`) |
+
+Templates are rendered with **Liquid**, so a template body can read
+`{{ proof.values.owner.name }}`, `{{ product.title }}`, `{{ contact.firstName }}`,
+`{{ proofUrl }}`, and any `props` you passed (`{{ note }}`). See
+[Liquid Templates](./liquid-templates.md) and [Comms](./comms.md) for the template
+model and channel resolution.
+
+> This is a **1:1 transactional** send. It goes straight through the transactional
+> comms path — it does **not** touch the interactions → segments → broadcasts
+> (marketing/audience) pipeline. Recording a CRM interaction or awarding loyalty is
+> a separate, independent concern; don't route those through the comms trigger.
+
+---
+
+## Roles by action
+
+| Action | Roles | Fired when |
+|--------|-------|-----------|
+| `claim` / `claimProduct` | `claimer` | after the proof is committed to the ledger |
+| `transfer` (directed) | `recipient`, `sender` | on initiation |
+| `transfer` (`release: true`) | `owner` | on initiation |
+| `acceptTransfer` | `recipient` (new owner), `sender` (previous owner) | after the ownership move completes |
+| `cancelTransfer` | `owner` (canceller), `recipient` (earmarked, directed only) | after the transfer is cancelled |
+
+Timing is deliberate: comms fire **only after the durable write** (the ledger
+commit for a claim, the ownership move for an accept). A failed action sends
+nothing; a comms failure never breaks the action (best-effort).
+
+---
+
+## Examples
+
+Directed transfer — notify the buyer, confirm to the seller:
+
+```ts
+await proof.transfer(collectionId, productId, proofId, {
+  toEmail: 'buyer@example.com',
+  comms: {
+    recipient: { templateId: 'transfer-incoming', props: { note: 'Enjoy the watch!' } },
+    sender:    { templateId: 'transfer-sent' },
+  },
+})
+```
+
+Claim — confirm to the claimer:
+
+```ts
+await proof.claim(collectionId, productId, proofId, {
+  data: { purchaseStore: 'Regent St' },
+  comms: {
+    claimer: { templateId: 'welcome-owner', channel: 'preferred' },
+  },
+})
+```
+
+Accept — completion confirmation to both parties:
+
+```ts
+await proof.acceptTransfer(collectionId, productId, proofId, {
+  comms: {
+    recipient: { templateId: 'transfer-complete-owner' },
+    sender:    { templateId: 'transfer-complete-previous' },
+  },
+})
+```
+
+Suppress comms for one role while still messaging another:
+
+```ts
+comms: {
+  recipient: { templateId: 'transfer-incoming' },
+  sender:    { notify: false },   // do the transfer, don't email the seller
+}
+```
+
+Omit `comms` entirely and nothing is sent — comms are **opt-in**.
+
+---
+
+## Notes
+
+- **Email-only recipients work.** A directed transfer to a `toEmail` that isn't a
+  contact yet resolves/creates a contact before sending.
+- **SMS recipients work the same way.** A directed transfer to a `toPhone` (E.164)
+  resolves the recipient by phone and gives their contact a phone identity, so an
+  SMS-channel trigger (`channel: 'sms'`) reaches them. Because the phone maps to a
+  stable Firebase uid, they accept by logging in via SMS OTP — the accept is still
+  auth-gated exactly as with email.
+- **Consent + suppression apply.** Transactional sends still respect the contact's
+  channel consent and suppression list; a template's `topic` governs this.
+- **Delivery is logged** to comms history (with your `appId` and a `ref`), so sends
+  are auditable per contact.
+
+See also [Proof Ownership Transfer](./proof-ownership-transfer.md),
+[Proof Claiming Methods](./proof-claiming-methods.md), and [Comms](./comms.md).

package/docs/proof-ownership-transfer.md

@@ -15,9 +15,20 @@ reserves states for them.
 
 | Mode | How | Who completes it |
 |------|-----|------------------|
-| **Directed** | Owner names a recipient (`toEmail` / `toUserId`). The proof is earmarked for them (`claimUserId`) and they're emailed a link. | The named recipient calls `acceptTransfer`. |
+| **Directed** | Owner names a recipient (`toEmail` / `toPhone` / `toUserId`). The proof is earmarked for them (`claimUserId`); you notify them with a comms trigger. | The named recipient calls `acceptTransfer`. |
 | **Open release** | Owner marks the proof `claimable`. | Anyone claims it via the normal claim flow. |
 
+A `toPhone` recipient (E.164) resolves to the **same user they log in as via SMS
+OTP** — Firebase keys the uid by phone number, so the earmark matches when they
+sign in. Pair it with an SMS comms trigger to notify them by text:
+
+```ts
+await proof.transfer(collectionId, productId, proofId, {
+  toPhone: '+14155551234',
+  comms: { recipient: { templateId: 'transfer-incoming', channel: 'sms' } },
+})
+```
+
 Only the current owner (or a collection admin) can start a transfer. A proof can
 have **one active transfer at a time**.
 
@@ -41,10 +52,14 @@ authoritative and atomic:
 ```ts
 import { proof } from '@proveanything/smartlinks'
 
-// Directed — hand it to a named buyer (they must accept)
+// Directed — hand it to a named buyer (they must accept). Notify each party with a
+// comms trigger naming a template you authored (see Comms Triggers below).
 const { transfer } = await proof.transfer(collectionId, productId, proofId, {
   toEmail: 'buyer@example.com',
-  message: 'Enjoy the watch!',
+  comms: {
+    recipient: { templateId: 'transfer-incoming', props: { note: 'Enjoy the watch!' } },
+    sender:    { templateId: 'transfer-sent' },
+  },
 })
 
 // …or an open release — anyone can now claim it
@@ -60,12 +75,18 @@ await proof.cancelTransfer(collectionId, productId, proofId)
 ## Recipient flow (directed)
 
 ```ts
-// Only the named recipient can accept — a third party is rejected.
-const { proof: mine } = await proof.acceptTransfer(collectionId, productId, proofId)
+// Only the named recipient can accept — a third party is rejected. Optionally
+// send completion comms to both parties.
+const { proof: mine } = await proof.acceptTransfer(collectionId, productId, proofId, {
+  comms: {
+    recipient: { templateId: 'transfer-complete-owner' },     // the new owner
+    sender:    { templateId: 'transfer-complete-previous' },  // the previous owner
+  },
+})
 ```
 
 The recipient sees the pending transfer on their account (a pending claim) and via
-the email link. Until they accept, the proof still belongs to the seller.
+the notification you sent. Until they accept, the proof still belongs to the seller.
 
 ---
 
@@ -101,14 +122,34 @@ the email link. Until they accept, the proof still belongs to the seller.
   added, are dispute-protected and never auto-transfer by default).
 - **Every state change is audited** as an append-only attestation on the proof.
 
+## Comms
+
+Every transfer action takes an optional `comms` map (role → comms trigger) that
+sends a transactional message once the action's write is durable. Roles:
+
+| Action | Roles |
+|--------|-------|
+| `transfer` (directed) | `recipient`, `sender` |
+| `transfer` (`release: true`) | `owner` |
+| `acceptTransfer` | `recipient` (new owner), `sender` (previous owner) |
+| `cancelTransfer` | `owner`, `recipient` (directed only) |
+
+You author each template; the server owns who each role resolves to and hydrates
+`{{ proof }}` / `{{ product }}` / `{{ contact }}` / `{{ proofUrl }}`. Pass
+`notify: false` on a role (or omit `comms`) to send nothing. Full detail:
+[Comms Triggers](./proof-comms-triggers.md).
+
 ## API
 
 | Method | Endpoint |
 |--------|----------|
 | `proof.transfer(c, p, id, opts)` | `POST …/proof/:id/transfer` |
-| `proof.acceptTransfer(c, p, id)` | `POST …/proof/:id/transfer/accept` |
-| `proof.cancelTransfer(c, p, id)` | `POST …/proof/:id/transfer/cancel` |
+| `proof.acceptTransfer(c, p, id, opts?)` | `POST …/proof/:id/transfer/accept` |
+| `proof.cancelTransfer(c, p, id, opts?)` | `POST …/proof/:id/transfer/cancel` |
 | `proof.getTransfer(c, p, id)` | `GET …/proof/:id/transfer` |
 
-See also [Proof Share Grants](./proof-share-grants.md) and
+`opts` on transfer/accept/cancel carries the `comms` map (and `notify`).
+
+See also [Comms Triggers](./proof-comms-triggers.md),
+[Proof Share Grants](./proof-share-grants.md) and
 [Proof Claiming Methods](./proof-claiming-methods.md).

package/openapi.yaml

@@ -25717,6 +25717,14 @@ components:
           type: object
           additionalProperties:
             $ref: "#/components/schemas/JsonValue"
+    ProofClaimRequest:
+      type: object
+      properties:
+        data:
+          type: object
+          additionalProperties: true
+        comms:
+          $ref: "#/components/schemas/CommsTriggerMap"
     ProofFieldsConfig:
       type: object
       properties:
@@ -25844,11 +25852,38 @@ components:
         - state
         - createdAt
         - updatedAt
+    CommsTrigger:
+      type: object
+      properties:
+        templateId:
+          type: string
+        channel:
+          type: string
+          enum:
+            - preferred
+            - email
+            - sms
+            - push
+            - wallet
+            - whatsapp
+        props:
+          type: object
+          additionalProperties: true
+        notify:
+          type: boolean
+        appId:
+          type: string
+      required:
+        - templateId
     TransferProofOptions:
       type: object
       properties:
+        comms:
+          $ref: "#/components/schemas/CommsTriggerMap"
         toEmail:
           type: string
+        toPhone:
+          type: string
         toUserId:
           type: string
         toName:
@@ -25875,6 +25910,20 @@ components:
         - ok
         - mode
         - transfer
+    AcceptTransferOptions:
+      type: object
+      properties:
+        comms:
+          $ref: "#/components/schemas/CommsTriggerMap"
+        notify:
+          type: boolean
+    CancelTransferOptions:
+      type: object
+      properties:
+        comms:
+          $ref: "#/components/schemas/CommsTriggerMap"
+        notify:
+          type: boolean
     ProofTransferType:
       type: string
       enum:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.16.3",
+  "version": "1.16.5",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",