@aithos/sdk 0.1.0-alpha.43 → 0.1.0-alpha.44

package/dist/src/transcribe-resilience.js

@@ -0,0 +1,203 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+const LS_KEY = "aithos:transcribe:pending";
+/**
+ * Framework-agnostic observable registry of in-flight transcription jobs.
+ * Persisted to localStorage when available (so it survives reloads), with
+ * an in-memory fallback otherwise. Subscribe with `subscribe(listener)`;
+ * read with `getSnapshot()` (stable reference between mutations, so it
+ * plugs directly into React's `useSyncExternalStore`).
+ */
+export class LocalPendingTranscribeTracker {
+    #listeners = new Set();
+    #mem = [];
+    #snapshot = [];
+    constructor() {
+        this.#snapshot = this.#read();
+        // Cross-tab sync: when another tab updates the key, re-emit.
+        try {
+            if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+                window.addEventListener("storage", (e) => {
+                    if (e.key === LS_KEY) {
+                        this.#snapshot = this.#read();
+                        this.#emit();
+                    }
+                });
+            }
+        }
+        catch {
+            /* no window — fine */
+        }
+    }
+    #ls() {
+        try {
+            return typeof localStorage !== "undefined" ? localStorage : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    #read() {
+        const ls = this.#ls();
+        if (!ls)
+            return [...this.#mem];
+        try {
+            const raw = ls.getItem(LS_KEY);
+            return raw ? JSON.parse(raw) : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    #write(list) {
+        const ls = this.#ls();
+        if (ls) {
+            try {
+                ls.setItem(LS_KEY, JSON.stringify(list));
+            }
+            catch {
+                /* quota / private mode — keep in-memory copy authoritative */
+                this.#mem = list;
+            }
+        }
+        else {
+            this.#mem = list;
+        }
+        this.#snapshot = list;
+        this.#emit();
+    }
+    #emit() {
+        for (const l of this.#listeners)
+            l();
+    }
+    /** Current entries. Stable reference until the next mutation. */
+    getSnapshot() {
+        return this.#snapshot;
+    }
+    list() {
+        this.#snapshot = this.#read();
+        return this.#snapshot;
+    }
+    /** Subscribe to changes. Returns an unsubscribe function. */
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    upsert(jobId, status, meta) {
+        const now = Date.now();
+        const list = this.#read();
+        const idx = list.findIndex((e) => e.jobId === jobId);
+        if (idx >= 0) {
+            const prev = list[idx];
+            list[idx] = {
+                ...prev,
+                status,
+                updatedAt: now,
+                ...(meta ? { meta: { ...prev.meta, ...meta } } : {}),
+            };
+        }
+        else {
+            list.push({
+                jobId,
+                status,
+                createdAt: now,
+                updatedAt: now,
+                ...(meta ? { meta } : {}),
+            });
+        }
+        this.#write(list);
+    }
+    remove(jobId) {
+        const list = this.#read().filter((e) => e.jobId !== jobId);
+        this.#write(list);
+    }
+    clear() {
+        this.#write([]);
+    }
+}
+const DB_NAME = "aithos-transcribe";
+const DB_VERSION = 1;
+const STORE = "drafts";
+export class TranscribeDraftUnavailableError extends Error {
+    constructor() {
+        super("IndexedDB is not available in this environment — the transcription draft queue is browser-only.");
+        this.name = "TranscribeDraftUnavailableError";
+    }
+}
+function getIndexedDB() {
+    try {
+        if (typeof indexedDB !== "undefined")
+            return indexedDB;
+    }
+    catch {
+        /* fall through */
+    }
+    throw new TranscribeDraftUnavailableError();
+}
+function openDb() {
+    const idb = getIndexedDB();
+    return new Promise((resolve, reject) => {
+        const req = idb.open(DB_NAME, DB_VERSION);
+        req.onupgradeneeded = () => {
+            const db = req.result;
+            if (!db.objectStoreNames.contains(STORE)) {
+                db.createObjectStore(STORE, { keyPath: "draftId" });
+            }
+        };
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error("indexedDB open failed"));
+    });
+}
+function tx(db, mode, fn) {
+    return new Promise((resolve, reject) => {
+        const t = db.transaction(STORE, mode);
+        const req = fn(t.objectStore(STORE));
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error("indexedDB request failed"));
+    });
+}
+/**
+ * IndexedDB-backed queue of recorded audio Blobs. Save a recording the
+ * instant it finishes (before any network), then `upload` it when the
+ * user confirms — so a flaky network or a closed tab never loses audio.
+ * Browser-only: methods reject with {@link TranscribeDraftUnavailableError}
+ * when IndexedDB is absent.
+ */
+export class TranscribeDraftStore {
+    async save(blob, meta) {
+        const db = await openDb();
+        const draftId = `draft_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+        const record = {
+            draftId,
+            blob,
+            metadata: {
+                ...(meta ?? {}),
+                ...(meta?.contentType ? {} : { contentType: blob.type || "audio/webm" }),
+            },
+            createdAt: Date.now(),
+        };
+        await tx(db, "readwrite", (s) => s.put(record));
+        db.close();
+        return { draftId };
+    }
+    async list() {
+        const db = await openDb();
+        const out = await tx(db, "readonly", (s) => s.getAll());
+        db.close();
+        return out.sort((a, b) => a.createdAt - b.createdAt);
+    }
+    async get(draftId) {
+        const db = await openDb();
+        const rec = await tx(db, "readonly", (s) => s.get(draftId));
+        db.close();
+        return rec ?? null;
+    }
+    async delete(draftId) {
+        const db = await openDb();
+        await tx(db, "readwrite", (s) => s.delete(draftId));
+        db.close();
+    }
+}
+//# sourceMappingURL=transcribe-resilience.js.map

package/dist/test/transcribe-invoke.test.d.ts

@@ -0,0 +1,2 @@
+import "fake-indexeddb/auto";
+//# sourceMappingURL=transcribe-invoke.test.d.ts.map

package/dist/test/transcribe-invoke.test.js

@@ -0,0 +1,204 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Tests for the high-level invokeTranscribe flow (prepare -> upload -> start
+// -> poll) and the framework-agnostic resilience helpers (local pending
+// tracker + IndexedDB draft store). fake-indexeddb/auto installs an
+// in-memory IndexedDB for the draft tests.
+import "fake-indexeddb/auto";
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { createBrowserIdentity } from "@aithos/protocol-client";
+import { AithosAuth, AithosSDK, LocalPendingTranscribeTracker, TranscribeDraftStore, memoryKeyStore, noopStore, } from "../src/index.js";
+import { serializeRecoveryFile } from "../src/internal/recovery-file.js";
+const APP_DID = "did:aithos:app:test";
+const UPLOAD_URL = "https://s3.example.test/upload?sig=abc";
+async function makeSdk(fetchImpl) {
+    const id = createBrowserIdentity("test-handle", "Test User");
+    const auth = new AithosAuth({
+        authBaseUrl: "https://auth.test",
+        fetch: (() => {
+            throw new Error("auth not used");
+        }),
+        sessionStore: noopStore(),
+        keyStore: memoryKeyStore(),
+    });
+    const { text } = serializeRecoveryFile(id);
+    await auth.signInWithRecovery({ file: text });
+    return new AithosSDK({
+        auth,
+        appDid: APP_DID,
+        endpoints: { compute: "https://compute.example.test" },
+        fetch: fetchImpl,
+    });
+}
+function jsonRpc(result) {
+    return new Response(JSON.stringify({ result }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+    });
+}
+describe("compute.invokeTranscribe — full flow", () => {
+    it("prepares, uploads to S3, starts, polls and returns the transcript", async () => {
+        const calls = [];
+        let putBytes = 0;
+        let statusPolls = 0;
+        const fetchImpl = async (input, init) => {
+            const url = typeof input === "string" ? input : input.toString();
+            if (init?.method === "PUT" && url.startsWith("https://s3.example.test/")) {
+                // S3 upload.
+                calls.push("s3-put");
+                putBytes = init.body.size;
+                return new Response("", { status: 200 });
+            }
+            const method = JSON.parse(init?.body).method;
+            calls.push(method);
+            if (method === "aithos.compute_transcribe_prepare") {
+                return jsonRpc({
+                    job_id: "tj_FLOW",
+                    upload_url: UPLOAD_URL,
+                    s3_object_key: "uploads/2026/05/tj_FLOW.webm",
+                    expires_at: 1717000000,
+                });
+            }
+            if (method === "aithos.compute_transcribe_start") {
+                return jsonRpc({
+                    job_id: "tj_FLOW",
+                    status: "running",
+                    estimated_credits: 60,
+                    walletBalance: 49_940,
+                    fundedBy: "purchase",
+                });
+            }
+            if (method === "aithos.compute_transcribe_status") {
+                statusPolls += 1;
+                if (statusPolls < 2) {
+                    return jsonRpc({ job_id: "tj_FLOW", status: "running", elapsed_sec: 1 });
+                }
+                return jsonRpc({
+                    job_id: "tj_FLOW",
+                    status: "completed",
+                    text: "Bonjour le monde",
+                    segments: [{ start_sec: 0, end_sec: 1.4, text: "Bonjour le monde" }],
+                    words: [{ start_sec: 0, end_sec: 0.4, content: "Bonjour", confidence: 0.99 }],
+                    duration_sec_actual: 30,
+                    language_code: "fr-FR",
+                    creditsCharged: 60,
+                    walletBalance: 49_940,
+                    auditId: "audit_flow",
+                    fundedBy: "purchase",
+                });
+            }
+            throw new Error(`unexpected method ${method}`);
+        };
+        const sdk = await makeSdk(fetchImpl);
+        const phases = [];
+        const audio = new Blob([new Uint8Array(2048)], { type: "audio/webm" });
+        const result = await sdk.compute.invokeTranscribe({
+            audio,
+            durationSecOverride: 30,
+            pollIntervalMs: 1,
+            onProgress: (s) => phases.push(s.phase),
+        });
+        assert.equal(result.text, "Bonjour le monde");
+        assert.equal(result.durationSec, 30);
+        assert.equal(result.creditsCharged, 60);
+        assert.equal(result.jobId, "tj_FLOW");
+        assert.equal(result.fundedBy, "purchase");
+        assert.equal(result.segments.length, 1);
+        // The flow visited every step in order.
+        assert.deepEqual(calls, [
+            "aithos.compute_transcribe_prepare",
+            "s3-put",
+            "aithos.compute_transcribe_start",
+            "aithos.compute_transcribe_status",
+            "aithos.compute_transcribe_status",
+        ]);
+        assert.equal(putBytes, 2048);
+        assert.ok(phases.includes("queued"));
+        assert.ok(phases.includes("uploading"));
+        assert.ok(phases.includes("starting"));
+        assert.ok(phases.includes("completed"));
+        // Job cleared from the local pending tracker on success.
+        assert.equal(sdk.compute.listLocalPendingTranscribes().length, 0);
+    });
+    it("throws an AithosSDKError when the job fails, leaving the job flagged failed", async () => {
+        const fetchImpl = async (input, init) => {
+            const url = typeof input === "string" ? input : input.toString();
+            if (init?.method === "PUT")
+                return new Response("", { status: 200 });
+            const method = JSON.parse(init?.body).method;
+            if (method === "aithos.compute_transcribe_prepare") {
+                return jsonRpc({ job_id: "tj_F", upload_url: UPLOAD_URL, s3_object_key: "k", expires_at: 1 });
+            }
+            if (method === "aithos.compute_transcribe_start") {
+                return jsonRpc({ job_id: "tj_F", status: "running", estimated_credits: 60, walletBalance: 1 });
+            }
+            return jsonRpc({
+                job_id: "tj_F",
+                status: "failed",
+                error: { code: "transcribe_provider_error", message: "bad audio" },
+            });
+        };
+        const sdk = await makeSdk(fetchImpl);
+        const audio = new Blob([new Uint8Array(10)], { type: "audio/webm" });
+        await assert.rejects(() => sdk.compute.invokeTranscribe({ audio, durationSecOverride: 30, pollIntervalMs: 1 }), (e) => {
+            assert.ok(e instanceof Error);
+            assert.match(e.message, /bad audio/);
+            return true;
+        });
+        const pending = sdk.compute.listLocalPendingTranscribes();
+        assert.equal(pending.find((p) => p.jobId === "tj_F")?.status, "failed");
+    });
+});
+describe("LocalPendingTranscribeTracker (vanilla, framework-agnostic)", () => {
+    it("upserts, lists, removes and notifies subscribers", () => {
+        const t = new LocalPendingTranscribeTracker();
+        t.clear();
+        let notifications = 0;
+        const unsub = t.subscribe(() => {
+            notifications += 1;
+        });
+        t.upsert("tj_1", "uploading", { model: "transcribe:aws-fr-standard" });
+        assert.equal(t.list().length, 1);
+        assert.equal(t.list()[0]?.status, "uploading");
+        t.upsert("tj_1", "running");
+        assert.equal(t.list().length, 1, "same job id updates in place");
+        assert.equal(t.list()[0]?.status, "running");
+        t.upsert("tj_2", "running");
+        assert.equal(t.list().length, 2);
+        t.remove("tj_1");
+        assert.equal(t.list().length, 1);
+        assert.equal(t.list()[0]?.jobId, "tj_2");
+        assert.ok(notifications >= 4, "subscriber fired on each mutation");
+        unsub();
+        const before = notifications;
+        t.upsert("tj_3", "running");
+        assert.equal(notifications, before, "no notification after unsubscribe");
+    });
+    it("getSnapshot returns a stable reference between mutations", () => {
+        const t = new LocalPendingTranscribeTracker();
+        t.clear();
+        const a = t.getSnapshot();
+        const b = t.getSnapshot();
+        assert.equal(a, b);
+        t.upsert("tj_x", "running");
+        assert.notEqual(t.getSnapshot(), a, "new reference after a mutation");
+    });
+});
+describe("TranscribeDraftStore (IndexedDB via fake-indexeddb)", () => {
+    it("saves, lists, gets and deletes a draft", async () => {
+        const store = new TranscribeDraftStore();
+        const blob = new Blob([new Uint8Array(64)], { type: "audio/webm" });
+        const { draftId } = await store.save(blob, { title: "séance 1" });
+        assert.ok(draftId.startsWith("draft_"));
+        const list = await store.list();
+        assert.ok(list.some((d) => d.draftId === draftId));
+        const got = await store.get(draftId);
+        assert.equal(got?.metadata.title, "séance 1");
+        assert.equal(got?.metadata.contentType, "audio/webm");
+        assert.equal(got?.blob.size, 64);
+        await store.delete(draftId);
+        assert.equal(await store.get(draftId), null);
+    });
+});
+//# sourceMappingURL=transcribe-invoke.test.js.map

package/dist/test/transcribe.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transcribe.test.d.ts.map

package/dist/test/transcribe.test.js

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Unit tests for the transcription low-level API (sdk.compute.{prepare,
+// start,getStatus,listPending}Transcribe) with a mock fetch. A real
+// BrowserIdentity signs the envelopes, so any signing/canonicalization
+// regression surfaces here too.
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { createBrowserIdentity } from "@aithos/protocol-client";
+import { AithosAuth, AithosSDK, memoryKeyStore, noopStore, } from "../src/index.js";
+import { serializeRecoveryFile } from "../src/internal/recovery-file.js";
+const APP_DID = "did:aithos:app:test";
+async function makeSdk(fetchImpl) {
+    const id = createBrowserIdentity("test-handle", "Test User");
+    const auth = new AithosAuth({
+        authBaseUrl: "https://auth.test",
+        fetch: (() => {
+            throw new Error("auth not used in compute tests");
+        }),
+        sessionStore: noopStore(),
+        keyStore: memoryKeyStore(),
+    });
+    const { text } = serializeRecoveryFile(id);
+    await auth.signInWithRecovery({ file: text });
+    return new AithosSDK({
+        auth,
+        appDid: APP_DID,
+        endpoints: { compute: "https://compute.example.test" },
+        fetch: fetchImpl,
+    });
+}
+function jsonRpc(result) {
+    return new Response(JSON.stringify({ result }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+    });
+}
+function bodyParams(init) {
+    return JSON.parse(init?.body).params;
+}
+function bodyMethod(init) {
+    return JSON.parse(init?.body).method;
+}
+describe("compute.prepareTranscribe", () => {
+    it("posts transcribe_prepare with app_did + content_type and maps the result", async () => {
+        let method;
+        let params;
+        const sdk = await makeSdk(async (_url, init) => {
+            method = bodyMethod(init);
+            params = bodyParams(init);
+            return jsonRpc({
+                job_id: "tj_ABC",
+                upload_url: "https://s3.example/upload?sig=1",
+                s3_object_key: "uploads/2026/05/tj_ABC.webm",
+                expires_at: 1717000000,
+            });
+        });
+        const out = await sdk.compute.prepareTranscribe({
+            contentType: "audio/webm",
+            durationSecEstimate: 120,
+        });
+        assert.equal(method, "aithos.compute_transcribe_prepare");
+        assert.equal(params?.app_did, APP_DID);
+        assert.equal(params?.content_type, "audio/webm");
+        assert.equal(params?.duration_sec_estimate, 120);
+        assert.ok(params._envelope, "must carry an envelope");
+        assert.deepEqual(out, {
+            jobId: "tj_ABC",
+            uploadUrl: "https://s3.example/upload?sig=1",
+            s3ObjectKey: "uploads/2026/05/tj_ABC.webm",
+            expiresAt: 1717000000,
+        });
+    });
+});
+describe("compute.startTranscribe", () => {
+    it("posts transcribe_start with the wire params and maps the result", async () => {
+        let method;
+        let params;
+        const sdk = await makeSdk(async (_url, init) => {
+            method = bodyMethod(init);
+            params = bodyParams(init);
+            return jsonRpc({
+                job_id: "tj_ABC",
+                status: "running",
+                estimated_credits: 240,
+                walletBalance: 49_760,
+                fundedBy: "purchase",
+            });
+        });
+        const out = await sdk.compute.startTranscribe({
+            jobId: "tj_ABC",
+            model: "transcribe:aws-fr-standard",
+            durationSec: 120,
+            languageCode: "fr-FR",
+            diarization: false,
+            idempotencyKey: "ik_1",
+        });
+        assert.equal(method, "aithos.compute_transcribe_start");
+        assert.equal(params?.job_id, "tj_ABC");
+        assert.equal(params?.model, "transcribe:aws-fr-standard");
+        assert.equal(params?.duration_sec, 120);
+        assert.equal(params?.language_code, "fr-FR");
+        assert.equal(params?.diarization, false);
+        assert.equal(params?.idempotency_key, "ik_1");
+        assert.ok(typeof params?.mandate_id === "string" && params.mandate_id.length > 0);
+        assert.deepEqual(out, {
+            jobId: "tj_ABC",
+            status: "running",
+            estimatedCredits: 240,
+            walletBalance: 49_760,
+            fundedBy: "purchase",
+        });
+    });
+});
+describe("compute.getTranscribeStatus", () => {
+    it("maps a running response", async () => {
+        const sdk = await makeSdk(async () => jsonRpc({ job_id: "tj_ABC", status: "running", elapsed_sec: 12 }));
+        const out = await sdk.compute.getTranscribeStatus({ jobId: "tj_ABC" });
+        assert.deepEqual(out, { jobId: "tj_ABC", status: "running", elapsedSec: 12 });
+    });
+    it("maps a completed response (duration_sec_actual -> durationSec)", async () => {
+        const sdk = await makeSdk(async () => jsonRpc({
+            job_id: "tj_ABC",
+            status: "completed",
+            text: "Bonjour le monde",
+            segments: [{ start_sec: 0, end_sec: 1.4, text: "Bonjour le monde" }],
+            words: [{ start_sec: 0, end_sec: 0.4, content: "Bonjour", confidence: 0.99 }],
+            duration_sec_actual: 127,
+            language_code: "fr-FR",
+            creditsCharged: 254,
+            walletBalance: 49_746,
+            auditId: "audit_1",
+            fundedBy: "purchase",
+        }));
+        const out = await sdk.compute.getTranscribeStatus({ jobId: "tj_ABC" });
+        assert.equal(out.status, "completed");
+        if (out.status !== "completed")
+            return;
+        assert.equal(out.text, "Bonjour le monde");
+        assert.equal(out.durationSec, 127);
+        assert.equal(out.languageCode, "fr-FR");
+        assert.equal(out.creditsCharged, 254);
+        assert.equal(out.auditId, "audit_1");
+        assert.equal(out.fundedBy, "purchase");
+        assert.equal(out.segments.length, 1);
+        assert.equal(out.words[0]?.content, "Bonjour");
+    });
+    it("maps a failed response", async () => {
+        const sdk = await makeSdk(async () => jsonRpc({
+            job_id: "tj_ABC",
+            status: "failed",
+            error: { code: "transcribe_provider_error", message: "boom" },
+        }));
+        const out = await sdk.compute.getTranscribeStatus({ jobId: "tj_ABC" });
+        assert.equal(out.status, "failed");
+        if (out.status !== "failed")
+            return;
+        assert.equal(out.error.code, "transcribe_provider_error");
+        assert.equal(out.error.message, "boom");
+    });
+});
+describe("compute.listPendingTranscribes", () => {
+    it("forwards include_completed and maps job summaries", async () => {
+        let params;
+        const sdk = await makeSdk(async (_url, init) => {
+            params = bodyParams(init);
+            return jsonRpc({
+                jobs: [
+                    { job_id: "tj_1", status: "running", created_at: 1717000000, estimated_credits: 240 },
+                    { job_id: "tj_2", status: "completed", created_at: 1717000100, creditsCharged: 250 },
+                ],
+            });
+        });
+        const out = await sdk.compute.listPendingTranscribes({ includeCompleted: true });
+        assert.equal(params?.include_completed, true);
+        assert.equal(out.jobs.length, 2);
+        assert.deepEqual(out.jobs[0], {
+            jobId: "tj_1",
+            status: "running",
+            createdAt: 1717000000,
+            estimatedCredits: 240,
+        });
+        assert.equal(out.jobs[1]?.creditsCharged, 250);
+    });
+});
+//# sourceMappingURL=transcribe.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.43",
+  "version": "0.1.0-alpha.44",
   "description": "Aithos SDK — high-level TypeScript developer kit for building agentic apps on the Aithos protocol. Wraps @aithos/protocol-client and exposes the Aithos compute proxy and wallet (Stripe top-up) endpoints.",
   "keywords": [
     "aithos",