@proveanything/smartlinks 1.9.2 → 1.9.4

package/README.md

@@ -22,6 +22,7 @@ If you're new to the SDK, this is the easiest path:
 
 - [docs/ai.md](docs/ai.md) — AI responses, chat, RAG, voice, streaming, and product assistants
 - [docs/analytics.md](docs/analytics.md) — fire-and-forget web analytics, tag scan telemetry, and dashboard queries
+- [docs/translations.md](docs/translations.md) — runtime translation lookup, browser-side caching, and translation admin flows
 - [docs/widgets.md](docs/widgets.md) — embeddable React components
 - [docs/realtime.md](docs/realtime.md) — subscriptions and live updates
 - [docs/iframe-responder.md](docs/iframe-responder.md) — iframe integration and parent/child messaging
@@ -31,6 +32,7 @@ If you're new to the SDK, this is the easiest path:
 
 - **Build an AI assistant** → start with [docs/ai.md](docs/ai.md)
 - **Track page views, clicks, or tag scans** → start with [docs/analytics.md](docs/analytics.md)
+- **Translate dynamic content with local browser caching** → start with [docs/translations.md](docs/translations.md)
 - **Fetch collections/products** → see [Quick start](README.md#quick-start)
 - **Authenticate admins or end users** → see [Authentication](README.md#authentication)
 - **Upload and manage files** → see [Assets](README.md#assets)
@@ -42,6 +44,7 @@ For the full list of functions and types, see the API summary:
 **Documentation:**
 - [AI & Chat Completions](docs/ai.md) - Chat completions, RAG, voice integration
 - [Analytics](docs/analytics.md) - Fire-and-forget analytics tracking, tag scans, and dashboard queries
+- [Translations](docs/translations.md) - Runtime translation lookup, browser-side IndexedDB caching, and admin translation management
 - [Widgets](docs/widgets.md) - Embeddable React components
 - [Realtime](docs/realtime.md) - Realtime data updates
 - [iframe Responder](docs/iframe-responder.md) - iframe integration

package/dist/api/index.d.ts

@@ -35,3 +35,4 @@ export { app } from "./appObjects";
 export { attestations } from "./attestations";
 export { containers } from "./containers";
 export { loyalty } from "./loyalty";
+export { translations } from "./translations";

package/dist/api/index.js

@@ -38,3 +38,4 @@ export { app } from "./appObjects";
 export { attestations } from "./attestations";
 export { containers } from "./containers";
 export { loyalty } from "./loyalty";
+export { translations } from "./translations";

package/dist/api/translations.d.ts

@@ -0,0 +1,12 @@
+import type { ResolvedTranslationResponse, TranslationHashOptions, TranslationListParams, TranslationListResponse, TranslationLookupRequest, TranslationLookupResponse, TranslationRecord, TranslationResolveOptions, TranslationUpdateRequest } from '../types/translations';
+export declare namespace translations {
+    function hashText(text: string, options?: TranslationHashOptions): Promise<string>;
+    function hashTexts(texts: string[], options?: TranslationHashOptions): Promise<string[]>;
+    function normalizeText(text: string, options?: TranslationHashOptions): string;
+    function lookup(collectionId: string, body: TranslationLookupRequest): Promise<TranslationLookupResponse>;
+    function resolve(collectionId: string, body: TranslationLookupRequest, options?: TranslationResolveOptions): Promise<ResolvedTranslationResponse>;
+    function list(collectionId: string, params?: TranslationListParams): Promise<TranslationListResponse>;
+    function get(collectionId: string, translationId: string): Promise<TranslationRecord>;
+    function update(collectionId: string, translationId: string, body: TranslationUpdateRequest): Promise<TranslationRecord>;
+    function clearLocalCache(collectionId?: string): Promise<void>;
+}

package/dist/api/translations.js

@@ -0,0 +1,217 @@
+import { patch, post, request } from '../http';
+import { clearCachedTranslations, deriveTranslationContextKey, getCachedTranslations, getDefaultTranslationCacheTtlMs, hashTranslationText, normalizeTranslationText, setCachedTranslations, } from '../translationCache';
+function normalizeLookupRequest(body) {
+    var _a, _b, _c;
+    const texts = Array.isArray(body.texts)
+        ? [...(body.texts)]
+        : typeof body.text === 'string'
+            ? [body.text]
+            : [];
+    if (!body.targetLanguage) {
+        throw new Error('[smartlinks] translations.lookup requires targetLanguage');
+    }
+    if (texts.length === 0) {
+        throw new Error('[smartlinks] translations.lookup requires text or texts');
+    }
+    return {
+        targetLanguage: body.targetLanguage,
+        sourceLanguage: (_a = body.sourceLanguage) !== null && _a !== void 0 ? _a : 'en',
+        mode: (_b = body.mode) !== null && _b !== void 0 ? _b : 'cache-fill',
+        contentType: (_c = body.contentType) !== null && _c !== void 0 ? _c : 'text/plain',
+        contextKey: deriveTranslationContextKey(body.context),
+        requestBody: {
+            targetLanguage: body.targetLanguage,
+            sourceLanguage: body.sourceLanguage,
+            mode: body.mode,
+            contentType: body.contentType,
+            context: body.context,
+            returnMeta: body.returnMeta,
+            texts,
+        },
+        texts,
+    };
+}
+function buildTranslationListQuery(params = {}) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null)
+            continue;
+        query.append(key, String(value));
+    }
+    const queryString = query.toString();
+    return queryString ? `?${queryString}` : '';
+}
+function sameLanguage(left, right) {
+    return left.trim().toLowerCase() === right.trim().toLowerCase();
+}
+function toResolvedItem(item, index, cacheSource) {
+    return Object.assign(Object.assign({}, item), { index,
+        cacheSource });
+}
+export var translations;
+(function (translations) {
+    async function hashText(text, options) {
+        return hashTranslationText(text, options);
+    }
+    translations.hashText = hashText;
+    async function hashTexts(texts, options) {
+        return Promise.all(texts.map((text) => hashTranslationText(text, options)));
+    }
+    translations.hashTexts = hashTexts;
+    function normalizeText(text, options) {
+        return normalizeTranslationText(text, options);
+    }
+    translations.normalizeText = normalizeText;
+    async function lookup(collectionId, body) {
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/translations/lookup`;
+        const normalized = normalizeLookupRequest(body);
+        return post(path, normalized.requestBody);
+    }
+    translations.lookup = lookup;
+    async function resolve(collectionId, body, options = {}) {
+        var _a, _b, _c;
+        const normalized = normalizeLookupRequest(body);
+        const { useLocalCache = true, refreshLocalCache = false, localCacheTtlMs = getDefaultTranslationCacheTtlMs(), hashOptions, } = options;
+        const hashes = await Promise.all(normalized.texts.map((text) => hashTranslationText(text, hashOptions)));
+        const results = new Array(normalized.texts.length);
+        if (sameLanguage(normalized.sourceLanguage, normalized.targetLanguage)) {
+            const passthroughItems = normalized.texts.map((text, index) => ({
+                index,
+                hash: hashes[index],
+                sourceText: text,
+                translatedText: text,
+                status: 'passthrough',
+                quality: 'passthrough',
+                cacheSource: 'local',
+                expiresAt: Date.now() + localCacheTtlMs,
+            }));
+            if (useLocalCache) {
+                await setCachedTranslations({
+                    collectionId,
+                    sourceLanguage: normalized.sourceLanguage,
+                    targetLanguage: normalized.targetLanguage,
+                    contentType: normalized.contentType,
+                    contextKey: normalized.contextKey,
+                    ttlMs: localCacheTtlMs,
+                    items: passthroughItems.map((item) => ({ hash: item.hash, item })),
+                });
+            }
+            return {
+                targetLanguage: normalized.targetLanguage,
+                sourceLanguage: normalized.sourceLanguage,
+                mode: normalized.mode,
+                items: passthroughItems,
+            };
+        }
+        const cachedByHash = useLocalCache && !refreshLocalCache
+            ? await getCachedTranslations({
+                collectionId,
+                sourceLanguage: normalized.sourceLanguage,
+                targetLanguage: normalized.targetLanguage,
+                contentType: normalized.contentType,
+                contextKey: normalized.contextKey,
+                hashes,
+            })
+            : new Map();
+        const missingIndexes = [];
+        for (let index = 0; index < normalized.texts.length; index += 1) {
+            const cached = cachedByHash.get(hashes[index]);
+            if ((_a = cached === null || cached === void 0 ? void 0 : cached.item) === null || _a === void 0 ? void 0 : _a.translatedText) {
+                results[index] = toResolvedItem(cached.item, index, 'local');
+            }
+            else {
+                missingIndexes.push(index);
+            }
+        }
+        if (missingIndexes.length === 0) {
+            return {
+                targetLanguage: normalized.targetLanguage,
+                sourceLanguage: normalized.sourceLanguage,
+                mode: normalized.mode,
+                items: results,
+            };
+        }
+        const uniqueMisses = [];
+        const uniqueMissLookup = new Map();
+        for (const index of missingIndexes) {
+            const hash = hashes[index];
+            const existing = uniqueMissLookup.get(hash);
+            if (existing) {
+                existing.indexes.push(index);
+                continue;
+            }
+            uniqueMissLookup.set(hash, { firstIndex: index, indexes: [index] });
+            uniqueMisses.push({ index, hash, text: normalized.texts[index] });
+        }
+        const remoteResponse = await lookup(collectionId, {
+            targetLanguage: normalized.targetLanguage,
+            sourceLanguage: body.sourceLanguage,
+            mode: body.mode,
+            contentType: body.contentType,
+            context: body.context,
+            returnMeta: body.returnMeta,
+            texts: uniqueMisses.map((item) => item.text),
+        });
+        const cacheableRemoteItems = [];
+        remoteResponse.items.forEach((remoteItem, remoteIndex) => {
+            var _a, _b;
+            const miss = uniqueMisses[remoteIndex];
+            if (!miss)
+                return;
+            const indexes = (_b = (_a = uniqueMissLookup.get(miss.hash)) === null || _a === void 0 ? void 0 : _a.indexes) !== null && _b !== void 0 ? _b : [miss.index];
+            for (const index of indexes) {
+                const resolvedItem = Object.assign(Object.assign({}, remoteItem), { index, hash: miss.hash, sourceText: normalized.texts[index], cacheSource: 'remote' });
+                results[index] = resolvedItem;
+            }
+            if (remoteItem.translatedText) {
+                cacheableRemoteItems.push({
+                    hash: miss.hash,
+                    item: Object.assign(Object.assign({}, remoteItem), { index: miss.index, hash: miss.hash, sourceText: miss.text, cacheSource: 'remote' }),
+                });
+            }
+        });
+        if (useLocalCache && cacheableRemoteItems.length > 0) {
+            await setCachedTranslations({
+                collectionId,
+                sourceLanguage: normalized.sourceLanguage,
+                targetLanguage: normalized.targetLanguage,
+                contentType: normalized.contentType,
+                contextKey: normalized.contextKey,
+                ttlMs: localCacheTtlMs,
+                items: cacheableRemoteItems,
+            });
+        }
+        return {
+            targetLanguage: remoteResponse.targetLanguage,
+            sourceLanguage: (_b = remoteResponse.sourceLanguage) !== null && _b !== void 0 ? _b : normalized.sourceLanguage,
+            mode: (_c = remoteResponse.mode) !== null && _c !== void 0 ? _c : normalized.mode,
+            items: results.map((item, index) => item !== null && item !== void 0 ? item : {
+                index,
+                hash: hashes[index],
+                sourceText: normalized.texts[index],
+                cacheSource: 'remote',
+            }),
+        };
+    }
+    translations.resolve = resolve;
+    async function list(collectionId, params) {
+        const query = buildTranslationListQuery(params);
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/translations${query}`;
+        return request(path);
+    }
+    translations.list = list;
+    async function get(collectionId, translationId) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/translations/${encodeURIComponent(translationId)}`;
+        return request(path);
+    }
+    translations.get = get;
+    async function update(collectionId, translationId, body) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/translations/${encodeURIComponent(translationId)}`;
+        return patch(path, body);
+    }
+    translations.update = update;
+    async function clearLocalCache(collectionId) {
+        await clearCachedTranslations(collectionId);
+    }
+    translations.clearLocalCache = clearLocalCache;
+})(translations || (translations = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.2  |  Generated: 2026-03-23T18:11:56.796Z
+Version: 1.9.4  |  Generated: 2026-03-23T19:52:46.756Z
 
 This is a concise summary of all available API functions and types.
 
@@ -110,6 +110,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 +6344,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`
@@ -8169,6 +8317,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/dist/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 |