@inflowpayai/x402 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Jarwin, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @inflowpayai/x402
+
+Core types, HTTP client, and shared constants for the [InFlow x402 SDK](https://github.com/inflowpayai/inflow-node/tree/main/docs/x402).
+
+This package is a transitive dependency of `@inflowpayai/x402-seller*` and `@inflowpayai/x402-buyer*`. Most integrations don't install it directly.
+
+## Install
+
+```bash
+pnpm add @inflowpayai/x402 @x402/core
+```
+
+`@x402/core` is a peer dependency. Co-install it on the consumer side so package managers can warn loudly when it's missing.
+
+## What's exported
+
+### Main entry — `@inflowpayai/x402`
+
+- `InflowHttpClient` — the shared HTTP client used by every other package in this monorepo. Carries `X-API-KEY` injection, JSON parsing,
+  per-request timeout, retry on transient statuses (`429`, `502`, `503`, `504`) with exponential backoff capped at three attempts, and error
+  mapping into `InflowApiError`.
+- `resolveBaseUrl(options)` — returns the API base URL for an `Environment` (`'production' | 'sandbox'`) or a `baseUrl` override.
+- `InflowApiError`, `X402VersionMismatchError` — typed errors raised by the client.
+- Constants — `X402_VERSION`, `HEADERS`, `SCHEMES`, `NETWORKS`, `CONTRACTS`, `EXTRA_KEYS`, `PAYLOAD_KEYS`, `ASSET_TRANSFER_METHODS`.
+- Wire-shape types — `PaymentRequirements`, `PaymentRequired`, `SettleResponse`, `VerifyResponse`, `ResourceInfo`, `PaymentScheme`, `InstrumentType`.
+- InFlow-specific types — `X402ConfigResponse`, `X402AssetInfo`, `X402WalletInfo`, `PaymentMethodInfo`,
+  `X402FacilitatorSupportedResponse`, `X402BuyerSupportedResponse`, `X402SupportedKind`, `InflowPaymentPayload`, `BalancePayloadData`,
+  `ExactPayloadData`, `Permit2PayloadData`, `InstrumentPayloadData`.
+- Narrowing helpers — `isBalancePayload`, `isExactPayload`, `isPermit2Payload`, `isInstrumentPayload`.
+- `readHeader(headers, name)` — case-insensitive header read for WHATWG `Headers`, Node `IncomingHttpHeaders`-style records, or plain
+  `Record<string, string | string[] | undefined>`.
+
+### `@inflowpayai/x402/extensions`
+
+- `ExtensionHandler<TDecl, TPayloadEntry>` — pluggable handler contract.
+- `PAYMENT_IDENTIFIER` — handler for the `payment-identifier` extension.
+- `validatePaymentId(id)` / `generatePaymentId(prefix?)` — format validation and generation.
+- `getExtension<TDecl>(extensions, handler)` / `setExtension<TDecl>(extensions, handler, value)` — typed accessor
+  helpers for `PaymentRequired.extensions` / `PaymentPayload.extensions`.
+- `EXTENSION_REGISTRY` — registry of every handler the SDK ships with, keyed by extension name.
+
+### `@inflowpayai/x402/extras`
+
+- `getExtra<T>(extra, key)` / `setExtra<T>(extra, key, value)` — open-key analogs of the extension helpers, for `PaymentRequirements.extra`,
+  `PaymentMethodInfo.extra`, and similar bag fields.
+
+### `@inflowpayai/x402/security`
+
+- `timingSafeEqualStrings(a, b)` — constant-time string equality.
+
+## Example — `InflowHttpClient`
+
+```ts
+import { InflowHttpClient, InflowApiError } from '@inflowpayai/x402';
+
+const http = new InflowHttpClient({
+  apiKey: process.env.INFLOW_API_KEY!,
+  environment: 'sandbox',
+});
+
+try {
+  const config = await http.get('/v1/x402/config');
+  console.log(config);
+} catch (err) {
+  if (err instanceof InflowApiError) {
+    console.error(`[${err.requestId ?? '-'}] ${err.code} (${err.httpStatus})`);
+  } else {
+    throw err;
+  }
+}
+```
+
+## See also
+
+- [@inflowpayai/x402-seller](../x402-seller) — framework-agnostic seller core
+- [@inflowpayai/x402-buyer](../x402-buyer) — framework-agnostic buyer core
+- [Product overview](../../docs/x402/README.md)
+- [Architecture](../../docs/x402/architecture.md) — InFlow vs. foundation responsibilities, request lifecycle, conflict precedence
+- [Wire-format mapping](../../docs/x402/protocol-mapping.md) — types, headers, network rules, decimals
+- [Extensions](../../docs/x402/extensions.md) — `payment-identifier` end-to-end
+
+## License
+
+MIT.

package/dist/extensions/index.cjs

@@ -0,0 +1,78 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/extensions/payment-identifier.ts
+var EXTENSION_PAYMENT_IDENTIFIER = "payment-identifier";
+var PAYMENT_ID_MIN_LENGTH = 16;
+var PAYMENT_ID_MAX_LENGTH = 128;
+var PAYMENT_ID_REGEX = /^[a-zA-Z0-9_-]+$/u;
+var PAYMENT_ID_PREFIX_REGEX = /^[a-zA-Z0-9_-]*$/u;
+var PAYMENT_ID_DEFAULT_PREFIX = "pay_";
+function validatePaymentId(id) {
+  if (typeof id !== "string") return false;
+  if (id.length < PAYMENT_ID_MIN_LENGTH || id.length > PAYMENT_ID_MAX_LENGTH) return false;
+  return PAYMENT_ID_REGEX.test(id);
+}
+function generatePaymentId(prefix = PAYMENT_ID_DEFAULT_PREFIX) {
+  if (typeof prefix !== "string" || !PAYMENT_ID_PREFIX_REGEX.test(prefix)) {
+    throw new Error(`generatePaymentId: prefix "${prefix}" contains characters outside ${PAYMENT_ID_REGEX.source}`);
+  }
+  const suffix = crypto.randomBytes(16).toString("hex");
+  const id = `${prefix}${suffix}`;
+  if (id.length < PAYMENT_ID_MIN_LENGTH || id.length > PAYMENT_ID_MAX_LENGTH) {
+    throw new Error(
+      `generatePaymentId: result length ${id.length} is outside [${PAYMENT_ID_MIN_LENGTH}, ${PAYMENT_ID_MAX_LENGTH}]`
+    );
+  }
+  return id;
+}
+var PAYMENT_IDENTIFIER = {
+  name: EXTENSION_PAYMENT_IDENTIFIER,
+  buildDeclaration() {
+    return { required: false };
+  },
+  readDeclaration(decl) {
+    if (decl === null || typeof decl !== "object") return null;
+    const required = decl.required;
+    if (typeof required !== "boolean") return null;
+    return { required };
+  },
+  buildPayloadEntry(_declaration, context) {
+    const id = context.providedPaymentId;
+    if (id === void 0) return null;
+    if (!validatePaymentId(id)) return null;
+    return { paymentId: id };
+  }
+};
+
+// src/extensions/access.ts
+function getExtension(extensions, handler) {
+  if (extensions === void 0) return void 0;
+  const raw = extensions[handler.name];
+  if (raw === void 0) return void 0;
+  return handler.readDeclaration(raw) ?? void 0;
+}
+function setExtension(extensions, handler, value) {
+  return { ...extensions ?? {}, [handler.name]: value };
+}
+
+// src/extensions/index.ts
+var ALL_EXTENSIONS = [PAYMENT_IDENTIFIER];
+var EXTENSION_REGISTRY = new Map(
+  ALL_EXTENSIONS.map((h) => [h.name, h])
+);
+
+exports.EXTENSION_PAYMENT_IDENTIFIER = EXTENSION_PAYMENT_IDENTIFIER;
+exports.EXTENSION_REGISTRY = EXTENSION_REGISTRY;
+exports.PAYMENT_IDENTIFIER = PAYMENT_IDENTIFIER;
+exports.PAYMENT_ID_DEFAULT_PREFIX = PAYMENT_ID_DEFAULT_PREFIX;
+exports.PAYMENT_ID_MAX_LENGTH = PAYMENT_ID_MAX_LENGTH;
+exports.PAYMENT_ID_MIN_LENGTH = PAYMENT_ID_MIN_LENGTH;
+exports.PAYMENT_ID_REGEX = PAYMENT_ID_REGEX;
+exports.generatePaymentId = generatePaymentId;
+exports.getExtension = getExtension;
+exports.setExtension = setExtension;
+exports.validatePaymentId = validatePaymentId;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/extensions/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/extensions/payment-identifier.ts","../../src/extensions/access.ts","../../src/extensions/index.ts"],"names":["randomBytes"],"mappings":"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","file":"index.cjs","sourcesContent":["import { randomBytes } from 'node:crypto';\n\nimport type { ExtensionHandler } from './types.js';\n\n/** Extension name on the wire — the key in `extensions[]` maps. */\nexport const EXTENSION_PAYMENT_IDENTIFIER = 'payment-identifier' as const;\n\nexport const PAYMENT_ID_MIN_LENGTH = 16;\nexport const PAYMENT_ID_MAX_LENGTH = 128;\n\n/** Regex a valid payment identifier must match. Mirrors the x402 `payment-identifier` extension spec. */\nexport const PAYMENT_ID_REGEX = /^[a-zA-Z0-9_-]+$/u;\n\n/**\n * Regex a {@link generatePaymentId} prefix must match — same character class as {@link PAYMENT_ID_REGEX}, but allows the\n * empty string.\n */\nconst PAYMENT_ID_PREFIX_REGEX = /^[a-zA-Z0-9_-]*$/u;\n\n/**\n * Default prefix used by {@link generatePaymentId}. Mirrors the format produced by InFlow's automatic\n * transaction-id-derived identifiers (`pay_<32 hex chars>`).\n */\nexport const PAYMENT_ID_DEFAULT_PREFIX = 'pay_';\n\n/** Declaration shape attached to `PaymentRequired.extensions['payment-identifier']`. */\nexport interface PaymentIdentifierDeclaration {\n  /**\n   * When `true`, the payload's `extensions['payment-identifier'].paymentId` is mandatory; settlement fails without it.\n   * When `false`, the field is optional and may be omitted.\n   */\n  required: boolean;\n}\n\n/** Payload-entry shape attached to `PaymentPayload.extensions['payment-identifier']`. */\nexport interface PaymentIdentifierPayloadEntry {\n  /** The identifier value, satisfying {@link validatePaymentId}. */\n  paymentId: string;\n}\n\n/**\n * Validate a payment-identifier string against the extension spec.\n *\n * @param id - Candidate identifier. Returns `false` for any non-string input.\n * @returns `true` when `id` is a string of length 16–128 containing only `a–z`, `A–Z`, `0–9`, `_`, and `-`. `false`\n *   otherwise.\n */\nexport function validatePaymentId(id: unknown): id is string {\n  if (typeof id !== 'string') return false;\n  if (id.length < PAYMENT_ID_MIN_LENGTH || id.length > PAYMENT_ID_MAX_LENGTH) return false;\n  return PAYMENT_ID_REGEX.test(id);\n}\n\n/**\n * Generate a new payment identifier.\n *\n * @param prefix - String prefix prepended to a random 32-character hex suffix. Defaults to `'pay_'`. Must satisfy\n *   `^[a-zA-Z0-9_-]*$` and yield a total length of 16–128 when combined with the suffix.\n * @returns A string of the form `<prefix><32 hex chars>` (lowercase).\n * @throws {Error} When `prefix` contains characters not allowed by {@link PAYMENT_ID_REGEX} or the resulting identifier\n *   falls outside the 16–128-character bound.\n */\nexport function generatePaymentId(prefix: string = PAYMENT_ID_DEFAULT_PREFIX): string {\n  if (typeof prefix !== 'string' || !PAYMENT_ID_PREFIX_REGEX.test(prefix)) {\n    throw new Error(`generatePaymentId: prefix \"${prefix}\" contains characters outside ${PAYMENT_ID_REGEX.source}`);\n  }\n  const suffix = randomBytes(16).toString('hex');\n  const id = `${prefix}${suffix}`;\n  if (id.length < PAYMENT_ID_MIN_LENGTH || id.length > PAYMENT_ID_MAX_LENGTH) {\n    throw new Error(\n      `generatePaymentId: result length ${id.length} is outside [${PAYMENT_ID_MIN_LENGTH}, ${PAYMENT_ID_MAX_LENGTH}]`,\n    );\n  }\n  return id;\n}\n\n/**\n * Handler for the x402 `payment-identifier` extension. Used by the seller (`inflowAccepts`) and the buyer (signer flows\n * that compose external `x402Client` signers).\n */\nexport const PAYMENT_IDENTIFIER: ExtensionHandler<PaymentIdentifierDeclaration, PaymentIdentifierPayloadEntry> = {\n  name: EXTENSION_PAYMENT_IDENTIFIER,\n  buildDeclaration(): PaymentIdentifierDeclaration {\n    return { required: false };\n  },\n  readDeclaration(decl: unknown): PaymentIdentifierDeclaration | null {\n    if (decl === null || typeof decl !== 'object') return null;\n    const required = (decl as { required?: unknown }).required;\n    if (typeof required !== 'boolean') return null;\n    return { required };\n  },\n  buildPayloadEntry(_declaration, context): PaymentIdentifierPayloadEntry | null {\n    const id = context.providedPaymentId;\n    if (id === undefined) return null;\n    if (!validatePaymentId(id)) return null;\n    return { paymentId: id };\n  },\n};\n","import type { ExtensionHandler } from './types.js';\n\n/**\n * Read a typed extension entry from an `extensions` map.\n *\n * @typeParam TDecl - Shape of the parsed declaration the handler returns.\n * @param extensions - The `extensions` record from `PaymentRequired` (or any equivalent shape). `undefined` is treated\n *   as an empty map.\n * @param handler - The {@link ExtensionHandler} that knows how to parse the entry for its own `name`.\n * @returns The parsed declaration, or `undefined` if the entry is missing or didn't match the handler's expected shape.\n */\nexport function getExtension<TDecl>(\n  extensions: Readonly<Record<string, unknown>> | undefined,\n  handler: ExtensionHandler<TDecl, unknown>,\n): TDecl | undefined {\n  if (extensions === undefined) return undefined;\n  const raw = extensions[handler.name];\n  if (raw === undefined) return undefined;\n  return handler.readDeclaration(raw) ?? undefined;\n}\n\n/**\n * Return a new `extensions` map with the handler's entry set to `value`. Never mutates the input.\n *\n * @typeParam TDecl - Shape of the declaration being written.\n * @param extensions - The existing `extensions` record, or `undefined` to start from empty.\n * @param handler - The handler whose `name` keys the entry.\n * @param value - The declaration value to write.\n * @returns A new record with `value` set under `handler.name`.\n */\nexport function setExtension<TDecl>(\n  extensions: Readonly<Record<string, unknown>> | undefined,\n  handler: ExtensionHandler<TDecl, unknown>,\n  value: TDecl,\n): Record<string, unknown> {\n  return { ...(extensions ?? {}), [handler.name]: value };\n}\n","import type { ExtensionHandler } from './types.js';\nimport { PAYMENT_IDENTIFIER } from './payment-identifier.js';\n\nexport type { DeclarationContext, ExtensionHandler, SignContext } from './types.js';\nexport { getExtension, setExtension } from './access.js';\nexport {\n  EXTENSION_PAYMENT_IDENTIFIER,\n  PAYMENT_ID_DEFAULT_PREFIX,\n  PAYMENT_ID_MAX_LENGTH,\n  PAYMENT_ID_MIN_LENGTH,\n  PAYMENT_ID_REGEX,\n  PAYMENT_IDENTIFIER,\n  generatePaymentId,\n  validatePaymentId,\n} from './payment-identifier.js';\nexport type { PaymentIdentifierDeclaration, PaymentIdentifierPayloadEntry } from './payment-identifier.js';\n\n// Source list for EXTENSION_REGISTRY below. Kept module-local: there's no public reason for consumers to iterate\n// \"all extensions\" — they look up handlers by name via EXTENSION_REGISTRY, or by importing the named handler module\n// directly. Add new extension handlers here when adding a handler module.\nconst ALL_EXTENSIONS: readonly ExtensionHandler<unknown, unknown>[] = [PAYMENT_IDENTIFIER];\n\n/**\n * Lookup table keyed by extension name. Used by the seller (`inflowAccepts`) and the buyer signer to dispatch declared\n * extensions to their handlers. Names without a registered handler are forwarded verbatim by the callers so out-of-band\n * extensions still reach the wire.\n */\nexport const EXTENSION_REGISTRY: ReadonlyMap<string, ExtensionHandler<unknown, unknown>> = new Map(\n  ALL_EXTENSIONS.map((h) => [h.name, h]),\n);\n"]}

package/dist/extensions/index.d.cts

@@ -0,0 +1,32 @@
+import { a as ExtensionHandler } from '../payment-identifier-BNYznClf.cjs';
+export { D as DeclarationContext, E as EXTENSION_PAYMENT_IDENTIFIER, P as PAYMENT_IDENTIFIER, b as PAYMENT_ID_DEFAULT_PREFIX, c as PAYMENT_ID_MAX_LENGTH, d as PAYMENT_ID_MIN_LENGTH, e as PAYMENT_ID_REGEX, f as PaymentIdentifierDeclaration, g as PaymentIdentifierPayloadEntry, S as SignContext, h as generatePaymentId, v as validatePaymentId } from '../payment-identifier-BNYznClf.cjs';
+
+/**
+ * Read a typed extension entry from an `extensions` map.
+ *
+ * @typeParam TDecl - Shape of the parsed declaration the handler returns.
+ * @param extensions - The `extensions` record from `PaymentRequired` (or any equivalent shape). `undefined` is treated
+ *   as an empty map.
+ * @param handler - The {@link ExtensionHandler} that knows how to parse the entry for its own `name`.
+ * @returns The parsed declaration, or `undefined` if the entry is missing or didn't match the handler's expected shape.
+ */
+declare function getExtension<TDecl>(extensions: Readonly<Record<string, unknown>> | undefined, handler: ExtensionHandler<TDecl, unknown>): TDecl | undefined;
+/**
+ * Return a new `extensions` map with the handler's entry set to `value`. Never mutates the input.
+ *
+ * @typeParam TDecl - Shape of the declaration being written.
+ * @param extensions - The existing `extensions` record, or `undefined` to start from empty.
+ * @param handler - The handler whose `name` keys the entry.
+ * @param value - The declaration value to write.
+ * @returns A new record with `value` set under `handler.name`.
+ */
+declare function setExtension<TDecl>(extensions: Readonly<Record<string, unknown>> | undefined, handler: ExtensionHandler<TDecl, unknown>, value: TDecl): Record<string, unknown>;
+
+/**
+ * Lookup table keyed by extension name. Used by the seller (`inflowAccepts`) and the buyer signer to dispatch declared
+ * extensions to their handlers. Names without a registered handler are forwarded verbatim by the callers so out-of-band
+ * extensions still reach the wire.
+ */
+declare const EXTENSION_REGISTRY: ReadonlyMap<string, ExtensionHandler<unknown, unknown>>;
+
+export { EXTENSION_REGISTRY, ExtensionHandler, getExtension, setExtension };

package/dist/extensions/index.d.ts

@@ -0,0 +1,32 @@
+import { a as ExtensionHandler } from '../payment-identifier-BNYznClf.js';
+export { D as DeclarationContext, E as EXTENSION_PAYMENT_IDENTIFIER, P as PAYMENT_IDENTIFIER, b as PAYMENT_ID_DEFAULT_PREFIX, c as PAYMENT_ID_MAX_LENGTH, d as PAYMENT_ID_MIN_LENGTH, e as PAYMENT_ID_REGEX, f as PaymentIdentifierDeclaration, g as PaymentIdentifierPayloadEntry, S as SignContext, h as generatePaymentId, v as validatePaymentId } from '../payment-identifier-BNYznClf.js';
+
+/**
+ * Read a typed extension entry from an `extensions` map.
+ *
+ * @typeParam TDecl - Shape of the parsed declaration the handler returns.
+ * @param extensions - The `extensions` record from `PaymentRequired` (or any equivalent shape). `undefined` is treated
+ *   as an empty map.
+ * @param handler - The {@link ExtensionHandler} that knows how to parse the entry for its own `name`.
+ * @returns The parsed declaration, or `undefined` if the entry is missing or didn't match the handler's expected shape.
+ */
+declare function getExtension<TDecl>(extensions: Readonly<Record<string, unknown>> | undefined, handler: ExtensionHandler<TDecl, unknown>): TDecl | undefined;
+/**
+ * Return a new `extensions` map with the handler's entry set to `value`. Never mutates the input.
+ *
+ * @typeParam TDecl - Shape of the declaration being written.
+ * @param extensions - The existing `extensions` record, or `undefined` to start from empty.
+ * @param handler - The handler whose `name` keys the entry.
+ * @param value - The declaration value to write.
+ * @returns A new record with `value` set under `handler.name`.
+ */
+declare function setExtension<TDecl>(extensions: Readonly<Record<string, unknown>> | undefined, handler: ExtensionHandler<TDecl, unknown>, value: TDecl): Record<string, unknown>;
+
+/**
+ * Lookup table keyed by extension name. Used by the seller (`inflowAccepts`) and the buyer signer to dispatch declared
+ * extensions to their handlers. Names without a registered handler are forwarded verbatim by the callers so out-of-band
+ * extensions still reach the wire.
+ */
+declare const EXTENSION_REGISTRY: ReadonlyMap<string, ExtensionHandler<unknown, unknown>>;
+
+export { EXTENSION_REGISTRY, ExtensionHandler, getExtension, setExtension };

package/dist/extensions/index.js

@@ -0,0 +1,66 @@
+import { randomBytes } from 'crypto';
+
+// src/extensions/payment-identifier.ts
+var EXTENSION_PAYMENT_IDENTIFIER = "payment-identifier";
+var PAYMENT_ID_MIN_LENGTH = 16;
+var PAYMENT_ID_MAX_LENGTH = 128;
+var PAYMENT_ID_REGEX = /^[a-zA-Z0-9_-]+$/u;
+var PAYMENT_ID_PREFIX_REGEX = /^[a-zA-Z0-9_-]*$/u;
+var PAYMENT_ID_DEFAULT_PREFIX = "pay_";
+function validatePaymentId(id) {
+  if (typeof id !== "string") return false;
+  if (id.length < PAYMENT_ID_MIN_LENGTH || id.length > PAYMENT_ID_MAX_LENGTH) return false;
+  return PAYMENT_ID_REGEX.test(id);
+}
+function generatePaymentId(prefix = PAYMENT_ID_DEFAULT_PREFIX) {
+  if (typeof prefix !== "string" || !PAYMENT_ID_PREFIX_REGEX.test(prefix)) {
+    throw new Error(`generatePaymentId: prefix "${prefix}" contains characters outside ${PAYMENT_ID_REGEX.source}`);
+  }
+  const suffix = randomBytes(16).toString("hex");
+  const id = `${prefix}${suffix}`;
+  if (id.length < PAYMENT_ID_MIN_LENGTH || id.length > PAYMENT_ID_MAX_LENGTH) {
+    throw new Error(
+      `generatePaymentId: result length ${id.length} is outside [${PAYMENT_ID_MIN_LENGTH}, ${PAYMENT_ID_MAX_LENGTH}]`
+    );
+  }
+  return id;
+}
+var PAYMENT_IDENTIFIER = {
+  name: EXTENSION_PAYMENT_IDENTIFIER,
+  buildDeclaration() {
+    return { required: false };
+  },
+  readDeclaration(decl) {
+    if (decl === null || typeof decl !== "object") return null;
+    const required = decl.required;
+    if (typeof required !== "boolean") return null;
+    return { required };
+  },
+  buildPayloadEntry(_declaration, context) {
+    const id = context.providedPaymentId;
+    if (id === void 0) return null;
+    if (!validatePaymentId(id)) return null;
+    return { paymentId: id };
+  }
+};
+
+// src/extensions/access.ts
+function getExtension(extensions, handler) {
+  if (extensions === void 0) return void 0;
+  const raw = extensions[handler.name];
+  if (raw === void 0) return void 0;
+  return handler.readDeclaration(raw) ?? void 0;
+}
+function setExtension(extensions, handler, value) {
+  return { ...extensions ?? {}, [handler.name]: value };
+}
+
+// src/extensions/index.ts
+var ALL_EXTENSIONS = [PAYMENT_IDENTIFIER];
+var EXTENSION_REGISTRY = new Map(
+  ALL_EXTENSIONS.map((h) => [h.name, h])
+);
+
+export { EXTENSION_PAYMENT_IDENTIFIER, EXTENSION_REGISTRY, PAYMENT_IDENTIFIER, PAYMENT_ID_DEFAULT_PREFIX, PAYMENT_ID_MAX_LENGTH, PAYMENT_ID_MIN_LENGTH, PAYMENT_ID_REGEX, generatePaymentId, getExtension, setExtension, validatePaymentId };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/extensions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/extensions/payment-identifier.ts","../../src/extensions/access.ts","../../src/extensions/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { randomBytes } from 'node:crypto';\n\nimport type { ExtensionHandler } from './types.js';\n\n/** Extension name on the wire — the key in `extensions[]` maps. */\nexport const EXTENSION_PAYMENT_IDENTIFIER = 'payment-identifier' as const;\n\nexport const PAYMENT_ID_MIN_LENGTH = 16;\nexport const PAYMENT_ID_MAX_LENGTH = 128;\n\n/** Regex a valid payment identifier must match. Mirrors the x402 `payment-identifier` extension spec. */\nexport const PAYMENT_ID_REGEX = /^[a-zA-Z0-9_-]+$/u;\n\n/**\n * Regex a {@link generatePaymentId} prefix must match — same character class as {@link PAYMENT_ID_REGEX}, but allows the\n * empty string.\n */\nconst PAYMENT_ID_PREFIX_REGEX = /^[a-zA-Z0-9_-]*$/u;\n\n/**\n * Default prefix used by {@link generatePaymentId}. Mirrors the format produced by InFlow's automatic\n * transaction-id-derived identifiers (`pay_<32 hex chars>`).\n */\nexport const PAYMENT_ID_DEFAULT_PREFIX = 'pay_';\n\n/** Declaration shape attached to `PaymentRequired.extensions['payment-identifier']`. */\nexport interface PaymentIdentifierDeclaration {\n  /**\n   * When `true`, the payload's `extensions['payment-identifier'].paymentId` is mandatory; settlement fails without it.\n   * When `false`, the field is optional and may be omitted.\n   */\n  required: boolean;\n}\n\n/** Payload-entry shape attached to `PaymentPayload.extensions['payment-identifier']`. */\nexport interface PaymentIdentifierPayloadEntry {\n  /** The identifier value, satisfying {@link validatePaymentId}. */\n  paymentId: string;\n}\n\n/**\n * Validate a payment-identifier string against the extension spec.\n *\n * @param id - Candidate identifier. Returns `false` for any non-string input.\n * @returns `true` when `id` is a string of length 16–128 containing only `a–z`, `A–Z`, `0–9`, `_`, and `-`. `false`\n *   otherwise.\n */\nexport function validatePaymentId(id: unknown): id is string {\n  if (typeof id !== 'string') return false;\n  if (id.length < PAYMENT_ID_MIN_LENGTH || id.length > PAYMENT_ID_MAX_LENGTH) return false;\n  return PAYMENT_ID_REGEX.test(id);\n}\n\n/**\n * Generate a new payment identifier.\n *\n * @param prefix - String prefix prepended to a random 32-character hex suffix. Defaults to `'pay_'`. Must satisfy\n *   `^[a-zA-Z0-9_-]*$` and yield a total length of 16–128 when combined with the suffix.\n * @returns A string of the form `<prefix><32 hex chars>` (lowercase).\n * @throws {Error} When `prefix` contains characters not allowed by {@link PAYMENT_ID_REGEX} or the resulting identifier\n *   falls outside the 16–128-character bound.\n */\nexport function generatePaymentId(prefix: string = PAYMENT_ID_DEFAULT_PREFIX): string {\n  if (typeof prefix !== 'string' || !PAYMENT_ID_PREFIX_REGEX.test(prefix)) {\n    throw new Error(`generatePaymentId: prefix \"${prefix}\" contains characters outside ${PAYMENT_ID_REGEX.source}`);\n  }\n  const suffix = randomBytes(16).toString('hex');\n  const id = `${prefix}${suffix}`;\n  if (id.length < PAYMENT_ID_MIN_LENGTH || id.length > PAYMENT_ID_MAX_LENGTH) {\n    throw new Error(\n      `generatePaymentId: result length ${id.length} is outside [${PAYMENT_ID_MIN_LENGTH}, ${PAYMENT_ID_MAX_LENGTH}]`,\n    );\n  }\n  return id;\n}\n\n/**\n * Handler for the x402 `payment-identifier` extension. Used by the seller (`inflowAccepts`) and the buyer (signer flows\n * that compose external `x402Client` signers).\n */\nexport const PAYMENT_IDENTIFIER: ExtensionHandler<PaymentIdentifierDeclaration, PaymentIdentifierPayloadEntry> = {\n  name: EXTENSION_PAYMENT_IDENTIFIER,\n  buildDeclaration(): PaymentIdentifierDeclaration {\n    return { required: false };\n  },\n  readDeclaration(decl: unknown): PaymentIdentifierDeclaration | null {\n    if (decl === null || typeof decl !== 'object') return null;\n    const required = (decl as { required?: unknown }).required;\n    if (typeof required !== 'boolean') return null;\n    return { required };\n  },\n  buildPayloadEntry(_declaration, context): PaymentIdentifierPayloadEntry | null {\n    const id = context.providedPaymentId;\n    if (id === undefined) return null;\n    if (!validatePaymentId(id)) return null;\n    return { paymentId: id };\n  },\n};\n","import type { ExtensionHandler } from './types.js';\n\n/**\n * Read a typed extension entry from an `extensions` map.\n *\n * @typeParam TDecl - Shape of the parsed declaration the handler returns.\n * @param extensions - The `extensions` record from `PaymentRequired` (or any equivalent shape). `undefined` is treated\n *   as an empty map.\n * @param handler - The {@link ExtensionHandler} that knows how to parse the entry for its own `name`.\n * @returns The parsed declaration, or `undefined` if the entry is missing or didn't match the handler's expected shape.\n */\nexport function getExtension<TDecl>(\n  extensions: Readonly<Record<string, unknown>> | undefined,\n  handler: ExtensionHandler<TDecl, unknown>,\n): TDecl | undefined {\n  if (extensions === undefined) return undefined;\n  const raw = extensions[handler.name];\n  if (raw === undefined) return undefined;\n  return handler.readDeclaration(raw) ?? undefined;\n}\n\n/**\n * Return a new `extensions` map with the handler's entry set to `value`. Never mutates the input.\n *\n * @typeParam TDecl - Shape of the declaration being written.\n * @param extensions - The existing `extensions` record, or `undefined` to start from empty.\n * @param handler - The handler whose `name` keys the entry.\n * @param value - The declaration value to write.\n * @returns A new record with `value` set under `handler.name`.\n */\nexport function setExtension<TDecl>(\n  extensions: Readonly<Record<string, unknown>> | undefined,\n  handler: ExtensionHandler<TDecl, unknown>,\n  value: TDecl,\n): Record<string, unknown> {\n  return { ...(extensions ?? {}), [handler.name]: value };\n}\n","import type { ExtensionHandler } from './types.js';\nimport { PAYMENT_IDENTIFIER } from './payment-identifier.js';\n\nexport type { DeclarationContext, ExtensionHandler, SignContext } from './types.js';\nexport { getExtension, setExtension } from './access.js';\nexport {\n  EXTENSION_PAYMENT_IDENTIFIER,\n  PAYMENT_ID_DEFAULT_PREFIX,\n  PAYMENT_ID_MAX_LENGTH,\n  PAYMENT_ID_MIN_LENGTH,\n  PAYMENT_ID_REGEX,\n  PAYMENT_IDENTIFIER,\n  generatePaymentId,\n  validatePaymentId,\n} from './payment-identifier.js';\nexport type { PaymentIdentifierDeclaration, PaymentIdentifierPayloadEntry } from './payment-identifier.js';\n\n// Source list for EXTENSION_REGISTRY below. Kept module-local: there's no public reason for consumers to iterate\n// \"all extensions\" — they look up handlers by name via EXTENSION_REGISTRY, or by importing the named handler module\n// directly. Add new extension handlers here when adding a handler module.\nconst ALL_EXTENSIONS: readonly ExtensionHandler<unknown, unknown>[] = [PAYMENT_IDENTIFIER];\n\n/**\n * Lookup table keyed by extension name. Used by the seller (`inflowAccepts`) and the buyer signer to dispatch declared\n * extensions to their handlers. Names without a registered handler are forwarded verbatim by the callers so out-of-band\n * extensions still reach the wire.\n */\nexport const EXTENSION_REGISTRY: ReadonlyMap<string, ExtensionHandler<unknown, unknown>> = new Map(\n  ALL_EXTENSIONS.map((h) => [h.name, h]),\n);\n"]}

package/dist/extras/index.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+// src/extras/access.ts
+function getExtra(extra, key) {
+  if (extra === void 0) return void 0;
+  const value = extra[key];
+  if (value === void 0) return void 0;
+  return value;
+}
+function setExtra(extra, key, value) {
+  return { ...extra ?? {}, [key]: value };
+}
+
+exports.getExtra = getExtra;
+exports.setExtra = setExtra;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/extras/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/extras/access.ts"],"names":[],"mappings":";;;AAUO,SAAS,QAAA,CACd,OACA,GAAA,EACe;AACf,EAAA,IAAI,KAAA,KAAU,QAAW,OAAO,MAAA;AAChC,EAAA,MAAM,KAAA,GAAQ,MAAM,GAAG,CAAA;AACvB,EAAA,IAAI,KAAA,KAAU,QAAW,OAAO,MAAA;AAChC,EAAA,OAAO,KAAA;AACT;AAWO,SAAS,QAAA,CACd,KAAA,EACA,GAAA,EACA,KAAA,EACyB;AACzB,EAAA,OAAO,EAAE,GAAI,KAAA,IAAS,IAAK,CAAC,GAAG,GAAG,KAAA,EAAM;AAC1C","file":"index.cjs","sourcesContent":["/**\n * Read a typed entry from an `extra` map (the open-ended record carried on `PaymentRequirements.extra`,\n * `PaymentMethodInfo.extra`, and similar).\n *\n * @typeParam T - Caller-supplied expected type of the value. The function does **not** validate at runtime; callers\n *   must narrow defensively.\n * @param extra - The `extra` record, or `undefined`.\n * @param key - Key to read.\n * @returns The raw value cast to `T`, or `undefined` if absent.\n */\nexport function getExtra<T = unknown>(\n  extra: Readonly<Record<string, unknown>> | undefined,\n  key: string,\n): T | undefined {\n  if (extra === undefined) return undefined;\n  const value = extra[key];\n  if (value === undefined) return undefined;\n  return value as T;\n}\n\n/**\n * Return a new `extra` map with `key` set to `value`. Never mutates the input.\n *\n * @typeParam T - Type of the value being written.\n * @param extra - The existing `extra` record, or `undefined` to start from empty.\n * @param key - Key to write.\n * @param value - Value to associate with `key`.\n * @returns A new record with `value` set at `key`.\n */\nexport function setExtra<T>(\n  extra: Readonly<Record<string, unknown>> | undefined,\n  key: string,\n  value: T,\n): Record<string, unknown> {\n  return { ...(extra ?? {}), [key]: value };\n}\n"]}

package/dist/extras/index.d.cts

@@ -0,0 +1,23 @@
+/**
+ * Read a typed entry from an `extra` map (the open-ended record carried on `PaymentRequirements.extra`,
+ * `PaymentMethodInfo.extra`, and similar).
+ *
+ * @typeParam T - Caller-supplied expected type of the value. The function does **not** validate at runtime; callers
+ *   must narrow defensively.
+ * @param extra - The `extra` record, or `undefined`.
+ * @param key - Key to read.
+ * @returns The raw value cast to `T`, or `undefined` if absent.
+ */
+declare function getExtra<T = unknown>(extra: Readonly<Record<string, unknown>> | undefined, key: string): T | undefined;
+/**
+ * Return a new `extra` map with `key` set to `value`. Never mutates the input.
+ *
+ * @typeParam T - Type of the value being written.
+ * @param extra - The existing `extra` record, or `undefined` to start from empty.
+ * @param key - Key to write.
+ * @param value - Value to associate with `key`.
+ * @returns A new record with `value` set at `key`.
+ */
+declare function setExtra<T>(extra: Readonly<Record<string, unknown>> | undefined, key: string, value: T): Record<string, unknown>;
+
+export { getExtra, setExtra };

package/dist/extras/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Read a typed entry from an `extra` map (the open-ended record carried on `PaymentRequirements.extra`,
+ * `PaymentMethodInfo.extra`, and similar).
+ *
+ * @typeParam T - Caller-supplied expected type of the value. The function does **not** validate at runtime; callers
+ *   must narrow defensively.
+ * @param extra - The `extra` record, or `undefined`.
+ * @param key - Key to read.
+ * @returns The raw value cast to `T`, or `undefined` if absent.
+ */
+declare function getExtra<T = unknown>(extra: Readonly<Record<string, unknown>> | undefined, key: string): T | undefined;
+/**
+ * Return a new `extra` map with `key` set to `value`. Never mutates the input.
+ *
+ * @typeParam T - Type of the value being written.
+ * @param extra - The existing `extra` record, or `undefined` to start from empty.
+ * @param key - Key to write.
+ * @param value - Value to associate with `key`.
+ * @returns A new record with `value` set at `key`.
+ */
+declare function setExtra<T>(extra: Readonly<Record<string, unknown>> | undefined, key: string, value: T): Record<string, unknown>;
+
+export { getExtra, setExtra };

package/dist/extras/index.js

@@ -0,0 +1,14 @@
+// src/extras/access.ts
+function getExtra(extra, key) {
+  if (extra === void 0) return void 0;
+  const value = extra[key];
+  if (value === void 0) return void 0;
+  return value;
+}
+function setExtra(extra, key, value) {
+  return { ...extra ?? {}, [key]: value };
+}
+
+export { getExtra, setExtra };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/extras/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/extras/access.ts"],"names":[],"mappings":";AAUO,SAAS,QAAA,CACd,OACA,GAAA,EACe;AACf,EAAA,IAAI,KAAA,KAAU,QAAW,OAAO,MAAA;AAChC,EAAA,MAAM,KAAA,GAAQ,MAAM,GAAG,CAAA;AACvB,EAAA,IAAI,KAAA,KAAU,QAAW,OAAO,MAAA;AAChC,EAAA,OAAO,KAAA;AACT;AAWO,SAAS,QAAA,CACd,KAAA,EACA,GAAA,EACA,KAAA,EACyB;AACzB,EAAA,OAAO,EAAE,GAAI,KAAA,IAAS,IAAK,CAAC,GAAG,GAAG,KAAA,EAAM;AAC1C","file":"index.js","sourcesContent":["/**\n * Read a typed entry from an `extra` map (the open-ended record carried on `PaymentRequirements.extra`,\n * `PaymentMethodInfo.extra`, and similar).\n *\n * @typeParam T - Caller-supplied expected type of the value. The function does **not** validate at runtime; callers\n *   must narrow defensively.\n * @param extra - The `extra` record, or `undefined`.\n * @param key - Key to read.\n * @returns The raw value cast to `T`, or `undefined` if absent.\n */\nexport function getExtra<T = unknown>(\n  extra: Readonly<Record<string, unknown>> | undefined,\n  key: string,\n): T | undefined {\n  if (extra === undefined) return undefined;\n  const value = extra[key];\n  if (value === undefined) return undefined;\n  return value as T;\n}\n\n/**\n * Return a new `extra` map with `key` set to `value`. Never mutates the input.\n *\n * @typeParam T - Type of the value being written.\n * @param extra - The existing `extra` record, or `undefined` to start from empty.\n * @param key - Key to write.\n * @param value - Value to associate with `key`.\n * @returns A new record with `value` set at `key`.\n */\nexport function setExtra<T>(\n  extra: Readonly<Record<string, unknown>> | undefined,\n  key: string,\n  value: T,\n): Record<string, unknown> {\n  return { ...(extra ?? {}), [key]: value };\n}\n"]}