@oobe-protocol-labs/synapse-sap-sdk 0.6.3 → 0.8.0

package/dist/esm/types/enums.js

@@ -168,4 +168,99 @@ export const ToolCategory = {
     Analytics: { analytics: {} },
     Custom: { custom: {} },
 };
+// ═══════════════════════════════════════════════════════════════════
+//  Settlement Security (V2.1)
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name SettlementSecurity
+ * @description Anchor-compatible enum variants for V2 escrow settlement security levels.
+ *
+ * - `SelfReport` — **DEPRECATED in v0.7** — Agent settles unilaterally (abuse vector).
+ * - `CoSigned` — Agent + client must co-sign every settlement.
+ * - `DisputeWindow` — Settlement enters pending state, depositor can dispute.
+ *
+ * @category Types
+ * @since v0.5.0
+ */
+export const SettlementSecurity = {
+    /** @deprecated Removed in v0.7 — returns SelfReportDeprecated error */
+    SelfReport: { selfReport: {} },
+    CoSigned: { coSigned: {} },
+    DisputeWindow: { disputeWindow: {} },
+};
+// ═══════════════════════════════════════════════════════════════════
+//  Dispute Outcome (V2.1)
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name DisputeOutcome
+ * @description Anchor-compatible enum variants for dispute resolution outcomes.
+ *
+ * @category Types
+ * @since v0.5.0
+ */
+export const DisputeOutcome = {
+    Pending: { pending: {} },
+    AutoReleased: { autoReleased: {} },
+    DepositorWins: { depositorWins: {} },
+    AgentWins: { agentWins: {} },
+    /** @since v0.7.0 — Proportional refund based on proven vs claimed calls */
+    PartialRefund: { partialRefund: {} },
+    /** @since v0.7.0 — 50/50 split for irresolvable quality disputes */
+    Split: { split: {} },
+};
+// ═══════════════════════════════════════════════════════════════════
+//  Dispute Type (v0.7)
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name DisputeType
+ * @description Categories of disputes that can be filed against a pending settlement.
+ *
+ * - `NonDelivery` — Agent took payment but delivered nothing.
+ * - `PartialDelivery` — Agent delivered fewer calls than claimed.
+ * - `Overcharge` — Agent charged more than the agreed price.
+ * - `Quality` — Agent delivered but output quality is disputed.
+ *
+ * @category Types
+ * @since v0.7.0
+ */
+export const DisputeType = {
+    NonDelivery: 0,
+    PartialDelivery: 1,
+    Overcharge: 2,
+    Quality: 3,
+};
+// ═══════════════════════════════════════════════════════════════════
+//  Resolution Layer (v0.7)
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name ResolutionLayer
+ * @description How a dispute was resolved.
+ *
+ * - `Pending` — Not yet resolved.
+ * - `Auto` — Resolved automatically via receipt merkle proofs.
+ * - `Governance` — Resolved via protocol governance (quality disputes).
+ *
+ * @category Types
+ * @since v0.7.0
+ */
+export const ResolutionLayer = {
+    Pending: { pending: {} },
+    Auto: { auto: {} },
+    Governance: { governance: {} },
+};
+// ═══════════════════════════════════════════════════════════════════
+//  Billing Interval (V2.1)
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name BillingInterval
+ * @description Anchor-compatible enum variants for subscription billing intervals.
+ *
+ * @category Types
+ * @since v0.5.0
+ */
+export const BillingInterval = {
+    Daily: { daily: {} },
+    Weekly: { weekly: {} },
+    Monthly: { monthly: {} },
+};
 //# sourceMappingURL=enums.js.map

package/dist/esm/types/enums.js.map

@@ -1 +1 @@
-{"version":3,"file":"enums.js","sourceRoot":"","sources":["../../../src/types/enums.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,sEAAsE;AACtE,cAAc;AACd,sEAAsE;AAEtE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,GAAG,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE;IAChB,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;IAClB,GAAG,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE;CACR,CAAC;AASX,sEAAsE;AACtE,eAAe;AACf,sEAAsE;AAEtE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;IACtB,UAAU,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE;IAC9B,UAAU,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE;IAC9B,SAAS,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;IAC5B,UAAU,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE;IAC9B,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;CACd,CAAC;AAQX,sEAAsE;AACtE,mBAAmB;AACnB,sEAAsE;AAEtE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,OAAO,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;IACxB,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;IACtB,OAAO,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;IACxB,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;CACV,CAAC;AASX,sEAAsE;AACtE,oBAAoB;AACpB,sEAAsE;AAEtE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,GAAG,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE;IAChB,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;IAClB,GAAG,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE;IAChB,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;IACtB,QAAQ,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;CAClB,CAAC;AASX,sEAAsE;AACtE,iBAAiB;AACjB,sEAAsE;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;IAClB,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;IAClB,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;IACpB,GAAG,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE;IAChB,OAAO,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;IACxB,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;IAClB,UAAU,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE;IAC9B,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;IACtB,SAAS,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;IAC5B,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;CACd,CAAC"}
+{"version":3,"file":"enums.js","sourceRoot":"","sources":["../../../src/types/enums.ts"],"names":[],"mappings":"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"}

package/dist/esm/types/index.js

@@ -20,6 +20,6 @@
  * ```
  */
 // ── Enums ────────────────────────────────────────────
-export { TokenType, PluginType, SettlementMode, ToolHttpMethod, ToolCategory, } from "./enums";
+export { TokenType, PluginType, SettlementMode, ToolHttpMethod, ToolCategory, SettlementSecurity, DisputeOutcome, BillingInterval, DisputeType, ResolutionLayer, } from "./enums";
 export { DelegatePermission, SchemaType, CompressionType, } from "./instructions";
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,wDAAwD;AACxD,OAAO,EACL,SAAS,EACT,UAAU,EACV,cAAc,EACd,cAAc,EACd,YAAY,GACb,MAAM,SAAS,CAAC;AA0DjB,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,eAAe,GAChB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,wDAAwD;AACxD,OAAO,EACL,SAAS,EACT,UAAU,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,WAAW,EACX,eAAe,GAChB,MAAM,SAAS,CAAC;AAyEjB,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,eAAe,GAChB,MAAM,gBAAgB,CAAC"}

package/dist/esm/types/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/types/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA+SH,sEAAsE;AACtE,+BAA+B;AAC/B,sEAAsE;AAEtE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,QAAQ,EAAE,CAAC;IACX,YAAY,EAAE,CAAC;IACf,WAAW,EAAE,CAAC;IACd,GAAG,EAAE,CAAC;CACE,CAAC;AASX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,KAAK,EAAE,CAAC;IACR,MAAM,EAAE,CAAC;IACT,WAAW,EAAE,CAAC;CACN,CAAC;AAQX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,CAAC;IACP,OAAO,EAAE,CAAC;IACV,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;CACD,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/types/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgTH,sEAAsE;AACtE,+BAA+B;AAC/B,sEAAsE;AAEtE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,QAAQ,EAAE,CAAC;IACX,YAAY,EAAE,CAAC;IACf,WAAW,EAAE,CAAC;IACd,GAAG,EAAE,CAAC;CACE,CAAC;AASX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,KAAK,EAAE,CAAC;IACR,MAAM,EAAE,CAAC;IACT,WAAW,EAAE,CAAC;CACN,CAAC;AAQX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,CAAC;IACP,OAAO,EAAE,CAAC;IACV,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;CACD,CAAC"}

package/dist/esm/utils/escrow-validation.js

@@ -0,0 +1,212 @@
+/**
+ * @module utils/escrow-validation
+ * @description Server-side escrow validation pipeline.
+ *
+ * Provides typed helpers to validate escrow state before settlement
+ * and to build the correct SPL `AccountMeta[]` for token escrows.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+import { PublicKey, } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { findATA } from "./rpc-strategy";
+import { deriveAgent, deriveEscrow } from "../pda";
+import { SapError } from "../errors";
+// ═══════════════════════════════════════════════════════════════════
+//  Error
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name MissingEscrowAtaError
+ * @description Thrown when an SPL escrow operation is missing required
+ * Associated Token Accounts.
+ * @category Errors
+ * @since v0.6.4
+ */
+export class MissingEscrowAtaError extends SapError {
+    /** The ATA address that is missing. */
+    ataAddress;
+    /** Which side is missing: depositor or escrow. */
+    side;
+    constructor(ataAddress, side) {
+        super(`Missing ${side} ATA: ${ataAddress}. ` +
+            `Settlement mode is Escrow/SPL but the Associated Token Account does not exist. ` +
+            `The ${side} must create the ATA before escrow operations.`, "SAP_MISSING_ESCROW_ATA");
+        this.name = "MissingEscrowAtaError";
+        this.ataAddress = ataAddress;
+        this.side = side;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Validation
+// ═══════════════════════════════════════════════════════════════════
+/** Standard SPL Token program ID. */
+const TOKEN_PROGRAM_ID_STR = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+/**
+ * @name validateEscrowState
+ * @description Validates that an escrow is in a correct state for settlement.
+ *
+ * Checks:
+ * - Escrow PDA exists on-chain
+ * - If SPL: depositor ATA exists, escrow ATA exists, token mint matches
+ * - Balance >= requested settlement amount
+ * - Escrow is not expired
+ * - Max calls not exceeded
+ *
+ * @param connection  - Solana RPC connection.
+ * @param agentWallet - The agent's wallet public key.
+ * @param depositorWallet - The depositor's wallet public key.
+ * @param fetchEscrow - Callback to fetch escrow data (avoids coupling to SapProgram).
+ * @param opts
+ * @param opts.callsToSettle - Number of calls to validate affordability for.
+ *
+ * @returns A detailed {@link EscrowValidationResult}.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * const result = await validateEscrowState(
+ *   connection,
+ *   agentWallet,
+ *   depositorWallet,
+ *   (pda) => client.escrow.fetchByPda(pda),
+ *   { callsToSettle: 5 },
+ * );
+ *
+ * if (!result.valid) {
+ *   console.error("Escrow validation failed:", result.errors);
+ * }
+ * ```
+ */
+export async function validateEscrowState(connection, agentWallet, depositorWallet, fetchEscrow, opts) {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = deriveEscrow(agentPda, depositorWallet);
+    const errors = [];
+    // 1. Fetch escrow
+    const escrow = await fetchEscrow(escrowPda);
+    if (!escrow) {
+        return {
+            valid: false,
+            escrow: null,
+            escrowPda,
+            agentPda,
+            isSplEscrow: false,
+            splAccounts: [],
+            errors: [`Escrow not found at ${escrowPda.toBase58()}`],
+        };
+    }
+    // 2. Check expiry
+    if (escrow.expiresAt.gt(new BN(0))) {
+        const now = Math.floor(Date.now() / 1000);
+        if (escrow.expiresAt.lt(new BN(now))) {
+            errors.push(`Escrow expired at ${escrow.expiresAt.toString()}`);
+        }
+    }
+    // 3. Check balance / calls
+    const callsToSettle = opts?.callsToSettle ?? 1;
+    const costForCalls = escrow.pricePerCall.mul(new BN(callsToSettle));
+    if (escrow.balance.lt(costForCalls)) {
+        errors.push(`Insufficient balance: ${escrow.balance.toString()} < ${costForCalls.toString()} (${callsToSettle} calls × ${escrow.pricePerCall.toString()})`);
+    }
+    // 4. Check max calls
+    if (escrow.maxCalls.gt(new BN(0))) {
+        const remaining = escrow.maxCalls.sub(escrow.totalCallsSettled);
+        if (remaining.lt(new BN(callsToSettle))) {
+            errors.push(`Max calls exceeded: ${remaining.toString()} remaining but needs ${callsToSettle}`);
+        }
+    }
+    // 5. Determine if SPL
+    const isSplEscrow = escrow.tokenMint !== null &&
+        escrow.tokenMint.toBase58() !== "11111111111111111111111111111111";
+    // 6. Build SPL accounts (if SPL escrow)
+    const splAccounts = [];
+    if (isSplEscrow) {
+        const mint = escrow.tokenMint;
+        const depositorAta = findATA(depositorWallet, mint);
+        const escrowAta = findATA(escrowPda, mint);
+        // Verify depositor ATA exists
+        const depositorAtaInfo = await connection.getAccountInfo(depositorAta);
+        if (!depositorAtaInfo) {
+            errors.push(`Depositor ATA does not exist: ${depositorAta.toBase58()}`);
+        }
+        // Verify escrow ATA exists
+        const escrowAtaInfo = await connection.getAccountInfo(escrowAta);
+        if (!escrowAtaInfo) {
+            errors.push(`Escrow ATA does not exist: ${escrowAta.toBase58()}`);
+        }
+        // Verify mint matches
+        if (depositorAtaInfo) {
+            // SPL token account data: bytes 0-32 = mint
+            const ataMint = depositorAtaInfo.data.subarray(0, 32);
+            if (Buffer.from(ataMint).toString("hex") !== mint.toBuffer().toString("hex")) {
+                errors.push(`Depositor ATA mint mismatch: expected ${mint.toBase58()}`);
+            }
+        }
+        splAccounts.push({ kind: "depositorAta", pubkey: depositorAta, writable: true }, { kind: "escrowAta", pubkey: escrowAta, writable: true }, { kind: "tokenMint", pubkey: mint, writable: false }, { kind: "tokenProgram", pubkey: new PublicKey(TOKEN_PROGRAM_ID_STR), writable: false });
+    }
+    return {
+        valid: errors.length === 0,
+        escrow,
+        escrowPda,
+        agentPda,
+        isSplEscrow,
+        splAccounts,
+        errors,
+    };
+}
+/**
+ * @name attachSplAccounts
+ * @description Build the typed `SplAccountMeta[]` for an SPL token escrow operation.
+ * Does NOT validate existence — use {@link validateEscrowState} for full validation.
+ *
+ * @param escrowPda      - The escrow PDA address.
+ * @param depositorWallet - The depositor's wallet public key.
+ * @param tokenMint      - The SPL token mint.
+ * @returns An array of typed {@link SplAccountMeta} for SPL escrow operations.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * const splMetas = attachSplAccounts(escrowPda, depositorWallet, usdcMint);
+ *
+ * // Convert to Anchor-compatible AccountMeta[]
+ * const accountMetas = splMetas.map(m => ({
+ *   pubkey: m.pubkey,
+ *   isWritable: m.writable,
+ *   isSigner: false,
+ * }));
+ *
+ * await client.escrow.settle(depositor, calls, hash, accountMetas);
+ * ```
+ */
+export function attachSplAccounts(escrowPda, depositorWallet, tokenMint) {
+    return [
+        { kind: "depositorAta", pubkey: findATA(depositorWallet, tokenMint), writable: true },
+        { kind: "escrowAta", pubkey: findATA(escrowPda, tokenMint), writable: true },
+        { kind: "tokenMint", pubkey: tokenMint, writable: false },
+        { kind: "tokenProgram", pubkey: new PublicKey(TOKEN_PROGRAM_ID_STR), writable: false },
+    ];
+}
+/**
+ * @name toAccountMetas
+ * @description Convert typed {@link SplAccountMeta} to Anchor-compatible
+ * `AccountMeta[]` for use with `.remainingAccounts()`.
+ *
+ * @param splMetas - Array of typed SPL account metas.
+ * @returns `AccountMeta[]` compatible with Anchor's `remainingAccounts`.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+export function toAccountMetas(splMetas) {
+    return splMetas.map((m) => ({
+        pubkey: m.pubkey,
+        isWritable: m.writable,
+        isSigner: false,
+    }));
+}
+//# sourceMappingURL=escrow-validation.js.map

package/dist/esm/utils/escrow-validation.js.map

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

package/dist/esm/utils/index.js

@@ -23,4 +23,8 @@ export { getRpcUrl, getFallbackRpcUrl, createDualConnection, findATA, classifyAn
 export { createEnvSchema, createEndpointDescriptorSchema, createHealthCheckSchema, createToolManifestEntrySchema, createAgentManifestSchema, createPreparePaymentSchema, createRegisterAgentSchema, createCallArgsSchema, validateOrThrow, } from "./schemas";
 // ── v0.6.2  Priority Fee & Settle Options ───────────
 export { buildPriorityFeeIxs, buildRpcOptions, FAST_SETTLE_OPTIONS, FAST_BATCH_SETTLE_OPTIONS, DEFAULT_SETTLE_PRIORITY_FEE, DEFAULT_SETTLE_COMPUTE_UNITS, DEFAULT_BATCH_SETTLE_COMPUTE_UNITS, } from "./priority-fee";
+// ── v0.6.4  Escrow Validation & Merchant Middleware ──
+export { validateEscrowState, attachSplAccounts, toAccountMetas, MissingEscrowAtaError, } from "./escrow-validation";
+export { SapMerchantValidator, parseX402Headers, } from "./merchant-validator";
+export { getX402DirectPayments } from "./x402-direct";
 //# 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;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEnE,uDAAuD;AACvD,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,oBAAoB,EACpB,OAAO,EACP,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,eAAe,EACf,8BAA8B,EAC9B,uBAAuB,EACvB,6BAA6B,EAC7B,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,GAChB,MAAM,WAAW,CAAC;AAEnB,uDAAuD;AACvD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,EAC5B,kCAAkC,GACnC,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEnE,uDAAuD;AACvD,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,oBAAoB,EACpB,OAAO,EACP,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,eAAe,EACf,8BAA8B,EAC9B,uBAAuB,EACvB,6BAA6B,EAC7B,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,GAChB,MAAM,WAAW,CAAC;AAEnB,uDAAuD;AACvD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,EAC5B,kCAAkC,GACnC,MAAM,gBAAgB,CAAC;AAMxB,wDAAwD;AACxD,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAM7B,OAAO,EACL,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

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";
+// ═══════════════════════════════════════════════════════════════════
+//  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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"}