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

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

@@ -1,226 +0,0 @@
-/**
- * @module utils/endpoint-validator
- * @description Endpoint validation utilities for SAP agent discovery.
- *
- * Fetches advertised endpoints and verifies they respond with JSON,
- * proper CORS headers, and SAP-compatible behavior. Designed to
- * fail fast when an endpoint 404s, requires CSRF tokens, or
- * serves HTML instead of JSON.
- *
- * Used by:
- *   - CLI `discovery validate` command
- *   - SDK programmatic validation before x402 calls
- *   - Integration test harnesses
- *
- * @category Utils
- * @since v0.6.0
- */
-// ═══════════════════════════════════════════════════════════════════
-//  Core Validator
-// ═══════════════════════════════════════════════════════════════════
-/**
- * @name validateEndpoint
- * @description Validate a single endpoint URL for SAP compatibility.
- *
- * Performs the following checks:
- *   1. URL is reachable (no 4xx/5xx)
- *   2. Response Content-Type is JSON
- *   3. CORS headers are present (if checkCors enabled)
- *   4. No redirect to HTML login pages
- *   5. Measures response latency
- *
- * @param url - The endpoint URL to validate.
- * @param opts - Validation options.
- * @returns An {@link EndpointValidationResult} with detailed check results.
- *
- * @category Utils
- * @since v0.6.0
- *
- * @example
- * ```ts
- * const result = await validateEndpoint("https://api.example.com/x402");
- * if (!result.reachable) console.error(result.error);
- * ```
- */
-export async function validateEndpoint(url, opts = {}) {
-    const timeoutMs = opts.timeoutMs ?? 10_000;
-    const retries = opts.retries ?? 1;
-    const method = opts.method ?? "HEAD";
-    const warnings = [];
-    let lastError;
-    for (let attempt = 0; attempt <= retries; attempt++) {
-        try {
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), timeoutMs);
-            const start = Date.now();
-            const response = await fetch(url, {
-                method,
-                signal: controller.signal,
-                headers: {
-                    Accept: "application/json",
-                    ...(opts.headers ?? {}),
-                },
-                redirect: "follow",
-            });
-            clearTimeout(timer);
-            const latencyMs = Date.now() - start;
-            const contentType = response.headers.get("content-type") ?? "";
-            const isJson = contentType.includes("application/json") || contentType.includes("text/json");
-            const hasCors = !!response.headers.get("access-control-allow-origin");
-            // Check for HTML responses (login pages, CSRF gates)
-            if (contentType.includes("text/html")) {
-                warnings.push("Endpoint returns HTML — may require CSRF or browser session");
-            }
-            // Check for redirect chains
-            if (response.redirected) {
-                warnings.push(`Endpoint redirected to ${response.url}`);
-            }
-            // Check for common error statuses
-            if (response.status === 403) {
-                warnings.push("403 Forbidden — may require authentication or CSRF tokens");
-            }
-            if (response.status === 404) {
-                warnings.push("404 Not Found — endpoint URL may be incorrect");
-            }
-            if (response.status === 405) {
-                warnings.push(`405 Method Not Allowed — endpoint may not accept ${method}`);
-            }
-            // Determine SAP capability
-            const isSapCapable = isJson &&
-                response.status < 400 &&
-                !contentType.includes("text/html");
-            // CORS check if requested
-            if (opts.checkCors && !hasCors) {
-                warnings.push("No CORS headers — cross-origin requests will fail");
-            }
-            return {
-                url,
-                reachable: response.status < 500,
-                statusCode: response.status,
-                latencyMs,
-                isJson,
-                hasCors,
-                isSapCapable,
-                error: response.status >= 400
-                    ? `HTTP ${response.status}: ${response.statusText}`
-                    : undefined,
-                warnings,
-            };
-        }
-        catch (err) {
-            lastError =
-                err instanceof Error ? err.message : String(err);
-            if (attempt < retries)
-                continue;
-        }
-    }
-    return {
-        url,
-        reachable: false,
-        statusCode: 0,
-        latencyMs: 0,
-        isJson: false,
-        hasCors: false,
-        isSapCapable: false,
-        error: lastError ?? "Unknown error",
-        warnings,
-    };
-}
-/**
- * @name validateEndpointDescriptor
- * @description Validate an {@link EndpointDescriptor} with context-aware checks.
- *
- * Uses the descriptor's method, auth requirements, and other metadata to
- * perform a more targeted validation than raw URL checking.
- *
- * @param descriptor - The endpoint descriptor to validate.
- * @param opts - Additional options.
- * @returns An {@link EndpointValidationResult}.
- *
- * @category Utils
- * @since v0.6.0
- */
-export async function validateEndpointDescriptor(descriptor, opts = {}) {
-    const headers = {
-        ...(opts.headers ?? {}),
-        ...(descriptor.requiredHeaders ?? {}),
-    };
-    // Use the descriptor's method, falling back to HEAD for safety
-    const method = opts.method ?? (descriptor.method === "GET" ? "GET" : "HEAD");
-    const result = await validateEndpoint(descriptor.url, {
-        ...opts,
-        method,
-        headers,
-    });
-    // Add descriptor-specific warnings
-    const warnings = [...result.warnings];
-    if (descriptor.requiresCSRF) {
-        warnings.push("Endpoint declares requiresCSRF — automated calls may need token management");
-    }
-    if (descriptor.requiresCookies) {
-        warnings.push("Endpoint declares requiresCookies — stateless calls may fail");
-    }
-    if (descriptor.requiresAuth && !descriptor.authType) {
-        warnings.push("Endpoint requires auth but no authType specified");
-    }
-    return { ...result, warnings };
-}
-/**
- * @name validateHealthCheck
- * @description Validate an agent's health-check endpoint.
- *
- * @param health - The health-check descriptor.
- * @returns An {@link EndpointValidationResult}.
- *
- * @category Utils
- * @since v0.6.0
- */
-export async function validateHealthCheck(health) {
-    const result = await validateEndpoint(health.url, {
-        timeoutMs: health.timeoutMs,
-        method: health.method ?? "GET",
-    });
-    const warnings = [...result.warnings];
-    if (result.reachable && result.statusCode !== health.expectedStatus) {
-        warnings.push(`Expected status ${health.expectedStatus}, got ${result.statusCode}`);
-    }
-    return {
-        ...result,
-        isSapCapable: result.reachable && result.statusCode === health.expectedStatus,
-        warnings,
-    };
-}
-/**
- * @name validateAgentEndpoints
- * @description Validate all endpoints for an agent (primary + health + tool overrides).
- *
- * @param params - Object containing the endpoints to validate.
- * @param params.endpoint - Primary endpoint descriptor.
- * @param params.healthCheck - Optional health-check descriptor.
- * @param params.toolEndpoints - Optional array of tool-specific endpoint overrides.
- * @param opts - Validation options.
- * @returns A map of `label → EndpointValidationResult`.
- *
- * @category Utils
- * @since v0.6.0
- */
-export async function validateAgentEndpoints(params, opts = {}) {
-    const results = new Map();
-    // Validate primary endpoint
-    const primary = await validateEndpointDescriptor(params.endpoint, opts);
-    results.set("primary", primary);
-    // Validate health check
-    if (params.healthCheck) {
-        const health = await validateHealthCheck(params.healthCheck);
-        results.set("health", health);
-    }
-    // Validate tool-specific endpoints
-    if (params.toolEndpoints) {
-        for (const { name, endpoint } of params.toolEndpoints) {
-            const toolResult = await validateEndpointDescriptor(endpoint, opts);
-            results.set(`tool:${name}`, toolResult);
-        }
-    }
-    return results;
-}
-//# sourceMappingURL=endpoint-validator.js.map

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

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

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

@@ -1,212 +0,0 @@
-/**
- * @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

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

package/dist/esm/utils/hash.js

@@ -1,103 +0,0 @@
-/**
- * @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

@@ -1 +0,0 @@
-{"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"}