@proveanything/smartlinks 1.12.0 → 1.13.1

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.12.0  |  Generated: 2026-05-05T10:17:03.386Z
+Version: 1.13.1  |  Generated: 2026-05-07T10:59:17.642Z
 
 This is a concise summary of all available API functions and types.
 
@@ -9,26 +9,41 @@ This is a concise summary of all available API functions and types.
 For detailed guides on specific features:
 
 - **[SmartLinks Microapp Overview](overview.md)** - Platform architecture, data model, auth patterns, storage, anti-patterns, and quick-reference for all SDK docs
+- **[Assets](assets.md)** - Asset object, AssetRef, upload, replace, soft-delete, restore, bulk-delete, and public token-based uploads
 - **[AI & Chat Completions](ai.md)** - Chat completions, RAG (document-grounded Q&A), voice integration, streaming, tool calling, podcast generation
 - **[Translations](translations.md)** - Runtime translation lookup, browser-side IndexedDB caching, and admin translation management
 - **[Widgets](widgets.md)** - Embeddable React components for parent applications
-- **[Containers](containers.md)** - Building full-app embeddable containers (lazy-loaded) 
+- **[Building React Components](building-react-components.md)** - Foundational guide to building React widgets and containers for SmartLinks
+- **[Containers](containers.md)** - Building full-app embeddable containers (lazy-loaded)
+- **[Mobile Admin Container](mobile-admin-container.md)** - Building mobile-optimised operator/admin containers as a separate bundle
+- **[Container Tracking](container-tracking.md)** - Hierarchical physical/logical container groupings with item membership
 - **[Scanner Containers](scanner-container.md)** - Building scanner microapps for the SmartLinks Scanner Android host (RFID, NFC, QR, key events)
 - **[Multi-Page App Architecture](mpa.md)** - Vite MPA build pipeline: public/admin entry points, widget/container/executor bundles, content-hashed CDN assets
 - **[App Configuration Files](app-manifest.md)** - `app.manifest.json` and `app.admin.json` reference — bundles, components, setup questions, import schemas, tunable fields, and metrics
 - **[Executor Model](executor.md)** - Programmatic JS bundles for AI-driven setup, server-side SEO metadata generation, and LLM content for AI crawlers
 - **[Realtime](realtime.md)** - Real-time data updates and WebSocket connections
 - **[iframe Responder](iframe-responder.md)** - iframe integration and cross-origin communication
+- **[iframe Streaming Parent Changes](iframe-streaming-parent-changes.md)** - Parent-side changes required to support AI streaming in iframe proxy mode
 - **[Utilities](utils.md)** - Helper functions for building portal paths, URLs, and common tasks
+- **[UI Utils](ui-utils.md)** - Reusable, themeable admin UI React component library for microapps
+- **[Caching](caching.md)** - Multi-tier caching strategy (in-memory, SessionStorage, IndexedDB) used by the SDK
+- **[Native Facade](native-facade.md)** - Contract layer for accessing device capabilities (share, NFC, haptics) across host shells
 - **[i18n](i18n.md)** - Internationalization and localization
 - **[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)
+- **[Product Facets SDK](PRODUCT_FACETS_SDK.md)** - Admin and public product facet endpoints and TypeScript interfaces
+- **[Attestations](attestations.md)** - Append-only fact log with cryptographic chain integrity, time-series analytics, and public/owner/admin visibility
+- **[Auth Kit](auth-kit.md)** - End-user authentication flows (email/password, magic link, OTP, OAuth) for microapps
 - **[App Data Storage](app-data-storage.md)** - User-specific and collection-scoped app data storage
+- **[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
 - **[Communications](comms.md)** - Transactional sends, multi-channel broadcasts, consent management, push registration, and analytics
 - **[Interactions & Event Tracking](interactions.md)** - Log user events, count outcomes, query history, and define interaction types with permissions
+- **[Analytics](analytics.md)** - Web analytics, link-click tracking, QR/tag scan telemetry, and event reporting
+- **[Analytics Metadata Conventions](analytics-metadata-conventions.md)** - Standard recommended keys and conventions for analytics metadata fields
 - **[Loyalty: Points, Members & Earning Rules](loyalty.md)** - Loyalty schemes, automatic point earning via interaction rules, member balances, transaction history, and manual adjustments
 - **[Deep Link Discovery](deep-link-discovery.md)** - Registering and discovering navigable app states for portal menus and AI orchestration
 - **[AI-Native App Manifests](manifests.md)** - How AI workflows discover, configure, and import apps via structured manifests and prose guides
@@ -2245,28 +2260,71 @@ interface PublicCreateBranch {
 
 ### asset
 
+**AssetRef** (interface)
+```typescript
+interface AssetRef {
+  id: string
+  url: string
+  thumbnail: string | null
+}
+```
+
+**AssetVersion** (interface)
+```typescript
+interface AssetVersion {
+  url: string
+  mimeType: string | null
+  fileType: string | null
+  size: number | null
+  hash: string | null
+  thumbnail: string | null
+  replacedAt: string
+  replacedBy: string | null
+}
+```
+
 **Asset** (interface)
 ```typescript
 interface Asset {
   id: string
+  collectionId: string
+  site: string
+  productId: string | null
+  proofId: string | null
+  appId: string | null
   url: string
+  * CDN URL of the WebP thumbnail (max 512px longest edge, no crop).
+  * Always .webp — null until thumbnail generation has run.
+  thumbnail: string | null
   name: string
-  mimeType?: string
-  size?: number
-  createdAt?: string
-  metadata?: Record<string, any>
-  assetType?: string
-  type?: string
-  collectionId?: string
-  hash?: string
+  cleanName: string | null
+  assetType: 'Image' | 'Video' | 'Audio' | 'Document'
+  fileType: string | null
+  type: string | null
+  mimeType: string | null
+  contentType: string | null
+  size: number | null
+  width: number | null
+  height: number | null
+  hash: string | null
+  labels: string[]
+  metadata: Record<string, any>
+  versions: AssetVersion[]
+  uploadedBy: string | null
+  uploaderContactId: string | null
+  uploadTokenId: string | null
+  uploaderIp: string | null
+  status: 'active' | 'pending_review' | 'deleted'
+  createdAt: string
+  updatedAt: string
+  deletedAt: string | null
+  * @deprecated Use `thumbnail` instead. Legacy multi-size thumbnail map.
   thumbnails?: {
   x100?: string
   x200?: string
   x512?: string
   [key: string]: string | undefined
   }
-  site?: string
-  cleanName?: string
 }
 ```
 
@@ -2337,6 +2395,117 @@ interface RemoveAssetOptions {
 }
 ```
 
+**AdminListAssetsOptions** (interface)
+```typescript
+interface AdminListAssetsOptions {
+  collectionId: string
+  productId?: string
+  proofId?: string
+  appId?: string
+  assetType?: 'Image' | 'Video' | 'Audio' | 'Document'
+  labels?: string
+  sort?: 'createdAt' | 'name' | 'size' | 'assetType'
+  order?: 'asc' | 'desc'
+  limit?: number
+  offset?: number
+}
+```
+
+**AdminListAssetsResponse** (interface)
+```typescript
+interface AdminListAssetsResponse {
+  data: Asset[]
+  total: number
+  limit: number
+  offset: number
+}
+```
+
+**UpdateAssetOptions** (interface)
+```typescript
+interface UpdateAssetOptions {
+  collectionId: string
+  assetId: string
+  name?: string
+  appId?: string
+  labels?: string[]
+  metadata?: Record<string, any>
+  thumbnail?: string
+}
+```
+
+**ReplaceAssetFileOptions** (interface)
+```typescript
+interface ReplaceAssetFileOptions {
+  collectionId: string
+  assetId: string
+  file: File
+  onProgress?: (percent: number) => void
+}
+```
+
+**DeleteAssetOptions** (interface)
+```typescript
+interface DeleteAssetOptions {
+  collectionId: string
+  assetId: string
+  graceDays?: number
+}
+```
+
+**BulkDeleteAssetsOptions** (interface)
+```typescript
+interface BulkDeleteAssetsOptions {
+  collectionId: string
+  assetIds: string[]
+  graceDays?: number
+}
+```
+
+**RequestUploadTokenOptions** (interface)
+```typescript
+interface RequestUploadTokenOptions {
+  collectionId: string
+  appId: string
+  contactId?: string
+  productId?: string
+  proofId?: string
+}
+```
+
+**UploadTokenPolicy** (interface)
+```typescript
+interface UploadTokenPolicy {
+  requireLevel: 'anonymous' | 'contact' | 'owner'
+  allowedMimeTypes: string[]
+  maxFileSizeBytes: number
+  reviewRequired: boolean
+  productId: string | null
+  proofId: string | null
+}
+```
+
+**UploadTokenResponse** (interface)
+```typescript
+interface UploadTokenResponse {
+  tokenId: string
+  expiresAt: string
+  policy: UploadTokenPolicy
+}
+```
+
+**PublicTokenUploadOptions** (interface)
+```typescript
+interface PublicTokenUploadOptions {
+  collectionId: string
+  tokenId: string
+  file: File
+  name?: string
+  metadata?: Record<string, any>
+  onProgress?: (percent: number) => void
+}
+```
+
 **AssetResponse** = `Asset`
 
 ### attestation
@@ -3190,22 +3359,8 @@ interface Collection {
   id: string
   title: string
   description: string
-  headerImage?: {
-  url: string
-  thumbnails: {
-  x100: string
-  x200: string
-  x512: string
-  }
-  }
-  logoImage?: {
-  url: string
-  thumbnails: {
-  x100: string
-  x200: string
-  x512: string
-  }
-  }
+  headerImage?: AssetRef | null
+  logoImage?: AssetRef | null
   loaderImage?: {
   overwriteName: string
   name: string
@@ -6276,37 +6431,6 @@ interface ProductKey {
 }
 ```
 
-**ProductImageThumbnails** (interface)
-```typescript
-interface ProductImageThumbnails {
-  x100?: string
-  x200?: string
-  x512?: string
-}
-```
-
-**ProductImage** (interface)
-```typescript
-interface ProductImage {
-  id?: string
-  collectionId?: string
-  productId?: string
-  site?: string
-  name?: string
-  cleanName?: string
-  assetType?: string
-  type?: string
-  url?: string
-  thumbnails?: ProductImageThumbnails
-  contentType?: string
-  size?: string | number
-  hash?: string
-  createdAt?: ISODateString | null
-  updatedAt?: ISODateString | null
-  deletedAt?: ISODateString | null
-}
-```
-
 **ProductImageUrlInput** (interface)
 ```typescript
 interface ProductImageUrlInput {
@@ -6378,14 +6502,21 @@ interface ProductWriteInput {
   name: string
   description?: string | null
   gtin?: string | null
-  ownGtin?: boolean | null
+  ownGtin?: string | null
   additionalGtins?: AdditionalGtin[]
   sku?: string | null
+  schemaType?: string | null
   label?: string | null
   status?: string | null
   sortOrder?: number | null
-  heroImage?: ProductImage | ProductImageUrlInput | string | null
+  * Pass the existing `AssetRef` unchanged to keep the current image,
+  * or a URL string / `{ url }` object to import a new file.
+  heroImage?: AssetRef | ProductImageUrlInput | string | null
+  * Pass existing `AssetRef` entries unchanged; replace entries with a URL string
+  * or `{ url }` object to import new files.
+  additionalImages?: Array<AssetRef | ProductImageUrlInput | string>
   facets?: ProductFacetMap
+  tags?: Record<string, boolean>
   data?: Record<string, JsonValue>
   admin?: Record<string, JsonValue>
   extra?: Record<string, JsonValue>
@@ -7634,6 +7765,33 @@ Get an asset by id within a scope (public)
 **remove**(options: RemoveAssetOptions) → `Promise<void>`
 Remove an asset by id within a scope (admin)
 
+**listAdmin**(options: AdminListAssetsOptions) → `Promise<AdminListAssetsResponse>`
+List assets for a collection with full filtering options.
+
+**getAdmin**(collectionId: string, assetId: string) → `Promise<Asset>`
+Get a single asset by ID (admin).
+
+**updateAdmin**(options: UpdateAssetOptions) → `Promise<Asset>`
+Update asset metadata (admin). Use `replaceFile` to swap the file.
+
+**replaceFile**(options: ReplaceAssetFileOptions) → `Promise<Asset>`
+Replace the file of an existing asset. The previous file URL is snapshotted into `versions[]` on the asset.
+
+**deleteAdmin**(options: DeleteAssetOptions) → `Promise<`
+Soft-delete an asset. Schedules CDN purge after `graceDays` (default 30). Recoverable via `restoreAdmin` until purge runs.
+
+**restoreAdmin**(collectionId: string, assetId: string) → `Promise<Asset>`
+Restore a soft-deleted asset (clears `deletedAt`).
+
+**bulkDelete**(options: BulkDeleteAssetsOptions) → `Promise<`
+Soft-delete multiple assets in one request.
+
+**requestUploadToken**(options: RequestUploadTokenOptions) → `Promise<UploadTokenResponse>`
+Request a single-use upload token for a public (unauthenticated) upload. The token encodes the upload policy (allowed types, max size, review requirement). ```typescript const { tokenId, policy } = await asset.requestUploadToken({ collectionId: 'my-collection', appId: 'user-gallery', contactId: contact.id, }) const uploaded = await asset.publicUploadWithToken({ collectionId: 'my-collection', tokenId, file: selectedFile, }) ```
+
+**publicUploadWithToken**(options: PublicTokenUploadOptions) → `Promise<Asset>`
+Upload a file using a single-use upload token (no admin auth required). Assets are created with `status: 'pending_review'` when the token policy has `reviewRequired: true`.
+
 ### async
 
 **enqueueAsyncJob**(collectionId: string,

package/docs/assets.md

@@ -0,0 +1,310 @@
+# Assets
+
+Reference for asset types, endpoints, and public (token-based) uploads.
+
+---
+
+## Asset object
+
+```typescript
+interface Asset {
+  // Identity
+  id:           string            // Postgres UUID — stable permanent identifier
+  collectionId: string            // owning collection
+  site:         string            // alias for collectionId (compat)
+  productId:    string | null     // set when scoped to a product
+  proofId:      string | null     // set when scoped to a proof (ledger entry)
+  appId:        string | null     // app that owns this asset, e.g. 'homepage'
+
+  // File
+  url:          string            // CDN URL of the original file
+  thumbnail:    string | null     // CDN URL of WebP thumbnail (max 512px longest edge, no crop)
+                                  // Always .webp — null until thumbnail generation has run
+  name:         string            // original filename
+  cleanName:    string | null     // filename without extension
+  assetType:    'Image' | 'Video' | 'Audio' | 'Document'
+  fileType:     string | null     // file extension, e.g. 'jpg'
+  type:         string | null     // alias for fileType (compat)
+  mimeType:     string | null     // e.g. 'image/jpeg'
+  contentType:  string | null     // alias for mimeType (compat)
+  size:         number | null     // bytes
+  width:        number | null     // pixels (images only)
+  height:       number | null     // pixels (images only)
+  hash:         string | null     // SHA-256 of file content
+
+  // Organisation
+  labels:       string[]          // arbitrary string labels for filtering
+  metadata:     Record<string, any>
+  versions:     AssetVersion[]    // previous file versions (populated by replace)
+
+  // Upload provenance
+  uploadedBy:        string | null  // Firebase UID of admin uploader
+  uploaderContactId: string | null  // contact ID for public/token uploads
+  uploadTokenId:     string | null  // upload token used (public uploads)
+  uploaderIp:        string | null
+
+  // Lifecycle
+  status:    'active' | 'pending_review' | 'deleted'
+  createdAt: string   // ISO 8601
+  updatedAt: string
+  deletedAt: string | null
+}
+
+interface AssetVersion {
+  url:        string
+  mimeType:   string | null
+  fileType:   string | null
+  size:       number | null
+  hash:       string | null
+  thumbnail:  string | null
+  replacedAt: string
+  replacedBy: string | null
+}
+```
+
+### Thumbnail spec
+
+- Format: WebP, quality 82
+- Max 512px on the longest edge — never upscales
+- Fit: `inside` (letterbox, no crop)
+- SVGs are skipped — `thumbnail` stays null
+- URL always ends in `_thumb.webp`
+
+---
+
+## AssetRef — slim embedded shape
+
+When an asset is referenced inside a product or collection document (e.g. `heroImage`), only three fields are stored to keep documents lean:
+
+```typescript
+interface AssetRef {
+  id:        string        // Postgres UUID — use to fetch the full Asset if needed
+  url:       string        // CDN URL of the original file
+  thumbnail: string | null // WebP thumbnail URL, or null if not yet generated
+}
+```
+
+Render the thumbnail wherever a compact preview is needed; fall back to `url` if null:
+
+```typescript
+function getHeroImageUrl(product: Product): string | null {
+  const ref = product.heroImage
+  if (!ref) return null
+  return ref.thumbnail ?? ref.url
+}
+```
+
+---
+
+## Admin endpoints
+
+All admin endpoints require authentication. Base path: `/api/admin/collection/:collectionId`
+
+### List assets
+
+```
+GET /assets
+```
+
+| Parameter   | Type   | Description |
+|-------------|--------|-------------|
+| `productId` | string | Filter to a specific product |
+| `proofId`   | string | Filter to a specific proof |
+| `appId`     | string | Filter by owning app |
+| `assetType` | string | `Image`, `Video`, `Audio`, `Document` |
+| `labels`    | string | Comma-separated label filter (any match) |
+| `sort`      | string | `createdAt` (default), `name`, `size`, `assetType` |
+| `order`     | string | `desc` (default), `asc` |
+| `limit`     | number | Max results (default 50, max 200) |
+| `offset`    | number | Pagination offset |
+
+**Response:**
+
+```typescript
+{ data: Asset[], total: number, limit: number, offset: number }
+```
+
+**SDK:**
+
+```typescript
+const { data, total } = await Api.asset.listAdmin({
+  collectionId: 'my-collection',
+  assetType: 'Image',
+  labels: 'hero,banner',
+  limit: 20,
+})
+```
+
+---
+
+### Get asset
+
+```
+GET /assets/:assetId
+```
+
+Returns `Asset` or `404`.
+
+**SDK:** `Api.asset.getAdmin(collectionId, assetId)`
+
+---
+
+### Upload asset
+
+```
+POST /assets
+```
+
+Use the existing `Api.asset.upload()` method (file) or `Api.asset.uploadFromUrl()` (URL import).
+
+---
+
+### Update asset metadata
+
+```
+PUT /assets/:assetId
+```
+
+Updates metadata only. Use `/replace` to swap the file.
+
+```typescript
+await Api.asset.updateAdmin({
+  collectionId: 'my-collection',
+  assetId: 'abc123',
+  name: 'New display name',
+  labels: ['hero', 'featured'],
+  metadata: { altText: 'A product photo' },
+})
+```
+
+---
+
+### Replace file
+
+```
+POST /assets/:assetId/replace
+```
+
+Replaces the file; the previous URL is snapshotted into `versions[]`.
+
+```typescript
+await Api.asset.replaceFile({
+  collectionId: 'my-collection',
+  assetId: 'abc123',
+  file: newFile,
+  onProgress: (pct) => console.log(pct),
+})
+```
+
+---
+
+### Delete asset (soft)
+
+```
+DELETE /assets/:assetId?graceDays=30
+```
+
+Sets `deletedAt` and schedules CDN purge after `graceDays` (default 30). Recoverable until purge.
+
+```typescript
+await Api.asset.deleteAdmin({ collectionId: 'my-collection', assetId: 'abc123', graceDays: 7 })
+```
+
+---
+
+### Restore asset
+
+```
+POST /assets/:assetId/restore
+```
+
+Clears `deletedAt`. Asset becomes active again.
+
+```typescript
+await Api.asset.restoreAdmin('my-collection', 'abc123')
+```
+
+---
+
+### Bulk delete
+
+```
+POST /assets/bulk-delete
+```
+
+```typescript
+await Api.asset.bulkDelete({
+  collectionId: 'my-collection',
+  assetIds: ['abc123', 'def456'],
+  graceDays: 14,
+})
+// Returns { deleted: 2 }
+```
+
+---
+
+## Public (token-based) uploads
+
+For anonymous or contact-initiated uploads from the portal — no admin auth required.
+
+### 1. Request an upload token
+
+```typescript
+const { tokenId, expiresAt, policy } = await Api.asset.requestUploadToken({
+  collectionId: 'my-collection',
+  appId: 'user-gallery',
+  contactId: contact.id,   // required when policy requireLevel = 'contact'
+})
+```
+
+The `policy` describes what the token allows:
+
+```typescript
+interface UploadTokenPolicy {
+  requireLevel:     'anonymous' | 'contact' | 'owner'
+  allowedMimeTypes: string[]
+  maxFileSizeBytes: number
+  reviewRequired:   boolean   // when true, asset is created as 'pending_review'
+  productId:        string | null
+  proofId:          string | null
+}
+```
+
+Tokens are **single-use**, TTL 900 s.
+
+### 2. Upload with token
+
+```typescript
+const asset = await Api.asset.publicUploadWithToken({
+  collectionId: 'my-collection',
+  tokenId,
+  file: selectedFile,
+  onProgress: (pct) => setProgress(pct),
+})
+```
+
+Assets are created with `status: 'pending_review'` when `reviewRequired: true`. An admin must review and set `status` to `'active'` before the asset appears publicly.
+
+---
+
+## Writing image fields on products and collections
+
+`heroImage`, `additionalImages` (products), `logoImage`, and `headerImage` (collections) all use the slim `AssetRef` shape when read.
+
+When writing:
+
+- **Pass the `AssetRef` back unchanged** to keep the current image (server detects the UUID and skips re-processing).
+- **Pass a URL string or `{ url }`** to import a new file — the server fetches/registers it and returns the resulting `AssetRef`.
+
+```typescript
+// Keep existing image
+await Api.products.update(collectionId, productId, {
+  name: 'New name',
+  heroImage: product.heroImage,  // AssetRef — not re-processed
+})
+
+// Import a new image
+await Api.products.update(collectionId, productId, {
+  heroImage: 'https://example.com/new-image.jpg',
+})
+```

package/docs/liquid-templates.md

@@ -95,9 +95,7 @@ A **Product** represents a type or definition of a physical or digital item. Pro
 | `product.gtin` | string | Global Trade Item Number |
 | `product.type` | string | Product type from standard types |
 | `product.heroImage.url` | string | Primary product image URL |
-| `product.heroImage.thumbnails.x100` | string | 100px thumbnail |
-| `product.heroImage.thumbnails.x200` | string | 200px thumbnail |
-| `product.heroImage.thumbnails.x512` | string | 512px thumbnail |
+| `product.heroImage.thumbnail` | string | WebP thumbnail URL (max 512px longest edge), or null if not yet generated |
 | `product.tags` | object | Tag map with boolean values |
 | `product.data` | object | Flexible key-value data map |
 | `product.admin` | object | Admin-only configuration |

package/docs/overview.md

@@ -48,6 +48,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | Topic | File | When to Use |
 |-------|------|-------------|
 | **API Reference** | `docs/API_SUMMARY.md` | Complete SDK function reference, types, error handling |
+| **Assets** | `docs/assets.md` | Asset object, AssetRef, upload, replace, soft-delete, restore, bulk-delete, public token-based uploads |
 | **Building React Components** | `docs/building-react-components.md` | **READ THIS FIRST** — Dual-mode rendering, router rules, useAppContext pattern |
 | **Multi-Page Architecture** | `docs/mpa.md` | Build pipeline, entry points, multi-page setup, content hashing |
 | **AI & Chat** | `docs/ai.md` | Chat completions, RAG, streaming, tool calling, voice, podcasts, TTS |