@aithos/sdk 0.1.0-alpha.3 → 0.1.0-alpha.30

package/dist/src/session-store.js

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/* -------------------------------------------------------------------------- */
+/*  Storage key & expiration                                                   */
+/* -------------------------------------------------------------------------- */
+/**
+ * Storage key used by the bundled stores. Apps that want to coexist with
+ * other Aithos-aware libs (or that want to scope sessions per-tenant) can
+ * pass a custom key via {@link sessionStorageStore} or
+ * {@link localStorageStore}.
+ */
+export const DEFAULT_SESSION_STORAGE_KEY = "aithos.session.v1";
+/** Conservative buffer — drop the session 30 s before its `exp` so we
+ *  don't hand out a token the server is about to reject. */
+const SESSION_EXPIRY_BUFFER_S = 30;
+function isExpired(session, nowSec) {
+    return session.exp <= nowSec + SESSION_EXPIRY_BUFFER_S;
+}
+/**
+ * Validate at runtime that an opaque object looks like an `AithosSession`.
+ * Storage values come from JSON.parse over user-controlled data — we can't
+ * trust them blind. This isn't a security check (the server validates the
+ * JWT ; persistence layers don't authenticate themselves) ; it just
+ * prevents weird crashes when the storage was tampered with.
+ */
+function isSessionShaped(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const o = v;
+    return (typeof o["session"] === "string" &&
+        typeof o["exp"] === "number" &&
+        typeof o["did"] === "string" &&
+        typeof o["handle"] === "string");
+}
+function browserStorageStore(storageRef, opts = {}) {
+    const key = opts.key ?? DEFAULT_SESSION_STORAGE_KEY;
+    return {
+        get() {
+            const s = storageRef();
+            if (!s)
+                return null;
+            let raw;
+            try {
+                raw = s.getItem(key);
+            }
+            catch {
+                return null;
+            }
+            if (!raw)
+                return null;
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                // Corrupted entry — wipe to recover.
+                try {
+                    s.removeItem(key);
+                }
+                catch {
+                    /* ignore */
+                }
+                return null;
+            }
+            if (!isSessionShaped(parsed))
+                return null;
+            const nowSec = Math.floor(Date.now() / 1000);
+            if (isExpired(parsed, nowSec)) {
+                // Auto-evict — let the caller see "no session" and re-auth.
+                try {
+                    s.removeItem(key);
+                }
+                catch {
+                    /* ignore */
+                }
+                return null;
+            }
+            return parsed;
+        },
+        set(session) {
+            const s = storageRef();
+            if (!s)
+                return;
+            try {
+                s.setItem(key, JSON.stringify(session));
+            }
+            catch (e) {
+                // Quota exceeded, private mode, etc. — log but don't throw : the
+                // sign-in returned successfully, the in-memory session is still
+                // usable for this tab.
+                // eslint-disable-next-line no-console
+                console.warn("[AithosAuth] failed to persist session:", e.message);
+            }
+        },
+        clear() {
+            const s = storageRef();
+            if (!s)
+                return;
+            try {
+                s.removeItem(key);
+            }
+            catch {
+                /* ignore */
+            }
+        },
+    };
+}
+function safeStorage(getter) {
+    return () => {
+        try {
+            const s = getter();
+            return s ?? null;
+        }
+        catch {
+            // Some restricted contexts (sandboxed iframes, file:// URLs) throw
+            // on access. Treat them as "no storage available".
+            return null;
+        }
+    };
+}
+/**
+ * Default web store : `sessionStorage`. The session lives until the tab
+ * is closed. Cleared on `signOut()`. Use this when reauthenticating each
+ * day is acceptable and reduces blast radius after an XSS.
+ */
+export function sessionStorageStore(opts) {
+    return browserStorageStore(safeStorage(() => (typeof sessionStorage !== "undefined" ? sessionStorage : undefined)), opts);
+}
+/**
+ * `localStorage` store. The session persists until the JWT expires or the
+ * user explicitly signs out. Higher convenience, larger XSS blast radius.
+ */
+export function localStorageStore(opts) {
+    return browserStorageStore(safeStorage(() => (typeof localStorage !== "undefined" ? localStorage : undefined)), opts);
+}
+/**
+ * No-op store. `set` and `clear` discard their input ; `get` always
+ * returns null. The default in non-browser contexts (Node, edge runtimes)
+ * — apps running there should pass their own store explicitly.
+ */
+export function noopStore() {
+    return {
+        get: () => null,
+        set: () => { },
+        clear: () => { },
+    };
+}
+/**
+ * Pick a sensible default : `sessionStorage` if the browser environment
+ * is available, {@link noopStore} otherwise.
+ */
+export function defaultSessionStore() {
+    if (typeof sessionStorage !== "undefined") {
+        return sessionStorageStore();
+    }
+    return noopStore();
+}
+//# sourceMappingURL=session-store.js.map

package/dist/src/wallet.d.ts

@@ -1,4 +1,4 @@
-import { type BrowserIdentity } from "@aithos/protocol-client";
+import type { AithosAuth } from "./auth.js";
 import { type AithosSdkEndpoints } from "./endpoints.js";
 /**
  * Canonical credit-pack identifiers. Pricing and microcredit amounts are
@@ -44,12 +44,10 @@ export interface GetBalanceResult {
     readonly exists: boolean;
 }
 export interface WalletNamespaceDeps {
-    /** User identity — needed to sign the balance-lookup envelope. */
-    readonly identity: BrowserIdentity;
+    /** Auth instance — the wallet reads the active owner DID + signing key from here. */
+    readonly auth: AithosAuth;
     /** App DID — sent as audit attribution alongside the balance request. */
     readonly appDid: string;
-    /** Pre-resolved DID convenience accessor (mirrors identity.did). */
-    readonly userDid: string;
     readonly endpoints: AithosSdkEndpoints;
     readonly fetch: typeof fetch;
 }
@@ -64,7 +62,7 @@ export declare class WalletNamespace {
      * hosted URL — the caller is responsible for redirecting the user (e.g.
      * `window.location.href = result.checkoutUrl`).
      *
-     * On success, the Stripe webhook will credit `userDid`'s wallet once the
+     * On success, the Stripe webhook will credit the user's wallet once the
      * payment clears. Wallet balances are shared across all Aithos apps that
      * use the same DID.
      */

package/dist/src/wallet.js

@@ -13,8 +13,9 @@
 //     compute proxy at `${compute}/v1/invoke`. Read-only DDB GetItem on
 //     the wallet table, gated by the same signed envelope verification
 //     as compute_invoke. Returns the current balance + daily spent.
-import { buildSignedEnvelope, } from "@aithos/protocol-client";
+import { buildSignedEnvelope } from "@aithos/protocol-client";
 import { computeInvokeUrl, walletTopupCheckoutUrl, } from "./endpoints.js";
+import { ownerKeyPair } from "./internal/protocol-client-bridge.js";
 import { AithosSDKError } from "./types.js";
 /**
  * `sdk.wallet` namespace.
@@ -29,12 +30,16 @@ export class WalletNamespace {
      * hosted URL — the caller is responsible for redirecting the user (e.g.
      * `window.location.href = result.checkoutUrl`).
      *
-     * On success, the Stripe webhook will credit `userDid`'s wallet once the
+     * On success, the Stripe webhook will credit the user's wallet once the
      * payment clears. Wallet balances are shared across all Aithos apps that
      * use the same DID.
      */
     async createTopupSession(args) {
-        const { userDid, endpoints, fetch: fetchImpl } = this.#deps;
+        const { auth, endpoints, fetch: fetchImpl } = this.#deps;
+        const owner = auth._getOwnerSigners();
+        if (!owner || owner.destroyed) {
+            throw new AithosSDKError("sdk_no_owner", "no owner signed in; sign in first");
+        }
         const url = walletTopupCheckoutUrl(endpoints);
         let res;
         try {
@@ -42,7 +47,7 @@ export class WalletNamespace {
                 method: "POST",
                 headers: { "content-type": "application/json" },
                 body: JSON.stringify({
-                    user_did: userDid,
+                    user_did: owner.did,
                     pack_id: args.packId,
                     success_url: args.successUrl,
                     cancel_url: args.cancelUrl,
@@ -88,16 +93,21 @@ export class WalletNamespace {
      *   envelope-verify failures from the proxy).
      */
     async getBalance(args = {}) {
-        const { identity, appDid, endpoints, fetch: fetchImpl } = this.#deps;
+        const { auth, appDid, endpoints, fetch: fetchImpl } = this.#deps;
+        const owner = auth._getOwnerSigners();
+        if (!owner || owner.destroyed) {
+            throw new AithosSDKError("sdk_no_owner", "no owner signed in; sign in first");
+        }
+        const publicKp = ownerKeyPair(owner, "public");
         const url = computeInvokeUrl(endpoints);
         const params = { app_did: appDid };
         const envelope = buildSignedEnvelope({
-            iss: identity.did,
+            iss: owner.did,
             aud: url,
             method: "aithos.wallet_get_balance",
-            verificationMethod: `${identity.did}#public`,
+            verificationMethod: `${owner.did}#public`,
             params,
-            signer: identity.public,
+            signer: publicKp,
         });
         let res;
         try {

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