@nevermined-io/payments 1.13.0 → 1.14.0

package/dist/a2a/types.d.ts

@@ -113,6 +113,31 @@ export interface PaymentMetadata {
     agentId?: string;
     /** Configuration for credit redemption behavior */
     redemptionConfig?: PaymentRedemptionConfig;
+    /**
+     * The settle's transaction reference, written by the SDK after settlement.
+     * A chain tx hash on the crypto rails; the PSP transaction id on fiat (a
+     * Stripe PaymentIntent `pi_...`), so do not assume it is a hash.
+     *
+     * ABSENT unless the settle both succeeded AND reported a `transaction`. The
+     * wire's `transaction` is an empty string on a failed settle, and publishing
+     * that put a blank id on a completed task — so the key is omitted instead,
+     * and its PRESENCE means a settlement really happened. Absence does not by
+     * itself mean failure: a successful fiat charge is referenced by the receipt's
+     * `orderTx` and can carry an empty `transaction`. Same rule as `creditsCharged`.
+     */
+    txHash?: string;
+    /**
+     * Credits the settle ACTUALLY REDEEMED, written by the SDK after settlement —
+     * not the credits the request asked to burn, which stay on `creditsUsed`.
+     *
+     * ⚠️ Its ABSENCE is meaningful and is part of the contract. The key is omitted
+     * when there is no measured redemption to report: a pay-as-you-go plan (which
+     * holds no credit balance, so its `creditsRedeemed` is '0' even on a charge
+     * that succeeded), a settle that failed, or a backend that reported no usable
+     * figure. `0` means the opposite — a settle that completed and redeemed
+     * nothing. Read it with `in`, never truthiness. See `resolveCreditsCharged`.
+     */
+    creditsCharged?: number;
 }
 /**
  * Options required to register or retrieve a client in the registry.

package/dist/a2a/types.d.ts.map

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

package/dist/a2a/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/a2a/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG","sourcesContent":["/**\n * Types and interfaces for the A2A payments integration.\n *\n * This module defines the core types and interfaces used throughout the A2A\n * payments integration. It provides:\n * - Task context structures for user executors\n * - Handler result definitions\n * - Payment metadata interfaces\n * - Re-exports of A2A SDK types for convenience\n *\n * These types ensure type safety and provide clear contracts between\n * the user's executor implementation and the payments system.\n */\n\nimport type {\n  AgentCard,\n  Task,\n  Message,\n  Artifact,\n  TaskState,\n  Part,\n  TaskStatusUpdateEvent,\n  TaskArtifactUpdateEvent,\n  PushNotificationConfig,\n  MessageSendParams,\n  SendMessageResponse,\n  TaskQueryParams,\n  GetTaskResponse,\n  TaskPushNotificationConfig,\n  SetTaskPushNotificationConfigResponse,\n  TaskIdParams,\n  GetTaskPushNotificationConfigResponse,\n} from '@a2a-js/sdk'\n\nimport type { ExecutionEventBus, AgentExecutor } from '@a2a-js/sdk/server'\nimport type { StartAgentRequest } from '../common/types.ts'\nimport type { Payments } from '../payments.ts'\n\n/**\n * Union type for A2A streaming events\n *\n * This type represents all possible events that can be yielded by A2A streaming methods.\n * It includes messages, tasks, status updates, and artifact updates.\n */\nexport type A2AStreamEvent = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent\n\n/**\n * Context provided to the user's task handler.\n *\n * This interface contains all the information available to the user's\n * executor when handling an A2A task. It includes:\n * - The original user message\n * - Any existing task state (for continuation)\n * - Authentication information\n * - Request metadata\n *\n * The context is created by the PaymentsA2AAdapter and passed to the\n * user's handleTask method.\n */\nexport interface TaskContext {\n  /** The original message from the user containing the request */\n  userMessage: Message\n  /** Any existing task state (for task continuation scenarios) */\n  existingTask?: Task\n  /** Bearer token for authentication and payment validation */\n  bearerToken?: string\n  /** Additional metadata from the original request */\n  requestMetadata?: Record<string, any>\n  /**\n   * Emit a streaming event to the client (SSE, WebSocket, etc.) during task execution.\n   * This function allows the executor to send intermediate messages or progress updates.\n   *\n   * @param parts - Array of message parts (text, etc.) to send as a streaming event\n   * @param metadata - Optional metadata to include with the event\n   */\n  emitStreamingEvent?: (parts: Part[], metadata?: Record<string, any>) => void\n}\n\n/**\n * Result returned by the user's task handler.\n *\n * This interface defines the structure that user executors must return\n * from their handleTask method. The result includes:\n * - Parts that will be converted to A2A Message or Artifact objects\n * - Optional metadata for payment tracking and other purposes\n * - Task state information\n *\n * The result is processed by the PaymentsA2AAdapter to create the\n * appropriate A2A protocol objects and handle payment operations.\n */\nexport interface TaskHandlerResult {\n  /** Parts that will be converted to A2A Message or Artifact objects */\n  parts: Part[]\n  /** Optional metadata including payment information and custom data */\n  metadata?: PaymentMetadata & Record<string, any>\n  /** The final state of the task */\n  state?: TaskState\n}\n\n/**\n * Configuration for credit redemption behavior\n *\n * This interface defines how credits should be redeemed for a specific agent.\n * The configuration is set at the server level and cannot be manipulated by clients.\n */\nexport interface PaymentRedemptionConfig {\n  /** Whether to use batch processing for redemptions */\n  useBatch?: boolean\n  /** Whether to use margin-based redemptions (if false, uses fixed credits) */\n  useMargin?: boolean\n  /** Margin percentage (0-100) when using margin-based redemptions */\n  marginPercent?: number\n}\n\n/**\n * Metadata for payment/credits information to be included in A2A objects.\n *\n * This interface defines the payment-related metadata that can be included\n * in task handler results. This metadata is used for:\n * - Credit tracking and validation\n * - Payment processing\n * - Cost reporting\n * - Plan management\n *\n * The metadata is embedded in A2A Message objects and can be used by\n * clients to understand the cost of operations.\n */\nexport interface PaymentMetadata {\n  /** Number of credits used for this operation */\n  creditsUsed?: number\n  /** ID of the payment plan associated with this operation */\n  planId?: string\n  /** Type of payment model used */\n  paymentType?: 'fixed' | 'dynamic'\n  /** Human-readable description of the cost */\n  costDescription?: string\n  /** Agent ID for payment tracking */\n  agentId?: string\n  /** Configuration for credit redemption behavior */\n  redemptionConfig?: PaymentRedemptionConfig\n}\n\n/**\n * Options required to register or retrieve a client in the registry.\n */\nexport interface ClientRegistryOptions {\n  agentBaseUrl: string\n  agentId: string\n  planId: string\n  agentCardPath?: string\n  delegationConfig?: import('../common/types.js').DelegationConfig\n  /**\n   * EIP-712 token version to request. `3` mints a single-use token bound to the\n   * agent's service endpoint, minted per paid call instead of cached.\n   */\n  tokenVersion?: import('../common/types.js').X402TokenVersion\n}\n\n/**\n * Options for agent interaction methods (used by PaymentsClient).\n */\nexport interface AgentOptions {\n  agentId: string\n  planId?: string\n}\n\n/**\n * HTTP context associated with a task or message (for internal request tracking).\n *\n * INVARIANT — exactly one of two mutually-exclusive states:\n * - **payment-required**: a payment-gated request arrived with NO token, so only\n *   `paymentRequired` is set (`bearerToken`/`validation` are absent). The handler\n *   short-circuits to an `input-required` task instead of executing the agent.\n * - **authorized**: a token was supplied (in band via `x402.payment.payload` when\n *   `inBand` is true, else the deprecated `payment-signature` header), so\n *   `bearerToken` + `validation` are set (`paymentRequired` is absent).\n *\n * A `mode`-discriminated union would enforce this at the type level (tracked as a\n * follow-up); for now consumers guard the field they need — e.g. the settlement\n * path asserts `bearerToken` + `validation` are present.\n */\nexport type HttpRequestContext = {\n  /** Set only in the authorized state. */\n  bearerToken?: string\n  urlRequested?: string\n  httpMethodRequested?: string\n  /** The validated request — set only in the authorized state. */\n  validation?: StartAgentRequest\n  /**\n   * x402 v2 A2A in-band transport: set by the server middleware when a\n   * payment-gated request arrives with NO token (neither in-band\n   * `x402.payment.payload` nor the deprecated `payment-signature` header). The\n   * handler short-circuits and returns an `input-required` task carrying this\n   * X402PaymentRequired object under `x402.payment.required`, instead of\n   * executing the agent. Set only in the payment-required state.\n   */\n  paymentRequired?: import('../x402/facilitator-api.js').X402PaymentRequired\n  /**\n   * Whether the bearer token was supplied in band (via `x402.payment.payload`\n   * message metadata) rather than the deprecated `payment-signature` header.\n   * When true, settlement receipts are stamped into the task metadata under the\n   * spec-defined `x402.payment.*` keys.\n   */\n  inBand?: boolean\n}\n\n/**\n * Authentication result for A2A requests (equivalent to MCP AuthResult)\n */\nexport interface A2AAuthResult {\n  /** The agent request ID for tracking */\n  requestId: string\n  /** The bearer token for authentication */\n  token: string\n  /** The agent ID */\n  agentId: string\n  /** The agent request data */\n  agentRequest: StartAgentRequest\n}\n\n/**\n * Agent request context provided to A2A AgentExecutors\n *\n * This context contains all the payment-related data that an AgentExecutor needs\n * to process requests with payment integration. The agent is responsible for\n * calculating and specifying credits in its final response.\n */\nexport interface AgentRequestContext {\n  /** Authentication result with request metadata */\n  authResult: A2AAuthResult\n  /** The HTTP context with request details */\n  httpContext: HttpRequestContext\n  /** The payments service instance for observability and other operations */\n  paymentsService: Payments\n}\n\n/**\n * Base RequestContext interface (local definition based on actual usage)\n *\n * This defines the structure that the A2A SDK RequestContext actually has\n * based on how it's used in PaymentsRequestHandler.\n */\nexport interface RequestContext {\n  /** The original message from the user containing the request */\n  userMessage: Message\n  /** Unique identifier for the task */\n  taskId: string\n  /** Unique identifier for the context/conversation */\n  contextId: string\n  /** Any existing task state (for task continuation scenarios) */\n  task?: Task\n  /** Reference tasks for multi-turn conversations */\n  referenceTasks?: Task[]\n  /** Additional metadata from the original request */\n  requestMetadata?: Record<string, any>\n  /** Any existing task state (for task continuation scenarios) */\n  existingTask?: Task\n}\n\n/**\n * Extended RequestContext with agent request data injection\n *\n * This extends the standard A2A RequestContext to include agent request context\n * while maintaining compatibility with the A2A protocol.\n */\nexport interface PaymentsRequestContext extends RequestContext {\n  /** Agent request context injection (following MCP pattern) */\n  payments?: AgentRequestContext\n}\n\n/**\n * Payments-specific AgentExecutor that uses PaymentsRequestContext\n */\nexport interface PaymentsAgentExecutor {\n  execute(requestContext: PaymentsRequestContext, eventBus: ExecutionEventBus): Promise<void>\n  cancelTask(taskId: string, eventBus: ExecutionEventBus): Promise<void>\n}\n\n// Re-export A2A SDK types for convenience\nexport type {\n  AgentCard,\n  Task,\n  Message,\n  Artifact,\n  TaskState,\n  Part,\n  TaskStatusUpdateEvent,\n  PushNotificationConfig,\n  MessageSendParams,\n  SendMessageResponse,\n  TaskQueryParams,\n  GetTaskResponse,\n  TaskPushNotificationConfig,\n  SetTaskPushNotificationConfigResponse,\n  TaskIdParams,\n  GetTaskPushNotificationConfigResponse,\n  ExecutionEventBus,\n  AgentExecutor,\n}\n\n// Re-export server options type for convenience\nexport type { PaymentsA2AServerOptions } from './server.ts'\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/a2a/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG","sourcesContent":["/**\n * Types and interfaces for the A2A payments integration.\n *\n * This module defines the core types and interfaces used throughout the A2A\n * payments integration. It provides:\n * - Task context structures for user executors\n * - Handler result definitions\n * - Payment metadata interfaces\n * - Re-exports of A2A SDK types for convenience\n *\n * These types ensure type safety and provide clear contracts between\n * the user's executor implementation and the payments system.\n */\n\nimport type {\n  AgentCard,\n  Task,\n  Message,\n  Artifact,\n  TaskState,\n  Part,\n  TaskStatusUpdateEvent,\n  TaskArtifactUpdateEvent,\n  PushNotificationConfig,\n  MessageSendParams,\n  SendMessageResponse,\n  TaskQueryParams,\n  GetTaskResponse,\n  TaskPushNotificationConfig,\n  SetTaskPushNotificationConfigResponse,\n  TaskIdParams,\n  GetTaskPushNotificationConfigResponse,\n} from '@a2a-js/sdk'\n\nimport type { ExecutionEventBus, AgentExecutor } from '@a2a-js/sdk/server'\nimport type { StartAgentRequest } from '../common/types.ts'\nimport type { Payments } from '../payments.ts'\n\n/**\n * Union type for A2A streaming events\n *\n * This type represents all possible events that can be yielded by A2A streaming methods.\n * It includes messages, tasks, status updates, and artifact updates.\n */\nexport type A2AStreamEvent = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent\n\n/**\n * Context provided to the user's task handler.\n *\n * This interface contains all the information available to the user's\n * executor when handling an A2A task. It includes:\n * - The original user message\n * - Any existing task state (for continuation)\n * - Authentication information\n * - Request metadata\n *\n * The context is created by the PaymentsA2AAdapter and passed to the\n * user's handleTask method.\n */\nexport interface TaskContext {\n  /** The original message from the user containing the request */\n  userMessage: Message\n  /** Any existing task state (for task continuation scenarios) */\n  existingTask?: Task\n  /** Bearer token for authentication and payment validation */\n  bearerToken?: string\n  /** Additional metadata from the original request */\n  requestMetadata?: Record<string, any>\n  /**\n   * Emit a streaming event to the client (SSE, WebSocket, etc.) during task execution.\n   * This function allows the executor to send intermediate messages or progress updates.\n   *\n   * @param parts - Array of message parts (text, etc.) to send as a streaming event\n   * @param metadata - Optional metadata to include with the event\n   */\n  emitStreamingEvent?: (parts: Part[], metadata?: Record<string, any>) => void\n}\n\n/**\n * Result returned by the user's task handler.\n *\n * This interface defines the structure that user executors must return\n * from their handleTask method. The result includes:\n * - Parts that will be converted to A2A Message or Artifact objects\n * - Optional metadata for payment tracking and other purposes\n * - Task state information\n *\n * The result is processed by the PaymentsA2AAdapter to create the\n * appropriate A2A protocol objects and handle payment operations.\n */\nexport interface TaskHandlerResult {\n  /** Parts that will be converted to A2A Message or Artifact objects */\n  parts: Part[]\n  /** Optional metadata including payment information and custom data */\n  metadata?: PaymentMetadata & Record<string, any>\n  /** The final state of the task */\n  state?: TaskState\n}\n\n/**\n * Configuration for credit redemption behavior\n *\n * This interface defines how credits should be redeemed for a specific agent.\n * The configuration is set at the server level and cannot be manipulated by clients.\n */\nexport interface PaymentRedemptionConfig {\n  /** Whether to use batch processing for redemptions */\n  useBatch?: boolean\n  /** Whether to use margin-based redemptions (if false, uses fixed credits) */\n  useMargin?: boolean\n  /** Margin percentage (0-100) when using margin-based redemptions */\n  marginPercent?: number\n}\n\n/**\n * Metadata for payment/credits information to be included in A2A objects.\n *\n * This interface defines the payment-related metadata that can be included\n * in task handler results. This metadata is used for:\n * - Credit tracking and validation\n * - Payment processing\n * - Cost reporting\n * - Plan management\n *\n * The metadata is embedded in A2A Message objects and can be used by\n * clients to understand the cost of operations.\n */\nexport interface PaymentMetadata {\n  /** Number of credits used for this operation */\n  creditsUsed?: number\n  /** ID of the payment plan associated with this operation */\n  planId?: string\n  /** Type of payment model used */\n  paymentType?: 'fixed' | 'dynamic'\n  /** Human-readable description of the cost */\n  costDescription?: string\n  /** Agent ID for payment tracking */\n  agentId?: string\n  /** Configuration for credit redemption behavior */\n  redemptionConfig?: PaymentRedemptionConfig\n  /**\n   * The settle's transaction reference, written by the SDK after settlement.\n   * A chain tx hash on the crypto rails; the PSP transaction id on fiat (a\n   * Stripe PaymentIntent `pi_...`), so do not assume it is a hash.\n   *\n   * ABSENT unless the settle both succeeded AND reported a `transaction`. The\n   * wire's `transaction` is an empty string on a failed settle, and publishing\n   * that put a blank id on a completed task — so the key is omitted instead,\n   * and its PRESENCE means a settlement really happened. Absence does not by\n   * itself mean failure: a successful fiat charge is referenced by the receipt's\n   * `orderTx` and can carry an empty `transaction`. Same rule as `creditsCharged`.\n   */\n  txHash?: string\n  /**\n   * Credits the settle ACTUALLY REDEEMED, written by the SDK after settlement —\n   * not the credits the request asked to burn, which stay on `creditsUsed`.\n   *\n   * ⚠️ Its ABSENCE is meaningful and is part of the contract. The key is omitted\n   * when there is no measured redemption to report: a pay-as-you-go plan (which\n   * holds no credit balance, so its `creditsRedeemed` is '0' even on a charge\n   * that succeeded), a settle that failed, or a backend that reported no usable\n   * figure. `0` means the opposite — a settle that completed and redeemed\n   * nothing. Read it with `in`, never truthiness. See `resolveCreditsCharged`.\n   */\n  creditsCharged?: number\n}\n\n/**\n * Options required to register or retrieve a client in the registry.\n */\nexport interface ClientRegistryOptions {\n  agentBaseUrl: string\n  agentId: string\n  planId: string\n  agentCardPath?: string\n  delegationConfig?: import('../common/types.js').DelegationConfig\n  /**\n   * EIP-712 token version to request. `3` mints a single-use token bound to the\n   * agent's service endpoint, minted per paid call instead of cached.\n   */\n  tokenVersion?: import('../common/types.js').X402TokenVersion\n}\n\n/**\n * Options for agent interaction methods (used by PaymentsClient).\n */\nexport interface AgentOptions {\n  agentId: string\n  planId?: string\n}\n\n/**\n * HTTP context associated with a task or message (for internal request tracking).\n *\n * INVARIANT — exactly one of two mutually-exclusive states:\n * - **payment-required**: a payment-gated request arrived with NO token, so only\n *   `paymentRequired` is set (`bearerToken`/`validation` are absent). The handler\n *   short-circuits to an `input-required` task instead of executing the agent.\n * - **authorized**: a token was supplied (in band via `x402.payment.payload` when\n *   `inBand` is true, else the deprecated `payment-signature` header), so\n *   `bearerToken` + `validation` are set (`paymentRequired` is absent).\n *\n * A `mode`-discriminated union would enforce this at the type level (tracked as a\n * follow-up); for now consumers guard the field they need — e.g. the settlement\n * path asserts `bearerToken` + `validation` are present.\n */\nexport type HttpRequestContext = {\n  /** Set only in the authorized state. */\n  bearerToken?: string\n  urlRequested?: string\n  httpMethodRequested?: string\n  /** The validated request — set only in the authorized state. */\n  validation?: StartAgentRequest\n  /**\n   * x402 v2 A2A in-band transport: set by the server middleware when a\n   * payment-gated request arrives with NO token (neither in-band\n   * `x402.payment.payload` nor the deprecated `payment-signature` header). The\n   * handler short-circuits and returns an `input-required` task carrying this\n   * X402PaymentRequired object under `x402.payment.required`, instead of\n   * executing the agent. Set only in the payment-required state.\n   */\n  paymentRequired?: import('../x402/facilitator-api.js').X402PaymentRequired\n  /**\n   * Whether the bearer token was supplied in band (via `x402.payment.payload`\n   * message metadata) rather than the deprecated `payment-signature` header.\n   * When true, settlement receipts are stamped into the task metadata under the\n   * spec-defined `x402.payment.*` keys.\n   */\n  inBand?: boolean\n}\n\n/**\n * Authentication result for A2A requests (equivalent to MCP AuthResult)\n */\nexport interface A2AAuthResult {\n  /** The agent request ID for tracking */\n  requestId: string\n  /** The bearer token for authentication */\n  token: string\n  /** The agent ID */\n  agentId: string\n  /** The agent request data */\n  agentRequest: StartAgentRequest\n}\n\n/**\n * Agent request context provided to A2A AgentExecutors\n *\n * This context contains all the payment-related data that an AgentExecutor needs\n * to process requests with payment integration. The agent is responsible for\n * calculating and specifying credits in its final response.\n */\nexport interface AgentRequestContext {\n  /** Authentication result with request metadata */\n  authResult: A2AAuthResult\n  /** The HTTP context with request details */\n  httpContext: HttpRequestContext\n  /** The payments service instance for observability and other operations */\n  paymentsService: Payments\n}\n\n/**\n * Base RequestContext interface (local definition based on actual usage)\n *\n * This defines the structure that the A2A SDK RequestContext actually has\n * based on how it's used in PaymentsRequestHandler.\n */\nexport interface RequestContext {\n  /** The original message from the user containing the request */\n  userMessage: Message\n  /** Unique identifier for the task */\n  taskId: string\n  /** Unique identifier for the context/conversation */\n  contextId: string\n  /** Any existing task state (for task continuation scenarios) */\n  task?: Task\n  /** Reference tasks for multi-turn conversations */\n  referenceTasks?: Task[]\n  /** Additional metadata from the original request */\n  requestMetadata?: Record<string, any>\n  /** Any existing task state (for task continuation scenarios) */\n  existingTask?: Task\n}\n\n/**\n * Extended RequestContext with agent request data injection\n *\n * This extends the standard A2A RequestContext to include agent request context\n * while maintaining compatibility with the A2A protocol.\n */\nexport interface PaymentsRequestContext extends RequestContext {\n  /** Agent request context injection (following MCP pattern) */\n  payments?: AgentRequestContext\n}\n\n/**\n * Payments-specific AgentExecutor that uses PaymentsRequestContext\n */\nexport interface PaymentsAgentExecutor {\n  execute(requestContext: PaymentsRequestContext, eventBus: ExecutionEventBus): Promise<void>\n  cancelTask(taskId: string, eventBus: ExecutionEventBus): Promise<void>\n}\n\n// Re-export A2A SDK types for convenience\nexport type {\n  AgentCard,\n  Task,\n  Message,\n  Artifact,\n  TaskState,\n  Part,\n  TaskStatusUpdateEvent,\n  PushNotificationConfig,\n  MessageSendParams,\n  SendMessageResponse,\n  TaskQueryParams,\n  GetTaskResponse,\n  TaskPushNotificationConfig,\n  SetTaskPushNotificationConfigResponse,\n  TaskIdParams,\n  GetTaskPushNotificationConfigResponse,\n  ExecutionEventBus,\n  AgentExecutor,\n}\n\n// Re-export server options type for convenience\nexport type { PaymentsA2AServerOptions } from './server.ts'\n"]}

package/dist/api/agents-api.d.ts

@@ -116,13 +116,14 @@ export declare class AgentsAPI extends BasePaymentsAPI {
      * Gets the list of plans that can be ordered to get access to an agent.
      *
      * @param agentId - The unique identifier of the agent.
-     * @param pagination - Optional pagination options to control the number of results returned.p
+     * @param pagination - Optional pagination options. Accepts a plain object
+     * (`{ page, offset, sortBy, sortOrder }`) or a `PaginationOptions` instance.
      * @returns A promise that resolves to the list of all different plans giving access to the agent.
      * @throws PaymentsError if the agent is not found.
      *
      * @example
      * ```
-     *  const result = payments.agents.getAgentPlans(planId)
+     *  const result = payments.agents.getAgentPlans(agentId, { page: 1, offset: 10 })
      *  // {
      *  //  total: 10,
      *  //  page: 1,
@@ -131,7 +132,7 @@ export declare class AgentsAPI extends BasePaymentsAPI {
      *  // }
      * ```
      */
-    getAgentPlans(agentId: string, pagination?: PaginationOptions): Promise<any>;
+    getAgentPlans(agentId: string, pagination?: Partial<PaginationOptions>): Promise<any>;
     /**
      * Lists the AI agents **you** published (the authenticated caller's own
      * agents). This is account management, not a marketplace search — it never

package/dist/api/agents-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents-api.d.ts","sourceRoot":"","sources":["../../src/api/agents-api.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,eAAe,EAChB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAA6B,MAAM,oBAAoB,CAAA;AAYnG,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D;;GAEG;AACH,qBAAa,SAAU,SAAQ,eAAe;IAC5C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS;IAItD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,aAAa,CACxB,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,kBAAkB,EAC5B,YAAY,EAAE,MAAM,EAAE,EACtB,kBAAkB,CAAC,EAAE,kBAAkB,GACtC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAsB/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACU,oBAAoB,CAC/B,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,kBAAkB,EAC5B,YAAY,EAAE,YAAY,EAC1B,WAAW,EAAE,eAAe,EAC5B,aAAa,EAAE,iBAAiB,EAChC,WAAW,CAAC,EAAE,SAAS,GAAG,MAAM,EAChC,kBAAkB,CAAC,EAAE,kBAAkB,GACtC,OAAO,CAAC;QACT,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;KACf,CAAC;IA4CF;;;;;;;;;;;OAWG;IACU,QAAQ,CAAC,OAAO,EAAE,MAAM;IASrC;;;;;;;;;;;;;;;;OAgBG;IACU,mBAAmB,CAC9B,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC;IAcxB;;;;;;;;;;;;;;;;;;OAkBG;IACU,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,oBAA0B;IAWhF;;;;;;;;;;;;OAYG;IACU,SAAS,CACpB,IAAI,SAAI,EACR,MAAM,SAAM,EACZ,MAAM,SAAY,EAClB,SAAS,GAAE,KAAK,GAAG,MAAe,EAClC,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC;IAc1E;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAYnF;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAiBzF"}
+{"version":3,"file":"agents-api.d.ts","sourceRoot":"","sources":["../../src/api/agents-api.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,eAAe,EAChB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAA6B,MAAM,oBAAoB,CAAA;AAYnG,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D;;GAEG;AACH,qBAAa,SAAU,SAAQ,eAAe;IAC5C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS;IAItD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,aAAa,CACxB,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,kBAAkB,EAC5B,YAAY,EAAE,MAAM,EAAE,EACtB,kBAAkB,CAAC,EAAE,kBAAkB,GACtC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAsB/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACU,oBAAoB,CAC/B,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,kBAAkB,EAC5B,YAAY,EAAE,YAAY,EAC1B,WAAW,EAAE,eAAe,EAC5B,aAAa,EAAE,iBAAiB,EAChC,WAAW,CAAC,EAAE,SAAS,GAAG,MAAM,EAChC,kBAAkB,CAAC,EAAE,kBAAkB,GACtC,OAAO,CAAC;QACT,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;KACf,CAAC;IA4CF;;;;;;;;;;;OAWG;IACU,QAAQ,CAAC,OAAO,EAAE,MAAM;IASrC;;;;;;;;;;;;;;;;OAgBG;IACU,mBAAmB,CAC9B,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC;IAcxB;;;;;;;;;;;;;;;;;;;OAmBG;IACU,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,GAAE,OAAO,CAAC,iBAAiB,CAAM;IAavF;;;;;;;;;;;;OAYG;IACU,SAAS,CACpB,IAAI,SAAI,EACR,MAAM,SAAM,EACZ,MAAM,SAAY,EAClB,SAAS,GAAE,KAAK,GAAG,MAAe,EAClC,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC;IAc1E;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAYnF;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAiBzF"}

package/dist/api/agents-api.js

@@ -178,13 +178,14 @@ export class AgentsAPI extends BasePaymentsAPI {
      * Gets the list of plans that can be ordered to get access to an agent.
      *
      * @param agentId - The unique identifier of the agent.
-     * @param pagination - Optional pagination options to control the number of results returned.p
+     * @param pagination - Optional pagination options. Accepts a plain object
+     * (`{ page, offset, sortBy, sortOrder }`) or a `PaginationOptions` instance.
      * @returns A promise that resolves to the list of all different plans giving access to the agent.
      * @throws PaymentsError if the agent is not found.
      *
      * @example
      * ```
-     *  const result = payments.agents.getAgentPlans(planId)
+     *  const result = payments.agents.getAgentPlans(agentId, { page: 1, offset: 10 })
      *  // {
      *  //  total: 10,
      *  //  page: 1,
@@ -193,8 +194,10 @@ export class AgentsAPI extends BasePaymentsAPI {
      *  // }
      * ```
      */
-    async getAgentPlans(agentId, pagination = new PaginationOptions()) {
-        const query = API_URL_GET_AGENT_PLANS.replace(':agentId', agentId) + '?' + pagination.asQueryParams();
+    async getAgentPlans(agentId, pagination = {}) {
+        const query = API_URL_GET_AGENT_PLANS.replace(':agentId', agentId) +
+            '?' +
+            new PaginationOptions(pagination).asQueryParams();
         const url = new URL(query, this.environment.backend);
         const response = await fetch(url, this.getPublicHTTPOptions('GET'));
         if (!response.ok) {

package/dist/api/agents-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"agents-api.js","sourceRoot":"","sources":["../../src/api/agents-api.ts"],"names":[],"mappings":"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","sourcesContent":["import { safeParseJson } from '../common/helper.js'\nimport { PaymentsError } from '../common/payments.error.js'\nimport {\n  AgentAPIAttributes,\n  AgentMetadata,\n  NvmAPIResult,\n  PaginationOptions,\n  PaymentOptions,\n  PlanCreditsConfig,\n  PlanMetadata,\n  PlanPriceConfig,\n} from '../common/types.js'\nimport { BasePaymentsAPI, PublicationOptions, resolvePublicationHeaders } from './base-payments.js'\nimport {\n  API_URL_ADD_PLAN_AGENT,\n  API_URL_GET_AGENT,\n  API_URL_GET_AGENTS,\n  API_URL_GET_AGENT_PLANS,\n  API_URL_REGISTER_AGENT,\n  API_URL_REGISTER_AGENTS_AND_PLAN,\n  API_URL_REMOVE_PLAN_AGENT,\n  API_URL_UPDATE_AGENT,\n} from './nvm-api.js'\n\nexport type { PublicationOptions } from './base-payments.js'\n\n/**\n * The AgentsAPI class provides methods to register and interact with AI Agents on Nevermined.\n */\nexport class AgentsAPI extends BasePaymentsAPI {\n  /**\n   * This method is used to create a singleton instance of the AgentsAPI class.\n   *\n   * @param options - The options to initialize the payments class.\n   * @returns The instance of the AgentsAPI class.\n   */\n  static getInstance(options: PaymentOptions): AgentsAPI {\n    return new AgentsAPI(options)\n  }\n\n  /**\n   *\n   * It registers a new AI Agent on Nevermined.\n   * The agent must be associated to one or multiple Payment Plans. Users that are subscribers of a payment plan can query the agent.\n   * Depending on the Payment Plan and the configuration of the agent, the usage of the agent/service will consume credits.\n   * When the plan expires (because the time is over or the credits are consumed), the user needs to renew the plan to continue using the agent.\n   *\n   * @remarks This method is oriented to AI Builders\n   * @remarks To call this method, the NVM API Key must have publication permissions\n   *\n   * @see https://nevermined.ai/docs/tutorials/builders/register-agent\n   *\n   * @param agentMetadata - @see {@link AgentMetadata}\n   * @param agentApi - @see {@link AgentAPIAttributes}\n   * @param paymentPlans - the list of payment plans giving access to the agent.\n   *\n   * @example\n   * ```\n   *  const agentMetadata = { name: 'My AI Payments Agent', tags: ['test'] }\n   *  const agentApi = { endpoints: [{ 'POST': 'https://example.com/api/v1/agents/:agentId/tasks' }] }\n   *  const paymentPlans = [planId]\n   *\n   *  const { agentId } = await payments.agents.registerAgent(agentMetadata, agentApi, paymentPlans)\n   * ```\n   *\n   * @returns The unique identifier of the newly created agent (Agent Id).\n   */\n  public async registerAgent(\n    agentMetadata: AgentMetadata,\n    agentApi: AgentAPIAttributes,\n    paymentPlans: string[],\n    publicationOptions?: PublicationOptions,\n  ): Promise<{ agentId: string }> {\n    const body = {\n      metadataAttributes: agentMetadata,\n      agentApiAttributes: agentApi,\n      plans: paymentPlans,\n    }\n\n    const options = this.getBackendHTTPOptions(\n      'POST',\n      body,\n      resolvePublicationHeaders(publicationOptions),\n    )\n    const url = new URL(API_URL_REGISTER_AGENT, this.environment.backend)\n\n    const response = await fetch(url, options)\n    if (!response.ok) {\n      throw PaymentsError.fromBackend('Unable to register agent', await safeParseJson(response))\n    }\n    const agentData = await response.json()\n    return { agentId: agentData.data.agentId }\n  }\n\n  /**\n   *\n   * It registers a new AI Agent and a Payment Plan associated to this new agent.\n   * Depending on the Payment Plan and the configuration of the agent, the usage of the agent/service will consume credits.\n   * When the plan expires (because the time is over or the credits are consumed), the user needs to renew the plan to continue using the agent.\n   *\n   * @remarks This method is oriented to AI Builders\n   * @remarks To call this method, the NVM API Key must have publication permissions\n   *\n   * @see https://nevermined.ai/docs/tutorials/builders/register-agent\n   *\n   * @param agentMetadata - @see {@link AgentMetadata}\n   * @param agentApi - @see {@link AgentAPIAttributes}\n   * @param planMetadata - @see {@link PlanMetadata}\n   * @param priceConfig - @see {@link PlanPriceConfig}\n   * @param creditsConfig - @see {@link PlanCreditsConfig}\n   *\n   * @example\n   * ```\n   *  const agentMetadata = { name: 'My AI Payments Agent', tags: ['test'] }\n   *  const agentApi { endpoints: [{ 'POST': 'https://example.com/api/v1/agents/:agentId/tasks' }] }\n   *  const cryptoPriceConfig = getNativeTokenPriceConfig(100n, builderAddress)\n   *  const 1dayDurationPlan = getExpirableDurationConfig(ONE_DAY_DURATION)\n   *  const { agentId, planId } = await payments.agents.registerAgentAndPlan(\n   *    agentMetadata,\n   *    agentApi,\n   *    cryptoPriceConfig,\n   *    1dayDurationPlan\n   *  )\n   * ```\n   *\n   * @returns The unique identifier of the newly created agent (agentId).\n   * @returns The unique identifier of the newly created plan (planId).\n   */\n  public async registerAgentAndPlan(\n    agentMetadata: AgentMetadata,\n    agentApi: AgentAPIAttributes,\n    planMetadata: PlanMetadata,\n    priceConfig: PlanPriceConfig,\n    creditsConfig: PlanCreditsConfig,\n    accessLimit?: 'credits' | 'time',\n    publicationOptions?: PublicationOptions,\n  ): Promise<{\n    agentId: string\n    planId: string\n    txHash: string\n  }> {\n    if (accessLimit && !['credits', 'time'].includes(accessLimit)) {\n      throw new PaymentsError(\n        'Invalid access limit',\n        'accessLimit must be either \"credits\" or \"time\"',\n      )\n    }\n    if (!accessLimit) {\n      accessLimit = creditsConfig.durationSecs > 0n ? 'time' : 'credits'\n    }\n    const body = {\n      plan: {\n        metadataAttributes: planMetadata,\n        priceConfig: priceConfig,\n        creditsConfig: creditsConfig,\n        accessLimit,\n      },\n      agent: {\n        metadataAttributes: agentMetadata,\n        agentApiAttributes: agentApi,\n      },\n    }\n    const options = this.getBackendHTTPOptions(\n      'POST',\n      body,\n      resolvePublicationHeaders(publicationOptions),\n    )\n    const url = new URL(API_URL_REGISTER_AGENTS_AND_PLAN, this.environment.backend)\n\n    const response = await fetch(url, options)\n    if (!response.ok) {\n      throw PaymentsError.fromBackend(\n        'Unable to register agent & plan',\n        await safeParseJson(response),\n      )\n    }\n    const result = await response.json()\n    return {\n      agentId: result.data.agentId,\n      planId: result.data.planId,\n      txHash: result.txHash,\n    }\n  }\n\n  /**\n   * Gets the metadata for a given Agent identifier.\n   *\n   * @param agentId - The unique identifier of the agent.\n   * @returns A promise that resolves to the agent's metadata.\n   * @throws PaymentsError if the agent is not found.\n   *\n   * @example\n   * ```\n   *  const plan = payments.agents.getAgent(agentId)\n   * ```\n   */\n  public async getAgent(agentId: string) {\n    const url = new URL(API_URL_GET_AGENT.replace(':agentId', agentId), this.environment.backend)\n    const response = await fetch(url, this.getPublicHTTPOptions('GET'))\n    if (!response.ok) {\n      throw PaymentsError.fromBackend('Agent not found', await safeParseJson(response))\n    }\n    return response.json()\n  }\n\n  /**\n   * Updates the metadata and API attributes of an existing AI Agent.\n   *\n   * @param agentId - The unique identifier of the agent.\n   * @param agentMetadata - The new metadata attributes for the agent.\n   * @param agentApi - The new API attributes for the agent.\n   * @returns  @see {@link NvmAPIResult} A promise that resolves indicating if the operation was successful.\n   * @throws PaymentsError if the agent is not found or if the update fails.\n   *\n   * @example\n   * ```\n   *  const agentMetadata = { name: 'My Updated Agent', tags: ['test'] }\n   *  const agentApi = { endpoints: [{ 'POST': 'https://nevermined.app/api/v1/agents/:agentId/tasks' }] }\n   *\n   *  await payments.agents.updateAgentMetadata(agentId, agentMetadata, agentApi)\n   * ```\n   */\n  public async updateAgentMetadata(\n    agentId: string,\n    agentMetadata: AgentMetadata,\n    agentApi: AgentAPIAttributes,\n  ): Promise<NvmAPIResult> {\n    const body = {\n      metadataAttributes: agentMetadata,\n      agentApiAttributes: agentApi,\n    }\n    const url = new URL(API_URL_UPDATE_AGENT.replace(':agentId', agentId), this.environment.backend)\n    const options = this.getBackendHTTPOptions('PUT', body)\n    const response = await fetch(url, options)\n    if (!response.ok) {\n      throw PaymentsError.fromBackend('Error updating agent', await safeParseJson(response))\n    }\n    return response.json()\n  }\n\n  /**\n   * Gets the list of plans that can be ordered to get access to an agent.\n   *\n   * @param agentId - The unique identifier of the agent.\n   * @param pagination - Optional pagination options to control the number of results returned.p\n   * @returns A promise that resolves to the list of all different plans giving access to the agent.\n   * @throws PaymentsError if the agent is not found.\n   *\n   * @example\n   * ```\n   *  const result = payments.agents.getAgentPlans(planId)\n   *  // {\n   *  //  total: 10,\n   *  //  page: 1,\n   *  //  offset: 5,\n   *  //  plans: [ ..]\n   *  // }\n   * ```\n   */\n  public async getAgentPlans(agentId: string, pagination = new PaginationOptions()) {\n    const query =\n      API_URL_GET_AGENT_PLANS.replace(':agentId', agentId) + '?' + pagination.asQueryParams()\n    const url = new URL(query, this.environment.backend)\n    const response = await fetch(url, this.getPublicHTTPOptions('GET'))\n    if (!response.ok) {\n      throw PaymentsError.fromBackend('Agent not found', await safeParseJson(response))\n    }\n    return response.json()\n  }\n\n  /**\n   * Lists the AI agents **you** published (the authenticated caller's own\n   * agents). This is account management, not a marketplace search — it never\n   * returns other users' agents.\n   *\n   * @param page - The page number to retrieve.\n   * @param offset - The number of items per page.\n   * @param sortBy - The field to sort the results by.\n   * @param sortOrder - The order in which to sort the results.\n   * @param orgId - Optional organization id. When set, returns every agent in\n   *   that organization (requires active membership) instead of the caller's.\n   * @returns A promise that resolves to the paginated list of your agents.\n   */\n  public async getAgents(\n    page = 1,\n    offset = 100,\n    sortBy = 'created',\n    sortOrder: 'asc' | 'desc' = 'desc',\n    orgId?: string,\n  ): Promise<{ total: number; page: number; offset: number; agents: any[] }> {\n    const url = new URL(API_URL_GET_AGENTS, this.environment.backend)\n    url.searchParams.set('page', page.toString())\n    url.searchParams.set('offset', offset.toString())\n    url.searchParams.set('sortBy', sortBy)\n    url.searchParams.set('sortOrder', sortOrder)\n    if (orgId) url.searchParams.set('orgId', orgId)\n    const response = await fetch(url, this.getBackendHTTPOptions('GET'))\n    if (!response.ok) {\n      throw PaymentsError.fromBackend('Unable to get agents', await safeParseJson(response))\n    }\n    return response.json()\n  }\n\n  /**\n   * Adds an existing Payment Plan to an AI Agent.\n   * After this operation, users with access to the Payment Plan will be able to access the AI Agent.\n   *\n   * @remarks\n   * Only the owner of the Payment Plan can call this method.\n   *\n   * @param planId - The unique identifier of the Payment Plan.\n   * @param agentId - The unique identifier of the AI Agent.\n   * @returns  @see {@link NvmAPIResult} A promise that resolves indicating if the operation was successful.\n   * @throws PaymentsError if unable to add the plan to the agent.\n   *\n   * @example\n   * ```\n   * const result = await payments.agents.addPlanToAgent(planId, agentId)\n   * // {\n   * //   txHash: '0x8d29d5769e832a35e53f80cd4e8890d941c50a09c33dbd975533debc894f2535',\n   * //   success: true\n   * // }\n   * ```\n   */\n  public async addPlanToAgent(planId: string, agentId: string): Promise<NvmAPIResult> {\n    const options = this.getBackendHTTPOptions('POST')\n    const endpoint = API_URL_ADD_PLAN_AGENT.replace(':planId', planId).replace(':agentId', agentId)\n    const url = new URL(endpoint, this.environment.backend)\n    const response = await fetch(url, options)\n    if (!response.ok) {\n      throw PaymentsError.fromBackend('Unable to add plan to agent', await safeParseJson(response))\n    }\n\n    return response.json()\n  }\n\n  /**\n   * Removes a Payment Plan from an AI Agent.\n   * After this operation, users with access to the Payment Plan will no longer be able to access the AI Agent.\n   *\n   * @remarks\n   * Only the owner of the Payment Plan can call this method.\n   *\n   * @param planId - The unique identifier of the Payment Plan.\n   * @param agentId - The unique identifier of the AI Agent.\n   * @returns  @see {@link NvmAPIResult} A promise that resolves indicating if the operation was successful.\n   * @throws PaymentsError if unable to remove the plan from the agent.\n   *\n   * @example\n   * ```\n   * const result = await payments.agents.removePlanFromAgent(planId, agentId)\n   * // {\n   * //   txHash: '0x8d29d5769e832a35e53f80cd4e8890d941c50a09c33dbd975533debc894f2535',\n   * //   success: true\n   * // }\n   * ```\n   */\n  public async removePlanFromAgent(planId: string, agentId: string): Promise<NvmAPIResult> {\n    const options = this.getBackendHTTPOptions('DELETE')\n    const endpoint = API_URL_REMOVE_PLAN_AGENT.replace(':planId', planId).replace(\n      ':agentId',\n      agentId,\n    )\n    const url = new URL(endpoint, this.environment.backend)\n    const response = await fetch(url, options)\n    if (!response.ok) {\n      throw PaymentsError.fromBackend(\n        'Unable to remove plan from agent',\n        await safeParseJson(response),\n      )\n    }\n\n    return response.json()\n  }\n}\n"]}
+{"version":3,"file":"agents-api.js","sourceRoot":"","sources":["../../src/api/agents-api.ts"],"names":[],"mappings":"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","sourcesContent":["import { safeParseJson } from '../common/helper.js'\nimport { PaymentsError } from '../common/payments.error.js'\nimport {\n  AgentAPIAttributes,\n  AgentMetadata,\n  NvmAPIResult,\n  PaginationOptions,\n  PaymentOptions,\n  PlanCreditsConfig,\n  PlanMetadata,\n  PlanPriceConfig,\n} from '../common/types.js'\nimport { BasePaymentsAPI, PublicationOptions, resolvePublicationHeaders } from './base-payments.js'\nimport {\n  API_URL_ADD_PLAN_AGENT,\n  API_URL_GET_AGENT,\n  API_URL_GET_AGENTS,\n  API_URL_GET_AGENT_PLANS,\n  API_URL_REGISTER_AGENT,\n  API_URL_REGISTER_AGENTS_AND_PLAN,\n  API_URL_REMOVE_PLAN_AGENT,\n  API_URL_UPDATE_AGENT,\n} from './nvm-api.js'\n\nexport type { PublicationOptions } from './base-payments.js'\n\n/**\n * The AgentsAPI class provides methods to register and interact with AI Agents on Nevermined.\n */\nexport class AgentsAPI extends BasePaymentsAPI {\n  /**\n   * This method is used to create a singleton instance of the AgentsAPI class.\n   *\n   * @param options - The options to initialize the payments class.\n   * @returns The instance of the AgentsAPI class.\n   */\n  static getInstance(options: PaymentOptions): AgentsAPI {\n    return new AgentsAPI(options)\n  }\n\n  /**\n   *\n   * It registers a new AI Agent on Nevermined.\n   * The agent must be associated to one or multiple Payment Plans. Users that are subscribers of a payment plan can query the agent.\n   * Depending on the Payment Plan and the configuration of the agent, the usage of the agent/service will consume credits.\n   * When the plan expires (because the time is over or the credits are consumed), the user needs to renew the plan to continue using the agent.\n   *\n   * @remarks This method is oriented to AI Builders\n   * @remarks To call this method, the NVM API Key must have publication permissions\n   *\n   * @see https://nevermined.ai/docs/tutorials/builders/register-agent\n   *\n   * @param agentMetadata - @see {@link AgentMetadata}\n   * @param agentApi - @see {@link AgentAPIAttributes}\n   * @param paymentPlans - the list of payment plans giving access to the agent.\n   *\n   * @example\n   * ```\n   *  const agentMetadata = { name: 'My AI Payments Agent', tags: ['test'] }\n   *  const agentApi = { endpoints: [{ 'POST': 'https://example.com/api/v1/agents/:agentId/tasks' }] }\n   *  const paymentPlans = [planId]\n   *\n   *  const { agentId } = await payments.agents.registerAgent(agentMetadata, agentApi, paymentPlans)\n   * ```\n   *\n   * @returns The unique identifier of the newly created agent (Agent Id).\n   */\n  public async registerAgent(\n    agentMetadata: AgentMetadata,\n    agentApi: AgentAPIAttributes,\n    paymentPlans: string[],\n    publicationOptions?: PublicationOptions,\n  ): Promise<{ agentId: string }> {\n    const body = {\n      metadataAttributes: agentMetadata,\n      agentApiAttributes: agentApi,\n      plans: paymentPlans,\n    }\n\n    const options = this.getBackendHTTPOptions(\n      'POST',\n      body,\n      resolvePublicationHeaders(publicationOptions),\n    )\n    const url = new URL(API_URL_REGISTER_AGENT, this.environment.backend)\n\n    const response = await fetch(url, options)\n    if (!response.ok) {\n      throw PaymentsError.fromBackend('Unable to register agent', await safeParseJson(response))\n    }\n    const agentData = await response.json()\n    return { agentId: agentData.data.agentId }\n  }\n\n  /**\n   *\n   * It registers a new AI Agent and a Payment Plan associated to this new agent.\n   * Depending on the Payment Plan and the configuration of the agent, the usage of the agent/service will consume credits.\n   * When the plan expires (because the time is over or the credits are consumed), the user needs to renew the plan to continue using the agent.\n   *\n   * @remarks This method is oriented to AI Builders\n   * @remarks To call this method, the NVM API Key must have publication permissions\n   *\n   * @see https://nevermined.ai/docs/tutorials/builders/register-agent\n   *\n   * @param agentMetadata - @see {@link AgentMetadata}\n   * @param agentApi - @see {@link AgentAPIAttributes}\n   * @param planMetadata - @see {@link PlanMetadata}\n   * @param priceConfig - @see {@link PlanPriceConfig}\n   * @param creditsConfig - @see {@link PlanCreditsConfig}\n   *\n   * @example\n   * ```\n   *  const agentMetadata = { name: 'My AI Payments Agent', tags: ['test'] }\n   *  const agentApi { endpoints: [{ 'POST': 'https://example.com/api/v1/agents/:agentId/tasks' }] }\n   *  const cryptoPriceConfig = getNativeTokenPriceConfig(100n, builderAddress)\n   *  const 1dayDurationPlan = getExpirableDurationConfig(ONE_DAY_DURATION)\n   *  const { agentId, planId } = await payments.agents.registerAgentAndPlan(\n   *    agentMetadata,\n   *    agentApi,\n   *    cryptoPriceConfig,\n   *    1dayDurationPlan\n   *  )\n   * ```\n   *\n   * @returns The unique identifier of the newly created agent (agentId).\n   * @returns The unique identifier of the newly created plan (planId).\n   */\n  public async registerAgentAndPlan(\n    agentMetadata: AgentMetadata,\n    agentApi: AgentAPIAttributes,\n    planMetadata: PlanMetadata,\n    priceConfig: PlanPriceConfig,\n    creditsConfig: PlanCreditsConfig,\n    accessLimit?: 'credits' | 'time',\n    publicationOptions?: PublicationOptions,\n  ): Promise<{\n    agentId: string\n    planId: string\n    txHash: string\n  }> {\n    if (accessLimit && !['credits', 'time'].includes(accessLimit)) {\n      throw new PaymentsError(\n        'Invalid access limit',\n        'accessLimit must be either \"credits\" or \"time\"',\n      )\n    }\n    if (!accessLimit) {\n      accessLimit = creditsConfig.durationSecs > 0n ? 'time' : 'credits'\n    }\n    const body = {\n      plan: {\n        metadataAttributes: planMetadata,\n        priceConfig: priceConfig,\n        creditsConfig: creditsConfig,\n        accessLimit,\n      },\n      agent: {\n        metadataAttributes: agentMetadata,\n        agentApiAttributes: agentApi,\n      },\n    }\n    const options = this.getBackendHTTPOptions(\n      'POST',\n      body,\n      resolvePublicationHeaders(publicationOptions),\n    )\n    const url = new URL(API_URL_REGISTER_AGENTS_AND_PLAN, this.environment.backend)\n\n    const response = await fetch(url, options)\n    if (!response.ok) {\n      throw PaymentsError.fromBackend(\n        'Unable to register agent & plan',\n        await safeParseJson(response),\n      )\n    }\n    const result = await response.json()\n    return {\n      agentId: result.data.agentId,\n      planId: result.data.planId,\n      txHash: result.txHash,\n    }\n  }\n\n  /**\n   * Gets the metadata for a given Agent identifier.\n   *\n   * @param agentId - The unique identifier of the agent.\n   * @returns A promise that resolves to the agent's metadata.\n   * @throws PaymentsError if the agent is not found.\n   *\n   * @example\n   * ```\n   *  const plan = payments.agents.getAgent(agentId)\n   * ```\n   */\n  public async getAgent(agentId: string) {\n    const url = new URL(API_URL_GET_AGENT.replace(':agentId', agentId), this.environment.backend)\n    const response = await fetch(url, this.getPublicHTTPOptions('GET'))\n    if (!response.ok) {\n      throw PaymentsError.fromBackend('Agent not found', await safeParseJson(response))\n    }\n    return response.json()\n  }\n\n  /**\n   * Updates the metadata and API attributes of an existing AI Agent.\n   *\n   * @param agentId - The unique identifier of the agent.\n   * @param agentMetadata - The new metadata attributes for the agent.\n   * @param agentApi - The new API attributes for the agent.\n   * @returns  @see {@link NvmAPIResult} A promise that resolves indicating if the operation was successful.\n   * @throws PaymentsError if the agent is not found or if the update fails.\n   *\n   * @example\n   * ```\n   *  const agentMetadata = { name: 'My Updated Agent', tags: ['test'] }\n   *  const agentApi = { endpoints: [{ 'POST': 'https://nevermined.app/api/v1/agents/:agentId/tasks' }] }\n   *\n   *  await payments.agents.updateAgentMetadata(agentId, agentMetadata, agentApi)\n   * ```\n   */\n  public async updateAgentMetadata(\n    agentId: string,\n    agentMetadata: AgentMetadata,\n    agentApi: AgentAPIAttributes,\n  ): Promise<NvmAPIResult> {\n    const body = {\n      metadataAttributes: agentMetadata,\n      agentApiAttributes: agentApi,\n    }\n    const url = new URL(API_URL_UPDATE_AGENT.replace(':agentId', agentId), this.environment.backend)\n    const options = this.getBackendHTTPOptions('PUT', body)\n    const response = await fetch(url, options)\n    if (!response.ok) {\n      throw PaymentsError.fromBackend('Error updating agent', await safeParseJson(response))\n    }\n    return response.json()\n  }\n\n  /**\n   * Gets the list of plans that can be ordered to get access to an agent.\n   *\n   * @param agentId - The unique identifier of the agent.\n   * @param pagination - Optional pagination options. Accepts a plain object\n   * (`{ page, offset, sortBy, sortOrder }`) or a `PaginationOptions` instance.\n   * @returns A promise that resolves to the list of all different plans giving access to the agent.\n   * @throws PaymentsError if the agent is not found.\n   *\n   * @example\n   * ```\n   *  const result = payments.agents.getAgentPlans(agentId, { page: 1, offset: 10 })\n   *  // {\n   *  //  total: 10,\n   *  //  page: 1,\n   *  //  offset: 5,\n   *  //  plans: [ ..]\n   *  // }\n   * ```\n   */\n  public async getAgentPlans(agentId: string, pagination: Partial<PaginationOptions> = {}) {\n    const query =\n      API_URL_GET_AGENT_PLANS.replace(':agentId', agentId) +\n      '?' +\n      new PaginationOptions(pagination).asQueryParams()\n    const url = new URL(query, this.environment.backend)\n    const response = await fetch(url, this.getPublicHTTPOptions('GET'))\n    if (!response.ok) {\n      throw PaymentsError.fromBackend('Agent not found', await safeParseJson(response))\n    }\n    return response.json()\n  }\n\n  /**\n   * Lists the AI agents **you** published (the authenticated caller's own\n   * agents). This is account management, not a marketplace search — it never\n   * returns other users' agents.\n   *\n   * @param page - The page number to retrieve.\n   * @param offset - The number of items per page.\n   * @param sortBy - The field to sort the results by.\n   * @param sortOrder - The order in which to sort the results.\n   * @param orgId - Optional organization id. When set, returns every agent in\n   *   that organization (requires active membership) instead of the caller's.\n   * @returns A promise that resolves to the paginated list of your agents.\n   */\n  public async getAgents(\n    page = 1,\n    offset = 100,\n    sortBy = 'created',\n    sortOrder: 'asc' | 'desc' = 'desc',\n    orgId?: string,\n  ): Promise<{ total: number; page: number; offset: number; agents: any[] }> {\n    const url = new URL(API_URL_GET_AGENTS, this.environment.backend)\n    url.searchParams.set('page', page.toString())\n    url.searchParams.set('offset', offset.toString())\n    url.searchParams.set('sortBy', sortBy)\n    url.searchParams.set('sortOrder', sortOrder)\n    if (orgId) url.searchParams.set('orgId', orgId)\n    const response = await fetch(url, this.getBackendHTTPOptions('GET'))\n    if (!response.ok) {\n      throw PaymentsError.fromBackend('Unable to get agents', await safeParseJson(response))\n    }\n    return response.json()\n  }\n\n  /**\n   * Adds an existing Payment Plan to an AI Agent.\n   * After this operation, users with access to the Payment Plan will be able to access the AI Agent.\n   *\n   * @remarks\n   * Only the owner of the Payment Plan can call this method.\n   *\n   * @param planId - The unique identifier of the Payment Plan.\n   * @param agentId - The unique identifier of the AI Agent.\n   * @returns  @see {@link NvmAPIResult} A promise that resolves indicating if the operation was successful.\n   * @throws PaymentsError if unable to add the plan to the agent.\n   *\n   * @example\n   * ```\n   * const result = await payments.agents.addPlanToAgent(planId, agentId)\n   * // {\n   * //   txHash: '0x8d29d5769e832a35e53f80cd4e8890d941c50a09c33dbd975533debc894f2535',\n   * //   success: true\n   * // }\n   * ```\n   */\n  public async addPlanToAgent(planId: string, agentId: string): Promise<NvmAPIResult> {\n    const options = this.getBackendHTTPOptions('POST')\n    const endpoint = API_URL_ADD_PLAN_AGENT.replace(':planId', planId).replace(':agentId', agentId)\n    const url = new URL(endpoint, this.environment.backend)\n    const response = await fetch(url, options)\n    if (!response.ok) {\n      throw PaymentsError.fromBackend('Unable to add plan to agent', await safeParseJson(response))\n    }\n\n    return response.json()\n  }\n\n  /**\n   * Removes a Payment Plan from an AI Agent.\n   * After this operation, users with access to the Payment Plan will no longer be able to access the AI Agent.\n   *\n   * @remarks\n   * Only the owner of the Payment Plan can call this method.\n   *\n   * @param planId - The unique identifier of the Payment Plan.\n   * @param agentId - The unique identifier of the AI Agent.\n   * @returns  @see {@link NvmAPIResult} A promise that resolves indicating if the operation was successful.\n   * @throws PaymentsError if unable to remove the plan from the agent.\n   *\n   * @example\n   * ```\n   * const result = await payments.agents.removePlanFromAgent(planId, agentId)\n   * // {\n   * //   txHash: '0x8d29d5769e832a35e53f80cd4e8890d941c50a09c33dbd975533debc894f2535',\n   * //   success: true\n   * // }\n   * ```\n   */\n  public async removePlanFromAgent(planId: string, agentId: string): Promise<NvmAPIResult> {\n    const options = this.getBackendHTTPOptions('DELETE')\n    const endpoint = API_URL_REMOVE_PLAN_AGENT.replace(':planId', planId).replace(\n      ':agentId',\n      agentId,\n    )\n    const url = new URL(endpoint, this.environment.backend)\n    const response = await fetch(url, options)\n    if (!response.ok) {\n      throw PaymentsError.fromBackend(\n        'Unable to remove plan from agent',\n        await safeParseJson(response),\n      )\n    }\n\n    return response.json()\n  }\n}\n"]}

package/dist/api/base-payments.d.ts

@@ -56,8 +56,13 @@ export declare abstract class BasePaymentsAPI {
      * (`<prefix>:<jwt>`); the key wins whenever its prefix is recognized. The
      * deprecated `environment` option is still honored as a fallback when the
      * key has no recognized prefix (e.g. local/custom dev), and ultimately
-     * defaults to `custom`. Passing `environment` emits a one-time deprecation
-     * warning.
+     * defaults to `custom`.
+     *
+     * The deprecation warning fires only when a passed `environment` is actually
+     * overridden by the key prefix (i.e. silently ignored). When it matches the
+     * derived environment, or is the fallback that's actually used, it's harmless
+     * — documented snippets still pass a matching `environment`, so nagging every
+     * new integration would be pure noise (#431).
      */
     private resolveEnvironmentName;
     /**

package/dist/api/base-payments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-payments.d.ts","sourceRoot":"","sources":["../../src/api/base-payments.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClE,OAAO,EACL,eAAe,EACf,eAAe,EAGhB,MAAM,oBAAoB,CAAA;AAM3B;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAA;AAUvD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,CAAC,EAAE,kBAAkB,GAC3B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAKpC;AAED;;;GAGG;AACH,8BAAsB,eAAe;IACnC,SAAS,CAAC,SAAS,EAAE,MAAM,CAAA;IAC3B,SAAS,CAAC,MAAM,EAAE,aAAa,CAAA;IAC/B,SAAS,CAAC,WAAW,EAAE,eAAe,CAAA;IACtC,SAAS,CAAC,eAAe,EAAE,eAAe,CAAA;IAC1C,SAAS,CAAC,SAAS,EAAE,MAAM,CAAA;IAC3B,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACxB;;;;OAIG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IAC1B,SAAS,CAAC,cAAc,EAAE,MAAM,CAAA;IAChC,SAAS,CAAC,cAAc,EAAE,MAAM,CAAA;IAChC,SAAS,CAAC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,iBAAiB,UAAO;gBAEnB,OAAO,EAAE,cAAc;IAmCnC;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAkB9B;;;OAGG;IACH,SAAS,CAAC,cAAc,IAAI;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE;IAc9E;;;OAGG;IACI,kBAAkB,IAAI,eAAe;IAI5C;;;OAGG;IACI,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAI9C;;;;;;OAMG;IACI,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAIzC;;;;;;;OAOG;IACI,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI7D;;;;;;;;;OASG;IACH,SAAS,CAAC,qBAAqB,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,GAAG,EACV,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IA4BvC;;;;;;;;OAQG;IACH,SAAS,CAAC,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG;gBAE7C,MAAM;iBACL,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;eACxB,MAAM;;CAgBlB"}
+{"version":3,"file":"base-payments.d.ts","sourceRoot":"","sources":["../../src/api/base-payments.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClE,OAAO,EACL,eAAe,EACf,eAAe,EAGhB,MAAM,oBAAoB,CAAA;AAM3B;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAA;AAUvD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,CAAC,EAAE,kBAAkB,GAC3B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAKpC;AAED;;;GAGG;AACH,8BAAsB,eAAe;IACnC,SAAS,CAAC,SAAS,EAAE,MAAM,CAAA;IAC3B,SAAS,CAAC,MAAM,EAAE,aAAa,CAAA;IAC/B,SAAS,CAAC,WAAW,EAAE,eAAe,CAAA;IACtC,SAAS,CAAC,eAAe,EAAE,eAAe,CAAA;IAC1C,SAAS,CAAC,SAAS,EAAE,MAAM,CAAA;IAC3B,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACxB;;;;OAIG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IAC1B,SAAS,CAAC,cAAc,EAAE,MAAM,CAAA;IAChC,SAAS,CAAC,cAAc,EAAE,MAAM,CAAA;IAChC,SAAS,CAAC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,iBAAiB,UAAO;gBAEnB,OAAO,EAAE,cAAc;IAmCnC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,sBAAsB;IAqB9B;;;OAGG;IACH,SAAS,CAAC,cAAc,IAAI;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE;IAc9E;;;OAGG;IACI,kBAAkB,IAAI,eAAe;IAI5C;;;OAGG;IACI,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAI9C;;;;;;OAMG;IACI,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAIzC;;;;;;;OAOG;IACI,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI7D;;;;;;;;;OASG;IACH,SAAS,CAAC,qBAAqB,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,GAAG,EACV,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IA4BvC;;;;;;;;OAQG;IACH,SAAS,CAAC,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG;gBAE7C,MAAM;iBACL,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;eACxB,MAAM;;CAgBlB"}

package/dist/api/base-payments.js

@@ -73,20 +73,27 @@ export class BasePaymentsAPI {
      * (`<prefix>:<jwt>`); the key wins whenever its prefix is recognized. The
      * deprecated `environment` option is still honored as a fallback when the
      * key has no recognized prefix (e.g. local/custom dev), and ultimately
-     * defaults to `custom`. Passing `environment` emits a one-time deprecation
-     * warning.
+     * defaults to `custom`.
+     *
+     * The deprecation warning fires only when a passed `environment` is actually
+     * overridden by the key prefix (i.e. silently ignored). When it matches the
+     * derived environment, or is the fallback that's actually used, it's harmless
+     * — documented snippets still pass a matching `environment`, so nagging every
+     * new integration would be pure noise (#431).
      */
     resolveEnvironmentName(options) {
         const fromKey = getEnvironmentFromApiKey(options.nvmApiKey);
-        if (options.environment && !environmentOptionDeprecationWarned) {
+        const resolved = fromKey ?? options.environment ?? 'custom';
+        if (options.environment &&
+            options.environment !== resolved &&
+            !environmentOptionDeprecationWarned) {
             environmentOptionDeprecationWarned = true;
-            const override = fromKey && fromKey !== options.environment
-                ? ` It is ignored in favor of the environment derived from the API key ('${fromKey}').`
-                : '';
             console.warn("[DEPRECATED] The 'environment' option is deprecated; the environment is now derived " +
-                `from the NVM API key prefix.${override} Remove the 'environment' option to silence this warning.`);
+                `from the NVM API key prefix. Your value ('${options.environment}') is ignored in favor of ` +
+                `the environment derived from the API key ('${resolved}'). Remove the 'environment' option ` +
+                'to silence this warning.');
         }
-        return fromKey ?? options.environment ?? 'custom';
+        return resolved;
     }
     /**
      * Parses the NVM API Key to extract the account address.

package/dist/api/base-payments.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-payments.js","sourceRoot":"","sources":["../../src/api/base-payments.ts"],"names":[],"mappings":"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","sourcesContent":["import { decodeJwt } from 'jose'\nimport { API_VERSION_HEADER, LOCKED_API_VERSION } from '../common/api-version.js'\nimport { jsonReplacer } from '../common/helper.js'\nimport { PaymentsError } from '../common/payments.error.js'\nimport { PaymentOptions, PaymentScheme } from '../common/types.js'\nimport {\n  EnvironmentInfo,\n  EnvironmentName,\n  Environments,\n  getEnvironmentFromApiKey,\n} from '../environments.js'\n\n// Emit the `environment` deprecation notice at most once per process to avoid\n// log spam when many sub-API instances are constructed from the same options.\nlet environmentOptionDeprecationWarned = false\n\n/**\n * Header used by the Nevermined backend to resolve the active organization\n * context for an authenticated request. Resolution priority is:\n * path `:orgId` &gt; this header &gt; API-key tag &gt; fallback membership &gt; personal.\n * See `apps/api/src/common/guards/current-org-context.guard.ts` in nvm-monorepo.\n */\nexport const CURRENT_ORG_ID_HEADER = 'X-Current-Org-Id'\n\n/**\n * Set of header names that callers can pass to `getBackendHTTPOptions` via\n * `extraHeaders`. Anything outside this set is dropped silently so a stray\n * `Authorization` or `Content-Type` override can't clobber the SDK's\n * transport security headers.\n */\nconst ALLOWED_EXTRA_HEADERS = new Set<string>([CURRENT_ORG_ID_HEADER])\n\n/**\n * Options accepted by publication methods (`registerAgent`,\n * `registerAgentAndPlan`, `registerPlan`, …) that want to override the\n * active organization workspace for a single call.\n */\nexport type PublicationOptions = {\n  /**\n   * Organization id (e.g. `org-…`) to publish into. When set, the SDK\n   * sends an `X-Current-Org-Id` header for this call only — the caller's\n   * instance-level pin (set via `Payments.setOrganizationId`) is not\n   * affected.\n   */\n  organizationId?: string\n}\n\n/**\n * Builds the `extraHeaders` argument for `getBackendHTTPOptions` from\n * publication options. Returns `undefined` when no override is requested\n * so existing callers receive identical request shapes.\n */\nexport function resolvePublicationHeaders(\n  options?: PublicationOptions,\n): Record<string, string> | undefined {\n  if (options?.organizationId) {\n    return { [CURRENT_ORG_ID_HEADER]: options.organizationId }\n  }\n  return undefined\n}\n\n/**\n * Base class extended by all Payments API classes.\n * It provides common functionality such as parsing the NVM API Key and getting the account address.\n */\nexport abstract class BasePaymentsAPI {\n  protected nvmApiKey: string\n  protected scheme: PaymentScheme\n  protected environment: EnvironmentInfo\n  protected environmentName: EnvironmentName\n  protected returnUrl: string\n  protected appId?: string\n  /**\n   * Backend API version (MAJOR.MINOR) pinned by this instance, set from\n   * `options.version`. When unset, every request defaults to\n   * {@link LOCKED_API_VERSION}.\n   */\n  protected version?: string\n  protected accountAddress: string\n  protected heliconeApiKey: string\n  protected currentOrganizationId: string | null\n  public isBrowserInstance = true\n\n  constructor(options: PaymentOptions) {\n    // Type-level narrowing of PaymentScheme to 'nvm' won't protect callers\n    // pinned to an older .d.ts that still has 'visa' in the union — they\n    // would silently fall through to the standard pipeline and hit a\n    // misleading 'Invalid NVM API Key' from parseNvmApiKey when the\n    // legacy Visa path tolerated a non-JWT key. Reject up front with a\n    // clear migration message.\n    if (options.scheme && options.scheme !== 'nvm') {\n      throw new PaymentsError(\n        `scheme '${options.scheme}' is no longer supported. Visa is now exposed as provider:'visa' on createDelegation; construct Payments without a scheme override.`,\n      )\n    }\n    this.nvmApiKey = options.nvmApiKey\n    this.scheme = options.scheme || 'nvm'\n    this.returnUrl = options.returnUrl || ''\n    this.environmentName = this.resolveEnvironmentName(options)\n    this.environment = Environments[this.environmentName]\n    this.appId = options.appId\n    // `version` is the backend API pin (MAJOR.MINOR) sent verbatim as\n    // Nevermined-Version. Fail fast on a malformed value rather than shipping\n    // an invalid header (e.g. an SDK package version '1.0.0', 'v1.1', or '')\n    // that the backend rejects with 400 on every call.\n    if (options.version !== undefined && !/^\\d+\\.\\d+$/.test(options.version)) {\n      throw new PaymentsError(\n        `Invalid 'version' option '${options.version}': expected a backend API version as MAJOR.MINOR (e.g. '1.1'). Omit it to use the SDK's default pin.`,\n      )\n    }\n    this.version = options.version\n    this.currentOrganizationId = options.organizationId ?? null\n\n    const { accountAddress, heliconeApiKey } = this.parseNvmApiKey()\n    this.accountAddress = accountAddress\n    this.heliconeApiKey = heliconeApiKey\n  }\n\n  /**\n   * Resolves the active environment for this instance.\n   *\n   * The environment is derived from the NVM API key prefix\n   * (`<prefix>:<jwt>`); the key wins whenever its prefix is recognized. The\n   * deprecated `environment` option is still honored as a fallback when the\n   * key has no recognized prefix (e.g. local/custom dev), and ultimately\n   * defaults to `custom`. Passing `environment` emits a one-time deprecation\n   * warning.\n   */\n  private resolveEnvironmentName(options: PaymentOptions): EnvironmentName {\n    const fromKey = getEnvironmentFromApiKey(options.nvmApiKey)\n\n    if (options.environment && !environmentOptionDeprecationWarned) {\n      environmentOptionDeprecationWarned = true\n      const override =\n        fromKey && fromKey !== options.environment\n          ? ` It is ignored in favor of the environment derived from the API key ('${fromKey}').`\n          : ''\n      console.warn(\n        \"[DEPRECATED] The 'environment' option is deprecated; the environment is now derived \" +\n          `from the NVM API key prefix.${override} Remove the 'environment' option to silence this warning.`,\n      )\n    }\n\n    return fromKey ?? options.environment ?? 'custom'\n  }\n\n  /**\n   * Parses the NVM API Key to extract the account address.\n   * @throws PaymentsError if the API key is invalid.\n   */\n  protected parseNvmApiKey(): { accountAddress: string; heliconeApiKey: string } {\n    try {\n      if (!this.nvmApiKey) {\n        throw new PaymentsError('NVM API Key is required')\n      }\n      const jwt = decodeJwt(this.nvmApiKey)\n      const accountAddress = jwt.sub as string\n      const heliconeApiKey = jwt.o11y as string\n      return { accountAddress, heliconeApiKey }\n    } catch (error) {\n      throw new PaymentsError('Invalid NVM API Key')\n    }\n  }\n\n  /**\n   * Returns the environment name used to initialize the Payments instance.\n   * @returns The environment name (e.g. 'sandbox', 'live')\n   */\n  public getEnvironmentName(): EnvironmentName {\n    return this.environmentName\n  }\n\n  /**\n   * It returns the account address associated with the NVM API Key used to initialize the Payments Library instance.\n   * @returns The account address extracted from the NVM API Key\n   */\n  public getAccountAddress(): string | undefined {\n    return this.accountAddress\n  }\n\n  /**\n   * Returns the current organization context applied to every authenticated\n   * backend request via the `X-Current-Org-Id` header.\n   *\n   * `null` means \"no pinned workspace\" — the backend falls back to the\n   * caller's API-key tag or most-recent active membership.\n   */\n  public getOrganizationId(): string | null {\n    return this.currentOrganizationId\n  }\n\n  /**\n   * Sets the organization context applied to every subsequent authenticated\n   * backend request via the `X-Current-Org-Id` header.\n   *\n   * Pass `null` to clear the pin and fall back to the backend default.\n   *\n   * @param organizationId - Org ID (e.g. `org-…`) or `null` to clear.\n   */\n  public setOrganizationId(organizationId: string | null): void {\n    this.currentOrganizationId = organizationId\n  }\n\n  /**\n   * Returns the HTTP options required to query the backend.\n   * @param method - HTTP method.\n   * @param body - Optional request body.\n   * @param extraHeaders - Optional per-call header overrides. Use\n   *   `{ 'X-Current-Org-Id': orgId }` to target a specific workspace for\n   *   one call without mutating the instance-level pin.\n   * @returns HTTP options object.\n   * @internal\n   */\n  protected getBackendHTTPOptions(\n    method: string,\n    body?: any,\n    extraHeaders?: Record<string, string>,\n  ) {\n    const headers: Record<string, string> = {\n      Accept: 'application/json',\n      'Content-Type': 'application/json',\n      Authorization: `Bearer ${this.nvmApiKey}`,\n      [API_VERSION_HEADER]: this.version ?? LOCKED_API_VERSION,\n    }\n    if (this.currentOrganizationId) {\n      headers[CURRENT_ORG_ID_HEADER] = this.currentOrganizationId\n    }\n    if (extraHeaders) {\n      // Allowlist callers' header overrides so a passed-in `Authorization`\n      // or `Content-Type` can't clobber the SDK's transport security\n      // headers. Today only `X-Current-Org-Id` is allowed through.\n      for (const [name, value] of Object.entries(extraHeaders)) {\n        if (ALLOWED_EXTRA_HEADERS.has(name)) {\n          headers[name] = value\n        }\n      }\n    }\n    return {\n      method,\n      headers,\n      ...(body && { body: JSON.stringify(body, jsonReplacer) }),\n    }\n  }\n\n  /**\n   * Get HTTP options for public backend requests (no authorization header).\n   * Converts body keys from snake_case to camelCase for consistency.\n   *\n   * @param method - HTTP method\n   * @param body - Optional request body (keys will be converted to camelCase)\n   * @returns HTTP options object\n   * @internal\n   */\n  protected getPublicHTTPOptions(method: string, body?: any) {\n    const options: {\n      method: string\n      headers: Record<string, string>\n      body?: string\n    } = {\n      method,\n      headers: {\n        Accept: 'application/json',\n        'Content-Type': 'application/json',\n        [API_VERSION_HEADER]: this.version ?? LOCKED_API_VERSION,\n      },\n    }\n\n    if (body) {\n      options.body = JSON.stringify(body, jsonReplacer)\n    }\n\n    return options\n  }\n}\n"]}
+{"version":3,"file":"base-payments.js","sourceRoot":"","sources":["../../src/api/base-payments.ts"],"names":[],"mappings":"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","sourcesContent":["import { decodeJwt } from 'jose'\nimport { API_VERSION_HEADER, LOCKED_API_VERSION } from '../common/api-version.js'\nimport { jsonReplacer } from '../common/helper.js'\nimport { PaymentsError } from '../common/payments.error.js'\nimport { PaymentOptions, PaymentScheme } from '../common/types.js'\nimport {\n  EnvironmentInfo,\n  EnvironmentName,\n  Environments,\n  getEnvironmentFromApiKey,\n} from '../environments.js'\n\n// Emit the `environment` deprecation notice at most once per process to avoid\n// log spam when many sub-API instances are constructed from the same options.\nlet environmentOptionDeprecationWarned = false\n\n/**\n * Header used by the Nevermined backend to resolve the active organization\n * context for an authenticated request. Resolution priority is:\n * path `:orgId` &gt; this header &gt; API-key tag &gt; fallback membership &gt; personal.\n * See `apps/api/src/common/guards/current-org-context.guard.ts` in nvm-monorepo.\n */\nexport const CURRENT_ORG_ID_HEADER = 'X-Current-Org-Id'\n\n/**\n * Set of header names that callers can pass to `getBackendHTTPOptions` via\n * `extraHeaders`. Anything outside this set is dropped silently so a stray\n * `Authorization` or `Content-Type` override can't clobber the SDK's\n * transport security headers.\n */\nconst ALLOWED_EXTRA_HEADERS = new Set<string>([CURRENT_ORG_ID_HEADER])\n\n/**\n * Options accepted by publication methods (`registerAgent`,\n * `registerAgentAndPlan`, `registerPlan`, …) that want to override the\n * active organization workspace for a single call.\n */\nexport type PublicationOptions = {\n  /**\n   * Organization id (e.g. `org-…`) to publish into. When set, the SDK\n   * sends an `X-Current-Org-Id` header for this call only — the caller's\n   * instance-level pin (set via `Payments.setOrganizationId`) is not\n   * affected.\n   */\n  organizationId?: string\n}\n\n/**\n * Builds the `extraHeaders` argument for `getBackendHTTPOptions` from\n * publication options. Returns `undefined` when no override is requested\n * so existing callers receive identical request shapes.\n */\nexport function resolvePublicationHeaders(\n  options?: PublicationOptions,\n): Record<string, string> | undefined {\n  if (options?.organizationId) {\n    return { [CURRENT_ORG_ID_HEADER]: options.organizationId }\n  }\n  return undefined\n}\n\n/**\n * Base class extended by all Payments API classes.\n * It provides common functionality such as parsing the NVM API Key and getting the account address.\n */\nexport abstract class BasePaymentsAPI {\n  protected nvmApiKey: string\n  protected scheme: PaymentScheme\n  protected environment: EnvironmentInfo\n  protected environmentName: EnvironmentName\n  protected returnUrl: string\n  protected appId?: string\n  /**\n   * Backend API version (MAJOR.MINOR) pinned by this instance, set from\n   * `options.version`. When unset, every request defaults to\n   * {@link LOCKED_API_VERSION}.\n   */\n  protected version?: string\n  protected accountAddress: string\n  protected heliconeApiKey: string\n  protected currentOrganizationId: string | null\n  public isBrowserInstance = true\n\n  constructor(options: PaymentOptions) {\n    // Type-level narrowing of PaymentScheme to 'nvm' won't protect callers\n    // pinned to an older .d.ts that still has 'visa' in the union — they\n    // would silently fall through to the standard pipeline and hit a\n    // misleading 'Invalid NVM API Key' from parseNvmApiKey when the\n    // legacy Visa path tolerated a non-JWT key. Reject up front with a\n    // clear migration message.\n    if (options.scheme && options.scheme !== 'nvm') {\n      throw new PaymentsError(\n        `scheme '${options.scheme}' is no longer supported. Visa is now exposed as provider:'visa' on createDelegation; construct Payments without a scheme override.`,\n      )\n    }\n    this.nvmApiKey = options.nvmApiKey\n    this.scheme = options.scheme || 'nvm'\n    this.returnUrl = options.returnUrl || ''\n    this.environmentName = this.resolveEnvironmentName(options)\n    this.environment = Environments[this.environmentName]\n    this.appId = options.appId\n    // `version` is the backend API pin (MAJOR.MINOR) sent verbatim as\n    // Nevermined-Version. Fail fast on a malformed value rather than shipping\n    // an invalid header (e.g. an SDK package version '1.0.0', 'v1.1', or '')\n    // that the backend rejects with 400 on every call.\n    if (options.version !== undefined && !/^\\d+\\.\\d+$/.test(options.version)) {\n      throw new PaymentsError(\n        `Invalid 'version' option '${options.version}': expected a backend API version as MAJOR.MINOR (e.g. '1.1'). Omit it to use the SDK's default pin.`,\n      )\n    }\n    this.version = options.version\n    this.currentOrganizationId = options.organizationId ?? null\n\n    const { accountAddress, heliconeApiKey } = this.parseNvmApiKey()\n    this.accountAddress = accountAddress\n    this.heliconeApiKey = heliconeApiKey\n  }\n\n  /**\n   * Resolves the active environment for this instance.\n   *\n   * The environment is derived from the NVM API key prefix\n   * (`<prefix>:<jwt>`); the key wins whenever its prefix is recognized. The\n   * deprecated `environment` option is still honored as a fallback when the\n   * key has no recognized prefix (e.g. local/custom dev), and ultimately\n   * defaults to `custom`.\n   *\n   * The deprecation warning fires only when a passed `environment` is actually\n   * overridden by the key prefix (i.e. silently ignored). When it matches the\n   * derived environment, or is the fallback that's actually used, it's harmless\n   * — documented snippets still pass a matching `environment`, so nagging every\n   * new integration would be pure noise (#431).\n   */\n  private resolveEnvironmentName(options: PaymentOptions): EnvironmentName {\n    const fromKey = getEnvironmentFromApiKey(options.nvmApiKey)\n    const resolved = fromKey ?? options.environment ?? 'custom'\n\n    if (\n      options.environment &&\n      options.environment !== resolved &&\n      !environmentOptionDeprecationWarned\n    ) {\n      environmentOptionDeprecationWarned = true\n      console.warn(\n        \"[DEPRECATED] The 'environment' option is deprecated; the environment is now derived \" +\n          `from the NVM API key prefix. Your value ('${options.environment}') is ignored in favor of ` +\n          `the environment derived from the API key ('${resolved}'). Remove the 'environment' option ` +\n          'to silence this warning.',\n      )\n    }\n\n    return resolved\n  }\n\n  /**\n   * Parses the NVM API Key to extract the account address.\n   * @throws PaymentsError if the API key is invalid.\n   */\n  protected parseNvmApiKey(): { accountAddress: string; heliconeApiKey: string } {\n    try {\n      if (!this.nvmApiKey) {\n        throw new PaymentsError('NVM API Key is required')\n      }\n      const jwt = decodeJwt(this.nvmApiKey)\n      const accountAddress = jwt.sub as string\n      const heliconeApiKey = jwt.o11y as string\n      return { accountAddress, heliconeApiKey }\n    } catch (error) {\n      throw new PaymentsError('Invalid NVM API Key')\n    }\n  }\n\n  /**\n   * Returns the environment name used to initialize the Payments instance.\n   * @returns The environment name (e.g. 'sandbox', 'live')\n   */\n  public getEnvironmentName(): EnvironmentName {\n    return this.environmentName\n  }\n\n  /**\n   * It returns the account address associated with the NVM API Key used to initialize the Payments Library instance.\n   * @returns The account address extracted from the NVM API Key\n   */\n  public getAccountAddress(): string | undefined {\n    return this.accountAddress\n  }\n\n  /**\n   * Returns the current organization context applied to every authenticated\n   * backend request via the `X-Current-Org-Id` header.\n   *\n   * `null` means \"no pinned workspace\" — the backend falls back to the\n   * caller's API-key tag or most-recent active membership.\n   */\n  public getOrganizationId(): string | null {\n    return this.currentOrganizationId\n  }\n\n  /**\n   * Sets the organization context applied to every subsequent authenticated\n   * backend request via the `X-Current-Org-Id` header.\n   *\n   * Pass `null` to clear the pin and fall back to the backend default.\n   *\n   * @param organizationId - Org ID (e.g. `org-…`) or `null` to clear.\n   */\n  public setOrganizationId(organizationId: string | null): void {\n    this.currentOrganizationId = organizationId\n  }\n\n  /**\n   * Returns the HTTP options required to query the backend.\n   * @param method - HTTP method.\n   * @param body - Optional request body.\n   * @param extraHeaders - Optional per-call header overrides. Use\n   *   `{ 'X-Current-Org-Id': orgId }` to target a specific workspace for\n   *   one call without mutating the instance-level pin.\n   * @returns HTTP options object.\n   * @internal\n   */\n  protected getBackendHTTPOptions(\n    method: string,\n    body?: any,\n    extraHeaders?: Record<string, string>,\n  ) {\n    const headers: Record<string, string> = {\n      Accept: 'application/json',\n      'Content-Type': 'application/json',\n      Authorization: `Bearer ${this.nvmApiKey}`,\n      [API_VERSION_HEADER]: this.version ?? LOCKED_API_VERSION,\n    }\n    if (this.currentOrganizationId) {\n      headers[CURRENT_ORG_ID_HEADER] = this.currentOrganizationId\n    }\n    if (extraHeaders) {\n      // Allowlist callers' header overrides so a passed-in `Authorization`\n      // or `Content-Type` can't clobber the SDK's transport security\n      // headers. Today only `X-Current-Org-Id` is allowed through.\n      for (const [name, value] of Object.entries(extraHeaders)) {\n        if (ALLOWED_EXTRA_HEADERS.has(name)) {\n          headers[name] = value\n        }\n      }\n    }\n    return {\n      method,\n      headers,\n      ...(body && { body: JSON.stringify(body, jsonReplacer) }),\n    }\n  }\n\n  /**\n   * Get HTTP options for public backend requests (no authorization header).\n   * Converts body keys from snake_case to camelCase for consistency.\n   *\n   * @param method - HTTP method\n   * @param body - Optional request body (keys will be converted to camelCase)\n   * @returns HTTP options object\n   * @internal\n   */\n  protected getPublicHTTPOptions(method: string, body?: any) {\n    const options: {\n      method: string\n      headers: Record<string, string>\n      body?: string\n    } = {\n      method,\n      headers: {\n        Accept: 'application/json',\n        'Content-Type': 'application/json',\n        [API_VERSION_HEADER]: this.version ?? LOCKED_API_VERSION,\n      },\n    }\n\n    if (body) {\n      options.body = JSON.stringify(body, jsonReplacer)\n    }\n\n    return options\n  }\n}\n"]}

package/dist/api/nvm-api.d.ts

@@ -72,10 +72,10 @@ export declare abstract class AbstractHTTPClient {
     }, accessToken?: string): {
         Authorization?: string | undefined;
     };
-    request(method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', url: string, data?: any, reqOptions?: HTTPRequestOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-    get(url: string, reqOptions?: HTTPRequestOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-    post(url: string, data: any, reqOptions: HTTPRequestOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-    put(url: string, data: any, reqOptions: HTTPRequestOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-    delete(url: string, data: any, reqOptions: HTTPRequestOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+    request(method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', url: string, data?: any, reqOptions?: HTTPRequestOptions): Promise<import("axios").AxiosResponse<any, any, {}, any>>;
+    get(url: string, reqOptions?: HTTPRequestOptions): Promise<import("axios").AxiosResponse<any, any, {}, any>>;
+    post(url: string, data: any, reqOptions: HTTPRequestOptions): Promise<import("axios").AxiosResponse<any, any, {}, any>>;
+    put(url: string, data: any, reqOptions: HTTPRequestOptions): Promise<import("axios").AxiosResponse<any, any, {}, any>>;
+    delete(url: string, data: any, reqOptions: HTTPRequestOptions): Promise<import("axios").AxiosResponse<any, any, {}, any>>;
 }
 //# sourceMappingURL=nvm-api.d.ts.map

package/dist/api/observability-api/types.d.ts

@@ -1,12 +1,36 @@
 import type OpenAI from 'openai';
 import type Together from 'together-ai';
-import type * as ChainsModule from 'langchain/chains';
-import type * as AgentsModule from 'langchain/agents';
-import type * as ToolsModule from 'langchain/tools';
 import type * as anthropic from '@anthropic-ai/sdk';
 import type * as cohere from 'cohere-ai';
 import type * as bedrock from '@aws-sdk/client-bedrock-runtime';
 import type * as google_aiplatform from '@google-cloud/aiplatform';
+/**
+ * A LangChain entry-point module handed over by the caller.
+ *
+ * On the resolved `@traceloop/node-server-sdk` (0.26.0) nothing reads a member
+ * of it. `observability-api.ts` forwards the bag to
+ * `traceloop.initialize({ instrumentModules })` behind an `as any`, and there
+ * the field is declared `langchain?: boolean` and never consulted —
+ * `instrumentModules?.langchain` appears nowhere in its `dist/` — because
+ * LangChain is instrumented unconditionally by hooking
+ * `@langchain/core/callbacks/manager`.
+ *
+ * That was not always so. traceloop 0.14 declared five module fields
+ * (`chainsModule`, `agentsModule`, `toolsModule`, `runnablesModule`,
+ * `vectorStoreModule`) and passed them to `manuallyInstrument`; #158 took three
+ * of them, and they went inert with the 0.26 bump in #312. They stay for source
+ * compatibility with callers written against that contract.
+ *
+ * Typing the three as `typeof import('langchain/chains')` and friends therefore
+ * bought no checking, and cost twice. It pinned this SDK's build to one
+ * LangChain layout — v1 moved the legacy chains and agents entry points out, so
+ * those subpaths stopped resolving and a dev-only bump failed with TS2307
+ * (#317) — and, because declaration emit keeps those imports in the published
+ * `types.d.ts` while `langchain` is neither a dependency nor a peer, it broke
+ * the typecheck of any consumer building with `skipLibCheck: false` unless they
+ * happened to have a 0.3-layout `langchain` installed.
+ */
+export type LangChainModule = Record<string, unknown>;
 export type AsyncLoggerProviders = {
     openAI?: typeof OpenAI;
     anthropic?: typeof anthropic;
@@ -14,10 +38,14 @@ export type AsyncLoggerProviders = {
     bedrock?: typeof bedrock;
     google_aiplatform?: typeof google_aiplatform;
     together?: typeof Together;
+    /**
+     * Inert on the resolved traceloop (0.26.0), which instruments LangChain
+     * unconditionally and ignores these modules. See {@link LangChainModule}.
+     */
     langchain?: {
-        chainsModule?: typeof ChainsModule;
-        agentsModule?: typeof AgentsModule;
-        toolsModule?: typeof ToolsModule;
+        chainsModule?: LangChainModule;
+        agentsModule?: LangChainModule;
+        toolsModule?: LangChainModule;
     };
 };
 /**

package/dist/api/observability-api/types.d.ts.map

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

package/dist/api/observability-api/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/api/observability-api/types.ts"],"names":[],"mappings":"","sourcesContent":["import type OpenAI from 'openai'\nimport type Together from 'together-ai'\nimport type * as ChainsModule from 'langchain/chains'\nimport type * as AgentsModule from 'langchain/agents'\nimport type * as ToolsModule from 'langchain/tools'\nimport type * as anthropic from '@anthropic-ai/sdk'\nimport type * as cohere from 'cohere-ai'\nimport type * as bedrock from '@aws-sdk/client-bedrock-runtime'\nimport type * as google_aiplatform from '@google-cloud/aiplatform'\n\nexport type AsyncLoggerProviders = {\n  openAI?: typeof OpenAI\n  anthropic?: typeof anthropic\n  cohere?: typeof cohere\n  bedrock?: typeof bedrock\n  google_aiplatform?: typeof google_aiplatform\n  together?: typeof Together\n  langchain?: {\n    chainsModule?: typeof ChainsModule\n    agentsModule?: typeof AgentsModule\n    toolsModule?: typeof ToolsModule\n  }\n}\n\n/**\n * Configuration for creating a Helicone payload\n */\nexport interface HeliconePayloadConfig {\n  model: string\n  inputData: Record<string, any>\n  temperature?: number\n  top_p?: number\n  frequency_penalty?: number\n  presence_penalty?: number\n  n?: number\n  stream?: boolean\n}\n\n/**\n * Configuration for creating a Helicone response\n */\nexport interface HeliconeResponseConfig {\n  idPrefix: string\n  model: string\n  resultData: any\n  usage: {\n    prompt_tokens: number\n    completion_tokens: number\n    total_tokens: number\n    prompt_tokens_details?: {\n      cached_tokens: number\n      audio_tokens: number\n    }\n    completion_tokens_details?: {\n      reasoning_tokens: number\n      audio_tokens: number\n      accepted_prediction_tokens: number\n      rejected_prediction_tokens: number\n    }\n  }\n  systemFingerprint?: string\n}\n\nexport type CustomProperties = Record<string, string>\n\nexport type NeverminedHeliconeHeaders = {\n  'Helicone-Auth': string\n  'Helicone-Property-accountaddress': string\n  'Helicone-Property-consumeraddress': string\n  'Helicone-Property-agentid': string\n  'Helicone-Property-planid': string\n  'Helicone-Property-plantype': string\n  'Helicone-Property-planname': string\n  'Helicone-Property-agentname': string\n  'Helicone-Property-agentrequestid': string\n  'Helicone-Property-pricepercredit': string\n  'Helicone-Property-environmentname': string\n  'Helicone-Property-batch': string\n  'Helicone-Property-ismarginbased': string\n  'Helicone-Property-marginpercent': string\n}\n\nexport type DefaultHeliconeHeaders = NeverminedHeliconeHeaders & CustomProperties\n\nexport type ChatOpenAIConfiguration = {\n  model: string\n  apiKey: string\n  configuration: {\n    baseURL: string\n    defaultHeaders: DefaultHeliconeHeaders\n  }\n}\n\nexport type OpenAIConfiguration = {\n  apiKey: string\n  baseURL: string\n  defaultHeaders: DefaultHeliconeHeaders\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/api/observability-api/types.ts"],"names":[],"mappings":"","sourcesContent":["import type OpenAI from 'openai'\nimport type Together from 'together-ai'\nimport type * as anthropic from '@anthropic-ai/sdk'\nimport type * as cohere from 'cohere-ai'\nimport type * as bedrock from '@aws-sdk/client-bedrock-runtime'\nimport type * as google_aiplatform from '@google-cloud/aiplatform'\n\n/**\n * A LangChain entry-point module handed over by the caller.\n *\n * On the resolved `@traceloop/node-server-sdk` (0.26.0) nothing reads a member\n * of it. `observability-api.ts` forwards the bag to\n * `traceloop.initialize({ instrumentModules })` behind an `as any`, and there\n * the field is declared `langchain?: boolean` and never consulted —\n * `instrumentModules?.langchain` appears nowhere in its `dist/` — because\n * LangChain is instrumented unconditionally by hooking\n * `@langchain/core/callbacks/manager`.\n *\n * That was not always so. traceloop 0.14 declared five module fields\n * (`chainsModule`, `agentsModule`, `toolsModule`, `runnablesModule`,\n * `vectorStoreModule`) and passed them to `manuallyInstrument`; #158 took three\n * of them, and they went inert with the 0.26 bump in #312. They stay for source\n * compatibility with callers written against that contract.\n *\n * Typing the three as `typeof import('langchain/chains')` and friends therefore\n * bought no checking, and cost twice. It pinned this SDK's build to one\n * LangChain layout — v1 moved the legacy chains and agents entry points out, so\n * those subpaths stopped resolving and a dev-only bump failed with TS2307\n * (#317) — and, because declaration emit keeps those imports in the published\n * `types.d.ts` while `langchain` is neither a dependency nor a peer, it broke\n * the typecheck of any consumer building with `skipLibCheck: false` unless they\n * happened to have a 0.3-layout `langchain` installed.\n */\nexport type LangChainModule = Record<string, unknown>\n\nexport type AsyncLoggerProviders = {\n  openAI?: typeof OpenAI\n  anthropic?: typeof anthropic\n  cohere?: typeof cohere\n  bedrock?: typeof bedrock\n  google_aiplatform?: typeof google_aiplatform\n  together?: typeof Together\n  /**\n   * Inert on the resolved traceloop (0.26.0), which instruments LangChain\n   * unconditionally and ignores these modules. See {@link LangChainModule}.\n   */\n  langchain?: {\n    chainsModule?: LangChainModule\n    agentsModule?: LangChainModule\n    toolsModule?: LangChainModule\n  }\n}\n\n/**\n * Configuration for creating a Helicone payload\n */\nexport interface HeliconePayloadConfig {\n  model: string\n  inputData: Record<string, any>\n  temperature?: number\n  top_p?: number\n  frequency_penalty?: number\n  presence_penalty?: number\n  n?: number\n  stream?: boolean\n}\n\n/**\n * Configuration for creating a Helicone response\n */\nexport interface HeliconeResponseConfig {\n  idPrefix: string\n  model: string\n  resultData: any\n  usage: {\n    prompt_tokens: number\n    completion_tokens: number\n    total_tokens: number\n    prompt_tokens_details?: {\n      cached_tokens: number\n      audio_tokens: number\n    }\n    completion_tokens_details?: {\n      reasoning_tokens: number\n      audio_tokens: number\n      accepted_prediction_tokens: number\n      rejected_prediction_tokens: number\n    }\n  }\n  systemFingerprint?: string\n}\n\nexport type CustomProperties = Record<string, string>\n\nexport type NeverminedHeliconeHeaders = {\n  'Helicone-Auth': string\n  'Helicone-Property-accountaddress': string\n  'Helicone-Property-consumeraddress': string\n  'Helicone-Property-agentid': string\n  'Helicone-Property-planid': string\n  'Helicone-Property-plantype': string\n  'Helicone-Property-planname': string\n  'Helicone-Property-agentname': string\n  'Helicone-Property-agentrequestid': string\n  'Helicone-Property-pricepercredit': string\n  'Helicone-Property-environmentname': string\n  'Helicone-Property-batch': string\n  'Helicone-Property-ismarginbased': string\n  'Helicone-Property-marginpercent': string\n}\n\nexport type DefaultHeliconeHeaders = NeverminedHeliconeHeaders & CustomProperties\n\nexport type ChatOpenAIConfiguration = {\n  model: string\n  apiKey: string\n  configuration: {\n    baseURL: string\n    defaultHeaders: DefaultHeliconeHeaders\n  }\n}\n\nexport type OpenAIConfiguration = {\n  apiKey: string\n  baseURL: string\n  defaultHeaders: DefaultHeliconeHeaders\n}\n"]}