@nevermined-io/payments 1.5.0 → 1.6.0

package/README.md

@@ -19,16 +19,15 @@ The Nevermined Payments Library is a TypeScript SDK that allows AI Builders and
 
 The Payments Library enables:
 
-* Easy registration and discovery of AI agents and the payment plans required to access them. All agents registered in Nevermined expose their metadata in a generic way, making them searchable and discoverable for specific purposes.
-* Flexible definition of pricing options and how AI agents can be queried. This is achieved through payment plans (based on time or credits) and consumption costs (fixed per request or dynamic). All of this can be defined by the AI builder or agent during the registration process.
-* Subscribers (humans or other agents) to purchase credits that grant access to AI agent services. Payments can be made in crypto or fiat via Stripe integration. The protocol registers the payment and credits distribution settlement on-chain.
-* Agents or users with access credits to query other AI agents. Nevermined authorizes only users with sufficient balance and keeps track of their credit usage.
-
+- Easy registration and discovery of AI agents and the payment plans required to access them. All agents registered in Nevermined expose their metadata in a generic way, making them searchable and discoverable for specific purposes.
+- Flexible definition of pricing options and how AI agents can be queried. This is achieved through payment plans (based on time or credits) and consumption costs (fixed per request or dynamic). All of this can be defined by the AI builder or agent during the registration process.
+- Subscribers (humans or other agents) to purchase credits that grant access to AI agent services. Payments can be made in crypto or fiat via Stripe integration. The protocol registers the payment and credits distribution settlement on-chain.
+- Agents or users with access credits to query other AI agents. Nevermined authorizes only users with sufficient balance and keeps track of their credit usage.
 
 The library is designed for use in browser environments or as part of AI Agents:
 
-* In a browser, the library provides a simple way to connect to the Nevermined protocol, allowing users to query AI Agents or publish their own.
-* As part of an AI Agent, the library allows the agent to query other agents programmatically. Additionally, agents can use the library to expose their own services and make them available to other agents or humans.
+- In a browser, the library provides a simple way to connect to the Nevermined protocol, allowing users to query AI Agents or publish their own.
+- As part of an AI Agent, the library allows the agent to query other agents programmatically. Additionally, agents can use the library to expose their own services and make them available to other agents or humans.
 
 ## Quickstart
 
@@ -41,6 +40,7 @@ npm install @nevermined-io/payments@^1.1
 ```
 
 > Pin the major version (or rely on a committed lockfile) so SDK upgrades are explicit. Always commit `package-lock.json` / `pnpm-lock.yaml`.
+
 ## A2A Integration (Agents‑to‑Agents)
 
 Nevermined Payments integrates with the A2A protocol to authorize and charge per request between agents:
@@ -78,13 +78,13 @@ Add a payment extension under `capabilities.extensions` carrying Nevermined meta
 ```
 
 Important notes:
+
 - The `url` must match exactly the URL registered in Nevermined for the agent/plan.
 - The final streaming event must include `metadata.creditsUsed` with the consumed cost.
 
-
 ## Requirements
 
-To use the Nevermined Payments Library, you need to get your Nevermined API key. You can get yours freely from the  [Nevermined App](https://nevermined.app).
+To use the Nevermined Payments Library, you need to get your Nevermined API key. You can get yours freely from the [Nevermined App](https://nevermined.app).
 
 ### Environments
 
@@ -92,6 +92,15 @@ To use the Nevermined Payments Library, you need to get your Nevermined API key.
 
 Pick the environment that matches where your agent and plans are registered. The agent card `url` must belong to that environment.
 
+### Optional peer dependencies
+
+The core SDK has no required runtime peers. Some integrations are gated behind optional peer dependencies you install only if you use them:
+
+- **LangChain tool protection** (`@nevermined-io/payments/langchain`) — requires `@langchain/core` and `@langchain/langgraph >=1.0.0 <2`.
+- **LangSmith observability** (`@nevermined-io/payments/langsmith`, and the spans the `requiresPayment` wrapper emits when `LANGSMITH_TRACING=true`) — requires **`langsmith >=0.7`**. The spans rely on `getCurrentRunTree` (exported from `langsmith/singletons/traceable`) and the merging `RunTree.metadata` setter, both of which are only reliably present from `0.7` onward. Install it yourself: `pnpm add langsmith`.
+
+These are declared as optional peers, so npm/pnpm will not pull them in automatically and the SDK no-ops cleanly when they are absent.
+
 ### Initialize the Payments library in the Browser
 
 This is a browser only method. Here we have an example using react.
@@ -124,7 +133,7 @@ export default function Home() {
 ### Initialize the Payments library in an AI Agent
 
 ```typescript
-import { Payments } from "@nevermined-io/payments";
+import { Payments } from '@nevermined-io/payments'
 
 const payments = Payments.getInstance({
   nvmApiKey,
@@ -138,19 +147,29 @@ Once the app is initialized we can create a payment plan:
 
 ```typescript
 const planMetadata: PlanMetadata = {
-    name: 'E2E test Payments Plan',
-  }
+  name: 'E2E test Payments Plan',
+}
 const priceConfig = payments.plans.getERC20PriceConfig(20n, ERC20_ADDRESS, builderAddress)
 const creditsConfig = payments.plans.getFixedCreditsConfig(100n)
-const { planId } = await payments.plans.registerCreditsPlan(planMetadata, priceConfig, creditsConfig)
+const { planId } = await payments.plans.registerCreditsPlan(
+  planMetadata,
+  priceConfig,
+  creditsConfig,
+)
 ```
 
 Or register a plan limited by time:
 
 ```typescript
 const priceConfig = payments.plans.getERC20PriceConfig(50n, ERC20_ADDRESS, builderAddress)
-const expirablePlanConfig = payments.plans.getExpirableDurationConfig(payments.plans.ONE_DAY_DURATION) // 1 day
-const response = await payments.plans.registerTimePlan(planMetadata, priceConfig, expirablePlanConfig)
+const expirablePlanConfig = payments.plans.getExpirableDurationConfig(
+  payments.plans.ONE_DAY_DURATION,
+) // 1 day
+const response = await payments.plans.registerTimePlan(
+  planMetadata,
+  priceConfig,
+  expirablePlanConfig,
+)
 ```
 
 You can also create trial plans (free plans that can only be purchased once):
@@ -166,7 +185,7 @@ const trialCreditsConfig = payments.plans.getFixedCreditsConfig(10n)
 const trialPlan = await payments.plans.registerCreditsTrialPlan(
   trialPlanMetadata,
   freePriceConfig,
-  trialCreditsConfig
+  trialCreditsConfig,
 )
 
 // Time-based trial plan
@@ -174,7 +193,7 @@ const timeTrialConfig = payments.plans.getExpirableDurationConfig(ONE_DAY_DURATI
 const timeTrialPlan = await payments.plans.registerTimeTrialPlan(
   trialPlanMetadata,
   freePriceConfig,
-  timeTrialConfig
+  timeTrialConfig,
 )
 ```
 
@@ -192,12 +211,13 @@ const agentMetadata = {
 // The API that the agent will expose
 const agentApi = {
   endpoints: [
-    { 'POST': `https://example.com/api/v1/agents/:agentId/tasks` },
-    { 'GET': `https://example.com/api/v1/agents/:agentId/tasks/invoke` }
-]}
+    { POST: `https://example.com/api/v1/agents/:agentId/tasks` },
+    { GET: `https://example.com/api/v1/agents/:agentId/tasks/invoke` },
+  ],
+}
 
 // This is the list of payment plans that the agent will accept
-const paymentPlans = [ creditsPlanId, expirablePlanId ]
+const paymentPlans = [creditsPlanId, expirablePlanId]
 const result = await payments.agents.registerAgent(agentMetadata, agentApi, paymentPlans)
 ```
 
@@ -212,9 +232,7 @@ const agentMetadata = {
 }
 
 const agentApi = {
-  endpoints: [
-    { 'POST': 'https://example.com/api/v1/agents/:agentId/tasks' }
-  ]
+  endpoints: [{ POST: 'https://example.com/api/v1/agents/:agentId/tasks' }],
 }
 
 const planMetadata = { name: 'Basic Plan' }
@@ -228,11 +246,12 @@ const { agentId, planId, txHash } = await payments.agents.registerAgentAndPlan(
   planMetadata,
   priceConfig,
   creditsConfig,
-  'time' // Optionally set access limit to 'time' or 'credits'
+  'time', // Optionally set access limit to 'time' or 'credits'
 )
 ```
 
 The `accessLimit` parameter is optional. If not specified, it's automatically inferred:
+
 - `'credits'` if `creditsConfig.durationSecs === 0n` (non-expirable)
 - `'time'` if `creditsConfig.durationSecs > 0n` (expirable)
 
@@ -261,7 +280,7 @@ const agentHTTPOptions = {
   headers: {
     Accept: 'application/json',
     'Content-Type': 'application/json',
-    'payment-signature': accessToken
+    'payment-signature': accessToken,
   },
 }
 const response = await fetch(new URL(agentURL), agentHTTPOptions)
@@ -281,7 +300,7 @@ MCP servers expose handlers (tools/resources/prompts) with their logical URLs, s
 
 ### Why Nevermined Payments?
 
-While MCP defines *what* an agent can do, it doesn't specify *who* can access it or *how* to charge for it. **Nevermined Payments** adds:
+While MCP defines _what_ an agent can do, it doesn't specify _who_ can access it or _how_ to charge for it. **Nevermined Payments** adds:
 
 - **Authentication**: Validates user tokens via `Authorization` header
 - **Credit System**: Checks and deducts credits per request
@@ -292,77 +311,77 @@ While MCP defines *what* an agent can do, it doesn't specify *who* can access it
 #### 1. Initialize Nevermined Payments
 
 ```typescript
-import { Payments, EnvironmentName } from "@nevermined-io/payments";
+import { Payments, EnvironmentName } from '@nevermined-io/payments'
 
 const payments = Payments.getInstance({
   nvmApiKey: process.env.NVM_API_KEY!,
   environment: process.env.NVM_ENVIRONMENT! as EnvironmentName,
-});
+})
 ```
 
 #### 2. Register Protected Tools
 
 ```typescript
-import { z } from "zod";
+import { z } from 'zod'
 
 const schema = z.object({
-  city: z.string().describe("City name"),
-}) as any;
+  city: z.string().describe('City name'),
+}) as any
 
 payments.mcp.registerTool(
-  "weather.today",
+  'weather.today',
   {
     title: "Today's Weather",
-    description: "Get weather for a city",
+    description: 'Get weather for a city',
     inputSchema: schema,
   },
   async (args) => {
-    const { city } = args as { city: string };
+    const { city } = args as { city: string }
     return {
-      content: [{ type: "text", text: `Weather for ${city}: Sunny, 25C` }],
-    };
+      content: [{ type: 'text', text: `Weather for ${city}: Sunny, 25C` }],
+    }
   },
-  { credits: 1n }
-);
+  { credits: 1n },
+)
 ```
 
 #### 3. Register Protected Resources
 
 ```typescript
 payments.mcp.registerResource(
-  "Weather Data",
-  "weather://today",
+  'Weather Data',
+  'weather://today',
   {
     title: "Today's Weather",
-    description: "JSON weather data",
-    mimeType: "application/json",
+    description: 'JSON weather data',
+    mimeType: 'application/json',
   },
   async (uri) => {
     return {
-      contents: [{ uri: uri.href, text: "{...}", mimeType: "application/json" }],
-    };
+      contents: [{ uri: uri.href, text: '{...}', mimeType: 'application/json' }],
+    }
   },
-  { credits: 5n }
-);
+  { credits: 5n },
+)
 ```
 
 #### 4. Register Protected Prompts
 
 ```typescript
 payments.mcp.registerPrompt(
-  "weather.ensureCity",
+  'weather.ensureCity',
   {
-    title: "Ensure city",
-    description: "Guide to call weather.today",
+    title: 'Ensure city',
+    description: 'Guide to call weather.today',
     argsSchema: schema,
   },
   (args) => {
     return {
-      messages: [{ role: "user", content: { type: "text", text: "..." } }],
-    };
+      messages: [{ role: 'user', content: { type: 'text', text: '...' } }],
+    }
   },
-  { credits: (ctx) => ctx.result.length > 100 ? 2n : 1n }  // Dynamic credits
-);
+  { credits: (ctx) => (ctx.result.length > 100 ? 2n : 1n) }, // Dynamic credits
+)
 ```
 
 #### 5. Start the Server
@@ -371,9 +390,9 @@ payments.mcp.registerPrompt(
 const { info, stop } = await payments.mcp.start({
   port: 3002,
   agentId: process.env.NVM_AGENT_ID!,
-  serverName: "weather-mcp",
-  version: "0.1.0",
-});
+  serverName: 'weather-mcp',
+  version: '0.1.0',
+})
 ```
 
 ### Credit Configuration
@@ -382,22 +401,32 @@ All registration functions support fixed or dynamic credits:
 
 ```typescript
 // Fixed credits
-{ credits: 1n }
-{ credits: 5n }
+{
+  credits: 1n
+}
+{
+  credits: 5n
+}
 
 // Dynamic credits based on input
-{ credits: (ctx) => ctx.args.premium ? 5n : 1n }
+{
+  credits: (ctx) => (ctx.args.premium ? 5n : 1n)
+}
 
 // Dynamic credits based on result
-{ credits: (ctx) => ctx.result.length > 1000 ? 3n : 1n }
+{
+  credits: (ctx) => (ctx.result.length > 1000 ? 3n : 1n)
+}
 
 // Tiered pricing
-{ credits: (ctx) => {
-  const size = JSON.stringify(ctx.result).length;
-  if (size > 1000) return 5n;
-  if (size > 500) return 3n;
-  return 1n;
-}}
+{
+  credits: (ctx) => {
+    const size = JSON.stringify(ctx.result).length
+    if (size > 1000) return 5n
+    if (size > 500) return 3n
+    return 1n
+  }
+}
 ```
 
 ### Client Usage
@@ -405,55 +434,54 @@ All registration functions support fixed or dynamic credits:
 #### Get Access Token
 
 ```typescript
-import { Payments } from "@nevermined-io/payments";
+import { Payments } from '@nevermined-io/payments'
 
 const payments = Payments.getInstance({
   nvmApiKey: process.env.NVM_API_KEY!,
-  environment: "sandbox",
-});
+  environment: 'sandbox',
+})
 
 const { accessToken } = await payments.x402.getX402AccessToken(
   process.env.NVM_PLAN_ID!,
-  process.env.NVM_AGENT_ID!
-);
+  process.env.NVM_AGENT_ID!,
+)
 ```
 
 #### Call Protected Tools
 
 ```typescript
-import { Client } from "@modelcontextprotocol/sdk/client";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp";
+import { Client } from '@modelcontextprotocol/sdk/client'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp'
 
-const transport = new StreamableHTTPClientTransport(
-  new URL("http://localhost:3002/mcp"),
-  { requestInit: { headers: { Authorization: `Bearer ${accessToken}` } } }
-);
+const transport = new StreamableHTTPClientTransport(new URL('http://localhost:3002/mcp'), {
+  requestInit: { headers: { Authorization: `Bearer ${accessToken}` } },
+})
 
-const client = new Client({ name: "my-client" });
-await client.connect(transport);
+const client = new Client({ name: 'my-client' })
+await client.connect(transport)
 
 const result = await client.callTool({
-  name: "weather.today",
-  arguments: { city: "London" },
-});
+  name: 'weather.today',
+  arguments: { city: 'London' },
+})
 ```
 
 ### Endpoints
 
-| Endpoint | Description |
-|----------|-------------|
-| `POST /mcp` | MCP JSON-RPC requests |
-| `GET /mcp` | SSE stream for notifications |
-| `DELETE /mcp` | Session termination |
-| `GET /health` | Health check |
-| `GET /` | Server info |
+| Endpoint      | Description                  |
+| ------------- | ---------------------------- |
+| `POST /mcp`   | MCP JSON-RPC requests        |
+| `GET /mcp`    | SSE stream for notifications |
+| `DELETE /mcp` | Session termination          |
+| `GET /health` | Health check                 |
+| `GET /`       | Server info                  |
 
 ### Error Codes
 
-| Code | Description |
-|------|-------------|
+| Code     | Description                                                      |
+| -------- | ---------------------------------------------------------------- |
 | `-32003` | Authorization required / Payment required / Insufficient credits |
-| `-32002` | Server error |
+| `-32002` | Server error                                                     |
 
 ### Notes
 

package/dist/x402/langchain/agent.d.ts

@@ -0,0 +1,96 @@
+/**
+ * LangGraph ReAct agent helper that surfaces `PaymentRequiredError` intact.
+ *
+ * By default `createReactAgent` from `@langchain/langgraph/prebuilt` constructs a
+ * `ToolNode` with `handleToolErrors: true` — tool exceptions are caught and
+ * rendered into a `ToolMessage` for the LLM. That is convenient for
+ * prompt-engineered recovery, but it stringifies the exception and loses the
+ * `X402PaymentRequired` payload attached to {@link PaymentRequiredError}.
+ * Without that payload the caller cannot run the x402 discovery flow (probe →
+ * read scheme/network/plan id → acquire token → retry).
+ *
+ * {@link createPaidReactAgent} builds the same agent but with a `ToolNode`
+ * configured to **re-raise** exceptions (`handleToolErrors: false`), so
+ * `PaymentRequiredError` propagates all the way back to `agent.invoke()`'s
+ * caller with `.paymentRequired` populated.
+ *
+ * `@langchain/langgraph` is imported **lazily** inside the function so the
+ * existing `peerDependencies` story is unchanged — users who only use the
+ * `requiresPayment` wrapper do not need LangGraph installed. Install it
+ * yourself (`pnpm add @langchain/langgraph`) to use this helper.
+ *
+ * Unlike Python's synchronous `create_paid_react_agent`, this helper is
+ * **`async`** — that is a deliberate consequence of the lazy `import()` that
+ * keeps `@langchain/langgraph` an optional peer, not a parity break. `await` it.
+ *
+ * @example
+ * ```typescript
+ * import { tool } from '@langchain/core/tools'
+ * import { ChatOpenAI } from '@langchain/openai'
+ * import { z } from 'zod'
+ * import {
+ *   PaymentRequiredError,
+ *   createPaidReactAgent,
+ *   requiresPayment,
+ *   lastSettlement,
+ * } from '@nevermined-io/payments/langchain'
+ *
+ * const getMarketInsight = tool(
+ *   requiresPayment(
+ *     (args) => `Market insight for ${args.topic} ...`,
+ *     { payments, planId: PLAN_ID, credits: 1 },
+ *   ),
+ *   { name: 'get_market_insight', description: 'Paid market insight', schema: z.object({ topic: z.string() }) },
+ * )
+ *
+ * const agent = await createPaidReactAgent(
+ *   new ChatOpenAI({ model: 'gpt-4o-mini', temperature: 0 }),
+ *   [getMarketInsight],
+ *   { prompt: '...' },
+ * )
+ *
+ * // Discovery: invoke without a token to learn what to pay for.
+ * try {
+ *   await agent.invoke({ messages: [...] }, { configurable: {} })
+ * } catch (err) {
+ *   if (err instanceof PaymentRequiredError) {
+ *     const accept = err.paymentRequired?.accepts[0]
+ *     // ... acquire token using accept.planId / accept.scheme / accept.network ...
+ *   }
+ * }
+ *
+ * const result = await agent.invoke(
+ *   { messages: [...] },
+ *   { configurable: { payment_token: token } },
+ * )
+ * const receipt = lastSettlement()
+ * ```
+ */
+/**
+ * Options forwarded to the underlying `createReactAgent` call.
+ *
+ * Everything except `tools` (which this helper builds from the `tools`
+ * argument as a `ToolNode` with `handleToolErrors: false`) and `llm` (which
+ * this helper maps from the `model` argument) is passed through verbatim —
+ * `prompt`, `stateSchema`, `checkpointer`, `responseFormat`, etc.
+ */
+export type CreatePaidReactAgentOptions = Record<string, unknown>;
+/**
+ * Build a LangGraph ReAct agent that lets `PaymentRequiredError` propagate.
+ *
+ * Wraps `createReactAgent` from `@langchain/langgraph/prebuilt` with a
+ * `ToolNode(tools, { handleToolErrors: false })`. The signature mirrors the
+ * Python `create_paid_react_agent(model, tools, **kwargs)` helper: `model` is
+ * mapped to the JS `llm` parameter and any extra `options` are forwarded.
+ *
+ * @param model - The chat model (mapped to `createReactAgent`'s `llm` argument).
+ * @param tools - The LangChain tools, typically functions wrapped with
+ *   `requiresPayment` and registered via `tool(...)`.
+ * @param options - Forwarded verbatim to `createReactAgent` (`prompt`,
+ *   `stateSchema`, `checkpointer`, …).
+ * @returns The compiled ReAct agent graph, ready to be invoked with
+ *   `agent.invoke(...)`.
+ * @throws If `@langchain/langgraph` is not installed.
+ */
+export declare function createPaidReactAgent(model: unknown, tools: readonly unknown[], options?: CreatePaidReactAgentOptions): Promise<unknown>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/x402/langchain/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/x402/langchain/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEjE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,OAAO,CAAC,CAyClB"}

package/dist/x402/langchain/agent.js

@@ -0,0 +1,121 @@
+/**
+ * LangGraph ReAct agent helper that surfaces `PaymentRequiredError` intact.
+ *
+ * By default `createReactAgent` from `@langchain/langgraph/prebuilt` constructs a
+ * `ToolNode` with `handleToolErrors: true` — tool exceptions are caught and
+ * rendered into a `ToolMessage` for the LLM. That is convenient for
+ * prompt-engineered recovery, but it stringifies the exception and loses the
+ * `X402PaymentRequired` payload attached to {@link PaymentRequiredError}.
+ * Without that payload the caller cannot run the x402 discovery flow (probe →
+ * read scheme/network/plan id → acquire token → retry).
+ *
+ * {@link createPaidReactAgent} builds the same agent but with a `ToolNode`
+ * configured to **re-raise** exceptions (`handleToolErrors: false`), so
+ * `PaymentRequiredError` propagates all the way back to `agent.invoke()`'s
+ * caller with `.paymentRequired` populated.
+ *
+ * `@langchain/langgraph` is imported **lazily** inside the function so the
+ * existing `peerDependencies` story is unchanged — users who only use the
+ * `requiresPayment` wrapper do not need LangGraph installed. Install it
+ * yourself (`pnpm add @langchain/langgraph`) to use this helper.
+ *
+ * Unlike Python's synchronous `create_paid_react_agent`, this helper is
+ * **`async`** — that is a deliberate consequence of the lazy `import()` that
+ * keeps `@langchain/langgraph` an optional peer, not a parity break. `await` it.
+ *
+ * @example
+ * ```typescript
+ * import { tool } from '@langchain/core/tools'
+ * import { ChatOpenAI } from '@langchain/openai'
+ * import { z } from 'zod'
+ * import {
+ *   PaymentRequiredError,
+ *   createPaidReactAgent,
+ *   requiresPayment,
+ *   lastSettlement,
+ * } from '@nevermined-io/payments/langchain'
+ *
+ * const getMarketInsight = tool(
+ *   requiresPayment(
+ *     (args) => `Market insight for ${args.topic} ...`,
+ *     { payments, planId: PLAN_ID, credits: 1 },
+ *   ),
+ *   { name: 'get_market_insight', description: 'Paid market insight', schema: z.object({ topic: z.string() }) },
+ * )
+ *
+ * const agent = await createPaidReactAgent(
+ *   new ChatOpenAI({ model: 'gpt-4o-mini', temperature: 0 }),
+ *   [getMarketInsight],
+ *   { prompt: '...' },
+ * )
+ *
+ * // Discovery: invoke without a token to learn what to pay for.
+ * try {
+ *   await agent.invoke({ messages: [...] }, { configurable: {} })
+ * } catch (err) {
+ *   if (err instanceof PaymentRequiredError) {
+ *     const accept = err.paymentRequired?.accepts[0]
+ *     // ... acquire token using accept.planId / accept.scheme / accept.network ...
+ *   }
+ * }
+ *
+ * const result = await agent.invoke(
+ *   { messages: [...] },
+ *   { configurable: { payment_token: token } },
+ * )
+ * const receipt = lastSettlement()
+ * ```
+ */
+/**
+ * Build a LangGraph ReAct agent that lets `PaymentRequiredError` propagate.
+ *
+ * Wraps `createReactAgent` from `@langchain/langgraph/prebuilt` with a
+ * `ToolNode(tools, { handleToolErrors: false })`. The signature mirrors the
+ * Python `create_paid_react_agent(model, tools, **kwargs)` helper: `model` is
+ * mapped to the JS `llm` parameter and any extra `options` are forwarded.
+ *
+ * @param model - The chat model (mapped to `createReactAgent`'s `llm` argument).
+ * @param tools - The LangChain tools, typically functions wrapped with
+ *   `requiresPayment` and registered via `tool(...)`.
+ * @param options - Forwarded verbatim to `createReactAgent` (`prompt`,
+ *   `stateSchema`, `checkpointer`, …).
+ * @returns The compiled ReAct agent graph, ready to be invoked with
+ *   `agent.invoke(...)`.
+ * @throws If `@langchain/langgraph` is not installed.
+ */
+export async function createPaidReactAgent(model, tools, options = {}) {
+    // `llm` and `tools` are owned by this helper — `tools` carries the
+    // handleToolErrors:false ToolNode that makes PaymentRequiredError propagate,
+    // and overriding either would silently defeat the whole point of the helper
+    // (a caller-supplied `tools` re-enables the default handleToolErrors:true and
+    // the X402 payload is stringified away). Reject them up front, mirroring how
+    // Python's positional `create_paid_react_agent(model, tools, **kwargs)` raises
+    // a TypeError if `llm`/`tools` are passed again via kwargs.
+    if ('llm' in options || 'tools' in options) {
+        throw new Error('createPaidReactAgent: `llm` and `tools` are set from the `model` and ' +
+            '`tools` arguments and must not be passed in `options` (they would ' +
+            'override the handleToolErrors:false ToolNode and break x402 discovery).');
+    }
+    let prebuilt;
+    try {
+        prebuilt = await import('@langchain/langgraph/prebuilt');
+    }
+    catch (err) {
+        throw new Error('createPaidReactAgent requires @langchain/langgraph. ' +
+            `Install it with \`pnpm add @langchain/langgraph\`. (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const { ToolNode, createReactAgent } = prebuilt;
+    // handleToolErrors: false re-raises tool exceptions instead of stringifying
+    // them into a ToolMessage, so PaymentRequiredError reaches agent.invoke()'s
+    // caller with its X402PaymentRequired payload intact.
+    const toolNode = new ToolNode(tools, { handleToolErrors: false });
+    // `createReactAgent` is the current prebuilt entry point in
+    // @langchain/langgraph@1.2.0. It is marked @deprecated in favour of
+    // `createAgent`, but that replacement lives in the separate `langchain`
+    // package (out of scope for this SDK's optional langgraph peer), so the
+    // prebuilt `createReactAgent` is the deliberate, only in-package choice here.
+    // Spread `...options` FIRST so the protected `llm`/`tools` keys (set last)
+    // always win, even though the guard above already forbids them in `options`.
+    return createReactAgent({ ...options, llm: model, tools: toolNode });
+}
+//# sourceMappingURL=agent.js.map

package/dist/x402/langchain/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/x402/langchain/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAYH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAc,EACd,KAAyB,EACzB,UAAuC,EAAE;IAEzC,mEAAmE;IACnE,6EAA6E;IAC7E,4EAA4E;IAC5E,8EAA8E;IAC9E,6EAA6E;IAC7E,+EAA+E;IAC/E,4DAA4D;IAC5D,IAAI,KAAK,IAAI,OAAO,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CACb,uEAAuE;YACrE,oEAAoE;YACpE,yEAAyE,CAC5E,CAAA;IACH,CAAC;IAED,IAAI,QAAwD,CAAA;IAC5D,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,MAAM,CAAC,+BAA+B,CAAC,CAAA;IAC1D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,sDAAsD;YACpD,uDACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,GAAG,CACN,CAAA;IACH,CAAC;IACD,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,QAAQ,CAAA;IAE/C,4EAA4E;IAC5E,4EAA4E;IAC5E,sDAAsD;IACtD,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,KAAc,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC,CAAA;IAC1E,4DAA4D;IAC5D,oEAAoE;IACpE,wEAAwE;IACxE,wEAAwE;IACxE,8EAA8E;IAC9E,2EAA2E;IAC3E,6EAA6E;IAC7E,OAAO,gBAAgB,CAAC,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,KAAc,EAAE,KAAK,EAAE,QAAQ,EAAW,CAAC,CAAA;AACxF,CAAC","sourcesContent":["/**\n * LangGraph ReAct agent helper that surfaces `PaymentRequiredError` intact.\n *\n * By default `createReactAgent` from `@langchain/langgraph/prebuilt` constructs a\n * `ToolNode` with `handleToolErrors: true` — tool exceptions are caught and\n * rendered into a `ToolMessage` for the LLM. That is convenient for\n * prompt-engineered recovery, but it stringifies the exception and loses the\n * `X402PaymentRequired` payload attached to {@link PaymentRequiredError}.\n * Without that payload the caller cannot run the x402 discovery flow (probe →\n * read scheme/network/plan id → acquire token → retry).\n *\n * {@link createPaidReactAgent} builds the same agent but with a `ToolNode`\n * configured to **re-raise** exceptions (`handleToolErrors: false`), so\n * `PaymentRequiredError` propagates all the way back to `agent.invoke()`'s\n * caller with `.paymentRequired` populated.\n *\n * `@langchain/langgraph` is imported **lazily** inside the function so the\n * existing `peerDependencies` story is unchanged — users who only use the\n * `requiresPayment` wrapper do not need LangGraph installed. Install it\n * yourself (`pnpm add @langchain/langgraph`) to use this helper.\n *\n * Unlike Python's synchronous `create_paid_react_agent`, this helper is\n * **`async`** — that is a deliberate consequence of the lazy `import()` that\n * keeps `@langchain/langgraph` an optional peer, not a parity break. `await` it.\n *\n * @example\n * ```typescript\n * import { tool } from '@langchain/core/tools'\n * import { ChatOpenAI } from '@langchain/openai'\n * import { z } from 'zod'\n * import {\n *   PaymentRequiredError,\n *   createPaidReactAgent,\n *   requiresPayment,\n *   lastSettlement,\n * } from '@nevermined-io/payments/langchain'\n *\n * const getMarketInsight = tool(\n *   requiresPayment(\n *     (args) => `Market insight for ${args.topic} ...`,\n *     { payments, planId: PLAN_ID, credits: 1 },\n *   ),\n *   { name: 'get_market_insight', description: 'Paid market insight', schema: z.object({ topic: z.string() }) },\n * )\n *\n * const agent = await createPaidReactAgent(\n *   new ChatOpenAI({ model: 'gpt-4o-mini', temperature: 0 }),\n *   [getMarketInsight],\n *   { prompt: '...' },\n * )\n *\n * // Discovery: invoke without a token to learn what to pay for.\n * try {\n *   await agent.invoke({ messages: [...] }, { configurable: {} })\n * } catch (err) {\n *   if (err instanceof PaymentRequiredError) {\n *     const accept = err.paymentRequired?.accepts[0]\n *     // ... acquire token using accept.planId / accept.scheme / accept.network ...\n *   }\n * }\n *\n * const result = await agent.invoke(\n *   { messages: [...] },\n *   { configurable: { payment_token: token } },\n * )\n * const receipt = lastSettlement()\n * ```\n */\n\n/**\n * Options forwarded to the underlying `createReactAgent` call.\n *\n * Everything except `tools` (which this helper builds from the `tools`\n * argument as a `ToolNode` with `handleToolErrors: false`) and `llm` (which\n * this helper maps from the `model` argument) is passed through verbatim —\n * `prompt`, `stateSchema`, `checkpointer`, `responseFormat`, etc.\n */\nexport type CreatePaidReactAgentOptions = Record<string, unknown>\n\n/**\n * Build a LangGraph ReAct agent that lets `PaymentRequiredError` propagate.\n *\n * Wraps `createReactAgent` from `@langchain/langgraph/prebuilt` with a\n * `ToolNode(tools, { handleToolErrors: false })`. The signature mirrors the\n * Python `create_paid_react_agent(model, tools, **kwargs)` helper: `model` is\n * mapped to the JS `llm` parameter and any extra `options` are forwarded.\n *\n * @param model - The chat model (mapped to `createReactAgent`'s `llm` argument).\n * @param tools - The LangChain tools, typically functions wrapped with\n *   `requiresPayment` and registered via `tool(...)`.\n * @param options - Forwarded verbatim to `createReactAgent` (`prompt`,\n *   `stateSchema`, `checkpointer`, …).\n * @returns The compiled ReAct agent graph, ready to be invoked with\n *   `agent.invoke(...)`.\n * @throws If `@langchain/langgraph` is not installed.\n */\nexport async function createPaidReactAgent(\n  model: unknown,\n  tools: readonly unknown[],\n  options: CreatePaidReactAgentOptions = {},\n): Promise<unknown> {\n  // `llm` and `tools` are owned by this helper — `tools` carries the\n  // handleToolErrors:false ToolNode that makes PaymentRequiredError propagate,\n  // and overriding either would silently defeat the whole point of the helper\n  // (a caller-supplied `tools` re-enables the default handleToolErrors:true and\n  // the X402 payload is stringified away). Reject them up front, mirroring how\n  // Python's positional `create_paid_react_agent(model, tools, **kwargs)` raises\n  // a TypeError if `llm`/`tools` are passed again via kwargs.\n  if ('llm' in options || 'tools' in options) {\n    throw new Error(\n      'createPaidReactAgent: `llm` and `tools` are set from the `model` and ' +\n        '`tools` arguments and must not be passed in `options` (they would ' +\n        'override the handleToolErrors:false ToolNode and break x402 discovery).',\n    )\n  }\n\n  let prebuilt: typeof import('@langchain/langgraph/prebuilt')\n  try {\n    prebuilt = await import('@langchain/langgraph/prebuilt')\n  } catch (err) {\n    throw new Error(\n      'createPaidReactAgent requires @langchain/langgraph. ' +\n        `Install it with \\`pnpm add @langchain/langgraph\\`. (${\n          err instanceof Error ? err.message : String(err)\n        })`,\n    )\n  }\n  const { ToolNode, createReactAgent } = prebuilt\n\n  // handleToolErrors: false re-raises tool exceptions instead of stringifying\n  // them into a ToolMessage, so PaymentRequiredError reaches agent.invoke()'s\n  // caller with its X402PaymentRequired payload intact.\n  const toolNode = new ToolNode(tools as never, { handleToolErrors: false })\n  // `createReactAgent` is the current prebuilt entry point in\n  // @langchain/langgraph@1.2.0. It is marked @deprecated in favour of\n  // `createAgent`, but that replacement lives in the separate `langchain`\n  // package (out of scope for this SDK's optional langgraph peer), so the\n  // prebuilt `createReactAgent` is the deliberate, only in-package choice here.\n  // Spread `...options` FIRST so the protected `llm`/`tools` keys (set last)\n  // always win, even though the guard above already forbids them in `options`.\n  return createReactAgent({ ...options, llm: model as never, tools: toolNode } as never)\n}\n"]}