@proveanything/smartlinks 1.15.3 → 1.15.4

package/dist/openapi.yaml

@@ -24084,6 +24084,67 @@ components:
             $ref: "#/components/schemas/JsonValue"
       required:
         - claimId
+    ScopedFieldOption:
+      type: object
+      properties:
+        value:
+          type: string
+        label:
+          type: string
+      required:
+        - value
+        - label
+    ScopedFieldDef:
+      type: object
+      properties:
+        key:
+          type: string
+        label:
+          type: string
+        type:
+          $ref: "#/components/schemas/ScopedFieldType"
+        required:
+          type: boolean
+        placeholder:
+          type: string
+        help:
+          type: string
+        options:
+          type: array
+          items:
+            $ref: "#/components/schemas/ScopedFieldOption"
+        defaultValue:
+          $ref: "#/components/schemas/JsonValue"
+        showInTable:
+          type: boolean
+        showInDetail:
+          type: boolean
+      required:
+        - key
+        - label
+        - type
+    ProductFieldsConfig:
+      type: object
+      properties:
+        fields:
+          type: array
+          items:
+            $ref: "#/components/schemas/ProductFieldDef"
+      required:
+        - fields
+    ProofValues:
+      type: object
+      properties:
+        owner:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/JsonValue"
+        personal:
+          type: object
+          additionalProperties:
+            type: object
+            additionalProperties:
+              $ref: "#/components/schemas/JsonValue"
     Proof:
       type: object
       properties:
@@ -24103,9 +24164,16 @@ components:
           type: boolean
         virtual:
           type: boolean
-        values:
+        data:
           type: object
-          additionalProperties: true
+          additionalProperties:
+            $ref: "#/components/schemas/JsonValue"
+        admin:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/JsonValue"
+        values:
+          $ref: "#/components/schemas/ProofValues"
       required:
         - collectionId
         - createdAt
@@ -24118,14 +24186,30 @@ components:
       type: object
       properties:
         values:
+          $ref: "#/components/schemas/ProofValues"
+        data:
           type: object
-          additionalProperties: true
+          additionalProperties:
+            $ref: "#/components/schemas/JsonValue"
+        admin:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/JsonValue"
         claimable:
           type: boolean
         virtual:
           type: boolean
       required:
         - values
+    ProofFieldsConfig:
+      type: object
+      properties:
+        fields:
+          type: array
+          items:
+            $ref: "#/components/schemas/ProofFieldDef"
+      required:
+        - fields
     ProofResponse:
       type: object
       additionalProperties: true

package/dist/types/product.d.ts

@@ -85,7 +85,9 @@ export interface Product extends ProductKey {
     facets?: ProductFacetMap;
     /** Tag keys where value is true */
     tags?: Record<string, boolean>;
+    /** Public custom data — readable by everyone, writable by business admins only. */
     data?: Record<string, JsonValue>;
+    /** Business-only custom data — stripped from public/non-admin reads. See docs/proof-product-data-scoping.md. */
     admin?: Record<string, JsonValue>;
     extra?: Record<string, JsonValue>;
     validCollections?: string[] | null;
@@ -161,3 +163,38 @@ export type ProductClaimCreateRequestBody = Omit<ProductClaimCreateInput, 'colle
 export type ProductResponse = Product;
 export type ProductCreateRequest = ProductWriteInput;
 export type ProductUpdateRequest = Partial<Omit<ProductWriteInput, 'id'>>;
+export type ScopedFieldType = 'text' | 'textarea' | 'number' | 'date' | 'select' | 'switch' | 'url';
+export interface ScopedFieldOption {
+    value: string;
+    label: string;
+}
+export interface ScopedFieldDef {
+    /** Stable key. Written into the resolved bag at this name. */
+    key: string;
+    /** Human label for editors and read-only renderers. */
+    label: string;
+    type: ScopedFieldType;
+    required?: boolean;
+    placeholder?: string;
+    help?: string;
+    /** Required when type === 'select'. */
+    options?: ScopedFieldOption[];
+    /** Default value applied when creating a new record. */
+    defaultValue?: JsonValue;
+    /** Show as a column in the default items table. */
+    showInTable?: boolean;
+    /** Show on the inline detail / edit view. */
+    showInDetail?: boolean;
+}
+/**
+ * `'public'` (default, omitted) reads/writes `product.data[key]`.
+ * `'admin'` reads/writes `product.admin[key]` (admin only).
+ */
+export type ProductFieldScope = 'public' | 'admin';
+export type ProductFieldDef = ScopedFieldDef & {
+    scope?: ProductFieldScope;
+};
+/** Shape of the `productFields` collection settings group. */
+export interface ProductFieldsConfig {
+    fields: ProductFieldDef[];
+}

package/dist/types/proof.d.ts

@@ -1,3 +1,17 @@
+import { JsonValue, ScopedFieldDef } from './product';
+/**
+ * `proof.values` — the owner + business-writable bag.
+ * Public keys sit at the root (business + current owner can write, everyone
+ * can read); `owner` and `personal` are reserved sub-keys with their own
+ * read/write rules. See docs/proof-product-data-scoping.md.
+ */
+export interface ProofValues {
+    [key: string]: JsonValue | Record<string, JsonValue> | Record<string, Record<string, JsonValue>> | undefined;
+    /** Owner-scoped: read/write by business + current owner; transfers with ownership. */
+    owner?: Record<string, JsonValue>;
+    /** Per-user: read/write only by the matching userId; not visible to the next owner, not even business admins. */
+    personal?: Record<string, Record<string, JsonValue>>;
+}
 /**
  * Represents a Proof object.
  */
@@ -18,14 +32,36 @@ export interface Proof {
     claimable?: boolean;
     /** Is this proof virtual */
     virtual?: boolean;
-    /** Arbitrary key-value pairs for proof values */
-    values: Record<string, any>;
+    /** Public, business-writable spec data — readable by everyone. */
+    data?: Record<string, JsonValue>;
+    /** Business-only spec data — stripped from public/non-admin reads. */
+    admin?: Record<string, JsonValue>;
+    /** Owner + business-writable consumer data. See ProofValues. */
+    values: ProofValues;
 }
 export type ProofResponse = Proof;
 export interface ProofCreateRequest {
-    values: Record<string, any>;
+    values: ProofValues;
+    /** Business-writable public spec data. */
+    data?: Record<string, JsonValue>;
+    /** Business-only spec data. */
+    admin?: Record<string, JsonValue>;
     claimable?: boolean;
     virtual?: boolean;
 }
 export type ProofUpdateRequest = Partial<ProofCreateRequest>;
 export type ProofClaimRequest = Record<string, any>;
+/**
+ * `'public'` (default, omitted) reads/writes `proof.values[key]`.
+ * `'owner'` reads/writes `proof.values.owner[key]`.
+ * `'personal'` reads/writes `proof.values.personal[userId][key]`.
+ * `'admin'` reads/writes `proof.admin[key]` (admin only).
+ */
+export type ProofFieldScope = 'public' | 'owner' | 'personal' | 'admin';
+export type ProofFieldDef = ScopedFieldDef & {
+    scope?: ProofFieldScope;
+};
+/** Shape of the `proofFields` collection settings group. */
+export interface ProofFieldsConfig {
+    fields: ProofFieldDef[];
+}

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.3  |  Generated: 2026-07-11T13:25:50.969Z
+Version: 1.15.4  |  Generated: 2026-07-14T15:01:53.978Z
 
 This is a concise summary of all available API functions and types.
 
@@ -42,6 +42,7 @@ For detailed guides on specific features:
 - **[Portal Back Button](portal-back-button.md)** - `parentPath` contract for hierarchy-aware "up" navigation; `useDeepLinkSync` integration
 - **[Contact Search](contact-search.md)** - Admin contact search: free-text, typeahead, identity/tag/JSONB filters, and pagination
 - **[App Data Storage](app-data-storage.md)** - User-specific and collection-scoped app data storage
+- **[Product/Proof Data Scoping](proof-product-data-scoping.md)** - Canonical spec for `product.data`/`.admin` and `proof.data`/`.admin`/`.values` (owner/personal) buckets, read/write authority, and the `productFields`/`proofFields` collection-settings schemas
 - **[Forms](forms.md)** - Platform-managed form definitions, submissions, and schema-driven React form UI
 - **[App Objects: Cases, Threads & Records](app-objects.md)** - Generic app-scoped building blocks for support cases, discussions, bookings, registrations, and more
 - **[App Records Pattern](app-records-pattern.md)** - Canonical pattern for storing per-product, per-facet, or rule-targeted app data
@@ -6946,6 +6947,37 @@ interface ProductQueryResponse {
 }
 ```
 
+**ScopedFieldOption** (interface)
+```typescript
+interface ScopedFieldOption {
+  value: string
+  label: string
+}
+```
+
+**ScopedFieldDef** (interface)
+```typescript
+interface ScopedFieldDef {
+  key: string
+  label: string
+  type: ScopedFieldType
+  required?: boolean
+  placeholder?: string
+  help?: string
+  options?: ScopedFieldOption[]
+  defaultValue?: JsonValue
+  showInTable?: boolean
+  showInDetail?: boolean
+}
+```
+
+**ProductFieldsConfig** (interface)
+```typescript
+interface ProductFieldsConfig {
+  fields: ProductFieldDef[]
+}
+```
+
 **JsonPrimitive** = `string | number | boolean | null`
 
 **JsonValue** = ``
@@ -6962,8 +6994,23 @@ interface ProductQueryResponse {
 
 **ProductUpdateRequest** = `Partial<Omit<ProductWriteInput, 'id'>>`
 
+**ScopedFieldType** = ``
+
+**ProductFieldScope** = `'public' | 'admin'`
+
+**ProductFieldDef** = `ScopedFieldDef & { scope?: ProductFieldScope }`
+
 ### proof
 
+**ProofValues** (interface)
+```typescript
+interface ProofValues {
+  [key: string]: JsonValue | Record<string, JsonValue> | Record<string, Record<string, JsonValue>> | undefined
+  owner?: Record<string, JsonValue>
+  personal?: Record<string, Record<string, JsonValue>>
+}
+```
+
 **Proof** (interface)
 ```typescript
 interface Proof {
@@ -6975,25 +7022,40 @@ interface Proof {
   userId: string
   claimable?: boolean
   virtual?: boolean
-  values: Record<string, any>
+  data?: Record<string, JsonValue>
+  admin?: Record<string, JsonValue>
+  values: ProofValues
 }
 ```
 
 **ProofCreateRequest** (interface)
 ```typescript
 interface ProofCreateRequest {
-  values: Record<string, any>
+  values: ProofValues
+  data?: Record<string, JsonValue>
+  admin?: Record<string, JsonValue>
   claimable?: boolean
   virtual?: boolean
 }
 ```
 
+**ProofFieldsConfig** (interface)
+```typescript
+interface ProofFieldsConfig {
+  fields: ProofFieldDef[]
+}
+```
+
 **ProofResponse** = `Proof`
 
 **ProofUpdateRequest** = `Partial<ProofCreateRequest>`
 
 **ProofClaimRequest** = `Record<string, any>`
 
+**ProofFieldScope** = `'public' | 'owner' | 'personal' | 'admin'`
+
+**ProofFieldDef** = `ScopedFieldDef & { scope?: ProofFieldScope }`
+
 ### qr
 
 **QrShortCodeLookupResponse** (interface)

package/docs/app-data-storage.md

@@ -2,6 +2,8 @@
 
 The SmartLinks platform provides two distinct types of data storage for apps:
 
+> **Not what you're looking for?** This guide covers app-owned config/records scoped to a collection or product. For the core product/proof documents themselves — `product.data`/`.admin`, `proof.data`/`.admin`/`.values` (owner/personal) — see [proof-product-data-scoping.md](proof-product-data-scoping.md).
+
 ## Choose the Right Model First
 
 There are now two different families of flexible app data in SmartLinks, and they solve different problems:

package/docs/overview.md

@@ -80,6 +80,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Contact Search** | `docs/contact-search.md` | Admin contact search: free-text, typeahead, identity/tag/JSONB filters, and pagination |
 | **App Records Pattern** | `docs/app-records-pattern.md` | Standard pattern for per-product/facet/variant/batch admin + public widget UIs |
 | **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
+| **Product/Proof Data Scoping** | `docs/proof-product-data-scoping.md` | Canonical spec for `product.data`/`.admin` and `proof.data`/`.admin`/`.values` (owner/personal) — who can read and write each bucket |
 
 ---
 
@@ -204,6 +205,12 @@ Prefer `app.records` over `setDataItem` when the data is becoming a real entity
 
 For data attached to specific proof instances, use `SL.attestation.create()` and `SL.attestation.list()`.
 
+### Custom Data Scoping (Product & Proof)
+
+`product.data`/`product.admin` and `proof.data`/`proof.admin`/`proof.values` are the canonical buckets for custom fields on products and proofs — `data` is public and business-writable, `admin` is business-only, and `proof.values` additionally supports owner-scoped (`values.owner`) and per-user (`values.personal[userId]`) sub-keys. This is a different mechanism from the app-scoped storage in `docs/app-data-storage.md` (which is for app-owned config/records, not the product/proof documents themselves).
+
+See `docs/proof-product-data-scoping.md` for the full read/write authority matrix, worked examples, and the `productFields`/`proofFields` collection-settings schemas that drive field-config editors.
+
 ---
 
 ## Error Handling