@proveanything/smartlinks 1.3.34 → 1.3.37

package/dist/types/collection.d.ts

@@ -63,6 +63,8 @@ export interface Collection {
     /** if dark mode is enabled for this collection */
     dark?: boolean;
     portalUrl?: string;
+    /** Allow users to claim products without providing a proof ID (auto-generates serial on-demand) */
+    allowAutoGenerateClaims?: boolean;
 }
 export type CollectionResponse = Collection;
 export type CollectionCreateRequest = Omit<Collection, 'id' | 'shortId'>;

package/dist/types/product.d.ts

@@ -14,7 +14,12 @@ export interface Product {
     gtin?: string;
     /** An optional product type from the standard smartlinks types */
     type?: string;
-    /** Hero image asset object */
+    /**
+     * Hero image asset object.
+     * When creating/updating, you can pass either:
+     * - A full asset object with url and thumbnails
+     * - A string URL - the system will automatically fetch and store the image
+     */
     heroImage: {
         /** URL to the asset */
         url: string;
@@ -33,7 +38,19 @@ export interface Product {
     data: {
         [key: string]: any;
     };
+    /** Admin-only configuration */
+    admin?: {
+        /** Allow users to claim this product without providing a proof ID (overrides collection setting) */
+        allowAutoGenerateClaims?: boolean;
+        /** Last generated serial ID for auto-claim functionality */
+        lastSerialId?: number;
+        [key: string]: any;
+    };
 }
 export type ProductResponse = Product;
-export type ProductCreateRequest = Omit<Product, 'id' | 'collectionId'>;
-export type ProductUpdateRequest = Partial<Omit<Product, 'id' | 'collectionId'>>;
+export type ProductCreateRequest = Omit<Product, 'id' | 'collectionId'> & {
+    heroImage?: Product['heroImage'] | string;
+};
+export type ProductUpdateRequest = Partial<Omit<Product, 'id' | 'collectionId'>> & {
+    heroImage?: Product['heroImage'] | string;
+};

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.34  |  Generated: 2026-02-16T09:46:01.466Z
+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
 }
 ```
 
@@ -3363,6 +3366,10 @@ interface Product {
   description: string
   gtin?: string
   type?: string
+  * Hero image asset object.
+  * When creating/updating, you can pass either:
+  * - A full asset object with url and thumbnails
+  * - A string URL - the system will automatically fetch and store the image
   heroImage: {
   url: string
   thumbnails: {
@@ -3377,14 +3384,19 @@ interface Product {
   data: {
   [key: string]: any
   } // Flexible key/value data map
+  admin?: {
+  allowAutoGenerateClaims?: boolean
+  lastSerialId?: number
+  [key: string]: any
+  }
 }
 ```
 
 **ProductResponse** = `Product`
 
-**ProductCreateRequest** = `Omit<Product, 'id' | 'collectionId'>`
+**ProductCreateRequest** = `Omit<Product, 'id' | 'collectionId'> & {`
 
-**ProductUpdateRequest** = `Partial<Omit<Product, 'id' | 'collectionId'>>`
+**ProductUpdateRequest** = `Partial<Omit<Product, 'id' | 'collectionId'>> & {`
 
 ### proof
 
@@ -3772,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
 }
 ```
@@ -3937,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>`
@@ -4778,12 +4808,12 @@ List all Product Items for a Collection.
 
 **create**(collectionId: string,
     data: ProductCreateRequest) → `Promise<ProductResponse>`
-Create a new product for a collection (admin only). The `data` payload follows the same shape as ProductResponse minus `id` and `collectionId`.
+Create a new product for a collection (admin only). The `data` payload follows the same shape as ProductResponse minus `id` and `collectionId`. **Hero Image Auto-Fetch:** You can pass `heroImage` as either: - A full asset object: `{ url: '...', thumbnails: {...} }` - A string URL: The system automatically fetches and stores the image ```typescript // Using a URL - auto-fetched and stored const product = await product.create(collectionId, { name: 'Wine Bottle', description: 'Premium red wine', heroImage: 'https://example.com/wine.jpg', // Auto-fetched! tags: {}, data: {} }); ```
 
 **update**(collectionId: string,
     productId: string,
     data: ProductUpdateRequest) → `Promise<ProductResponse>`
-Update a product for a collection (admin only). The `data` payload is a partial of ProductResponse minus `id` and `collectionId`.
+Update a product for a collection (admin only). The `data` payload is a partial of ProductResponse minus `id` and `collectionId`. **Hero Image Auto-Fetch:** You can pass `heroImage` as either: - A full asset object: `{ url: '...', thumbnails: {...} }` - A string URL: The system automatically fetches and stores the image ```typescript // Update with new URL - auto-fetched and stored const product = await product.update(collectionId, productId, { heroImage: 'https://example.com/new-wine.jpg' // Auto-fetched! }); ```
 
 **remove**(collectionId: string,
     productId: string) → `Promise<void>`
@@ -4828,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,
@@ -4974,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/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 |