@proveanything/smartlinks 1.9.2 → 1.9.4

package/docs/translations.md

@@ -0,0 +1,253 @@
+# 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,
+})
+```
+
+## 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.

package/openapi.yaml

@@ -53,6 +53,7 @@ tags:
   - name: segments
   - name: tags
   - name: template
+  - name: translations
   - name: variant
 security:
   - bearerAuth: []
@@ -7280,6 +7281,107 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/TemplateRenderRequest"
+  /admin/collection/{collectionId}/translations/{translationId}:
+    get:
+      tags:
+        - translations
+      summary: translations.get
+      operationId: translations_get
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: translationId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TranslationRecord"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+    patch:
+      tags:
+        - translations
+      summary: translations.update
+      operationId: translations_update
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: translationId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TranslationRecord"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/TranslationUpdateRequest"
+  /admin/collection/{collectionId}/translations{query}:
+    get:
+      tags:
+        - translations
+      summary: translations.list
+      operationId: translations_list
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: query
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TranslationListResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /api/admin/auth/push:
     get:
       tags:
@@ -10737,6 +10839,38 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /public/collection/{collectionId}/translations/lookup:
+    post:
+      tags:
+        - translations
+      summary: translations.lookup
+      operationId: translations_lookup
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TranslationLookupResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/TranslationLookupRequest"
   /public/location/{locationId}:
     get:
       tags:
@@ -20922,6 +21056,236 @@ components:
           additionalProperties: true
       required:
         - ok
+    TranslationContext:
+      type: object
+      properties:
+        surface:
+          type: string
+        field:
+          type: string
+    TranslationLookupRequestBase:
+      type: object
+      properties:
+        targetLanguage:
+          type: string
+        sourceLanguage:
+          type: string
+        mode:
+          $ref: "#/components/schemas/TranslationLookupMode"
+        contentType:
+          $ref: "#/components/schemas/TranslationContentType"
+        context:
+          $ref: "#/components/schemas/TranslationContext"
+        returnMeta:
+          type: boolean
+      required:
+        - targetLanguage
+    TranslationLookupSingleRequest:
+      type: object
+      properties:
+        text:
+          type: string
+        texts: {}
+      required:
+        - text
+    TranslationLookupBatchRequest:
+      type: object
+      properties:
+        text: {}
+        texts:
+          type: array
+          items:
+            type: string
+      required:
+        - texts
+    TranslationLookupItem:
+      type: object
+      properties:
+        index:
+          type: number
+        hash:
+          type: string
+        sourceText:
+          type: string
+        translatedText:
+          type: string
+        status:
+          $ref: "#/components/schemas/TranslationItemStatus"
+        provider:
+          type: string
+        model:
+          type: string
+        isOverride:
+          type: boolean
+        quality:
+          $ref: "#/components/schemas/TranslationQuality"
+        createdAt:
+          type: string
+        updatedAt:
+          type: string
+      required:
+        - index
+        - hash
+        - sourceText
+    TranslationLookupResponse:
+      type: object
+      properties:
+        targetLanguage:
+          type: string
+        sourceLanguage:
+          type: string
+        mode:
+          $ref: "#/components/schemas/TranslationLookupMode"
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/TranslationLookupItem"
+      required:
+        - targetLanguage
+        - items
+    ResolvedTranslationItem:
+      type: object
+      properties:
+        cacheSource:
+          type: string
+          enum:
+            - local
+            - remote
+        expiresAt:
+          type: number
+    ResolvedTranslationResponse:
+      type: object
+      properties:
+        targetLanguage:
+          type: string
+        sourceLanguage:
+          type: string
+        mode:
+          $ref: "#/components/schemas/TranslationLookupMode"
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/ResolvedTranslationItem"
+      required:
+        - targetLanguage
+        - items
+    TranslationHashOptions:
+      type: object
+      properties:
+        trim:
+          type: boolean
+        collapseWhitespace:
+          type: boolean
+        unicodeNormalization:
+          type: string
+          enum:
+            - NFC
+            - NFKC
+    TranslationResolveOptions:
+      type: object
+      properties:
+        useLocalCache:
+          type: boolean
+        refreshLocalCache:
+          type: boolean
+        localCacheTtlMs:
+          type: number
+        hashOptions:
+          $ref: "#/components/schemas/TranslationHashOptions"
+    TranslationRecord:
+      type: object
+      properties:
+        id:
+          type: string
+        collectionId:
+          type: string
+        sourceHash:
+          type: string
+        sourceText:
+          type: string
+        sourceLanguage:
+          type: string
+        targetLanguage:
+          type: string
+        contentType:
+          type: string
+        contextKey:
+          type: string
+        translatedText:
+          type: string
+        provider:
+          type: string
+        model:
+          type: string
+        quality:
+          $ref: "#/components/schemas/TranslationQuality"
+        isOverride:
+          type: boolean
+        metadata:
+          type: object
+          additionalProperties: true
+        createdAt:
+          type: string
+        updatedAt:
+          type: string
+      required:
+        - id
+        - collectionId
+        - sourceHash
+        - sourceText
+        - targetLanguage
+        - contentType
+        - translatedText
+        - quality
+        - isOverride
+        - createdAt
+        - updatedAt
+    TranslationListParams:
+      type: object
+      properties:
+        targetLanguage:
+          type: string
+        sourceLanguage:
+          type: string
+        contentType:
+          type: string
+        contextKey:
+          type: string
+        q:
+          type: string
+        isOverride:
+          type: boolean
+        limit:
+          type: number
+        offset:
+          type: number
+    TranslationListResponse:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/TranslationRecord"
+        total:
+          type: number
+        limit:
+          type: number
+        offset:
+          type: number
+      required:
+        - items
+    TranslationUpdateRequest:
+      type: object
+      properties:
+        translatedText:
+          type: string
+        isOverride:
+          type: boolean
+        quality:
+          $ref: "#/components/schemas/TranslationQuality"
+        metadata:
+          type: object
+          additionalProperties: true
     AppConfigOptions:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",