@canopy-finance/x402-client 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# @canopy-finance/x402-client
+
+Buyer-side [x402](https://x402.org) client for the Canopy facilitator. Build and
+post **`exact-permit2-v2`** payments — an EIP-712 Permit2 witness that binds both
+the recipient and a stable `serviceId` into the payer's signature — without
+hand-rolling the typed data.
+
+- Works in the **browser and in Node** (uses `fetch` + `globalThis.crypto` only).
+- **Zero runtime dependencies** except **viem** (peer).
+- Signer-agnostic: pass any `signTypedData` (viem wallet, ethers, injected wallet…).
+- ESM + CJS + type declarations.
+
+The EIP-712 shape here is the single source of truth shared with the facilitator's
+verifier, so buyer and verifier can never drift.
+
+## Install
+
+```bash
+npm install @canopy-finance/x402-client viem
+```
+
+## The four-step buyer flow
+
+```ts
+import {
+  getSupported,
+  permit2ApprovalTx,
+  createExactPermit2V2Payment,
+  post,
+} from "@canopy-finance/x402-client";
+import { createWalletClient, custom } from "viem";
+
+const url = "https://facilitator.canopyfinance.io";
+
+// 1. Discover the facilitator's advertised kind (validates schemeVersion = 2).
+const kind = await getSupported(url);
+
+// 2. (once per payer) Approve Permit2 to move the asset on your behalf.
+const wallet = createWalletClient({ account, transport: custom(window.ethereum) });
+await wallet.writeContract(permit2ApprovalTx(kind));
+
+// 3. Build a signed payment. `serviceId` comes from the resource's 402
+//    response (paymentRequirements.extra.serviceId).
+const body = await createExactPermit2V2Payment({
+  chainId: 4663,
+  kind,
+  owner: account.address,
+  payTo,          // the seller's recipient address
+  amount: 10_000n, // atomic units (e.g. 0.01 USDG at 6 decimals)
+  serviceId,       // bytes32 from the resource's 402
+  signTypedData: (args) => wallet.signTypedData({ account, ...args }),
+});
+
+// 4. POST to /verify, then /settle.
+const verified = await post(url, "verify", body);
+if (verified.isValid !== true) throw new Error("verify failed");
+const settled = await post(url, "settle", body /*, apiKey */);
+```
+
+## Migration from v1 (`exact-permit2`)
+
+The legacy `exact-permit2` scheme is read-only. To integrate:
+
+1. Read `serviceId` from the resource's 402 (`extra.serviceId`).
+2. Call `createExactPermit2V2Payment` (the v1 creator `createPermit2Payment` now
+   throws `UnsupportedSchemeError`).
+3. Target a facilitator advertising `schemeVersion: 2` / `payloadVersion: 2`.
+
+## Exports
+
+- `getSupported(url)` — fetch + validate the `exact-permit2-v2` kind.
+- `permit2ApprovalTx(kind, amount?)` — viem `writeContract` config for the one-time approval.
+- `createExactPermit2V2Payment(params)` — build a signed, ready-to-POST payment body.
+- `post(url, "verify" | "settle", body, apiKey?)` — POST helper.
+- Constants: `PERMIT2_TYPES`, `WITNESS_TYPE_STRING`, `SUPPORTED_SCHEME`,
+  `SUPPORTED_SCHEME_VERSION`, `SUPPORTED_PAYLOAD_VERSION`.
+- Errors: `UnsupportedSchemeError`, `UnsupportedSchemeVersionError`,
+  `UnsupportedPayloadVersionError`, `MissingServiceIdError`.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,187 @@
+'use strict';
+
+var viem = require('viem');
+
+// src/index.ts
+var SUPPORTED_SCHEME = "exact-permit2-v2";
+var SUPPORTED_SCHEME_VERSION = 2;
+var SUPPORTED_PAYLOAD_VERSION = 2;
+var UnsupportedSchemeError = class extends Error {
+  constructor(scheme) {
+    super(`unsupported scheme "${scheme}"; expected ${SUPPORTED_SCHEME}`);
+    this.scheme = scheme;
+    this.name = "UnsupportedSchemeError";
+  }
+  scheme;
+};
+var UnsupportedSchemeVersionError = class extends Error {
+  constructor(version) {
+    super(`unsupported schemeVersion ${String(version)}; expected ${SUPPORTED_SCHEME_VERSION}`);
+    this.version = version;
+    this.name = "UnsupportedSchemeVersionError";
+  }
+  version;
+};
+var UnsupportedPayloadVersionError = class extends Error {
+  constructor(version) {
+    super(`unsupported payloadVersion ${String(version)}; expected ${SUPPORTED_PAYLOAD_VERSION}`);
+    this.version = version;
+    this.name = "UnsupportedPayloadVersionError";
+  }
+  version;
+};
+var MissingServiceIdError = class extends Error {
+  constructor() {
+    super("serviceId is required for exact-permit2-v2; read it from the resource's 402 extra.serviceId");
+    this.name = "MissingServiceIdError";
+  }
+};
+var PERMIT2_TYPES = {
+  PermitWitnessTransferFrom: [
+    { name: "permitted", type: "TokenPermissions" },
+    { name: "spender", type: "address" },
+    { name: "nonce", type: "uint256" },
+    { name: "deadline", type: "uint256" },
+    { name: "witness", type: "X402Witness" }
+  ],
+  TokenPermissions: [
+    { name: "token", type: "address" },
+    { name: "amount", type: "uint256" }
+  ],
+  X402Witness: [
+    { name: "to", type: "address" },
+    { name: "serviceId", type: "bytes32" }
+  ]
+};
+var WITNESS_TYPE_STRING = "X402Witness witness)TokenPermissions(address token,uint256 amount)X402Witness(address to,bytes32 serviceId)";
+var isBytes32 = (v) => typeof v === "string" && /^0x[0-9a-fA-F]{64}$/u.test(v);
+async function getSupported(facilitatorUrl) {
+  const res = await fetch(`${facilitatorUrl.replace(/\/+$/u, "")}/supported`);
+  if (!res.ok) throw new Error(`/supported failed: ${res.status}`);
+  const body = await res.json();
+  if (body.schemeVersion !== SUPPORTED_SCHEME_VERSION) {
+    throw new UnsupportedSchemeVersionError(body.schemeVersion);
+  }
+  if (body.payloadVersion !== SUPPORTED_PAYLOAD_VERSION) {
+    throw new UnsupportedPayloadVersionError(body.payloadVersion);
+  }
+  const kind = body.kinds?.find((k) => k.scheme === SUPPORTED_SCHEME);
+  if (!kind) throw new UnsupportedSchemeError(body.kinds?.[0]?.scheme ?? "none");
+  if (!kind.extra?.spender || !kind.extra.permit2 || !kind.extra.asset) {
+    throw new Error("facilitator /supported did not advertise a usable exact-permit2-v2 kind");
+  }
+  return kind;
+}
+function permit2ApprovalTx(kind, amount = viem.maxUint256) {
+  return {
+    address: viem.getAddress(kind.extra.asset),
+    abi: [
+      {
+        type: "function",
+        name: "approve",
+        stateMutability: "nonpayable",
+        inputs: [
+          { name: "spender", type: "address" },
+          { name: "amount", type: "uint256" }
+        ],
+        outputs: [{ type: "bool" }]
+      }
+    ],
+    functionName: "approve",
+    args: [viem.getAddress(kind.extra.permit2), amount]
+  };
+}
+function randomNonce() {
+  const b = new Uint8Array(31);
+  globalThis.crypto.getRandomValues(b);
+  let n = 0n;
+  for (const x of b) n = n << 8n | BigInt(x);
+  return n;
+}
+async function createExactPermit2V2Payment(p) {
+  if (p.kind.scheme !== SUPPORTED_SCHEME) throw new UnsupportedSchemeError(p.kind.scheme);
+  if (!isBytes32(p.serviceId)) throw new MissingServiceIdError();
+  const token = viem.getAddress(p.kind.extra.asset);
+  const spender = viem.getAddress(p.kind.extra.spender);
+  const owner = viem.getAddress(p.owner);
+  const payTo = viem.getAddress(p.payTo);
+  const nonce = p.nonce ?? randomNonce();
+  const deadline = BigInt(Math.floor(Date.now() / 1e3) + (p.deadlineSeconds ?? 600));
+  const domain = {
+    name: "Permit2",
+    chainId: p.chainId,
+    verifyingContract: viem.getAddress(p.kind.extra.permit2)
+  };
+  const signature = await p.signTypedData({
+    domain,
+    types: PERMIT2_TYPES,
+    primaryType: "PermitWitnessTransferFrom",
+    message: {
+      permitted: { token, amount: p.amount },
+      spender,
+      nonce,
+      deadline,
+      witness: { to: payTo, serviceId: p.serviceId }
+    }
+  });
+  const accepted = {
+    scheme: SUPPORTED_SCHEME,
+    schemeVersion: SUPPORTED_SCHEME_VERSION,
+    payloadVersion: SUPPORTED_PAYLOAD_VERSION,
+    network: p.kind.network,
+    amount: p.amount.toString(),
+    asset: token,
+    payTo,
+    maxTimeoutSeconds: 600,
+    extra: { serviceId: p.serviceId }
+  };
+  return {
+    x402Version: 2,
+    paymentPayload: {
+      x402Version: 2,
+      accepted,
+      payload: {
+        signature,
+        owner,
+        spender,
+        serviceId: p.serviceId,
+        permit: {
+          permitted: { token, amount: p.amount.toString() },
+          nonce: nonce.toString(),
+          deadline: deadline.toString()
+        }
+      },
+      extensions: {}
+    },
+    paymentRequirements: accepted
+  };
+}
+function createPermit2Payment() {
+  throw new UnsupportedSchemeError("exact-permit2");
+}
+async function post(facilitatorUrl, path, body, apiKey) {
+  const res = await fetch(`${facilitatorUrl.replace(/\/+$/u, "")}/${path}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
+    },
+    body: JSON.stringify(body)
+  });
+  return await res.json();
+}
+
+exports.MissingServiceIdError = MissingServiceIdError;
+exports.PERMIT2_TYPES = PERMIT2_TYPES;
+exports.SUPPORTED_PAYLOAD_VERSION = SUPPORTED_PAYLOAD_VERSION;
+exports.SUPPORTED_SCHEME = SUPPORTED_SCHEME;
+exports.SUPPORTED_SCHEME_VERSION = SUPPORTED_SCHEME_VERSION;
+exports.UnsupportedPayloadVersionError = UnsupportedPayloadVersionError;
+exports.UnsupportedSchemeError = UnsupportedSchemeError;
+exports.UnsupportedSchemeVersionError = UnsupportedSchemeVersionError;
+exports.WITNESS_TYPE_STRING = WITNESS_TYPE_STRING;
+exports.createExactPermit2V2Payment = createExactPermit2V2Payment;
+exports.createPermit2Payment = createPermit2Payment;
+exports.getSupported = getSupported;
+exports.permit2ApprovalTx = permit2ApprovalTx;
+exports.post = post;

package/dist/index.d.cts

@@ -0,0 +1,158 @@
+import { Address, Hex, TypedDataDomain } from 'viem';
+
+/**
+ * Canopy x402 buyer SDK — construct an exact-permit2-v2 payment for the
+ * facilitator without hand-rolling the EIP-712 witness. Signer-agnostic: pass
+ * any `signTypedData` implementation (viem, ethers, a wallet, etc.).
+ *
+ * exact-permit2-v2 binds a stable `serviceId` (from the resource's 402
+ * `paymentRequirements.extra.serviceId`) into the signed witness, so a payment
+ * attributes to exactly one Discovery listing.
+ *
+ * Flow:
+ *   1. const kind = await getSupported(url)            // validates schemeVersion=2
+ *   2. (once) approve Permit2 on the asset             // permit2ApprovalTx()
+ *   3. const body = await createExactPermit2V2Payment({..., serviceId})
+ *   4. POST body to `${url}/verify` then `${url}/settle`
+ *
+ * Migration from v1 (exact-permit2): the legacy scheme is read-only. You must
+ * (a) read serviceId from the resource's 402, (b) call
+ * createExactPermit2V2Payment instead of the removed v1 creator, and (c) target
+ * a facilitator advertising schemeVersion=2 / payloadVersion=2.
+ */
+
+declare const SUPPORTED_SCHEME: "exact-permit2-v2";
+declare const SUPPORTED_SCHEME_VERSION: 2;
+declare const SUPPORTED_PAYLOAD_VERSION: 2;
+/** Typed errors so integrators can switch on failure modes. */
+declare class UnsupportedSchemeError extends Error {
+    readonly scheme: string;
+    constructor(scheme: string);
+}
+declare class UnsupportedSchemeVersionError extends Error {
+    readonly version: unknown;
+    constructor(version: unknown);
+}
+declare class UnsupportedPayloadVersionError extends Error {
+    readonly version: unknown;
+    constructor(version: unknown);
+}
+declare class MissingServiceIdError extends Error {
+    constructor();
+}
+interface SupportedExtra {
+    permit2: Address;
+    spender: Address;
+    asset: Address;
+    witnessTypeString: string;
+    serviceIdRequired?: boolean;
+}
+interface SupportedKind {
+    x402Version: number;
+    scheme: string;
+    network: string;
+    extra: SupportedExtra;
+}
+/** EIP-712 types for the v2 witnessed Permit2 transfer (matches the facilitator). */
+declare const PERMIT2_TYPES: {
+    readonly PermitWitnessTransferFrom: readonly [{
+        readonly name: "permitted";
+        readonly type: "TokenPermissions";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }, {
+        readonly name: "witness";
+        readonly type: "X402Witness";
+    }];
+    readonly TokenPermissions: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly X402Witness: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "serviceId";
+        readonly type: "bytes32";
+    }];
+};
+/**
+ * The witnessTypeString Permit2 concatenates after its stub — FROZEN and
+ * byte-identical to the facilitator's verifier (src/verify/domain.ts). If the
+ * buyer and verifier ever disagree here, every signature silently fails.
+ */
+declare const WITNESS_TYPE_STRING: "X402Witness witness)TokenPermissions(address token,uint256 amount)X402Witness(address to,bytes32 serviceId)";
+/** Fetch and validate the facilitator's advertised exact-permit2-v2 kind. */
+declare function getSupported(facilitatorUrl: string): Promise<SupportedKind>;
+/**
+ * The one-time approval the payer submits on-chain, so Permit2 can move the
+ * asset on their behalf. Returns a viem-style writeContract config.
+ */
+declare function permit2ApprovalTx(kind: SupportedKind, amount?: bigint): {
+    address: `0x${string}`;
+    abi: readonly [{
+        readonly type: "function";
+        readonly name: "approve";
+        readonly stateMutability: "nonpayable";
+        readonly inputs: readonly [{
+            readonly name: "spender";
+            readonly type: "address";
+        }, {
+            readonly name: "amount";
+            readonly type: "uint256";
+        }];
+        readonly outputs: readonly [{
+            readonly type: "bool";
+        }];
+    }];
+    functionName: "approve";
+    args: readonly [`0x${string}`, bigint];
+};
+type SignTypedData = (args: {
+    domain: TypedDataDomain;
+    types: typeof PERMIT2_TYPES;
+    primaryType: "PermitWitnessTransferFrom";
+    message: Record<string, unknown>;
+}) => Promise<Hex>;
+interface CreatePaymentParams {
+    chainId: number;
+    kind: SupportedKind;
+    owner: Address;
+    /** Recipient of the funds (the seller's payTo). */
+    payTo: Address;
+    /** Atomic amount (e.g. 10000 = 0.01 USDG at 6 decimals). */
+    amount: bigint;
+    /** Stable bytes32 serviceId from the resource's 402 (extra.serviceId). */
+    serviceId: Hex;
+    /** Unordered Permit2 nonce. Defaults to a random 255-bit value. */
+    nonce?: bigint;
+    /** Seconds until the permit expires. Default 600. */
+    deadlineSeconds?: number;
+    signTypedData: SignTypedData;
+}
+interface FacilitatorRequestBody {
+    x402Version: number;
+    paymentPayload: Record<string, unknown>;
+    paymentRequirements: Record<string, unknown>;
+}
+/** Build a signed exact-permit2-v2 payment body ready to POST to /verify + /settle. */
+declare function createExactPermit2V2Payment(p: CreatePaymentParams): Promise<FacilitatorRequestBody>;
+/**
+ * Deprecated v1 creator. The legacy exact-permit2 scheme is read-only; creating
+ * new legacy payments is disabled. Use createExactPermit2V2Payment.
+ */
+declare function createPermit2Payment(): never;
+/** POST a payment body to the facilitator, optionally with an API key. */
+declare function post(facilitatorUrl: string, path: "verify" | "settle", body: FacilitatorRequestBody, apiKey?: string): Promise<Record<string, unknown>>;
+
+export { type CreatePaymentParams, type FacilitatorRequestBody, MissingServiceIdError, PERMIT2_TYPES, SUPPORTED_PAYLOAD_VERSION, SUPPORTED_SCHEME, SUPPORTED_SCHEME_VERSION, type SignTypedData, type SupportedExtra, type SupportedKind, UnsupportedPayloadVersionError, UnsupportedSchemeError, UnsupportedSchemeVersionError, WITNESS_TYPE_STRING, createExactPermit2V2Payment, createPermit2Payment, getSupported, permit2ApprovalTx, post };

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+import { Address, Hex, TypedDataDomain } from 'viem';
+
+/**
+ * Canopy x402 buyer SDK — construct an exact-permit2-v2 payment for the
+ * facilitator without hand-rolling the EIP-712 witness. Signer-agnostic: pass
+ * any `signTypedData` implementation (viem, ethers, a wallet, etc.).
+ *
+ * exact-permit2-v2 binds a stable `serviceId` (from the resource's 402
+ * `paymentRequirements.extra.serviceId`) into the signed witness, so a payment
+ * attributes to exactly one Discovery listing.
+ *
+ * Flow:
+ *   1. const kind = await getSupported(url)            // validates schemeVersion=2
+ *   2. (once) approve Permit2 on the asset             // permit2ApprovalTx()
+ *   3. const body = await createExactPermit2V2Payment({..., serviceId})
+ *   4. POST body to `${url}/verify` then `${url}/settle`
+ *
+ * Migration from v1 (exact-permit2): the legacy scheme is read-only. You must
+ * (a) read serviceId from the resource's 402, (b) call
+ * createExactPermit2V2Payment instead of the removed v1 creator, and (c) target
+ * a facilitator advertising schemeVersion=2 / payloadVersion=2.
+ */
+
+declare const SUPPORTED_SCHEME: "exact-permit2-v2";
+declare const SUPPORTED_SCHEME_VERSION: 2;
+declare const SUPPORTED_PAYLOAD_VERSION: 2;
+/** Typed errors so integrators can switch on failure modes. */
+declare class UnsupportedSchemeError extends Error {
+    readonly scheme: string;
+    constructor(scheme: string);
+}
+declare class UnsupportedSchemeVersionError extends Error {
+    readonly version: unknown;
+    constructor(version: unknown);
+}
+declare class UnsupportedPayloadVersionError extends Error {
+    readonly version: unknown;
+    constructor(version: unknown);
+}
+declare class MissingServiceIdError extends Error {
+    constructor();
+}
+interface SupportedExtra {
+    permit2: Address;
+    spender: Address;
+    asset: Address;
+    witnessTypeString: string;
+    serviceIdRequired?: boolean;
+}
+interface SupportedKind {
+    x402Version: number;
+    scheme: string;
+    network: string;
+    extra: SupportedExtra;
+}
+/** EIP-712 types for the v2 witnessed Permit2 transfer (matches the facilitator). */
+declare const PERMIT2_TYPES: {
+    readonly PermitWitnessTransferFrom: readonly [{
+        readonly name: "permitted";
+        readonly type: "TokenPermissions";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }, {
+        readonly name: "witness";
+        readonly type: "X402Witness";
+    }];
+    readonly TokenPermissions: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly X402Witness: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "serviceId";
+        readonly type: "bytes32";
+    }];
+};
+/**
+ * The witnessTypeString Permit2 concatenates after its stub — FROZEN and
+ * byte-identical to the facilitator's verifier (src/verify/domain.ts). If the
+ * buyer and verifier ever disagree here, every signature silently fails.
+ */
+declare const WITNESS_TYPE_STRING: "X402Witness witness)TokenPermissions(address token,uint256 amount)X402Witness(address to,bytes32 serviceId)";
+/** Fetch and validate the facilitator's advertised exact-permit2-v2 kind. */
+declare function getSupported(facilitatorUrl: string): Promise<SupportedKind>;
+/**
+ * The one-time approval the payer submits on-chain, so Permit2 can move the
+ * asset on their behalf. Returns a viem-style writeContract config.
+ */
+declare function permit2ApprovalTx(kind: SupportedKind, amount?: bigint): {
+    address: `0x${string}`;
+    abi: readonly [{
+        readonly type: "function";
+        readonly name: "approve";
+        readonly stateMutability: "nonpayable";
+        readonly inputs: readonly [{
+            readonly name: "spender";
+            readonly type: "address";
+        }, {
+            readonly name: "amount";
+            readonly type: "uint256";
+        }];
+        readonly outputs: readonly [{
+            readonly type: "bool";
+        }];
+    }];
+    functionName: "approve";
+    args: readonly [`0x${string}`, bigint];
+};
+type SignTypedData = (args: {
+    domain: TypedDataDomain;
+    types: typeof PERMIT2_TYPES;
+    primaryType: "PermitWitnessTransferFrom";
+    message: Record<string, unknown>;
+}) => Promise<Hex>;
+interface CreatePaymentParams {
+    chainId: number;
+    kind: SupportedKind;
+    owner: Address;
+    /** Recipient of the funds (the seller's payTo). */
+    payTo: Address;
+    /** Atomic amount (e.g. 10000 = 0.01 USDG at 6 decimals). */
+    amount: bigint;
+    /** Stable bytes32 serviceId from the resource's 402 (extra.serviceId). */
+    serviceId: Hex;
+    /** Unordered Permit2 nonce. Defaults to a random 255-bit value. */
+    nonce?: bigint;
+    /** Seconds until the permit expires. Default 600. */
+    deadlineSeconds?: number;
+    signTypedData: SignTypedData;
+}
+interface FacilitatorRequestBody {
+    x402Version: number;
+    paymentPayload: Record<string, unknown>;
+    paymentRequirements: Record<string, unknown>;
+}
+/** Build a signed exact-permit2-v2 payment body ready to POST to /verify + /settle. */
+declare function createExactPermit2V2Payment(p: CreatePaymentParams): Promise<FacilitatorRequestBody>;
+/**
+ * Deprecated v1 creator. The legacy exact-permit2 scheme is read-only; creating
+ * new legacy payments is disabled. Use createExactPermit2V2Payment.
+ */
+declare function createPermit2Payment(): never;
+/** POST a payment body to the facilitator, optionally with an API key. */
+declare function post(facilitatorUrl: string, path: "verify" | "settle", body: FacilitatorRequestBody, apiKey?: string): Promise<Record<string, unknown>>;
+
+export { type CreatePaymentParams, type FacilitatorRequestBody, MissingServiceIdError, PERMIT2_TYPES, SUPPORTED_PAYLOAD_VERSION, SUPPORTED_SCHEME, SUPPORTED_SCHEME_VERSION, type SignTypedData, type SupportedExtra, type SupportedKind, UnsupportedPayloadVersionError, UnsupportedSchemeError, UnsupportedSchemeVersionError, WITNESS_TYPE_STRING, createExactPermit2V2Payment, createPermit2Payment, getSupported, permit2ApprovalTx, post };

package/dist/index.mjs

@@ -0,0 +1,172 @@
+import { maxUint256, getAddress } from 'viem';
+
+// src/index.ts
+var SUPPORTED_SCHEME = "exact-permit2-v2";
+var SUPPORTED_SCHEME_VERSION = 2;
+var SUPPORTED_PAYLOAD_VERSION = 2;
+var UnsupportedSchemeError = class extends Error {
+  constructor(scheme) {
+    super(`unsupported scheme "${scheme}"; expected ${SUPPORTED_SCHEME}`);
+    this.scheme = scheme;
+    this.name = "UnsupportedSchemeError";
+  }
+  scheme;
+};
+var UnsupportedSchemeVersionError = class extends Error {
+  constructor(version) {
+    super(`unsupported schemeVersion ${String(version)}; expected ${SUPPORTED_SCHEME_VERSION}`);
+    this.version = version;
+    this.name = "UnsupportedSchemeVersionError";
+  }
+  version;
+};
+var UnsupportedPayloadVersionError = class extends Error {
+  constructor(version) {
+    super(`unsupported payloadVersion ${String(version)}; expected ${SUPPORTED_PAYLOAD_VERSION}`);
+    this.version = version;
+    this.name = "UnsupportedPayloadVersionError";
+  }
+  version;
+};
+var MissingServiceIdError = class extends Error {
+  constructor() {
+    super("serviceId is required for exact-permit2-v2; read it from the resource's 402 extra.serviceId");
+    this.name = "MissingServiceIdError";
+  }
+};
+var PERMIT2_TYPES = {
+  PermitWitnessTransferFrom: [
+    { name: "permitted", type: "TokenPermissions" },
+    { name: "spender", type: "address" },
+    { name: "nonce", type: "uint256" },
+    { name: "deadline", type: "uint256" },
+    { name: "witness", type: "X402Witness" }
+  ],
+  TokenPermissions: [
+    { name: "token", type: "address" },
+    { name: "amount", type: "uint256" }
+  ],
+  X402Witness: [
+    { name: "to", type: "address" },
+    { name: "serviceId", type: "bytes32" }
+  ]
+};
+var WITNESS_TYPE_STRING = "X402Witness witness)TokenPermissions(address token,uint256 amount)X402Witness(address to,bytes32 serviceId)";
+var isBytes32 = (v) => typeof v === "string" && /^0x[0-9a-fA-F]{64}$/u.test(v);
+async function getSupported(facilitatorUrl) {
+  const res = await fetch(`${facilitatorUrl.replace(/\/+$/u, "")}/supported`);
+  if (!res.ok) throw new Error(`/supported failed: ${res.status}`);
+  const body = await res.json();
+  if (body.schemeVersion !== SUPPORTED_SCHEME_VERSION) {
+    throw new UnsupportedSchemeVersionError(body.schemeVersion);
+  }
+  if (body.payloadVersion !== SUPPORTED_PAYLOAD_VERSION) {
+    throw new UnsupportedPayloadVersionError(body.payloadVersion);
+  }
+  const kind = body.kinds?.find((k) => k.scheme === SUPPORTED_SCHEME);
+  if (!kind) throw new UnsupportedSchemeError(body.kinds?.[0]?.scheme ?? "none");
+  if (!kind.extra?.spender || !kind.extra.permit2 || !kind.extra.asset) {
+    throw new Error("facilitator /supported did not advertise a usable exact-permit2-v2 kind");
+  }
+  return kind;
+}
+function permit2ApprovalTx(kind, amount = maxUint256) {
+  return {
+    address: getAddress(kind.extra.asset),
+    abi: [
+      {
+        type: "function",
+        name: "approve",
+        stateMutability: "nonpayable",
+        inputs: [
+          { name: "spender", type: "address" },
+          { name: "amount", type: "uint256" }
+        ],
+        outputs: [{ type: "bool" }]
+      }
+    ],
+    functionName: "approve",
+    args: [getAddress(kind.extra.permit2), amount]
+  };
+}
+function randomNonce() {
+  const b = new Uint8Array(31);
+  globalThis.crypto.getRandomValues(b);
+  let n = 0n;
+  for (const x of b) n = n << 8n | BigInt(x);
+  return n;
+}
+async function createExactPermit2V2Payment(p) {
+  if (p.kind.scheme !== SUPPORTED_SCHEME) throw new UnsupportedSchemeError(p.kind.scheme);
+  if (!isBytes32(p.serviceId)) throw new MissingServiceIdError();
+  const token = getAddress(p.kind.extra.asset);
+  const spender = getAddress(p.kind.extra.spender);
+  const owner = getAddress(p.owner);
+  const payTo = getAddress(p.payTo);
+  const nonce = p.nonce ?? randomNonce();
+  const deadline = BigInt(Math.floor(Date.now() / 1e3) + (p.deadlineSeconds ?? 600));
+  const domain = {
+    name: "Permit2",
+    chainId: p.chainId,
+    verifyingContract: getAddress(p.kind.extra.permit2)
+  };
+  const signature = await p.signTypedData({
+    domain,
+    types: PERMIT2_TYPES,
+    primaryType: "PermitWitnessTransferFrom",
+    message: {
+      permitted: { token, amount: p.amount },
+      spender,
+      nonce,
+      deadline,
+      witness: { to: payTo, serviceId: p.serviceId }
+    }
+  });
+  const accepted = {
+    scheme: SUPPORTED_SCHEME,
+    schemeVersion: SUPPORTED_SCHEME_VERSION,
+    payloadVersion: SUPPORTED_PAYLOAD_VERSION,
+    network: p.kind.network,
+    amount: p.amount.toString(),
+    asset: token,
+    payTo,
+    maxTimeoutSeconds: 600,
+    extra: { serviceId: p.serviceId }
+  };
+  return {
+    x402Version: 2,
+    paymentPayload: {
+      x402Version: 2,
+      accepted,
+      payload: {
+        signature,
+        owner,
+        spender,
+        serviceId: p.serviceId,
+        permit: {
+          permitted: { token, amount: p.amount.toString() },
+          nonce: nonce.toString(),
+          deadline: deadline.toString()
+        }
+      },
+      extensions: {}
+    },
+    paymentRequirements: accepted
+  };
+}
+function createPermit2Payment() {
+  throw new UnsupportedSchemeError("exact-permit2");
+}
+async function post(facilitatorUrl, path, body, apiKey) {
+  const res = await fetch(`${facilitatorUrl.replace(/\/+$/u, "")}/${path}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
+    },
+    body: JSON.stringify(body)
+  });
+  return await res.json();
+}
+
+export { MissingServiceIdError, PERMIT2_TYPES, SUPPORTED_PAYLOAD_VERSION, SUPPORTED_SCHEME, SUPPORTED_SCHEME_VERSION, UnsupportedPayloadVersionError, UnsupportedSchemeError, UnsupportedSchemeVersionError, WITNESS_TYPE_STRING, createExactPermit2V2Payment, createPermit2Payment, getSupported, permit2ApprovalTx, post };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@canopy-finance/x402-client",
+  "version": "0.1.0",
+  "description": "Buyer-side x402 client for the Canopy facilitator: build and post exact-permit2-v2 payments (EIP-712 Permit2 witness). Works in the browser and in Node. Zero runtime deps except viem (peer).",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "viem": "^2"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.5.0",
+    "viem": "^2.21.0"
+  },
+  "keywords": [
+    "x402",
+    "permit2",
+    "eip-712",
+    "canopy",
+    "robinhood-chain",
+    "payments",
+    "stablecoin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/canopyfinance/canopy-facilitator.git",
+    "directory": "packages/x402-client"
+  }
+}