@bankofai/x402-extensions 2.6.0-beta.0

package/dist/esm/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/eip2612-gas-sponsoring/types.ts","../../src/eip2612-gas-sponsoring/resourceService.ts","../../src/eip2612-gas-sponsoring/facilitator.ts","../../src/erc20-approval-gas-sponsoring/types.ts","../../src/erc20-approval-gas-sponsoring/resourceService.ts","../../src/erc20-approval-gas-sponsoring/facilitator.ts"],"sourcesContent":["/**\n * Type definitions for the EIP-2612 Gas Sponsoring Extension\n *\n * This extension enables gasless approval of the Permit2 contract for tokens\n * that implement EIP-2612. The client signs an off-chain permit, and the\n * facilitator submits it on-chain via `x402Permit2Proxy.settleWithPermit`.\n */\n\nimport type { FacilitatorExtension } from \"@bankofai/x402-core/types\";\n\n/**\n * Extension identifier for the EIP-2612 gas sponsoring extension.\n */\nexport const EIP2612_GAS_SPONSORING: FacilitatorExtension = { key: \"eip2612GasSponsoring\" };\n\n/**\n * EIP-2612 gas sponsoring info populated by the client.\n *\n * Contains the EIP-2612 permit signature and parameters that the facilitator\n * needs to call `x402Permit2Proxy.settleWithPermit`.\n */\nexport interface Eip2612GasSponsoringInfo {\n  /** Index signature for compatibility with Record<string, unknown> */\n  [key: string]: unknown;\n  /** The address of the sender (token owner). */\n  from: string;\n  /** The address of the ERC-20 token contract. */\n  asset: string;\n  /** The address of the spender (Canonical Permit2). */\n  spender: string;\n  /** The amount to approve (uint256 as decimal string). Typically MaxUint256. */\n  amount: string;\n  /** The current EIP-2612 nonce of the sender (decimal string). */\n  nonce: string;\n  /** The timestamp at which the permit signature expires (decimal string). */\n  deadline: string;\n  /** The 65-byte concatenated EIP-2612 permit signature (r, s, v) as a hex string. */\n  signature: string;\n  /** Schema version identifier. */\n  version: string;\n}\n\n/**\n * Server-side EIP-2612 gas sponsoring info included in PaymentRequired.\n * Contains a description and version; the client populates the rest.\n */\nexport interface Eip2612GasSponsoringServerInfo {\n  /** Index signature for compatibility with Record<string, unknown> */\n  [key: string]: unknown;\n  /** Human-readable description of the extension. */\n  description: string;\n  /** Schema version identifier. */\n  version: string;\n}\n\n/**\n * The full extension object as it appears in PaymentRequired.extensions\n * and PaymentPayload.extensions.\n */\nexport interface Eip2612GasSponsoringExtension {\n  /** Extension info - server-provided or client-enriched. */\n  info: Eip2612GasSponsoringServerInfo | Eip2612GasSponsoringInfo;\n  /** JSON Schema describing the expected structure of info. */\n  schema: Record<string, unknown>;\n}\n","/**\n * Resource Service functions for declaring the EIP-2612 Gas Sponsoring extension.\n *\n * These functions help servers declare support for EIP-2612 gasless Permit2 approvals\n * in the PaymentRequired response extensions.\n */\n\nimport { EIP2612_GAS_SPONSORING, type Eip2612GasSponsoringExtension } from \"./types\";\n\n/**\n * The JSON Schema for the EIP-2612 gas sponsoring extension info.\n * Matches the schema defined in the spec.\n */\nconst eip2612GasSponsoringSchema: Record<string, unknown> = {\n  $schema: \"https://json-schema.org/draft/2020-12/schema\",\n  type: \"object\",\n  properties: {\n    from: {\n      type: \"string\",\n      pattern: \"^0x[a-fA-F0-9]{40}$\",\n      description: \"The address of the sender.\",\n    },\n    asset: {\n      type: \"string\",\n      pattern: \"^0x[a-fA-F0-9]{40}$\",\n      description: \"The address of the ERC-20 token contract.\",\n    },\n    spender: {\n      type: \"string\",\n      pattern: \"^0x[a-fA-F0-9]{40}$\",\n      description: \"The address of the spender (Canonical Permit2).\",\n    },\n    amount: {\n      type: \"string\",\n      pattern: \"^[0-9]+$\",\n      description: \"The amount to approve (uint256). Typically MaxUint.\",\n    },\n    nonce: {\n      type: \"string\",\n      pattern: \"^[0-9]+$\",\n      description: \"The current nonce of the sender.\",\n    },\n    deadline: {\n      type: \"string\",\n      pattern: \"^[0-9]+$\",\n      description: \"The timestamp at which the signature expires.\",\n    },\n    signature: {\n      type: \"string\",\n      pattern: \"^0x[a-fA-F0-9]+$\",\n      description: \"The 65-byte concatenated signature (r, s, v) as a hex string.\",\n    },\n    version: {\n      type: \"string\",\n      pattern: \"^[0-9]+(\\\\.[0-9]+)*$\",\n      description: \"Schema version identifier.\",\n    },\n  },\n  required: [\"from\", \"asset\", \"spender\", \"amount\", \"nonce\", \"deadline\", \"signature\", \"version\"],\n};\n\n/**\n * Declares the EIP-2612 gas sponsoring extension for inclusion in\n * PaymentRequired.extensions.\n *\n * The server advertises that it (or its facilitator) supports EIP-2612\n * gasless Permit2 approval. The client will populate the info with the\n * actual permit signature data.\n *\n * @returns An object keyed by the extension identifier containing the extension declaration\n *\n * @example\n * ```typescript\n * import { declareEip2612GasSponsoringExtension } from '@bankofai/x402-extensions';\n *\n * const routes = [\n *   {\n *     path: \"/api/data\",\n *     price: \"$0.01\",\n *     extensions: {\n *       ...declareEip2612GasSponsoringExtension(),\n *     },\n *   },\n * ];\n * ```\n */\nexport function declareEip2612GasSponsoringExtension(): Record<\n  string,\n  Eip2612GasSponsoringExtension\n> {\n  const key = EIP2612_GAS_SPONSORING.key;\n  return {\n    [key]: {\n      info: {\n        description:\n          \"The facilitator accepts EIP-2612 gasless Permit to `Permit2` canonical contract.\",\n        version: \"1\",\n      },\n      schema: eip2612GasSponsoringSchema,\n    },\n  };\n}\n","/**\n * Facilitator functions for extracting and validating EIP-2612 Gas Sponsoring extension data.\n *\n * These functions help facilitators extract the EIP-2612 permit data from payment\n * payloads and validate it before calling settleWithPermit.\n */\n\nimport type { PaymentPayload } from \"@bankofai/x402-core/types\";\nimport {\n  EIP2612_GAS_SPONSORING,\n  type Eip2612GasSponsoringInfo,\n  type Eip2612GasSponsoringExtension,\n} from \"./types\";\n\n/**\n * Extracts the EIP-2612 gas sponsoring info from a payment payload's extensions.\n *\n * Returns the info if the extension is present and contains the required client-populated\n * fields (from, asset, spender, amount, nonce, deadline, signature, version).\n *\n * @param paymentPayload - The payment payload to extract from\n * @returns The EIP-2612 gas sponsoring info, or null if not present\n */\nexport function extractEip2612GasSponsoringInfo(\n  paymentPayload: PaymentPayload,\n): Eip2612GasSponsoringInfo | null {\n  if (!paymentPayload.extensions) {\n    return null;\n  }\n\n  const extension = paymentPayload.extensions[EIP2612_GAS_SPONSORING.key] as\n    | Eip2612GasSponsoringExtension\n    | undefined;\n\n  if (!extension?.info) {\n    return null;\n  }\n\n  const info = extension.info as Record<string, unknown>;\n\n  // Check that the client has populated the required fields\n  if (\n    !info.from ||\n    !info.asset ||\n    !info.spender ||\n    !info.amount ||\n    !info.nonce ||\n    !info.deadline ||\n    !info.signature ||\n    !info.version\n  ) {\n    return null;\n  }\n\n  return info as unknown as Eip2612GasSponsoringInfo;\n}\n\n/**\n * Validates that the EIP-2612 gas sponsoring info has valid format.\n *\n * Performs basic validation on the info fields:\n * - Addresses are valid hex (0x + 40 hex chars)\n * - Amount, nonce, deadline are numeric strings\n * - Signature is a hex string\n * - Version is a numeric version string\n *\n * @param info - The EIP-2612 gas sponsoring info to validate\n * @returns True if the info is valid, false otherwise\n */\nexport function validateEip2612GasSponsoringInfo(info: Eip2612GasSponsoringInfo): boolean {\n  const addressPattern = /^0x[a-fA-F0-9]{40}$/;\n  const numericPattern = /^[0-9]+$/;\n  const hexPattern = /^0x[a-fA-F0-9]+$/;\n  const versionPattern = /^[0-9]+(\\.[0-9]+)*$/;\n\n  return (\n    addressPattern.test(info.from) &&\n    addressPattern.test(info.asset) &&\n    addressPattern.test(info.spender) &&\n    numericPattern.test(info.amount) &&\n    numericPattern.test(info.nonce) &&\n    numericPattern.test(info.deadline) &&\n    hexPattern.test(info.signature) &&\n    versionPattern.test(info.version)\n  );\n}\n","/**\n * Type definitions for the ERC-20 Approval Gas Sponsoring Extension\n *\n * This extension enables gasless Permit2 approval for generic ERC-20 tokens\n * that do NOT implement EIP-2612. The client signs (but does not broadcast) a\n * raw `approve(Permit2, MaxUint256)` transaction, and the facilitator broadcasts\n * it atomically before settling the Permit2 payment.\n */\n\nimport type { FacilitatorExtension } from \"@bankofai/x402-core/types\";\n\n/**\n * Signer capability carried by the ERC-20 approval extension when registered in a facilitator.\n *\n * Mirrors FacilitatorEvmSigner (from @bankofai/x402-evm) plus `sendRawTransaction`.\n * The extension signer owns the full approve+settle flow: it broadcasts the\n * pre-signed approval transaction AND executes the Permit2 settle call, enabling\n * production implementations to bundle both atomically (e.g., Flashbots, multicall).\n *\n * The method signatures are duplicated here (rather than extending FacilitatorEvmSigner)\n * to avoid a circular dependency between @bankofai/x402-extensions and @bankofai/x402-evm.\n */\nexport interface Erc20ApprovalGasSponsoringSigner {\n  getAddresses(): readonly `0x${string}`[];\n  readContract(args: {\n    address: `0x${string}`;\n    abi: readonly unknown[];\n    functionName: string;\n    args?: readonly unknown[];\n  }): Promise<unknown>;\n  verifyTypedData(args: {\n    address: `0x${string}`;\n    domain: Record<string, unknown>;\n    types: Record<string, unknown>;\n    primaryType: string;\n    message: Record<string, unknown>;\n    signature: `0x${string}`;\n  }): Promise<boolean>;\n  writeContract(args: {\n    address: `0x${string}`;\n    abi: readonly unknown[];\n    functionName: string;\n    args: readonly unknown[];\n  }): Promise<`0x${string}`>;\n  sendTransaction(args: { to: `0x${string}`; data: `0x${string}` }): Promise<`0x${string}`>;\n  waitForTransactionReceipt(args: { hash: `0x${string}` }): Promise<{ status: string }>;\n  getCode(args: { address: `0x${string}` }): Promise<`0x${string}` | undefined>;\n  sendRawTransaction(args: { serializedTransaction: `0x${string}` }): Promise<`0x${string}`>;\n}\n\n/**\n * Extension identifier for the ERC-20 approval gas sponsoring extension.\n */\nexport const ERC20_APPROVAL_GAS_SPONSORING = {\n  key: \"erc20ApprovalGasSponsoring\",\n} as const satisfies FacilitatorExtension;\n\n/** Current schema version for the ERC-20 approval gas sponsoring extension info. */\nexport const ERC20_APPROVAL_GAS_SPONSORING_VERSION = \"1\";\n\n/**\n * Extended extension object registered in a facilitator via registerExtension().\n * Carries the signer that owns the full approve+settle flow for ERC-20 tokens\n * that lack EIP-2612. The signer must have all FacilitatorEvmSigner capabilities\n * plus `sendRawTransaction` for broadcasting the pre-signed approval tx.\n *\n * @example\n * ```typescript\n * import { createErc20ApprovalGasSponsoringExtension } from '@bankofai/x402-extensions';\n *\n * facilitator.registerExtension(\n *   createErc20ApprovalGasSponsoringExtension(evmSigner, viemClient),\n * );\n * ```\n */\nexport interface Erc20ApprovalGasSponsoringFacilitatorExtension extends FacilitatorExtension {\n  key: \"erc20ApprovalGasSponsoring\";\n  /** Signer with broadcast + settle capability. Optional — settlement fails gracefully if absent. */\n  signer?: Erc20ApprovalGasSponsoringSigner;\n}\n\n/**\n * Signer input for {@link createErc20ApprovalGasSponsoringExtension}.\n * Matches the FacilitatorEvmSigner shape from @bankofai/x402-evm (duplicated to avoid circular dep).\n */\nexport type Erc20ApprovalGasSponsoringBaseSigner = Omit<\n  Erc20ApprovalGasSponsoringSigner,\n  \"sendRawTransaction\"\n>;\n\n/**\n * Create an ERC-20 approval gas sponsoring extension ready to register in a facilitator.\n *\n * @param signer - The EVM facilitator signer (e.g. from `toFacilitatorEvmSigner()`)\n * @param client - Object providing `sendRawTransaction` (e.g. a viem WalletClient)\n * @param client.sendRawTransaction - Broadcasts a signed transaction to the network\n * @returns A fully configured extension to pass to `facilitator.registerExtension()`\n */\nexport function createErc20ApprovalGasSponsoringExtension(\n  signer: Erc20ApprovalGasSponsoringBaseSigner,\n  client: {\n    sendRawTransaction: (args: { serializedTransaction: `0x${string}` }) => Promise<`0x${string}`>;\n  },\n): Erc20ApprovalGasSponsoringFacilitatorExtension {\n  return {\n    ...ERC20_APPROVAL_GAS_SPONSORING,\n    signer: {\n      ...signer,\n      sendRawTransaction: client.sendRawTransaction.bind(client),\n    },\n  };\n}\n\n/**\n * ERC-20 approval gas sponsoring info populated by the client.\n *\n * Contains the RLP-encoded signed `approve(Permit2, MaxUint256)` transaction\n * that the facilitator broadcasts before settling the Permit2 payment.\n *\n * Note: Unlike EIP-2612, there is no nonce/deadline/signature — instead the\n * entire signed transaction is included as `signedTransaction`.\n */\nexport interface Erc20ApprovalGasSponsoringInfo {\n  /** Index signature for compatibility with Record<string, unknown> */\n  [key: string]: unknown;\n  /** The address of the sender (token owner who signed the tx). */\n  from: `0x${string}`;\n  /** The address of the ERC-20 token contract. */\n  asset: `0x${string}`;\n  /** The address of the spender (Canonical Permit2). */\n  spender: `0x${string}`;\n  /** The amount approved (uint256 as decimal string). Always MaxUint256. */\n  amount: string;\n  /** The RLP-encoded signed EIP-1559 transaction as a hex string. */\n  signedTransaction: `0x${string}`;\n  /** Schema version identifier. */\n  version: string;\n}\n\n/**\n * Server-side ERC-20 approval gas sponsoring info included in PaymentRequired.\n * Contains a description and version; the client populates the rest.\n */\nexport interface Erc20ApprovalGasSponsoringServerInfo {\n  /** Index signature for compatibility with Record<string, unknown> */\n  [key: string]: unknown;\n  /** Human-readable description of the extension. */\n  description: string;\n  /** Schema version identifier. */\n  version: string;\n}\n\n/**\n * The full extension object as it appears in PaymentRequired.extensions\n * and PaymentPayload.extensions.\n */\nexport interface Erc20ApprovalGasSponsoringExtension {\n  /** Extension info - server-provided or client-enriched. */\n  info: Erc20ApprovalGasSponsoringServerInfo | Erc20ApprovalGasSponsoringInfo;\n  /** JSON Schema describing the expected structure of info. */\n  schema: Record<string, unknown>;\n}\n","/**\n * Resource Service functions for declaring the ERC-20 Approval Gas Sponsoring extension.\n *\n * These functions help servers declare support for ERC-20 approval gas sponsoring\n * in the PaymentRequired response extensions. Use this for tokens that do NOT\n * implement EIP-2612 (generic ERC-20 tokens).\n */\n\nimport {\n  ERC20_APPROVAL_GAS_SPONSORING,\n  ERC20_APPROVAL_GAS_SPONSORING_VERSION,\n  type Erc20ApprovalGasSponsoringExtension,\n} from \"./types\";\n\n/**\n * The JSON Schema for the ERC-20 approval gas sponsoring extension info.\n * Matches the schema defined in the spec.\n */\nexport const erc20ApprovalGasSponsoringSchema: Record<string, unknown> = {\n  $schema: \"https://json-schema.org/draft/2020-12/schema\",\n  type: \"object\",\n  properties: {\n    from: {\n      type: \"string\",\n      pattern: \"^0x[a-fA-F0-9]{40}$\",\n      description: \"The address of the sender (token owner).\",\n    },\n    asset: {\n      type: \"string\",\n      pattern: \"^0x[a-fA-F0-9]{40}$\",\n      description: \"The address of the ERC-20 token contract.\",\n    },\n    spender: {\n      type: \"string\",\n      pattern: \"^0x[a-fA-F0-9]{40}$\",\n      description: \"The address of the spender (Canonical Permit2).\",\n    },\n    amount: {\n      type: \"string\",\n      pattern: \"^[0-9]+$\",\n      description: \"The amount approved (uint256). Always MaxUint256.\",\n    },\n    signedTransaction: {\n      type: \"string\",\n      pattern: \"^0x[a-fA-F0-9]+$\",\n      description: \"The RLP-encoded signed EIP-1559 transaction as a hex string.\",\n    },\n    version: {\n      type: \"string\",\n      pattern: \"^[0-9]+(\\\\.[0-9]+)*$\",\n      description: \"Schema version identifier.\",\n    },\n  },\n  required: [\"from\", \"asset\", \"spender\", \"amount\", \"signedTransaction\", \"version\"],\n};\n\n/**\n * Declares the ERC-20 approval gas sponsoring extension for inclusion in\n * PaymentRequired.extensions.\n *\n * The server advertises that it (or its facilitator) supports broadcasting\n * a pre-signed `approve(Permit2, MaxUint256)` transaction on the client's behalf.\n * Use this for tokens that do NOT implement EIP-2612.\n *\n * @returns An object keyed by the extension identifier containing the extension declaration\n *\n * @example\n * ```typescript\n * import { declareErc20ApprovalGasSponsoringExtension } from '@bankofai/x402-extensions';\n *\n * const routes = [\n *   {\n *     path: \"/api/data\",\n *     price: { amount: \"1000\", asset: \"0x...\", extra: { assetTransferMethod: \"permit2\" } },\n *     extensions: {\n *       ...declareErc20ApprovalGasSponsoringExtension(),\n *     },\n *   },\n * ];\n * ```\n */\nexport function declareErc20ApprovalGasSponsoringExtension(): Record<\n  string,\n  Erc20ApprovalGasSponsoringExtension\n> {\n  const key = ERC20_APPROVAL_GAS_SPONSORING.key;\n  return {\n    [key]: {\n      info: {\n        description:\n          \"The facilitator broadcasts a pre-signed ERC-20 approve() transaction to grant Permit2 allowance.\",\n        version: ERC20_APPROVAL_GAS_SPONSORING_VERSION,\n      },\n      schema: erc20ApprovalGasSponsoringSchema,\n    },\n  };\n}\n","/**\n * Facilitator functions for extracting and validating ERC-20 Approval Gas Sponsoring\n * extension data.\n *\n * These functions help facilitators extract the pre-signed approve() transaction\n * from payment payloads and validate it before broadcasting and settling.\n */\n\nimport Ajv from \"ajv/dist/2020.js\";\nimport type { PaymentPayload } from \"@bankofai/x402-core/types\";\nimport {\n  ERC20_APPROVAL_GAS_SPONSORING,\n  type Erc20ApprovalGasSponsoringInfo,\n  type Erc20ApprovalGasSponsoringExtension,\n} from \"./types\";\nimport { erc20ApprovalGasSponsoringSchema } from \"./resourceService\";\n\n/**\n * Extracts the ERC-20 approval gas sponsoring info from a payment payload's extensions.\n *\n * Performs structural extraction only — checks that the extension is present and\n * contains all required fields. Does NOT validate field formats (use\n * validateErc20ApprovalGasSponsoringInfo for that).\n *\n * @param paymentPayload - The payment payload to extract from\n * @returns The ERC-20 approval gas sponsoring info, or null if not present\n */\nexport function extractErc20ApprovalGasSponsoringInfo(\n  paymentPayload: PaymentPayload,\n): Erc20ApprovalGasSponsoringInfo | null {\n  if (!paymentPayload.extensions) {\n    return null;\n  }\n\n  const extension = paymentPayload.extensions[ERC20_APPROVAL_GAS_SPONSORING.key] as\n    | Erc20ApprovalGasSponsoringExtension\n    | undefined;\n\n  if (!extension?.info) {\n    return null;\n  }\n\n  const info = extension.info as Record<string, unknown>;\n\n  if (\n    !info.from ||\n    !info.asset ||\n    !info.spender ||\n    !info.amount ||\n    !info.signedTransaction ||\n    !info.version\n  ) {\n    return null;\n  }\n\n  return info as unknown as Erc20ApprovalGasSponsoringInfo;\n}\n\n/**\n * Validates that the ERC-20 approval gas sponsoring info has valid format.\n *\n * Validates the info against the canonical JSON Schema, checking:\n * - All required fields are present\n * - Addresses are valid hex (0x + 40 hex chars)\n * - Amount is a numeric string\n * - signedTransaction is a hex string\n * - Version is a numeric version string\n *\n * @param info - The ERC-20 approval gas sponsoring info to validate\n * @returns True if the info is valid, false otherwise\n */\nexport function validateErc20ApprovalGasSponsoringInfo(\n  info: Erc20ApprovalGasSponsoringInfo,\n): boolean {\n  const ajv = new Ajv({ strict: false, allErrors: true });\n  const validate = ajv.compile(erc20ApprovalGasSponsoringSchema);\n  return validate(info) as boolean;\n}\n"],"mappings":"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","names":[]}

package/dist/esm/payment-identifier/index.d.mts

@@ -0,0 +1,345 @@
+import { ResourceServerExtension, PaymentPayload } from '@bankofai/x402-core/types';
+
+/**
+ * Type definitions for the Payment-Identifier Extension
+ *
+ * Enables clients to provide an idempotency key that resource servers
+ * can use for deduplication of payment requests.
+ */
+/**
+ * Extension identifier constant for the payment-identifier extension
+ */
+declare const PAYMENT_IDENTIFIER = "payment-identifier";
+/**
+ * Minimum length for payment identifier
+ */
+declare const PAYMENT_ID_MIN_LENGTH = 16;
+/**
+ * Maximum length for payment identifier
+ */
+declare const PAYMENT_ID_MAX_LENGTH = 128;
+/**
+ * Pattern for valid payment identifier characters (alphanumeric, hyphens, underscores)
+ */
+declare const PAYMENT_ID_PATTERN: RegExp;
+/**
+ * Payment identifier info containing the required flag and client-provided ID
+ */
+interface PaymentIdentifierInfo {
+    /**
+     * Whether the server requires clients to include a payment identifier.
+     * When true, clients must provide an `id` or receive a 400 Bad Request.
+     */
+    required: boolean;
+    /**
+     * Client-provided unique identifier for idempotency.
+     * Must be 16-128 characters, alphanumeric with hyphens and underscores allowed.
+     */
+    id?: string;
+}
+/**
+ * Payment identifier extension with info and schema.
+ *
+ * Used both for server-side declarations (info without id) and
+ * client-side payloads (info with id).
+ */
+interface PaymentIdentifierExtension {
+    /**
+     * The payment identifier info.
+     * Server declarations have required only, clients add the id.
+     */
+    info: PaymentIdentifierInfo;
+    /**
+     * JSON Schema validating the info structure
+     */
+    schema: PaymentIdentifierSchema;
+}
+/**
+ * JSON Schema type for the payment-identifier extension
+ */
+interface PaymentIdentifierSchema {
+    $schema: "https://json-schema.org/draft/2020-12/schema";
+    type: "object";
+    properties: {
+        required: {
+            type: "boolean";
+        };
+        id: {
+            type: "string";
+            minLength: number;
+            maxLength: number;
+            pattern: string;
+        };
+    };
+    required: ["required"];
+}
+
+/**
+ * JSON Schema definitions for the Payment-Identifier Extension
+ */
+
+/**
+ * JSON Schema for validating payment identifier info.
+ * Compliant with JSON Schema Draft 2020-12.
+ */
+declare const paymentIdentifierSchema: PaymentIdentifierSchema;
+
+/**
+ * Utility functions for the Payment-Identifier Extension
+ */
+/**
+ * Generates a unique payment identifier.
+ *
+ * @param prefix - Optional prefix for the ID (e.g., "pay_"). Defaults to "pay_".
+ * @returns A unique payment identifier string
+ *
+ * @example
+ * ```typescript
+ * // With default prefix
+ * const id = generatePaymentId(); // "pay_7d5d747be160e280504c099d984bcfe0"
+ *
+ * // With custom prefix
+ * const id = generatePaymentId("txn_"); // "txn_7d5d747be160e280504c099d984bcfe0"
+ *
+ * // Without prefix
+ * const id = generatePaymentId(""); // "7d5d747be160e280504c099d984bcfe0"
+ * ```
+ */
+declare function generatePaymentId(prefix?: string): string;
+/**
+ * Validates that a payment ID meets the format requirements.
+ *
+ * @param id - The payment ID to validate
+ * @returns True if the ID is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidPaymentId("pay_7d5d747be160e280"); // true (exactly 16 chars after prefix removal check)
+ * isValidPaymentId("abc"); // false (too short)
+ * isValidPaymentId("pay_abc!@#"); // false (invalid characters)
+ * ```
+ */
+declare function isValidPaymentId(id: string): boolean;
+
+/**
+ * Client-side utilities for the Payment-Identifier Extension
+ */
+/**
+ * Appends a payment identifier to the extensions object if the server declared support.
+ *
+ * This function reads the server's `payment-identifier` declaration from the extensions,
+ * and appends the client's ID to it. If the extension is not present (server didn't declare it),
+ * the extensions are returned unchanged.
+ *
+ * @param extensions - The extensions object from PaymentRequired (will be modified in place)
+ * @param id - Optional custom payment ID. If not provided, a new ID will be generated.
+ * @returns The modified extensions object (same reference as input)
+ * @throws Error if the provided ID is invalid
+ *
+ * @example
+ * ```typescript
+ * import { appendPaymentIdentifierToExtensions } from '@bankofai/x402-extensions/payment-identifier';
+ *
+ * // Get extensions from server's PaymentRequired response
+ * const extensions = paymentRequired.extensions ?? {};
+ *
+ * // Append a generated ID (only if server declared payment-identifier)
+ * appendPaymentIdentifierToExtensions(extensions);
+ *
+ * // Or use a custom ID
+ * appendPaymentIdentifierToExtensions(extensions, "pay_my_custom_id_12345");
+ *
+ * // Include in PaymentPayload
+ * const paymentPayload = {
+ *   x402Version: 2,
+ *   resource: paymentRequired.resource,
+ *   accepted: selectedPaymentOption,
+ *   payload: { ... },
+ *   extensions
+ * };
+ * ```
+ */
+declare function appendPaymentIdentifierToExtensions(extensions: Record<string, unknown>, id?: string): Record<string, unknown>;
+
+/**
+ * Resource Server utilities for the Payment-Identifier Extension
+ */
+
+/**
+ * Declares the payment-identifier extension for inclusion in PaymentRequired.extensions.
+ *
+ * Resource servers call this function to advertise support for payment identifiers.
+ * The declaration indicates whether a payment identifier is required and includes
+ * the schema that clients must follow.
+ *
+ * @param required - Whether clients must provide a payment identifier. Defaults to false.
+ * @returns A PaymentIdentifierExtension object ready for PaymentRequired.extensions
+ *
+ * @example
+ * ```typescript
+ * import { declarePaymentIdentifierExtension, PAYMENT_IDENTIFIER } from '@bankofai/x402-extensions/payment-identifier';
+ *
+ * // Include in PaymentRequired response (optional identifier)
+ * const paymentRequired = {
+ *   x402Version: 2,
+ *   resource: { ... },
+ *   accepts: [ ... ],
+ *   extensions: {
+ *     [PAYMENT_IDENTIFIER]: declarePaymentIdentifierExtension()
+ *   }
+ * };
+ *
+ * // Require payment identifier
+ * const paymentRequiredStrict = {
+ *   x402Version: 2,
+ *   resource: { ... },
+ *   accepts: [ ... ],
+ *   extensions: {
+ *     [PAYMENT_IDENTIFIER]: declarePaymentIdentifierExtension(true)
+ *   }
+ * };
+ * ```
+ */
+declare function declarePaymentIdentifierExtension(required?: boolean): PaymentIdentifierExtension;
+/**
+ * ResourceServerExtension implementation for payment-identifier.
+ *
+ * This extension doesn't require any enrichment hooks since the declaration
+ * is static. It's provided for consistency with other extensions and for
+ * potential future use with the extension registration system.
+ *
+ * @example
+ * ```typescript
+ * import { paymentIdentifierResourceServerExtension } from '@bankofai/x402-extensions/payment-identifier';
+ *
+ * resourceServer.registerExtension(paymentIdentifierResourceServerExtension);
+ * ```
+ */
+declare const paymentIdentifierResourceServerExtension: ResourceServerExtension;
+
+/**
+ * Validation and extraction utilities for the Payment-Identifier Extension
+ */
+
+/**
+ * Type guard to check if an object is a valid payment-identifier extension structure.
+ *
+ * This checks for the basic structure (info object with required boolean),
+ * but does not validate the id format if present.
+ *
+ * @param extension - The object to check
+ * @returns True if the object has the expected payment-identifier extension structure
+ *
+ * @example
+ * ```typescript
+ * if (isPaymentIdentifierExtension(extensions["payment-identifier"])) {
+ *   // TypeScript knows this is PaymentIdentifierExtension
+ *   console.log(extension.info.required);
+ * }
+ * ```
+ */
+declare function isPaymentIdentifierExtension(extension: unknown): extension is PaymentIdentifierExtension;
+/**
+ * Result of payment identifier validation
+ */
+interface PaymentIdentifierValidationResult {
+    /**
+     * Whether the payment identifier is valid
+     */
+    valid: boolean;
+    /**
+     * Error messages if validation failed
+     */
+    errors?: string[];
+}
+/**
+ * Validates a payment-identifier extension object.
+ *
+ * Checks both the structure (using JSON Schema) and the ID format.
+ *
+ * @param extension - The extension object to validate
+ * @returns Validation result with errors if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = validatePaymentIdentifier(paymentPayload.extensions?.["payment-identifier"]);
+ * if (!result.valid) {
+ *   console.error("Invalid payment identifier:", result.errors);
+ * }
+ * ```
+ */
+declare function validatePaymentIdentifier(extension: unknown): PaymentIdentifierValidationResult;
+/**
+ * Extracts the payment identifier from a PaymentPayload.
+ *
+ * @param paymentPayload - The payment payload to extract from
+ * @param validate - Whether to validate the ID before returning (default: true)
+ * @returns The payment ID string, or null if not present or invalid
+ *
+ * @example
+ * ```typescript
+ * const id = extractPaymentIdentifier(paymentPayload);
+ * if (id) {
+ *   // Use for idempotency lookup
+ *   const cached = await idempotencyStore.get(id);
+ * }
+ * ```
+ */
+declare function extractPaymentIdentifier(paymentPayload: PaymentPayload, validate?: boolean): string | null;
+/**
+ * Extracts and validates the payment identifier from a PaymentPayload.
+ *
+ * @param paymentPayload - The payment payload to extract from
+ * @returns Object with the ID and validation result
+ *
+ * @example
+ * ```typescript
+ * const { id, validation } = extractAndValidatePaymentIdentifier(paymentPayload);
+ * if (!validation.valid) {
+ *   return res.status(400).json({ error: validation.errors });
+ * }
+ * if (id) {
+ *   // Use for idempotency
+ * }
+ * ```
+ */
+declare function extractAndValidatePaymentIdentifier(paymentPayload: PaymentPayload): {
+    id: string | null;
+    validation: PaymentIdentifierValidationResult;
+};
+/**
+ * Checks if a PaymentPayload contains a payment-identifier extension.
+ *
+ * @param paymentPayload - The payment payload to check
+ * @returns True if the extension is present
+ */
+declare function hasPaymentIdentifier(paymentPayload: PaymentPayload): boolean;
+/**
+ * Checks if the server requires a payment identifier based on the extension info.
+ *
+ * @param extension - The payment-identifier extension from PaymentRequired or PaymentPayload
+ * @returns True if the server requires a payment identifier
+ */
+declare function isPaymentIdentifierRequired(extension: unknown): boolean;
+/**
+ * Validates that a payment identifier is provided when required.
+ *
+ * Use this to check if a client's PaymentPayload satisfies the server's requirement.
+ *
+ * @param paymentPayload - The client's payment payload
+ * @param serverRequired - Whether the server requires a payment identifier (from PaymentRequired)
+ * @returns Validation result - invalid if required but not provided
+ *
+ * @example
+ * ```typescript
+ * const serverExtension = paymentRequired.extensions?.["payment-identifier"];
+ * const serverRequired = isPaymentIdentifierRequired(serverExtension);
+ * const result = validatePaymentIdentifierRequirement(paymentPayload, serverRequired);
+ * if (!result.valid) {
+ *   return res.status(400).json({ error: result.errors });
+ * }
+ * ```
+ */
+declare function validatePaymentIdentifierRequirement(paymentPayload: PaymentPayload, serverRequired: boolean): PaymentIdentifierValidationResult;
+
+export { PAYMENT_IDENTIFIER, PAYMENT_ID_MAX_LENGTH, PAYMENT_ID_MIN_LENGTH, PAYMENT_ID_PATTERN, type PaymentIdentifierExtension, type PaymentIdentifierInfo, type PaymentIdentifierSchema, type PaymentIdentifierValidationResult, appendPaymentIdentifierToExtensions, declarePaymentIdentifierExtension, extractAndValidatePaymentIdentifier, extractPaymentIdentifier, generatePaymentId, hasPaymentIdentifier, isPaymentIdentifierExtension, isPaymentIdentifierRequired, isValidPaymentId, paymentIdentifierResourceServerExtension, paymentIdentifierSchema, validatePaymentIdentifier, validatePaymentIdentifierRequirement };

package/dist/esm/payment-identifier/index.mjs

@@ -0,0 +1,39 @@
+import {
+  PAYMENT_IDENTIFIER,
+  PAYMENT_ID_MAX_LENGTH,
+  PAYMENT_ID_MIN_LENGTH,
+  PAYMENT_ID_PATTERN,
+  appendPaymentIdentifierToExtensions,
+  declarePaymentIdentifierExtension,
+  extractAndValidatePaymentIdentifier,
+  extractPaymentIdentifier,
+  generatePaymentId,
+  hasPaymentIdentifier,
+  isPaymentIdentifierExtension,
+  isPaymentIdentifierRequired,
+  isValidPaymentId,
+  paymentIdentifierResourceServerExtension,
+  paymentIdentifierSchema,
+  validatePaymentIdentifier,
+  validatePaymentIdentifierRequirement
+} from "../chunk-RERA4OZZ.mjs";
+export {
+  PAYMENT_IDENTIFIER,
+  PAYMENT_ID_MAX_LENGTH,
+  PAYMENT_ID_MIN_LENGTH,
+  PAYMENT_ID_PATTERN,
+  appendPaymentIdentifierToExtensions,
+  declarePaymentIdentifierExtension,
+  extractAndValidatePaymentIdentifier,
+  extractPaymentIdentifier,
+  generatePaymentId,
+  hasPaymentIdentifier,
+  isPaymentIdentifierExtension,
+  isPaymentIdentifierRequired,
+  isValidPaymentId,
+  paymentIdentifierResourceServerExtension,
+  paymentIdentifierSchema,
+  validatePaymentIdentifier,
+  validatePaymentIdentifierRequirement
+};
+//# sourceMappingURL=index.mjs.map

package/dist/esm/payment-identifier/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}