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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/README.md +211 -7
  2. package/dist/src/assets.d.ts +207 -0
  3. package/dist/src/assets.js +533 -0
  4. package/dist/src/auth-api.d.ts +138 -0
  5. package/dist/src/auth-api.js +168 -0
  6. package/dist/src/auth.d.ts +536 -119
  7. package/dist/src/auth.js +1207 -152
  8. package/dist/src/compute.d.ts +221 -9
  9. package/dist/src/compute.js +293 -16
  10. package/dist/src/data-schema-contacts-v1.d.ts +14 -0
  11. package/dist/src/data-schema-contacts-v1.js +28 -0
  12. package/dist/src/data.d.ts +153 -0
  13. package/dist/src/data.js +670 -0
  14. package/dist/src/endpoints.d.ts +9 -0
  15. package/dist/src/endpoints.js +5 -0
  16. package/dist/src/ethos.d.ts +202 -1
  17. package/dist/src/ethos.js +821 -16
  18. package/dist/src/index.d.ts +16 -6
  19. package/dist/src/index.js +33 -6
  20. package/dist/src/internal/delegate-bundle.d.ts +18 -0
  21. package/dist/src/internal/delegate-bundle.js +94 -0
  22. package/dist/src/internal/delegate-state.d.ts +45 -0
  23. package/dist/src/internal/delegate-state.js +120 -0
  24. package/dist/src/internal/envelope.d.ts +77 -0
  25. package/dist/src/internal/envelope.js +154 -0
  26. package/dist/src/internal/owner-signers.d.ts +78 -0
  27. package/dist/src/internal/owner-signers.js +179 -0
  28. package/dist/src/internal/protocol-client-bridge.d.ts +8 -0
  29. package/dist/src/internal/protocol-client-bridge.js +20 -0
  30. package/dist/src/internal/recovery-file.d.ts +29 -0
  31. package/dist/src/internal/recovery-file.js +98 -0
  32. package/dist/src/internal/signer.d.ts +59 -0
  33. package/dist/src/internal/signer.js +86 -0
  34. package/dist/src/key-store.d.ts +128 -0
  35. package/dist/src/key-store.js +244 -0
  36. package/dist/src/mandates.d.ts +163 -1
  37. package/dist/src/mandates.js +286 -8
  38. package/dist/src/react/AithosAsset.d.ts +66 -0
  39. package/dist/src/react/AithosAsset.js +67 -0
  40. package/dist/src/react/context.d.ts +29 -0
  41. package/dist/src/react/context.js +31 -0
  42. package/dist/src/react/index.d.ts +28 -0
  43. package/dist/src/react/index.js +30 -0
  44. package/dist/src/react/use-aithos-asset.d.ts +39 -0
  45. package/dist/src/react/use-aithos-asset.js +118 -0
  46. package/dist/src/sdk.d.ts +39 -3
  47. package/dist/src/sdk.js +36 -23
  48. package/dist/src/wallet.d.ts +4 -6
  49. package/dist/src/wallet.js +18 -8
  50. package/dist/src/web.d.ts +279 -0
  51. package/dist/src/web.js +186 -0
  52. package/package.json +18 -3
  53. package/dist/test/auth.test.d.ts +0 -2
  54. package/dist/test/auth.test.js +0 -175
  55. package/dist/test/compute.test.d.ts +0 -2
  56. package/dist/test/compute.test.js +0 -179
  57. package/dist/test/endpoints.test.d.ts +0 -2
  58. package/dist/test/endpoints.test.js +0 -43
  59. package/dist/test/sdk.test.d.ts +0 -2
  60. package/dist/test/sdk.test.js +0 -86
  61. package/dist/test/wallet.test.d.ts +0 -2
  62. package/dist/test/wallet.test.js +0 -110
@@ -0,0 +1,118 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Copyright 2026 Mathieu Colla
3
+ /**
4
+ * `useAithosAsset(urn)` — React hook that fetches an asset and exposes
5
+ * it as a browser-consumable `blob:` URL, with full lifecycle
6
+ * management (revoke on unmount, race-cancel on URN change, error
7
+ * surfacing).
8
+ *
9
+ * For most UIs the higher-level `<AithosAsset>` component is enough.
10
+ * Reach for this hook directly when you want to feed the bytes or the
11
+ * blob URL to a non-`<img>`/`<video>`/`<audio>` consumer — e.g. an
12
+ * inline CSS `background-image`, a Canvas, a custom PDF viewer.
13
+ */
14
+ import { useEffect, useState } from "react";
15
+ import { useAssetsClient } from "./context.js";
16
+ /**
17
+ * Fetch + decrypt an Aithos asset and return a stable `blob:` URL.
18
+ *
19
+ * Lifecycle:
20
+ * - On mount or when `urn` changes, runs `client.fetch(urn)`.
21
+ * - On success, creates an object URL from the plaintext bytes.
22
+ * - On unmount or before refetching, revokes the URL to free memory.
23
+ * - Cancels in-flight fetches if the URN changes mid-flight.
24
+ *
25
+ * Throws (via `error`) when no client is available — supply one via
26
+ * `<AssetsClientProvider>` or the `client` option.
27
+ */
28
+ export function useAithosAsset(urn, options = {}) {
29
+ const contextClient = useAssetsClient();
30
+ const client = options.client ?? contextClient;
31
+ const [state, setState] = useState({
32
+ url: null,
33
+ bytes: null,
34
+ mediaType: null,
35
+ sizeBytes: null,
36
+ loading: !!urn,
37
+ error: null,
38
+ });
39
+ useEffect(() => {
40
+ if (!urn) {
41
+ setState({
42
+ url: null,
43
+ bytes: null,
44
+ mediaType: null,
45
+ sizeBytes: null,
46
+ loading: false,
47
+ error: null,
48
+ });
49
+ return;
50
+ }
51
+ if (!client) {
52
+ setState({
53
+ url: null,
54
+ bytes: null,
55
+ mediaType: null,
56
+ sizeBytes: null,
57
+ loading: false,
58
+ error: new Error("useAithosAsset: no AssetsClient available — wrap your tree with <AssetsClientProvider> or pass the `client` option"),
59
+ });
60
+ return;
61
+ }
62
+ let cancelled = false;
63
+ let createdUrl = null;
64
+ setState((prev) => options.keepPreviousOnUrnChange
65
+ ? { ...prev, loading: true, error: null }
66
+ : {
67
+ url: null,
68
+ bytes: null,
69
+ mediaType: null,
70
+ sizeBytes: null,
71
+ loading: true,
72
+ error: null,
73
+ });
74
+ (async () => {
75
+ try {
76
+ const result = await client.fetch(urn);
77
+ if (cancelled)
78
+ return;
79
+ // Construct the blob: URL the DOM can consume.
80
+ // The `as BlobPart` cast is needed because @types/node and
81
+ // lib.dom disagree on whether Uint8Array's backing buffer is
82
+ // always ArrayBuffer (vs SharedArrayBuffer). The runtime
83
+ // accepts our Uint8Array unconditionally.
84
+ const blob = new Blob([result.bytes], {
85
+ type: result.mediaType,
86
+ });
87
+ createdUrl = URL.createObjectURL(blob);
88
+ setState({
89
+ url: createdUrl,
90
+ bytes: result.bytes,
91
+ mediaType: result.mediaType,
92
+ sizeBytes: result.sizeBytes,
93
+ loading: false,
94
+ error: null,
95
+ });
96
+ }
97
+ catch (e) {
98
+ if (cancelled)
99
+ return;
100
+ setState({
101
+ url: null,
102
+ bytes: null,
103
+ mediaType: null,
104
+ sizeBytes: null,
105
+ loading: false,
106
+ error: e instanceof Error ? e : new Error(String(e)),
107
+ });
108
+ }
109
+ })();
110
+ return () => {
111
+ cancelled = true;
112
+ if (createdUrl)
113
+ URL.revokeObjectURL(createdUrl);
114
+ };
115
+ }, [urn, client, options.keepPreviousOnUrnChange]);
116
+ return state;
117
+ }
118
+ //# sourceMappingURL=use-aithos-asset.js.map
package/dist/src/sdk.d.ts CHANGED
@@ -1,18 +1,54 @@
1
+ import type { AithosAuth } from "./auth.js";
1
2
  import { ComputeNamespace } from "./compute.js";
2
3
  import { type AithosSdkEndpoints } from "./endpoints.js";
4
+ import { EthosNamespace } from "./ethos.js";
5
+ import { MandatesNamespace } from "./mandates.js";
3
6
  import { WalletNamespace } from "./wallet.js";
4
- import type { AithosSDKConfig } from "./types.js";
7
+ import { WebNamespace } from "./web.js";
8
+ export interface AithosSDKConfig {
9
+ /**
10
+ * The {@link AithosAuth} instance the SDK reads sign-in state from.
11
+ * Constructed and managed by the app — typically a singleton at the
12
+ * top of the application tree.
13
+ */
14
+ readonly auth: AithosAuth;
15
+ /**
16
+ * Application DID — identifies the calling app in mandates, audit
17
+ * logs, billing splits. Issued at developer onboarding (will be
18
+ * self-service before 0.1.0 stable).
19
+ */
20
+ readonly appDid: string;
21
+ /**
22
+ * Optional endpoint overrides. Production defaults point at the
23
+ * Aithos infrastructure; pass overrides for staging, self-hosting,
24
+ * tests.
25
+ */
26
+ readonly endpoints?: Partial<AithosSdkEndpoints>;
27
+ /**
28
+ * Optional `fetch` implementation. Defaults to the global `fetch`.
29
+ * Used by tests to inject a mock without monkeypatching globals.
30
+ */
31
+ readonly fetch?: typeof fetch;
32
+ }
5
33
  export declare class AithosSDK {
6
34
  /** Resolved endpoint configuration (defaults + caller overrides). */
7
35
  readonly endpoints: AithosSdkEndpoints;
8
36
  /** Application DID (as declared in mandates). */
9
37
  readonly appDid: string;
10
- /** User DID (derived from `config.identity`). */
11
- readonly userDid: string;
38
+ /** The same auth instance the app constructed and passed in. */
39
+ readonly auth: AithosAuth;
12
40
  /** Compute proxy namespace — Bedrock invocation. */
13
41
  readonly compute: ComputeNamespace;
14
42
  /** Wallet namespace — Stripe top-up. */
15
43
  readonly wallet: WalletNamespace;
44
+ /** Ethos editing namespace — load, mutate (staged), publish. */
45
+ readonly ethos: EthosNamespace;
46
+ /** Mandate lifecycle namespace — create / list / revoke. */
47
+ readonly mandates: MandatesNamespace;
48
+ /** Web extraction namespace — aithos.web_extract through the web extractor proxy. */
49
+ readonly web: WebNamespace;
16
50
  constructor(config: AithosSDKConfig);
51
+ /** DID of the currently signed-in owner, or null if no owner is loaded. */
52
+ get userDid(): string | null;
17
53
  }
18
54
  //# sourceMappingURL=sdk.d.ts.map
package/dist/src/sdk.js CHANGED
@@ -1,58 +1,71 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
2
  // Copyright 2026 Mathieu Colla
3
- // AithosSDK — top-level developer surface.
4
- //
5
- // One construction, namespaced methods. The SDK takes the user's identity
6
- // (a `BrowserIdentity` from `@aithos/protocol-client`) and the calling
7
- // app's DID, then exposes:
8
- //
9
- // sdk.compute — Bedrock invocation through the compute proxy.
10
- // sdk.wallet — Stripe Checkout for credit-pack top-ups.
11
- // sdk.ethos — re-exports from protocol-client (zone editor, signers).
12
- // sdk.onboarding / sdk.mandates — likewise.
13
- //
14
- // The class is intentionally thin: the heavy lifting lives in dedicated
15
- // namespace classes (`ComputeNamespace`, `WalletNamespace`) so each can be
16
- // tested in isolation with a mock fetch and so an advanced caller could
17
- // instantiate just one of them if needed.
18
3
  import { ComputeNamespace } from "./compute.js";
19
4
  import { resolveEndpoints } from "./endpoints.js";
5
+ import { EthosNamespace } from "./ethos.js";
6
+ import { MandatesNamespace } from "./mandates.js";
20
7
  import { WalletNamespace } from "./wallet.js";
8
+ import { WebNamespace } from "./web.js";
21
9
  export class AithosSDK {
22
10
  /** Resolved endpoint configuration (defaults + caller overrides). */
23
11
  endpoints;
24
12
  /** Application DID (as declared in mandates). */
25
13
  appDid;
26
- /** User DID (derived from `config.identity`). */
27
- userDid;
14
+ /** The same auth instance the app constructed and passed in. */
15
+ auth;
28
16
  /** Compute proxy namespace — Bedrock invocation. */
29
17
  compute;
30
18
  /** Wallet namespace — Stripe top-up. */
31
19
  wallet;
20
+ /** Ethos editing namespace — load, mutate (staged), publish. */
21
+ ethos;
22
+ /** Mandate lifecycle namespace — create / list / revoke. */
23
+ mandates;
24
+ /** Web extraction namespace — aithos.web_extract through the web extractor proxy. */
25
+ web;
32
26
  constructor(config) {
33
- if (!config.identity) {
34
- throw new TypeError("AithosSDK: config.identity is required");
27
+ if (!config.auth) {
28
+ throw new TypeError("AithosSDK: config.auth is required");
35
29
  }
36
30
  if (!config.appDid || typeof config.appDid !== "string") {
37
31
  throw new TypeError("AithosSDK: config.appDid is required (string)");
38
32
  }
39
33
  this.endpoints = resolveEndpoints(config.endpoints);
40
34
  this.appDid = config.appDid;
41
- this.userDid = config.identity.did;
35
+ this.auth = config.auth;
42
36
  const fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
43
37
  this.compute = new ComputeNamespace({
44
- identity: config.identity,
38
+ auth: config.auth,
45
39
  appDid: config.appDid,
46
40
  endpoints: this.endpoints,
47
41
  fetch: fetchImpl,
48
42
  });
49
43
  this.wallet = new WalletNamespace({
50
- identity: config.identity,
44
+ auth: config.auth,
51
45
  appDid: config.appDid,
52
- userDid: config.identity.did,
53
46
  endpoints: this.endpoints,
54
47
  fetch: fetchImpl,
55
48
  });
49
+ this.ethos = new EthosNamespace({
50
+ auth: config.auth,
51
+ endpoints: this.endpoints,
52
+ fetch: fetchImpl,
53
+ });
54
+ this.mandates = new MandatesNamespace({
55
+ auth: config.auth,
56
+ endpoints: this.endpoints,
57
+ fetch: fetchImpl,
58
+ });
59
+ this.web = new WebNamespace({
60
+ auth: config.auth,
61
+ appDid: config.appDid,
62
+ endpoints: this.endpoints,
63
+ fetch: fetchImpl,
64
+ });
65
+ }
66
+ /** DID of the currently signed-in owner, or null if no owner is loaded. */
67
+ get userDid() {
68
+ return this.auth.getOwnerInfo()?.did ?? null;
56
69
  }
57
70
  }
58
71
  //# sourceMappingURL=sdk.js.map
@@ -1,4 +1,4 @@
1
- import { type BrowserIdentity } from "@aithos/protocol-client";
1
+ import type { AithosAuth } from "./auth.js";
2
2
  import { type AithosSdkEndpoints } from "./endpoints.js";
3
3
  /**
4
4
  * Canonical credit-pack identifiers. Pricing and microcredit amounts are
@@ -44,12 +44,10 @@ export interface GetBalanceResult {
44
44
  readonly exists: boolean;
45
45
  }
46
46
  export interface WalletNamespaceDeps {
47
- /** User identityneeded to sign the balance-lookup envelope. */
48
- readonly identity: BrowserIdentity;
47
+ /** Auth instancethe wallet reads the active owner DID + signing key from here. */
48
+ readonly auth: AithosAuth;
49
49
  /** App DID — sent as audit attribution alongside the balance request. */
50
50
  readonly appDid: string;
51
- /** Pre-resolved DID convenience accessor (mirrors identity.did). */
52
- readonly userDid: string;
53
51
  readonly endpoints: AithosSdkEndpoints;
54
52
  readonly fetch: typeof fetch;
55
53
  }
@@ -64,7 +62,7 @@ export declare class WalletNamespace {
64
62
  * hosted URL — the caller is responsible for redirecting the user (e.g.
65
63
  * `window.location.href = result.checkoutUrl`).
66
64
  *
67
- * On success, the Stripe webhook will credit `userDid`'s wallet once the
65
+ * On success, the Stripe webhook will credit the user's wallet once the
68
66
  * payment clears. Wallet balances are shared across all Aithos apps that
69
67
  * use the same DID.
70
68
  */
@@ -13,8 +13,9 @@
13
13
  // compute proxy at `${compute}/v1/invoke`. Read-only DDB GetItem on
14
14
  // the wallet table, gated by the same signed envelope verification
15
15
  // as compute_invoke. Returns the current balance + daily spent.
16
- import { buildSignedEnvelope, } from "@aithos/protocol-client";
16
+ import { buildSignedEnvelope } from "@aithos/protocol-client";
17
17
  import { computeInvokeUrl, walletTopupCheckoutUrl, } from "./endpoints.js";
18
+ import { ownerKeyPair } from "./internal/protocol-client-bridge.js";
18
19
  import { AithosSDKError } from "./types.js";
19
20
  /**
20
21
  * `sdk.wallet` namespace.
@@ -29,12 +30,16 @@ export class WalletNamespace {
29
30
  * hosted URL — the caller is responsible for redirecting the user (e.g.
30
31
  * `window.location.href = result.checkoutUrl`).
31
32
  *
32
- * On success, the Stripe webhook will credit `userDid`'s wallet once the
33
+ * On success, the Stripe webhook will credit the user's wallet once the
33
34
  * payment clears. Wallet balances are shared across all Aithos apps that
34
35
  * use the same DID.
35
36
  */
36
37
  async createTopupSession(args) {
37
- const { userDid, endpoints, fetch: fetchImpl } = this.#deps;
38
+ const { auth, endpoints, fetch: fetchImpl } = this.#deps;
39
+ const owner = auth._getOwnerSigners();
40
+ if (!owner || owner.destroyed) {
41
+ throw new AithosSDKError("sdk_no_owner", "no owner signed in; sign in first");
42
+ }
38
43
  const url = walletTopupCheckoutUrl(endpoints);
39
44
  let res;
40
45
  try {
@@ -42,7 +47,7 @@ export class WalletNamespace {
42
47
  method: "POST",
43
48
  headers: { "content-type": "application/json" },
44
49
  body: JSON.stringify({
45
- user_did: userDid,
50
+ user_did: owner.did,
46
51
  pack_id: args.packId,
47
52
  success_url: args.successUrl,
48
53
  cancel_url: args.cancelUrl,
@@ -88,16 +93,21 @@ export class WalletNamespace {
88
93
  * envelope-verify failures from the proxy).
89
94
  */
90
95
  async getBalance(args = {}) {
91
- const { identity, appDid, endpoints, fetch: fetchImpl } = this.#deps;
96
+ const { auth, appDid, endpoints, fetch: fetchImpl } = this.#deps;
97
+ const owner = auth._getOwnerSigners();
98
+ if (!owner || owner.destroyed) {
99
+ throw new AithosSDKError("sdk_no_owner", "no owner signed in; sign in first");
100
+ }
101
+ const publicKp = ownerKeyPair(owner, "public");
92
102
  const url = computeInvokeUrl(endpoints);
93
103
  const params = { app_did: appDid };
94
104
  const envelope = buildSignedEnvelope({
95
- iss: identity.did,
105
+ iss: owner.did,
96
106
  aud: url,
97
107
  method: "aithos.wallet_get_balance",
98
- verificationMethod: `${identity.did}#public`,
108
+ verificationMethod: `${owner.did}#public`,
99
109
  params,
100
- signer: identity.public,
110
+ signer: publicKp,
101
111
  });
102
112
  let res;
103
113
  try {
@@ -0,0 +1,279 @@
1
+ import type { AithosAuth } from "./auth.js";
2
+ import { type AithosSdkEndpoints } from "./endpoints.js";
3
+ /** Opt-in scope a mandate must carry to invoke `aithos.web_extract`. */
4
+ export declare const WEB_EXTRACT_SCOPE: "web.extract";
5
+ export interface ExtractArgs {
6
+ /**
7
+ * Mandate ID under which this call should be attributed.
8
+ *
9
+ * - **Owner sessions**: optional. The SDK uses the owner's own DID
10
+ * as a sentinel "self" mandate id — the proxy skips mandate checks
11
+ * when the envelope is owner-signed.
12
+ * - **Delegate sessions**: required. Must reference the imported
13
+ * mandate bundle the SDK signs with; the proxy enforces the
14
+ * `web.extract` scope.
15
+ */
16
+ readonly mandateId?: string;
17
+ /** Absolute http(s) URL to extract. */
18
+ readonly url: string;
19
+ /**
20
+ * Playwright `waitUntil` strategy passed straight through to the
21
+ * server-side navigation. Defaults to `"networkidle"` server-side
22
+ * if omitted.
23
+ */
24
+ readonly waitUntil?: "load" | "domcontentloaded" | "networkidle";
25
+ /** Navigation timeout in ms. Server validates [1000, 60000]. */
26
+ readonly timeoutMs?: number;
27
+ /** Reserved for audit-level deduplication; the proxy currently does not
28
+ * enforce idempotency keys for extractions. */
29
+ readonly idempotencyKey?: string;
30
+ /** Abort signal to cancel the request. */
31
+ readonly signal?: AbortSignal;
32
+ }
33
+ export interface ExtractMeta {
34
+ readonly title: string | null;
35
+ readonly description: string | null;
36
+ readonly lang: string | null;
37
+ readonly charset: string | null;
38
+ readonly viewport: string | null;
39
+ readonly canonical: string | null;
40
+ readonly og: Readonly<Record<string, string>>;
41
+ }
42
+ export interface ExtractHeading {
43
+ readonly level: 1 | 2 | 3 | 4 | 5 | 6;
44
+ readonly text: string;
45
+ readonly id: string | null;
46
+ }
47
+ export interface ExtractSection {
48
+ readonly tag: string;
49
+ readonly role: string | null;
50
+ readonly html: string;
51
+ readonly text_len: number;
52
+ }
53
+ export interface ExtractLink {
54
+ readonly label: string;
55
+ readonly href: string;
56
+ readonly internal: boolean;
57
+ }
58
+ export interface ExtractImage {
59
+ readonly src: string;
60
+ readonly alt: string | null;
61
+ readonly role: string | null;
62
+ }
63
+ export interface ExtractFormField {
64
+ readonly type: string;
65
+ readonly name: string | null;
66
+ readonly required: boolean;
67
+ }
68
+ export interface ExtractForm {
69
+ readonly action: string | null;
70
+ readonly method: string;
71
+ readonly fields: readonly ExtractFormField[];
72
+ }
73
+ export interface ExtractStructure {
74
+ readonly headings: readonly ExtractHeading[];
75
+ readonly sections: readonly ExtractSection[];
76
+ readonly nav_links: readonly ExtractLink[];
77
+ readonly forms: readonly ExtractForm[];
78
+ }
79
+ export interface ExtractContent {
80
+ readonly main_html: string;
81
+ readonly main_text: string;
82
+ readonly images: readonly ExtractImage[];
83
+ readonly links: {
84
+ readonly internal: readonly ExtractLink[];
85
+ readonly external: readonly ExtractLink[];
86
+ };
87
+ }
88
+ export interface ExtractStyles {
89
+ readonly css: string;
90
+ readonly inline_styles_count: number;
91
+ }
92
+ export interface PaletteEntry {
93
+ readonly hex: string;
94
+ readonly weight: number;
95
+ readonly role: "background" | "text" | "accent" | "other";
96
+ }
97
+ export interface ComponentStyle {
98
+ readonly count: number;
99
+ readonly bg: string | null;
100
+ readonly fg: string | null;
101
+ readonly border: string | null;
102
+ readonly radius: string | null;
103
+ readonly padding: string | null;
104
+ readonly font_size: string | null;
105
+ readonly font_weight: string | null;
106
+ }
107
+ export interface VisualSignature {
108
+ readonly colors: {
109
+ readonly palette: readonly PaletteEntry[];
110
+ readonly background: string | null;
111
+ readonly text: string | null;
112
+ readonly primary: string | null;
113
+ readonly link: string | null;
114
+ };
115
+ readonly typography: {
116
+ readonly heading_font: string | null;
117
+ readonly body_font: string | null;
118
+ readonly size_scale: readonly number[];
119
+ readonly base_size_px: number | null;
120
+ readonly base_line_height: number | null;
121
+ };
122
+ readonly radii: {
123
+ readonly button: string | null;
124
+ readonly input: string | null;
125
+ readonly card: string | null;
126
+ };
127
+ readonly spacing: {
128
+ readonly base_unit_px: number | null;
129
+ readonly common_gaps_px: readonly number[];
130
+ };
131
+ readonly layout: {
132
+ readonly max_content_width_px: number | null;
133
+ readonly mode: "flex" | "grid" | "block" | null;
134
+ };
135
+ readonly components: {
136
+ readonly buttons: readonly ComponentStyle[];
137
+ readonly inputs: readonly ComponentStyle[];
138
+ readonly cards: readonly ComponentStyle[];
139
+ };
140
+ }
141
+ export interface ExtractIconDeclaration {
142
+ /** href as written in the HTML (relative or absolute). */
143
+ readonly href: string;
144
+ /** rel value, lowercased: "icon", "apple-touch-icon", "shortcut icon", ... */
145
+ readonly rel: string;
146
+ /** Declared `sizes` attribute, e.g. "180x180" or "any" or null. */
147
+ readonly sizes: string | null;
148
+ /** Declared mime type, e.g. "image/svg+xml" or null. */
149
+ readonly type: string | null;
150
+ }
151
+ /**
152
+ * Logo asset resolved server-side. The Lambda picks the best
153
+ * symbol-only asset available on the page — declared <link rel="icon"|
154
+ * "apple-touch-icon"> declarations + conventional well-known paths
155
+ * (/apple-touch-icon.png, /favicon.svg, /favicon.ico) — in that
156
+ * order of expected quality. Null when nothing resolves.
157
+ *
158
+ * Favicons are symbol-only by construction (no designer ships a
159
+ * wordmark inside a 16-180 px icon), which sidesteps the
160
+ * lockup-vs-symbol problem callers used to handle client-side with
161
+ * a vision model.
162
+ */
163
+ export interface ExtractLogo {
164
+ /** Absolute URL of the asset that was successfully fetched. */
165
+ readonly url: string;
166
+ /** Which source produced the winner. */
167
+ 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";
168
+ readonly content_type: string;
169
+ readonly size_bytes: number;
170
+ /** Base64-encoded asset bytes (no `data:` prefix). Build a data
171
+ * URI with `data:${content_type};base64,${base64}`. */
172
+ readonly base64: string;
173
+ }
174
+ export interface ExtractData {
175
+ readonly url: string;
176
+ readonly final_url: string;
177
+ readonly fetched_at: string;
178
+ readonly render_ms: number;
179
+ readonly meta: ExtractMeta;
180
+ readonly structure: ExtractStructure;
181
+ readonly content: ExtractContent;
182
+ readonly styles: ExtractStyles;
183
+ readonly visual_signature: VisualSignature;
184
+ /**
185
+ * Best logo asset resolved by the lambda — null when no
186
+ * <link rel="icon"> declaration and no conventional favicon
187
+ * path produced a usable image. Callers should then let the
188
+ * operator upload the logo manually rather than treat this as
189
+ * a fatal error.
190
+ */
191
+ readonly logo: ExtractLogo | null;
192
+ }
193
+ export interface ExtractResult {
194
+ /** Cleaned extraction payload. */
195
+ readonly data: ExtractData;
196
+ /** Microcredits charged for this call (1 on success, 0 on refunded failures). */
197
+ readonly creditsCharged: number;
198
+ /** Wallet balance after the (possibly refunded) debit. */
199
+ readonly walletBalance: number;
200
+ /** Audit log id for traceability. */
201
+ readonly auditId: string;
202
+ }
203
+ export interface FetchAssetArgs {
204
+ /** Absolute http(s) URL of the asset to fetch. */
205
+ readonly url: string;
206
+ /** Mandate id under which this call should be attributed. */
207
+ readonly mandateId?: string;
208
+ /** Abort signal. */
209
+ readonly signal?: AbortSignal;
210
+ }
211
+ export interface FetchAssetResult {
212
+ /** Asset payload. */
213
+ readonly data: {
214
+ /** URL we asked the proxy to fetch. */
215
+ readonly url: string;
216
+ /** URL after the proxy followed any redirects. */
217
+ readonly final_url: string;
218
+ /** Content-Type reported by the upstream server. */
219
+ readonly content_type: string;
220
+ /** Size of the fetched body in bytes. */
221
+ readonly size_bytes: number;
222
+ /** Base64-encoded body (no `data:` prefix). Build a data URI
223
+ * with `data:${content_type};base64,${base64}`. */
224
+ readonly base64: string;
225
+ };
226
+ /** Microcredits charged for this call. */
227
+ readonly creditsCharged: number;
228
+ readonly walletBalance: number;
229
+ readonly auditId: string;
230
+ }
231
+ export interface WebNamespaceDeps {
232
+ readonly auth: AithosAuth;
233
+ readonly appDid: string;
234
+ readonly endpoints: AithosSdkEndpoints;
235
+ readonly fetch: typeof fetch;
236
+ }
237
+ /**
238
+ * `sdk.web` namespace — Aithos's web extraction primitive.
239
+ *
240
+ * Designed so a downstream agent can read the static content of any
241
+ * public page (HTML, purged CSS, computed visual signature) without
242
+ * involving an LLM — saving ~30× over a Bedrock-based extraction in
243
+ * both latency and cost.
244
+ *
245
+ * @throws {AithosSDKError} — same error taxonomy as `sdk.compute`,
246
+ * including `-32071` (insufficient balance with `{required, available}`
247
+ * in `data`) and `-32042` (mandate scope mismatch).
248
+ */
249
+ export declare class WebNamespace {
250
+ #private;
251
+ constructor(deps: WebNamespaceDeps);
252
+ /**
253
+ * Extract a public webpage. Returns the cleaned HTML, purged CSS and
254
+ * a deterministic visual signature (palette, typography, dominant
255
+ * radii, spacing, layout mode, component digests).
256
+ */
257
+ extract(args: ExtractArgs): Promise<ExtractResult>;
258
+ /**
259
+ * Fetch a single asset (image / font / css / json …) server-side,
260
+ * bypassing browser CORS. Returns the bytes as base64 + content-type.
261
+ *
262
+ * Use when `fetch(url, {mode: "cors"})` and `<img crossOrigin>`
263
+ * canvas readback both fail because the asset server doesn't return
264
+ * Access-Control-Allow-Origin headers — typical for production
265
+ * sites' logos hosted on the main domain.
266
+ *
267
+ * For the common "logo of a webpage" case the lambda already
268
+ * resolves and embeds the best symbol-only logo in
269
+ * {@link extract}'s `data.logo` field; you only need fetchAsset
270
+ * when extract's logo doesn't fit, when picking up secondary
271
+ * assets (og:image, hero image, document download), or when
272
+ * fetching an asset on a page you haven't extracted.
273
+ *
274
+ * Costs 1 mc per successful fetch, full refund on failure. Server
275
+ * caps: 15 s timeout, 10 MB body, http/https only.
276
+ */
277
+ fetchAsset(args: FetchAssetArgs): Promise<FetchAssetResult>;
278
+ }
279
+ //# sourceMappingURL=web.d.ts.map