@proveanything/smartlinks 1.9.16 → 1.9.19

package/dist/api/appObjects.d.ts

@@ -1,4 +1,4 @@
-import type { AppCase, CreateCaseInput, UpdateCaseInput, AppendHistoryInput, CaseSummaryRequest, CaseSummaryResponse, CaseListQueryParams, AppThread, CreateThreadInput, UpdateThreadInput, ReplyInput, ThreadListQueryParams, AppRecord, CreateRecordInput, UpdateRecordInput, RecordListQueryParams, PaginatedResponse, AggregateRequest, AggregateResponse, RelatedResponse } from '../types/appObjects';
+import type { AppCase, CreateCaseInput, UpdateCaseInput, AppendHistoryInput, CaseSummaryRequest, CaseSummaryResponse, CaseListQueryParams, AppThread, CreateThreadInput, UpdateThreadInput, ReplyInput, ThreadListQueryParams, AppRecord, CreateRecordInput, CreateRecordResponse, UpdateRecordInput, RecordListQueryParams, PaginatedResponse, AggregateRequest, AggregateResponse, RelatedResponse } from '../types/appObjects';
 export declare namespace app {
     namespace cases {
         /**
@@ -95,8 +95,15 @@ export declare namespace app {
         /**
          * 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.
+         *
+         * @see {@link updateWithToken} — use the edit token for a follow-up amendment
          */
-        function create(collectionId: string, appId: string, input: CreateRecordInput, admin?: boolean): Promise<AppRecord>;
+        function create(collectionId: string, appId: string, input: CreateRecordInput, admin?: boolean): Promise<CreateRecordResponse>;
         /**
          * List records with optional query parameters
          * GET /records
@@ -113,6 +120,53 @@ export declare namespace app {
          * Admin can update any field, public (owner) can only update data and owner
          */
         function update(collectionId: string, appId: string, recordId: string, input: UpdateRecordInput, admin?: boolean): 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.
+         *
+         * @param collectionId - Collection the record belongs to
+         * @param appId        - App the record belongs to
+         * @param recordId     - ID of the record to amend
+         * @param data         - New (full replacement) value for the `data` zone
+         * @param editToken    - Token received from the original `create()` response
+         *
+         * @example
+         * ```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                             |
+         */
+        function updateWithToken(collectionId: string, appId: string, recordId: string, data: Record<string, unknown>, editToken: string): Promise<AppRecord>;
         /**
          * Soft delete a record
          * DELETE /records/:recordId

package/dist/api/appObjects.js

@@ -187,6 +187,13 @@ export var app;
         /**
          * 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.
+         *
+         * @see {@link updateWithToken} — use the edit token for a follow-up amendment
          */
         async function create(collectionId, appId, input, admin = false) {
             const path = basePath(collectionId, appId, admin);
@@ -222,6 +229,57 @@ export var app;
             return patch(path, input);
         }
         records.update = update;
+        /**
+         * 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.
+         *
+         * @param collectionId - Collection the record belongs to
+         * @param appId        - App the record belongs to
+         * @param recordId     - ID of the record to amend
+         * @param data         - New (full replacement) value for the `data` zone
+         * @param editToken    - Token received from the original `create()` response
+         *
+         * @example
+         * ```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                             |
+         */
+        async function updateWithToken(collectionId, appId, recordId, data, editToken) {
+            const path = `${basePath(collectionId, appId, false)}/${encodeURIComponent(recordId)}`;
+            return patch(path, { data }, { 'X-Edit-Token': editToken });
+        }
+        records.updateWithToken = updateWithToken;
         /**
          * Soft delete a record
          * DELETE /records/:recordId

package/dist/api/authKit.js

@@ -25,12 +25,12 @@ export var authKit;
     authKit.googleLogin = googleLogin;
     /** Send a magic link email to the user (public). */
     async function sendMagicLink(clientId, data) {
-        return post(`/authkit/${encodeURIComponent(clientId)}/magic-link/send`, data);
+        return post(`/authkit/${encodeURIComponent(clientId)}/auth/magic-link/send`, data);
     }
     authKit.sendMagicLink = sendMagicLink;
     /** Verify a magic link token and authenticate/create the user (public). */
     async function verifyMagicLink(clientId, token) {
-        const res = await post(`/authkit/${encodeURIComponent(clientId)}/magic-link/verify`, { token });
+        const res = await post(`/authkit/${encodeURIComponent(clientId)}/auth/magic-link/verify`, { token });
         if (res.token)
             setBearerToken(res.token);
         return res;

package/dist/api/http.js

@@ -23,6 +23,10 @@
 //     { collectionId, productId, appId, data }
 //   )
 import { request as _get, post as _post, put as _put, patch as _patch, del as _del, } from '../http';
+/** Ensure the path always starts with `/` so it concatenates correctly with baseURL. */
+function normalizePath(path) {
+    return path.startsWith('/') ? path : `/${path}`;
+}
 export var http;
 (function (http) {
     /**
@@ -36,7 +40,7 @@ export var http;
      * const fields = await http.get<FieldDefinition[]>('/public/config/fields')
      */
     async function get(path) {
-        return _get(path);
+        return _get(normalizePath(path));
     }
     http.get = get;
     /**
@@ -56,7 +60,7 @@ export var http;
      * })
      */
     async function post(path, body) {
-        return _post(path, body);
+        return _post(normalizePath(path), body);
     }
     http.post = post;
     /**
@@ -68,7 +72,7 @@ export var http;
      * @throws {SmartlinksApiError} on non-2xx responses
      */
     async function put(path, body) {
-        return _put(path, body);
+        return _put(normalizePath(path), body);
     }
     http.put = put;
     /**
@@ -80,7 +84,7 @@ export var http;
      * @throws {SmartlinksApiError} on non-2xx responses
      */
     async function patch(path, body) {
-        return _patch(path, body);
+        return _patch(normalizePath(path), body);
     }
     http.patch = patch;
     /**
@@ -91,7 +95,7 @@ export var http;
      * @throws {SmartlinksApiError} on non-2xx responses
      */
     async function del(path) {
-        return _del(path);
+        return _del(normalizePath(path));
     }
     http.del = del;
 })(http || (http = {}));

package/dist/containers/types.d.ts

@@ -0,0 +1,77 @@
+import type { SmartLinksWidgetProps } from '../types';
+/**
+ * Props for a SmartLinks container component.
+ *
+ * Extends {@link SmartLinksWidgetProps} with container-specific additions.
+ *
+ * ## Rendering modes
+ *
+ * Containers run in two modes, and props are the sole source of context in
+ * both:
+ *
+ * | Mode              | How context arrives                                    |
+ * |-------------------|--------------------------------------------------------|
+ * | Direct component  | All props are passed directly by the parent platform   |
+ * | Iframe fallback   | Core params arrive via URL; `PublicPage` reads them    |
+ *                       from search params when the equivalent prop is absent  |
+ *
+ * ## Deep-link parameters (`dlParams`) in container mode
+ *
+ * When the parent platform resolves a deep link (e.g. from a scanned QR code,
+ * NFC tap, or shared URL), it **decodes** the link's `dlParams` payload and
+ * forwards each parameter as an explicit React prop — it does **not** append
+ * them to the browser URL.
+ *
+ * App-specific params (e.g. `preselectedAmount`, `voucherId`, `campaignSlug`)
+ * should therefore be declared as optional props directly on this interface.
+ * The parent guarantees that any param present in the `dlParams` payload will
+ * arrive as the corresponding named prop.
+ *
+ * ### PublicPage priority order
+ *
+ * `PublicPage` (and pages derived from it) **must** resolve app-specific params
+ * in the following priority order so the component works correctly in both
+ * rendering modes:
+ *
+ * ```
+ * 1. Prop value (set by parent in container / direct-component mode)
+ * 2. React Router search param (useSearchParams) in MemoryRouter
+ * 3. Raw URL search param (window.location) — iframe-mode fallback
+ * ```
+ *
+ * Example hook:
+ *
+ * ```ts
+ * function usePreselectedAmount(
+ *   propValue: string | undefined,
+ * ): string | undefined {
+ *   const [searchParams] = useSearchParams()
+ *   return (
+ *     propValue ??
+ *     searchParams.get('preselectedAmount') ??
+ *     new URLSearchParams(window.location.search).get('preselectedAmount') ??
+ *     undefined
+ *   )
+ * }
+ * ```
+ *
+ * @see docs/smartlinks/routing-guide.md — full pattern documentation
+ * @see docs/containers.md              — container architecture overview
+ */
+export interface SmartLinksContainerProps extends SmartLinksWidgetProps {
+    /**
+     * Optional CSS class applied to the outermost wrapper element rendered by
+     * the framework around this container.
+     */
+    className?: string;
+    /**
+     * Initial route path to navigate to inside the container's MemoryRouter.
+     *
+     * The framework sets the MemoryRouter's `initialEntries` from this value
+     * when present. Useful for deep links that target a specific page within
+     * the container (e.g. `'/loyalty/redeem'`).
+     *
+     * In iframe mode the equivalent is the `pageId` URL search parameter.
+     */
+    initialPath?: string;
+}

package/dist/containers/types.js

@@ -0,0 +1 @@
+export {};

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