@proveanything/smartlinks 1.9.3 → 1.9.5

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.3  |  Generated: 2026-03-23T18:12:23.239Z
+Version: 1.9.5  |  Generated: 2026-03-23T20:19:00.201Z
 
 This is a concise summary of all available API functions and types.
 
@@ -10,13 +10,16 @@ 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
 - **[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) 
+- **[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
+- **[Utilities](utils.md)** - Helper functions for building portal paths, URLs, and common tasks
 - **[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
@@ -110,6 +113,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **realtime** - Functions for realtime operations
 - **tags** - Functions for tags operations
 - **template** - Functions for template operations
+- **translations** - Functions for translations operations
 
 ## HTTP Utilities
 
@@ -6343,6 +6347,153 @@ interface TemplateRenderSourceResponse {
 
 **TemplatePublic** = `TemplateBase`
 
+### translations
+
+**TranslationContext** (interface)
+```typescript
+interface TranslationContext {
+  surface?: string
+  field?: string
+  [key: string]: TranslationContextValue | undefined
+}
+```
+
+**TranslationLookupRequestBase** (interface)
+```typescript
+interface TranslationLookupRequestBase {
+  targetLanguage: string
+  sourceLanguage?: string
+  mode?: TranslationLookupMode
+  contentType?: TranslationContentType
+  context?: TranslationContext
+  returnMeta?: boolean
+}
+```
+
+**TranslationLookupItem** (interface)
+```typescript
+interface TranslationLookupItem {
+  index: number
+  hash: string
+  sourceText: string
+  translatedText?: string
+  status?: TranslationItemStatus
+  provider?: string
+  model?: string
+  isOverride?: boolean
+  quality?: TranslationQuality
+  createdAt?: string
+  updatedAt?: string
+}
+```
+
+**TranslationLookupResponse** (interface)
+```typescript
+interface TranslationLookupResponse {
+  targetLanguage: string
+  sourceLanguage?: string
+  mode?: TranslationLookupMode
+  items: TranslationLookupItem[]
+}
+```
+
+**ResolvedTranslationResponse** (interface)
+```typescript
+interface ResolvedTranslationResponse {
+  targetLanguage: string
+  sourceLanguage?: string
+  mode?: TranslationLookupMode
+  items: ResolvedTranslationItem[]
+}
+```
+
+**TranslationHashOptions** (interface)
+```typescript
+interface TranslationHashOptions {
+  trim?: boolean
+  collapseWhitespace?: boolean
+  unicodeNormalization?: 'NFC' | 'NFKC' | false
+}
+```
+
+**TranslationResolveOptions** (interface)
+```typescript
+interface TranslationResolveOptions {
+  useLocalCache?: boolean
+  refreshLocalCache?: boolean
+  localCacheTtlMs?: number
+  hashOptions?: TranslationHashOptions
+}
+```
+
+**TranslationRecord** (interface)
+```typescript
+interface TranslationRecord {
+  id: string
+  collectionId: string
+  sourceHash: string
+  sourceText: string
+  sourceLanguage?: string
+  targetLanguage: string
+  contentType: string
+  contextKey?: string | null
+  translatedText: string
+  provider?: string | null
+  model?: string | null
+  quality: TranslationQuality
+  isOverride: boolean
+  metadata?: Record<string, any>
+  createdAt: string
+  updatedAt: string
+}
+```
+
+**TranslationListParams** (interface)
+```typescript
+interface TranslationListParams {
+  targetLanguage?: string
+  sourceLanguage?: string
+  contentType?: string
+  contextKey?: string
+  q?: string
+  isOverride?: boolean
+  limit?: number
+  offset?: number
+}
+```
+
+**TranslationListResponse** (interface)
+```typescript
+interface TranslationListResponse {
+  items: TranslationRecord[]
+  total?: number
+  limit?: number
+  offset?: number
+}
+```
+
+**TranslationUpdateRequest** (interface)
+```typescript
+interface TranslationUpdateRequest {
+  translatedText?: string
+  isOverride?: boolean
+  quality?: TranslationQuality
+  metadata?: Record<string, any>
+}
+```
+
+**TranslationLookupMode** = `'cache-fill' | 'cache-only'`
+
+**TranslationContentType** = `'text/plain' | 'text/html' | 'text/x-liquid' | (string & {})`
+
+**TranslationQuality** = `'machine' | 'human' | 'passthrough' | (string & {})`
+
+**TranslationItemStatus** = `'cached' | 'generated' | 'miss' | 'passthrough' | 'local-cache' | (string & {})`
+
+**TranslationContextValue** = `string | number | boolean | null`
+
+**TranslationLookupRequest** = `TranslationLookupSingleRequest | TranslationLookupBatchRequest`
+
 ### variant
 
 **VariantResponse** = `any`
@@ -6412,6 +6563,140 @@ type VerifyTokenResponse = {
 }
 ```
 
+### conditions (utils)
+
+**BaseCondition** (interface)
+```typescript
+interface BaseCondition {
+  type: string
+  contains?: boolean
+  passes?: boolean
+}
+```
+
+**ConditionSet** (interface)
+```typescript
+interface ConditionSet {
+  id?: string
+  type?: 'and' | 'or'
+  conditions?: Condition[]
+}
+```
+
+**UserLocation** (interface)
+```typescript
+interface UserLocation {
+  country?: string
+  latitude?: number
+  longitude?: number
+}
+```
+
+**PlatformInfo** (interface)
+```typescript
+interface PlatformInfo {
+  android?: boolean
+  ios?: boolean
+  win?: boolean
+  mac?: boolean
+}
+```
+
+**StatsInfo** (interface)
+```typescript
+interface StatsInfo {
+  version?: string | null
+  platform?: PlatformInfo
+  mobile?: boolean
+}
+```
+
+**UserInfo** (interface)
+```typescript
+interface UserInfo {
+  valid: boolean
+  uid?: string
+  location?: UserLocation
+  groups?: string[]
+}
+```
+
+**ProductInfo** (interface)
+```typescript
+interface ProductInfo {
+  id: string
+  tags?: Record<string, any>
+}
+```
+
+**ProofInfo** (interface)
+```typescript
+interface ProofInfo {
+  id?: string
+  userId?: string
+  claimable?: boolean
+  virtual?: boolean
+}
+```
+
+**CollectionInfo** (interface)
+```typescript
+interface CollectionInfo {
+  id: string
+  roles?: Record<string, any>
+}
+```
+
+**ConditionParams** (interface)
+```typescript
+interface ConditionParams {
+  condition?: ConditionSet
+  conditionId?: string
+  conditionStack?: string[]
+  user?: UserInfo
+  product?: ProductInfo
+  proof?: ProofInfo
+  collection?: CollectionInfo
+  stats?: StatsInfo
+  fetchCondition?: (collectionId: string, conditionId: string) => Promise<ConditionSet | null>
+  getLocation?: () => Promise<{ latitude: number; longitude: number }>
+  debugConditions?: boolean | ConditionDebugOptions
+  [key: string]: any
+}
+```
+
+**ConditionDebugOptions** (interface)
+```typescript
+interface ConditionDebugOptions {
+  enabled?: boolean
+  logger?: ConditionDebugLogger
+  label?: string
+}
+```
+
+**RegionKey** = `keyof typeof REGION_COUNTRIES`
+
+**Condition** = ``
+
+**ConditionDebugLogger** = `(...args: any[]) => void`
+
+### paths (utils)
+
+**PortalPathParams** (interface)
+```typescript
+interface PortalPathParams {
+  collection: Collection | { shortId: string; portalUrl?: string }
+  product?: Product
+  productId?: string
+  batch?: BatchResponse
+  batchId?: string
+  variant?: { id: string } | string
+  proof?: Proof | string
+  queryParams?: Record<string, string>
+  pathOnly?: boolean
+}
+```
+
 ## API Functions
 
 ### analytics.admin
@@ -8169,6 +8454,33 @@ Reverse lookup by ref via POST (public). `POST /public/collection/:collectionId/
 **renderSource**(collectionId: string,
     body: TemplateRenderSourceRequest) → `Promise<TemplateRenderSourceResponse>`
 
+### translations
+
+**hashText**(text: string, options?: TranslationHashOptions) → `Promise<string>`
+
+**hashTexts**(texts: string[], options?: TranslationHashOptions) → `Promise<string[]>`
+
+**normalizeText**(text: string, options?: TranslationHashOptions) → `string`
+
+**lookup**(collectionId: string,
+    body: TranslationLookupRequest) → `Promise<TranslationLookupResponse>`
+
+**resolve**(collectionId: string,
+    body: TranslationLookupRequest,
+    options: TranslationResolveOptions = {}) → `Promise<ResolvedTranslationResponse>`
+
+**list**(collectionId: string,
+    params?: TranslationListParams) → `Promise<TranslationListResponse>`
+
+**get**(collectionId: string,
+    translationId: string) → `Promise<TranslationRecord>`
+
+**update**(collectionId: string,
+    translationId: string,
+    body: TranslationUpdateRequest) → `Promise<TranslationRecord>`
+
+**clearLocalCache**(collectionId?: string) → `Promise<void>`
+
 ### tts
 
 **generate**(collectionId: string,

package/docs/overview.md

@@ -49,6 +49,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **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 |
 | **Analytics** | `docs/analytics.md` | Fire-and-forget page/click/tag analytics plus admin dashboard queries |
+| **Translations** | `docs/translations.md` | Runtime translation lookup, local-first IndexedDB caching, and translation admin APIs |
 | **Theming** | `docs/theme.system.md` | Implementing dynamic themes via URL params or postMessage |
 | **Theme Defaults** | `docs/theme-defaults.md` | Default colour values for light/dark modes |
 | **Internationalization** | `docs/i18n.md` | Adding multi-language support, translation patterns |

package/docs/translations.md

@@ -0,0 +1,335 @@
+# SmartLinks Translations
+
+Runtime translation API for collection-scoped UI strings and content blocks, with optional browser-side IndexedDB caching.
+
+This guide covers the new `translations` namespace in the SDK.
+
+## When To Use This
+
+Use `translations` when you need to translate dynamic runtime content such as:
+
+- product descriptions fetched from APIs
+- customer-configurable portal copy
+- CMS-driven long-form content blocks
+- repeated UI strings that should be cached per collection and language
+
+This is different from the static app-local i18n flow in [i18n.md](i18n.md), which is still the right choice for build-time translation keys such as button labels and route titles.
+
+## Two Levels Of API
+
+The SDK exposes two ways to work with translations:
+
+### 1. `translations.lookup(...)`
+
+This is the direct backend API wrapper.
+
+- calls `POST /public/collection/:collectionId/translations/lookup`
+- sends one string or many strings
+- returns the server response as-is
+- does not check local IndexedDB first
+
+### 2. `translations.resolve(...)`
+
+This is the enriched client helper for front-end use.
+
+- hashes each source string locally
+- checks the browser-local translation cache first
+- sends only cache misses to the backend
+- stores successful results back into IndexedDB
+- preserves the original input order, including duplicates
+
+For browser apps, `resolve(...)` is the recommended default.
+
+## Quick Start
+
+```ts
+import { initializeApi, translations } from '@proveanything/smartlinks'
+
+initializeApi({ baseURL: 'https://smartlinks.app/api/v1' })
+
+const response = await translations.resolve('collection-123', {
+  targetLanguage: 'fr',
+  sourceLanguage: 'en',
+  context: {
+    surface: 'portal-product-page',
+    field: 'description',
+  },
+  texts: [
+    'Welcome to the product page',
+    'Scan to verify authenticity',
+  ],
+})
+
+console.log(response.items.map((item) => item.translatedText))
+```
+
+## Raw Backend Lookup
+
+Use `lookup(...)` if you want the SDK to stay close to the backend contract.
+
+```ts
+const response = await translations.lookup('collection-123', {
+  targetLanguage: 'de',
+  text: 'Claim your item',
+})
+
+console.log(response.items[0].translatedText)
+```
+
+### Batch Lookup
+
+```ts
+const response = await translations.lookup('collection-123', {
+  targetLanguage: 'es',
+  sourceLanguage: 'en',
+  mode: 'cache-fill',
+  contentType: 'text/plain',
+  texts: [
+    'Welcome to the product page',
+    'Scan to verify authenticity',
+  ],
+  returnMeta: true,
+})
+```
+
+## Content Types
+
+`contentType` is part of the translation cache identity. Use it to tell the backend what kind of content is being translated so it can preserve structure correctly.
+
+### `text/plain`
+
+Use this for normal strings, paragraphs, labels, and other plain text content with no markup.
+
+```ts
+await translations.resolve('collection-123', {
+  targetLanguage: 'fr',
+  sourceLanguage: 'en',
+  contentType: 'text/plain',
+  texts: [
+    'Welcome to the product page',
+    'Scan to verify authenticity',
+  ],
+})
+```
+
+### `text/html`
+
+Use this when the source contains HTML tags that must survive translation unchanged. This is important for rich text descriptions, CMS content, and formatted snippets.
+
+```ts
+await translations.resolve('collection-123', {
+  targetLanguage: 'de',
+  sourceLanguage: 'en',
+  contentType: 'text/html',
+  context: {
+    surface: 'portal-product-page',
+    field: 'rich-description',
+  },
+  texts: [
+    '<p>Welcome to the <strong>product page</strong>.</p>',
+    '<p>Scan the tag to <a href="/verify">verify authenticity</a>.</p>',
+  ],
+})
+```
+
+Use `text/html` when you want the translation system to preserve tags such as:
+
+- `<p>`, `<strong>`, `<em>`
+- `<ul>`, `<li>`
+- `<a>`
+- inline markup embedded in CMS-rendered HTML
+
+### `text/x-liquid`
+
+Use this when the content includes Liquid syntax that must be preserved exactly, including output tags, control-flow blocks, and filters.
+
+```ts
+await translations.resolve('collection-123', {
+  targetLanguage: 'es',
+  sourceLanguage: 'en',
+  contentType: 'text/x-liquid',
+  context: {
+    surface: 'portal-email-template',
+    field: 'body',
+  },
+  texts: [
+    'Hello {{ customer.first_name }}, your item {{ product.title }} is ready.',
+    '{% if claimable %}Claim your item{% else %}View item details{% endif %}',
+  ],
+})
+```
+
+Use `text/x-liquid` when the source includes constructs such as:
+
+- `{{ customer.first_name }}`
+- `{{ product.title | upcase }}`
+- `{% if claimable %}...{% endif %}`
+- loop or conditional blocks used in templates
+
+### Choosing The Right Value
+
+- use `text/plain` for normal strings with no markup
+- use `text/html` when HTML tags are part of the source and must be preserved
+- use `text/x-liquid` when Liquid template syntax is part of the source and must be preserved
+
+Do not mix plain text, HTML, and Liquid under the same `contentType` if you want stable cache keys and predictable translation behavior.
+
+## Local-First Resolution
+
+`resolve(...)` is intended for browser rendering paths where repeated translations should not keep hitting the network.
+
+```ts
+const response = await translations.resolve('collection-123', {
+  targetLanguage: 'fr',
+  sourceLanguage: 'en',
+  texts: [
+    'Welcome to the product page',
+    'Welcome to the product page',
+    'Scan to verify authenticity',
+  ],
+})
+
+for (const item of response.items) {
+  console.log(item.index, item.cacheSource, item.translatedText)
+}
+```
+
+### Default Client Cache Behavior
+
+- cache backend hits in IndexedDB when available
+- fall back to in-memory cache when IndexedDB is unavailable
+- expire entries lazily on read
+- keep entries for 90 days by default
+
+IndexedDB does not provide native time-based expiry, so the SDK stores `expiresAt` and evicts stale records when reading them.
+
+### Configure Local Cache TTL
+
+```ts
+await translations.resolve('collection-123', {
+  targetLanguage: 'fr',
+  texts: ['Limited edition'],
+}, {
+  localCacheTtlMs: 180 * 24 * 60 * 60_000,
+})
+```
+
+### Force A Fresh Remote Lookup
+
+```ts
+await translations.resolve('collection-123', {
+  targetLanguage: 'fr',
+  texts: ['Welcome back'],
+}, {
+  refreshLocalCache: true,
+})
+```
+
+### Disable The Local Cache
+
+```ts
+await translations.resolve('collection-123', {
+  targetLanguage: 'fr',
+  texts: ['Welcome back'],
+}, {
+  useLocalCache: false,
+})
+```
+
+## Context Matters
+
+The same source string can require different translations depending on where it appears. Pass stable context whenever the meaning can change.
+
+```ts
+await translations.resolve('collection-123', {
+  targetLanguage: 'fr',
+  texts: ['Claim'],
+  context: {
+    surface: 'portal-product-page',
+    field: 'cta-button',
+  },
+})
+```
+
+The SDK derives a deterministic local cache key from `context` so browser-local entries do not collide across different UI surfaces.
+
+## Hashing Helpers
+
+The SDK also exposes the normalization and hashing helpers used by the local cache flow.
+
+```ts
+const hash = await translations.hashText('Welcome to the product page')
+
+const hashes = await translations.hashTexts([
+  'Welcome to the product page',
+  'Scan to verify authenticity',
+])
+
+const normalized = translations.normalizeText('  Hello\r\nWorld  ')
+```
+
+By default the hash path:
+
+- normalizes CRLF to LF
+- trims surrounding whitespace
+- applies Unicode NFC normalization
+- preserves interior whitespace unless `collapseWhitespace: true` is set
+
+## Clearing Local Cache
+
+Clear all locally cached translations:
+
+```ts
+await translations.clearLocalCache()
+```
+
+Clear only one collection's local entries:
+
+```ts
+await translations.clearLocalCache('collection-123')
+```
+
+## Admin APIs
+
+The namespace also exposes basic admin translation management.
+
+### List
+
+```ts
+const page = await translations.list('collection-123', {
+  targetLanguage: 'fr',
+  q: 'authenticity',
+  limit: 20,
+  offset: 0,
+})
+```
+
+### Get One
+
+```ts
+const record = await translations.get('collection-123', 'translation-id')
+```
+
+### Update One
+
+```ts
+const updated = await translations.update('collection-123', 'translation-id', {
+  translatedText: 'Bienvenue sur la page produit',
+  isOverride: true,
+  quality: 'human',
+})
+```
+
+## Recommended Usage Pattern
+
+For front-end rendering:
+
+1. Use static app-local i18n for fixed UI keys.
+2. Use `translations.resolve(...)` for dynamic runtime content.
+3. Always pass `context` for ambiguous strings.
+4. Prefer batched requests for multiple strings on the same screen.
+
+For back-office or tooling flows:
+
+1. Use `translations.lookup(...)` for direct backend access.
+2. Use `translations.list/get/update` for translation review and correction workflows.