@agirails/sdk 3.2.0 → 3.4.1

package/dist/transport/QuoteChannel.js

@@ -0,0 +1,358 @@
+"use strict";
+/**
+ * QuoteChannel — HTTPS transport for AIP-2.1 quote + counter-offer messages.
+ *
+ * Split into three responsibilities so the SDK is framework-agnostic:
+ *
+ *  1. `QuoteChannelClient`  — sends a signed message to a peer's endpoint.
+ *     Used by buyers (posting counter-offers to the provider) and by
+ *     providers (posting quotes to the buyer). Plain fetch + timeout.
+ *
+ *  2. `QuoteChannelHandler` — framework-agnostic receive-side handler.
+ *     Callers wire it into whatever HTTP framework they use (Express,
+ *     Next.js route handler, Fastify, etc). Enforces the security model
+ *     from AIP-2.1-DRAFT §8:
+ *        - URL path binding: `/quote-channel/{chainId}/{txId}` must
+ *          match message.chainId / message.txId (closes T2 + T5).
+ *        - EIP-712 signature verification (closes "anyone can POST").
+ *        - TTL + grace window (closes T3).
+ *        - Nonce LRU dedup (closes T1, idempotent replay).
+ *     Rate limiting is intentionally out of scope — framework-level
+ *     concern (Next.js middleware, Express rate-limit, nginx, etc).
+ *
+ *  3. `DedupStore` — swappable backing for the nonce LRU. In-memory
+ *     default for single-process use; callers can plug Redis etc. for
+ *     multi-worker production.
+ *
+ * @module transport/QuoteChannel
+ * @see Protocol/aips/AIP-2.1-DRAFT.md §8 (threat model + mitigations)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertSafePeerUrl = exports.QuoteChannelHandler = exports.QuoteChannelClient = exports.InMemoryDedupStore = exports.DEDUP_TTL_SECONDS = exports.TTL_GRACE_SECONDS = exports.buildChannelPath = void 0;
+const QuoteBuilder_1 = require("../builders/QuoteBuilder");
+const CounterOfferBuilder_1 = require("../builders/CounterOfferBuilder");
+const NonceManager_1 = require("../utils/NonceManager");
+const ethers_1 = require("ethers");
+// ============================================================================
+// Constants (exported for tests + callers that want to align)
+// ============================================================================
+/** Path pattern builders use / handlers expect. */
+function buildChannelPath(chainId, txId) {
+    return `/quote-channel/${chainId}/${txId}`;
+}
+exports.buildChannelPath = buildChannelPath;
+exports.TTL_GRACE_SECONDS = 30;
+exports.DEDUP_TTL_SECONDS = 90000; // 25h (covers max quote TTL + grace)
+/**
+ * Single-process in-memory LRU. Callers replace this in production
+ * with a distributed store (Redis SET NX EX, DynamoDB conditional put,
+ * Postgres INSERT ... ON CONFLICT DO NOTHING, etc).
+ *
+ * Atomicity here is free because JavaScript event-loop execution is
+ * single-threaded — a `recordOnce` call cannot be interrupted mid-way.
+ * Multi-worker deployments MUST use a real distributed store or will
+ * see duplicate 'recorded' returns across workers.
+ */
+class InMemoryDedupStore {
+    constructor(maxSize = 10000) {
+        this.entries = new Map(); // key → expires_at_ms
+        this.maxSize = maxSize;
+    }
+    async recordOnce(key, ttlMs) {
+        this.dropExpired();
+        const now = Date.now();
+        const exp = this.entries.get(key);
+        if (exp !== undefined && exp > now) {
+            return 'duplicate';
+        }
+        // Atomic in single-threaded JS — the check above and this set happen
+        // without any await in between, so no other task can interleave.
+        this.entries.set(key, now + ttlMs);
+        // Trim AFTER the set so `size <= maxSize` is an invariant. Trimming
+        // before the set would still leave the map at maxSize+1 after set.
+        this.trimToSize();
+        return 'recorded';
+    }
+    /** Drop entries whose TTL has elapsed. O(n) — fine for our sizes. */
+    dropExpired() {
+        const now = Date.now();
+        for (const [k, exp] of this.entries) {
+            if (exp <= now)
+                this.entries.delete(k);
+        }
+    }
+    /** Bound the map at `maxSize` by evicting oldest-inserted keys. */
+    trimToSize() {
+        while (this.entries.size > this.maxSize) {
+            const firstKey = this.entries.keys().next().value;
+            if (firstKey === undefined)
+                break;
+            this.entries.delete(firstKey);
+        }
+    }
+}
+exports.InMemoryDedupStore = InMemoryDedupStore;
+class QuoteChannelClient {
+    constructor(cfg = {}) {
+        this.timeoutMs = cfg.timeoutMs ?? 10000;
+        this.fetchImpl = cfg.fetchImpl ?? fetch;
+        this.allowInsecureTargets = cfg.allowInsecureTargets ?? false;
+    }
+    /** POST a provider quote to the buyer's endpoint. */
+    async sendQuote(peerEndpoint, quote) {
+        await this.post(peerEndpoint, quote.chainId, quote.txId, {
+            type: 'agirails.quote.v1',
+            message: quote,
+        });
+    }
+    /** POST a buyer counter-offer to the provider's endpoint. */
+    async sendCounter(peerEndpoint, counter) {
+        await this.post(peerEndpoint, counter.chainId, counter.txId, {
+            type: 'agirails.counteroffer.v1',
+            message: counter,
+        });
+    }
+    async post(peerEndpoint, chainId, txId, payload) {
+        const url = `${stripTrailingSlash(peerEndpoint)}${buildChannelPath(chainId, txId)}`;
+        // SSRF guard. Peer endpoints come from on-chain AgentRegistry / the
+        // agirails.app DB — both technically writable by an adversary. A
+        // malicious endpoint pointing at http://169.254.169.254/ (AWS metadata),
+        // http://localhost:8080 (internal service), or http://10.x.x.x (RFC1918
+        // internal) would have the client leak signed payloads inside the
+        // deployer's infrastructure. Fail fast in `new URL()` + string checks.
+        assertSafePeerUrl(url, this.allowInsecureTargets);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await this.fetchImpl(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`Quote channel POST failed: ${res.status} ${res.statusText}${text ? ` — ${text}` : ''}`);
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.QuoteChannelClient = QuoteChannelClient;
+class QuoteChannelHandler {
+    constructor(cfg) {
+        this.kernelAddressByChainId = cfg.kernelAddressByChainId;
+        this.dedupStore = cfg.dedupStore ?? new InMemoryDedupStore();
+        this.ttlGraceSeconds = cfg.ttlGraceSeconds ?? exports.TTL_GRACE_SECONDS;
+        const throwawayWallet = ethers_1.Wallet.createRandom();
+        const throwawayNonces = new NonceManager_1.InMemoryNonceManager();
+        this.quoteVerifier = new QuoteBuilder_1.QuoteBuilder(throwawayWallet, throwawayNonces);
+        this.counterVerifier = new CounterOfferBuilder_1.CounterOfferBuilder(throwawayWallet, throwawayNonces);
+    }
+    /**
+     * Validate + dedup an incoming POST.
+     * Caller is responsible for: parsing URL path into `pathChainId` /
+     * `pathTxId`, parsing request body into `ChannelPayload`, and rate
+     * limiting the endpoint at the framework level.
+     */
+    async handle(payload, ctx) {
+        // 1. Shape check on the payload wrapper.
+        if (!isChannelPayload(payload)) {
+            return {
+                status: 400,
+                body: { accepted: false, reason: 'Invalid payload shape' },
+            };
+        }
+        // 2. Path binding — the URL path chainId/txId MUST match the inner message.
+        if (payload.message.chainId !== ctx.pathChainId) {
+            return {
+                status: 400,
+                body: { accepted: false, reason: 'chainId mismatch between URL and message' },
+            };
+        }
+        if (payload.message.txId.toLowerCase() !== ctx.pathTxId.toLowerCase()) {
+            return {
+                status: 400,
+                body: { accepted: false, reason: 'txId mismatch between URL and message' },
+            };
+        }
+        // 3. Kernel address must be configured for this chain.
+        const kernelAddress = this.kernelAddressByChainId[payload.message.chainId];
+        if (!kernelAddress) {
+            return {
+                status: 400,
+                body: { accepted: false, reason: `Unsupported chainId: ${payload.message.chainId}` },
+            };
+        }
+        // 4. TTL + grace. Check expiry BEFORE signature to fast-reject stale traffic
+        // cheaply; signature verification is the expensive step.
+        const now = Math.floor(Date.now() / 1000);
+        if (payload.message.expiresAt + this.ttlGraceSeconds < now) {
+            return {
+                status: 410,
+                body: { accepted: false, reason: 'Message expired' },
+            };
+        }
+        // 5. Signature verification + business rules (delegated to the builder).
+        try {
+            if (payload.type === 'agirails.quote.v1') {
+                await this.quoteVerifier.verify(payload.message, kernelAddress);
+            }
+            else {
+                await this.counterVerifier.verify(payload.message, kernelAddress);
+            }
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            // Signature failures vs schema/band failures are both client errors;
+            // distinguish with 401 (auth) vs 422 (validation) for better diagnostics.
+            const isAuth = /signature|Invalid signature|recovered/i.test(reason);
+            return {
+                status: isAuth ? 401 : 422,
+                body: { accepted: false, reason },
+            };
+        }
+        // 6. Dedup via nonce LRU. Key is (type, signerDID, nonce) — uniquely
+        // identifies a signed message within its issuing agent's nonce space.
+        // Single atomic recordOnce() call (not check-then-record) so concurrent
+        // workers competing on the same key see exactly one 'recorded'; the
+        // rest see 'duplicate' and return the idempotent cached response.
+        const signerDID = payload.type === 'agirails.quote.v1'
+            ? payload.message.provider
+            : payload.message.consumer;
+        const dedupKey = `${payload.type}:${signerDID}:${payload.message.nonce}`;
+        const outcome = await this.dedupStore.recordOnce(dedupKey, exports.DEDUP_TTL_SECONDS * 1000);
+        if (outcome === 'duplicate') {
+            return { status: 200, body: { accepted: true, duplicate: true } };
+        }
+        return { status: 201, body: { accepted: true, duplicate: false } };
+    }
+}
+exports.QuoteChannelHandler = QuoteChannelHandler;
+// ============================================================================
+// Helpers
+// ============================================================================
+function stripTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+/**
+ * Reject peer URLs that could SSRF into local / internal infrastructure.
+ *
+ * Rules (default, `allowInsecureTargets=false`):
+ *   - scheme MUST be https
+ *   - hostname MUST NOT be `localhost`
+ *   - hostname MUST NOT be a literal loopback IP (127.x.x.x, ::1)
+ *   - hostname MUST NOT be a literal link-local IP (169.254.x.x, fe80::/10)
+ *     — this also covers AWS metadata at 169.254.169.254
+ *   - hostname MUST NOT be a literal RFC1918 private IP (10.x, 172.16-31.x,
+ *     192.168.x) or IPv6 ULA (fc00::/7)
+ *
+ * Dev mode (`allowInsecureTargets=true`): no restrictions, callers
+ * opting in are responsible for their own network security.
+ *
+ * @throws Error if the URL fails the checks. Error message is deliberately
+ *   specific so test fixtures and diagnostics can assert on it.
+ * @internal Exported for unit tests.
+ */
+function assertSafePeerUrl(url, allowInsecureTargets) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid peer URL: ${url}`);
+    }
+    if (allowInsecureTargets)
+        return;
+    if (parsed.protocol !== 'https:') {
+        throw new Error(`Peer URL must use https:// (got ${parsed.protocol}//). ` +
+            `Set allowInsecureTargets=true on the QuoteChannelClient for dev/test only.`);
+    }
+    // Node's URL() keeps brackets around IPv6 hosts. Strip them so the
+    // downstream string checks work uniformly for IPv4 and IPv6 literals.
+    const rawHost = parsed.hostname.toLowerCase();
+    const stripped = rawHost.startsWith('[') && rawHost.endsWith(']')
+        ? rawHost.slice(1, -1)
+        : rawHost;
+    // IPv4-mapped IPv6 — the OS resolves this to the corresponding IPv4
+    // address, so the same loopback / RFC1918 / link-local rules MUST apply.
+    // Two normalized shapes can come out of Node's URL():
+    //   1. dotted-quad: `::ffff:127.0.0.1`            (rare, some Node versions)
+    //   2. hex pair:    `::ffff:7f00:1`               (Node default — folds the v4 octets)
+    // Without this re-extraction, an attacker crafts `[::ffff:127.0.0.1]`
+    // or `[::ffff:169.254.169.254]` and bypasses the IPv4 checks below
+    // (which only match dotted-quad).
+    let host = stripped;
+    const mappedDotted = stripped.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    const mappedHex = stripped.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (mappedDotted) {
+        host = mappedDotted[1];
+    }
+    else if (mappedHex) {
+        const hi = parseInt(mappedHex[1], 16);
+        const lo = parseInt(mappedHex[2], 16);
+        host = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+    }
+    if (host === 'localhost' || host.endsWith('.localhost')) {
+        throw new Error(`Peer URL points at localhost (${host}) — refusing (SSRF guard)`);
+    }
+    // IPv4 literals
+    const ipv4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (ipv4) {
+        const [, a, b] = ipv4.map(Number);
+        if (a === 127) {
+            throw new Error(`Peer URL points at loopback IP (${host}) — refusing (SSRF guard)`);
+        }
+        if (a === 169 && b === 254) {
+            throw new Error(`Peer URL points at link-local / cloud-metadata IP (${host}) — refusing (SSRF guard)`);
+        }
+        if (a === 10) {
+            throw new Error(`Peer URL points at RFC1918 10.x.x.x (${host}) — refusing (SSRF guard)`);
+        }
+        if (a === 192 && b === 168) {
+            throw new Error(`Peer URL points at RFC1918 192.168.x.x (${host}) — refusing (SSRF guard)`);
+        }
+        if (a === 172 && b >= 16 && b <= 31) {
+            throw new Error(`Peer URL points at RFC1918 172.16-31.x (${host}) — refusing (SSRF guard)`);
+        }
+    }
+    // IPv6 literals — URL() wraps with brackets; the hostname getter strips them.
+    if (host === '::1') {
+        throw new Error(`Peer URL points at IPv6 loopback (${host}) — refusing (SSRF guard)`);
+    }
+    if (host.startsWith('fe80:') || host.startsWith('fe80::')) {
+        throw new Error(`Peer URL points at IPv6 link-local (${host}) — refusing (SSRF guard)`);
+    }
+    // IPv6 ULA fc00::/7 → high byte starts with 0xfc or 0xfd.
+    if (host.startsWith('fc') || host.startsWith('fd')) {
+        // Narrow to the fc00::/7 pattern: fc?? or fd?? as the first group.
+        if (/^(fc|fd)[0-9a-f]{0,2}:/.test(host)) {
+            throw new Error(`Peer URL points at IPv6 ULA (${host}) — refusing (SSRF guard)`);
+        }
+    }
+}
+exports.assertSafePeerUrl = assertSafePeerUrl;
+function isChannelPayload(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const p = x;
+    if (p.type !== 'agirails.quote.v1' && p.type !== 'agirails.counteroffer.v1')
+        return false;
+    if (!p.message || typeof p.message !== 'object')
+        return false;
+    const msg = p.message;
+    if (typeof msg.chainId !== 'number')
+        return false;
+    if (typeof msg.txId !== 'string')
+        return false;
+    if (typeof msg.nonce !== 'number')
+        return false;
+    if (typeof msg.expiresAt !== 'number')
+        return false;
+    if (typeof msg.signature !== 'string')
+        return false;
+    return true;
+}
+//# sourceMappingURL=QuoteChannel.js.map

package/dist/transport/QuoteChannel.js.map

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

package/dist/types/adapter.d.ts

@@ -55,8 +55,8 @@ export declare const AdapterMetadataSchema: z.ZodObject<{
     settlementMode: z.ZodEnum<["explicit", "timed", "atomic"]>;
     priority: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
-    id: string;
     name: string;
+    id: string;
     usesEscrow: boolean;
     supportsDisputes: boolean;
     requiresIdentity: boolean;
@@ -64,8 +64,8 @@ export declare const AdapterMetadataSchema: z.ZodObject<{
     priority: number;
     supportedIdentityTypes?: string[] | undefined;
 }, {
-    id: string;
     name: string;
+    id: string;
     usesEscrow: boolean;
     supportsDisputes: boolean;
     requiresIdentity: boolean;
@@ -102,11 +102,11 @@ export declare const PaymentIdentitySchema: z.ZodObject<{
     type: z.ZodEnum<["erc8004", "did", "ens", "address"]>;
     value: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    type: "address" | "erc8004" | "did" | "ens";
     value: string;
+    type: "did" | "address" | "erc8004" | "ens";
 }, {
-    type: "address" | "erc8004" | "did" | "ens";
     value: string;
+    type: "did" | "address" | "erc8004" | "ens";
 }>;
 /**
  * Zod schema for PaymentMetadata runtime validation.
@@ -119,11 +119,11 @@ export declare const PaymentMetadataSchema: z.ZodObject<{
         type: z.ZodEnum<["erc8004", "did", "ens", "address"]>;
         value: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        type: "address" | "erc8004" | "did" | "ens";
         value: string;
+        type: "did" | "address" | "erc8004" | "ens";
     }, {
-        type: "address" | "erc8004" | "did" | "ens";
         value: string;
+        type: "did" | "address" | "erc8004" | "ens";
     }>>;
     paymentMethod: z.ZodOptional<z.ZodEnum<["x402", "actp", "auto"]>>;
 }, "strip", z.ZodTypeAny, {
@@ -131,8 +131,8 @@ export declare const PaymentMetadataSchema: z.ZodObject<{
     requiresEscrow?: boolean | undefined;
     requiresDispute?: boolean | undefined;
     identity?: {
-        type: "address" | "erc8004" | "did" | "ens";
         value: string;
+        type: "did" | "address" | "erc8004" | "ens";
     } | undefined;
     paymentMethod?: "x402" | "actp" | "auto" | undefined;
 }, {
@@ -140,8 +140,8 @@ export declare const PaymentMetadataSchema: z.ZodObject<{
     requiresEscrow?: boolean | undefined;
     requiresDispute?: boolean | undefined;
     identity?: {
-        type: "address" | "erc8004" | "did" | "ens";
         value: string;
+        type: "did" | "address" | "erc8004" | "ens";
     } | undefined;
     paymentMethod?: "x402" | "actp" | "auto" | undefined;
 }>;
@@ -151,8 +151,15 @@ export declare const PaymentMetadataSchema: z.ZodObject<{
 export interface UnifiedPayParams {
     /** Recipient - address, HTTP endpoint, or ERC-8004 agent ID */
     to: string;
-    /** Amount in human-readable format */
-    amount: string | number;
+    /**
+     * Amount in human-readable format.
+     *
+     * - REQUIRED for ACTP adapters (basic, standard) — client sets the price
+     * - OPTIONAL for x402 URL targets — amount comes from the server's
+     *   payment-required response; this field is ignored. The x402 adapter
+     *   enforces its own per-tx safety cap via `X402AdapterConfig.maxAmountPerTx`.
+     */
+    amount?: string | number;
     /** Deadline (relative like '+24h' or unix timestamp) */
     deadline?: string | number;
     /** Dispute window in seconds (min 3600, max 30 days) */
@@ -167,13 +174,22 @@ export interface UnifiedPayParams {
      * Used for reputation reporting after settlement.
      */
     erc8004AgentId?: string;
+    /**
+     * HTTP method for x402 paid requests. Ignored by ACTP adapters.
+     * Default: 'GET'.
+     */
+    httpMethod?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** HTTP body for x402 paid requests (POST/PUT/PATCH). Ignored by ACTP adapters. */
+    httpBody?: string | Uint8Array;
+    /** Extra HTTP headers for x402 paid requests. Ignored by ACTP adapters. */
+    httpHeaders?: Record<string, string>;
 }
 /**
  * Zod schema for UnifiedPayParams with strict validation.
  */
 export declare const UnifiedPayParamsSchema: z.ZodObject<{
     to: z.ZodString;
-    amount: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    amount: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
     deadline: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
     disputeWindow: z.ZodOptional<z.ZodNumber>;
     description: z.ZodOptional<z.ZodString>;
@@ -185,11 +201,11 @@ export declare const UnifiedPayParamsSchema: z.ZodObject<{
             type: z.ZodEnum<["erc8004", "did", "ens", "address"]>;
             value: z.ZodString;
         }, "strip", z.ZodTypeAny, {
-            type: "address" | "erc8004" | "did" | "ens";
             value: string;
+            type: "did" | "address" | "erc8004" | "ens";
         }, {
-            type: "address" | "erc8004" | "did" | "ens";
             value: string;
+            type: "did" | "address" | "erc8004" | "ens";
         }>>;
         paymentMethod: z.ZodOptional<z.ZodEnum<["x402", "actp", "auto"]>>;
     }, "strip", z.ZodTypeAny, {
@@ -197,8 +213,8 @@ export declare const UnifiedPayParamsSchema: z.ZodObject<{
         requiresEscrow?: boolean | undefined;
         requiresDispute?: boolean | undefined;
         identity?: {
-            type: "address" | "erc8004" | "did" | "ens";
             value: string;
+            type: "did" | "address" | "erc8004" | "ens";
         } | undefined;
         paymentMethod?: "x402" | "actp" | "auto" | undefined;
     }, {
@@ -206,15 +222,18 @@ export declare const UnifiedPayParamsSchema: z.ZodObject<{
         requiresEscrow?: boolean | undefined;
         requiresDispute?: boolean | undefined;
         identity?: {
-            type: "address" | "erc8004" | "did" | "ens";
             value: string;
+            type: "did" | "address" | "erc8004" | "ens";
         } | undefined;
         paymentMethod?: "x402" | "actp" | "auto" | undefined;
     }>>;
     erc8004AgentId: z.ZodOptional<z.ZodString>;
+    httpMethod: z.ZodOptional<z.ZodEnum<["GET", "POST", "PUT", "PATCH", "DELETE"]>>;
+    httpBody: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodType<Uint8Array, z.ZodTypeDef, Uint8Array>]>>;
+    httpHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
-    amount: string | number;
     to: string;
+    amount?: string | number | undefined;
     deadline?: string | number | undefined;
     disputeWindow?: number | undefined;
     description?: string | undefined;
@@ -223,15 +242,18 @@ export declare const UnifiedPayParamsSchema: z.ZodObject<{
         requiresEscrow?: boolean | undefined;
         requiresDispute?: boolean | undefined;
         identity?: {
-            type: "address" | "erc8004" | "did" | "ens";
             value: string;
+            type: "did" | "address" | "erc8004" | "ens";
         } | undefined;
         paymentMethod?: "x402" | "actp" | "auto" | undefined;
     } | undefined;
     erc8004AgentId?: string | undefined;
+    httpMethod?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | undefined;
+    httpBody?: string | Uint8Array | undefined;
+    httpHeaders?: Record<string, string> | undefined;
 }, {
-    amount: string | number;
     to: string;
+    amount?: string | number | undefined;
     deadline?: string | number | undefined;
     disputeWindow?: number | undefined;
     description?: string | undefined;
@@ -240,12 +262,15 @@ export declare const UnifiedPayParamsSchema: z.ZodObject<{
         requiresEscrow?: boolean | undefined;
         requiresDispute?: boolean | undefined;
         identity?: {
-            type: "address" | "erc8004" | "did" | "ens";
             value: string;
+            type: "did" | "address" | "erc8004" | "ens";
         } | undefined;
         paymentMethod?: "x402" | "actp" | "auto" | undefined;
     } | undefined;
     erc8004AgentId?: string | undefined;
+    httpMethod?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | undefined;
+    httpBody?: string | Uint8Array | undefined;
+    httpHeaders?: Record<string, string> | undefined;
 }>;
 /**
  * Transaction state after payment initiation.
@@ -257,11 +282,13 @@ export type InitialTransactionState = 'COMMITTED' | 'IN_PROGRESS';
 /**
  * Unified payment result returned by all adapters.
  *
- * NOTE: success=true means payment INITIATED, not settled.
- * Caller must call releaseEscrow() after delivery verification.
+ * For escrow adapters (basic/standard), success=true means payment initiated
+ * and caller must later call releaseEscrow() after delivery verification.
+ * For atomic adapters (x402), success=true means settlement is final and
+ * releaseRequired=false.
  */
 export interface UnifiedPayResult {
-    /** ACTP transaction ID */
+    /** Transaction identifier (ACTP txId or x402 settlement transaction hash) */
     txId: string;
     /** Escrow ID (for release) - null for non-escrow adapters */
     escrowId: string | null;
@@ -296,8 +323,11 @@ export interface UnifiedPayResult {
      */
     erc8004AgentId?: string;
     /**
-     * Fee breakdown for x402 payments routed through X402Relay.
-     * Present only when relay is configured and payment used the relay path.
+     * @deprecated Legacy from the pre-v2 x402 flow routed through the
+     * on-chain X402Relay fee-splitting contract. The current X402Adapter
+     * (SDK 3.3.0+) pays seller directly with zero AGIRAILS fee, so this
+     * field is never populated on the x402 path. Retained for API
+     * back-compat; removal scheduled for the next breaking SDK major.
      */
     feeBreakdown?: X402FeeBreakdown;
 }
@@ -339,18 +369,18 @@ export declare const UnifiedPayResultSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     txId: string;
-    requester: string;
-    provider: string;
+    escrowId: string | null;
     amount: string;
+    success: boolean;
     deadline: string;
-    escrowId: string | null;
+    provider: string;
     adapter: string;
     state: "COMMITTED" | "IN_PROGRESS";
-    success: boolean;
     releaseRequired: boolean;
-    response?: any;
+    requester: string;
     error?: string | undefined;
     erc8004AgentId?: string | undefined;
+    response?: any;
     feeBreakdown?: {
         grossAmount: string;
         providerNet: string;
@@ -360,18 +390,18 @@ export declare const UnifiedPayResultSchema: z.ZodObject<{
     } | undefined;
 }, {
     txId: string;
-    requester: string;
-    provider: string;
+    escrowId: string | null;
     amount: string;
+    success: boolean;
     deadline: string;
-    escrowId: string | null;
+    provider: string;
     adapter: string;
     state: "COMMITTED" | "IN_PROGRESS";
-    success: boolean;
     releaseRequired: boolean;
-    response?: any;
+    requester: string;
     error?: string | undefined;
     erc8004AgentId?: string | undefined;
+    response?: any;
     feeBreakdown?: {
         grossAmount: string;
         providerNet: string;

package/dist/types/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/types/adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/types/adapter.ts"],"names":[],"mappings":"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"}