@tabai/sdk 0.2.0

package/dist/x402/hub.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Monad's API Hub, read as a list of tools a fronting Service can sell on credit.
+ *
+ * The Hub fronts pay-per-request providers behind one x402 endpoint,
+ * `POST https://x402.monid.ai/v1/run`, and publishes what each provider offers
+ * at `https://api.monid.ai/public/v1/endpoints?provider=<provider>`. Every
+ * endpoint there carries a display name, a description, a USD price and the
+ * networks its payment is accepted on. This module fetches that manifest and
+ * reduces it to what `tab_discover` shows: the Hub endpoints as tools of the
+ * Service fronting them.
+ *
+ * ## Prices are the Hub's word, not Tab's
+ *
+ * A Hub price is a decimal USD figure. The Asset a fronting Service meters in is
+ * a six-decimal dollar stablecoin, so the figure is also rendered as base units
+ * of one, for a per-call price. A per-result or per-unit price depends on the
+ * response and is reported with the rate alone: the metered amount is whatever
+ * the upstream's `402` asks for on the day, plus the Service's margin, and the
+ * manifest is a catalogue, never a quote.
+ */
+import { type Result } from "../_shared/index.js";
+/** Where the Hub publishes its manifest. */
+export declare const API_HUB_MANIFEST_URL = "https://api.monid.ai/public/v1/endpoints";
+/** The one x402 endpoint every Hub provider is called through. */
+export declare const API_HUB_RUN_URL = "https://x402.monid.ai/v1/run";
+/** How a Hub endpoint is priced. The Hub may add kinds; unknown ones are carried as they came. */
+export type HubPriceType = "PER_CALL" | "PER_RESULT" | "PER_UNIT" | "PER_UNIT_MATRIX" | (string & {});
+export interface HubEndpoint {
+    readonly provider: string;
+    readonly providerName: string | null;
+    /** The provider-relative path, for example `/get_current_weather`. */
+    readonly endpoint: string;
+    readonly name: string | null;
+    readonly description: string | null;
+    readonly priceType: HubPriceType;
+    /** The manifest's decimal USD figure, as text. Null when the manifest carries none. */
+    readonly priceUsd: string | null;
+    /** The same figure in six-decimal base units, for a per-call price. Null otherwise. */
+    readonly priceBaseUnits: string | null;
+    /** CAIP-2 networks the Hub accepts payment on, for example `eip155:143`. */
+    readonly networks: readonly string[];
+    readonly categories: readonly string[];
+    readonly tags: readonly string[];
+}
+export interface HubManifest {
+    readonly provider: string;
+    readonly endpoints: readonly HubEndpoint[];
+    /** What the manifest said it holds for the provider, which may exceed the pages fetched. */
+    readonly total: number;
+}
+/** The little of a fetch this module needs. */
+export interface HubFetchResponse {
+    readonly status: number;
+    json(): Promise<unknown>;
+}
+export type HubFetch = (url: string, init: {
+    readonly method: "GET";
+    readonly headers: Readonly<Record<string, string>>;
+}) => Promise<HubFetchResponse>;
+export interface FetchHubManifestOptions {
+    readonly provider: string;
+    /** Defaults to {@link API_HUB_MANIFEST_URL}. */
+    readonly manifestUrl?: string;
+    readonly fetchImpl?: HubFetch;
+    /** Pages followed through the manifest's cursor. Defaults to 5, at 100 endpoints a page. */
+    readonly maxPages?: number;
+}
+/** Fetches one provider's manifest, following its cursor. */
+export declare function fetchHubManifest(options: FetchHubManifestOptions): Promise<Result<HubManifest>>;
+/**
+ * A decimal USD figure as six-decimal base units, as text.
+ *
+ * String arithmetic, because the figure came out of JSON as a double and this
+ * is the last place it can be turned into an exact integer before it is shown
+ * beside a Tab price that always was one. Anything finer than six decimals is
+ * rounded up: a catalogue must not understate a price.
+ */
+export declare function usdToBaseUnits(usd: string): string | null;
+//# sourceMappingURL=hub.d.ts.map

package/dist/x402/hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub.d.ts","sourceRoot":"","sources":["../../src/x402/hub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAqB,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAK/D,4CAA4C;AAC5C,eAAO,MAAM,oBAAoB,6CAA6C,CAAC;AAE/E,kEAAkE;AAClE,eAAO,MAAM,eAAe,iCAAiC,CAAC;AAE9D,kGAAkG;AAClG,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,GAAG,iBAAiB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEtG,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,uFAAuF;IACvF,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,CAAC;IAC3C,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAExJ,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC;IAC9B,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,6DAA6D;AAC7D,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CA+DrG;AAmDD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASzD"}

package/dist/x402/hub.js

@@ -0,0 +1,164 @@
+/**
+ * Monad's API Hub, read as a list of tools a fronting Service can sell on credit.
+ *
+ * The Hub fronts pay-per-request providers behind one x402 endpoint,
+ * `POST https://x402.monid.ai/v1/run`, and publishes what each provider offers
+ * at `https://api.monid.ai/public/v1/endpoints?provider=<provider>`. Every
+ * endpoint there carries a display name, a description, a USD price and the
+ * networks its payment is accepted on. This module fetches that manifest and
+ * reduces it to what `tab_discover` shows: the Hub endpoints as tools of the
+ * Service fronting them.
+ *
+ * ## Prices are the Hub's word, not Tab's
+ *
+ * A Hub price is a decimal USD figure. The Asset a fronting Service meters in is
+ * a six-decimal dollar stablecoin, so the figure is also rendered as base units
+ * of one, for a per-call price. A per-result or per-unit price depends on the
+ * response and is reported with the rate alone: the metered amount is whatever
+ * the upstream's `402` asks for on the day, plus the Service's margin, and the
+ * manifest is a catalogue, never a quote.
+ */
+import { causeOf, ok, wrap } from "../_shared/index.js";
+import { upstreamError, validationError } from "../errors.js";
+import { asArray, asNumber, asRecord, asString, asStringOrNull, field, isRecord } from "../mcp/json.js";
+/** Where the Hub publishes its manifest. */
+export const API_HUB_MANIFEST_URL = "https://api.monid.ai/public/v1/endpoints";
+/** The one x402 endpoint every Hub provider is called through. */
+export const API_HUB_RUN_URL = "https://x402.monid.ai/v1/run";
+/** Fetches one provider's manifest, following its cursor. */
+export async function fetchHubManifest(options) {
+    const provider = options.provider.trim();
+    if (provider.length === 0 || !/^[a-z0-9][a-z0-9._-]*$/i.test(provider)) {
+        return validationError("HUB_PROVIDER_INVALID", `\`${options.provider}\` is not a Hub provider slug`, {
+            details: { provider: options.provider },
+        });
+    }
+    const send = options.fetchImpl ?? hostFetch();
+    if (send === undefined) {
+        return upstreamError("FETCH_UNAVAILABLE", "this host has no global fetch; supply fetchImpl, or run on Node 20.10 or later");
+    }
+    const base = options.manifestUrl ?? API_HUB_MANIFEST_URL;
+    const maxPages = options.maxPages ?? 5;
+    const endpoints = [];
+    let total = 0;
+    let cursor;
+    for (let page = 0; page < maxPages; page += 1) {
+        const url = pageUrl(base, provider, cursor);
+        if (!url.ok)
+            return url;
+        const fetched = await wrap(async () => send(url.value, { method: "GET", headers: { accept: "application/json" } }), (error) => ({
+            category: "UPSTREAM",
+            code: "HUB_MANIFEST_UNREACHABLE",
+            message: `the API Hub manifest at ${base} did not answer`,
+            retryable: true,
+            details: { provider },
+            cause: causeOf(error),
+        }));
+        if (!fetched.ok)
+            return fetched;
+        if (fetched.value.status < 200 || fetched.value.status >= 300) {
+            return upstreamError("HUB_MANIFEST_REFUSED", `the API Hub manifest answered ${fetched.value.status} for provider ${provider}`, {
+                retryable: fetched.value.status >= 500,
+                details: { provider, status: fetched.value.status },
+            });
+        }
+        const body = await wrap(async () => fetched.value.json(), (error) => ({
+            category: "UPSTREAM",
+            code: "HUB_MANIFEST_INVALID",
+            message: "the API Hub manifest is not JSON",
+            retryable: false,
+            details: { provider },
+            cause: causeOf(error),
+        }));
+        if (!body.ok)
+            return body;
+        if (!isRecord(body.value) || !Array.isArray(body.value["items"])) {
+            return upstreamError("HUB_MANIFEST_INVALID", "the API Hub manifest carries no `items` array", { details: { provider } });
+        }
+        total = asNumber(body.value["total"], total);
+        for (const item of asArray(body.value["items"])) {
+            const endpoint = toHubEndpoint(item, provider);
+            if (endpoint !== undefined)
+                endpoints.push(endpoint);
+        }
+        const next = asStringOrNull(body.value["cursor"]);
+        if (next === null || next.length === 0)
+            break;
+        cursor = next;
+    }
+    return ok({ provider, endpoints, total: Math.max(total, endpoints.length) });
+}
+function pageUrl(base, provider, cursor) {
+    try {
+        const url = new URL(base);
+        url.searchParams.set("provider", provider);
+        url.searchParams.set("limit", "100");
+        if (cursor !== undefined)
+            url.searchParams.set("cursor", cursor);
+        return ok(url.toString());
+    }
+    catch {
+        return validationError("HUB_MANIFEST_URL_INVALID", `\`${base}\` is not an absolute URL`, { details: { manifestUrl: base } });
+    }
+}
+/** One manifest item, or nothing when it names no endpoint. */
+function toHubEndpoint(item, provider) {
+    const endpoint = asString(field(item, "endpoint"), "");
+    if (endpoint.length === 0)
+        return undefined;
+    const price = asRecord(field(item, "price"));
+    const priceType = asString(price["type"], "PER_CALL");
+    const priceUsd = usdText(field(price["amount"], "value"));
+    return {
+        provider: asString(field(item, "provider"), provider),
+        providerName: asStringOrNull(field(item, "providerDisplayName")),
+        endpoint,
+        name: asStringOrNull(field(item, "displayName")),
+        description: asStringOrNull(field(item, "displayDescription")),
+        priceType,
+        priceUsd,
+        priceBaseUnits: priceType === "PER_CALL" && priceUsd !== null ? usdToBaseUnits(priceUsd) : null,
+        networks: asArray(field(item, "supportedX402Networks")).map((entry) => asString(entry, "")).filter((entry) => entry.length > 0),
+        categories: asArray(field(item, "categories")).map((entry) => asString(entry, "")).filter((entry) => entry.length > 0),
+        tags: asArray(field(item, "tags")).map((entry) => asString(entry, "")).filter((entry) => entry.length > 0),
+    };
+}
+/**
+ * The manifest's price as plain decimal text.
+ *
+ * A JSON number smaller than a millionth prints with an exponent, `1e-7`, and
+ * an exponent is not a price anyone can read or parse into base units. Twelve
+ * fixed decimals cover any USD figure the Hub lists, and the trailing zeros go.
+ */
+function usdText(value) {
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+        return Number.isInteger(value) ? value.toString(10) : value.toFixed(12).replace(/0+$/, "").replace(/\.$/, "");
+    }
+    if (typeof value === "string" && /^[0-9]+(\.[0-9]+)?$/.test(value.trim()))
+        return value.trim();
+    return null;
+}
+/**
+ * A decimal USD figure as six-decimal base units, as text.
+ *
+ * String arithmetic, because the figure came out of JSON as a double and this
+ * is the last place it can be turned into an exact integer before it is shown
+ * beside a Tab price that always was one. Anything finer than six decimals is
+ * rounded up: a catalogue must not understate a price.
+ */
+export function usdToBaseUnits(usd) {
+    const match = /^([0-9]+)(?:\.([0-9]+))?$/.exec(usd.trim());
+    if (match === null || match[1] === undefined)
+        return null;
+    const whole = BigInt(match[1]);
+    const fraction = (match[2] ?? "").padEnd(6, "0");
+    const kept = BigInt(fraction.slice(0, 6));
+    const remainder = fraction.slice(6);
+    const roundUp = /[1-9]/.test(remainder) ? 1n : 0n;
+    return (whole * 1000000n + kept + roundUp).toString(10);
+}
+function hostFetch() {
+    const candidate = globalThis.fetch;
+    return typeof candidate === "function" ? candidate : undefined;
+}
+//# sourceMappingURL=hub.js.map

package/dist/x402/hub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub.js","sourceRoot":"","sources":["../../src/x402/hub.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Monad's API Hub, read as a list of tools a fronting Service can sell on credit.\n *\n * The Hub fronts pay-per-request providers behind one x402 endpoint,\n * `POST https://x402.monid.ai/v1/run`, and publishes what each provider offers\n * at `https://api.monid.ai/public/v1/endpoints?provider=<provider>`. Every\n * endpoint there carries a display name, a description, a USD price and the\n * networks its payment is accepted on. This module fetches that manifest and\n * reduces it to what `tab_discover` shows: the Hub endpoints as tools of the\n * Service fronting them.\n *\n * ## Prices are the Hub's word, not Tab's\n *\n * A Hub price is a decimal USD figure. The Asset a fronting Service meters in is\n * a six-decimal dollar stablecoin, so the figure is also rendered as base units\n * of one, for a per-call price. A per-result or per-unit price depends on the\n * response and is reported with the rate alone: the metered amount is whatever\n * the upstream's `402` asks for on the day, plus the Service's margin, and the\n * manifest is a catalogue, never a quote.\n */\n\nimport { causeOf, ok, wrap, type Result } from \"../_shared/index.js\";\n\nimport { upstreamError, validationError } from \"../errors.js\";\nimport { asArray, asNumber, asRecord, asString, asStringOrNull, field, isRecord } from \"../mcp/json.js\";\n\n/** Where the Hub publishes its manifest. */\nexport const API_HUB_MANIFEST_URL = \"https://api.monid.ai/public/v1/endpoints\";\n\n/** The one x402 endpoint every Hub provider is called through. */\nexport const API_HUB_RUN_URL = \"https://x402.monid.ai/v1/run\";\n\n/** How a Hub endpoint is priced. The Hub may add kinds; unknown ones are carried as they came. */\nexport type HubPriceType = \"PER_CALL\" | \"PER_RESULT\" | \"PER_UNIT\" | \"PER_UNIT_MATRIX\" | (string & {});\n\nexport interface HubEndpoint {\n  readonly provider: string;\n  readonly providerName: string | null;\n  /** The provider-relative path, for example `/get_current_weather`. */\n  readonly endpoint: string;\n  readonly name: string | null;\n  readonly description: string | null;\n  readonly priceType: HubPriceType;\n  /** The manifest's decimal USD figure, as text. Null when the manifest carries none. */\n  readonly priceUsd: string | null;\n  /** The same figure in six-decimal base units, for a per-call price. Null otherwise. */\n  readonly priceBaseUnits: string | null;\n  /** CAIP-2 networks the Hub accepts payment on, for example `eip155:143`. */\n  readonly networks: readonly string[];\n  readonly categories: readonly string[];\n  readonly tags: readonly string[];\n}\n\nexport interface HubManifest {\n  readonly provider: string;\n  readonly endpoints: readonly HubEndpoint[];\n  /** What the manifest said it holds for the provider, which may exceed the pages fetched. */\n  readonly total: number;\n}\n\n/** The little of a fetch this module needs. */\nexport interface HubFetchResponse {\n  readonly status: number;\n  json(): Promise<unknown>;\n}\n\nexport type HubFetch = (url: string, init: { readonly method: \"GET\"; readonly headers: Readonly<Record<string, string>> }) => Promise<HubFetchResponse>;\n\nexport interface FetchHubManifestOptions {\n  readonly provider: string;\n  /** Defaults to {@link API_HUB_MANIFEST_URL}. */\n  readonly manifestUrl?: string;\n  readonly fetchImpl?: HubFetch;\n  /** Pages followed through the manifest's cursor. Defaults to 5, at 100 endpoints a page. */\n  readonly maxPages?: number;\n}\n\n/** Fetches one provider's manifest, following its cursor. */\nexport async function fetchHubManifest(options: FetchHubManifestOptions): Promise<Result<HubManifest>> {\n  const provider = options.provider.trim();\n  if (provider.length === 0 || !/^[a-z0-9][a-z0-9._-]*$/i.test(provider)) {\n    return validationError(\"HUB_PROVIDER_INVALID\", `\\`${options.provider}\\` is not a Hub provider slug`, {\n      details: { provider: options.provider },\n    });\n  }\n  const send = options.fetchImpl ?? hostFetch();\n  if (send === undefined) {\n    return upstreamError(\"FETCH_UNAVAILABLE\", \"this host has no global fetch; supply fetchImpl, or run on Node 20.10 or later\");\n  }\n  const base = options.manifestUrl ?? API_HUB_MANIFEST_URL;\n  const maxPages = options.maxPages ?? 5;\n\n  const endpoints: HubEndpoint[] = [];\n  let total = 0;\n  let cursor: string | undefined;\n  for (let page = 0; page < maxPages; page += 1) {\n    const url = pageUrl(base, provider, cursor);\n    if (!url.ok) return url;\n    const fetched = await wrap(\n      async () => send(url.value, { method: \"GET\", headers: { accept: \"application/json\" } }),\n      (error) => ({\n        category: \"UPSTREAM\" as const,\n        code: \"HUB_MANIFEST_UNREACHABLE\",\n        message: `the API Hub manifest at ${base} did not answer`,\n        retryable: true,\n        details: { provider },\n        cause: causeOf(error),\n      }),\n    );\n    if (!fetched.ok) return fetched;\n    if (fetched.value.status < 200 || fetched.value.status >= 300) {\n      return upstreamError(\"HUB_MANIFEST_REFUSED\", `the API Hub manifest answered ${fetched.value.status} for provider ${provider}`, {\n        retryable: fetched.value.status >= 500,\n        details: { provider, status: fetched.value.status },\n      });\n    }\n    const body = await wrap(\n      async () => fetched.value.json(),\n      (error) => ({\n        category: \"UPSTREAM\" as const,\n        code: \"HUB_MANIFEST_INVALID\",\n        message: \"the API Hub manifest is not JSON\",\n        retryable: false,\n        details: { provider },\n        cause: causeOf(error),\n      }),\n    );\n    if (!body.ok) return body;\n    if (!isRecord(body.value) || !Array.isArray(body.value[\"items\"])) {\n      return upstreamError(\"HUB_MANIFEST_INVALID\", \"the API Hub manifest carries no `items` array\", { details: { provider } });\n    }\n    total = asNumber(body.value[\"total\"], total);\n    for (const item of asArray(body.value[\"items\"])) {\n      const endpoint = toHubEndpoint(item, provider);\n      if (endpoint !== undefined) endpoints.push(endpoint);\n    }\n    const next = asStringOrNull(body.value[\"cursor\"]);\n    if (next === null || next.length === 0) break;\n    cursor = next;\n  }\n  return ok({ provider, endpoints, total: Math.max(total, endpoints.length) });\n}\n\nfunction pageUrl(base: string, provider: string, cursor: string | undefined): Result<string> {\n  try {\n    const url = new URL(base);\n    url.searchParams.set(\"provider\", provider);\n    url.searchParams.set(\"limit\", \"100\");\n    if (cursor !== undefined) url.searchParams.set(\"cursor\", cursor);\n    return ok(url.toString());\n  } catch {\n    return validationError(\"HUB_MANIFEST_URL_INVALID\", `\\`${base}\\` is not an absolute URL`, { details: { manifestUrl: base } });\n  }\n}\n\n/** One manifest item, or nothing when it names no endpoint. */\nfunction toHubEndpoint(item: unknown, provider: string): HubEndpoint | undefined {\n  const endpoint = asString(field(item, \"endpoint\"), \"\");\n  if (endpoint.length === 0) return undefined;\n  const price = asRecord(field(item, \"price\"));\n  const priceType = asString(price[\"type\"], \"PER_CALL\");\n  const priceUsd = usdText(field(price[\"amount\"], \"value\"));\n  return {\n    provider: asString(field(item, \"provider\"), provider),\n    providerName: asStringOrNull(field(item, \"providerDisplayName\")),\n    endpoint,\n    name: asStringOrNull(field(item, \"displayName\")),\n    description: asStringOrNull(field(item, \"displayDescription\")),\n    priceType,\n    priceUsd,\n    priceBaseUnits: priceType === \"PER_CALL\" && priceUsd !== null ? usdToBaseUnits(priceUsd) : null,\n    networks: asArray(field(item, \"supportedX402Networks\")).map((entry) => asString(entry, \"\")).filter((entry) => entry.length > 0),\n    categories: asArray(field(item, \"categories\")).map((entry) => asString(entry, \"\")).filter((entry) => entry.length > 0),\n    tags: asArray(field(item, \"tags\")).map((entry) => asString(entry, \"\")).filter((entry) => entry.length > 0),\n  };\n}\n\n/**\n * The manifest's price as plain decimal text.\n *\n * A JSON number smaller than a millionth prints with an exponent, `1e-7`, and\n * an exponent is not a price anyone can read or parse into base units. Twelve\n * fixed decimals cover any USD figure the Hub lists, and the trailing zeros go.\n */\nfunction usdText(value: unknown): string | null {\n  if (typeof value === \"number\" && Number.isFinite(value) && value >= 0) {\n    return Number.isInteger(value) ? value.toString(10) : value.toFixed(12).replace(/0+$/, \"\").replace(/\\.$/, \"\");\n  }\n  if (typeof value === \"string\" && /^[0-9]+(\\.[0-9]+)?$/.test(value.trim())) return value.trim();\n  return null;\n}\n\n/**\n * A decimal USD figure as six-decimal base units, as text.\n *\n * String arithmetic, because the figure came out of JSON as a double and this\n * is the last place it can be turned into an exact integer before it is shown\n * beside a Tab price that always was one. Anything finer than six decimals is\n * rounded up: a catalogue must not understate a price.\n */\nexport function usdToBaseUnits(usd: string): string | null {\n  const match = /^([0-9]+)(?:\\.([0-9]+))?$/.exec(usd.trim());\n  if (match === null || match[1] === undefined) return null;\n  const whole = BigInt(match[1]);\n  const fraction = (match[2] ?? \"\").padEnd(6, \"0\");\n  const kept = BigInt(fraction.slice(0, 6));\n  const remainder = fraction.slice(6);\n  const roundUp = /[1-9]/.test(remainder) ? 1n : 0n;\n  return (whole * 1_000_000n + kept + roundUp).toString(10);\n}\n\nfunction hostFetch(): HubFetch | undefined {\n  const candidate = (globalThis as { fetch?: unknown }).fetch;\n  return typeof candidate === \"function\" ? (candidate as HubFetch) : undefined;\n}\n"]}

package/dist/x402/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * x402, the prepaid protocol, as a fallback beside Tab's credit and as an
+ * upstream a Tab Service can front.
+ *
+ * - `wire.ts` is the V2 wire format: the three headers, the codecs from
+ *   `@x402/core`, and the one selector that decides which `accepts` entry this
+ *   package can sign.
+ * - `client.ts` signs an EIP-3009 authorization with an ethers signer and
+ *   repeats a request with it. The Tab 402 client and `tab_call` use it when a
+ *   credit refusal carries `PAYMENT-REQUIRED` and an x402 signer is configured.
+ * - `server.ts` builds the requirement a Tab `402` can offer and takes a signed
+ *   payment through a facilitator: verify, deliver, settle.
+ * - `proxy.ts` fronts an x402 upstream: the Service pays it and meters the Agent.
+ * - `hub.ts` reads Monad's API Hub manifest so `tab_discover` can list a
+ *   fronted provider's endpoints as tools.
+ *
+ * Nothing here throws. The official `@x402/core` is used for types, header
+ * codecs and the facilitator HTTP client; the EIP-3009 signing and the
+ * fronting logic are this package's own and are documented against the
+ * specification in each file.
+ */
+export * from "./wire.js";
+export * from "./client.js";
+export * from "./server.js";
+export * from "./proxy.js";
+export * from "./hub.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/x402/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/x402/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC"}

package/dist/x402/index.js

@@ -0,0 +1,27 @@
+/**
+ * x402, the prepaid protocol, as a fallback beside Tab's credit and as an
+ * upstream a Tab Service can front.
+ *
+ * - `wire.ts` is the V2 wire format: the three headers, the codecs from
+ *   `@x402/core`, and the one selector that decides which `accepts` entry this
+ *   package can sign.
+ * - `client.ts` signs an EIP-3009 authorization with an ethers signer and
+ *   repeats a request with it. The Tab 402 client and `tab_call` use it when a
+ *   credit refusal carries `PAYMENT-REQUIRED` and an x402 signer is configured.
+ * - `server.ts` builds the requirement a Tab `402` can offer and takes a signed
+ *   payment through a facilitator: verify, deliver, settle.
+ * - `proxy.ts` fronts an x402 upstream: the Service pays it and meters the Agent.
+ * - `hub.ts` reads Monad's API Hub manifest so `tab_discover` can list a
+ *   fronted provider's endpoints as tools.
+ *
+ * Nothing here throws. The official `@x402/core` is used for types, header
+ * codecs and the facilitator HTTP client; the EIP-3009 signing and the
+ * fronting logic are this package's own and are documented against the
+ * specification in each file.
+ */
+export * from "./wire.js";
+export * from "./client.js";
+export * from "./server.js";
+export * from "./proxy.js";
+export * from "./hub.js";
+//# sourceMappingURL=index.js.map

package/dist/x402/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/x402/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC","sourcesContent":["/**\n * x402, the prepaid protocol, as a fallback beside Tab's credit and as an\n * upstream a Tab Service can front.\n *\n * - `wire.ts` is the V2 wire format: the three headers, the codecs from\n *   `@x402/core`, and the one selector that decides which `accepts` entry this\n *   package can sign.\n * - `client.ts` signs an EIP-3009 authorization with an ethers signer and\n *   repeats a request with it. The Tab 402 client and `tab_call` use it when a\n *   credit refusal carries `PAYMENT-REQUIRED` and an x402 signer is configured.\n * - `server.ts` builds the requirement a Tab `402` can offer and takes a signed\n *   payment through a facilitator: verify, deliver, settle.\n * - `proxy.ts` fronts an x402 upstream: the Service pays it and meters the Agent.\n * - `hub.ts` reads Monad's API Hub manifest so `tab_discover` can list a\n *   fronted provider's endpoints as tools.\n *\n * Nothing here throws. The official `@x402/core` is used for types, header\n * codecs and the facilitator HTTP client; the EIP-3009 signing and the\n * fronting logic are this package's own and are documented against the\n * specification in each file.\n */\n\nexport * from \"./wire.js\";\nexport * from \"./client.js\";\nexport * from \"./server.js\";\nexport * from \"./proxy.js\";\nexport * from \"./hub.js\";\n"]}

package/dist/x402/proxy.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Buy now, pay later for x402 APIs: a Tab Service fronts a pay-per-request
+ * upstream, pays it with the Service operator's own key, and meters the Agent's
+ * Open Tab for what it paid.
+ *
+ * ## The shape
+ *
+ * ```text
+ * Agent  --(Tab-Agent)-->  fronting proxy  --(request)-->  x402 upstream
+ *                                          <--(402, PAYMENT-REQUIRED)--
+ *                            operator signs EIP-3009 for the quoted amount
+ *                                          --(PAYMENT-SIGNATURE)-->
+ *                                          <--(200, PAYMENT-RESPONSE)--
+ *        post-paid plugin meters upstream price + margin onto the Open Tab
+ * Agent  <--(200, Tab-Charge-*)--
+ * ```
+ *
+ * The Agent never signs and never holds the upstream's currency. It buys on
+ * credit, from a Service it already has a tab with, and settles later exactly
+ * as it settles every other Tab charge. The Service is the one taking the
+ * upstream's price risk, which is what the margin is for.
+ *
+ * ## The price is known only after the upstream's 402
+ *
+ * `tabPostPaid` asks `priceOf(request)` once the response exists, which is
+ * after the forward. So the forward records what it paid, keyed by the request
+ * object, and {@link X402UpstreamPricing.priceOf} reads it back for the same
+ * object. `createTabProxy` hands its `fetchImpl` that request for this reason.
+ *
+ * ## Before the operator's funds move
+ *
+ * An upstream paid for a delivery the Agent then cannot be metered for is the
+ * operator's loss. `preflight` runs between the upstream's `402` and the
+ * signature, with the quoted amount in hand, so a Service can simulate the
+ * delivery against `TabBook` and refuse an Agent with no headroom before paying.
+ * A refusal is answered at its category's status, `402` for `LIMIT`, and the
+ * upstream is not paid.
+ */
+import { type Address, type Bytes32, type Result, type TabError } from "../_shared/index.js";
+import type { AssetRef } from "../payments/strategy.js";
+import { type TabProxy, type TabProxyOptions } from "../proxy/proxy.js";
+import type { MeteredRequest, PriceQuote } from "../server/post-paid.js";
+import { type X402Fetch, type X402PaymentReceipt, type X402Signer } from "./client.js";
+import type { PaymentRequired, PaymentRequirements } from "./wire.js";
+/** What the Service adds on top of the upstream's price. Both parts optional; both default to nothing. */
+export interface X402UpstreamMargin {
+    /** Basis points of the upstream amount, rounded down. `500n` is five percent. */
+    readonly bps?: bigint;
+    /** A flat count of Asset base units per call. */
+    readonly flatBaseUnits?: bigint;
+}
+export interface X402UpstreamPricingOptions {
+    /** The tool key the fronted calls are metered under, as the applied price list holds it. */
+    readonly tool: Bytes32;
+    readonly margin?: X402UpstreamMargin;
+    /**
+     * What one unit of this tool costs on chain, as `ServiceRegistry` holds it.
+     *
+     * A fronted call's price is not known until the upstream answers, and
+     * `TabBook.recordDelivery` refuses any unit price that is not the one in the
+     * applied price list. So the varying amount rides in the **unit count**, not
+     * in the unit price: a Service publishes a small fixed unit and a call
+     * consumes as many of them as it cost. One base unit, the default, makes the
+     * charge exact; a coarser unit rounds up, never down, so the Service is
+     * never left short by its own rounding.
+     *
+     * The published price and this number must be the same, or every fronted
+     * delivery reverts `PriceListChangedMidCall` and the Service pays the
+     * upstream for work it bills nobody.
+     */
+    readonly unitBaseUnits?: bigint;
+}
+/** One fronted call's economics: what the operator paid and what the Agent is metered. */
+export interface X402UpstreamCharge {
+    readonly upstreamAmount: bigint;
+    readonly margin: bigint;
+    /** `upstreamAmount + margin`: what lands on the Open Tab. */
+    readonly amount: bigint;
+    readonly payment: X402PaymentReceipt;
+}
+/**
+ * The price book a fronting proxy writes and its post-paid plugin reads.
+ *
+ * Built once and shared: the plugin takes `priceOf` at construction, and the
+ * proxy takes the whole object so it can `record` into it. Keyed weakly by the
+ * request, so nothing is retained after the request is gone.
+ */
+export interface X402UpstreamPricing {
+    readonly tool: Bytes32;
+    /** For `tabPostPaid({ priceOf })`. Nothing when no upstream payment was made for this request. */
+    priceOf(request: MeteredRequest): PriceQuote | undefined;
+    chargeOf(request: MeteredRequest): X402UpstreamCharge | undefined;
+    record(request: MeteredRequest, payment: X402PaymentReceipt): X402UpstreamCharge;
+    /** The Agent's price for an upstream amount, margin applied. */
+    amountFor(upstreamAmount: bigint): bigint;
+    /** What one unit costs on chain: the unit price every quote carries. */
+    readonly unitBaseUnits: bigint;
+}
+export declare function createX402UpstreamPricing(options: X402UpstreamPricingOptions): X402UpstreamPricing;
+/** What `preflight` is told before the operator signs. */
+export interface X402PreflightQuote {
+    /** The Agent named by `Tab-Agent`, when the request named one. */
+    readonly agent: Address | undefined;
+    readonly tool: Bytes32;
+    /** What the Agent will be metered: upstream amount plus margin. */
+    readonly amount: bigint;
+    readonly upstreamAmount: bigint;
+    readonly requirement: PaymentRequirements;
+    readonly required: PaymentRequired;
+}
+/**
+ * Where an upstream is paid, when that is not the Service's own chain and Asset.
+ *
+ * The API Hub takes USDC on Monad Mainnet and nothing else, and a Service on
+ * Testnet meters in a Testnet Asset, so the two sides of a fronted call can sit
+ * on different chains. This names the paying side. The signer is the one that
+ * holds funds there, and defaults to the proxy's own; the amount the Agent is
+ * metered is the upstream's base units passed through `pricing`, which is right
+ * only when both Assets are six-decimal dollar stablecoins, and a Service that
+ * fronts anything else states its own conversion in `pricing`.
+ */
+export interface X402UpstreamPayment {
+    readonly chainId: bigint;
+    readonly asset: Address;
+    readonly signer?: X402Signer;
+}
+export interface X402FrontedProxyOptions extends Omit<TabProxyOptions, "fetchImpl"> {
+    /** The Service operator's key: what pays the upstream. */
+    readonly signer: X402Signer;
+    readonly pricing: X402UpstreamPricing;
+    /** The Asset the Service meters in. The upstream is paid in it, on its chain, unless `upstreamPayment` says otherwise. */
+    readonly asset: Pick<AssetRef, "chainId" | "address">;
+    /** The chain, Asset and key the upstream is paid with, where they differ from the Service's own. */
+    readonly upstreamPayment?: X402UpstreamPayment;
+    /** The `fetch` the paying client sends with. Defaults to the host's. */
+    readonly fetchImpl?: X402Fetch<Response>;
+    /** Refuse any upstream price above this many atomic units. Omitted sets no ceiling. */
+    readonly maxUpstreamAmount?: bigint;
+    /** Runs after the upstream's 402 and before the signature. An `err` stops the payment. */
+    readonly preflight?: (quote: X402PreflightQuote, request: Request) => Promise<Result<void>> | Result<void>;
+    /** Replaces the response a `preflight` refusal is answered with. */
+    readonly onRefused?: (error: TabError, quote: X402PreflightQuote, request: Request) => Response | undefined;
+    readonly onPayment?: (receipt: X402PaymentReceipt, request: Request) => void;
+    /** Seconds since the epoch, for `validBefore`. A test passes a fixed clock. */
+    readonly nowSeconds?: () => number;
+}
+export interface X402FrontedProxy extends TabProxy {
+    readonly pricing: X402UpstreamPricing;
+    /** Every upstream payment made, oldest first. */
+    payments(): readonly X402PaymentReceipt[];
+}
+/**
+ * Builds the fronting proxy: `createTabProxy` with a forward that pays.
+ *
+ * Everything `createTabProxy` does, hooks, header hygiene, the metering plugin
+ * around the forward, streaming of the response, holds. The one thing it gives
+ * up is streaming of the *request* body: an upstream that answers `402` has to
+ * be sent the same body twice, so a streamed body is read into memory before
+ * the first attempt.
+ */
+export declare function createX402FrontedProxy(options: X402FrontedProxyOptions): X402FrontedProxy;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/x402/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/x402/proxy.ts"],"names":[],"mappings":"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"}