@proveanything/smartlinks 1.9.17 → 1.9.20

package/dist/openapi.yaml

@@ -12417,6 +12417,54 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /{zone}/collection/{collectionId}/app/{appId}/recordse)}/{recordId}:
+    patch:
+      tags:
+        - records
+      summary: records.updateWithToken
+      operationId: records_updateWithToken
+      security: []
+      parameters:
+        - name: zone
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: appId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: recordId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AppRecord"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
   /{zone}/collection/{collectionId}/app/{appId}/recordsn)}/aggregate:
     post:
       tags:
@@ -12550,7 +12598,7 @@ paths:
     get:
       tags:
         - records
-      summary: "Create a new record POST /records / export async function create( collectionId: string, appId: string, input: CreateReco"
+      summary: "List records with optional query parameters GET /records / export async function list( collectionId: string, appId: stri"
       operationId: records_get
       security: []
       parameters:
@@ -15602,26 +15650,49 @@ components:
       type: object
       properties:
         cases:
-          $ref: "#/components/schemas/PublicCreateRule"
+          $ref: "#/components/schemas/PublicCreateObjectRule"
         threads:
-          $ref: "#/components/schemas/PublicCreateRule"
+          $ref: "#/components/schemas/PublicCreateObjectRule"
         records:
-          $ref: "#/components/schemas/PublicCreateRule"
-    PublicCreateRule:
+          $ref: "#/components/schemas/PublicCreateObjectRule"
+    PublicCreateObjectRule:
       type: object
       properties:
-        allow:
-          type: object
-          additionalProperties: true
         anonymous:
-          $ref: "#/components/schemas/CreateCaseInput"
+          $ref: "#/components/schemas/PublicCreateBranch"
         authenticated:
-          $ref: "#/components/schemas/CreateCaseInput"
+          $ref: "#/components/schemas/PublicCreateBranch"
+    PublicCreateBranch:
+      type: object
+      properties:
+        allow:
+          type: boolean
         enforce:
           type: object
           additionalProperties: true
+        visibility:
+          type: string
+          enum:
+            - public
+            - owner
+            - admin
+        status:
+          type: string
+        edit:
+          type: object
+          additionalProperties: true
+        editToken:
+          type: boolean
+        windowMinutes:
+          type: number
       required:
         - allow
+        - editToken
+    CreateRecordResponse:
+      type: object
+      properties:
+        editToken:
+          type: string
     Asset:
       type: object
       properties:
@@ -22544,6 +22615,66 @@ components:
         metadata:
           type: object
           additionalProperties: true
+    NavigationRequest:
+      type: object
+      properties:
+        appId:
+          type: string
+        deepLink:
+          type: string
+        params:
+          type: object
+          additionalProperties:
+            type: string
+        productId:
+          type: string
+        proofId:
+          type: string
+      required:
+        - appId
+    SmartLinksWidgetProps:
+      type: object
+      properties:
+        collectionId:
+          type: string
+        appId:
+          type: string
+        productId:
+          type: string
+        proofId:
+          type: string
+        user:
+          type: object
+          additionalProperties: true
+        id:
+          type: string
+        email:
+          type: string
+        name:
+          type: string
+        admin:
+          type: boolean
+        SL:
+          type: object
+          additionalProperties: true
+        publicPortalUrl:
+          type: string
+        size:
+          type: string
+          enum:
+            - compact
+            - standard
+            - large
+        lang:
+          type: string
+        translations:
+          type: object
+          additionalProperties:
+            type: string
+      required:
+        - collectionId
+        - appId
+        - SL
     AppConfigOptions:
       type: object
       properties:

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/dist/utils/conditions.d.ts

@@ -114,10 +114,62 @@ export interface ItemStatusCondition extends BaseCondition {
     type: 'itemStatus';
     statusType: 'isClaimable' | 'notClaimable' | 'noProof' | 'hasProof' | 'isVirtual' | 'notVirtual';
 }
+/**
+ * Facet-based condition — gates on the facet values assigned to the current product.
+ *
+ * The `facetKey` identifies which facet dimension to inspect (e.g. `'material'`, `'region'`,
+ * `'certifications'`).  The optional `values` array lists the value `key`s to test.
+ *
+ * ### Match modes (`matchMode`)
+ *
+ * | Mode | Passes when |
+ * |------|-------------|
+ * | `'any'` (default) | The product has **at least one** of the listed values on this facet |
+ * | `'all'` | The product has **every** listed value (multi-value facets only) |
+ * | `'none'` | The product has **none** of the listed values |
+ * | `'hasFacet'` | The product has **any** value on this facet (ignores `values`) |
+ * | `'notHasFacet'` | The product has **no** values on this facet (ignores `values`) |
+ *
+ * ### Examples
+ *
+ * ```typescript
+ * // Must carry the 'cotton' or 'linen' value on the 'material' facet
+ * { type: 'facet', facetKey: 'material', matchMode: 'any', values: ['cotton', 'linen'] }
+ *
+ * // Must carry BOTH 'organic' and 'recycled' on the 'certifications' facet
+ * { type: 'facet', facetKey: 'certifications', matchMode: 'all', values: ['organic', 'recycled'] }
+ *
+ * // Must NOT carry 'discontinued' on the 'status' facet
+ * { type: 'facet', facetKey: 'status', matchMode: 'none', values: ['discontinued'] }
+ *
+ * // Product must have at least one value on the 'region' facet
+ * { type: 'facet', facetKey: 'region', matchMode: 'hasFacet' }
+ * ```
+ */
+export interface FacetCondition extends BaseCondition {
+    type: 'facet';
+    /** The facet dimension key to inspect (e.g. `'material'`, `'region'`) */
+    facetKey: string;
+    /**
+     * How to match against `values`.
+     * - `'any'` — pass if the product has at least one of the listed values (default)
+     * - `'all'` — pass if the product has every listed value
+     * - `'none'` — pass if the product has none of the listed values
+     * - `'hasFacet'` — pass if the product has any value on this facet (ignores `values`)
+     * - `'notHasFacet'` — pass if the product has no values on this facet (ignores `values`)
+     */
+    matchMode?: 'any' | 'all' | 'none' | 'hasFacet' | 'notHasFacet';
+    /**
+     * Facet value keys to test against.
+     * Required for `'any'`, `'all'`, and `'none'` match modes.
+     * Ignored for `'hasFacet'` and `'notHasFacet'`.
+     */
+    values?: string[];
+}
 /**
  * Union of all condition types
  */
-export type Condition = CountryCondition | VersionCondition | DeviceCondition | NestedCondition | UserCondition | ProductCondition | TagCondition | DateCondition | GeofenceCondition | ValueCondition | ItemStatusCondition;
+export type Condition = CountryCondition | VersionCondition | DeviceCondition | NestedCondition | UserCondition | ProductCondition | TagCondition | FacetCondition | DateCondition | GeofenceCondition | ValueCondition | ItemStatusCondition;
 /**
  * Condition set that combines multiple conditions
  */
@@ -166,6 +218,23 @@ export interface UserInfo {
 export interface ProductInfo {
     id: string;
     tags?: Record<string, any>;
+    /**
+     * Facet values assigned to this product.
+     * Shape mirrors `ProductFacetMap`: a map of facet key → array of value objects.
+     * Each value object must have at minimum a `key` string property.
+     *
+     * @example
+     * ```ts
+     * {
+     *   material: [{ key: 'cotton', name: 'Cotton' }],
+     *   certifications: [{ key: 'organic', name: 'Organic' }, { key: 'recycled', name: 'Recycled' }]
+     * }
+     * ```
+     */
+    facets?: Record<string, Array<{
+        key: string;
+        [k: string]: unknown;
+    }>>;
 }
 /**
  * Proof information for condition validation
@@ -234,6 +303,7 @@ export interface ConditionDebugOptions {
  * - **user** - User authentication status (logged in, owner, admin)
  * - **product** - Product-specific conditions
  * - **tag** - Product tag-based conditions
+ * - **facet** - Product facet-based conditions (any/all/none of specific facet values)
  * - **date** - Time-based conditions (before, after, between dates)
  * - **geofence** - Location-based restrictions
  * - **value** - Custom field comparisons

package/dist/utils/conditions.js

@@ -93,7 +93,7 @@ function summarizeConditionSet(condition) {
     return `${(_a = condition.type) !== null && _a !== void 0 ? _a : 'and'} (${(_c = (_b = condition.conditions) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0} conditions)`;
 }
 function summarizeCondition(condition) {
-    var _a, _b;
+    var _a, _b, _c, _d, _e;
     switch (condition.type) {
         case 'country':
             return `country regions=${((_a = condition.regions) === null || _a === void 0 ? void 0 : _a.join(',')) || 'none'} countries=${((_b = condition.countries) === null || _b === void 0 ? void 0 : _b.join(',')) || 'none'} contains=${condition.contains}`;
@@ -115,6 +115,11 @@ function summarizeCondition(condition) {
             return `geofence contains=${condition.contains}`;
         case 'value':
             return `value field=${condition.field} ${condition.validationType} ${String(condition.value)}`;
+        case 'facet': {
+            const mode = (_c = condition.matchMode) !== null && _c !== void 0 ? _c : 'any';
+            const vals = (_e = (_d = condition.values) === null || _d === void 0 ? void 0 : _d.join(', ')) !== null && _e !== void 0 ? _e : '—';
+            return `facet key=${condition.facetKey} mode=${mode} values=[${vals}]`;
+        }
         case 'itemStatus':
             return `itemStatus ${condition.statusType}`;
         default:
@@ -143,6 +148,8 @@ async function evaluateConditionEntry(condition, params) {
             return validateGeofence(condition, params);
         case 'value':
             return validateValue(condition, params);
+        case 'facet':
+            return validateFacet(condition, params);
         case 'itemStatus':
             return validateItemStatus(condition, params);
         default:
@@ -162,6 +169,7 @@ async function evaluateConditionEntry(condition, params) {
  * - **user** - User authentication status (logged in, owner, admin)
  * - **product** - Product-specific conditions
  * - **tag** - Product tag-based conditions
+ * - **facet** - Product facet-based conditions (any/all/none of specific facet values)
  * - **date** - Time-based conditions (before, after, between dates)
  * - **geofence** - Location-based restrictions
  * - **value** - Custom field comparisons
@@ -730,6 +738,82 @@ async function validateValue(condition, params) {
         },
     };
 }
+/**
+ * Validate facet-based condition
+ */
+async function validateFacet(condition, params) {
+    var _a, _b, _c;
+    const { facetKey, matchMode = 'any', values = [] } = condition;
+    const facets = (_a = params.product) === null || _a === void 0 ? void 0 : _a.facets;
+    // No product
+    if (!((_b = params.product) === null || _b === void 0 ? void 0 : _b.id)) {
+        return {
+            passed: false,
+            detail: 'Product ID was not available.',
+            context: { facetKey, matchMode },
+        };
+    }
+    const assigned = (_c = facets === null || facets === void 0 ? void 0 : facets[facetKey]) !== null && _c !== void 0 ? _c : [];
+    const assignedKeys = assigned.map(v => v.key);
+    // Presence-only modes — ignore `values`
+    if (matchMode === 'hasFacet') {
+        return {
+            passed: assignedKeys.length > 0,
+            detail: `Product ${assigned.length > 0 ? 'has' : 'does not have'} values on facet '${facetKey}'.`,
+            context: { facetKey, assignedKeys },
+        };
+    }
+    if (matchMode === 'notHasFacet') {
+        return {
+            passed: assignedKeys.length === 0,
+            detail: `Product ${assigned.length === 0 ? 'has no' : 'has'} values on facet '${facetKey}'.`,
+            context: { facetKey, assignedKeys },
+        };
+    }
+    // Value-matching modes require at least one value to test
+    if (values.length === 0) {
+        return {
+            passed: false,
+            detail: `Facet condition for '${facetKey}' with matchMode '${matchMode}' requires at least one value.`,
+            context: { facetKey, matchMode },
+        };
+    }
+    if (matchMode === 'any') {
+        const matched = values.filter(v => assignedKeys.includes(v));
+        return {
+            passed: matched.length > 0,
+            detail: matched.length > 0
+                ? `Product matched facet '${facetKey}' value(s): [${matched.join(', ')}].`
+                : `Product did not match any of [${values.join(', ')}] on facet '${facetKey}'.`,
+            context: { facetKey, matchMode, testedValues: values, matched, assignedKeys },
+        };
+    }
+    if (matchMode === 'all') {
+        const missing = values.filter(v => !assignedKeys.includes(v));
+        return {
+            passed: missing.length === 0,
+            detail: missing.length === 0
+                ? `Product has all required values on facet '${facetKey}'.`
+                : `Product is missing [${missing.join(', ')}] on facet '${facetKey}'.`,
+            context: { facetKey, matchMode, testedValues: values, missing, assignedKeys },
+        };
+    }
+    if (matchMode === 'none') {
+        const matched = values.filter(v => assignedKeys.includes(v));
+        return {
+            passed: matched.length === 0,
+            detail: matched.length === 0
+                ? `Product correctly has none of [${values.join(', ')}] on facet '${facetKey}'.`
+                : `Product has forbidden value(s) [${matched.join(', ')}] on facet '${facetKey}'.`,
+            context: { facetKey, matchMode, testedValues: values, matched, assignedKeys },
+        };
+    }
+    return {
+        passed: false,
+        detail: `Unsupported facet matchMode '${matchMode}'.`,
+        context: { facetKey, matchMode },
+    };
+}
 /**
  * Validate item status condition
  */