@aithos/sdk 0.1.0-alpha.20 → 0.1.0-alpha.23

package/README.md

@@ -100,11 +100,47 @@ network — they fail fast with a precise `AithosSDKError`:
   set — useful for agents that only consume tokens (e.g. creative
   assistants) without seeing any of your data.
 
+## Extracting webpages without an LLM
+
+`sdk.web` is a token-priced primitive that lets your agent read a
+public webpage and get back cleaned HTML, purged CSS and a
+deterministic visual signature — all computed server-side without an
+LLM in the loop. Pricing is a flat **1 microcredit** per successful
+extraction (refunded on failure), versus ~30 mc for a comparable
+LLM-based extraction.
+
+```ts
+import { AithosSDK } from "@aithos/sdk";
+
+const sdk = new AithosSDK({ auth, appDid });
+
+const { data, creditsCharged } = await sdk.web.extract({
+  url: "https://example.com",
+});
+
+console.log(data.meta.title);             // "Example Domain"
+console.log(data.visual_signature.colors.primary); // "#0078d4"
+console.log(data.styles.css.length);      // purged + minified CSS
+```
+
+Owners can mint a mandate for delegate-only extraction:
+
+```ts
+import { WEB_EXTRACT_SCOPE } from "@aithos/sdk";
+
+await sdk.mandates.create({
+  appDid: "did:aithos:app:my-agent",
+  scopes: [WEB_EXTRACT_SCOPE],
+  // ...
+});
+```
+
 ## What lives where
 
 | Namespace        | Purpose                                                                                    |
 | ---------------- | ------------------------------------------------------------------------------------------ |
 | `sdk.compute`    | Bedrock invocation through the Aithos compute proxy (signed envelope, wallet enforcement). |
+| `sdk.web`        | Webpage extraction without an LLM through the web extractor proxy (1 mc / call).           |
 | `sdk.wallet`     | Stripe Checkout sessions for credit-pack top-ups, balance helpers.                         |
 | `sdk.ethos`      | Ethos-zone composition / parsing — re-exported from `@aithos/protocol-client`.             |
 | `sdk.onboarding` | First-run identity / DID flows — re-exported.                                              |

package/dist/src/endpoints.d.ts

@@ -10,11 +10,20 @@ export interface AithosSdkEndpoints {
      * suffixes a fixed path to it.
      */
     readonly wallet: string;
+    /**
+     * Web extractor proxy base URL — `aithos.web_extract`. Default
+     * `https://extract.aithos.be`. Same JSON-RPC + signed-envelope shape
+     * as the compute proxy, distinct audience so a mandate can hold one
+     * scope without the other.
+     */
+    readonly web: string;
 }
 /** Production defaults. */
 export declare const DEFAULT_SDK_ENDPOINTS: AithosSdkEndpoints;
 /** Compose the full compute-invoke URL: `${compute}/v1/invoke`. */
 export declare function computeInvokeUrl(endpoints: AithosSdkEndpoints): string;
+/** Compose the full web-extract URL: `${web}/v1/invoke`. */
+export declare function webInvokeUrl(endpoints: AithosSdkEndpoints): string;
 /** Compose the full top-up-checkout URL: `${wallet}/v1/wallet/topup/checkout`. */
 export declare function walletTopupCheckoutUrl(endpoints: AithosSdkEndpoints): string;
 /**

package/dist/src/endpoints.js

@@ -4,11 +4,16 @@
 export const DEFAULT_SDK_ENDPOINTS = {
     compute: "https://compute.aithos.be",
     wallet: "https://wallet.aithos.be",
+    web: "https://extract.aithos.be",
 };
 /** Compose the full compute-invoke URL: `${compute}/v1/invoke`. */
 export function computeInvokeUrl(endpoints) {
     return `${trimSlash(endpoints.compute)}/v1/invoke`;
 }
+/** Compose the full web-extract URL: `${web}/v1/invoke`. */
+export function webInvokeUrl(endpoints) {
+    return `${trimSlash(endpoints.web)}/v1/invoke`;
+}
 /** Compose the full top-up-checkout URL: `${wallet}/v1/wallet/topup/checkout`. */
 export function walletTopupCheckoutUrl(endpoints) {
     return `${trimSlash(endpoints.wallet)}/v1/wallet/topup/checkout`;

package/dist/src/ethos.d.ts

@@ -85,6 +85,53 @@ export declare class EthosZone {
     addSection(input: AddSectionInput): void;
     updateSection(sectionId: string, patch: UpdateSectionPatch): void;
     deleteSection(sectionId: string): void;
+    /**
+     * Return every section in this zone whose `title` is exactly `title`.
+     *
+     * Match is exact and case-sensitive. The result is always an array — it
+     * may be empty (no match), have one element (the typical case), or have
+     * more than one element when the author has happened to publish two
+     * sections with the same title. Section titles are not required by the
+     * protocol to be unique within a zone.
+     *
+     * The order of returned sections is the zone's authored order
+     * (`sections()` ordering, spec §2.5.2).
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     */
+    findSectionsByTitle(title: string): Promise<readonly Section[]>;
+    /**
+     * Stage an update for **every** section in this zone whose `title`
+     * matches `title` exactly. Returns the list of section IDs that were
+     * staged — empty when nothing matched.
+     *
+     * Apply with `client.publish()` like any other staged mutation. The
+     * staged entries are identical to what `updateSection(id, patch)` would
+     * produce, one per matched section, so `pendingChanges()` /
+     * `discard()` behave normally.
+     *
+     * Note: this method does NOT throw when there is no match — it returns
+     * `[]`. That's intentional: callers driven by an LLM frequently want to
+     * upsert (try update, then fall back to add) and shouldn't have to
+     * catch.
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     * @param patch Same patch shape accepted by `updateSection`.
+     * @returns Array of `section.id` strings whose updates were staged.
+     */
+    updateSectionsByTitle(title: string, patch: UpdateSectionPatch): Promise<readonly string[]>;
+    /**
+     * Stage a delete for **every** section in this zone whose `title`
+     * matches `title` exactly. Returns the list of section IDs that were
+     * staged — empty when nothing matched.
+     *
+     * Same semantics as {@link updateSectionsByTitle}: silent on no-match,
+     * apply with `client.publish()`.
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     * @returns Array of `section.id` strings whose deletes were staged.
+     */
+    deleteSectionsByTitle(title: string): Promise<readonly string[]>;
 }
 export interface EthosNamespaceDeps {
     readonly auth: AithosAuth;

package/dist/src/ethos.js

@@ -517,6 +517,89 @@ export class EthosZone {
     deleteSection(sectionId) {
         this.#parent._stageDelete(this.#name, sectionId);
     }
+    /* ------------------------------------------------------------------------ */
+    /*  By-title helpers                                                        */
+    /*                                                                          */
+    /*  The Aithos protocol does not (yet) treat section titles as a queryable  */
+    /*  index — only `section.id` is a normative anchor. These three methods    */
+    /*  are an ergonomic SDK-side affordance for the common LLM-driven case    */
+    /*  "act on the section called X". They resolve titles client-side by      */
+    /*  loading the full zone (`sections()`) and exact-match filtering on      */
+    /*  `Section.title`.                                                       */
+    /*                                                                          */
+    /*  When a future revision of `aithos.get_ethos_zone` (or a new            */
+    /*  `aithos.find_sections` primitive) supports server-side title           */
+    /*  filtering, the implementation behind these three methods can swap to   */
+    /*  the server call without changing the public signatures here. The      */
+    /*  contract — async, exact case-sensitive match, plural semantics — is    */
+    /*  intentionally aligned with what such an API would return.             */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Return every section in this zone whose `title` is exactly `title`.
+     *
+     * Match is exact and case-sensitive. The result is always an array — it
+     * may be empty (no match), have one element (the typical case), or have
+     * more than one element when the author has happened to publish two
+     * sections with the same title. Section titles are not required by the
+     * protocol to be unique within a zone.
+     *
+     * The order of returned sections is the zone's authored order
+     * (`sections()` ordering, spec §2.5.2).
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     */
+    async findSectionsByTitle(title) {
+        const all = await this.#parent._readZone(this.#name);
+        return all.filter((s) => s.title === title);
+    }
+    /**
+     * Stage an update for **every** section in this zone whose `title`
+     * matches `title` exactly. Returns the list of section IDs that were
+     * staged — empty when nothing matched.
+     *
+     * Apply with `client.publish()` like any other staged mutation. The
+     * staged entries are identical to what `updateSection(id, patch)` would
+     * produce, one per matched section, so `pendingChanges()` /
+     * `discard()` behave normally.
+     *
+     * Note: this method does NOT throw when there is no match — it returns
+     * `[]`. That's intentional: callers driven by an LLM frequently want to
+     * upsert (try update, then fall back to add) and shouldn't have to
+     * catch.
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     * @param patch Same patch shape accepted by `updateSection`.
+     * @returns Array of `section.id` strings whose updates were staged.
+     */
+    async updateSectionsByTitle(title, patch) {
+        const matches = await this.findSectionsByTitle(title);
+        const ids = [];
+        for (const s of matches) {
+            this.#parent._stageUpdate(this.#name, s.id, patch);
+            ids.push(s.id);
+        }
+        return ids;
+    }
+    /**
+     * Stage a delete for **every** section in this zone whose `title`
+     * matches `title` exactly. Returns the list of section IDs that were
+     * staged — empty when nothing matched.
+     *
+     * Same semantics as {@link updateSectionsByTitle}: silent on no-match,
+     * apply with `client.publish()`.
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     * @returns Array of `section.id` strings whose deletes were staged.
+     */
+    async deleteSectionsByTitle(title) {
+        const matches = await this.findSectionsByTitle(title);
+        const ids = [];
+        for (const s of matches) {
+            this.#parent._stageDelete(this.#name, s.id);
+            ids.push(s.id);
+        }
+        return ids;
+    }
 }
 export class EthosNamespace {
     #deps;

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0-alpha.19";
+export declare const VERSION = "0.1.0-alpha.23";
 export { AithosSDK } from "./sdk.js";
 export type { AithosSDKConfig } from "./types.js";
 export { AithosSDKError } from "./types.js";
@@ -9,6 +9,8 @@ export type { ComputeMessage, ImageAspectRatio, ImageModelId, InvokeBedrockArgs,
 export { ComputeNamespace } from "./compute.js";
 export type { CreditPackId, CreateTopupSessionArgs, CreateTopupSessionResult, GetBalanceArgs, GetBalanceResult, } from "./wallet.js";
 export { WalletNamespace } from "./wallet.js";
+export type { ComponentStyle, ExtractArgs, ExtractContent, ExtractData, ExtractForm, ExtractFormField, ExtractHeading, ExtractIconDeclaration, ExtractImage, ExtractLink, ExtractLogo, ExtractMeta, ExtractResult, ExtractSection, ExtractStructure, ExtractStyles, FetchAssetArgs, FetchAssetResult, PaletteEntry, VisualSignature, WebNamespaceDeps, } from "./web.js";
+export { WebNamespace, WEB_EXTRACT_SCOPE } from "./web.js";
 export { AithosAuth, DEFAULT_API_BASE_URL, DEFAULT_AUTH_BASE_URL, } from "./auth.js";
 export type { AithosAuthConfig, AithosSession, CompleteSsoFirstLoginInput, CompleteSsoFirstLoginResult, DelegateInfo, ImportMandateInput, OwnerInfo, SignInInput, SignInWithGoogleOptions, SignInWithRecoveryInput, SignUpInput, SignUpResult, } from "./auth.js";
 export { DEFAULT_SESSION_STORAGE_KEY, defaultSessionStore, localStorageStore, noopStore, sessionStorageStore, type AithosSessionStore, } from "./session-store.js";

package/dist/src/index.js

@@ -17,7 +17,7 @@
 // Public types specific to the SDK (`AithosSDKConfig`, `AithosSDKError`)
 // are exported from here. Endpoint config (`AithosSdkEndpoints`,
 // `DEFAULT_SDK_ENDPOINTS`) likewise.
-export const VERSION = "0.1.0-alpha.19";
+export const VERSION = "0.1.0-alpha.23";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
 // Re-export protocol-client's JSON-RPC error type so consumers can
@@ -27,6 +27,7 @@ export { AithosRpcError } from "@aithos/protocol-client";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
 export { ComputeNamespace } from "./compute.js";
 export { WalletNamespace } from "./wallet.js";
+export { WebNamespace, WEB_EXTRACT_SCOPE } from "./web.js";
 // Sign-up, sign-in, sign-in-with-Google. Lives outside the AithosSDK
 // class because the auth flow runs *before* the user has a
 // BrowserIdentity (sign-up creates one, sign-in restores it from the

package/dist/src/sdk.d.ts

@@ -4,6 +4,7 @@ import { type AithosSdkEndpoints } from "./endpoints.js";
 import { EthosNamespace } from "./ethos.js";
 import { MandatesNamespace } from "./mandates.js";
 import { WalletNamespace } from "./wallet.js";
+import { WebNamespace } from "./web.js";
 export interface AithosSDKConfig {
     /**
      * The {@link AithosAuth} instance the SDK reads sign-in state from.
@@ -44,6 +45,8 @@ export declare class AithosSDK {
     readonly ethos: EthosNamespace;
     /** Mandate lifecycle namespace — create / list / revoke. */
     readonly mandates: MandatesNamespace;
+    /** Web extraction namespace — aithos.web_extract through the web extractor proxy. */
+    readonly web: WebNamespace;
     constructor(config: AithosSDKConfig);
     /** DID of the currently signed-in owner, or null if no owner is loaded. */
     get userDid(): string | null;

package/dist/src/sdk.js

@@ -5,6 +5,7 @@ import { resolveEndpoints } from "./endpoints.js";
 import { EthosNamespace } from "./ethos.js";
 import { MandatesNamespace } from "./mandates.js";
 import { WalletNamespace } from "./wallet.js";
+import { WebNamespace } from "./web.js";
 export class AithosSDK {
     /** Resolved endpoint configuration (defaults + caller overrides). */
     endpoints;
@@ -20,6 +21,8 @@ export class AithosSDK {
     ethos;
     /** Mandate lifecycle namespace — create / list / revoke. */
     mandates;
+    /** Web extraction namespace — aithos.web_extract through the web extractor proxy. */
+    web;
     constructor(config) {
         if (!config.auth) {
             throw new TypeError("AithosSDK: config.auth is required");
@@ -53,6 +56,12 @@ export class AithosSDK {
             endpoints: this.endpoints,
             fetch: fetchImpl,
         });
+        this.web = new WebNamespace({
+            auth: config.auth,
+            appDid: config.appDid,
+            endpoints: this.endpoints,
+            fetch: fetchImpl,
+        });
     }
     /** DID of the currently signed-in owner, or null if no owner is loaded. */
     get userDid() {

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/endpoints.test.js

@@ -4,7 +4,7 @@
 import { strict as assert } from "node:assert";
 import { describe, it } from "node:test";
 import { DEFAULT_SDK_ENDPOINTS } from "../src/index.js";
-import { computeInvokeUrl, resolveEndpoints, walletTopupCheckoutUrl, } from "../src/endpoints.js";
+import { computeInvokeUrl, resolveEndpoints, walletTopupCheckoutUrl, webInvokeUrl, } from "../src/endpoints.js";
 describe("resolveEndpoints", () => {
     it("returns a fresh copy of the defaults when no override is given", () => {
         const a = resolveEndpoints();
@@ -23,12 +23,14 @@ describe("computeInvokeUrl", () => {
         assert.equal(computeInvokeUrl({
             compute: "https://compute.aithos.be",
             wallet: "https://wallet.aithos.be",
+            web: "https://extract.aithos.be",
         }), "https://compute.aithos.be/v1/invoke");
     });
     it("trims a trailing slash on the compute base", () => {
         assert.equal(computeInvokeUrl({
             compute: "https://compute.aithos.be/",
             wallet: "https://wallet.aithos.be",
+            web: "https://extract.aithos.be",
         }), "https://compute.aithos.be/v1/invoke");
     });
 });
@@ -37,7 +39,24 @@ describe("walletTopupCheckoutUrl", () => {
         assert.equal(walletTopupCheckoutUrl({
             compute: "https://compute.aithos.be",
             wallet: "https://wallet.aithos.be",
+            web: "https://extract.aithos.be",
         }), "https://wallet.aithos.be/v1/wallet/topup/checkout");
     });
 });
+describe("webInvokeUrl", () => {
+    it("appends /v1/invoke to the web base", () => {
+        assert.equal(webInvokeUrl({
+            compute: "https://compute.aithos.be",
+            wallet: "https://wallet.aithos.be",
+            web: "https://extract.aithos.be",
+        }), "https://extract.aithos.be/v1/invoke");
+    });
+    it("trims a trailing slash on the web base", () => {
+        assert.equal(webInvokeUrl({
+            compute: "https://compute.aithos.be",
+            wallet: "https://wallet.aithos.be",
+            web: "https://extract.aithos.be/",
+        }), "https://extract.aithos.be/v1/invoke");
+    });
+});
 //# sourceMappingURL=endpoints.test.js.map

package/dist/test/web.test.d.ts

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

package/dist/test/web.test.js

@@ -0,0 +1,270 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Unit tests for sdk.web.extract with a mock fetch.
+//
+// Mirrors test/compute.test.ts: real BrowserIdentity (synchronous Ed25519)
+// so the envelope-signing path runs for real and any
+// signature/canonicalization regression surfaces here.
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { createBrowserIdentity } from "@aithos/protocol-client";
+import { AithosAuth, AithosSDK, AithosSDKError, 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 web tests");
+        }),
+        sessionStore: noopStore(),
+        keyStore: memoryKeyStore(),
+    });
+    const { text } = serializeRecoveryFile(id);
+    await auth.signInWithRecovery({ file: text });
+    return new AithosSDK({
+        auth,
+        appDid: APP_DID,
+        endpoints: { web: "https://extract.example.test" },
+        fetch: fetchImpl,
+    });
+}
+const HAPPY_RESULT = {
+    data: {
+        url: "https://example.com",
+        final_url: "https://example.com/",
+        fetched_at: "2026-05-13T05:30:00.000Z",
+        render_ms: 1234,
+        meta: {
+            title: "Example",
+            description: null,
+            lang: "en",
+            charset: "UTF-8",
+            viewport: null,
+            canonical: null,
+            og: {},
+        },
+        structure: { headings: [], sections: [], nav_links: [], forms: [] },
+        content: {
+            main_html: "<main>hi</main>",
+            main_text: "hi",
+            images: [],
+            links: { internal: [], external: [] },
+        },
+        styles: { css: "", inline_styles_count: 0 },
+        visual_signature: {
+            colors: {
+                palette: [],
+                background: "#ffffff",
+                text: "#000000",
+                primary: null,
+                link: null,
+            },
+            typography: {
+                heading_font: null,
+                body_font: "sans-serif",
+                size_scale: [],
+                base_size_px: 16,
+                base_line_height: 1.5,
+            },
+            radii: { button: null, input: null, card: null },
+            spacing: { base_unit_px: null, common_gaps_px: [] },
+            layout: { max_content_width_px: null, mode: "block" },
+            components: { buttons: [], inputs: [], cards: [] },
+        },
+        logo: null,
+    },
+    creditsCharged: 1,
+    walletBalance: 99_999,
+    auditId: "audit-web-1",
+};
+describe("web.extract — happy path", () => {
+    it("posts to ${web}/v1/invoke with a JSON-RPC envelope and parses the result", async () => {
+        let capturedUrl;
+        let capturedInit;
+        const fakeFetch = async (input, init) => {
+            capturedUrl = typeof input === "string" ? input : input.toString();
+            capturedInit = init;
+            return new Response(JSON.stringify({ result: HAPPY_RESULT }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        const sdk = await makeSdk(fakeFetch);
+        const out = await sdk.web.extract({ url: "https://example.com" });
+        assert.deepEqual(out, HAPPY_RESULT);
+        assert.equal(capturedUrl, "https://extract.example.test/v1/invoke");
+        assert.equal(capturedInit?.method, "POST");
+        const headers = capturedInit?.headers;
+        assert.equal(headers["content-type"], "application/json");
+        const body = JSON.parse(capturedInit?.body);
+        assert.equal(body.jsonrpc, "2.0");
+        assert.equal(body.method, "aithos.web_extract");
+        assert.equal(body.params.url, "https://example.com");
+        assert.equal(body.params.app_did, APP_DID);
+        assert.ok(typeof body.params.mandate_id === "string");
+        assert.ok(body.params.mandate_id.length > 0);
+        assert.ok(body.params._envelope, "request must carry a signed envelope");
+    });
+    it("forwards waitUntil and timeoutMs as snake_case-free params", async () => {
+        let capturedBody;
+        const fakeFetch = async (_input, init) => {
+            capturedBody = JSON.parse(init.body);
+            return new Response(JSON.stringify({ result: HAPPY_RESULT }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        const sdk = await makeSdk(fakeFetch);
+        await sdk.web.extract({
+            url: "https://example.com",
+            waitUntil: "domcontentloaded",
+            timeoutMs: 5000,
+        });
+        assert.equal(capturedBody?.params.waitUntil, "domcontentloaded");
+        assert.equal(capturedBody?.params.timeoutMs, 5000);
+    });
+});
+describe("web.extract — error mapping", () => {
+    it("propagates -32071 insufficient_balance as AithosSDKError with data", async () => {
+        const fakeFetch = async () => new Response(JSON.stringify({
+            error: {
+                code: -32071,
+                message: "Insufficient balance",
+                data: { required: 1, available: 0 },
+            },
+        }), { status: 200, headers: { "content-type": "application/json" } });
+        const sdk = await makeSdk(fakeFetch);
+        await assert.rejects(() => sdk.web.extract({ url: "https://example.com" }), (err) => {
+            assert.ok(err instanceof AithosSDKError);
+            assert.equal(err.code, "-32071");
+            const data = err.data;
+            assert.equal(data?.required, 1);
+            assert.equal(data?.available, 0);
+            return true;
+        });
+    });
+    it("propagates -32042 scope mismatch as AithosSDKError", async () => {
+        const fakeFetch = async () => new Response(JSON.stringify({
+            error: {
+                code: -32042,
+                message: "mandate does not carry the web.extract scope",
+                data: {
+                    mandate_id: "mandate:abc",
+                    required_scope: "web.extract",
+                },
+            },
+        }), { status: 200, headers: { "content-type": "application/json" } });
+        const sdk = await makeSdk(fakeFetch);
+        await assert.rejects(() => sdk.web.extract({ url: "https://example.com" }), (err) => {
+            assert.ok(err instanceof AithosSDKError);
+            assert.equal(err.code, "-32042");
+            return true;
+        });
+    });
+    it("rejects HTTP transport errors as AithosSDKError code=http", async () => {
+        const fakeFetch = async () => new Response("upstream is down", { status: 502 });
+        const sdk = await makeSdk(fakeFetch);
+        await assert.rejects(() => sdk.web.extract({ url: "https://example.com" }), (err) => {
+            assert.ok(err instanceof AithosSDKError);
+            assert.equal(err.code, "http");
+            return true;
+        });
+    });
+});
+describe("web.extract — endpoint default", () => {
+    it("defaults to https://extract.aithos.be when no override is given", async () => {
+        let capturedUrl;
+        const fakeFetch = async (input) => {
+            capturedUrl = typeof input === "string" ? input : input.toString();
+            return new Response(JSON.stringify({ result: HAPPY_RESULT }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        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 });
+        const sdk = new AithosSDK({
+            auth,
+            appDid: APP_DID,
+            fetch: fakeFetch,
+        });
+        await sdk.web.extract({ url: "https://example.com" });
+        assert.equal(capturedUrl, "https://extract.aithos.be/v1/invoke");
+    });
+});
+describe("web.fetchAsset — happy path", () => {
+    it("posts to ${web}/v1/invoke with method aithos.web_fetch_asset", async () => {
+        let capturedUrl;
+        let capturedInit;
+        const fakeResult = {
+            data: {
+                url: "https://example.com/logo.png",
+                final_url: "https://example.com/logo.png",
+                content_type: "image/png",
+                size_bytes: 4096,
+                base64: "aGVsbG8K",
+            },
+            creditsCharged: 1,
+            walletBalance: 99_998,
+            auditId: "audit-asset-1",
+        };
+        const fakeFetch = async (input, init) => {
+            capturedUrl = typeof input === "string" ? input : input.toString();
+            capturedInit = init;
+            return new Response(JSON.stringify({ result: fakeResult }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        const sdk = await makeSdk(fakeFetch);
+        const out = await sdk.web.fetchAsset({ url: "https://example.com/logo.png" });
+        assert.deepEqual(out, fakeResult);
+        assert.equal(capturedUrl, "https://extract.example.test/v1/invoke");
+        const body = JSON.parse(capturedInit?.body);
+        assert.equal(body.method, "aithos.web_fetch_asset");
+        assert.equal(body.params.url, "https://example.com/logo.png");
+        assert.equal(body.params.app_did, APP_DID);
+        assert.ok(typeof body.params.mandate_id === "string");
+        assert.ok(body.params._envelope, "request must carry a signed envelope");
+    });
+});
+describe("web.fetchAsset — error propagation", () => {
+    it("propagates -32071 insufficient_balance as AithosSDKError", async () => {
+        const fakeFetch = async () => new Response(JSON.stringify({
+            error: {
+                code: -32071,
+                message: "Insufficient balance",
+                data: { required: 1, available: 0 },
+            },
+        }), { status: 200, headers: { "content-type": "application/json" } });
+        const sdk = await makeSdk(fakeFetch);
+        await assert.rejects(() => sdk.web.fetchAsset({ url: "https://example.com/logo.png" }), (err) => {
+            assert.ok(err instanceof AithosSDKError);
+            assert.equal(err.code, "-32071");
+            return true;
+        });
+    });
+    it("propagates -32000 upstream fetch failure as AithosSDKError", async () => {
+        const fakeFetch = async () => new Response(JSON.stringify({
+            error: { code: -32000, message: "Asset fetch failed", data: { reason: "upstream HTTP 404" } },
+        }), { status: 200, headers: { "content-type": "application/json" } });
+        const sdk = await makeSdk(fakeFetch);
+        await assert.rejects(() => sdk.web.fetchAsset({ url: "https://example.com/missing.png" }), (err) => {
+            assert.ok(err instanceof AithosSDKError);
+            assert.equal(err.code, "-32000");
+            return true;
+        });
+    });
+});
+//# sourceMappingURL=web.test.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.20",
-  "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.",
+  "version": "0.1.0-alpha.23",
+  "description": "Aithos SDK \u2014 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",
     "sdk",