@proveanything/smartlinks 1.3.35 → 1.3.37

package/dist/api/proof.d.ts

@@ -20,10 +20,27 @@ export declare namespace proof {
      */
     function update(collectionId: string, productId: string, proofId: string, values: ProofUpdateRequest): Promise<ProofResponse>;
     /**
-     * Claim a proof for a product.
-     * PUT /public/collection/:collectionId/product/:productId/proof/:proofId
+     * Claim a proof for a product using a proof ID (serial number, NFC tag, etc.).
+     * PUT /public/collection/:collectionId/product/:productId/proof/:proofId/claim
      */
     function claim(collectionId: string, productId: string, proofId: string, values: ProofClaimRequest): Promise<ProofResponse>;
+    /**
+     * Claim a product without providing a proof ID.
+     * System auto-generates a unique serial number on-demand.
+     * Requires allowAutoGenerateClaims to be enabled on the collection or product.
+     * PUT /public/collection/:collectionId/product/:productId/proof/claim
+     *
+     * @example
+     * ```typescript
+     * const proof = await proof.claimProduct(
+     *   'beauty-brand',
+     *   'moisturizer-pro',
+     *   { purchaseDate: '2026-02-17', store: 'Target' }
+     * );
+     * console.log('Auto-generated ID:', proof.id);
+     * ```
+     */
+    function claimProduct(collectionId: string, productId: string, values?: ProofClaimRequest): Promise<ProofResponse>;
     /**
      * Delete a proof for a product (admin only).
      * DELETE /admin/collection/:collectionId/product/:productId/proof/:proofId

package/dist/api/proof.js

@@ -42,14 +42,35 @@ export var proof;
     }
     proof.update = update;
     /**
-     * Claim a proof for a product.
-     * PUT /public/collection/:collectionId/product/:productId/proof/:proofId
+     * Claim a proof for a product using a proof ID (serial number, NFC tag, etc.).
+     * PUT /public/collection/:collectionId/product/:productId/proof/:proofId/claim
      */
     async function claim(collectionId, productId, proofId, values) {
         const path = `/public/collection/${encodeURIComponent(collectionId)}/product/${encodeURIComponent(productId)}/proof/${encodeURIComponent(proofId)}/claim`;
         return put(path, values);
     }
     proof.claim = claim;
+    /**
+     * Claim a product without providing a proof ID.
+     * System auto-generates a unique serial number on-demand.
+     * Requires allowAutoGenerateClaims to be enabled on the collection or product.
+     * PUT /public/collection/:collectionId/product/:productId/proof/claim
+     *
+     * @example
+     * ```typescript
+     * const proof = await proof.claimProduct(
+     *   'beauty-brand',
+     *   'moisturizer-pro',
+     *   { purchaseDate: '2026-02-17', store: 'Target' }
+     * );
+     * console.log('Auto-generated ID:', proof.id);
+     * ```
+     */
+    async function claimProduct(collectionId, productId, values) {
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/product/${encodeURIComponent(productId)}/proof/claim`;
+        return put(path, values || {});
+    }
+    proof.claimProduct = claimProduct;
     /**
      * Delete a proof for a product (admin only).
      * DELETE /admin/collection/:collectionId/product/:productId/proof/:proofId

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.35  |  Generated: 2026-02-16T09:53:23.211Z
+Version: 1.3.37  |  Generated: 2026-02-17T14:15:30.216Z
 
 This is a concise summary of all available API functions and types.
 
@@ -16,6 +16,8 @@ For detailed guides on specific features:
 - **[Liquid Templates](liquid-templates.md)** - Dynamic templating for content generation
 - **[Theme System](theme.system.md)** - Theme configuration and customization
 - **[Theme Defaults](theme-defaults.md)** - Default theme values and presets
+- **[Proof Claiming Methods](proof-claiming-methods.md)** - All methods for claiming/registering product ownership (NFC tags, serial numbers, auto-generated claims)
+- **[App Data Storage](app-data-storage.md)** - User-specific and collection-scoped app data storage
 
 ## API Namespaces
 
@@ -1503,6 +1505,7 @@ interface Collection {
   shortId: string, // The shortId of this collection
   dark?: boolean // if dark mode is enabled for this collection
   portalUrl?: string // URL for the collection's portal (if applicable)
+  allowAutoGenerateClaims?: boolean
 }
 ```
 
@@ -3381,6 +3384,11 @@ interface Product {
   data: {
   [key: string]: any
   } // Flexible key/value data map
+  admin?: {
+  allowAutoGenerateClaims?: boolean
+  lastSerialId?: number
+  [key: string]: any
+  }
 }
 ```
 
@@ -3776,16 +3784,27 @@ interface TemplateRenderSourceResponse {
 **AppConfigOptions** (type)
 ```typescript
 type AppConfigOptions = {
+  /** The app ID */
   appId: string
+  
+  /** Collection ID (required for most operations) */
   collectionId?: string
+  /** Product ID (optional - for product-scoped config) */
   productId?: string
+  /** Variant ID (optional - for variant-scoped config) */
   variantId?: string
+  /** Batch ID (optional - for batch-scoped config) */
   batchId?: string
+  
+  /** Item ID - required for getDataItem/deleteDataItem */
   itemId?: string
-  user?: boolean
-  userData?: boolean
+  
+  /** Use admin endpoints instead of public */
   admin?: boolean
+  
+  /** Configuration object for setConfig */
   config?: any
+  /** Data object for setDataItem */
   data?: any
 }
 ```
@@ -3941,18 +3960,25 @@ Post a chat message to the AI (admin or public)
 ### appConfiguration
 
 **getConfig**(opts: AppConfigOptions) → `Promise<any>`
+Get app configuration for a collection/product scope. ```typescript const config = await appConfiguration.getConfig({ appId: 'warranty-portal', collectionId: 'my-collection' }); ```
 
 **setConfig**(opts: AppConfigOptions) → `Promise<any>`
+Set app configuration for a collection/product scope. Requires admin authentication. ```typescript await appConfiguration.setConfig({ appId: 'warranty-portal', collectionId: 'my-collection', admin: true, config: { warrantyPeriod: 24, supportEmail: 'support@example.com' } }); ```
 
 **deleteConfig**(opts: AppConfigOptions) → `Promise<void>`
+Delete app configuration for a collection/product scope. Requires admin authentication. ```typescript await appConfiguration.deleteConfig({ appId: 'warranty-portal', collectionId: 'my-collection', admin: true }); ```
 
 **getData**(opts: AppConfigOptions) → `Promise<any[]>`
+Get all data items for an app within a scope. ```typescript const items = await appConfiguration.getData({ appId: 'product-docs', collectionId: 'my-collection', productId: 'product-123' }); ```
 
 **getDataItem**(opts: AppConfigOptions) → `Promise<any>`
+Get a single data item by ID within a scope. ```typescript const item = await appConfiguration.getDataItem({ appId: 'product-docs', collectionId: 'my-collection', productId: 'product-123', itemId: 'manual-1' }); ```
 
 **setDataItem**(opts: AppConfigOptions) → `Promise<any>`
+Set/create a data item within a scope. Requires admin authentication. ```typescript await appConfiguration.setDataItem({ appId: 'product-docs', collectionId: 'my-collection', productId: 'product-123', admin: true, data: { id: 'manual-1', title: 'User Manual', url: 'https://...' } }); ```
 
 **deleteDataItem**(opts: AppConfigOptions) → `Promise<void>`
+Delete a data item by ID within a scope. Requires admin authentication. ```typescript await appConfiguration.deleteDataItem({ appId: 'product-docs', collectionId: 'my-collection', productId: 'product-123', admin: true, itemId: 'manual-1' }); ```
 
 **getWidgets**(collectionId: string,
     options?: GetCollectionWidgetsOptions) → `Promise<CollectionWidgetsResponse>`
@@ -4832,7 +4858,12 @@ Update a proof for a product (admin only). PUT /admin/collection/:collectionId/p
     productId: string,
     proofId: string,
     values: ProofClaimRequest) → `Promise<ProofResponse>`
-Claim a proof for a product. PUT /public/collection/:collectionId/product/:productId/proof/:proofId
+Claim a proof for a product using a proof ID (serial number, NFC tag, etc.). PUT /public/collection/:collectionId/product/:productId/proof/:proofId/claim
+
+**claimProduct**(collectionId: string,
+    productId: string,
+    values?: ProofClaimRequest) → `Promise<ProofResponse>`
+Claim a product without providing a proof ID. System auto-generates a unique serial number on-demand. Requires allowAutoGenerateClaims to be enabled on the collection or product. PUT /public/collection/:collectionId/product/:productId/proof/claim ```typescript const proof = await proof.claimProduct( 'beauty-brand', 'moisturizer-pro', { purchaseDate: '2026-02-17', store: 'Target' } ); console.log('Auto-generated ID:', proof.id); ```
 
 **remove**(collectionId: string,
     productId: string,
@@ -4978,6 +5009,29 @@ Backward-compat: Public batch lookup (GET) with collectionId parameter (ignored)
 **renderSource**(collectionId: string,
     body: TemplateRenderSourceRequest) → `Promise<TemplateRenderSourceResponse>`
 
+### userAppData
+
+**getConfig**(appId: string) → `Promise<any>`
+Get user's config blob for an app. This is a single JSON object stored per user+app. ```typescript const config = await userAppData.getConfig('allergy-tracker'); // Returns: { allergies: ['peanuts'], notifications: true } ```
+
+**setConfig**(appId: string, config: any) → `Promise<any>`
+Set user's config blob for an app. ```typescript await userAppData.setConfig('allergy-tracker', { allergies: ['peanuts', 'shellfish'], notifications: true }); ```
+
+**deleteConfig**(appId: string) → `Promise<void>`
+Delete user's config blob for an app. ```typescript await userAppData.deleteConfig('allergy-tracker'); ```
+
+**list**(appId: string) → `Promise<any[]>`
+List all user's data items for an app. Returns an array of objects, each with an `id` field. ```typescript const beds = await userAppData.list('garden-planner'); // Returns: [{ id: 'bed-1', name: 'Vegetables', ... }, { id: 'bed-2', ... }] ```
+
+**get**(appId: string, itemId: string) → `Promise<any>`
+Get a specific user data item by ID. ```typescript const bed = await userAppData.get('garden-planner', 'bed-1'); // Returns: { id: 'bed-1', name: 'Vegetable Bed', plants: [...] } ```
+
+**set**(appId: string, item: any) → `Promise<any>`
+Create or update a user data item. The item object must include an `id` field. ```typescript await userAppData.set('garden-planner', { id: 'bed-1', name: 'Vegetable Bed', plants: ['tomatoes', 'peppers'], location: { x: 10, y: 20 } }); ```
+
+**remove**(appId: string, itemId: string) → `Promise<void>`
+Delete a user data item by ID. ```typescript await userAppData.remove('garden-planner', 'bed-1'); ```
+
 ### variant
 
 **get**(collectionId: string,

package/dist/docs/app-data-storage.md

@@ -0,0 +1,223 @@
+# App Data Storage Guide
+
+The SmartLinks platform provides two distinct types of data storage for apps:
+
+## 1. User-Specific Data (Global per User+App)
+
+**Use the `userAppData` namespace for all user-specific data.**
+
+User data is **shared across all collections** for a given user and app. This is perfect for storing user preferences, personal settings, and user-generated content that should persist regardless of which collection they're viewing.
+
+### Use Cases
+- User allergies in an allergy tracking app
+- Garden bed layouts in a garden planning app
+- User preferences and settings
+- Shopping lists, wishlists, favorites
+- Personal notes and annotations
+
+### API Endpoints
+```
+GET    /public/auth/app/:appId              - Get user's single config blob
+POST   /public/auth/app/:appId              - Set user's single config blob
+DELETE /public/auth/app/:appId              - Delete user's config blob
+
+GET    /public/auth/app/:appId/data         - Get all user's data items
+GET    /public/auth/app/:appId/data/:itemId - Get a specific user data item
+POST   /public/auth/app/:appId/data         - Create/update a user data item
+DELETE /public/auth/app/:appId/data/:itemId - Delete a user data item
+```
+
+### SDK Usage
+
+#### Single Config Blob (Simple Key-Value)
+```typescript
+import { userAppData } from '@proveanything/smartlinks';
+
+// Get user's config
+const config = await userAppData.getConfig('allergy-tracker');
+
+// Save user's config
+await userAppData.setConfig('allergy-tracker', { 
+  allergies: ['peanuts', 'shellfish'],
+  notifications: true 
+});
+
+// Delete user's config
+await userAppData.deleteConfig('allergy-tracker');
+```
+
+#### Multiple Keyed Data Items (Recommended)
+```typescript
+// Get all user's garden beds
+const beds = await userAppData.list('garden-planner');
+// Returns: [{ id: 'bed-1', name: 'Vegetables', ... }, { id: 'bed-2', ... }]
+
+// Get specific bed
+const bed = await userAppData.get('garden-planner', 'bed-1');
+
+// Save/update a bed
+await userAppData.set('garden-planner', { 
+  id: 'bed-1', 
+  name: 'Vegetable Bed', 
+  plants: ['tomatoes', 'peppers'],
+  location: { x: 10, y: 20 }
+});
+
+// Delete a bed
+await userAppData.remove('garden-planner', 'bed-1');
+```
+
+### Important Notes
+- ✅ **Clean, simple API** - Just pass the `appId` (no collection/product scoping)
+- ✅ User data requires authentication (Bearer token)
+- ✅ Data is automatically scoped to the authenticated user
+- ✅ Impossible to accidentally scope to collections
+
+---
+
+## 2. Collection/Product-Scoped Data (Admin Configuration)
+
+**Use the `appConfiguration` namespace for collection/product-scoped data.**
+
+This data is scoped to specific collections, products, variants, or batches. It's typically configured by collection admins/owners and applies to all users viewing that collection/product.
+
+### Use Cases
+- App-specific settings for a collection
+- Product-level configuration
+- Feature flags and toggles
+- Theme and branding settings
+- Public content that all users see
+
+### API Endpoints
+```
+GET    /public/collection/:collectionId/app/:appId
+POST   /admin/collection/:collectionId/app/:appId
+DELETE /admin/collection/:collectionId/app/:appId
+
+GET    /public/collection/:collectionId/product/:productId/app/:appId/data
+POST   /admin/collection/:collectionId/product/:productId/app/:appId/data
+...
+```
+
+### SDK Usage
+
+```typescript
+import { appConfiguration } from '@proveanything/smartlinks';
+
+// Get collection-level app config
+const collectionConfig = await appConfiguration.getConfig({ 
+  appId: 'warranty-portal', 
+  collectionId: 'my-collection'
+});
+
+// Set collection-level config (requires admin auth)
+await appConfiguration.setConfig({ 
+  appId: 'warranty-portal', 
+  collectionId: 'my-collection',
+  admin: true,
+  config: { 
+    warrantyPeriod: 24, 
+    supportEmail: 'support@example.com' 
+  }
+});
+
+// Get product-level data items
+const items = await appConfiguration.getData({ 
+  appId: 'product-docs', 
+  collectionId: 'my-collection',
+  productId: 'product-123'
+});
+
+// Set product-level data item (requires admin auth)
+await appConfiguration.setDataItem({ 
+  appId: 'product-docs', 
+  collectionId: 'my-collection',
+  productId: 'product-123',
+  admin: true,
+  data: { 
+    id: 'manual-1', 
+    title: 'User Manual',
+    url: 'https://...' 
+  }
+});
+```
+
+---
+
+## Comparison Table
+
+| Feature | User Data | Collection/Product Data |
+|---------|-----------|------------------------|
+| **Namespace** | `userAppData` | `appConfiguration` |
+| **Scope** | User + App (global) | Collection/Product/Variant/Batch |
+| **Set by** | Individual users | Collection admins/owners |
+| **Shared across collections?** | ✅ Yes | ❌ No |
+| **Requires auth?** | ✅ Yes (user token) | ✅ Yes (admin token for write) |
+| **Function signature** | Simple: `set(appId, data)` | Options object: `setDataItem({ appId, collectionId, data })` |
+| **Admin write required?** | ❌ No | ✅ Yes (for write operations) |
+
+---
+
+## Migration from Old SDK
+
+### Old SDK → New SDK
+
+```typescript
+// OLD: Get user config
+RemoteApi.get({ path: `public/auth/app/${appId}` })
+// NEW:
+userAppData.getConfig(appId)
+
+// OLD: Set user config
+RemoteApi.post({ path: `public/auth/app/${appId}`, data })
+// NEW:
+userAppData.setConfig(appId, data)
+
+// OLD: Get user data items
+RemoteApi.get({ path: `public/auth/app/${appId}/data` })
+// NEW:
+userAppData.list(appId)
+
+// OLD: Get user data item
+RemoteApi.get({ path: `public/auth/app/${appId}/data/${itemId}` })
+// NEW:
+userAppData.get(appId, itemId)
+
+// OLD: Set user data item
+RemoteApi.post({ path: `public/auth/app/${appId}/data`, data: item })
+// NEW:
+userAppData.set(appId, item)
+
+// OLD: Delete user data item
+RemoteApi.delete({ path: `public/auth/app/${appId}/data/${itemId}` })
+// NEW:
+userAppData.remove(appId, itemId)
+```
+
+---
+
+## Complete API Reference
+
+### `userAppData` (User-Specific Data)
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `getConfig` | `(appId: string) => Promise<any>` | Get user's config blob |
+| `setConfig` | `(appId: string, config: any) => Promise<any>` | Set user's config blob |
+| `deleteConfig` | `(appId: string) => Promise<void>` | Delete user's config blob |
+| `list` | `(appId: string) => Promise<any[]>` | List all user's data items |
+| `get` | `(appId: string, itemId: string) => Promise<any>` | Get specific data item |
+| `set` | `(appId: string, item: any) => Promise<any>` | Create/update data item |
+| `remove` | `(appId: string, itemId: string) => Promise<void>` | Delete data item |
+
+### `appConfiguration` (Collection/Product-Scoped Data)
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `getConfig` | `(opts: AppConfigOptions) => Promise<any>` | Get config for scope |
+| `setConfig` | `(opts: AppConfigOptions) => Promise<any>` | Set config for scope |
+| `deleteConfig` | `(opts: AppConfigOptions) => Promise<void>` | Delete config for scope |
+| `getData` | `(opts: AppConfigOptions) => Promise<any[]>` | List data items in scope |
+| `getDataItem` | `(opts: AppConfigOptions) => Promise<any>` | Get specific data item |
+| `setDataItem` | `(opts: AppConfigOptions) => Promise<any>` | Create/update data item |
+| `deleteDataItem` | `(opts: AppConfigOptions) => Promise<void>` | Delete data item |