@syntholoc/ota 0.0.0-stage → 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Syntholoc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @syntholoc/ota
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small ESM TypeScript client for Syntholoc OTA v1. It verifies manifests/catalogs with
+SHA-256, keeps bundled resources available offline, stages complete updates, and atomically
+activates or rolls back translation overlays. IndexedDB, memory and server file adapters
+are included. There are no runtime GraphQL, Prisma or framework dependencies.
+
+See [integration](../../docs/OTA_INTEGRATION.md), [protocol](../../docs/OTA_PROTOCOL.md)
+and [operations](../../docs/OTA_OPERATIONS.md). Native SDKs live separately in `sdks/`.
+
+```ts
+import { createOtaClient, createIndexedDbStorage } from '@syntholoc/ota';
+const ota = createOtaClient({
+  baseUrl: 'https://translations.example.com',
+  distributionId: 'dst_example',
+  channel: 'production',
+  catalogVersion: 'app-v1',
+  localeKey: 'ru',
+  bundles: ['app'],
+  storage: createIndexedDbStorage(),
+  fallbackResources: { ru: { app: { hello: 'Привет' } } },
+});
+await ota.loadCached();
+const update = await ota.checkForUpdates();
+if (update.status === 'available') await ota.activate(update.releaseId);
+console.log(ota.getResources());
+```
+
+`forceRefresh` skips freshness, never backoff/security. `resetFailureState` resumes after
+credential changes/explicit retirement override. Create a new scoped client to change language
+or channel. The package does not poll on a background timer; scheduling belongs to the host.
+
+Build: `bun run build`. Test: `bun run test`. Pack with
+`bun scripts/publish-package.ts packages/ota --dry-run` from the repository root.

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as createMemoryStorage, i as createIndexedDbStorage, n as createOtaClient, r as digest, t as OtaError } from "./src-DmqzlY0J.js";
+export { OtaError, createIndexedDbStorage, createMemoryStorage, createOtaClient, digest };

package/dist/ota/src/index.d.ts

@@ -0,0 +1,53 @@
+import { type JsonCatalog } from '../../shared/src/ota/index.js';
+import { type OtaStorage } from './storage.js';
+export { createMemoryStorage, createIndexedDbStorage } from './storage.js';
+export type { OtaStorage, OtaCacheState, CachedSet } from './storage.js';
+export type { JsonCatalog, OtaChannelManifest, OtaReleaseManifest } from '../../shared/src/ota/index.js';
+export type Resources = Record<string, Record<string, JsonCatalog>>;
+export interface OtaClientOptions {
+    baseUrl: string;
+    distributionId: string;
+    channel: string;
+    catalogVersion: string;
+    localeKey: string;
+    bundles: string[];
+    fallbackLocaleKeys?: string[];
+    fallbackResources?: Resources;
+    storage?: OtaStorage;
+    credentialProvider?: () => string | Promise<string>;
+    fetch?: typeof fetch;
+    checkIntervalSeconds?: number;
+    timeoutMs?: number;
+    onUpdateAvailable?: (releaseId: string) => void;
+    onActivated?: (releaseId: string) => void;
+    onError?: (error: Error) => void;
+}
+export type CheckResult = {
+    status: 'available';
+    releaseId: string;
+} | {
+    status: 'unchanged' | 'skipped' | 'retired' | 'error';
+    error?: string;
+};
+export declare class OtaError extends Error {
+    readonly status?: number | undefined;
+    readonly retryAfterMs: number;
+    constructor(message: string, status?: number | undefined, retryAfterMs?: number);
+}
+export declare function digest(bytes: Uint8Array): Promise<string>;
+export declare function createOtaClient(options: OtaClientOptions): {
+    loadCached: () => Promise<{
+        releaseId?: undefined;
+    } | {
+        releaseId: string;
+    }>;
+    checkForUpdates: (input?: {
+        forceRefresh?: boolean;
+        signal?: AbortSignal;
+    }) => Promise<CheckResult>;
+    activate: (releaseId: string) => Promise<void>;
+    getResources: () => Record<string, JsonCatalog>;
+    readonly activeReleaseId: string | undefined;
+    resetFailureState(): Promise<void>;
+    clearCache(): Promise<void>;
+};

package/dist/ota/src/server.d.ts

@@ -0,0 +1,4 @@
+export * from './index.js';
+import type { OtaStorage } from './storage.js';
+/** One app-private directory. Atomic rename + a shared directory lock protect server processes. */
+export declare function createFileStorage(directory: string): OtaStorage;

package/dist/ota/src/storage.d.ts

@@ -0,0 +1,38 @@
+import type { OtaAsset, OtaChannelManifest } from '../../shared/src/ota/index.js';
+export interface CachedSet {
+    releaseId: string;
+    generation: number;
+    assets: {
+        localeKey: string;
+        asset: OtaAsset;
+    }[];
+}
+export interface OtaCacheState {
+    revision: number;
+    cacheEpoch?: number;
+    lastUsedAt?: number;
+    active?: CachedSet;
+    previous?: CachedSet;
+    candidate?: CachedSet;
+    channel?: OtaChannelManifest;
+    etag?: string;
+    highestGeneration?: number;
+    lastChecked?: number;
+    nextCheck?: number;
+    nextAttempt?: number;
+    retryDelayMs?: number;
+    failures?: number;
+    stopped?: 'auth' | 'retired';
+}
+/** commit is an atomic compare-and-set; blobs are immutable and shared by hash. */
+export interface OtaStorage {
+    read(scope: string): Promise<OtaCacheState>;
+    commit(scope: string, state: OtaCacheState, expectedRevision: number): Promise<boolean>;
+    readBlob(hash: string): Promise<Uint8Array | undefined>;
+    writeBlob(hash: string, bytes: Uint8Array): Promise<void>;
+    clear(scope: string): Promise<void>;
+    collect?(scope: string, maxScopes?: number): Promise<void>;
+}
+export declare function createMemoryStorage(): OtaStorage;
+/** IDB owns atomic metadata/pointer commits across tabs. Catalogs never use localStorage. */
+export declare function createIndexedDbStorage(databaseName?: string): OtaStorage;

package/dist/server.js

@@ -0,0 +1,178 @@
+import { a as createMemoryStorage, i as createIndexedDbStorage, n as createOtaClient, r as digest, t as OtaError } from "./src-DmqzlY0J.js";
+import { mkdir, open, readdir, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { lock } from "proper-lockfile";
+//#region src/server.ts
+/** One app-private directory. Atomic rename + a shared directory lock protect server processes. */
+function createFileStorage(directory) {
+	const path = (kind, key) => join(directory, `${kind}-${createHash("sha256").update(key).digest("hex")}`);
+	function metadata(bytes) {
+		const state = JSON.parse(bytes);
+		if (!state || !Number.isSafeInteger(state.revision) || state.revision < 0) throw new SyntaxError("OTA_CORRUPT_CACHE");
+		return state;
+	}
+	async function bounded(file, maximum) {
+		const handle = await open(file, "r");
+		try {
+			if ((await handle.stat()).size > maximum) return void 0;
+			return await handle.readFile();
+		} finally {
+			await handle.close();
+		}
+	}
+	async function readMetadata(file) {
+		const bytes = await bounded(file, 16777216);
+		if (!bytes) throw new SyntaxError("OTA_CORRUPT_CACHE");
+		return metadata(bytes.toString("utf8"));
+	}
+	async function read(scope) {
+		try {
+			return await readMetadata(path("scope", scope));
+		} catch (e) {
+			if (e.code === "ENOENT") return { revision: 0 };
+			throw e;
+		}
+	}
+	async function atomic(file, bytes) {
+		await mkdir(directory, {
+			recursive: true,
+			mode: 448
+		});
+		const temporary = `${file}.${randomUUID()}.tmp`;
+		try {
+			await writeFile(temporary, bytes, { mode: 384 });
+			await rename(temporary, file);
+		} finally {
+			await rm(temporary, { force: true });
+		}
+	}
+	async function locked(fn) {
+		await mkdir(directory, {
+			recursive: true,
+			mode: 448
+		});
+		let compromised = false;
+		const release = await lock(directory, {
+			lockfilePath: join(directory, ".ota.lock"),
+			stale: 1e4,
+			update: 3e3,
+			retries: {
+				retries: 100,
+				factor: 1,
+				minTimeout: 100,
+				maxTimeout: 100
+			},
+			onCompromised: () => {
+				compromised = true;
+			}
+		});
+		try {
+			const result = await fn();
+			if (compromised) throw new Error("OTA_CACHE_LOCK_LOST");
+			return result;
+		} finally {
+			if (!compromised) await release();
+		}
+	}
+	return {
+		read,
+		async commit(scope, state, revision) {
+			return locked(async () => {
+				if ((await read(scope)).revision !== revision) return false;
+				await atomic(path("scope", scope), JSON.stringify({
+					...state,
+					revision: revision + 1
+				}));
+				return true;
+			});
+		},
+		async readBlob(hash) {
+			try {
+				return await locked(async () => {
+					const file = path("blob", hash);
+					const bytes = await bounded(file, 1e7);
+					if (!bytes) return void 0;
+					const now = /* @__PURE__ */ new Date();
+					await utimes(file, now, now);
+					return bytes;
+				});
+			} catch (e) {
+				if (e.code === "ENOENT") return void 0;
+				throw e;
+			}
+		},
+		async writeBlob(hash, bytes) {
+			await locked(() => atomic(path("blob", hash), bytes));
+		},
+		async collect(scope, maxScopes = 8) {
+			await locked(async () => {
+				const names = await readdir(directory);
+				const entries = [];
+				for (const name of names) {
+					if (!/^scope-[a-f0-9]{64}$/.test(name)) continue;
+					try {
+						entries.push({
+							file: join(directory, name),
+							state: await readMetadata(join(directory, name))
+						});
+					} catch {
+						return;
+					}
+				}
+				entries.sort((a, b) => (b.state.lastUsedAt ?? 0) - (a.state.lastUsedAt ?? 0));
+				const cutoff = Date.now() - 864e5;
+				const references = /* @__PURE__ */ new Set();
+				for (const [index, entry] of entries.entries()) {
+					const s = entry.state;
+					if (entry.file !== path("scope", scope) && index >= maxScopes && (s.lastUsedAt ?? 0) < cutoff) {
+						if (s.active || s.previous || s.candidate || s.channel || s.etag) await atomic(entry.file, JSON.stringify({
+							...s,
+							active: void 0,
+							previous: void 0,
+							candidate: void 0,
+							channel: void 0,
+							etag: void 0,
+							revision: s.revision + 1,
+							cacheEpoch: (s.cacheEpoch ?? 0) + 1
+						}));
+						continue;
+					}
+					for (const set of [
+						s.active,
+						s.previous,
+						s.candidate
+					]) for (const item of Array.isArray(set?.assets) ? set.assets : []) if (typeof item?.asset?.sha256 === "string") references.add(path("blob", item.asset.sha256));
+				}
+				for (const name of names) {
+					const file = join(directory, name);
+					const blob = /^blob-[a-f0-9]{64}$/.test(name);
+					const temporary = name.endsWith(".tmp");
+					if (!blob && !temporary) continue;
+					if (blob && references.has(file)) continue;
+					if ((await stat(file)).mtimeMs < cutoff) await rm(file, { force: true });
+				}
+			});
+		},
+		async clear(scope) {
+			await locked(async () => {
+				let previous;
+				try {
+					previous = await read(scope);
+				} catch (error) {
+					if (!(error instanceof SyntaxError)) throw error;
+					previous = {
+						revision: Date.now(),
+						cacheEpoch: Date.now()
+					};
+				}
+				await atomic(path("scope", scope), JSON.stringify({
+					revision: previous.revision + 1,
+					cacheEpoch: (previous.cacheEpoch ?? 0) + 1
+				}));
+			});
+		}
+	};
+}
+//#endregion
+export { OtaError, createFileStorage, createIndexedDbStorage, createMemoryStorage, createOtaClient, digest };

package/dist/shared/src/ota/index.d.ts

@@ -0,0 +1,93 @@
+/** OTA wire v1. This module has no framework, Node or server dependencies. */
+export declare const OTA_PROTOCOL_VERSION = 1;
+export declare const OTA_FORMATS: readonly ['JSON_FLAT', 'JSON_NESTED', 'ANDROID_XML', 'IOS_STRINGS', 'IOS_STRINGSDICT', 'IOS_XCSTRINGS'];
+export declare const OTA_PLATFORM_FORMATS: Record<string, readonly string[]>;
+export type OtaFormat = (typeof OTA_FORMATS)[number];
+export type JsonCatalog = {
+    [key: string]: string | JsonCatalog;
+};
+export interface OtaAsset {
+    id: string;
+    bundle: string;
+    namespace: string;
+    format: OtaFormat;
+    path: string;
+    sha256: string;
+    bytes: number;
+    contentType: string;
+}
+export interface OtaReleaseManifest {
+    protocolVersion: 1;
+    distributionId: string;
+    releaseId: string;
+    catalogVersion: string;
+    createdAt: string;
+    sourceDigest: string;
+    requiredBundles: string[];
+    locales: {
+        localeKey: string;
+        languageTag: string;
+        assets: OtaAsset[];
+    }[];
+}
+export interface OtaChannelManifest {
+    protocolVersion: 1;
+    distributionId: string;
+    channel: string;
+    generation: number;
+    catalogVersion: string;
+    release: {
+        id: string;
+        manifestPath: string;
+        sha256: string;
+        bytes: number;
+    };
+    recommendedCheckIntervalSeconds: number;
+}
+export interface OtaLocaleMapping {
+    localeId: string | 'source';
+    localeKey: string;
+    languageTag: string;
+}
+export interface OtaBundleConfig {
+    name: string;
+    namespace: string;
+    format: OtaFormat;
+    fileSelectors: string[];
+    includeUnassigned: boolean;
+    stripKeyPrefix: boolean;
+    required: boolean;
+}
+export interface OtaBaselineEntry {
+    bundle: string;
+    key: string;
+    sourceText: string;
+}
+export interface OtaConfig {
+    rendererVersion: 1;
+    bundles: OtaBundleConfig[];
+    locales: OtaLocaleMapping[];
+    onlyApproved: boolean;
+    missingPolicy: 'OMIT' | 'SOURCE' | 'FAIL';
+    sortKeysAlphabetically: boolean;
+    baseline: OtaBaselineEntry[];
+}
+export declare const OTA_LIMITS: {
+    readonly manifestBytes: 2000000;
+    readonly assetBytes: 10000000;
+    readonly snapshotBytes: number;
+    readonly releaseBytes: number;
+    readonly keys: 100000;
+    readonly bundles: 50;
+    readonly locales: 100;
+    readonly assets: 5000;
+};
+export declare const OTA_SAFE_NAME: RegExp;
+export declare const OTA_HASH: RegExp;
+export declare function otaAssert(ok: unknown, message?: string): asserts ok;
+export declare function validateChannelManifest(x: unknown): OtaChannelManifest;
+export declare function validateReleaseManifest(x: unknown): OtaReleaseManifest;
+export declare function validateCatalog(x: unknown, depth?: number): JsonCatalog;
+/** Reject encoded traversal before URL normalization. Credentials never leave the delivery scope. */
+export declare function deliveryUrl(base: string, path: string, prefix: string): URL;
+export declare function validateOtaConfig(input: unknown): OtaConfig;

package/dist/src-DmqzlY0J.js

@@ -0,0 +1,688 @@
+//#region ../shared/src/ota/index.ts
+const OTA_FORMATS = [
+	"JSON_FLAT",
+	"JSON_NESTED",
+	"ANDROID_XML",
+	"IOS_STRINGS",
+	"IOS_STRINGSDICT",
+	"IOS_XCSTRINGS"
+];
+const OTA_LIMITS = {
+	manifestBytes: 2e6,
+	assetBytes: 1e7,
+	snapshotBytes: 33554432,
+	releaseBytes: 104857600,
+	keys: 1e5,
+	bundles: 50,
+	locales: 100,
+	assets: 5e3
+};
+const OTA_SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/;
+const OTA_HASH = /^[a-f0-9]{64}$/;
+const unsafe = /* @__PURE__ */ new Set([
+	"__proto__",
+	"prototype",
+	"constructor"
+]);
+function otaAssert(ok, message = "OTA_INVALID_MANIFEST") {
+	if (!ok) throw new Error(message);
+}
+function record(x) {
+	otaAssert(x && typeof x === "object" && !Array.isArray(x));
+}
+function str(x) {
+	otaAssert(typeof x === "string" && x.length > 0 && x.length <= 512);
+}
+function name(x) {
+	str(x);
+	otaAssert(OTA_SAFE_NAME.test(x));
+}
+function hash(x) {
+	otaAssert(typeof x === "string" && OTA_HASH.test(x));
+}
+function size(x, max) {
+	otaAssert(Number.isSafeInteger(x) && Number(x) >= 0 && Number(x) <= max);
+}
+function unique(xs) {
+	otaAssert(new Set(xs).size === xs.length);
+}
+function validateChannelManifest(x) {
+	record(x);
+	otaAssert(x.protocolVersion === 1);
+	name(x.distributionId);
+	name(x.channel);
+	str(x.catalogVersion);
+	size(x.generation, Number.MAX_SAFE_INTEGER);
+	size(x.recommendedCheckIntervalSeconds, 86400);
+	record(x.release);
+	name(x.release.id);
+	str(x.release.manifestPath);
+	hash(x.release.sha256);
+	size(x.release.bytes, OTA_LIMITS.manifestBytes);
+	return x;
+}
+function validateReleaseManifest(x) {
+	record(x);
+	otaAssert(x.protocolVersion === 1);
+	name(x.distributionId);
+	name(x.releaseId);
+	str(x.catalogVersion);
+	str(x.createdAt);
+	otaAssert(Number.isFinite(Date.parse(x.createdAt)));
+	hash(x.sourceDigest);
+	otaAssert(Array.isArray(x.requiredBundles) && x.requiredBundles.length <= OTA_LIMITS.bundles);
+	x.requiredBundles.forEach(name);
+	unique(x.requiredBundles);
+	otaAssert(Array.isArray(x.locales) && x.locales.length > 0 && x.locales.length <= OTA_LIMITS.locales);
+	let totalBytes = 0;
+	const ids = [];
+	const locales = [];
+	for (const l of x.locales) {
+		record(l);
+		str(l.localeKey);
+		str(l.languageTag);
+		try {
+			otaAssert(Intl.getCanonicalLocales(l.languageTag).length === 1);
+		} catch {
+			throw new Error("OTA_INVALID_MANIFEST");
+		}
+		locales.push(l.localeKey);
+		otaAssert(Array.isArray(l.assets) && l.assets.length <= OTA_LIMITS.bundles);
+		const bundles = [];
+		for (const a of l.assets) {
+			record(a);
+			name(a.id);
+			name(a.bundle);
+			name(a.namespace);
+			str(a.path);
+			hash(a.sha256);
+			size(a.bytes, OTA_LIMITS.assetBytes);
+			totalBytes += a.bytes;
+			otaAssert(totalBytes <= OTA_LIMITS.releaseBytes, "OTA_LIMIT_EXCEEDED");
+			otaAssert(OTA_FORMATS.includes(a.format));
+			str(a.contentType);
+			otaAssert(a.contentType === (String(a.format).startsWith("JSON") || a.format === "IOS_XCSTRINGS" ? "application/json" : a.format === "IOS_STRINGS" ? "text/plain" : "application/xml"));
+			otaAssert(a.path === `assets/${a.id}/${a.sha256}`);
+			ids.push(a.id);
+			bundles.push(a.bundle);
+		}
+		unique(bundles);
+		otaAssert(x.requiredBundles.every((b) => bundles.includes(b)));
+	}
+	unique(locales);
+	unique(ids);
+	otaAssert(ids.length <= OTA_LIMITS.assets);
+	return x;
+}
+function validateCatalog(x, depth = 0) {
+	record(x);
+	otaAssert(depth < 40);
+	for (const [k, v] of Object.entries(x)) {
+		otaAssert(!unsafe.has(k), "OTA_UNSAFE_KEY");
+		if (typeof v !== "string") validateCatalog(v, depth + 1);
+	}
+	return x;
+}
+/** Reject encoded traversal before URL normalization. Credentials never leave the delivery scope. */
+function deliveryUrl(base, path, prefix) {
+	otaAssert(!/%|\\|\?|#/.test(path) && !path.split("/").some((p) => p === "." || p === ".."), "OTA_UNSAFE_PATH");
+	const origin = new URL(base);
+	const url = new URL(path, origin);
+	otaAssert(url.origin === origin.origin && (url.protocol === "https:" || url.hostname === "localhost" || url.hostname === "127.0.0.1"), "OTA_UNSAFE_ORIGIN");
+	otaAssert(!url.username && !url.password && url.pathname.startsWith(prefix), "OTA_UNSAFE_PATH");
+	return url;
+}
+//#endregion
+//#region src/storage.ts
+function createMemoryStorage() {
+	const states = /* @__PURE__ */ new Map();
+	const blobs = /* @__PURE__ */ new Map();
+	return {
+		async read(scope) {
+			return structuredClone(states.get(scope) ?? { revision: 0 });
+		},
+		async commit(scope, state, revision) {
+			if ((states.get(scope)?.revision ?? 0) !== revision) return false;
+			states.set(scope, structuredClone({
+				...state,
+				revision: revision + 1
+			}));
+			return true;
+		},
+		async readBlob(hash) {
+			return blobs.get(hash)?.slice();
+		},
+		async writeBlob(hash, bytes) {
+			blobs.set(hash, bytes.slice());
+		},
+		async clear(scope) {
+			const previous = states.get(scope);
+			states.set(scope, {
+				revision: (previous?.revision ?? 0) + 1,
+				cacheEpoch: (previous?.cacheEpoch ?? 0) + 1
+			});
+		}
+	};
+}
+/** IDB owns atomic metadata/pointer commits across tabs. Catalogs never use localStorage. */
+function createIndexedDbStorage(databaseName = "syntholoc-ota-v1") {
+	let database;
+	function db() {
+		return database ??= new Promise((resolve, reject) => {
+			const request = indexedDB.open(databaseName, 1);
+			request.onupgradeneeded = () => {
+				request.result.createObjectStore("states");
+				request.result.createObjectStore("blobs");
+			};
+			request.onerror = () => {
+				database = void 0;
+				reject(request.error);
+			};
+			request.onsuccess = () => {
+				request.result.onversionchange = () => {
+					request.result.close();
+					database = void 0;
+				};
+				resolve(request.result);
+			};
+		});
+	}
+	async function read(store, key) {
+		const d = await db();
+		return new Promise((resolve, reject) => {
+			const transaction = d.transaction(store, "readonly");
+			const request = transaction.objectStore(store).get(key);
+			transaction.oncomplete = () => resolve(request.result);
+			transaction.onerror = () => reject(transaction.error);
+			transaction.onabort = () => reject(transaction.error);
+		});
+	}
+	return {
+		async read(scope) {
+			return await read("states", scope) ?? { revision: 0 };
+		},
+		async commit(scope, state, revision) {
+			const d = await db();
+			return new Promise((resolve, reject) => {
+				const tx = d.transaction("states", "readwrite");
+				const store = tx.objectStore("states");
+				const request = store.get(scope);
+				let matched = false;
+				request.onsuccess = () => {
+					if ((request.result?.revision ?? 0) === revision) {
+						store.put({
+							...state,
+							revision: revision + 1
+						}, scope);
+						matched = true;
+					}
+				};
+				tx.oncomplete = () => resolve(matched);
+				tx.onerror = () => reject(tx.error);
+				tx.onabort = () => reject(tx.error);
+			});
+		},
+		async readBlob(hash) {
+			const d = await db();
+			return new Promise((resolve, reject) => {
+				const tx = d.transaction("blobs", "readwrite");
+				const store = tx.objectStore("blobs");
+				const request = store.get(hash);
+				let body;
+				request.onsuccess = () => {
+					const cached = request.result;
+					if (cached) {
+						body = cached instanceof Uint8Array ? cached : cached.bytes;
+						store.put({
+							bytes: body,
+							createdAt: Date.now()
+						}, hash);
+					}
+				};
+				tx.oncomplete = () => resolve(body);
+				tx.onerror = () => reject(tx.error);
+				tx.onabort = () => reject(tx.error);
+			});
+		},
+		async writeBlob(hash, bytes) {
+			const d = await db();
+			await new Promise((resolve, reject) => {
+				const tx = d.transaction("blobs", "readwrite");
+				tx.objectStore("blobs").put({
+					bytes,
+					createdAt: Date.now()
+				}, hash);
+				tx.oncomplete = () => resolve();
+				tx.onerror = () => reject(tx.error);
+				tx.onabort = () => reject(tx.error);
+			});
+		},
+		async collect(scope, maxScopes = 8) {
+			const d = await db();
+			await new Promise((resolve, reject) => {
+				const tx = d.transaction(["states", "blobs"], "readwrite");
+				const states = tx.objectStore("states");
+				const blobs = tx.objectStore("blobs");
+				const request = states.openCursor();
+				const entries = [];
+				request.onsuccess = () => {
+					const cursor = request.result;
+					if (cursor) {
+						entries.push({
+							key: cursor.key,
+							state: cursor.value
+						});
+						cursor.continue();
+						return;
+					}
+					entries.sort((a, b) => (b.state.lastUsedAt ?? 0) - (a.state.lastUsedAt ?? 0));
+					const references = /* @__PURE__ */ new Set();
+					const cutoff = Date.now() - 864e5;
+					for (const [index, entry] of entries.entries()) {
+						if (entry.key !== scope && index >= maxScopes && (entry.state.lastUsedAt ?? 0) < cutoff) {
+							states.delete(entry.key);
+							continue;
+						}
+						for (const set of [
+							entry.state.active,
+							entry.state.previous,
+							entry.state.candidate
+						]) for (const item of Array.isArray(set?.assets) ? set.assets : []) if (typeof item?.asset?.sha256 === "string") references.add(item.asset.sha256);
+					}
+					const scan = blobs.openCursor();
+					scan.onsuccess = () => {
+						const blob = scan.result;
+						if (!blob) return;
+						const value = blob.value;
+						if (!references.has(String(blob.key)) && (value.createdAt ?? 0) < cutoff) blob.delete();
+						blob.continue();
+					};
+				};
+				tx.oncomplete = () => resolve();
+				tx.onerror = () => reject(tx.error);
+				tx.onabort = () => reject(tx.error);
+			});
+		},
+		async clear(scope) {
+			const d = await db();
+			await new Promise((resolve, reject) => {
+				const tx = d.transaction("states", "readwrite");
+				const store = tx.objectStore("states");
+				const request = store.get(scope);
+				request.onsuccess = () => store.put({
+					revision: (request.result?.revision ?? 0) + 1,
+					cacheEpoch: (request.result?.cacheEpoch ?? 0) + 1
+				}, scope);
+				tx.oncomplete = () => resolve();
+				tx.onerror = () => reject(tx.error);
+				tx.onabort = () => reject(tx.error);
+			});
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+var OtaError = class extends Error {
+	status;
+	retryAfterMs;
+	constructor(message, status, retryAfterMs = 0) {
+		super(message);
+		this.status = status;
+		this.retryAfterMs = retryAfterMs;
+	}
+};
+const refreshes = /* @__PURE__ */ new WeakMap();
+async function digest(bytes) {
+	return Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes.slice().buffer))).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function merge(a = {}, b = {}) {
+	const out = Object.create(null);
+	for (const [k, v] of Object.entries(a)) out[k] = typeof v === "string" ? v : merge(v);
+	for (const [k, v] of Object.entries(b)) out[k] = typeof v === "string" ? v : merge(typeof out[k] === "object" ? out[k] : {}, v);
+	return out;
+}
+function notify(fn, arg) {
+	try {
+		fn?.(arg);
+	} catch {}
+}
+function createOtaClient(options) {
+	const o = {
+		...options,
+		bundles: [...options.bundles],
+		fallbackLocaleKeys: [...options.fallbackLocaleKeys ?? []]
+	};
+	otaAssert(OTA_SAFE_NAME.test(o.distributionId) && OTA_SAFE_NAME.test(o.channel) && !!o.catalogVersion && o.bundles.length > 0 && new Set(o.bundles).size === o.bundles.length, "OTA_INVALID_CONFIG");
+	const origin = new URL(o.baseUrl).origin;
+	const prefix = `/ota/v1/distributions/${o.distributionId}/channels/${o.channel}/`;
+	const channelUrl = deliveryUrl(origin, `${prefix}manifest.json`, prefix);
+	const scope = JSON.stringify([
+		origin,
+		o.distributionId,
+		o.channel,
+		o.catalogVersion,
+		o.localeKey,
+		o.fallbackLocaleKeys,
+		o.bundles
+	]);
+	const storage = o.storage ?? createMemoryStorage();
+	const pending = refreshes.get(storage) ?? /* @__PURE__ */ new Map();
+	refreshes.set(storage, pending);
+	const fetcher = o.fetch ?? globalThis.fetch;
+	const fallback = structuredClone(o.fallbackResources ?? {});
+	for (const namespaces of Object.values(fallback)) for (const catalog of Object.values(namespaces)) validateCatalog(catalog);
+	const localeKeys = [.../* @__PURE__ */ new Set([o.localeKey, ...o.fallbackLocaleKeys])];
+	let overlay = {};
+	let activeRelease;
+	let epoch = 0;
+	let nextCheckMonotonic;
+	let nextAttemptMonotonic;
+	const interval = Math.max(60, Math.min(86400, o.checkIntervalSeconds ?? 900)) * 1e3;
+	async function update(mutator) {
+		for (let i = 0; i < 10; i++) {
+			const s = await storage.read(scope);
+			const next = {
+				...mutator(s),
+				lastUsedAt: Date.now()
+			};
+			if (await storage.commit(scope, next, s.revision)) return {
+				...next,
+				revision: s.revision + 1
+			};
+		}
+		throw new OtaError("OTA_CACHE_CONFLICT");
+	}
+	async function parseSet(set) {
+		otaAssert(set && Array.isArray(set.assets) && set.assets.length <= OTA_LIMITS.assets && Number.isSafeInteger(set.generation), "OTA_CORRUPT_CACHE");
+		const resources = Object.create(null);
+		for (const { localeKey, asset } of set.assets) {
+			otaAssert(localeKeys.includes(localeKey) && o.bundles.includes(asset.bundle) && ["JSON_FLAT", "JSON_NESTED"].includes(asset.format), "OTA_UNSUPPORTED_FORMAT");
+			const bytes = await storage.readBlob(asset.sha256);
+			otaAssert(bytes && bytes.length === asset.bytes && await digest(bytes) === asset.sha256, "OTA_CORRUPT_CACHE");
+			const catalog = validateCatalog(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+			if (asset.format === "JSON_FLAT") otaAssert(Object.values(catalog).every((v) => typeof v === "string"), "OTA_INVALID_CATALOG");
+			const namespaces = resources[localeKey] ??= Object.create(null);
+			otaAssert(!Object.hasOwn(namespaces, asset.namespace), "OTA_DUPLICATE_NAMESPACE");
+			namespaces[asset.namespace] = catalog;
+		}
+		otaAssert(localeKeys.every((l) => o.bundles.every((b) => set.assets.some((a) => a.localeKey === l && a.asset.bundle === b))), "OTA_MISSING_BUNDLE");
+		return resources;
+	}
+	async function request(url, limit, etag, signal) {
+		const headers = {};
+		if (etag) headers["If-None-Match"] = etag;
+		if (o.credentialProvider) headers.Authorization = `Bearer ${await o.credentialProvider()}`;
+		const response = await fetcher(url, {
+			headers,
+			credentials: "omit",
+			redirect: "error",
+			signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(o.timeoutMs ?? 15e3)]) : AbortSignal.timeout(o.timeoutMs ?? 15e3)
+		});
+		if (response.status === 304) return {
+			response,
+			bytes: void 0
+		};
+		if (!response.ok) {
+			let code = `OTA_HTTP_${response.status}`;
+			try {
+				const error = await bounded(response, 4096);
+				const body = JSON.parse(new TextDecoder().decode(error));
+				if (typeof body.code === "string" && /^OTA_[A-Z0-9_]{1,100}$/.test(body.code)) code = body.code;
+			} catch {}
+			const retry = response.headers.get("Retry-After");
+			const retryMs = retry ? /^\d+$/.test(retry) ? Number(retry) * 1e3 : Date.parse(retry) - Date.now() : 0;
+			throw new OtaError(code, response.status, Math.max(0, Math.min(864e5, retryMs || 0)));
+		}
+		return {
+			response,
+			bytes: await bounded(response, limit)
+		};
+	}
+	async function bounded(response, limit) {
+		otaAssert(Number(response.headers.get("Content-Length") ?? 0) <= limit, "OTA_LIMIT_EXCEEDED");
+		if (!response.body) return /* @__PURE__ */ new Uint8Array();
+		const reader = response.body.getReader();
+		const chunks = [];
+		let length = 0;
+		try {
+			for (;;) {
+				const r = await reader.read();
+				if (r.done) break;
+				length += r.value.length;
+				otaAssert(length <= limit, "OTA_LIMIT_EXCEEDED");
+				chunks.push(r.value);
+			}
+		} finally {
+			await reader.cancel();
+			reader.releaseLock();
+		}
+		const bytes = new Uint8Array(length);
+		let offset = 0;
+		for (const c of chunks) {
+			bytes.set(c, offset);
+			offset += c.length;
+		}
+		return bytes;
+	}
+	async function loadCached() {
+		let s;
+		try {
+			s = await storage.read(scope);
+		} catch (err) {
+			overlay = {};
+			activeRelease = void 0;
+			notify(o.onError, new OtaError("OTA_CORRUPT_CACHE"));
+			return {};
+		}
+		for (const set of [s.active, s.previous]) {
+			if (!set) continue;
+			try {
+				overlay = await parseSet(set);
+				activeRelease = set.releaseId;
+				await update((current) => current).catch(() => void 0);
+				return { releaseId: set.releaseId };
+			} catch {}
+		}
+		overlay = {};
+		activeRelease = void 0;
+		return {};
+	}
+	async function check(force, signal) {
+		const requestEpoch = epoch;
+		let cacheEpoch;
+		try {
+			let s = await storage.read(scope);
+			cacheEpoch = s.cacheEpoch ?? 0;
+			const now = Date.now();
+			if (s.stopped) return { status: s.stopped === "retired" ? "retired" : "skipped" };
+			const remainingRetry = (s.nextAttempt ?? 0) - now;
+			if (nextAttemptMonotonic !== void 0 ? performance.now() < nextAttemptMonotonic : remainingRetry > 0 && remainingRetry <= Math.min(864e5, s.retryDelayMs ?? 36e5)) return { status: "skipped" };
+			const maxFreshDelay = Math.max(interval, Math.min(86400, s.channel?.recommendedCheckIntervalSeconds ?? 0) * 1e3) * 1.1;
+			const remainingFresh = (s.nextCheck ?? 0) - now;
+			const fresh = nextCheckMonotonic !== void 0 ? performance.now() < nextCheckMonotonic : remainingFresh > 0 && remainingFresh <= maxFreshDelay || s.lastChecked !== void 0 && now >= s.lastChecked && now - s.lastChecked < interval;
+			if (!force && fresh) return { status: "skipped" };
+			await storage.collect?.(scope).catch(() => void 0);
+			let reply = await request(channelUrl, OTA_LIMITS.manifestBytes, s.etag, signal);
+			if (!reply.bytes && !s.channel) reply = await request(channelUrl, OTA_LIMITS.manifestBytes, void 0, signal);
+			const channel = validateChannelManifest(reply.bytes ? JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(reply.bytes)) : s.channel);
+			otaAssert(channel.distributionId === o.distributionId && channel.channel === o.channel && channel.catalogVersion === o.catalogVersion, "OTA_CATALOG_INCOMPATIBLE");
+			otaAssert(channel.generation >= (s.highestGeneration ?? 0), "OTA_STALE_GENERATION");
+			otaAssert(channel.release.manifestPath === `${prefix}releases/${channel.release.id}/manifest.json`, "OTA_UNSAFE_PATH");
+			otaAssert(epoch === requestEpoch, "OTA_SCOPE_CHANGED");
+			s = await update((current) => {
+				otaAssert((current.cacheEpoch ?? 0) === cacheEpoch, "OTA_SCOPE_CHANGED");
+				otaAssert(channel.generation >= (current.highestGeneration ?? 0), "OTA_STALE_GENERATION");
+				return {
+					...current,
+					channel,
+					etag: reply.response.headers.get("ETag") ?? current.etag,
+					highestGeneration: channel.generation
+				};
+			});
+			if (s.active?.releaseId === channel.release.id) try {
+				const data = await parseSet(s.active);
+				await success(channel, cacheEpoch);
+				overlay = data;
+				activeRelease = s.active.releaseId;
+				return { status: "unchanged" };
+			} catch {}
+			const manifestUrl = deliveryUrl(origin, channel.release.manifestPath, prefix);
+			const fetched = await request(manifestUrl, OTA_LIMITS.manifestBytes, void 0, signal);
+			otaAssert(fetched.bytes && fetched.bytes.length === channel.release.bytes && await digest(fetched.bytes) === channel.release.sha256, "OTA_MANIFEST_INTEGRITY");
+			const manifest = validateReleaseManifest(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(fetched.bytes)));
+			otaAssert(manifest.distributionId === o.distributionId && manifest.releaseId === channel.release.id && manifest.catalogVersion === o.catalogVersion, "OTA_CATALOG_INCOMPATIBLE");
+			otaAssert(manifest.requiredBundles.every((b) => o.bundles.includes(b)), "OTA_MISSING_BUNDLE");
+			const assets = [];
+			for (const localeKey of localeKeys) {
+				const locale = manifest.locales.find((l) => l.localeKey === localeKey);
+				otaAssert(locale, "OTA_LOCALE_UNKNOWN");
+				for (const bundle of o.bundles) {
+					const asset = locale.assets.find((a) => a.bundle === bundle);
+					otaAssert(asset, "OTA_MISSING_BUNDLE");
+					otaAssert(["JSON_FLAT", "JSON_NESTED"].includes(asset.format), "OTA_UNSUPPORTED_FORMAT");
+					let bytes = await storage.readBlob(asset.sha256);
+					if (!bytes || bytes.length !== asset.bytes || await digest(bytes) !== asset.sha256) {
+						const url = deliveryUrl(manifestUrl.href, asset.path, `${prefix}releases/${manifest.releaseId}/assets/`);
+						let response = await request(url, OTA_LIMITS.assetBytes, void 0, signal);
+						if (!response.bytes) response = await request(url, OTA_LIMITS.assetBytes, void 0, signal);
+						otaAssert(response.bytes && response.bytes.length === asset.bytes && await digest(response.bytes) === asset.sha256, "OTA_ASSET_INTEGRITY");
+						bytes = response.bytes;
+						validateCatalog(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+						await storage.writeBlob(asset.sha256, bytes);
+					}
+					assets.push({
+						localeKey,
+						asset
+					});
+				}
+			}
+			const candidate = {
+				releaseId: manifest.releaseId,
+				generation: channel.generation,
+				assets
+			};
+			await parseSet(candidate);
+			otaAssert(epoch === requestEpoch, "OTA_SCOPE_CHANGED");
+			await update((current) => {
+				otaAssert((current.cacheEpoch ?? 0) === cacheEpoch, "OTA_SCOPE_CHANGED");
+				otaAssert(candidate.generation >= (current.highestGeneration ?? 0), "OTA_STALE_GENERATION");
+				return {
+					...current,
+					candidate
+				};
+			});
+			await success(channel, cacheEpoch);
+			notify(o.onUpdateAvailable, candidate.releaseId);
+			return {
+				status: "available",
+				releaseId: candidate.releaseId
+			};
+		} catch (err) {
+			const error = err instanceof OtaError ? err : err instanceof Error && /^OTA_[A-Z0-9_]{1,100}$/.test(err.message) ? err : new OtaError(err instanceof Error && err.name === "QuotaExceededError" ? "OTA_CACHE_QUOTA" : err instanceof Error && err.name === "TimeoutError" ? "OTA_TIMEOUT" : err instanceof SyntaxError ? "OTA_INVALID_DATA" : "OTA_UPDATE_FAILED");
+			const wire = error instanceof OtaError ? error : void 0;
+			await update((s) => {
+				if (cacheEpoch !== void 0 && (s.cacheEpoch ?? 0) !== cacheEpoch) return s;
+				const failures = (s.failures ?? 0) + 1;
+				const stopped = wire?.status === 410 && error.message === "OTA_DISTRIBUTION_RETIRED" ? "retired" : wire?.status === 401 || wire?.status === 403 ? "auth" : s.stopped;
+				const backoff = wire?.status === 404 ? 36e5 : Math.min(36e5, 15e3 * 2 ** Math.min(failures, 8));
+				const delay = Math.max(wire?.retryAfterMs ?? 0, backoff * (.8 + Math.random() * .4));
+				nextAttemptMonotonic = performance.now() + delay;
+				return {
+					...s,
+					failures,
+					stopped,
+					retryDelayMs: delay,
+					nextAttempt: Date.now() + delay
+				};
+			}).catch(() => void 0);
+			notify(o.onError, error);
+			return {
+				status: wire?.status === 410 && error.message === "OTA_DISTRIBUTION_RETIRED" ? "retired" : "error",
+				error: error.message
+			};
+		}
+	}
+	async function success(channel, cacheEpoch) {
+		const delay = Math.max(interval, Math.min(86400, channel.recommendedCheckIntervalSeconds) * 1e3) * (1 + Math.random() * .1);
+		await update((s) => {
+			otaAssert((s.cacheEpoch ?? 0) === cacheEpoch, "OTA_SCOPE_CHANGED");
+			return {
+				...s,
+				lastChecked: Date.now(),
+				failures: 0,
+				nextAttempt: 0,
+				retryDelayMs: 0,
+				nextCheck: Date.now() + delay
+			};
+		});
+		nextCheckMonotonic = performance.now() + delay;
+		nextAttemptMonotonic = void 0;
+	}
+	function checkForUpdates(input = {}) {
+		const key = scope;
+		const existing = pending.get(key);
+		if (existing) return existing;
+		const promise = check(input.forceRefresh ?? false, input.signal).finally(() => pending.delete(key));
+		pending.set(key, promise);
+		return promise;
+	}
+	async function activate(releaseId) {
+		const candidate = (await storage.read(scope)).candidate;
+		otaAssert(candidate?.releaseId === releaseId, "OTA_CANDIDATE_UNKNOWN");
+		const data = await parseSet(candidate);
+		const requestEpoch = epoch;
+		await update((current) => {
+			otaAssert(epoch === requestEpoch && current.candidate?.releaseId === releaseId && current.candidate.generation === candidate.generation && candidate.generation >= (current.highestGeneration ?? 0), "OTA_STALE_GENERATION");
+			return {
+				...current,
+				previous: current.active,
+				active: candidate,
+				candidate: void 0
+			};
+		});
+		overlay = data;
+		activeRelease = releaseId;
+		notify(o.onActivated, releaseId);
+		await storage.collect?.(scope).catch(() => void 0);
+	}
+	function getResources() {
+		const result = Object.create(null);
+		for (const locale of [...localeKeys].reverse()) {
+			for (const [namespace, catalog] of Object.entries(fallback[locale] ?? {})) result[namespace] = merge(result[namespace], catalog);
+			for (const [namespace, catalog] of Object.entries(overlay[locale] ?? {})) result[namespace] = merge(result[namespace], catalog);
+		}
+		return result;
+	}
+	return {
+		loadCached,
+		checkForUpdates,
+		activate,
+		getResources,
+		get activeReleaseId() {
+			return activeRelease;
+		},
+		async resetFailureState() {
+			await update((s) => ({
+				...s,
+				stopped: void 0,
+				nextAttempt: 0,
+				failures: 0,
+				lastChecked: void 0,
+				nextCheck: void 0,
+				etag: void 0
+			}));
+			nextCheckMonotonic = void 0;
+			nextAttemptMonotonic = void 0;
+		},
+		async clearCache() {
+			epoch++;
+			await storage.clear(scope);
+			overlay = {};
+			activeRelease = void 0;
+			nextCheckMonotonic = void 0;
+			nextAttemptMonotonic = void 0;
+		}
+	};
+}
+//#endregion
+export { createMemoryStorage as a, createIndexedDbStorage as i, createOtaClient as n, digest as r, OtaError as t };

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@syntholoc/ota",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.1",
+  "description": "Verified offline-first Syntholoc translation delivery client",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/ota/src/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/ota/src/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/ota/src/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./server": {
+        "types": "./dist/ota/src/server.d.ts",
+        "default": "./dist/server.js"
+      }
+    }
+  },
+  "devDependencies": {
+    "@syntholoc/shared": "0.1.0",
+    "@types/node": "22.19.21",
+    "@types/proper-lockfile": "4.1.4",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  },
+  "homepage": "https://syntholoc.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SergiyIva/syntholoc.git",
+    "directory": "packages/ota"
+  },
+  "dependencies": {
+    "proper-lockfile": "4.1.2"
+  }
+}