@oobe-protocol-labs/synapse-sap-sdk 0.14.0 → 0.15.1

package/dist/esm/utils/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/utils/hash.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,GAAG,MAAM,GAAG,UAAU,KAAG,UAM5D,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,UAAU,KAAG,MAAM,EAAsB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,eAAe,aAAa,CAAC,UAAU,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,KAC3D,UAyBF,CAAC"}

package/dist/esm/utils/hash.js

@@ -0,0 +1,103 @@
+/**
+ * @module utils/hash
+ * @description Cryptographic hashing utilities.
+ *
+ * @category Utils
+ * @since v0.1.0
+ */
+import { createHash } from "crypto";
+/**
+ * Compute the SHA-256 hash of a UTF-8 string or byte buffer.
+ *
+ * Returns a 32-byte `Uint8Array` suitable for PDA seeds
+ * and Anchor instruction arguments.
+ *
+ * @name sha256
+ * @description Hashes the input using Node’s `crypto.createHash("sha256")`.
+ * @param input - A UTF-8 string, `Buffer`, or `Uint8Array` to hash.
+ * @returns {Uint8Array} 32-byte SHA-256 digest.
+ * @category Utils
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { sha256 } from "@synapse-sap/sdk/utils";
+ *
+ * const hash = sha256("jupiter:swap"); // Uint8Array (32 bytes)
+ * ```
+ */
+export const sha256 = (input) => {
+    const hash = createHash("sha256");
+    hash.update(typeof input === "string" ? Buffer.from(input, "utf-8") : input);
+    return new Uint8Array(hash.digest());
+};
+/**
+ * Convert a `Uint8Array` hash to a plain `number[]`.
+ *
+ * Anchor instruction argument types expect `number[]` for hash fields
+ * rather than typed arrays.
+ *
+ * @name hashToArray
+ * @description Converts a byte array (typically 32 bytes) to a plain JavaScript `number[]`.
+ * @param hash - The byte array to convert.
+ * @returns {number[]} Shallow copy as a plain array of numbers.
+ * @category Utils
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { sha256, hashToArray } from "@synapse-sap/sdk/utils";
+ *
+ * const arr = hashToArray(sha256("jupiter:swap")); // number[]
+ * ```
+ */
+export const hashToArray = (hash) => Array.from(hash);
+/**
+ * Compute the deterministic batch root used by `settle_batch` (v0.10.0).
+ *
+ * The on-chain program enforces:
+ *   `batch_root == sha256(s_0 || s_1 || ... || s_{N-1})`
+ * where each `s_i` is a 32-byte service hash, in the same order as the
+ * `settlements: Settlement[]` array passed to the instruction.
+ *
+ * Use this helper to derive the seed for the {@link deriveSettlementReceipt}
+ * PDA when batching settlements.
+ *
+ * @name computeBatchRoot
+ * @param serviceHashes - Array of 32-byte service hashes (Buffer/Uint8Array/number[]).
+ * @returns {Uint8Array} 32-byte batch root.
+ * @throws If any `serviceHashes[i]` is not exactly 32 bytes long.
+ * @category Utils
+ * @since v0.10.0
+ *
+ * @example
+ * ```ts
+ * import { computeBatchRoot, hashToArray } from "@synapse-sap/sdk/utils";
+ *
+ * const root = computeBatchRoot([h1, h2, h3]);
+ * await client.escrow.settleBatch(depositor, settlements, root);
+ * ```
+ */
+export const computeBatchRoot = (serviceHashes) => {
+    if (serviceHashes.length === 0) {
+        throw new Error("computeBatchRoot: serviceHashes must not be empty");
+    }
+    const hash = createHash("sha256");
+    for (let i = 0; i < serviceHashes.length; i++) {
+        const h = serviceHashes[i];
+        let buf;
+        if (h instanceof Uint8Array) {
+            buf = Buffer.from(h);
+        }
+        else if (Array.isArray(h)) {
+            buf = Buffer.from(h);
+        }
+        else {
+            throw new Error(`computeBatchRoot: serviceHashes[${i}] is undefined or unsupported type`);
+        }
+        if (buf.length !== 32) {
+            throw new Error(`computeBatchRoot: serviceHashes[${i}] must be 32 bytes, got ${buf.length}`);
+        }
+        hash.update(buf);
+    }
+    return new Uint8Array(hash.digest());
+};
+//# sourceMappingURL=hash.js.map

package/dist/esm/utils/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../../src/utils/hash.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,KAAmC,EAAc,EAAE;IACxE,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,CAAC,MAAM,CACT,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAChE,CAAC;IACF,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;AACvC,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAgB,EAAY,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,aAA4D,EAChD,EAAE;IACd,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC,YAAY,UAAU,EAAE,CAAC;YAC5B,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;aAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5B,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CACb,mCAAmC,CAAC,oCAAoC,CACzE,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,mCAAmC,CAAC,2BAA2B,GAAG,CAAC,MAAM,EAAE,CAC5E,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;AACvC,CAAC,CAAC"}

package/dist/esm/utils/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./validate";
-export declare function sha256(data: Uint8Array): Uint8Array;
+export { sha256, hashToArray } from "./hash";
 export declare function hashReceipt(agent: Uint8Array, requestId: Uint8Array, callCount: number, amount: bigint): Uint8Array;
+/** Assert helper */
+export declare function assert(cond: boolean, msg: string): asserts cond;
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAKA,cAAc,YAAY,CAAC;AAG3B,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAEnD;AAGD,wBAAgB,WAAW,CACzB,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,UAAU,EACrB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,UAAU,CAEZ"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAKA,cAAc,YAAY,CAAC;AAG3B,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAG7C,wBAAgB,WAAW,CACzB,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,UAAU,EACrB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,UAAU,CAEZ;AAED,oBAAoB;AACpB,wBAAgB,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAE/D"}

package/dist/esm/utils/index.js

@@ -4,11 +4,14 @@
 // ================================================================
 export * from "./validate";
 // ── Merkle helpers for receipt proofs ──
-export function sha256(data) {
-    return crypto.subtle.digest("SHA-256", data).then(b => new Uint8Array(b));
-}
+export { sha256, hashToArray } from "./hash";
 // client-side sha256 for receipt hashing
 export function hashReceipt(agent, requestId, callCount, amount) {
     return new Uint8Array(32); // Stub
 }
+/** Assert helper */
+export function assert(cond, msg) {
+    if (!cond)
+        throw new Error(msg);
+}
 //# sourceMappingURL=index.js.map

package/dist/esm/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,wCAAwC;AACxC,2BAA2B;AAC3B,mEAAmE;AAEnE,cAAc,YAAY,CAAC;AAE3B,0CAA0C;AAC1C,MAAM,UAAU,MAAM,CAAC,IAAgB;IACrC,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAQ,CAAC;AACnF,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,WAAW,CACzB,KAAiB,EACjB,SAAqB,EACrB,SAAiB,EACjB,MAAc;IAEd,OAAO,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO;AACpC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,wCAAwC;AACxC,2BAA2B;AAC3B,mEAAmE;AAEnE,cAAc,YAAY,CAAC;AAE3B,0CAA0C;AAC1C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE7C,yCAAyC;AACzC,MAAM,UAAU,WAAW,CACzB,KAAiB,EACjB,SAAqB,EACrB,SAAiB,EACjB,MAAc;IAEd,OAAO,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO;AACpC,CAAC;AAED,oBAAoB;AACpB,MAAM,UAAU,MAAM,CAAC,IAAa,EAAE,GAAW;IAC/C,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;AAClC,CAAC"}

package/dist/esm/utils/merchant-validator.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @module utils/merchant-validator
+ * @description Standard Synapse merchant middleware for x402 settlement.
+ *
+ * Reads `X-Payment-*` headers from incoming HTTP requests, validates
+ * the escrow on-chain, auto-generates the correct `AccountMeta[]`,
+ * and throws explicit errors (e.g. {@link MissingEscrowAtaError})
+ * instead of letting the program return a generic crash.
+ *
+ * Designed for agents like Syra/Invoica that receive x402 payments.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+import { type PublicKey, type Connection, type AccountMeta } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import type { EscrowValidationResult } from "./escrow-validation";
+import type { EscrowAccountData } from "../types";
+/**
+ * @interface ParsedX402Headers
+ * @description Parsed and typed x402 payment headers from incoming HTTP request.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface ParsedX402Headers {
+    /** x402 protocol identifier — must be "SAP-x402". */
+    readonly protocol: string;
+    /** Escrow PDA address. */
+    readonly escrowPda: PublicKey;
+    /** Agent PDA address. */
+    readonly agentPda: PublicKey;
+    /** Depositor wallet address. */
+    readonly depositorWallet: PublicKey;
+    /** Max calls allowed. */
+    readonly maxCalls: BN;
+    /** Price per call. */
+    readonly pricePerCall: BN;
+    /** SAP program ID. */
+    readonly programId: PublicKey;
+    /** Network identifier. */
+    readonly network: string;
+}
+/**
+ * @interface MerchantValidationResult
+ * @description Complete validation result for merchant-side x402 processing.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface MerchantValidationResult {
+    /** Whether the escrow is valid and ready for settlement. */
+    readonly valid: boolean;
+    /** Parsed x402 headers. */
+    readonly headers: ParsedX402Headers;
+    /** Full escrow validation result. */
+    readonly escrowValidation: EscrowValidationResult;
+    /** Pre-built AccountMeta[] for settlement TX (empty for SOL escrows). */
+    readonly accountMetas: AccountMeta[];
+    /** All validation errors. */
+    readonly errors: string[];
+}
+/**
+ * @name parseX402Headers
+ * @description Parse and validate x402 headers from an HTTP request.
+ *
+ * @param headers - HTTP headers object (case-insensitive key lookup).
+ * @returns Parsed x402 headers.
+ * @throws {SapValidationError} If required headers are missing or malformed.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+export declare function parseX402Headers(headers: Record<string, string | string[] | undefined>): ParsedX402Headers;
+/**
+ * @name SapMerchantValidator
+ * @description Standard Synapse merchant middleware for x402 payment validation.
+ *
+ * Reads `X-Payment-*` headers, validates escrow state on-chain, generates
+ * correct `AccountMeta[]` for SPL token escrows, and throws explicit errors
+ * (e.g. {@link MissingEscrowAtaError}) when ATA accounts are missing.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * const validator = new SapMerchantValidator(connection, fetchEscrow);
+ *
+ * // Express.js integration
+ * app.post("/api/v1/chat", async (req, res) => {
+ *   try {
+ *     const validation = await validator.validateRequest(req.headers, {
+ *       callsToSettle: 1,
+ *     });
+ *
+ *     if (!validation.valid) {
+ *       return res.status(402).json({ errors: validation.errors });
+ *     }
+ *
+ *     // Process request...
+ *
+ *     // Settle payment using pre-built account metas
+ *     await client.escrow.settle(
+ *       validation.headers.depositorWallet,
+ *       1,
+ *       serviceHash,
+ *       validation.accountMetas,
+ *     );
+ *
+ *     res.json({ result: "..." });
+ *   } catch (err) {
+ *     if (err instanceof MissingEscrowAtaError) {
+ *       return res.status(402).json({
+ *         error: err.message,
+ *         side: err.side,
+ *         ata: err.ataAddress,
+ *       });
+ *     }
+ *     throw err;
+ *   }
+ * });
+ * ```
+ */
+export declare class SapMerchantValidator {
+    private readonly connection;
+    private readonly fetchEscrow;
+    /**
+     * @param connection  - Solana RPC connection.
+     * @param fetchEscrow - Callback to fetch escrow account data by PDA.
+     *   Typically `(pda) => client.escrow.fetchByPda(pda).catch(() => null)`.
+     */
+    constructor(connection: Connection, fetchEscrow: (escrowPda: PublicKey) => Promise<EscrowAccountData | null>);
+    /**
+     * @name validateRequest
+     * @description Full validation pipeline for an incoming x402 request.
+     *
+     * Steps:
+     * 1. Parse `X-Payment-*` headers
+     * 2. Fetch escrow on-chain
+     * 3. Validate escrow state (balance, expiry, max calls)
+     * 4. If SPL escrow: validate ATAs exist and mint matches
+     * 5. Build `AccountMeta[]` for settlement TX
+     *
+     * @param headers - HTTP headers from the incoming request.
+     * @param opts
+     * @param opts.callsToSettle     - Number of calls to validate affordability for (default: 1).
+     * @param opts.throwOnMissingAta - Throw {@link MissingEscrowAtaError} instead of returning errors (default: true).
+     *
+     * @returns A complete {@link MerchantValidationResult}.
+     *
+     * @throws {SapValidationError} If headers are missing or malformed.
+     * @throws {MissingEscrowAtaError} If SPL ATAs are missing and `throwOnMissingAta` is true.
+     *
+     * @category Utils
+     * @since v0.6.4
+     */
+    validateRequest(headers: Record<string, string | string[] | undefined>, opts?: {
+        callsToSettle?: number;
+        throwOnMissingAta?: boolean;
+    }): Promise<MerchantValidationResult>;
+    /**
+     * @name validateEscrow
+     * @description Validate escrow from pre-parsed headers (convenience method).
+     * Call this when you've already parsed the headers yourself.
+     *
+     * @param headers - Pre-parsed x402 headers.
+     * @param opts
+     * @returns The escrow validation result with pre-built account metas.
+     *
+     * @category Utils
+     * @since v0.6.4
+     */
+    validateEscrow(headers: ParsedX402Headers, opts?: {
+        callsToSettle?: number;
+    }): Promise<EscrowValidationResult>;
+}
+//# sourceMappingURL=merchant-validator.d.ts.map

package/dist/esm/utils/merchant-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merchant-validator.d.ts","sourceRoot":"","sources":["../../../src/utils/merchant-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AAMvC,OAAO,KAAK,EACV,sBAAsB,EACvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAMlD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0BAA0B;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,eAAe,EAAE,SAAS,CAAC;IACpC,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC;IACtB,sBAAsB;IACtB,QAAQ,CAAC,YAAY,EAAE,EAAE,CAAC;IAC1B,sBAAsB;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,qCAAqC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,sBAAsB,CAAC;IAClD,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,WAAW,EAAE,CAAC;IACrC,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;CAC3B;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GACrD,iBAAiB,CA6EnB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAEW;IAEvC;;;;OAIG;gBAED,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,CACX,SAAS,EAAE,SAAS,KACjB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAMxC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,eAAe,CACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACtD,IAAI,CAAC,EAAE;QACL,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC7B,GACA,OAAO,CAAC,wBAAwB,CAAC;IAwCpC;;;;;;;;;;;OAWG;IACG,cAAc,CAClB,OAAO,EAAE,iBAAiB,EAC1B,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAChC,OAAO,CAAC,sBAAsB,CAAC;CASnC"}

package/dist/esm/utils/merchant-validator.js

@@ -0,0 +1,241 @@
+/**
+ * @module utils/merchant-validator
+ * @description Standard Synapse merchant middleware for x402 settlement.
+ *
+ * Reads `X-Payment-*` headers from incoming HTTP requests, validates
+ * the escrow on-chain, auto-generates the correct `AccountMeta[]`,
+ * and throws explicit errors (e.g. {@link MissingEscrowAtaError})
+ * instead of letting the program return a generic crash.
+ *
+ * Designed for agents like Syra/Invoica that receive x402 payments.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+import { PublicKey as PK } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { validateEscrowState, toAccountMetas, MissingEscrowAtaError, } from "./escrow-validation";
+import { SapValidationError } from "../errors/index";
+// ═══════════════════════════════════════════════════════════════════
+//  Header parsing
+// ═══════════════════════════════════════════════════════════════════
+/** Required x402 headers. */
+const REQUIRED_HEADERS = [
+    "X-Payment-Protocol",
+    "X-Payment-Escrow",
+    "X-Payment-Agent",
+    "X-Payment-Depositor",
+    "X-Payment-MaxCalls",
+    "X-Payment-PricePerCall",
+    "X-Payment-Program",
+    "X-Payment-Network",
+];
+/**
+ * @name parseX402Headers
+ * @description Parse and validate x402 headers from an HTTP request.
+ *
+ * @param headers - HTTP headers object (case-insensitive key lookup).
+ * @returns Parsed x402 headers.
+ * @throws {SapValidationError} If required headers are missing or malformed.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+export function parseX402Headers(headers) {
+    // Normalize to case-insensitive
+    const normalized = new Map();
+    for (const [key, value] of Object.entries(headers)) {
+        const val = Array.isArray(value) ? value[0] : value;
+        if (val !== undefined) {
+            normalized.set(key.toLowerCase(), val);
+        }
+    }
+    // Validate required headers present
+    const missing = [];
+    for (const h of REQUIRED_HEADERS) {
+        if (!normalized.has(h.toLowerCase())) {
+            missing.push(h);
+        }
+    }
+    if (missing.length > 0) {
+        throw new SapValidationError(`Missing required x402 headers: ${missing.join(", ")}`, "x402-headers");
+    }
+    const get = (key) => normalized.get(key.toLowerCase());
+    // Validate protocol
+    const protocol = get("X-Payment-Protocol");
+    if (protocol !== "SAP-x402") {
+        throw new SapValidationError(`Invalid X-Payment-Protocol: "${protocol}" (expected "SAP-x402")`, "X-Payment-Protocol");
+    }
+    // Parse PublicKeys
+    let escrowPda;
+    let agentPda;
+    let depositorWallet;
+    let programId;
+    try {
+        escrowPda = new PK(get("X-Payment-Escrow"));
+        agentPda = new PK(get("X-Payment-Agent"));
+        depositorWallet = new PK(get("X-Payment-Depositor"));
+        programId = new PK(get("X-Payment-Program"));
+    }
+    catch {
+        throw new SapValidationError("Malformed public key in x402 headers", "x402-headers");
+    }
+    // Parse numeric values
+    const maxCallsStr = get("X-Payment-MaxCalls");
+    const pricePerCallStr = get("X-Payment-PricePerCall");
+    let maxCalls;
+    let pricePerCall;
+    try {
+        maxCalls = new BN(maxCallsStr);
+        pricePerCall = new BN(pricePerCallStr);
+    }
+    catch {
+        throw new SapValidationError("Invalid numeric value in X-Payment-MaxCalls or X-Payment-PricePerCall", "x402-headers");
+    }
+    return {
+        protocol,
+        escrowPda,
+        agentPda,
+        depositorWallet,
+        maxCalls,
+        pricePerCall,
+        programId,
+        network: get("X-Payment-Network"),
+    };
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Merchant Validator
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name SapMerchantValidator
+ * @description Standard Synapse merchant middleware for x402 payment validation.
+ *
+ * Reads `X-Payment-*` headers, validates escrow state on-chain, generates
+ * correct `AccountMeta[]` for SPL token escrows, and throws explicit errors
+ * (e.g. {@link MissingEscrowAtaError}) when ATA accounts are missing.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * const validator = new SapMerchantValidator(connection, fetchEscrow);
+ *
+ * // Express.js integration
+ * app.post("/api/v1/chat", async (req, res) => {
+ *   try {
+ *     const validation = await validator.validateRequest(req.headers, {
+ *       callsToSettle: 1,
+ *     });
+ *
+ *     if (!validation.valid) {
+ *       return res.status(402).json({ errors: validation.errors });
+ *     }
+ *
+ *     // Process request...
+ *
+ *     // Settle payment using pre-built account metas
+ *     await client.escrow.settle(
+ *       validation.headers.depositorWallet,
+ *       1,
+ *       serviceHash,
+ *       validation.accountMetas,
+ *     );
+ *
+ *     res.json({ result: "..." });
+ *   } catch (err) {
+ *     if (err instanceof MissingEscrowAtaError) {
+ *       return res.status(402).json({
+ *         error: err.message,
+ *         side: err.side,
+ *         ata: err.ataAddress,
+ *       });
+ *     }
+ *     throw err;
+ *   }
+ * });
+ * ```
+ */
+export class SapMerchantValidator {
+    connection;
+    fetchEscrow;
+    /**
+     * @param connection  - Solana RPC connection.
+     * @param fetchEscrow - Callback to fetch escrow account data by PDA.
+     *   Typically `(pda) => client.escrow.fetchByPda(pda).catch(() => null)`.
+     */
+    constructor(connection, fetchEscrow) {
+        this.connection = connection;
+        this.fetchEscrow = fetchEscrow;
+    }
+    /**
+     * @name validateRequest
+     * @description Full validation pipeline for an incoming x402 request.
+     *
+     * Steps:
+     * 1. Parse `X-Payment-*` headers
+     * 2. Fetch escrow on-chain
+     * 3. Validate escrow state (balance, expiry, max calls)
+     * 4. If SPL escrow: validate ATAs exist and mint matches
+     * 5. Build `AccountMeta[]` for settlement TX
+     *
+     * @param headers - HTTP headers from the incoming request.
+     * @param opts
+     * @param opts.callsToSettle     - Number of calls to validate affordability for (default: 1).
+     * @param opts.throwOnMissingAta - Throw {@link MissingEscrowAtaError} instead of returning errors (default: true).
+     *
+     * @returns A complete {@link MerchantValidationResult}.
+     *
+     * @throws {SapValidationError} If headers are missing or malformed.
+     * @throws {MissingEscrowAtaError} If SPL ATAs are missing and `throwOnMissingAta` is true.
+     *
+     * @category Utils
+     * @since v0.6.4
+     */
+    async validateRequest(headers, opts) {
+        // 1. Parse headers
+        const parsed = parseX402Headers(headers);
+        // 2. Validate escrow state
+        const escrowValidation = await validateEscrowState(this.connection, parsed.agentPda, // agentWallet derived inside validate
+        parsed.depositorWallet, this.fetchEscrow, { callsToSettle: opts?.callsToSettle ?? 1 });
+        // 3. Check for ATA errors and optionally throw
+        const throwOnMissingAta = opts?.throwOnMissingAta !== false;
+        if (throwOnMissingAta && escrowValidation.isSplEscrow) {
+            for (const error of escrowValidation.errors) {
+                if (error.includes("Depositor ATA does not exist")) {
+                    const ataAddr = error.split(": ")[1] ?? "unknown";
+                    throw new MissingEscrowAtaError(ataAddr, "depositor");
+                }
+                if (error.includes("Escrow ATA does not exist")) {
+                    const ataAddr = error.split(": ")[1] ?? "unknown";
+                    throw new MissingEscrowAtaError(ataAddr, "escrow");
+                }
+            }
+        }
+        // 4. Build account metas
+        const accountMetas = toAccountMetas(escrowValidation.splAccounts);
+        return {
+            valid: escrowValidation.valid,
+            headers: parsed,
+            escrowValidation,
+            accountMetas,
+            errors: escrowValidation.errors,
+        };
+    }
+    /**
+     * @name validateEscrow
+     * @description Validate escrow from pre-parsed headers (convenience method).
+     * Call this when you've already parsed the headers yourself.
+     *
+     * @param headers - Pre-parsed x402 headers.
+     * @param opts
+     * @returns The escrow validation result with pre-built account metas.
+     *
+     * @category Utils
+     * @since v0.6.4
+     */
+    async validateEscrow(headers, opts) {
+        return validateEscrowState(this.connection, headers.agentPda, headers.depositorWallet, this.fetchEscrow, opts);
+    }
+}
+//# sourceMappingURL=merchant-validator.js.map

package/dist/esm/utils/merchant-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merchant-validator.js","sourceRoot":"","sources":["../../../src/utils/merchant-validator.ts"],"names":[],"mappings":"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"}