@nevermined-io/payments 1.1.4 → 1.1.5

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

@@ -0,0 +1,146 @@
+/**
+ * LangChain tool wrapper for Nevermined payment protection using the x402 protocol.
+ *
+ * Wraps a LangChain.js tool implementation function to:
+ *
+ * 1. Extract the x402 payment token from `config.configurable.payment_token`
+ * 2. Verify the subscriber has sufficient credits
+ * 3. Execute the wrapped tool function
+ * 4. Settle (burn) credits after successful execution
+ *
+ * Payment errors throw `PaymentRequiredError` so LangChain agents can catch and
+ * surface them to the user. The error carries the full `X402PaymentRequired`
+ * object for programmatic token acquisition.
+ *
+ * The `credits` option accepts two forms:
+ *   - **Static number**: `credits: 1` — always charges 1 credit
+ *   - **Function**: `credits: (ctx) => Math.max(1, ctx.result.length / 100)` — dynamic
+ *
+ * When `credits` is a function, it receives `{ args, result }` after tool execution.
+ *
+ * @example
+ * ```typescript
+ * import { tool } from '@langchain/core/tools'
+ * import { z } from 'zod'
+ * import { Payments } from '@nevermined-io/payments'
+ * import { requiresPayment } from '@nevermined-io/payments/langchain'
+ *
+ * const payments = Payments.getInstance({ nvmApiKey: '...', environment: 'testing' })
+ *
+ * const searchData = tool(
+ *   requiresPayment(
+ *     (args) => `Results for ${args.query}`,
+ *     { payments, planId: PLAN_ID, credits: 1 }
+ *   ),
+ *   { name: 'search_data', description: 'Search for data', schema: z.object({ query: z.string() }) }
+ * )
+ *
+ * // Invoke with payment token
+ * const result = await searchData.invoke(
+ *   { query: 'AI trends' },
+ *   { configurable: { payment_token: accessToken } }
+ * )
+ * ```
+ */
+import type { Payments } from '../../payments.js';
+import { type X402PaymentRequired } from '../facilitator-api.js';
+/**
+ * Context passed to a dynamic credits function after tool execution.
+ */
+export interface CreditsContext {
+    /** The tool's input arguments */
+    args: Record<string, unknown>;
+    /** The tool's return value */
+    result: unknown;
+}
+/**
+ * Credits can be a static number or a function that receives
+ * `{ args, result }` and returns the number of credits to charge.
+ */
+export type CreditsCallable = (ctx: CreditsContext) => number;
+/**
+ * Options for the `requiresPayment` wrapper.
+ */
+export interface RequiresPaymentOptions {
+    /** The Payments instance (with payments.facilitator) */
+    payments: Payments;
+    /** Single plan ID to accept */
+    planId: string;
+    /** Number of credits to charge, or a function for dynamic pricing (default: 1) */
+    credits?: number | CreditsCallable;
+    /** Optional agent identifier */
+    agentId?: string;
+    /** Blockchain network in CAIP-2 format (default: 'eip155:84532' for Base Sepolia) */
+    network?: string;
+}
+/**
+ * Thrown when payment verification fails or no token is provided.
+ *
+ * Carries the `X402PaymentRequired` object so callers can inspect
+ * accepted plans and acquire the correct payment token.
+ */
+export declare class PaymentRequiredError extends Error {
+    /** The x402 PaymentRequired object for programmatic token acquisition */
+    paymentRequired: X402PaymentRequired | undefined;
+    constructor(message: string, paymentRequired?: X402PaymentRequired);
+}
+/**
+ * Payment context stored in `config.configurable.payment_context` after verification.
+ */
+export interface PaymentContext {
+    /** The x402 access token */
+    token: string;
+    /** The payment required object */
+    paymentRequired: X402PaymentRequired;
+    /** Number of credits to settle */
+    creditsToSettle: number;
+    /** Whether verification was successful */
+    verified: boolean;
+    /** Agent request ID for observability tracking */
+    agentRequestId?: string;
+    /** Agent request context for observability */
+    agentRequest?: unknown;
+}
+/**
+ * Wraps a LangChain.js tool implementation with x402 payment verification and settlement.
+ *
+ * This is a higher-order function that takes the tool's implementation function and
+ * payment options, returning a new function with the same signature that:
+ *
+ * 1. Extracts the payment token from `config.configurable.payment_token`
+ * 2. Verifies the subscriber has sufficient credits
+ * 3. Calls the original tool function
+ * 4. Settles (burns) credits
+ * 5. Stores `payment_context` and `payment_settlement` in `config.configurable`
+ *
+ * @param fn - The tool implementation function: `(args, config?) => result`
+ * @param options - Payment configuration
+ * @returns Wrapped function with the same signature
+ *
+ * @example Static credits
+ * ```typescript
+ * const searchData = tool(
+ *   requiresPayment(
+ *     (args) => `Results for ${args.query}`,
+ *     { payments, planId: PLAN_ID, credits: 1 }
+ *   ),
+ *   { name: 'search_data', description: 'Search', schema: z.object({ query: z.string() }) }
+ * )
+ * ```
+ *
+ * @example Dynamic credits
+ * ```typescript
+ * const summarize = tool(
+ *   requiresPayment(
+ *     (args) => `Summary of ${args.text}`,
+ *     {
+ *       payments, planId: PLAN_ID,
+ *       credits: (ctx) => Math.max(1, Math.floor(String(ctx.result).length / 100)),
+ *     }
+ *   ),
+ *   { name: 'summarize', description: 'Summarize text', schema: z.object({ text: z.string() }) }
+ * )
+ * ```
+ */
+export declare function requiresPayment<TArgs extends Record<string, unknown>, TResult>(fn: (args: TArgs, config?: unknown) => TResult | Promise<TResult>, options: RequiresPaymentOptions): (args: TArgs, config?: unknown) => Promise<TResult>;
+//# sourceMappingURL=decorator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../../src/x402/langchain/decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,uBAAuB,CAAA;AAE9B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,8BAA8B;IAC9B,MAAM,EAAE,OAAO,CAAA;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,CAAA;AAE7D;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,QAAQ,EAAE,QAAQ,CAAA;IAClB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAAA;IAClC,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,yEAAyE;IACzE,eAAe,EAAE,mBAAmB,GAAG,SAAS,CAAA;gBAEpC,OAAO,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,mBAAmB;CAKnE;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,kCAAkC;IAClC,eAAe,EAAE,mBAAmB,CAAA;IACpC,kCAAkC;IAClC,eAAe,EAAE,MAAM,CAAA;IACvB,0CAA0C;IAC1C,QAAQ,EAAE,OAAO,CAAA;IACjB,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,eAAe,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAC5E,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EACjE,OAAO,EAAE,sBAAsB,GAC9B,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAiFrD"}

package/dist/x402/langchain/decorator.js

@@ -0,0 +1,190 @@
+/**
+ * LangChain tool wrapper for Nevermined payment protection using the x402 protocol.
+ *
+ * Wraps a LangChain.js tool implementation function to:
+ *
+ * 1. Extract the x402 payment token from `config.configurable.payment_token`
+ * 2. Verify the subscriber has sufficient credits
+ * 3. Execute the wrapped tool function
+ * 4. Settle (burn) credits after successful execution
+ *
+ * Payment errors throw `PaymentRequiredError` so LangChain agents can catch and
+ * surface them to the user. The error carries the full `X402PaymentRequired`
+ * object for programmatic token acquisition.
+ *
+ * The `credits` option accepts two forms:
+ *   - **Static number**: `credits: 1` — always charges 1 credit
+ *   - **Function**: `credits: (ctx) => Math.max(1, ctx.result.length / 100)` — dynamic
+ *
+ * When `credits` is a function, it receives `{ args, result }` after tool execution.
+ *
+ * @example
+ * ```typescript
+ * import { tool } from '@langchain/core/tools'
+ * import { z } from 'zod'
+ * import { Payments } from '@nevermined-io/payments'
+ * import { requiresPayment } from '@nevermined-io/payments/langchain'
+ *
+ * const payments = Payments.getInstance({ nvmApiKey: '...', environment: 'testing' })
+ *
+ * const searchData = tool(
+ *   requiresPayment(
+ *     (args) => `Results for ${args.query}`,
+ *     { payments, planId: PLAN_ID, credits: 1 }
+ *   ),
+ *   { name: 'search_data', description: 'Search for data', schema: z.object({ query: z.string() }) }
+ * )
+ *
+ * // Invoke with payment token
+ * const result = await searchData.invoke(
+ *   { query: 'AI trends' },
+ *   { configurable: { payment_token: accessToken } }
+ * )
+ * ```
+ */
+import { buildPaymentRequired, } from '../facilitator-api.js';
+/**
+ * Thrown when payment verification fails or no token is provided.
+ *
+ * Carries the `X402PaymentRequired` object so callers can inspect
+ * accepted plans and acquire the correct payment token.
+ */
+export class PaymentRequiredError extends Error {
+    constructor(message, paymentRequired) {
+        super(message);
+        this.name = 'PaymentRequiredError';
+        this.paymentRequired = paymentRequired;
+    }
+}
+/**
+ * Extract the payment token from a LangChain RunnableConfig.
+ *
+ * In LangChain.js, the config is the optional second parameter to tool functions:
+ * `(args, config?) => ...` where config is a `RunnableConfig`.
+ */
+function extractPaymentToken(config) {
+    if (config == null || typeof config !== 'object')
+        return null;
+    const configurable = config.configurable;
+    if (configurable == null || typeof configurable !== 'object')
+        return null;
+    const token = configurable.payment_token;
+    return typeof token === 'string' ? token : null;
+}
+/**
+ * Store a value in config.configurable if available.
+ */
+function storeInConfigurable(config, key, value) {
+    if (config == null || typeof config !== 'object')
+        return;
+    const configurable = config.configurable;
+    if (configurable == null || typeof configurable !== 'object')
+        return;
+    configurable[key] = value;
+}
+/**
+ * Wraps a LangChain.js tool implementation with x402 payment verification and settlement.
+ *
+ * This is a higher-order function that takes the tool's implementation function and
+ * payment options, returning a new function with the same signature that:
+ *
+ * 1. Extracts the payment token from `config.configurable.payment_token`
+ * 2. Verifies the subscriber has sufficient credits
+ * 3. Calls the original tool function
+ * 4. Settles (burns) credits
+ * 5. Stores `payment_context` and `payment_settlement` in `config.configurable`
+ *
+ * @param fn - The tool implementation function: `(args, config?) => result`
+ * @param options - Payment configuration
+ * @returns Wrapped function with the same signature
+ *
+ * @example Static credits
+ * ```typescript
+ * const searchData = tool(
+ *   requiresPayment(
+ *     (args) => `Results for ${args.query}`,
+ *     { payments, planId: PLAN_ID, credits: 1 }
+ *   ),
+ *   { name: 'search_data', description: 'Search', schema: z.object({ query: z.string() }) }
+ * )
+ * ```
+ *
+ * @example Dynamic credits
+ * ```typescript
+ * const summarize = tool(
+ *   requiresPayment(
+ *     (args) => `Summary of ${args.text}`,
+ *     {
+ *       payments, planId: PLAN_ID,
+ *       credits: (ctx) => Math.max(1, Math.floor(String(ctx.result).length / 100)),
+ *     }
+ *   ),
+ *   { name: 'summarize', description: 'Summarize text', schema: z.object({ text: z.string() }) }
+ * )
+ * ```
+ */
+export function requiresPayment(fn, options) {
+    const { payments, planId, credits = 1, agentId, network } = options;
+    return async (args, config) => {
+        // Build payment required object
+        const paymentRequired = buildPaymentRequired(planId, {
+            endpoint: fn.name || 'tool',
+            agentId,
+            network,
+        });
+        // Extract token from config.configurable.payment_token
+        const token = extractPaymentToken(config);
+        if (!token) {
+            throw new PaymentRequiredError("Payment required: missing payment_token in config.configurable", paymentRequired);
+        }
+        // Resolve pre-execution credits (static only; callable deferred to post-execution)
+        const creditsToVerify = typeof credits === 'number' ? credits : 1;
+        // Verify permissions
+        let verification;
+        try {
+            verification = await payments.facilitator.verifyPermissions({
+                paymentRequired,
+                x402AccessToken: token,
+                maxAmount: BigInt(creditsToVerify),
+            });
+        }
+        catch (error) {
+            throw new PaymentRequiredError(`Payment verification failed: ${error instanceof Error ? error.message : String(error)}`, paymentRequired);
+        }
+        if (!verification.isValid) {
+            throw new PaymentRequiredError(`Payment verification failed: ${verification.invalidReason || 'Insufficient credits or invalid token'}`, paymentRequired);
+        }
+        // Store payment context
+        const paymentContext = {
+            token,
+            paymentRequired,
+            creditsToSettle: creditsToVerify,
+            verified: true,
+            agentRequestId: verification.agentRequest?.agentRequestId || verification.agentRequestId,
+            agentRequest: verification.agentRequest,
+        };
+        storeInConfigurable(config, 'payment_context', paymentContext);
+        // Execute the tool function
+        const result = await fn(args, config);
+        // Resolve final credits (may be dynamic based on result)
+        const finalCredits = typeof credits === 'function'
+            ? credits({ args: args, result })
+            : credits;
+        // Settle credits
+        try {
+            const settlement = await payments.facilitator.settlePermissions({
+                paymentRequired,
+                x402AccessToken: token,
+                maxAmount: BigInt(finalCredits),
+                agentRequestId: paymentContext.agentRequestId,
+            });
+            storeInConfigurable(config, 'payment_settlement', settlement);
+        }
+        catch (settleError) {
+            console.error('Payment settlement failed:', settleError);
+            // Still return result even if settlement fails
+        }
+        return result;
+    };
+}
+//# sourceMappingURL=decorator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decorator.js","sourceRoot":"","sources":["../../../src/x402/langchain/decorator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * LangChain tool wrapper for Nevermined payment protection using the x402 protocol.\n *\n * Wraps a LangChain.js tool implementation function to:\n *\n * 1. Extract the x402 payment token from `config.configurable.payment_token`\n * 2. Verify the subscriber has sufficient credits\n * 3. Execute the wrapped tool function\n * 4. Settle (burn) credits after successful execution\n *\n * Payment errors throw `PaymentRequiredError` so LangChain agents can catch and\n * surface them to the user. The error carries the full `X402PaymentRequired`\n * object for programmatic token acquisition.\n *\n * The `credits` option accepts two forms:\n *   - **Static number**: `credits: 1` — always charges 1 credit\n *   - **Function**: `credits: (ctx) => Math.max(1, ctx.result.length / 100)` — dynamic\n *\n * When `credits` is a function, it receives `{ args, result }` after tool execution.\n *\n * @example\n * ```typescript\n * import { tool } from '@langchain/core/tools'\n * import { z } from 'zod'\n * import { Payments } from '@nevermined-io/payments'\n * import { requiresPayment } from '@nevermined-io/payments/langchain'\n *\n * const payments = Payments.getInstance({ nvmApiKey: '...', environment: 'testing' })\n *\n * const searchData = tool(\n *   requiresPayment(\n *     (args) => `Results for ${args.query}`,\n *     { payments, planId: PLAN_ID, credits: 1 }\n *   ),\n *   { name: 'search_data', description: 'Search for data', schema: z.object({ query: z.string() }) }\n * )\n *\n * // Invoke with payment token\n * const result = await searchData.invoke(\n *   { query: 'AI trends' },\n *   { configurable: { payment_token: accessToken } }\n * )\n * ```\n */\n\nimport type { Payments } from '../../payments.js'\nimport {\n  buildPaymentRequired,\n  type X402PaymentRequired,\n  type VerifyPermissionsResult,\n} from '../facilitator-api.js'\n\n/**\n * Context passed to a dynamic credits function after tool execution.\n */\nexport interface CreditsContext {\n  /** The tool's input arguments */\n  args: Record<string, unknown>\n  /** The tool's return value */\n  result: unknown\n}\n\n/**\n * Credits can be a static number or a function that receives\n * `{ args, result }` and returns the number of credits to charge.\n */\nexport type CreditsCallable = (ctx: CreditsContext) => number\n\n/**\n * Options for the `requiresPayment` wrapper.\n */\nexport interface RequiresPaymentOptions {\n  /** The Payments instance (with payments.facilitator) */\n  payments: Payments\n  /** Single plan ID to accept */\n  planId: string\n  /** Number of credits to charge, or a function for dynamic pricing (default: 1) */\n  credits?: number | CreditsCallable\n  /** Optional agent identifier */\n  agentId?: string\n  /** Blockchain network in CAIP-2 format (default: 'eip155:84532' for Base Sepolia) */\n  network?: string\n}\n\n/**\n * Thrown when payment verification fails or no token is provided.\n *\n * Carries the `X402PaymentRequired` object so callers can inspect\n * accepted plans and acquire the correct payment token.\n */\nexport class PaymentRequiredError extends Error {\n  /** The x402 PaymentRequired object for programmatic token acquisition */\n  paymentRequired: X402PaymentRequired | undefined\n\n  constructor(message: string, paymentRequired?: X402PaymentRequired) {\n    super(message)\n    this.name = 'PaymentRequiredError'\n    this.paymentRequired = paymentRequired\n  }\n}\n\n/**\n * Payment context stored in `config.configurable.payment_context` after verification.\n */\nexport interface PaymentContext {\n  /** The x402 access token */\n  token: string\n  /** The payment required object */\n  paymentRequired: X402PaymentRequired\n  /** Number of credits to settle */\n  creditsToSettle: number\n  /** Whether verification was successful */\n  verified: boolean\n  /** Agent request ID for observability tracking */\n  agentRequestId?: string\n  /** Agent request context for observability */\n  agentRequest?: unknown\n}\n\n/**\n * Extract the payment token from a LangChain RunnableConfig.\n *\n * In LangChain.js, the config is the optional second parameter to tool functions:\n * `(args, config?) => ...` where config is a `RunnableConfig`.\n */\nfunction extractPaymentToken(config: unknown): string | null {\n  if (config == null || typeof config !== 'object') return null\n\n  const configurable = (config as Record<string, unknown>).configurable\n  if (configurable == null || typeof configurable !== 'object') return null\n\n  const token = (configurable as Record<string, unknown>).payment_token\n  return typeof token === 'string' ? token : null\n}\n\n/**\n * Store a value in config.configurable if available.\n */\nfunction storeInConfigurable(config: unknown, key: string, value: unknown): void {\n  if (config == null || typeof config !== 'object') return\n\n  const configurable = (config as Record<string, unknown>).configurable\n  if (configurable == null || typeof configurable !== 'object') return\n\n  ;(configurable as Record<string, unknown>)[key] = value\n}\n\n/**\n * Wraps a LangChain.js tool implementation with x402 payment verification and settlement.\n *\n * This is a higher-order function that takes the tool's implementation function and\n * payment options, returning a new function with the same signature that:\n *\n * 1. Extracts the payment token from `config.configurable.payment_token`\n * 2. Verifies the subscriber has sufficient credits\n * 3. Calls the original tool function\n * 4. Settles (burns) credits\n * 5. Stores `payment_context` and `payment_settlement` in `config.configurable`\n *\n * @param fn - The tool implementation function: `(args, config?) => result`\n * @param options - Payment configuration\n * @returns Wrapped function with the same signature\n *\n * @example Static credits\n * ```typescript\n * const searchData = tool(\n *   requiresPayment(\n *     (args) => `Results for ${args.query}`,\n *     { payments, planId: PLAN_ID, credits: 1 }\n *   ),\n *   { name: 'search_data', description: 'Search', schema: z.object({ query: z.string() }) }\n * )\n * ```\n *\n * @example Dynamic credits\n * ```typescript\n * const summarize = tool(\n *   requiresPayment(\n *     (args) => `Summary of ${args.text}`,\n *     {\n *       payments, planId: PLAN_ID,\n *       credits: (ctx) => Math.max(1, Math.floor(String(ctx.result).length / 100)),\n *     }\n *   ),\n *   { name: 'summarize', description: 'Summarize text', schema: z.object({ text: z.string() }) }\n * )\n * ```\n */\nexport function requiresPayment<TArgs extends Record<string, unknown>, TResult>(\n  fn: (args: TArgs, config?: unknown) => TResult | Promise<TResult>,\n  options: RequiresPaymentOptions,\n): (args: TArgs, config?: unknown) => Promise<TResult> {\n  const { payments, planId, credits = 1, agentId, network } = options\n\n  return async (args: TArgs, config?: unknown): Promise<TResult> => {\n    // Build payment required object\n    const paymentRequired = buildPaymentRequired(planId, {\n      endpoint: fn.name || 'tool',\n      agentId,\n      network,\n    })\n\n    // Extract token from config.configurable.payment_token\n    const token = extractPaymentToken(config)\n    if (!token) {\n      throw new PaymentRequiredError(\n        \"Payment required: missing payment_token in config.configurable\",\n        paymentRequired,\n      )\n    }\n\n    // Resolve pre-execution credits (static only; callable deferred to post-execution)\n    const creditsToVerify = typeof credits === 'number' ? credits : 1\n\n    // Verify permissions\n    let verification: VerifyPermissionsResult\n    try {\n      verification = await payments.facilitator.verifyPermissions({\n        paymentRequired,\n        x402AccessToken: token,\n        maxAmount: BigInt(creditsToVerify),\n      })\n    } catch (error) {\n      throw new PaymentRequiredError(\n        `Payment verification failed: ${error instanceof Error ? error.message : String(error)}`,\n        paymentRequired,\n      )\n    }\n\n    if (!verification.isValid) {\n      throw new PaymentRequiredError(\n        `Payment verification failed: ${verification.invalidReason || 'Insufficient credits or invalid token'}`,\n        paymentRequired,\n      )\n    }\n\n    // Store payment context\n    const paymentContext: PaymentContext = {\n      token,\n      paymentRequired,\n      creditsToSettle: creditsToVerify,\n      verified: true,\n      agentRequestId: verification.agentRequest?.agentRequestId || verification.agentRequestId,\n      agentRequest: verification.agentRequest,\n    }\n    storeInConfigurable(config, 'payment_context', paymentContext)\n\n    // Execute the tool function\n    const result = await fn(args, config)\n\n    // Resolve final credits (may be dynamic based on result)\n    const finalCredits =\n      typeof credits === 'function'\n        ? credits({ args: args as Record<string, unknown>, result })\n        : credits\n\n    // Settle credits\n    try {\n      const settlement = await payments.facilitator.settlePermissions({\n        paymentRequired,\n        x402AccessToken: token,\n        maxAmount: BigInt(finalCredits),\n        agentRequestId: paymentContext.agentRequestId,\n      })\n      storeInConfigurable(config, 'payment_settlement', settlement)\n    } catch (settleError) {\n      console.error('Payment settlement failed:', settleError)\n      // Still return result even if settlement fails\n    }\n\n    return result\n  }\n}\n"]}

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

@@ -0,0 +1,5 @@
+/**
+ * LangChain integration for Nevermined payment protection using the x402 protocol.
+ */
+export { requiresPayment, PaymentRequiredError, type RequiresPaymentOptions, type CreditsCallable, type CreditsContext, type PaymentContext, } from './decorator.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/x402/langchain/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAA"}

package/dist/x402/langchain/index.js

@@ -0,0 +1,5 @@
+/**
+ * LangChain integration for Nevermined payment protection using the x402 protocol.
+ */
+export { requiresPayment, PaymentRequiredError, } from './decorator.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/x402/langchain/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,oBAAoB,GAKrB,MAAM,gBAAgB,CAAA","sourcesContent":["/**\n * LangChain integration for Nevermined payment protection using the x402 protocol.\n */\n\nexport {\n  requiresPayment,\n  PaymentRequiredError,\n  type RequiresPaymentOptions,\n  type CreditsCallable,\n  type CreditsContext,\n  type PaymentContext,\n} from './decorator.js'\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nevermined-io/payments",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Typescript SDK to interact with the Nevermined Payments Protocol",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -31,6 +31,10 @@
     "./express": {
       "types": "./dist/x402/express/index.d.ts",
       "import": "./dist/x402/express/index.js"
+    },
+    "./langchain": {
+      "types": "./dist/x402/langchain/index.d.ts",
+      "import": "./dist/x402/langchain/index.js"
     }
   },
   "scripts": {
@@ -89,7 +93,8 @@
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.25.0",
-    "express": ">=4.0.0"
+    "express": ">=4.0.0",
+    "@langchain/core": ">=0.3.0"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/sdk": {
@@ -97,6 +102,9 @@
     },
     "express": {
       "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
     }
   },
   "dependencies": {