@proveanything/smartlinks 1.9.2 → 1.9.4

package/dist/translationCache.js

@@ -0,0 +1,298 @@
+const DB_NAME = 'smartlinks-sdk-translations';
+const STORE_NAME = 'translations';
+const DB_VERSION = 1;
+const DEFAULT_LOCAL_TRANSLATION_TTL_MS = 90 * 24 * 60 * 60000;
+let dbPromise = null;
+const memoryTranslationCache = new Map();
+export function getDefaultTranslationCacheTtlMs() {
+    return DEFAULT_LOCAL_TRANSLATION_TTL_MS;
+}
+function isIndexedDbAvailable() {
+    try {
+        return typeof indexedDB !== 'undefined' && indexedDB !== null;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+function openDb() {
+    if (dbPromise)
+        return dbPromise;
+    dbPromise = new Promise((resolve, reject) => {
+        try {
+            const request = indexedDB.open(DB_NAME, DB_VERSION);
+            request.onupgradeneeded = (event) => {
+                const db = event.target.result;
+                if (!db.objectStoreNames.contains(STORE_NAME)) {
+                    db.createObjectStore(STORE_NAME);
+                }
+            };
+            request.onsuccess = (event) => {
+                resolve(event.target.result);
+            };
+            request.onerror = () => {
+                dbPromise = null;
+                reject(request.error);
+            };
+            request.onblocked = () => {
+                dbPromise = null;
+                reject(new Error('[smartlinks] Translation IndexedDB open blocked'));
+            };
+        }
+        catch (error) {
+            dbPromise = null;
+            reject(error);
+        }
+    });
+    return dbPromise;
+}
+function stableContextKey(context) {
+    if (!context)
+        return null;
+    const entries = Object.entries(context)
+        .filter(([, value]) => value !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right));
+    if (entries.length === 0)
+        return null;
+    if (typeof context.surface === 'string' && typeof context.field === 'string') {
+        return `${context.surface}:${context.field}`;
+    }
+    return entries
+        .map(([key, value]) => `${key}=${String(value)}`)
+        .join('|');
+}
+export function deriveTranslationContextKey(context) {
+    return stableContextKey(context);
+}
+export function normalizeTranslationText(text, options = {}) {
+    const { trim = true, collapseWhitespace = false, unicodeNormalization = 'NFC', } = options;
+    let normalized = text.replace(/\r\n?/g, '\n');
+    if (trim) {
+        normalized = normalized.trim();
+    }
+    if (collapseWhitespace) {
+        normalized = normalized.replace(/[\t\f\v ]+/g, ' ');
+    }
+    if (unicodeNormalization) {
+        normalized = normalized.normalize(unicodeNormalization);
+    }
+    return normalized;
+}
+function toHex(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let output = '';
+    for (const byte of bytes) {
+        output += byte.toString(16).padStart(2, '0');
+    }
+    return output;
+}
+export async function hashTranslationText(text, options = {}) {
+    var _a;
+    const normalized = normalizeTranslationText(text, options);
+    const subtle = (_a = globalThis.crypto) === null || _a === void 0 ? void 0 : _a.subtle;
+    if (!subtle) {
+        throw new Error('[smartlinks] Web Crypto is required for translation hashing');
+    }
+    const encoded = new TextEncoder().encode(normalized);
+    const digest = await subtle.digest('SHA-256', encoded);
+    return `sha256:${toHex(digest)}`;
+}
+function buildLocalCacheKey(params) {
+    var _a;
+    return [
+        params.collectionId,
+        params.sourceLanguage,
+        params.targetLanguage,
+        params.contentType,
+        (_a = params.contextKey) !== null && _a !== void 0 ? _a : '',
+        params.hash,
+    ].join('::');
+}
+function isExpired(entry) {
+    return entry.expiresAt <= Date.now();
+}
+async function getEntry(key) {
+    const memoryEntry = memoryTranslationCache.get(key);
+    if (memoryEntry) {
+        if (isExpired(memoryEntry)) {
+            memoryTranslationCache.delete(key);
+            return null;
+        }
+        return memoryEntry;
+    }
+    if (!isIndexedDbAvailable())
+        return null;
+    try {
+        const db = await openDb();
+        return await new Promise((resolve) => {
+            try {
+                const tx = db.transaction(STORE_NAME, 'readonly');
+                const request = tx.objectStore(STORE_NAME).get(key);
+                request.onsuccess = () => {
+                    var _a;
+                    const result = (_a = request.result) !== null && _a !== void 0 ? _a : null;
+                    if (!result) {
+                        resolve(null);
+                        return;
+                    }
+                    if (isExpired(result)) {
+                        memoryTranslationCache.delete(key);
+                        void deleteEntries([key]);
+                        resolve(null);
+                        return;
+                    }
+                    memoryTranslationCache.set(key, result);
+                    resolve(result);
+                };
+                request.onerror = () => resolve(null);
+            }
+            catch (_a) {
+                resolve(null);
+            }
+        });
+    }
+    catch (_a) {
+        return null;
+    }
+}
+export async function getCachedTranslations(params) {
+    const entries = await Promise.all(params.hashes.map(async (hash) => {
+        const key = buildLocalCacheKey(Object.assign(Object.assign({}, params), { hash }));
+        const entry = await getEntry(key);
+        return entry ? [hash, entry] : null;
+    }));
+    return new Map(entries.filter((entry) => entry !== null));
+}
+async function setEntries(entries) {
+    for (const [key, entry] of entries) {
+        memoryTranslationCache.set(key, entry);
+    }
+    if (!isIndexedDbAvailable())
+        return;
+    try {
+        const db = await openDb();
+        await new Promise((resolve) => {
+            try {
+                const tx = db.transaction(STORE_NAME, 'readwrite');
+                const store = tx.objectStore(STORE_NAME);
+                for (const [key, entry] of entries) {
+                    store.put(entry, key);
+                }
+                tx.oncomplete = () => resolve();
+                tx.onerror = () => resolve();
+                tx.onabort = () => resolve();
+            }
+            catch (_a) {
+                resolve();
+            }
+        });
+    }
+    catch (_a) {
+        // Best-effort persistence only.
+    }
+}
+export async function setCachedTranslations(params) {
+    var _a;
+    const ttlMs = (_a = params.ttlMs) !== null && _a !== void 0 ? _a : DEFAULT_LOCAL_TRANSLATION_TTL_MS;
+    const now = Date.now();
+    const entries = params.items.map(({ hash, item }) => {
+        const key = buildLocalCacheKey({
+            collectionId: params.collectionId,
+            sourceLanguage: params.sourceLanguage,
+            targetLanguage: params.targetLanguage,
+            contentType: params.contentType,
+            contextKey: params.contextKey,
+            hash,
+        });
+        const entry = {
+            collectionId: params.collectionId,
+            sourceLanguage: params.sourceLanguage,
+            targetLanguage: params.targetLanguage,
+            contentType: params.contentType,
+            contextKey: params.contextKey,
+            hash,
+            item: Object.assign(Object.assign({}, item), { expiresAt: now + ttlMs }),
+            cachedAt: now,
+            expiresAt: now + ttlMs,
+        };
+        return [key, entry];
+    });
+    await setEntries(entries);
+}
+async function deleteEntries(keys) {
+    for (const key of keys) {
+        memoryTranslationCache.delete(key);
+    }
+    if (!isIndexedDbAvailable() || keys.length === 0)
+        return;
+    try {
+        const db = await openDb();
+        await new Promise((resolve) => {
+            try {
+                const tx = db.transaction(STORE_NAME, 'readwrite');
+                const store = tx.objectStore(STORE_NAME);
+                for (const key of keys) {
+                    store.delete(key);
+                }
+                tx.oncomplete = () => resolve();
+                tx.onerror = () => resolve();
+                tx.onabort = () => resolve();
+            }
+            catch (_a) {
+                resolve();
+            }
+        });
+    }
+    catch (_a) {
+        // Ignore deletion failures.
+    }
+}
+export async function clearCachedTranslations(collectionId) {
+    const memoryKeys = Array.from(memoryTranslationCache.keys());
+    const keysToDelete = collectionId
+        ? memoryKeys.filter((key) => key.startsWith(`${collectionId}::`))
+        : memoryKeys;
+    await deleteEntries(keysToDelete);
+    if (!isIndexedDbAvailable())
+        return;
+    try {
+        const db = await openDb();
+        if (!collectionId) {
+            await new Promise((resolve) => {
+                try {
+                    const tx = db.transaction(STORE_NAME, 'readwrite');
+                    tx.objectStore(STORE_NAME).clear();
+                    tx.oncomplete = () => resolve();
+                    tx.onerror = () => resolve();
+                    tx.onabort = () => resolve();
+                }
+                catch (_a) {
+                    resolve();
+                }
+            });
+            return;
+        }
+        await new Promise((resolve) => {
+            try {
+                const tx = db.transaction(STORE_NAME, 'readwrite');
+                const store = tx.objectStore(STORE_NAME);
+                const request = store.getAllKeys();
+                request.onsuccess = () => {
+                    for (const key of request.result) {
+                        if (key.startsWith(`${collectionId}::`)) {
+                            store.delete(key);
+                        }
+                    }
+                    resolve();
+                };
+                request.onerror = () => resolve();
+            }
+            catch (_a) {
+                resolve();
+            }
+        });
+    }
+    catch (_a) {
+        // Ignore deletion failures.
+    }
+}

package/dist/types/index.d.ts

@@ -32,3 +32,4 @@ export * from "./ai";
 export * from "./appManifest";
 export * from "./appObjects";
 export * from "./loyalty";
+export * from "./translations";

package/dist/types/index.js

@@ -34,3 +34,4 @@ export * from "./ai";
 export * from "./appManifest";
 export * from "./appObjects";
 export * from "./loyalty";
+export * from "./translations";

package/dist/types/translations.d.ts

@@ -0,0 +1,107 @@
+export type TranslationLookupMode = 'cache-fill' | 'cache-only';
+export type TranslationContentType = 'text/plain' | 'text/html' | 'text/x-liquid' | (string & {});
+export type TranslationQuality = 'machine' | 'human' | 'passthrough' | (string & {});
+export type TranslationItemStatus = 'cached' | 'generated' | 'miss' | 'passthrough' | 'local-cache' | (string & {});
+export type TranslationContextValue = string | number | boolean | null;
+export interface TranslationContext {
+    surface?: string;
+    field?: string;
+    [key: string]: TranslationContextValue | undefined;
+}
+export interface TranslationLookupRequestBase {
+    targetLanguage: string;
+    sourceLanguage?: string;
+    mode?: TranslationLookupMode;
+    contentType?: TranslationContentType;
+    context?: TranslationContext;
+    returnMeta?: boolean;
+}
+export interface TranslationLookupSingleRequest extends TranslationLookupRequestBase {
+    text: string;
+    texts?: never;
+}
+export interface TranslationLookupBatchRequest extends TranslationLookupRequestBase {
+    text?: never;
+    texts: string[];
+}
+export type TranslationLookupRequest = TranslationLookupSingleRequest | TranslationLookupBatchRequest;
+export interface TranslationLookupItem {
+    index: number;
+    hash: string;
+    sourceText: string;
+    translatedText?: string;
+    status?: TranslationItemStatus;
+    provider?: string;
+    model?: string;
+    isOverride?: boolean;
+    quality?: TranslationQuality;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface TranslationLookupResponse {
+    targetLanguage: string;
+    sourceLanguage?: string;
+    mode?: TranslationLookupMode;
+    items: TranslationLookupItem[];
+}
+export interface ResolvedTranslationItem extends TranslationLookupItem {
+    cacheSource?: 'local' | 'remote';
+    expiresAt?: number;
+}
+export interface ResolvedTranslationResponse {
+    targetLanguage: string;
+    sourceLanguage?: string;
+    mode?: TranslationLookupMode;
+    items: ResolvedTranslationItem[];
+}
+export interface TranslationHashOptions {
+    trim?: boolean;
+    collapseWhitespace?: boolean;
+    unicodeNormalization?: 'NFC' | 'NFKC' | false;
+}
+export interface TranslationResolveOptions {
+    useLocalCache?: boolean;
+    refreshLocalCache?: boolean;
+    localCacheTtlMs?: number;
+    hashOptions?: TranslationHashOptions;
+}
+export 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;
+}
+export interface TranslationListParams {
+    targetLanguage?: string;
+    sourceLanguage?: string;
+    contentType?: string;
+    contextKey?: string;
+    q?: string;
+    isOverride?: boolean;
+    limit?: number;
+    offset?: number;
+}
+export interface TranslationListResponse {
+    items: TranslationRecord[];
+    total?: number;
+    limit?: number;
+    offset?: number;
+}
+export interface TranslationUpdateRequest {
+    translatedText?: string;
+    isOverride?: boolean;
+    quality?: TranslationQuality;
+    metadata?: Record<string, any>;
+}

package/dist/types/translations.js

@@ -0,0 +1 @@
+export {};

package/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/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 |