@proveanything/smartlinks 1.9.4 → 1.9.5

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.4  |  Generated: 2026-03-23T19:52:46.756Z
+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
@@ -6560,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

package/dist/docs/translations.md

@@ -92,6 +92,88 @@ const response = await translations.lookup('collection-123', {
 })
 ```
 
+## 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.