@proveanything/smartlinks 1.9.16 → 1.9.19

package/dist/types/appObjects.d.ts

@@ -369,23 +369,116 @@ export interface RelatedResponse {
     records: AppRecord[];
 }
 /**
- * Public create policy configuration
+ * Top-level public-create policy stored under the `publicCreate` key of an
+ * app config document.  Controls which caller types may create objects on
+ * **public** App Objects endpoints.
+ *
+ * Set via `POST /api/v1/admin/collection/:collectionId/apps/:appId` with the
+ * policy as the request body (merged over any existing config).
+ *
+ * The server reads this document at request time — no cache invalidation or
+ * service restart is required after changing it.
  */
 export interface PublicCreatePolicy {
-    cases?: PublicCreateRule;
-    threads?: PublicCreateRule;
-    records?: PublicCreateRule;
+    cases?: PublicCreateObjectRule;
+    threads?: PublicCreateObjectRule;
+    records?: PublicCreateObjectRule;
 }
 /**
- * Rule for public create operations
+ * Per-object-type rule within a {@link PublicCreatePolicy}.
+ * Each caller class (`anonymous`, `authenticated`) has its own independent
+ * branch so you can apply different enforcement for each.
  */
-export interface PublicCreateRule {
-    allow: {
-        anonymous?: boolean;
-        authenticated?: boolean;
-    };
+export interface PublicCreateObjectRule {
+    /** Rules for unauthenticated (anonymous) callers */
+    anonymous?: PublicCreateBranch;
+    /** Rules for authenticated (signed-in contact) callers */
+    authenticated?: PublicCreateBranch;
+}
+/**
+ * Policy branch for a single caller class.
+ *
+ * ### Visibility enforcement guard-rails
+ *
+ * The server silently corrects misconfigured visibility values:
+ *
+ * | Caller type     | `enforce.visibility` supplied | Server overrides to  |
+ * |-----------------|-------------------------------|----------------------|
+ * | `anonymous`     | `'owner'`                     | `'admin'`            |
+ * | `authenticated` | `'public'`                    | `'owner'`            |
+ *
+ * These guards exist because anonymous callers have no identity to own a
+ * record, and `'public'` visibility for authenticated-only objects would be
+ * a misconfiguration.
+ */
+export interface PublicCreateBranch {
+    /** Whether creation is permitted for this caller class */
+    allow: boolean;
+    /**
+     * Field values merged **over** the caller's request body before writing.
+     * Use this to lock down `visibility` and `status` regardless of what the
+     * client sends.
+     */
     enforce?: {
-        anonymous?: Partial<CreateCaseInput | CreateThreadInput | CreateRecordInput>;
-        authenticated?: Partial<CreateCaseInput | CreateThreadInput | CreateRecordInput>;
+        visibility?: 'public' | 'owner' | 'admin';
+        status?: string;
+    };
+    /**
+     * Anonymous edit-token configuration.
+     * **Records only** — ignored for cases and threads.
+     *
+     * When `editToken: true`, the server generates a one-time 256-bit hex token
+     * on anonymous record creation, stores it in `admin.editToken` (never
+     * exposed to public / owner responses), and returns it **once** in the
+     * creation response under the `editToken` key.
+     *
+     * The client can then pass that token as the `X-Edit-Token` header on
+     * `PATCH /records/:recordId` to amend the `data` zone without
+     * authentication.
+     *
+     * @see {@link CreateRecordResponse} — creation response shape
+     * @see {@link records.updateWithToken} — SDK method for the amendment call
+     */
+    edit?: {
+        /** Enable edit-token generation on anonymous record creation */
+        editToken: boolean;
+        /**
+         * Optional expiry window in minutes from `createdAt`.
+         * After this many minutes the token is rejected with HTTP 403
+         * `EDIT_WINDOW_EXPIRED`.  Omit for no expiry.
+         */
+        windowMinutes?: number;
     };
 }
+/**
+ * Response from `app.records.create()` when the caller is anonymous and the
+ * app's `publicCreate.records.anonymous.edit.editToken` policy is `true`.
+ *
+ * The `editToken` field is present **only on the creation response** — it is
+ * stored in the record's `admin` zone and never returned again.  Store it
+ * client-side immediately.
+ *
+ * Use `app.records.updateWithToken()` to amend the record's `data` zone with
+ * this token.
+ *
+ * @example
+ * ```ts
+ * const response = await app.records.create(collectionId, appId, {
+ *   recordType: 'payment',
+ *   visibility: 'public',
+ *   data: { amount: 9900, currency: 'USD' },
+ * })
+ * // response.editToken is present when the policy has editToken: true
+ * const editToken = response.editToken
+ * ```
+ */
+export interface CreateRecordResponse extends AppRecord {
+    /**
+     * Short-lived edit token.  Present only when:
+     * 1. The caller is anonymous, AND
+     * 2. The app policy has `publicCreate.records.anonymous.edit.editToken: true`
+     *
+     * This value is returned **once** and cannot be retrieved again.
+     */
+    editToken?: string;
+}

package/dist/types/index.d.ts

@@ -34,3 +34,4 @@ export * from "./appObjects";
 export * from "./loyalty";
 export * from "./translations";
 export * from "./config";
+export * from "./widgets";

package/dist/types/index.js

@@ -36,3 +36,4 @@ export * from "./appObjects";
 export * from "./loyalty";
 export * from "./translations";
 export * from "./config";
+export * from "./widgets";

package/dist/types/widgets.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Structured navigation request emitted via the `onNavigate` prop when a
+ * widget or container needs to navigate the parent platform shell to another
+ * app or to a specific deep-link within an app.
+ *
+ * The portal orchestrator receives this object and performs the navigation
+ * while preserving hierarchy context (`collectionId`, `productId`, etc.).
+ *
+ * Legacy callers may still pass a plain string path; the `onNavigate`
+ * signature accepts both.  New widgets and containers should always use the
+ * structured form.
+ */
+export interface NavigationRequest {
+    /** Target app ID to activate */
+    appId: string;
+    /** Deep link / page within the target app (forwarded as `pageId`) */
+    deepLink?: string;
+    /** Extra URL params forwarded to the target app */
+    params?: Record<string, string>;
+    /** Optionally switch to a specific product before showing the app */
+    productId?: string;
+    /** Optionally switch to a specific proof before showing the app */
+    proofId?: string;
+}
+/**
+ * Standard props received by every SmartLinks widget and container.
+ *
+ * These are passed by the parent platform (portal shell, OrchestratedPortal,
+ * or a custom host) when mounting a widget or container component.
+ *
+ * **`SL` type note:** at runtime `SL` is the fully-initialised
+ * `@proveanything/smartlinks` SDK instance.  It is typed as
+ * `Record<string, unknown>` here to avoid a circular self-import; cast to
+ * a more specific type in your app code if needed.
+ */
+export interface SmartLinksWidgetProps {
+    /** Collection context — required */
+    collectionId: string;
+    /** App identifier — required */
+    appId: string;
+    /** Product context — present when the portal is scoped to a product */
+    productId?: string;
+    /** Proof (scan/instance) context */
+    proofId?: string;
+    /** Authenticated user info, if the viewer is logged in */
+    user?: {
+        id?: string;
+        email?: string;
+        name?: string;
+        admin?: boolean;
+    };
+    /**
+     * Pre-initialised SmartLinks SDK instance provided by the parent platform.
+     * At runtime this is `typeof import('@proveanything/smartlinks')`.
+     */
+    SL: Record<string, unknown>;
+    /**
+     * Navigation callback.  Emit a `NavigationRequest` to ask the parent
+     * platform to navigate to another app.  A legacy plain-string path is also
+     * accepted for backward compatibility.
+     */
+    onNavigate?: (request: NavigationRequest | string) => void;
+    /** Base URL of the full public portal, used for constructing deep links */
+    publicPortalUrl?: string;
+    /** Responsive size hint */
+    size?: 'compact' | 'standard' | 'large';
+    /** BCP-47 language code (e.g. `'en'`, `'fr'`) */
+    lang?: string;
+    /** Translation key overrides */
+    translations?: Record<string, string>;
+}

package/dist/types/widgets.js

@@ -0,0 +1,2 @@
+// src/types/widgets.ts
+export {};

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.16  |  Generated: 2026-04-13T17:25:57.673Z
+Version: 1.9.19  |  Generated: 2026-04-16T12:41:11.180Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1957,22 +1957,51 @@ interface RelatedResponse {
 **PublicCreatePolicy** (interface)
 ```typescript
 interface PublicCreatePolicy {
-  cases?: PublicCreateRule
-  threads?: PublicCreateRule
-  records?: PublicCreateRule
+  cases?:   PublicCreateObjectRule
+  threads?: PublicCreateObjectRule
+  records?: PublicCreateObjectRule
 }
 ```
 
-**PublicCreateRule** (interface)
+**PublicCreateObjectRule** (interface)
 ```typescript
-interface PublicCreateRule {
-  allow: {
-  anonymous?: boolean
-  authenticated?: boolean
-  }
+interface PublicCreateObjectRule {
+  anonymous?:     PublicCreateBranch
+  authenticated?: PublicCreateBranch
+}
+```
+
+**PublicCreateBranch** (interface)
+```typescript
+interface PublicCreateBranch {
+  allow: boolean
+  * Field values merged **over** the caller's request body before writing.
+  * Use this to lock down `visibility` and `status` regardless of what the
+  * client sends.
   enforce?: {
-  anonymous?: Partial<CreateCaseInput | CreateThreadInput | CreateRecordInput>
-  authenticated?: Partial<CreateCaseInput | CreateThreadInput | CreateRecordInput>
+  visibility?: 'public' | 'owner' | 'admin'
+  status?:     string
+  }
+  * Anonymous edit-token configuration.
+  * **Records only** — ignored for cases and threads.
+  *
+  * When `editToken: true`, the server generates a one-time 256-bit hex token
+  * on anonymous record creation, stores it in `admin.editToken` (never
+  * exposed to public / owner responses), and returns it **once** in the
+  * creation response under the `editToken` key.
+  *
+  * The client can then pass that token as the `X-Edit-Token` header on
+  * `PATCH /records/:recordId` to amend the `data` zone without
+  * authentication.
+  *
+  * @see {@link CreateRecordResponse} — creation response shape
+  * @see {@link records.updateWithToken} — SDK method for the amendment call
+  edit?: {
+  editToken: boolean
+  * Optional expiry window in minutes from `createdAt`.
+  * After this many minutes the token is rejected with HTTP 403
+  * `EDIT_WINDOW_EXPIRED`.  Omit for no expiry.
+  windowMinutes?: number
   }
 }
 ```
@@ -6654,6 +6683,46 @@ interface TranslationUpdateRequest {
 
 **VariantUpdateRequest** = `any`
 
+### widgets
+
+**NavigationRequest** (interface)
+```typescript
+interface NavigationRequest {
+  appId: string
+  deepLink?: string
+  params?: Record<string, string>
+  productId?: string
+  proofId?: string
+}
+```
+
+**SmartLinksWidgetProps** (interface)
+```typescript
+interface SmartLinksWidgetProps {
+  collectionId: string
+  appId: string
+  productId?: string
+  proofId?: string
+  user?: {
+  id?: string
+  email?: string
+  name?: string
+  admin?: boolean
+  }
+  * Pre-initialised SmartLinks SDK instance provided by the parent platform.
+  * At runtime this is `typeof import('@proveanything/smartlinks')`.
+  SL: Record<string, unknown>
+  * Navigation callback.  Emit a `NavigationRequest` to ask the parent
+  * platform to navigate to another app.  A legacy plain-string path is also
+  * accepted for backward compatibility.
+  onNavigate?: (request: NavigationRequest | string) => void
+  publicPortalUrl?: string
+  size?: 'compact' | 'standard' | 'large'
+  lang?: string
+  translations?: Record<string, string>
+}
+```
+
 ### appConfiguration (api)
 
 **AppConfigOptions** (type)
@@ -7024,8 +7093,8 @@ General-purpose structured app objects. Use these when a simple scoped data item
 **create**(collectionId: string,
     appId: string,
     input: CreateRecordInput,
-    admin: boolean = false) → `Promise<AppRecord>`
-Create a new record POST /records
+    admin: boolean = false) → `Promise<CreateRecordResponse>`
+Create a new record POST /records When called on the public endpoint (admin = false) with an anonymous caller, and the app's `publicCreate.records.anonymous.edit.editToken` policy is enabled, the response includes a one-time `editToken` string. Store it immediately — it is never returned again.
 
 **list**(collectionId: string,
     appId: string,
@@ -7046,6 +7115,13 @@ Get a single record by ID GET /records/:recordId
     admin: boolean = false) → `Promise<AppRecord>`
 Update a record PATCH /records/:recordId Admin can update any field, public (owner) can only update data and owner
 
+**updateWithToken**(collectionId: string,
+    appId: string,
+    recordId: string,
+    data: Record<string, unknown>,
+    editToken: string) → `Promise<AppRecord>`
+Amend the `data` zone of a record using an anonymous edit token. PATCH /records/:recordId  (public endpoint, no auth) This is the follow-up call after an anonymous `create()` that returned an `editToken`.  Present the token via `X-Edit-Token` — the server validates it with a constant-time comparison and, if `windowMinutes` is configured in the policy, checks that the token has not expired. **Scope:** only the `data` zone may be modified via this path. `owner`, `admin`, `status`, `visibility`, and indexed fields are immutable to anonymous token holders. ```ts const record = await app.records.create(collectionId, appId, { recordType: 'payment', visibility: 'public', data: { amount: 9900, currency: 'USD' }, }) const { editToken } = record  // store this immediately! // Later, once the payment gateway confirms: const updated = await app.records.updateWithToken( collectionId, appId, record.id, { amount: 9900, currency: 'USD', transactionId: 'txn_abc123' }, editToken, ) ``` ### Error codes | HTTP | `errorCode`           | Meaning                                           | |------|-----------------------|---------------------------------------------------| | 401  | `UNAUTHORIZED`        | No auth token and no `X-Edit-Token` header        | | 403  | `FORBIDDEN`           | Policy not enabled, or token does not match       | | 403  | `EDIT_WINDOW_EXPIRED` | `windowMinutes` elapsed since record creation     | | 404  | `NOT_FOUND`           | Record does not exist                             |
+
 **remove**(collectionId: string,
     appId: string,
     recordId: string,

package/docs/app-objects.md

@@ -576,47 +576,81 @@ const usageStats = await app.records.aggregate(collectionId, appId, {
 
 ## Public Create Policies
 
-Control who can create objects on **public endpoints** by setting a `publicCreate` policy on your app's config. This is a `publicCreate` field inside your app config object (identified by `appId` within your collection).
+Control who can create objects on **public endpoints** by setting a `publicCreate` policy on your app's config document (identified by `appId` within your collection).
+
+Set the policy via:
+```
+POST /api/v1/admin/collection/:collectionId/apps/:appId
+```
+
+The server reads this document at request time — no cache invalidation or service restart is required.
 
 ### Policy Structure
 
+Each object type (`cases`, `threads`, `records`) has **independent branches** for anonymous and authenticated callers. Each branch carries its own `allow` flag, optional field overrides (`enforce`), and — for records — optional edit-token config (`edit`).
+
 ```typescript
 interface PublicCreatePolicy {
-  cases?: {
-    allow: {
-      anonymous?: boolean      // allow unauthenticated users
-      authenticated?: boolean  // allow authenticated contacts
-    }
-    enforce?: {
-      anonymous?: Partial<CreateCaseInput>     // force these values for anon
-      authenticated?: Partial<CreateCaseInput> // force these values for auth
-    }
+  cases?:   PublicCreateObjectRule
+  threads?: PublicCreateObjectRule
+  records?: PublicCreateObjectRule
+}
+
+interface PublicCreateObjectRule {
+  anonymous?:     PublicCreateBranch
+  authenticated?: PublicCreateBranch
+}
+
+interface PublicCreateBranch {
+  /** Whether creation is permitted for this caller class */
+  allow: boolean
+
+  /**
+   * Hard overrides merged over the caller's body before writing.
+   * Lock down visibility and status regardless of what clients send.
+   */
+  enforce?: {
+    visibility?: 'public' | 'owner' | 'admin'
+    status?:     string
+  }
+
+  /**
+   * Anonymous edit-token config — records only.
+   * See "Anonymous Edit Tokens" section below.
+   */
+  edit?: {
+    editToken:      boolean
+    windowMinutes?: number  // omit for no expiry
   }
-  threads?: { /* same structure */ }
-  records?: { /* same structure */ }
 }
 ```
 
+#### Visibility enforcement guard-rails
+
+The server silently corrects misconfigured visibility values:
+
+| Caller type     | `enforce.visibility` supplied | Server overrides to |
+|-----------------|-------------------------------|---------------------|
+| `anonymous`     | `'owner'`                     | `'admin'`           |
+| `authenticated` | `'public'`                    | `'owner'`           |
+
+These guards exist because anonymous callers have no identity to own a record, and `'public'` visibility on authenticated-only objects would be a misconfiguration.
+
 ### Example Policies
 
 **Support tickets from anyone:**
 
 ```json
 {
-  "cases": {
-    "allow": {
-      "anonymous": true,
-      "authenticated": true
-    },
-    "enforce": {
+  "publicCreate": {
+    "cases": {
       "anonymous": {
-        "visibility": "owner",
-        "status": "open",
-        "category": "support"
+        "allow": true,
+        "enforce": { "visibility": "public", "status": "open" }
       },
       "authenticated": {
-        "visibility": "owner",
-        "status": "open"
+        "allow": true,
+        "enforce": { "visibility": "owner", "status": "open" }
       }
     }
   }
@@ -627,15 +661,35 @@ interface PublicCreatePolicy {
 
 ```json
 {
-  "threads": {
-    "allow": {
-      "anonymous": false,
-      "authenticated": true
-    },
-    "enforce": {
+  "publicCreate": {
+    "threads": {
+      "anonymous":     { "allow": false },
       "authenticated": {
-        "visibility": "public",
-        "status": "open"
+        "allow": true,
+        "enforce": { "visibility": "public", "status": "open" }
+      }
+    }
+  }
+}
+```
+
+**Anonymous record creation with edit token (30-minute window):**
+
+```json
+{
+  "publicCreate": {
+    "records": {
+      "anonymous": {
+        "allow": true,
+        "enforce": { "visibility": "public", "status": "pending" },
+        "edit": {
+          "editToken": true,
+          "windowMinutes": 30
+        }
+      },
+      "authenticated": {
+        "allow": true,
+        "enforce": { "visibility": "owner", "status": "pending" }
       }
     }
   }
@@ -646,16 +700,113 @@ interface PublicCreatePolicy {
 
 ```json
 {
-  "records": {
-    "allow": {
-      "anonymous": false,
-      "authenticated": false
+  "publicCreate": {
+    "records": {
+      "anonymous":     { "allow": false },
+      "authenticated": { "allow": false }
     }
   }
 }
 ```
 
-The `enforce` values are **merged over** the caller's request body, so you can lock down fields like `visibility`, `status`, or `category` regardless of what clients send.
+The `enforce` values are **merged over** the caller's request body, so you can lock down fields like `visibility` and `status` regardless of what clients send.
+
+---
+
+## Anonymous Edit Tokens
+
+Enables an anonymous caller to amend a record they just created — without authentication — by presenting a short-lived secret token.
+
+Designed for flows where a client needs to make a follow-up update before a server-side process locks the record. Common examples: payment + confirmation, multi-step forms, IoT device registration.
+
+### How It Works
+
+```
+1. Configure — set publicCreate.records.anonymous.edit.editToken: true in app config
+2. Create    — anonymous POST /records returns { ...record, editToken: "3f8a2c1e..." }
+               Token is stored in record's admin zone; never visible again
+3. Amend     — PATCH /records/:recordId with X-Edit-Token header
+               Only the data zone may be modified
+4. Expiry    — if windowMinutes is set, token is rejected after that many minutes
+```
+
+### SDK Usage
+
+```typescript
+import { app } from '@proveanything/smartlinks';
+
+// Step 1: Create the record (anonymous caller — no auth token)
+const response = await app.records.create(collectionId, appId, {
+  recordType: 'payment',
+  visibility: 'public',
+  data: { amount: 9900, currency: 'USD' },
+})
+
+// editToken is present only when the policy has editToken: true
+const { editToken } = response  // ⚠️ store immediately — returned once only
+
+// Step 2: After external confirmation (e.g. payment gateway callback)
+const updated = await app.records.updateWithToken(
+  collectionId,
+  appId,
+  response.id,
+  { amount: 9900, currency: 'USD', transactionId: 'txn_abc123' },
+  editToken,
+)
+```
+
+`app.records.updateWithToken()` sends the token as the `X-Edit-Token` request header on the public PATCH endpoint — no auth token needed.
+
+### Creation Response Shape
+
+```typescript
+interface CreateRecordResponse extends AppRecord {
+  /**
+   * Present only on anonymous creation when editToken policy is enabled.
+   * Returned ONCE — store it client-side immediately.
+   */
+  editToken?: string
+}
+```
+
+Example creation response:
+
+```json
+{
+  "id": "a1b2c3d4-...",
+  "recordType": "payment",
+  "status": "pending",
+  "visibility": "public",
+  "data": { "amount": 9900, "currency": "USD" },
+  "createdAt": "2026-04-16T12:00:00.000Z",
+  "editToken": "3f8a2c1e..."
+}
+```
+
+### Amendment Scope
+
+Anonymous token updates may only modify the **`data` zone**. The following are immutable via this path:
+
+- `owner`, `admin` zones
+- `status`, `visibility`
+- All indexed fields (`recordType`, `ref`, `startsAt`, `expiresAt`, etc.)
+
+### Error Codes
+
+| HTTP | `errorCode`            | Meaning                                          |
+|------|------------------------|--------------------------------------------------|
+| 401  | `UNAUTHORIZED`         | No auth token and no `X-Edit-Token` header       |
+| 403  | `FORBIDDEN`            | `editToken` policy not enabled for this app      |
+| 403  | `FORBIDDEN`            | Token does not match                             |
+| 403  | `EDIT_WINDOW_EXPIRED`  | `windowMinutes` elapsed since record creation    |
+| 404  | `NOT_FOUND`            | Record does not exist                            |
+
+### Security Notes
+
+- The token is stored in `admin.editToken` and is **always stripped** from public and owner responses — it cannot be read back after creation.
+- Token comparison uses `crypto.timingSafeEqual` to prevent timing-based oracle attacks.
+- The token is a 32-byte (`crypto.randomBytes(32)`) hex string — 256 bits of entropy.
+- For sensitive flows, combine `windowMinutes` with a server-side process that removes or overwrites the token once the record is confirmed.
 
 ---