@inflowpayai/x402 0.5.0

package/dist/payment-identifier-BNYznClf.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Per-call context threaded into {@link ExtensionHandler.buildDeclaration}. Reserved for forward compatibility: handlers
+ * may inspect fields here in future revisions. The seller's `inflowAccepts` currently passes `{}`.
+ */
+type DeclarationContext = Record<string, never>;
+/**
+ * Per-call context threaded into {@link ExtensionHandler.buildPayloadEntry}. Populated by the buyer signer when
+ * constructing a `PaymentPayload`.
+ */
+interface SignContext {
+    /**
+     * Caller-supplied payment identifier (from `SignOptions.paymentId`) when the SDK writes the extensions map directly —
+     * i.e. on the foundation-signed branch. Absent on the InFlow-signed branch, where the server embeds the identifier
+     * server-side.
+     */
+    providedPaymentId?: string;
+}
+/**
+ * Pluggable handler for one protocol extension. Sellers call `buildDeclaration` to populate
+ * `PaymentRequired.extensions[name]`; buyers call `readDeclaration` to parse what the server emitted, and
+ * `buildPayloadEntry` to produce the corresponding `PaymentPayload.extensions[name]` value.
+ *
+ * @typeParam TDeclaration - Shape of the declaration object the seller emits and the buyer reads.
+ * @typeParam TPayloadEntry - Shape of the per-payload entry the buyer emits.
+ */
+interface ExtensionHandler<TDeclaration, TPayloadEntry> {
+    /** Extension name, matching the wire key in `extensions[]` maps. */
+    readonly name: string;
+    /**
+     * Build the per-response declaration. Return `null` to omit this extension from the response entirely.
+     *
+     * @param context - {@link DeclarationContext}.
+     * @returns The declaration value, or `null`.
+     */
+    buildDeclaration(context: DeclarationContext): TDeclaration | null;
+    /**
+     * Parse a declaration emitted by a server. Implementations should be defensive: anything that doesn't match the
+     * expected shape returns `null`.
+     *
+     * @param decl - The raw value read from `PaymentRequired.extensions[name]`.
+     * @returns The parsed declaration, or `null` when the input was missing or malformed.
+     */
+    readDeclaration(decl: unknown): TDeclaration | null;
+    /**
+     * Build the per-payload entry. Return `null` to skip embedding for this call — common when the declaration was
+     * `required: false` and the caller did not opt in.
+     *
+     * @param declaration - The parsed declaration the server emitted on the matching 402.
+     * @param context - {@link SignContext}.
+     * @returns The payload-entry value, or `null` to omit.
+     */
+    buildPayloadEntry(declaration: TDeclaration, context: SignContext): TPayloadEntry | null;
+}
+
+/** Extension name on the wire — the key in `extensions[]` maps. */
+declare const EXTENSION_PAYMENT_IDENTIFIER: "payment-identifier";
+declare const PAYMENT_ID_MIN_LENGTH = 16;
+declare const PAYMENT_ID_MAX_LENGTH = 128;
+/** Regex a valid payment identifier must match. Mirrors the x402 `payment-identifier` extension spec. */
+declare const PAYMENT_ID_REGEX: RegExp;
+/**
+ * Default prefix used by {@link generatePaymentId}. Mirrors the format produced by InFlow's automatic
+ * transaction-id-derived identifiers (`pay_<32 hex chars>`).
+ */
+declare const PAYMENT_ID_DEFAULT_PREFIX = "pay_";
+/** Declaration shape attached to `PaymentRequired.extensions['payment-identifier']`. */
+interface PaymentIdentifierDeclaration {
+    /**
+     * When `true`, the payload's `extensions['payment-identifier'].paymentId` is mandatory; settlement fails without it.
+     * When `false`, the field is optional and may be omitted.
+     */
+    required: boolean;
+}
+/** Payload-entry shape attached to `PaymentPayload.extensions['payment-identifier']`. */
+interface PaymentIdentifierPayloadEntry {
+    /** The identifier value, satisfying {@link validatePaymentId}. */
+    paymentId: string;
+}
+/**
+ * Validate a payment-identifier string against the extension spec.
+ *
+ * @param id - Candidate identifier. Returns `false` for any non-string input.
+ * @returns `true` when `id` is a string of length 16–128 containing only `a–z`, `A–Z`, `0–9`, `_`, and `-`. `false`
+ *   otherwise.
+ */
+declare function validatePaymentId(id: unknown): id is string;
+/**
+ * Generate a new payment identifier.
+ *
+ * @param prefix - String prefix prepended to a random 32-character hex suffix. Defaults to `'pay_'`. Must satisfy
+ *   `^[a-zA-Z0-9_-]*$` and yield a total length of 16–128 when combined with the suffix.
+ * @returns A string of the form `<prefix><32 hex chars>` (lowercase).
+ * @throws {Error} When `prefix` contains characters not allowed by {@link PAYMENT_ID_REGEX} or the resulting identifier
+ *   falls outside the 16–128-character bound.
+ */
+declare function generatePaymentId(prefix?: string): string;
+/**
+ * Handler for the x402 `payment-identifier` extension. Used by the seller (`inflowAccepts`) and the buyer (signer flows
+ * that compose external `x402Client` signers).
+ */
+declare const PAYMENT_IDENTIFIER: ExtensionHandler<PaymentIdentifierDeclaration, PaymentIdentifierPayloadEntry>;
+
+export { type DeclarationContext as D, EXTENSION_PAYMENT_IDENTIFIER as E, PAYMENT_IDENTIFIER as P, type SignContext as S, type ExtensionHandler as a, PAYMENT_ID_DEFAULT_PREFIX as b, PAYMENT_ID_MAX_LENGTH as c, PAYMENT_ID_MIN_LENGTH as d, PAYMENT_ID_REGEX as e, type PaymentIdentifierDeclaration as f, type PaymentIdentifierPayloadEntry as g, generatePaymentId as h, validatePaymentId as v };

package/dist/security/index.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+var buffer = require('buffer');
+var crypto = require('crypto');
+
+// src/security/index.ts
+function timingSafeEqualStrings(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  const ab = buffer.Buffer.from(a, "utf8");
+  const bb = buffer.Buffer.from(b, "utf8");
+  if (ab.length !== bb.length) return false;
+  return crypto.timingSafeEqual(ab, bb);
+}
+
+exports.timingSafeEqualStrings = timingSafeEqualStrings;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/security/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/security/index.ts"],"names":["Buffer","timingSafeEqual"],"mappings":";;;;;;AAcO,SAAS,sBAAA,CAAuB,GAAY,CAAA,EAAqB;AACtE,EAAA,IAAI,OAAO,CAAA,KAAM,QAAA,IAAY,OAAO,CAAA,KAAM,UAAU,OAAO,KAAA;AAC3D,EAAA,MAAM,EAAA,GAAKA,aAAA,CAAO,IAAA,CAAK,CAAA,EAAG,MAAM,CAAA;AAChC,EAAA,MAAM,EAAA,GAAKA,aAAA,CAAO,IAAA,CAAK,CAAA,EAAG,MAAM,CAAA;AAChC,EAAA,IAAI,EAAA,CAAG,MAAA,KAAW,EAAA,CAAG,MAAA,EAAQ,OAAO,KAAA;AACpC,EAAA,OAAOC,sBAAA,CAAgB,IAAI,EAAE,CAAA;AAC/B","file":"index.cjs","sourcesContent":["import { Buffer } from 'node:buffer';\nimport { timingSafeEqual } from 'node:crypto';\n\n/**\n * Constant-time string equality.\n *\n * @param a - First value. Anything other than a string returns `false`.\n * @param b - Second value. Anything other than a string returns `false`.\n * @returns `true` when both arguments are strings, have equal UTF-8 byte length, and have identical byte content. The\n *   comparison time does not depend on where the strings differ. Returns `false` otherwise.\n *\n *   Use for comparing opaque tokens such as payment identifiers and extension-supplied HMAC values where naive equality\n *   (`===`) could leak timing information.\n */\nexport function timingSafeEqualStrings(a: unknown, b: unknown): boolean {\n  if (typeof a !== 'string' || typeof b !== 'string') return false;\n  const ab = Buffer.from(a, 'utf8');\n  const bb = Buffer.from(b, 'utf8');\n  if (ab.length !== bb.length) return false;\n  return timingSafeEqual(ab, bb);\n}\n"]}

package/dist/security/index.d.cts

@@ -0,0 +1,14 @@
+/**
+ * Constant-time string equality.
+ *
+ * @param a - First value. Anything other than a string returns `false`.
+ * @param b - Second value. Anything other than a string returns `false`.
+ * @returns `true` when both arguments are strings, have equal UTF-8 byte length, and have identical byte content. The
+ *   comparison time does not depend on where the strings differ. Returns `false` otherwise.
+ *
+ *   Use for comparing opaque tokens such as payment identifiers and extension-supplied HMAC values where naive equality
+ *   (`===`) could leak timing information.
+ */
+declare function timingSafeEqualStrings(a: unknown, b: unknown): boolean;
+
+export { timingSafeEqualStrings };

package/dist/security/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Constant-time string equality.
+ *
+ * @param a - First value. Anything other than a string returns `false`.
+ * @param b - Second value. Anything other than a string returns `false`.
+ * @returns `true` when both arguments are strings, have equal UTF-8 byte length, and have identical byte content. The
+ *   comparison time does not depend on where the strings differ. Returns `false` otherwise.
+ *
+ *   Use for comparing opaque tokens such as payment identifiers and extension-supplied HMAC values where naive equality
+ *   (`===`) could leak timing information.
+ */
+declare function timingSafeEqualStrings(a: unknown, b: unknown): boolean;
+
+export { timingSafeEqualStrings };

package/dist/security/index.js

@@ -0,0 +1,15 @@
+import { Buffer } from 'buffer';
+import { timingSafeEqual } from 'crypto';
+
+// src/security/index.ts
+function timingSafeEqualStrings(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  const ab = Buffer.from(a, "utf8");
+  const bb = Buffer.from(b, "utf8");
+  if (ab.length !== bb.length) return false;
+  return timingSafeEqual(ab, bb);
+}
+
+export { timingSafeEqualStrings };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/security/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/security/index.ts"],"names":[],"mappings":";;;;AAcO,SAAS,sBAAA,CAAuB,GAAY,CAAA,EAAqB;AACtE,EAAA,IAAI,OAAO,CAAA,KAAM,QAAA,IAAY,OAAO,CAAA,KAAM,UAAU,OAAO,KAAA;AAC3D,EAAA,MAAM,EAAA,GAAK,MAAA,CAAO,IAAA,CAAK,CAAA,EAAG,MAAM,CAAA;AAChC,EAAA,MAAM,EAAA,GAAK,MAAA,CAAO,IAAA,CAAK,CAAA,EAAG,MAAM,CAAA;AAChC,EAAA,IAAI,EAAA,CAAG,MAAA,KAAW,EAAA,CAAG,MAAA,EAAQ,OAAO,KAAA;AACpC,EAAA,OAAO,eAAA,CAAgB,IAAI,EAAE,CAAA;AAC/B","file":"index.js","sourcesContent":["import { Buffer } from 'node:buffer';\nimport { timingSafeEqual } from 'node:crypto';\n\n/**\n * Constant-time string equality.\n *\n * @param a - First value. Anything other than a string returns `false`.\n * @param b - Second value. Anything other than a string returns `false`.\n * @returns `true` when both arguments are strings, have equal UTF-8 byte length, and have identical byte content. The\n *   comparison time does not depend on where the strings differ. Returns `false` otherwise.\n *\n *   Use for comparing opaque tokens such as payment identifiers and extension-supplied HMAC values where naive equality\n *   (`===`) could leak timing information.\n */\nexport function timingSafeEqualStrings(a: unknown, b: unknown): boolean {\n  if (typeof a !== 'string' || typeof b !== 'string') return false;\n  const ab = Buffer.from(a, 'utf8');\n  const bb = Buffer.from(b, 'utf8');\n  if (ab.length !== bb.length) return false;\n  return timingSafeEqual(ab, bb);\n}\n"]}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@inflowpayai/x402",
+  "version": "0.5.0",
+  "description": "InFlow x402 SDK core: protocol types, HTTP client, scheme constants.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": {
+        "import": "./dist/index.js",
+        "require": "./dist/index.cjs"
+      },
+      "default": "./dist/index.js"
+    },
+    "./security": {
+      "types": "./dist/security/index.d.ts",
+      "node": {
+        "import": "./dist/security/index.js",
+        "require": "./dist/security/index.cjs"
+      },
+      "default": "./dist/security/index.js"
+    },
+    "./extensions": {
+      "types": "./dist/extensions/index.d.ts",
+      "node": {
+        "import": "./dist/extensions/index.js",
+        "require": "./dist/extensions/index.cjs"
+      },
+      "default": "./dist/extensions/index.js"
+    },
+    "./extras": {
+      "types": "./dist/extras/index.d.ts",
+      "node": {
+        "import": "./dist/extras/index.js",
+        "require": "./dist/extras/index.cjs"
+      },
+      "default": "./dist/extras/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@x402/core": "^2.12.0"
+  },
+  "peerDependenciesMeta": {
+    "@x402/core": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.0",
+    "@x402/core": "^2.12.0",
+    "msw": "^2.4.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/inflowpayai/inflow-node.git",
+    "directory": "packages/x402"
+  },
+  "bugs": {
+    "url": "https://github.com/inflowpayai/inflow-node/issues"
+  },
+  "homepage": "https://github.com/inflowpayai/inflow-node/tree/main/packages/x402#readme",
+  "keywords": [
+    "x402",
+    "payments",
+    "inflow",
+    "@inflowpayai",
+    "core",
+    "types"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "lint": "eslint src test --max-warnings 0",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "clean": "rm -rf dist .turbo"
+  }
+}