@t402/core 2.4.0 → 2.6.0

package/dist/cjs/{mechanisms-C7yK91d4.d.ts → mechanisms-dYCiYgko.d.ts}

@@ -240,42 +240,77 @@ declare const T402_A2A_EXTENSION_URI = "https://github.com/google-a2a/a2a-t402/v
 declare const A2A_EXTENSIONS_HEADER = "X-A2A-Extensions";
 /**
  * Check if a task is in a payment-required state
+ *
+ * @param task - The A2A task to check
+ * @returns Whether the task requires payment
  */
 declare function isPaymentRequired(task: A2ATask): boolean;
 /**
  * Check if a task has completed payment
+ *
+ * @param task - The A2A task to check
+ * @returns Whether the task has completed payment
  */
 declare function isPaymentCompleted(task: A2ATask): boolean;
 /**
  * Check if a task has failed payment
+ *
+ * @param task - The A2A task to check
+ * @returns Whether the task has failed payment
  */
 declare function isPaymentFailed(task: A2ATask): boolean;
 /**
  * Extract payment requirements from a task
+ *
+ * @param task - The A2A task to extract requirements from
+ * @returns The payment requirements if the task requires payment
  */
 declare function getPaymentRequired(task: A2ATask): PaymentRequired | undefined;
 /**
  * Extract payment receipts from a task
+ *
+ * @param task - The A2A task to extract receipts from
+ * @returns The settlement receipts if available
  */
 declare function getPaymentReceipts(task: A2ATask): SettleResponse[] | undefined;
 /**
  * Create a payment-required message
+ *
+ * @param paymentRequired - The payment requirements
+ * @param text - Optional message text
+ * @returns An A2A message with payment-required metadata
  */
 declare function createPaymentRequiredMessage(paymentRequired: PaymentRequired, text?: string): A2AMessage;
 /**
  * Create a payment submission message
+ *
+ * @param paymentPayload - The payment payload to submit
+ * @param text - Optional message text
+ * @returns An A2A message with payment-submitted metadata
  */
 declare function createPaymentSubmissionMessage(paymentPayload: PaymentPayload, text?: string): A2AMessage;
 /**
  * Create a payment completed message
+ *
+ * @param receipts - The settlement receipts
+ * @param text - Optional message text
+ * @returns An A2A message with payment-completed metadata
  */
 declare function createPaymentCompletedMessage(receipts: SettleResponse[], text?: string): A2AMessage;
 /**
  * Create a payment failed message
+ *
+ * @param receipts - The settlement receipts
+ * @param errorCode - The error code
+ * @param text - Optional message text
+ * @returns An A2A message with payment-failed metadata
  */
 declare function createPaymentFailedMessage(receipts: SettleResponse[], errorCode: string, text?: string): A2AMessage;
 /**
  * Create a T402 extension declaration for agent cards
+ *
+ * @param required - Whether the extension is required
+ * @returns An A2A extension declaration
  */
 declare function createT402Extension(required?: boolean): A2AExtension;
 
@@ -564,17 +599,47 @@ interface APIError {
     details?: string;
     retry?: boolean;
 }
-/** Returns the HTTP status code for a given error code */
+/**
+ * Returns the HTTP status code for a given error code
+ *
+ * @param code - The T402 error code
+ * @returns The corresponding HTTP status code
+ */
 declare function httpStatusForCode(code: ErrorCode): number;
-/** Returns true if the error code is a client error (T402-1xxx) */
+/**
+ * Returns true if the error code is a client error (T402-1xxx)
+ *
+ * @param code - The T402 error code
+ * @returns Whether the error is a client error
+ */
 declare function isClientError(code: ErrorCode): boolean;
-/** Returns true if the error code is a server error (T402-2xxx) */
+/**
+ * Returns true if the error code is a server error (T402-2xxx)
+ *
+ * @param code - The T402 error code
+ * @returns Whether the error is a server error
+ */
 declare function isServerError(code: ErrorCode): boolean;
-/** Returns true if the error code is a facilitator error (T402-3xxx) */
+/**
+ * Returns true if the error code is a facilitator error (T402-3xxx)
+ *
+ * @param code - The T402 error code
+ * @returns Whether the error is a facilitator error
+ */
 declare function isFacilitatorError(code: ErrorCode): boolean;
-/** Returns true if the error code is a chain error (T402-4xxx) */
+/**
+ * Returns true if the error code is a chain error (T402-4xxx)
+ *
+ * @param code - The T402 error code
+ * @returns Whether the error is a chain error
+ */
 declare function isChainError(code: ErrorCode): boolean;
-/** Returns true if the error code is a bridge error (T402-5xxx) */
+/**
+ * Returns true if the error code is a bridge error (T402-5xxx)
+ *
+ * @param code - The T402 error code
+ * @returns Whether the error is a bridge error
+ */
 declare function isBridgeError(code: ErrorCode): boolean;
 
 /**
@@ -797,18 +862,21 @@ declare const SettleResponseSchema: z.ZodObject<{
     network: z.ZodString;
     errorReason: z.ZodOptional<z.ZodString>;
     payer: z.ZodOptional<z.ZodString>;
+    confirmations: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     network: string;
     success: boolean;
     transaction: string;
     payer?: string | undefined;
     errorReason?: string | undefined;
+    confirmations?: string | undefined;
 }, {
     network: string;
     success: boolean;
     transaction: string;
     payer?: string | undefined;
     errorReason?: string | undefined;
+    confirmations?: string | undefined;
 }>;
 declare const PaymentRequirementsV1Schema: z.ZodObject<{
     scheme: z.ZodString;
@@ -996,6 +1064,7 @@ type SettleResponse = {
     payer?: string;
     transaction: string;
     network: Network;
+    confirmations?: string;
 };
 type SupportedKind = {
     t402Version: number;
@@ -1123,4 +1192,4 @@ interface SchemeNetworkServer {
     }, facilitatorExtensions: string[]): Promise<PaymentRequirements>;
 }
 
-export { createPaymentFailedMessage as $, type AssetAmount as A, type A2AArtifact as B, type A2ATaskStatus as C, type A2ATask as D, type A2ARequest as E, type A2AResponse as F, type A2AError as G, type A2AExtension as H, type A2ACapabilities as I, type A2AAgentCard as J, type A2ASkill as K, A2A_EXTENSIONS_HEADER as L, type Money as M, type Network as N, isPaymentRequired as O, type PaymentRequirements as P, isPaymentCompleted as Q, type ResourceServerExtension as R, type SettleResponse as S, T402_A2A_EXTENSION_URI as T, isPaymentFailed as U, type VerifyResponse as V, getPaymentRequired as W, getPaymentReceipts as X, createPaymentRequiredMessage as Y, createPaymentSubmissionMessage as Z, createPaymentCompletedMessage as _, type PaymentPayload as a, ERR_STREAM_NOT_FOUND as a$, createT402Extension as a0, type UptoPaymentRequirements as a1, type UptoExtra as a2, type UptoPayloadBase as a3, type UptoEvmPayload as a4, type UptoEvmPayloadCompact as a5, type UptoSettlement as a6, type UptoUsageDetails as a7, type UptoSettlementResponse as a8, type UptoValidationResult as a9, ERR_RATE_LIMITED as aA, ERR_SERVICE_UNAVAILABLE as aB, ERR_VERIFICATION_FAILED as aC, ERR_SETTLEMENT_FAILED as aD, ERR_INSUFFICIENT_BALANCE as aE, ERR_ALLOWANCE_INSUFFICIENT as aF, ERR_PAYMENT_MISMATCH as aG, ERR_DUPLICATE_PAYMENT as aH, ERR_SETTLEMENT_PENDING as aI, ERR_SETTLEMENT_TIMEOUT as aJ, ERR_NONCE_REPLAY as aK, ERR_IDEMPOTENCY_CONFLICT as aL, ERR_IDEMPOTENCY_UNAVAILABLE as aM, ERR_PREVIOUS_REQUEST_FAILED as aN, ERR_REQUEST_IN_PROGRESS as aO, ERR_CHAIN_UNAVAILABLE as aP, ERR_TRANSACTION_FAILED as aQ, ERR_TRANSACTION_REVERTED as aR, ERR_GAS_ESTIMATION_FAILED as aS, ERR_NONCE_CONFLICT as aT, ERR_CHAIN_CONGESTED as aU, ERR_CONTRACT_ERROR as aV, ERR_BRIDGE_UNAVAILABLE as aW, ERR_BRIDGE_QUOTE_FAILED as aX, ERR_BRIDGE_TRANSFER_FAILED as aY, ERR_BRIDGE_TIMEOUT as aZ, ERR_UNSUPPORTED_ROUTE as a_, type UptoUnit as aa, isUptoPaymentRequirements as ab, isUptoEvmPayload as ac, UPTO_SCHEME as ad, UPTO_DEFAULTS as ae, type ErrorCode as af, type APIError as ag, ERR_INVALID_REQUEST as ah, ERR_MISSING_PAYLOAD as ai, ERR_MISSING_REQUIREMENTS as aj, ERR_INVALID_PAYLOAD as ak, ERR_INVALID_REQUIREMENTS as al, ERR_INVALID_SIGNATURE as am, ERR_INVALID_NETWORK as an, ERR_INVALID_SCHEME as ao, ERR_INVALID_AMOUNT as ap, ERR_INVALID_ADDRESS as aq, ERR_EXPIRED_PAYMENT as ar, ERR_INVALID_NONCE as as, ERR_INSUFFICIENT_AMOUNT as at, ERR_INVALID_IDEMPOTENCY_KEY as au, ERR_SIGNATURE_EXPIRED as av, ERR_INTERNAL as aw, ERR_DATABASE_UNAVAILABLE as ax, ERR_CACHE_UNAVAILABLE as ay, ERR_RPC_UNAVAILABLE as az, type SchemeNetworkFacilitator as b, ERR_STREAM_ALREADY_CLOSED as b0, ERR_STREAM_ALREADY_PAUSED as b1, ERR_STREAM_NOT_PAUSED as b2, ERR_STREAM_AMOUNT_EXCEEDED as b3, ERR_STREAM_EXPIRED as b4, ERR_STREAM_INVALID_STATE as b5, ERR_STREAM_RATE_LIMITED as b6, ERR_INTENT_NOT_FOUND as b7, ERR_INTENT_ALREADY_EXECUTED as b8, ERR_INTENT_CANCELLED as b9, parsePaymentRequirements as bA, safeParsePaymentPayload as bB, safeParsePaymentRequired as bC, safeParsePaymentRequirements as bD, type ValidatedPaymentPayload as bE, type ValidatedPaymentRequired as bF, type ValidatedPaymentRequirements as bG, type ValidatedVerifyResponse as bH, type ValidatedSettleResponse as bI, ERR_INTENT_EXPIRED as ba, ERR_NO_ROUTES_AVAILABLE as bb, ERR_ROUTE_EXPIRED as bc, ERR_ROUTE_NOT_SELECTED as bd, ERR_INTENT_INVALID_STATE as be, ERR_RESOURCE_NOT_FOUND as bf, ERR_RESOURCE_ALREADY_EXISTS as bg, ERR_INVALID_PARAMETERS as bh, ERR_NOT_AUTHORIZED as bi, httpStatusForCode as bj, isClientError as bk, isServerError as bl, isFacilitatorError as bm, isChainError as bn, isBridgeError as bo, NetworkSchema as bp, ResourceInfoSchema as bq, PaymentRequirementsSchema as br, PaymentRequiredSchema as bs, PaymentPayloadSchema as bt, VerifyResponseSchema as bu, SettleResponseSchema as bv, PaymentRequirementsV1Schema as bw, PaymentPayloadV1Schema as bx, parsePaymentPayload as by, parsePaymentRequired as bz, type PaymentRequired as c, type SchemeNetworkClient as d, type SupportedResponse as e, type SchemeNetworkServer as f, type SupportedKind as g, type Price as h, type PaymentRequirementsV1 as i, type PaymentRequiredV1 as j, type PaymentPayloadV1 as k, type VerifyRequestV1 as l, type SettleRequestV1 as m, type SettleResponseV1 as n, type SupportedResponseV1 as o, type VerifyRequest as p, type SettleRequest as q, type MoneyParser as r, type A2APaymentStatus as s, type A2ATaskState as t, type A2ATextPart as u, type A2AFilePart as v, type A2ADataPart as w, type A2AMessagePart as x, type A2APaymentMetadata as y, type A2AMessage as z };
+export { ERR_GAS_ESTIMATION_FAILED as $, type A2AAgentCard as A, type A2AResponse as B, type A2ASkill as C, type A2ATask as D, type A2ATaskState as E, type A2ATaskStatus as F, type A2ATextPart as G, A2A_EXTENSIONS_HEADER as H, type APIError as I, type AssetAmount as J, ERR_ALLOWANCE_INSUFFICIENT as K, ERR_BRIDGE_QUOTE_FAILED as L, ERR_BRIDGE_TIMEOUT as M, type Network as N, ERR_BRIDGE_TRANSFER_FAILED as O, type PaymentRequirements as P, ERR_BRIDGE_UNAVAILABLE as Q, type ResourceServerExtension as R, type SettleResponse as S, ERR_CACHE_UNAVAILABLE as T, ERR_CHAIN_CONGESTED as U, type VerifyResponse as V, ERR_CHAIN_UNAVAILABLE as W, ERR_CONTRACT_ERROR as X, ERR_DATABASE_UNAVAILABLE as Y, ERR_DUPLICATE_PAYMENT as Z, ERR_EXPIRED_PAYMENT as _, type PaymentPayload as a, type SettleRequest as a$, ERR_IDEMPOTENCY_CONFLICT as a0, ERR_IDEMPOTENCY_UNAVAILABLE as a1, ERR_INSUFFICIENT_AMOUNT as a2, ERR_INSUFFICIENT_BALANCE as a3, ERR_INTENT_ALREADY_EXECUTED as a4, ERR_INTENT_CANCELLED as a5, ERR_INTENT_EXPIRED as a6, ERR_INTENT_INVALID_STATE as a7, ERR_INTENT_NOT_FOUND as a8, ERR_INTERNAL as a9, ERR_SERVICE_UNAVAILABLE as aA, ERR_SETTLEMENT_FAILED as aB, ERR_SETTLEMENT_PENDING as aC, ERR_SETTLEMENT_TIMEOUT as aD, ERR_SIGNATURE_EXPIRED as aE, ERR_STREAM_ALREADY_CLOSED as aF, ERR_STREAM_ALREADY_PAUSED as aG, ERR_STREAM_AMOUNT_EXCEEDED as aH, ERR_STREAM_EXPIRED as aI, ERR_STREAM_INVALID_STATE as aJ, ERR_STREAM_NOT_FOUND as aK, ERR_STREAM_NOT_PAUSED as aL, ERR_STREAM_RATE_LIMITED as aM, ERR_TRANSACTION_FAILED as aN, ERR_TRANSACTION_REVERTED as aO, ERR_UNSUPPORTED_ROUTE as aP, ERR_VERIFICATION_FAILED as aQ, type ErrorCode as aR, type Money as aS, type MoneyParser as aT, NetworkSchema as aU, PaymentPayloadSchema as aV, PaymentPayloadV1Schema as aW, PaymentRequiredSchema as aX, PaymentRequirementsSchema as aY, PaymentRequirementsV1Schema as aZ, ResourceInfoSchema as a_, ERR_INVALID_ADDRESS as aa, ERR_INVALID_AMOUNT as ab, ERR_INVALID_IDEMPOTENCY_KEY as ac, ERR_INVALID_NETWORK as ad, ERR_INVALID_NONCE as ae, ERR_INVALID_PARAMETERS as af, ERR_INVALID_PAYLOAD as ag, ERR_INVALID_REQUEST as ah, ERR_INVALID_REQUIREMENTS as ai, ERR_INVALID_SCHEME as aj, ERR_INVALID_SIGNATURE as ak, ERR_MISSING_PAYLOAD as al, ERR_MISSING_REQUIREMENTS as am, ERR_NONCE_CONFLICT as an, ERR_NONCE_REPLAY as ao, ERR_NOT_AUTHORIZED as ap, ERR_NO_ROUTES_AVAILABLE as aq, ERR_PAYMENT_MISMATCH as ar, ERR_PREVIOUS_REQUEST_FAILED as as, ERR_RATE_LIMITED as at, ERR_REQUEST_IN_PROGRESS as au, ERR_RESOURCE_ALREADY_EXISTS as av, ERR_RESOURCE_NOT_FOUND as aw, ERR_ROUTE_EXPIRED as ax, ERR_ROUTE_NOT_SELECTED as ay, ERR_RPC_UNAVAILABLE as az, type SchemeNetworkFacilitator as b, SettleResponseSchema as b0, T402_A2A_EXTENSION_URI as b1, UPTO_DEFAULTS as b2, UPTO_SCHEME as b3, type UptoEvmPayload as b4, type UptoEvmPayloadCompact as b5, type UptoExtra as b6, type UptoPayloadBase as b7, type UptoPaymentRequirements as b8, type UptoSettlement as b9, isServerError as bA, isUptoEvmPayload as bB, isUptoPaymentRequirements as bC, parsePaymentPayload as bD, parsePaymentRequired as bE, parsePaymentRequirements as bF, safeParsePaymentPayload as bG, safeParsePaymentRequired as bH, safeParsePaymentRequirements as bI, type UptoSettlementResponse as ba, type UptoUnit as bb, type UptoUsageDetails as bc, type UptoValidationResult as bd, type ValidatedPaymentPayload as be, type ValidatedPaymentRequired as bf, type ValidatedPaymentRequirements as bg, type ValidatedSettleResponse as bh, type ValidatedVerifyResponse as bi, type VerifyRequest as bj, VerifyResponseSchema as bk, createPaymentCompletedMessage as bl, createPaymentFailedMessage as bm, createPaymentRequiredMessage as bn, createPaymentSubmissionMessage as bo, createT402Extension as bp, getPaymentReceipts as bq, getPaymentRequired as br, httpStatusForCode as bs, isBridgeError as bt, isChainError as bu, isClientError as bv, isFacilitatorError as bw, isPaymentCompleted as bx, isPaymentFailed as by, isPaymentRequired as bz, type PaymentRequired as c, type SchemeNetworkClient as d, type SupportedResponse as e, type SchemeNetworkServer as f, type SupportedKind as g, type Price as h, type PaymentPayloadV1 as i, type PaymentRequiredV1 as j, type PaymentRequirementsV1 as k, type SettleRequestV1 as l, type SettleResponseV1 as m, type SupportedResponseV1 as n, type VerifyRequestV1 as o, type A2AArtifact as p, type A2ACapabilities as q, type A2ADataPart as r, type A2AError as s, type A2AExtension as t, type A2AFilePart as u, type A2AMessage as v, type A2AMessagePart as w, type A2APaymentMetadata as x, type A2APaymentStatus as y, type A2ARequest as z };

package/dist/cjs/server/index.d.ts

@@ -1,3 +1,3 @@
-export { C as CompiledRoute, F as FacilitatorClient, o as FacilitatorConfig, a as HTTPAdapter, H as HTTPFacilitatorClient, d as HTTPProcessResult, b as HTTPRequestContext, c as HTTPResponseInstructions, P as PaywallConfig, e as PaywallProvider, m as ProcessSettleFailureResponse, k as ProcessSettleResultResponse, l as ProcessSettleSuccessResponse, q as ResourceConfig, r as ResourceInfo, g as RouteConfig, R as RouteConfigurationError, n as RouteValidationError, h as RoutesConfig, U as UnpaidResponseBody, j as UnpaidResponseResult, t as t402HTTPResourceServer, p as t402ResourceServer } from '../t402HTTPResourceServer-CybruqCk.js';
-import '../mechanisms-C7yK91d4.js';
+export { C as CompiledRoute, F as FacilitatorClient, b as FacilitatorConfig, H as HTTPAdapter, c as HTTPFacilitatorClient, d as HTTPProcessResult, e as HTTPRequestContext, f as HTTPResponseInstructions, g as PaywallConfig, h as PaywallProvider, i as ProcessSettleFailureResponse, j as ProcessSettleResultResponse, k as ProcessSettleSuccessResponse, p as ResourceConfig, q as ResourceInfo, R as RouteConfig, l as RouteConfigurationError, m as RouteValidationError, n as RoutesConfig, U as UnpaidResponseBody, o as UnpaidResponseResult, t as t402HTTPResourceServer, r as t402ResourceServer } from '../t402HTTPResourceServer-CGZh_p2c.js';
+import '../mechanisms-dYCiYgko.js';
 import 'zod';

package/dist/cjs/server/index.js

@@ -85,6 +85,38 @@ function deepEqual(obj1, obj2) {
   }
 }
 
+// src/errors.ts
+var T402PaymentError = class _T402PaymentError extends Error {
+  constructor(message, options) {
+    super(message);
+    __publicField(this, "cause");
+    __publicField(this, "phase");
+    __publicField(this, "retryable");
+    __publicField(this, "code");
+    this.name = "T402PaymentError";
+    this.cause = options?.cause;
+    this.phase = options?.phase ?? "unknown";
+    this.retryable = options?.retryable ?? false;
+    this.code = options?.code;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _T402PaymentError);
+    }
+  }
+  isRetryable() {
+    return this.retryable;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      phase: this.phase,
+      retryable: this.retryable,
+      code: this.code,
+      cause: this.cause?.message
+    };
+  }
+};
+
 // src/http/httpFacilitatorClient.ts
 var DEFAULT_FACILITATOR_URL = "https://facilitator.t402.io";
 var HTTPFacilitatorClient = class {
@@ -125,7 +157,11 @@ var HTTPFacilitatorClient = class {
     });
     if (!response.ok) {
       const errorText = await response.text().catch(() => response.statusText);
-      throw new Error(`Facilitator verify failed (${response.status}): ${errorText}`);
+      throw new T402PaymentError(`Facilitator verify failed (${response.status}): ${errorText}`, {
+        phase: "verification",
+        code: response.status,
+        retryable: response.status >= 500 || response.status === 429
+      });
     }
     return await response.json();
   }
@@ -155,7 +191,11 @@ var HTTPFacilitatorClient = class {
     });
     if (!response.ok) {
       const errorText = await response.text().catch(() => response.statusText);
-      throw new Error(`Facilitator settle failed (${response.status}): ${errorText}`);
+      throw new T402PaymentError(`Facilitator settle failed (${response.status}): ${errorText}`, {
+        phase: "settlement",
+        code: response.status,
+        retryable: response.status >= 500 || response.status === 429
+      });
     }
     return await response.json();
   }
@@ -178,7 +218,14 @@ var HTTPFacilitatorClient = class {
     });
     if (!response.ok) {
       const errorText = await response.text().catch(() => response.statusText);
-      throw new Error(`Facilitator getSupported failed (${response.status}): ${errorText}`);
+      throw new T402PaymentError(
+        `Facilitator getSupported failed (${response.status}): ${errorText}`,
+        {
+          phase: "unknown",
+          code: response.status,
+          retryable: response.status >= 500 || response.status === 429
+        }
+      );
     }
     return await response.json();
   }
@@ -806,7 +853,8 @@ var SettleResponseSchema = import_zod.z.object({
   transaction: import_zod.z.string(),
   network: NetworkSchema,
   errorReason: import_zod.z.string().optional(),
-  payer: import_zod.z.string().optional()
+  payer: import_zod.z.string().optional(),
+  confirmations: import_zod.z.string().optional()
 });
 var PaymentRequirementsV1Schema = import_zod.z.object({
   scheme: import_zod.z.string().min(1),
@@ -1121,12 +1169,12 @@ var t402HTTPResourceServer = class {
    * @returns Decoded payment payload or null
    */
   extractPayment(adapter) {
-    const header = adapter.getHeader("payment-signature") || adapter.getHeader("PAYMENT-SIGNATURE");
+    const header = adapter.getHeader("payment-signature") || adapter.getHeader("PAYMENT-SIGNATURE") || adapter.getHeader("x-payment") || adapter.getHeader("X-PAYMENT");
     if (header) {
       try {
         return decodePaymentSignatureHeader(header);
       } catch (error) {
-        console.warn("Failed to decode PAYMENT-SIGNATURE header:", error);
+        console.warn("Failed to decode payment header:", error);
       }
     }
     return null;