@aithos/sdk 0.1.0-alpha.6 → 0.1.0-alpha.60

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/src/web.d.ts

@@ -0,0 +1,279 @@
+import type { AithosAuth } from "./auth.js";
+import { type AithosSdkEndpoints } from "./endpoints.js";
+/** Opt-in scope a mandate must carry to invoke `aithos.web_extract`. */
+export declare const WEB_EXTRACT_SCOPE: "web.extract";
+export interface ExtractArgs {
+    /**
+     * Mandate ID under which this call should be attributed.
+     *
+     * - **Owner sessions**: optional. The SDK uses the owner's own DID
+     *   as a sentinel "self" mandate id — the proxy skips mandate checks
+     *   when the envelope is owner-signed.
+     * - **Delegate sessions**: required. Must reference the imported
+     *   mandate bundle the SDK signs with; the proxy enforces the
+     *   `web.extract` scope.
+     */
+    readonly mandateId?: string;
+    /** Absolute http(s) URL to extract. */
+    readonly url: string;
+    /**
+     * Playwright `waitUntil` strategy passed straight through to the
+     * server-side navigation. Defaults to `"networkidle"` server-side
+     * if omitted.
+     */
+    readonly waitUntil?: "load" | "domcontentloaded" | "networkidle";
+    /** Navigation timeout in ms. Server validates [1000, 60000]. */
+    readonly timeoutMs?: number;
+    /** Reserved for audit-level deduplication; the proxy currently does not
+     *  enforce idempotency keys for extractions. */
+    readonly idempotencyKey?: string;
+    /** Abort signal to cancel the request. */
+    readonly signal?: AbortSignal;
+}
+export interface ExtractMeta {
+    readonly title: string | null;
+    readonly description: string | null;
+    readonly lang: string | null;
+    readonly charset: string | null;
+    readonly viewport: string | null;
+    readonly canonical: string | null;
+    readonly og: Readonly<Record<string, string>>;
+}
+export interface ExtractHeading {
+    readonly level: 1 | 2 | 3 | 4 | 5 | 6;
+    readonly text: string;
+    readonly id: string | null;
+}
+export interface ExtractSection {
+    readonly tag: string;
+    readonly role: string | null;
+    readonly html: string;
+    readonly text_len: number;
+}
+export interface ExtractLink {
+    readonly label: string;
+    readonly href: string;
+    readonly internal: boolean;
+}
+export interface ExtractImage {
+    readonly src: string;
+    readonly alt: string | null;
+    readonly role: string | null;
+}
+export interface ExtractFormField {
+    readonly type: string;
+    readonly name: string | null;
+    readonly required: boolean;
+}
+export interface ExtractForm {
+    readonly action: string | null;
+    readonly method: string;
+    readonly fields: readonly ExtractFormField[];
+}
+export interface ExtractStructure {
+    readonly headings: readonly ExtractHeading[];
+    readonly sections: readonly ExtractSection[];
+    readonly nav_links: readonly ExtractLink[];
+    readonly forms: readonly ExtractForm[];
+}
+export interface ExtractContent {
+    readonly main_html: string;
+    readonly main_text: string;
+    readonly images: readonly ExtractImage[];
+    readonly links: {
+        readonly internal: readonly ExtractLink[];
+        readonly external: readonly ExtractLink[];
+    };
+}
+export interface ExtractStyles {
+    readonly css: string;
+    readonly inline_styles_count: number;
+}
+export interface PaletteEntry {
+    readonly hex: string;
+    readonly weight: number;
+    readonly role: "background" | "text" | "accent" | "other";
+}
+export interface ComponentStyle {
+    readonly count: number;
+    readonly bg: string | null;
+    readonly fg: string | null;
+    readonly border: string | null;
+    readonly radius: string | null;
+    readonly padding: string | null;
+    readonly font_size: string | null;
+    readonly font_weight: string | null;
+}
+export interface VisualSignature {
+    readonly colors: {
+        readonly palette: readonly PaletteEntry[];
+        readonly background: string | null;
+        readonly text: string | null;
+        readonly primary: string | null;
+        readonly link: string | null;
+    };
+    readonly typography: {
+        readonly heading_font: string | null;
+        readonly body_font: string | null;
+        readonly size_scale: readonly number[];
+        readonly base_size_px: number | null;
+        readonly base_line_height: number | null;
+    };
+    readonly radii: {
+        readonly button: string | null;
+        readonly input: string | null;
+        readonly card: string | null;
+    };
+    readonly spacing: {
+        readonly base_unit_px: number | null;
+        readonly common_gaps_px: readonly number[];
+    };
+    readonly layout: {
+        readonly max_content_width_px: number | null;
+        readonly mode: "flex" | "grid" | "block" | null;
+    };
+    readonly components: {
+        readonly buttons: readonly ComponentStyle[];
+        readonly inputs: readonly ComponentStyle[];
+        readonly cards: readonly ComponentStyle[];
+    };
+}
+export interface ExtractIconDeclaration {
+    /** href as written in the HTML (relative or absolute). */
+    readonly href: string;
+    /** rel value, lowercased: "icon", "apple-touch-icon", "shortcut icon", ... */
+    readonly rel: string;
+    /** Declared `sizes` attribute, e.g. "180x180" or "any" or null. */
+    readonly sizes: string | null;
+    /** Declared mime type, e.g. "image/svg+xml" or null. */
+    readonly type: string | null;
+}
+/**
+ * Logo asset resolved server-side. The Lambda picks the best
+ * symbol-only asset available on the page — declared <link rel="icon"|
+ * "apple-touch-icon"> declarations + conventional well-known paths
+ * (/apple-touch-icon.png, /favicon.svg, /favicon.ico) — in that
+ * order of expected quality. Null when nothing resolves.
+ *
+ * Favicons are symbol-only by construction (no designer ships a
+ * wordmark inside a 16-180 px icon), which sidesteps the
+ * lockup-vs-symbol problem callers used to handle client-side with
+ * a vision model.
+ */
+export interface ExtractLogo {
+    /** Absolute URL of the asset that was successfully fetched. */
+    readonly url: string;
+    /** Which source produced the winner. */
+    readonly source: "link-icon-svg" | "link-apple-touch-icon" | "link-icon-large" | "link-icon" | "link-shortcut-icon" | "well-known-apple-180" | "well-known-apple" | "well-known-svg" | "well-known-png-large" | "well-known-ico";
+    readonly content_type: string;
+    readonly size_bytes: number;
+    /** Base64-encoded asset bytes (no `data:` prefix). Build a data
+     *  URI with `data:${content_type};base64,${base64}`. */
+    readonly base64: string;
+}
+export interface ExtractData {
+    readonly url: string;
+    readonly final_url: string;
+    readonly fetched_at: string;
+    readonly render_ms: number;
+    readonly meta: ExtractMeta;
+    readonly structure: ExtractStructure;
+    readonly content: ExtractContent;
+    readonly styles: ExtractStyles;
+    readonly visual_signature: VisualSignature;
+    /**
+     * Best logo asset resolved by the lambda — null when no
+     * <link rel="icon"> declaration and no conventional favicon
+     * path produced a usable image. Callers should then let the
+     * operator upload the logo manually rather than treat this as
+     * a fatal error.
+     */
+    readonly logo: ExtractLogo | null;
+}
+export interface ExtractResult {
+    /** Cleaned extraction payload. */
+    readonly data: ExtractData;
+    /** Microcredits charged for this call (1 on success, 0 on refunded failures). */
+    readonly creditsCharged: number;
+    /** Wallet balance after the (possibly refunded) debit. */
+    readonly walletBalance: number;
+    /** Audit log id for traceability. */
+    readonly auditId: string;
+}
+export interface FetchAssetArgs {
+    /** Absolute http(s) URL of the asset to fetch. */
+    readonly url: string;
+    /** Mandate id under which this call should be attributed. */
+    readonly mandateId?: string;
+    /** Abort signal. */
+    readonly signal?: AbortSignal;
+}
+export interface FetchAssetResult {
+    /** Asset payload. */
+    readonly data: {
+        /** URL we asked the proxy to fetch. */
+        readonly url: string;
+        /** URL after the proxy followed any redirects. */
+        readonly final_url: string;
+        /** Content-Type reported by the upstream server. */
+        readonly content_type: string;
+        /** Size of the fetched body in bytes. */
+        readonly size_bytes: number;
+        /** Base64-encoded body (no `data:` prefix). Build a data URI
+         *  with `data:${content_type};base64,${base64}`. */
+        readonly base64: string;
+    };
+    /** Microcredits charged for this call. */
+    readonly creditsCharged: number;
+    readonly walletBalance: number;
+    readonly auditId: string;
+}
+export interface WebNamespaceDeps {
+    readonly auth: AithosAuth;
+    readonly appDid: string;
+    readonly endpoints: AithosSdkEndpoints;
+    readonly fetch: typeof fetch;
+}
+/**
+ * `sdk.web` namespace — Aithos's web extraction primitive.
+ *
+ * Designed so a downstream agent can read the static content of any
+ * public page (HTML, purged CSS, computed visual signature) without
+ * involving an LLM — saving ~30× over a Bedrock-based extraction in
+ * both latency and cost.
+ *
+ * @throws {AithosSDKError} — same error taxonomy as `sdk.compute`,
+ *   including `-32071` (insufficient balance with `{required, available}`
+ *   in `data`) and `-32042` (mandate scope mismatch).
+ */
+export declare class WebNamespace {
+    #private;
+    constructor(deps: WebNamespaceDeps);
+    /**
+     * Extract a public webpage. Returns the cleaned HTML, purged CSS and
+     * a deterministic visual signature (palette, typography, dominant
+     * radii, spacing, layout mode, component digests).
+     */
+    extract(args: ExtractArgs): Promise<ExtractResult>;
+    /**
+     * Fetch a single asset (image / font / css / json …) server-side,
+     * bypassing browser CORS. Returns the bytes as base64 + content-type.
+     *
+     * Use when `fetch(url, {mode: "cors"})` and `<img crossOrigin>`
+     * canvas readback both fail because the asset server doesn't return
+     * Access-Control-Allow-Origin headers — typical for production
+     * sites' logos hosted on the main domain.
+     *
+     * For the common "logo of a webpage" case the lambda already
+     * resolves and embeds the best symbol-only logo in
+     * {@link extract}'s `data.logo` field; you only need fetchAsset
+     * when extract's logo doesn't fit, when picking up secondary
+     * assets (og:image, hero image, document download), or when
+     * fetching an asset on a page you haven't extracted.
+     *
+     * Costs 1 mc per successful fetch, full refund on failure. Server
+     * caps: 15 s timeout, 10 MB body, http/https only.
+     */
+    fetchAsset(args: FetchAssetArgs): Promise<FetchAssetResult>;
+}
+//# sourceMappingURL=web.d.ts.map

package/dist/src/web.js

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Web namespace — `aithos.web_extract` through the web-extractor proxy.
+//
+// Same JSON-RPC + signed-envelope protocol as the compute namespace, but
+// against a separate Aithos service (`extract.aithos.be`). Pricing is a
+// flat 1 microcredit per successful extraction (refunded on failure).
+//
+// The mandate scope is `web.extract` (exported as {@link WEB_EXTRACT_SCOPE}
+// for owner mint-time use). A delegate that holds only this scope can read
+// pages on the owner's behalf without gaining LLM-spend authority.
+//
+// Signing follows the same owner-vs-delegate logic as the compute namespace
+// (see ComputeNamespace.#resolveSigner). The duplication is bounded — both
+// namespaces' `#signAndPost` helpers can later move into a shared internal
+// once a third primitive arrives.
+import { buildSignedEnvelope, } from "@aithos/protocol-client";
+import { webInvokeUrl, } from "./endpoints.js";
+import { delegateKeyPair, ownerKeyPair, } from "./internal/protocol-client-bridge.js";
+import { AithosSDKError } from "./types.js";
+/** Opt-in scope a mandate must carry to invoke `aithos.web_extract`. */
+export const WEB_EXTRACT_SCOPE = "web.extract";
+/**
+ * `sdk.web` namespace — Aithos's web extraction primitive.
+ *
+ * Designed so a downstream agent can read the static content of any
+ * public page (HTML, purged CSS, computed visual signature) without
+ * involving an LLM — saving ~30× over a Bedrock-based extraction in
+ * both latency and cost.
+ *
+ * @throws {AithosSDKError} — same error taxonomy as `sdk.compute`,
+ *   including `-32071` (insufficient balance with `{required, available}`
+ *   in `data`) and `-32042` (mandate scope mismatch).
+ */
+export class WebNamespace {
+    #deps;
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    /**
+     * Extract a public webpage. Returns the cleaned HTML, purged CSS and
+     * a deterministic visual signature (palette, typography, dominant
+     * radii, spacing, layout mode, component digests).
+     */
+    async extract(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        const url = webInvokeUrl(endpoints);
+        const params = {
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
+            url: args.url,
+        };
+        if (args.waitUntil !== undefined)
+            params.waitUntil = args.waitUntil;
+        if (args.timeoutMs !== undefined)
+            params.timeoutMs = args.timeoutMs;
+        if (args.idempotencyKey !== undefined) {
+            params.idempotencyKey = args.idempotencyKey;
+        }
+        return await this.#signAndPost({
+            url,
+            method: "aithos.web_extract",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+    }
+    /**
+     * Fetch a single asset (image / font / css / json …) server-side,
+     * bypassing browser CORS. Returns the bytes as base64 + content-type.
+     *
+     * Use when `fetch(url, {mode: "cors"})` and `<img crossOrigin>`
+     * canvas readback both fail because the asset server doesn't return
+     * Access-Control-Allow-Origin headers — typical for production
+     * sites' logos hosted on the main domain.
+     *
+     * For the common "logo of a webpage" case the lambda already
+     * resolves and embeds the best symbol-only logo in
+     * {@link extract}'s `data.logo` field; you only need fetchAsset
+     * when extract's logo doesn't fit, when picking up secondary
+     * assets (og:image, hero image, document download), or when
+     * fetching an asset on a page you haven't extracted.
+     *
+     * Costs 1 mc per successful fetch, full refund on failure. Server
+     * caps: 15 s timeout, 10 MB body, http/https only.
+     */
+    async fetchAsset(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        const url = webInvokeUrl(endpoints);
+        const params = {
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
+            url: args.url,
+        };
+        return await this.#signAndPost({
+            url,
+            method: "aithos.web_fetch_asset",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+    }
+    /* ----------------------------- internals ----------------------------- */
+    #resolveSigner(mandateId) {
+        const { auth } = this.#deps;
+        const owner = auth._getOwnerSigners();
+        const ownerLoaded = owner !== null && !owner.destroyed;
+        if (ownerLoaded) {
+            const publicKp = ownerKeyPair(owner, "public");
+            return {
+                kind: "owner",
+                iss: owner.did,
+                verificationMethod: `${owner.did}#public`,
+                signer: publicKp,
+                mandate: undefined,
+            };
+        }
+        if (mandateId === undefined || mandateId.length === 0) {
+            throw new AithosSDKError("sdk_no_signer", "no owner signed in and no mandateId provided — pass a mandateId for a delegate session, or sign in as an owner first.");
+        }
+        const actor = auth._getDelegateActor(mandateId);
+        if (!actor || actor.destroyed) {
+            throw new AithosSDKError("sdk_no_delegate_for_mandate", `no owner signed in and no imported delegate mandate matches '${mandateId}'. Sign in as an owner, or import a delegate bundle for that mandate via auth.importMandate.`);
+        }
+        const kp = delegateKeyPair(actor);
+        return {
+            kind: "delegate",
+            iss: actor.subjectDid,
+            verificationMethod: actor.granteePubkeyMultibase,
+            signer: kp,
+            mandate: actor.mandate,
+        };
+    }
+    #resolveMandateIdForWire(explicit, choice) {
+        if (explicit && explicit.length > 0)
+            return explicit;
+        if (choice.kind === "delegate")
+            return choice.mandate.id;
+        return `${choice.iss}#self`;
+    }
+    async #signAndPost(opts) {
+        const { url, method, params, choice, fetchImpl, signal } = opts;
+        const envelope = buildSignedEnvelope({
+            iss: choice.iss,
+            aud: url,
+            method,
+            verificationMethod: choice.verificationMethod,
+            params,
+            signer: choice.signer,
+            ...(choice.kind === "delegate" ? { mandate: choice.mandate } : {}),
+        });
+        let res;
+        try {
+            res = await fetchImpl(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: method,
+                    method,
+                    params: { ...params, _envelope: envelope },
+                }),
+                ...(signal ? { signal } : {}),
+            });
+        }
+        catch (e) {
+            throw new AithosSDKError("network", e.message);
+        }
+        if (!res.ok) {
+            throw new AithosSDKError("http", `HTTP ${res.status} ${res.statusText}`, { status: res.status });
+        }
+        const body = (await res.json());
+        if (body.error) {
+            throw new AithosSDKError(String(body.error.code), body.error.message, body.error.data ? { data: body.error.data } : undefined);
+        }
+        if (!body.result) {
+            throw new AithosSDKError("empty", "empty result from web extractor proxy");
+        }
+        return body.result;
+    }
+}
+//# sourceMappingURL=web.js.map

package/dist/test/agent-dispatch.test.d.ts

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