@ausca/ai-sdk 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# @ausca/ai-sdk
+
+Vercel AI SDK tools that consume paid HTTP APIs by answering `402 Payment
+Required` with an [x402](https://www.x402.org) v2 payment, instead of carrying
+an API key. The model authors the request; the wallet and a hard per-call USD
+cap stay with your code.
+
+Works against any x402 v2 resource. [Ausca](https://ausca.com) is the default
+example because its services are keyless and receipt-backed, which is the shape
+this tool exists for.
+
+## Install
+
+```bash
+npm install @ausca/ai-sdk ai viem zod
+```
+
+## Use
+
+```ts
+import { generateText } from "ai";
+import { x402Tool } from "@ausca/ai-sdk";
+import { privateKeyToAccount } from "viem/accounts";
+import { z } from "zod";
+
+const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);
+
+const result = await generateText({
+  model: yourModel,
+  prompt: "Extract the text from the uploaded scan.",
+  tools: {
+    // Document OCR on Ausca: copy the exact offer binding from
+    // https://ausca.com/catalog.json (offer document.ocr).
+    extract_document_text: x402Tool({
+      description:
+        "Extracts normalized text from a scanned document for $0.30. Input is the immutable artifact commitment of the uploaded document.",
+      inputSchema: z.object({
+        artifact_ref: z.string(),
+        content_digest: z.string(),
+        media_type: z.string(),
+      }),
+      url: "https://ausca.com/v1/extract-text",
+      account,
+      maxPaymentUsd: 0.5,
+      buildBody: (input) => ({
+        offer_id: "document.ocr",
+        input: { artifact: input },
+        idempotency_key: `ocr-${input.content_digest.slice(7, 27)}`,
+      }),
+    }),
+  },
+});
+```
+
+The tool result carries the resource result and, when the call was paid, the
+decoded settlement proof from the `PAYMENT-RESPONSE` header.
+
+## Spend authority
+
+`maxPaymentUsd` is enforced by the x402 client's spend controls before
+anything is signed. A resource quoting above the cap makes the tool throw; no
+payment is created. The account object never reaches the model.
+
+## Any x402 resource
+
+Nothing here is vendor-specific: point `url` at any endpoint that answers an
+x402 v2 challenge and the tool pays it under the same cap. `network` defaults
+to Base mainnet (`eip155:8453`) and accepts any CAIP-2 network your account
+can pay on.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,107 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  x402Tool: () => x402Tool
+});
+module.exports = __toCommonJS(index_exports);
+var import_ai = require("ai");
+
+// ../payable/src/index.ts
+var import_fetch = require("@x402/fetch");
+var import_evm = require("@x402/evm");
+function createPayableFetch(options) {
+  if (!Number.isFinite(options.maxPaymentUsd) || options.maxPaymentUsd <= 0) {
+    throw new Error("maxPaymentUsd must be a positive number");
+  }
+  return (0, import_fetch.wrapFetchWithPaymentFromConfig)(options.fetch ?? globalThis.fetch, {
+    schemes: [
+      {
+        network: options.network ?? "eip155:8453",
+        client: new import_evm.ExactEvmScheme(options.account)
+      }
+    ],
+    spendControls: { maxAmountPerPayment: `$${options.maxPaymentUsd}` }
+  });
+}
+function paymentReceipt(response) {
+  const header = response.headers.get("PAYMENT-RESPONSE");
+  if (!header) {
+    return null;
+  }
+  const decoded = (0, import_fetch.decodePaymentResponseHeader)(header);
+  return {
+    success: decoded.success === true,
+    network: typeof decoded.network === "string" ? decoded.network : void 0,
+    transaction: typeof decoded.transaction === "string" ? decoded.transaction : void 0,
+    payer: typeof decoded.payer === "string" ? decoded.payer : void 0
+  };
+}
+async function payableCall(options, body) {
+  const method = options.method ?? "POST";
+  const payableFetch = createPayableFetch(options);
+  const response = await payableFetch(options.url, {
+    method,
+    headers: { "content-type": "application/json", ...options.headers },
+    body: method === "GET" ? void 0 : JSON.stringify(body ?? {})
+  });
+  const text = await response.text();
+  let result = text;
+  try {
+    result = JSON.parse(text);
+  } catch {
+  }
+  if (!response.ok) {
+    throw new Error(
+      `payable resource ${options.url} answered ${response.status}: ${text.slice(0, 512)}`
+    );
+  }
+  return { result, payment: paymentReceipt(response), status: response.status };
+}
+
+// src/index.ts
+function x402Tool(options) {
+  return (0, import_ai.tool)({
+    description: options.description,
+    inputSchema: options.inputSchema,
+    execute: async (input) => {
+      const outcome = await payableCall(
+        {
+          url: options.url,
+          method: options.method,
+          account: options.account,
+          network: options.network,
+          maxPaymentUsd: options.maxPaymentUsd,
+          headers: options.headers
+        },
+        options.buildBody ? options.buildBody(input) : input
+      );
+      if (outcome.payment && options.onPayment) {
+        options.onPayment(outcome.payment);
+      }
+      return { result: outcome.result, payment: outcome.payment };
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  x402Tool
+});

package/dist/index.d.cts

@@ -0,0 +1,235 @@
+import * as ai from 'ai';
+import * as _ai_sdk_provider from '@ai-sdk/provider';
+import * as _ai_sdk_provider_utils from '@ai-sdk/provider-utils';
+import { LocalAccount } from 'viem';
+import { z } from 'zod';
+import { PaymentReceipt } from '@ausca-internal/payable';
+export { PaymentReceipt } from '@ausca-internal/payable';
+
+interface X402ToolOptions<Schema extends z.ZodTypeAny> {
+    /** What the tool does and what it costs, in the model's language. */
+    readonly description: string;
+    /** Zod schema of the tool input the model authors. */
+    readonly inputSchema: Schema;
+    /** The payable resource URL. Any x402 v2 resource works. */
+    readonly url: string;
+    /** HTTP method of the payable resource. */
+    readonly method?: "GET" | "POST";
+    /** The signing account that pays. Never exposed to the model. */
+    readonly account: LocalAccount;
+    /** CAIP-2 network to pay on. Defaults to Base mainnet ("eip155:8453"). */
+    readonly network?: string;
+    /**
+     * Hard per-call USD cap enforced before signing. The model can author the
+     * request, never the spend authority.
+     */
+    readonly maxPaymentUsd: number;
+    /** Extra request headers. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Maps the model-authored input to the request body. Defaults to identity. */
+    readonly buildBody?: (input: z.infer<Schema>) => unknown;
+    /** Called with the settlement proof after each paid call. */
+    readonly onPayment?: (payment: PaymentReceipt) => void;
+}
+/**
+ * Builds a Vercel AI SDK tool over one x402 payable resource. The tool result
+ * carries the resource result and, when the call was paid, the decoded
+ * settlement proof.
+ */
+declare function x402Tool<Schema extends z.ZodTypeAny>(options: X402ToolOptions<Schema>): ({
+    title?: string;
+    providerOptions?: _ai_sdk_provider_utils.ProviderOptions;
+    metadata?: _ai_sdk_provider.JSONObject;
+    inputSchema: ai.FlexibleSchema<z.TypeOf<Schema>>;
+    contextSchema?: ai.FlexibleSchema<_ai_sdk_provider_utils.Context> | undefined;
+    needsApproval?: boolean | _ai_sdk_provider_utils.ToolNeedsApprovalFunction<[z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>, NoInfer<_ai_sdk_provider_utils.Context>> | undefined;
+    onInputStart?: ((options: ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+        output: NoInfer<{
+            result: unknown;
+            payment: PaymentReceipt | null;
+        }>;
+    }) => _ai_sdk_provider_utils.ToolResultOutput | PromiseLike<_ai_sdk_provider_utils.ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: ai.FlexibleSchema<{
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }> | undefined;
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+} & {
+    description?: string | ((options: {
+        context: NoInfer<_ai_sdk_provider_utils.Context>;
+        experimental_sandbox?: ai.Experimental_SandboxSession;
+    }) => string) | undefined;
+    strict?: boolean;
+    inputExamples?: {
+        input: NoInfer<z.TypeOf<Schema>>;
+    }[] | undefined;
+    id?: never;
+    isProviderExecuted?: never;
+    args?: never;
+    supportsDeferredResults?: never;
+} & {
+    type?: undefined | "function";
+} & {
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+}) | ({
+    title?: string;
+    providerOptions?: _ai_sdk_provider_utils.ProviderOptions;
+    metadata?: _ai_sdk_provider.JSONObject;
+    inputSchema: ai.FlexibleSchema<z.TypeOf<Schema>>;
+    contextSchema?: ai.FlexibleSchema<_ai_sdk_provider_utils.Context> | undefined;
+    needsApproval?: boolean | _ai_sdk_provider_utils.ToolNeedsApprovalFunction<[z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>, NoInfer<_ai_sdk_provider_utils.Context>> | undefined;
+    onInputStart?: ((options: ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+        output: NoInfer<{
+            result: unknown;
+            payment: PaymentReceipt | null;
+        }>;
+    }) => _ai_sdk_provider_utils.ToolResultOutput | PromiseLike<_ai_sdk_provider_utils.ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: ai.FlexibleSchema<{
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }> | undefined;
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+} & {
+    description?: string | ((options: {
+        context: NoInfer<_ai_sdk_provider_utils.Context>;
+        experimental_sandbox?: ai.Experimental_SandboxSession;
+    }) => string) | undefined;
+    strict?: boolean;
+    inputExamples?: {
+        input: NoInfer<z.TypeOf<Schema>>;
+    }[] | undefined;
+    id?: never;
+    isProviderExecuted?: never;
+    args?: never;
+    supportsDeferredResults?: never;
+} & {
+    type: "dynamic";
+} & {
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+}) | ({
+    title?: string;
+    providerOptions?: _ai_sdk_provider_utils.ProviderOptions;
+    metadata?: _ai_sdk_provider.JSONObject;
+    inputSchema: ai.FlexibleSchema<z.TypeOf<Schema>>;
+    contextSchema?: ai.FlexibleSchema<_ai_sdk_provider_utils.Context> | undefined;
+    needsApproval?: boolean | _ai_sdk_provider_utils.ToolNeedsApprovalFunction<[z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>, NoInfer<_ai_sdk_provider_utils.Context>> | undefined;
+    onInputStart?: ((options: ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+        output: NoInfer<{
+            result: unknown;
+            payment: PaymentReceipt | null;
+        }>;
+    }) => _ai_sdk_provider_utils.ToolResultOutput | PromiseLike<_ai_sdk_provider_utils.ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: ai.FlexibleSchema<{
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }> | undefined;
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+} & {
+    type: "provider";
+    id: `${string}.${string}`;
+    args: Record<string, unknown>;
+    description?: never;
+    strict?: never;
+    inputExamples?: never;
+} & {
+    isProviderExecuted: false;
+    supportsDeferredResults?: never;
+} & {
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+}) | ({
+    title?: string;
+    providerOptions?: _ai_sdk_provider_utils.ProviderOptions;
+    metadata?: _ai_sdk_provider.JSONObject;
+    inputSchema: ai.FlexibleSchema<z.TypeOf<Schema>>;
+    contextSchema?: ai.FlexibleSchema<_ai_sdk_provider_utils.Context> | undefined;
+    needsApproval?: boolean | _ai_sdk_provider_utils.ToolNeedsApprovalFunction<[z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>, NoInfer<_ai_sdk_provider_utils.Context>> | undefined;
+    onInputStart?: ((options: ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+        output: NoInfer<{
+            result: unknown;
+            payment: PaymentReceipt | null;
+        }>;
+    }) => _ai_sdk_provider_utils.ToolResultOutput | PromiseLike<_ai_sdk_provider_utils.ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: ai.FlexibleSchema<{
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }> | undefined;
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+} & {
+    type: "provider";
+    id: `${string}.${string}`;
+    args: Record<string, unknown>;
+    description?: never;
+    strict?: never;
+    inputExamples?: never;
+} & {
+    isProviderExecuted: true;
+    supportsDeferredResults?: boolean;
+} & {
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+});
+
+export { type X402ToolOptions, x402Tool };

package/dist/index.d.ts

@@ -0,0 +1,235 @@
+import * as ai from 'ai';
+import * as _ai_sdk_provider from '@ai-sdk/provider';
+import * as _ai_sdk_provider_utils from '@ai-sdk/provider-utils';
+import { LocalAccount } from 'viem';
+import { z } from 'zod';
+import { PaymentReceipt } from '@ausca-internal/payable';
+export { PaymentReceipt } from '@ausca-internal/payable';
+
+interface X402ToolOptions<Schema extends z.ZodTypeAny> {
+    /** What the tool does and what it costs, in the model's language. */
+    readonly description: string;
+    /** Zod schema of the tool input the model authors. */
+    readonly inputSchema: Schema;
+    /** The payable resource URL. Any x402 v2 resource works. */
+    readonly url: string;
+    /** HTTP method of the payable resource. */
+    readonly method?: "GET" | "POST";
+    /** The signing account that pays. Never exposed to the model. */
+    readonly account: LocalAccount;
+    /** CAIP-2 network to pay on. Defaults to Base mainnet ("eip155:8453"). */
+    readonly network?: string;
+    /**
+     * Hard per-call USD cap enforced before signing. The model can author the
+     * request, never the spend authority.
+     */
+    readonly maxPaymentUsd: number;
+    /** Extra request headers. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Maps the model-authored input to the request body. Defaults to identity. */
+    readonly buildBody?: (input: z.infer<Schema>) => unknown;
+    /** Called with the settlement proof after each paid call. */
+    readonly onPayment?: (payment: PaymentReceipt) => void;
+}
+/**
+ * Builds a Vercel AI SDK tool over one x402 payable resource. The tool result
+ * carries the resource result and, when the call was paid, the decoded
+ * settlement proof.
+ */
+declare function x402Tool<Schema extends z.ZodTypeAny>(options: X402ToolOptions<Schema>): ({
+    title?: string;
+    providerOptions?: _ai_sdk_provider_utils.ProviderOptions;
+    metadata?: _ai_sdk_provider.JSONObject;
+    inputSchema: ai.FlexibleSchema<z.TypeOf<Schema>>;
+    contextSchema?: ai.FlexibleSchema<_ai_sdk_provider_utils.Context> | undefined;
+    needsApproval?: boolean | _ai_sdk_provider_utils.ToolNeedsApprovalFunction<[z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>, NoInfer<_ai_sdk_provider_utils.Context>> | undefined;
+    onInputStart?: ((options: ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+        output: NoInfer<{
+            result: unknown;
+            payment: PaymentReceipt | null;
+        }>;
+    }) => _ai_sdk_provider_utils.ToolResultOutput | PromiseLike<_ai_sdk_provider_utils.ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: ai.FlexibleSchema<{
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }> | undefined;
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+} & {
+    description?: string | ((options: {
+        context: NoInfer<_ai_sdk_provider_utils.Context>;
+        experimental_sandbox?: ai.Experimental_SandboxSession;
+    }) => string) | undefined;
+    strict?: boolean;
+    inputExamples?: {
+        input: NoInfer<z.TypeOf<Schema>>;
+    }[] | undefined;
+    id?: never;
+    isProviderExecuted?: never;
+    args?: never;
+    supportsDeferredResults?: never;
+} & {
+    type?: undefined | "function";
+} & {
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+}) | ({
+    title?: string;
+    providerOptions?: _ai_sdk_provider_utils.ProviderOptions;
+    metadata?: _ai_sdk_provider.JSONObject;
+    inputSchema: ai.FlexibleSchema<z.TypeOf<Schema>>;
+    contextSchema?: ai.FlexibleSchema<_ai_sdk_provider_utils.Context> | undefined;
+    needsApproval?: boolean | _ai_sdk_provider_utils.ToolNeedsApprovalFunction<[z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>, NoInfer<_ai_sdk_provider_utils.Context>> | undefined;
+    onInputStart?: ((options: ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+        output: NoInfer<{
+            result: unknown;
+            payment: PaymentReceipt | null;
+        }>;
+    }) => _ai_sdk_provider_utils.ToolResultOutput | PromiseLike<_ai_sdk_provider_utils.ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: ai.FlexibleSchema<{
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }> | undefined;
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+} & {
+    description?: string | ((options: {
+        context: NoInfer<_ai_sdk_provider_utils.Context>;
+        experimental_sandbox?: ai.Experimental_SandboxSession;
+    }) => string) | undefined;
+    strict?: boolean;
+    inputExamples?: {
+        input: NoInfer<z.TypeOf<Schema>>;
+    }[] | undefined;
+    id?: never;
+    isProviderExecuted?: never;
+    args?: never;
+    supportsDeferredResults?: never;
+} & {
+    type: "dynamic";
+} & {
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+}) | ({
+    title?: string;
+    providerOptions?: _ai_sdk_provider_utils.ProviderOptions;
+    metadata?: _ai_sdk_provider.JSONObject;
+    inputSchema: ai.FlexibleSchema<z.TypeOf<Schema>>;
+    contextSchema?: ai.FlexibleSchema<_ai_sdk_provider_utils.Context> | undefined;
+    needsApproval?: boolean | _ai_sdk_provider_utils.ToolNeedsApprovalFunction<[z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>, NoInfer<_ai_sdk_provider_utils.Context>> | undefined;
+    onInputStart?: ((options: ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+        output: NoInfer<{
+            result: unknown;
+            payment: PaymentReceipt | null;
+        }>;
+    }) => _ai_sdk_provider_utils.ToolResultOutput | PromiseLike<_ai_sdk_provider_utils.ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: ai.FlexibleSchema<{
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }> | undefined;
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+} & {
+    type: "provider";
+    id: `${string}.${string}`;
+    args: Record<string, unknown>;
+    description?: never;
+    strict?: never;
+    inputExamples?: never;
+} & {
+    isProviderExecuted: false;
+    supportsDeferredResults?: never;
+} & {
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+}) | ({
+    title?: string;
+    providerOptions?: _ai_sdk_provider_utils.ProviderOptions;
+    metadata?: _ai_sdk_provider.JSONObject;
+    inputSchema: ai.FlexibleSchema<z.TypeOf<Schema>>;
+    contextSchema?: ai.FlexibleSchema<_ai_sdk_provider_utils.Context> | undefined;
+    needsApproval?: boolean | _ai_sdk_provider_utils.ToolNeedsApprovalFunction<[z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>, NoInfer<_ai_sdk_provider_utils.Context>> | undefined;
+    onInputStart?: ((options: ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+    } & ai.ToolExecutionOptions<NoInfer<_ai_sdk_provider_utils.Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: [z.TypeOf<Schema>] extends [never] ? unknown : z.TypeOf<Schema>;
+        output: NoInfer<{
+            result: unknown;
+            payment: PaymentReceipt | null;
+        }>;
+    }) => _ai_sdk_provider_utils.ToolResultOutput | PromiseLike<_ai_sdk_provider_utils.ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: ai.FlexibleSchema<{
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }> | undefined;
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+} & {
+    type: "provider";
+    id: `${string}.${string}`;
+    args: Record<string, unknown>;
+    description?: never;
+    strict?: never;
+    inputExamples?: never;
+} & {
+    isProviderExecuted: true;
+    supportsDeferredResults?: boolean;
+} & {
+    execute: ai.ToolExecuteFunction<z.TypeOf<Schema>, {
+        result: unknown;
+        payment: PaymentReceipt | null;
+    }, NoInfer<_ai_sdk_provider_utils.Context>>;
+});
+
+export { type X402ToolOptions, x402Tool };

package/dist/index.js

@@ -0,0 +1,82 @@
+// src/index.ts
+import { tool } from "ai";
+
+// ../payable/src/index.ts
+import { decodePaymentResponseHeader, wrapFetchWithPaymentFromConfig } from "@x402/fetch";
+import { ExactEvmScheme } from "@x402/evm";
+function createPayableFetch(options) {
+  if (!Number.isFinite(options.maxPaymentUsd) || options.maxPaymentUsd <= 0) {
+    throw new Error("maxPaymentUsd must be a positive number");
+  }
+  return wrapFetchWithPaymentFromConfig(options.fetch ?? globalThis.fetch, {
+    schemes: [
+      {
+        network: options.network ?? "eip155:8453",
+        client: new ExactEvmScheme(options.account)
+      }
+    ],
+    spendControls: { maxAmountPerPayment: `$${options.maxPaymentUsd}` }
+  });
+}
+function paymentReceipt(response) {
+  const header = response.headers.get("PAYMENT-RESPONSE");
+  if (!header) {
+    return null;
+  }
+  const decoded = decodePaymentResponseHeader(header);
+  return {
+    success: decoded.success === true,
+    network: typeof decoded.network === "string" ? decoded.network : void 0,
+    transaction: typeof decoded.transaction === "string" ? decoded.transaction : void 0,
+    payer: typeof decoded.payer === "string" ? decoded.payer : void 0
+  };
+}
+async function payableCall(options, body) {
+  const method = options.method ?? "POST";
+  const payableFetch = createPayableFetch(options);
+  const response = await payableFetch(options.url, {
+    method,
+    headers: { "content-type": "application/json", ...options.headers },
+    body: method === "GET" ? void 0 : JSON.stringify(body ?? {})
+  });
+  const text = await response.text();
+  let result = text;
+  try {
+    result = JSON.parse(text);
+  } catch {
+  }
+  if (!response.ok) {
+    throw new Error(
+      `payable resource ${options.url} answered ${response.status}: ${text.slice(0, 512)}`
+    );
+  }
+  return { result, payment: paymentReceipt(response), status: response.status };
+}
+
+// src/index.ts
+function x402Tool(options) {
+  return tool({
+    description: options.description,
+    inputSchema: options.inputSchema,
+    execute: async (input) => {
+      const outcome = await payableCall(
+        {
+          url: options.url,
+          method: options.method,
+          account: options.account,
+          network: options.network,
+          maxPaymentUsd: options.maxPaymentUsd,
+          headers: options.headers
+        },
+        options.buildBody ? options.buildBody(input) : input
+      );
+      if (outcome.payment && options.onPayment) {
+        options.onPayment(outcome.payment);
+      }
+      return { result: outcome.result, payment: outcome.payment };
+    }
+  });
+}
+export {
+  x402Tool
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ausca/ai-sdk",
+  "version": "0.1.0",
+  "description": "Vercel AI SDK tools that pay for HTTP 402 APIs over x402 instead of carrying API keys. Works with any x402 v2 resource; Ausca is the default example.",
+  "license": "MIT",
+  "homepage": "https://ausca.com",
+  "type": "module",
+  "keywords": ["ai-sdk", "vercel", "x402", "payments", "agents", "tools", "ausca"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@x402/evm": "^2.24.0",
+    "@x402/fetch": "^2.24.0"
+  },
+  "peerDependencies": {
+    "ai": ">=5",
+    "viem": ">=2",
+    "zod": ">=3"
+  },
+  "devDependencies": {
+    "@ausca-internal/payable": "*",
+    "ai": "^7.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.0",
+    "viem": "^2.44.0",
+    "vitest": "^4.0.0",
+    "zod": "^3.25.0"
+  },
+  "tsup": {
+    "noExternal": ["@ausca-internal/payable"]
+  }
+}