@aithos/sdk 0.1.0-alpha.39 → 0.1.0-alpha.40

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

@@ -0,0 +1,29 @@
+/**
+ * React context for the Aithos assets client.
+ *
+ * App roots wrap their tree with `<AssetsClientProvider client={sdk.assets}>`
+ * once, then child components use `<AithosAsset urn="..." />` (or the
+ * `useAithosAsset` hook) without having to thread the client through
+ * props.
+ */
+import { type ReactNode } from "react";
+import type { AssetsClient } from "../assets.js";
+export interface AssetsClientProviderProps {
+    /** The SDK's assets client — typically `sdk.assets`. */
+    readonly client: AssetsClient;
+    readonly children?: ReactNode;
+}
+/**
+ * Provider that exposes an {@link AssetsClient} to descendants.
+ *
+ * Typical placement: as high in the React tree as the authenticated
+ * session lives (e.g. inside the auth boundary).
+ */
+export declare function AssetsClientProvider(props: AssetsClientProviderProps): any;
+/**
+ * Return the {@link AssetsClient} from the nearest provider, or `null`
+ * if no provider is present. Components SHOULD accept an override via
+ * an explicit `client` prop and fall back to this hook when omitted.
+ */
+export declare function useAssetsClient(): AssetsClient | null;
+//# sourceMappingURL=context.d.ts.map

package/dist/src/react/context.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * React context for the Aithos assets client.
+ *
+ * App roots wrap their tree with `<AssetsClientProvider client={sdk.assets}>`
+ * once, then child components use `<AithosAsset urn="..." />` (or the
+ * `useAithosAsset` hook) without having to thread the client through
+ * props.
+ */
+import { createContext, useContext } from "react";
+const AssetsClientContext = createContext(null);
+/**
+ * Provider that exposes an {@link AssetsClient} to descendants.
+ *
+ * Typical placement: as high in the React tree as the authenticated
+ * session lives (e.g. inside the auth boundary).
+ */
+export function AssetsClientProvider(props) {
+    return (_jsx(AssetsClientContext.Provider, { value: props.client, children: props.children }));
+}
+/**
+ * Return the {@link AssetsClient} from the nearest provider, or `null`
+ * if no provider is present. Components SHOULD accept an override via
+ * an explicit `client` prop and fall back to this hook when omitted.
+ */
+export function useAssetsClient() {
+    return useContext(AssetsClientContext);
+}
+//# sourceMappingURL=context.js.map

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

@@ -0,0 +1,28 @@
+/**
+ * `@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";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/react/index.js

@@ -0,0 +1,30 @@
+// 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";
+//# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.39",
+  "version": "0.1.0-alpha.40",
   "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",
@@ -29,6 +29,10 @@
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
     },
+    "./react": {
+      "types": "./dist/src/react/index.d.ts",
+      "import": "./dist/src/react/index.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/src/index.js",
@@ -52,7 +56,17 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "@aithos/protocol-client": ">=0.1.0-alpha.13 <0.2.0"
+    "@aithos/protocol-client": ">=0.1.0-alpha.13 <0.2.0",
+    "@aithos/assets-crypto": ">=0.1.0-alpha.1 <0.2.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aithos/assets-crypto": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@aithos/protocol-client": "^0.1.0-alpha.13",

package/dist/test/auth-j3.test.d.ts

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