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

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

@@ -0,0 +1,29 @@
+/**
+ * `@aithos/sdk/react` — React bindings for the Aithos SDK.
+ *
+ * Drop-in components and hooks for displaying Aithos-hosted assets in
+ * React applications. The package's only peer dependency beyond
+ * `@aithos/sdk` itself is `react` (^18 || ^19).
+ *
+ * Quick start:
+ *
+ *     // 1. Wrap your tree once
+ *     <AssetsClientProvider client={sdk.assets}>
+ *       <App />
+ *     </AssetsClientProvider>
+ *
+ *     // 2. Use anywhere
+ *     <AithosAsset urn={cv.urn} alt="CV" className="w-full" />
+ *     <AithosAsset urn={video.urn} as="video" controls />
+ *     <AithosAsset urn={pdf.urn} as="download" filename="cv.pdf">
+ *       Download my CV
+ *     </AithosAsset>
+ *
+ *     // 3. Or use the hook directly for custom rendering
+ *     const { url, bytes, loading, error } = useAithosAsset(urn);
+ */
+export { AssetsClientProvider, useAssetsClient, type AssetsClientProviderProps, } from "./context.js";
+export { useAithosAsset, type UseAithosAssetState, type UseAithosAssetOptions, } from "./use-aithos-asset.js";
+export { AithosAsset, type AithosAssetProps, type AithosImageProps, type AithosVideoProps, type AithosAudioProps, type AithosDownloadProps, } from "./AithosAsset.js";
+export { useAithosTranscribePendingJobs, type UseAithosTranscribePendingJobs, } from "./use-transcribe-pending.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/react/index.js

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * `@aithos/sdk/react` — React bindings for the Aithos SDK.
+ *
+ * Drop-in components and hooks for displaying Aithos-hosted assets in
+ * React applications. The package's only peer dependency beyond
+ * `@aithos/sdk` itself is `react` (^18 || ^19).
+ *
+ * Quick start:
+ *
+ *     // 1. Wrap your tree once
+ *     <AssetsClientProvider client={sdk.assets}>
+ *       <App />
+ *     </AssetsClientProvider>
+ *
+ *     // 2. Use anywhere
+ *     <AithosAsset urn={cv.urn} alt="CV" className="w-full" />
+ *     <AithosAsset urn={video.urn} as="video" controls />
+ *     <AithosAsset urn={pdf.urn} as="download" filename="cv.pdf">
+ *       Download my CV
+ *     </AithosAsset>
+ *
+ *     // 3. Or use the hook directly for custom rendering
+ *     const { url, bytes, loading, error } = useAithosAsset(urn);
+ */
+export { AssetsClientProvider, useAssetsClient, } from "./context.js";
+export { useAithosAsset, } from "./use-aithos-asset.js";
+export { AithosAsset, } from "./AithosAsset.js";
+export { useAithosTranscribePendingJobs, } from "./use-transcribe-pending.js";
+//# sourceMappingURL=index.js.map

package/dist/src/react/use-aithos-asset.d.ts

@@ -0,0 +1,39 @@
+import type { AssetsClient } from "../assets.js";
+export interface UseAithosAssetState {
+    /** A `blob:` URL pointing at the decrypted plaintext. Use in <img src=…> etc. */
+    readonly url: string | null;
+    /** Raw decrypted bytes. Use when you need the binary itself (e.g. PDF viewer). */
+    readonly bytes: Uint8Array | null;
+    /** IANA media type — useful for routing rendering. */
+    readonly mediaType: string | null;
+    /** Plaintext size in bytes. */
+    readonly sizeBytes: number | null;
+    /** True while the fetch+decrypt is in flight. */
+    readonly loading: boolean;
+    /** Non-null when the fetch/decrypt failed. */
+    readonly error: Error | null;
+}
+export interface UseAithosAssetOptions {
+    /** Override the client from context. Useful for tests. */
+    readonly client?: AssetsClient | null;
+    /**
+     * If `true`, the hook keeps the previous blob URL visible while a
+     * new URN is being fetched, instead of flashing `null`. Default
+     * `false` (more predictable, less visual stutter avoidance).
+     */
+    readonly keepPreviousOnUrnChange?: boolean;
+}
+/**
+ * Fetch + decrypt an Aithos asset and return a stable `blob:` URL.
+ *
+ * Lifecycle:
+ *  - On mount or when `urn` changes, runs `client.fetch(urn)`.
+ *  - On success, creates an object URL from the plaintext bytes.
+ *  - On unmount or before refetching, revokes the URL to free memory.
+ *  - Cancels in-flight fetches if the URN changes mid-flight.
+ *
+ * Throws (via `error`) when no client is available — supply one via
+ * `<AssetsClientProvider>` or the `client` option.
+ */
+export declare function useAithosAsset(urn: string | null | undefined, options?: UseAithosAssetOptions): UseAithosAssetState;
+//# sourceMappingURL=use-aithos-asset.d.ts.map

package/dist/src/react/use-aithos-asset.js

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * `useAithosAsset(urn)` — React hook that fetches an asset and exposes
+ * it as a browser-consumable `blob:` URL, with full lifecycle
+ * management (revoke on unmount, race-cancel on URN change, error
+ * surfacing).
+ *
+ * For most UIs the higher-level `<AithosAsset>` component is enough.
+ * Reach for this hook directly when you want to feed the bytes or the
+ * blob URL to a non-`<img>`/`<video>`/`<audio>` consumer — e.g. an
+ * inline CSS `background-image`, a Canvas, a custom PDF viewer.
+ */
+import { useEffect, useState } from "react";
+import { useAssetsClient } from "./context.js";
+/**
+ * Fetch + decrypt an Aithos asset and return a stable `blob:` URL.
+ *
+ * Lifecycle:
+ *  - On mount or when `urn` changes, runs `client.fetch(urn)`.
+ *  - On success, creates an object URL from the plaintext bytes.
+ *  - On unmount or before refetching, revokes the URL to free memory.
+ *  - Cancels in-flight fetches if the URN changes mid-flight.
+ *
+ * Throws (via `error`) when no client is available — supply one via
+ * `<AssetsClientProvider>` or the `client` option.
+ */
+export function useAithosAsset(urn, options = {}) {
+    const contextClient = useAssetsClient();
+    const client = options.client ?? contextClient;
+    const [state, setState] = useState({
+        url: null,
+        bytes: null,
+        mediaType: null,
+        sizeBytes: null,
+        loading: !!urn,
+        error: null,
+    });
+    useEffect(() => {
+        if (!urn) {
+            setState({
+                url: null,
+                bytes: null,
+                mediaType: null,
+                sizeBytes: null,
+                loading: false,
+                error: null,
+            });
+            return;
+        }
+        if (!client) {
+            setState({
+                url: null,
+                bytes: null,
+                mediaType: null,
+                sizeBytes: null,
+                loading: false,
+                error: new Error("useAithosAsset: no AssetsClient available — wrap your tree with <AssetsClientProvider> or pass the `client` option"),
+            });
+            return;
+        }
+        let cancelled = false;
+        let createdUrl = null;
+        setState((prev) => options.keepPreviousOnUrnChange
+            ? { ...prev, loading: true, error: null }
+            : {
+                url: null,
+                bytes: null,
+                mediaType: null,
+                sizeBytes: null,
+                loading: true,
+                error: null,
+            });
+        (async () => {
+            try {
+                const result = await client.fetch(urn);
+                if (cancelled)
+                    return;
+                // Construct the blob: URL the DOM can consume.
+                // The `as BlobPart` cast is needed because @types/node and
+                // lib.dom disagree on whether Uint8Array's backing buffer is
+                // always ArrayBuffer (vs SharedArrayBuffer). The runtime
+                // accepts our Uint8Array unconditionally.
+                const blob = new Blob([result.bytes], {
+                    type: result.mediaType,
+                });
+                createdUrl = URL.createObjectURL(blob);
+                setState({
+                    url: createdUrl,
+                    bytes: result.bytes,
+                    mediaType: result.mediaType,
+                    sizeBytes: result.sizeBytes,
+                    loading: false,
+                    error: null,
+                });
+            }
+            catch (e) {
+                if (cancelled)
+                    return;
+                setState({
+                    url: null,
+                    bytes: null,
+                    mediaType: null,
+                    sizeBytes: null,
+                    loading: false,
+                    error: e instanceof Error ? e : new Error(String(e)),
+                });
+            }
+        })();
+        return () => {
+            cancelled = true;
+            if (createdUrl)
+                URL.revokeObjectURL(createdUrl);
+        };
+    }, [urn, client, options.keepPreviousOnUrnChange]);
+    return state;
+}
+//# sourceMappingURL=use-aithos-asset.js.map

package/dist/src/react/use-transcribe-pending.d.ts

@@ -0,0 +1,21 @@
+import type { ComputeNamespace, InvokeTranscribeResult, TranscribeProgressState } from "../compute.js";
+import type { LocalPendingEntry } from "../transcribe-resilience.js";
+export interface UseAithosTranscribePendingJobs {
+    /** Locally-tracked in-flight jobs (survives reloads via localStorage). */
+    readonly pending: readonly LocalPendingEntry[];
+    /** Resume polling a job by id; resolves with the final transcript. */
+    readonly resume: (jobId: string, opts?: {
+        readonly mandateId?: string;
+        readonly onProgress?: (state: TranscribeProgressState) => void;
+        readonly signal?: AbortSignal;
+        readonly pollIntervalMs?: number;
+    }) => Promise<InvokeTranscribeResult>;
+}
+/**
+ * Subscribe a React component to the SDK's local pending-transcription
+ * registry. Re-renders whenever a job is added, advances, or clears.
+ *
+ * @param compute the SDK compute namespace (`sdk.compute`).
+ */
+export declare function useAithosTranscribePendingJobs(compute: ComputeNamespace): UseAithosTranscribePendingJobs;
+//# sourceMappingURL=use-transcribe-pending.d.ts.map

package/dist/src/react/use-transcribe-pending.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * `useAithosTranscribePendingJobs(sdk.compute)` — a thin React adapter over
+ * the framework-agnostic local pending-jobs tracker exposed by the compute
+ * namespace. The tracker itself (subscribe/getSnapshot) is plain vanilla JS
+ * and works with any framework; this hook just wires it into React's
+ * `useSyncExternalStore`. Vue/Svelte/vanilla users can call
+ * `sdk.compute.subscribeLocalPendingTranscribes` directly.
+ *
+ *     function PendingBanner({ sdk }) {
+ *       const { pending, resume } = useAithosTranscribePendingJobs(sdk.compute);
+ *       if (pending.length === 0) return null;
+ *       return (
+ *         <div>
+ *           {pending.map((p) => (
+ *             <button key={p.jobId} onClick={() => resume(p.jobId)}>
+ *               Resume {p.jobId} ({p.status})
+ *             </button>
+ *           ))}
+ *         </div>
+ *       );
+ *     }
+ */
+import { useCallback, useEffect, useState } from "react";
+/**
+ * Subscribe a React component to the SDK's local pending-transcription
+ * registry. Re-renders whenever a job is added, advances, or clears.
+ *
+ * @param compute the SDK compute namespace (`sdk.compute`).
+ */
+export function useAithosTranscribePendingJobs(compute) {
+    const [pending, setPending] = useState(() => compute.getLocalPendingTranscribesSnapshot());
+    useEffect(() => {
+        // Sync immediately (the snapshot may have changed before mount) then
+        // subscribe. getSnapshot returns a stable reference between mutations,
+        // so identical states bail out of a re-render.
+        setPending(compute.getLocalPendingTranscribesSnapshot());
+        const unsubscribe = compute.subscribeLocalPendingTranscribes(() => {
+            setPending(compute.getLocalPendingTranscribesSnapshot());
+        });
+        return unsubscribe;
+    }, [compute]);
+    const resume = useCallback((jobId, opts) => compute.resumeTranscribe(jobId, opts), [compute]);
+    return { pending, resume };
+}
+//# sourceMappingURL=use-transcribe-pending.js.map

package/dist/src/rotate.d.ts

@@ -0,0 +1,94 @@
+/** Raw 32-byte seeds for a rotation. `root` is unchanged; the rest are new. */
+export interface RotationSeeds {
+    readonly root: Uint8Array;
+    readonly public: Uint8Array;
+    readonly circle: Uint8Array;
+    readonly self: Uint8Array;
+    /** Optional dedicated #data sphere (added if present). */
+    readonly data?: Uint8Array;
+}
+interface VerificationMethodLike {
+    id: string;
+    type: "Ed25519VerificationKey2020" | "X25519KeyAgreementKey2020";
+    controller: string;
+    publicKeyMultibase: string;
+}
+/** Minimal structural view of a did.json (browser-safe; no node import). */
+export interface DidDocumentLike {
+    "@context": readonly string[];
+    id: string;
+    verificationMethod: readonly VerificationMethodLike[];
+    keyAgreement?: readonly VerificationMethodLike[];
+    aithos: {
+        version: "0.1.0";
+        display_name?: string;
+        created_at: string;
+        rotated: readonly unknown[];
+    };
+    proof?: unknown;
+}
+/**
+ * Build + sign a rotated did.json. The result rotates every Ethos sphere whose
+ * seed differs from the previously-published key, appends one `rotated[]` entry
+ * per changed sphere (preserving prior history), carries / adds `#data`, and is
+ * signed by `#root`. Ready to POST via `aithos.rotate_sphere_key`.
+ *
+ * @param seeds        the post-rotation seeds (same root, new sphere seeds).
+ * @param previousDoc  the currently-published did.json (old pubkeys + history).
+ * @param displayName  display name to carry on the doc.
+ * @param reason       audit reason recorded on each new rotated entry.
+ */
+export declare function buildSignedRotatedDidDocument(seeds: RotationSeeds, previousDoc: DidDocumentLike, displayName: string, reason?: string): DidDocumentLike;
+import { type RekeyReport } from "./migrate.js";
+import { type ParsedRecoveryFile } from "./internal/recovery-file.js";
+export interface RotateEthosOptions {
+    /** api.aithos.be base URL. Default {@link DEFAULT_API_BASE_URL}. NOTE: the
+     *  Ethos-zone recopy uses @aithos/protocol-client's ambient endpoint
+     *  (api.aithos.be); a non-default apiBaseUrl only redirects the did.json
+     *  rotation, not the zone publish — keep them aligned (prod) for now. */
+    readonly apiBaseUrl?: string;
+    /** PDS base URL for the collection re-key. Default `https://pds.aithos.be`. */
+    readonly pdsUrl?: string;
+    readonly fetch?: typeof fetch;
+    /** Audit reason recorded in rotated[]. */
+    readonly reason?: string;
+    /**
+     * Skip the Ethos circle/self zone recopy (the live, protocol-client-RPC part).
+     * Used by hermetic tests and by data-only accounts. WARNING: with real
+     * circle/self content, skipping while rotating the sphere keys would orphan
+     * that content — rotateEthos refuses to rotate the Ethos spheres when an
+     * edition exists and zones are skipped (unless `force`).
+     */
+    readonly skipZones?: boolean;
+    /** Override the safety refusal above. */
+    readonly force?: boolean;
+    readonly onProgress?: (msg: string) => void;
+}
+export interface RotateEthosResult {
+    readonly did: string;
+    /** Ethos spheres whose key changed (always public/circle/self here). */
+    readonly rotatedSpheres: readonly string[];
+    /** Whether a fresh edition was republished (zones re-sealed under new keys). */
+    readonly editionRepublished: boolean;
+    /** Whether the account had an Ethos edition at all. */
+    readonly hadEdition: boolean;
+    /** Collection re-key report (dual #data wraps toward the NEW #data). */
+    readonly collections: RekeyReport;
+    /** New recovery file (ALL new sphere seeds + new #data). PERSIST THIS. */
+    readonly updatedRecoveryFile: string;
+}
+/**
+ * Fully rotate an Ethos: new public/circle/self/#data keys (root unchanged),
+ * re-encrypt the Ethos zones under the new keys (fresh edition), and dual-wrap
+ * every data collection toward the new #data. Entirely client-side; uses only
+ * existing API primitives (rotate_sphere_key, publish_ethos_edition via the
+ * protocol-client editor, rotate_cmk). Returns a new recovery file — persist it.
+ *
+ * Option (a) semantics: the new head edition (carrying all current content) is
+ * fully verifiable under the new keys; pre-rotation edition snapshots are not
+ * re-verifiable against the rotated did.json (rotated[] retains the old keys so
+ * a rotated[]-aware verifier can be added later without re-rotating).
+ */
+export declare function rotateEthos(recovery: ParsedRecoveryFile | string, opts?: RotateEthosOptions): Promise<RotateEthosResult>;
+export {};
+//# sourceMappingURL=rotate.d.ts.map