@oobe-protocol-labs/synapse-sap-sdk 0.13.0 → 0.15.0

package/dist/esm/utils/rpc-strategy.d.ts

@@ -0,0 +1,172 @@
+/**
+ * @module utils/rpc-strategy
+ * @description Dual-connection RPC strategy and idempotent ATA creation.
+ *
+ * Solves two interoperability problems:
+ *
+ * 1. **WebSocket 400 loop**: Some authenticated RPCs reject WebSocket
+ *    connections for SPL token operations. This module exposes a
+ *    dual-connection strategy: primary RPC for SAP program calls,
+ *    fallback public RPC for token operations.
+ *
+ * 2. **Idempotent ATA creation**: Wraps `getOrCreateAssociatedTokenAccount`
+ *    with retries so "account already exists" doesn't surface as a
+ *    hard error.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+import { Connection, type Commitment, PublicKey, type TransactionSignature } from "@solana/web3.js";
+/**
+ * @interface RpcConfig
+ * @description Configuration for dual-connection RPC strategy.
+ * @category Utils
+ * @since v0.6.0
+ */
+export interface RpcConfig {
+    /** Primary RPC URL (for SAP program calls). */
+    readonly primaryUrl: string;
+    /** Fallback RPC URL (for SPL token ops, public RPCs). */
+    readonly fallbackUrl?: string;
+    /** Commitment level. */
+    readonly commitment?: Commitment;
+}
+/**
+ * @interface DualConnection
+ * @description Dual RPC connections: primary for SAP, fallback for tokens.
+ * @category Utils
+ * @since v0.6.0
+ */
+export interface DualConnection {
+    /** Primary connection for SAP program calls. */
+    readonly primary: Connection;
+    /** Fallback connection for SPL token operations. */
+    readonly fallback: Connection;
+}
+/**
+ * @name getRpcUrl
+ * @description Get the primary RPC URL from environment or config.
+ *
+ * Resolution order:
+ *   1. Explicit `config.primaryUrl`
+ *   2. `SOLANA_RPC_URL` env var
+ *   3. Cluster-appropriate public RPC
+ *
+ * @param config - Optional RPC configuration.
+ * @param cluster - Cluster hint (defaults to "mainnet-beta").
+ * @returns The resolved primary RPC URL.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export declare function getRpcUrl(config?: Partial<RpcConfig>, cluster?: string): string;
+/**
+ * @name getFallbackRpcUrl
+ * @description Get the fallback RPC URL for SPL token operations.
+ *
+ * This avoids the WebSocket-400 loop when the primary RPC is
+ * an authenticated endpoint that rejects token-related WebSocket
+ * subscriptions.
+ *
+ * @param config - Optional RPC configuration.
+ * @param cluster - Cluster hint (defaults to "mainnet-beta").
+ * @returns The resolved fallback RPC URL.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export declare function getFallbackRpcUrl(config?: Partial<RpcConfig>, cluster?: string): string;
+/**
+ * @name createDualConnection
+ * @description Create a dual-connection pair: primary for SAP program calls,
+ * fallback for SPL token operations.
+ *
+ * @param config - RPC configuration.
+ * @param cluster - Cluster hint.
+ * @returns A {@link DualConnection} with both connections.
+ *
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * const { primary, fallback } = createDualConnection({
+ *   primaryUrl: "https://my-rpc.example.com",
+ * }, "mainnet-beta");
+ *
+ * // Use primary for SAP calls
+ * const provider = new AnchorProvider(primary, wallet, {});
+ *
+ * // Use fallback for SPL token account creation
+ * const ata = await getOrCreateATA(fallback, mint, owner);
+ * ```
+ */
+export declare function createDualConnection(config: Partial<RpcConfig>, cluster?: string): DualConnection;
+/**
+ * @interface AtaResult
+ * @description Result of idempotent ATA creation attempt.
+ * @category Utils
+ * @since v0.6.0
+ */
+export interface AtaResult {
+    /** The ATA public key (exists or newly created). */
+    readonly address: PublicKey;
+    /** Whether the ATA already existed. */
+    readonly existed: boolean;
+    /** Transaction signature (only if newly created). */
+    readonly txSignature?: TransactionSignature;
+}
+/**
+ * @name findATA
+ * @description Derive the Associated Token Account address.
+ * Uses the standard ATA PDA derivation without importing the full
+ * `@solana/spl-token` package.
+ *
+ * @param owner - The token account owner.
+ * @param mint - The token mint.
+ * @param programId - Token program ID (defaults to TOKEN_PROGRAM_ID).
+ * @returns The derived ATA public key.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export declare function findATA(owner: PublicKey, mint: PublicKey, programId?: PublicKey): PublicKey;
+/**
+ * @name classifyAnchorError
+ * @description Convert an Anchor error code into a friendly, actionable message.
+ *
+ * @param errorCode - The numeric Anchor error code.
+ * @returns A human-readable error message, or a generic message for unknown codes.
+ *
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.escrow.create(...);
+ * } catch (err) {
+ *   const code = extractAnchorErrorCode(err);
+ *   if (code !== null) {
+ *     console.error(classifyAnchorError(code));
+ *   }
+ * }
+ * ```
+ */
+export declare function classifyAnchorError(errorCode: number): string;
+/**
+ * @name extractAnchorErrorCode
+ * @description Attempt to extract an Anchor error code from an Error object.
+ *
+ * Anchor errors typically have the structure `{ code: number, msg: string }`.
+ * This function handles both the direct `error.code` pattern and the
+ * `error.error.errorCode.number` nested pattern.
+ *
+ * @param err - The caught error object.
+ * @returns The numeric error code, or `null` if not an Anchor error.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export declare function extractAnchorErrorCode(err: unknown): number | null;
+//# sourceMappingURL=rpc-strategy.d.ts.map

package/dist/esm/utils/rpc-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-strategy.d.ts","sourceRoot":"","sources":["../../../src/utils/rpc-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,UAAU,EACV,KAAK,UAAU,EACf,SAAS,EACT,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAC;AAMzB;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,wBAAwB;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;CAC/B;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CACvB,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EAC3B,OAAO,GAAE,MAAuB,GAC/B,MAAM,CASR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EAC3B,OAAO,GAAE,MAAuB,GAC/B,MAAM,CAWR;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,EAC1B,OAAO,GAAE,MAAuB,GAC/B,cAAc,CAShB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,oBAAoB,CAAC;CAC7C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,SAAS,EACf,SAAS,GAAE,SAAwE,GAClF,SAAS,CAUX;AAiCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAyBlE"}

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

@@ -0,0 +1,351 @@
+/**
+ * @module utils/schemas
+ * @description Zod schemas for runtime validation of environment variables,
+ * tool arguments, agent manifests, and x402 payment parameters.
+ *
+ * These schemas enforce correctness at the boundary: CLI scripts refuse
+ * to run if required fields are missing or mis-typed, and SDK methods
+ * validate inputs before hitting the chain.
+ *
+ * Zod is a peer dependency — these schemas are tree-shaken if not imported.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+/**
+ * @name createEnvSchema
+ * @description Create a Zod schema for SAP SDK environment variables.
+ * Validates that all required env vars are present and correctly typed.
+ *
+ * @returns A Zod schema object for env validation.
+ *
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * import { createEnvSchema } from "@synapse-sap/sdk";
+ *
+ * const schema = createEnvSchema();
+ * const env = schema.parse(process.env);
+ * // env.SOLANA_CLUSTER is typed as "mainnet-beta" | "devnet" | "localnet"
+ * ```
+ */
+export declare function createEnvSchema(): import("zod").ZodObject<{
+    SOLANA_CLUSTER: import("zod").ZodDefault<import("zod").ZodEnum<{
+        "mainnet-beta": "mainnet-beta";
+        devnet: "devnet";
+        localnet: "localnet";
+    }>>;
+    SOLANA_RPC_URL: import("zod").ZodOptional<import("zod").ZodString>;
+    SOLANA_FALLBACK_RPC_URL: import("zod").ZodOptional<import("zod").ZodString>;
+    SOLANA_WS_URL: import("zod").ZodOptional<import("zod").ZodString>;
+    WALLET_KEYPAIR_PATH: import("zod").ZodOptional<import("zod").ZodString>;
+    WALLET_PRIVATE_KEY: import("zod").ZodOptional<import("zod").ZodString>;
+    SAP_PROGRAM_ID: import("zod").ZodOptional<import("zod").ZodString>;
+    DATABASE_URL: import("zod").ZodOptional<import("zod").ZodString>;
+    LOG_LEVEL: import("zod").ZodDefault<import("zod").ZodEnum<{
+        error: "error";
+        info: "info";
+        debug: "debug";
+        warn: "warn";
+    }>>;
+    X402_ENDPOINT: import("zod").ZodOptional<import("zod").ZodString>;
+    AGENT_URI: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+/**
+ * @name createEndpointDescriptorSchema
+ * @description Zod schema for {@link EndpointDescriptor}.
+ * @returns A Zod schema for endpoint descriptor validation.
+ * @category Utils
+ * @since v0.6.0
+ */
+export declare function createEndpointDescriptorSchema(): import("zod").ZodObject<{
+    url: import("zod").ZodString;
+    method: import("zod").ZodDefault<import("zod").ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PUT: "PUT";
+        DELETE: "DELETE";
+    }>>;
+    contentType: import("zod").ZodDefault<import("zod").ZodString>;
+    requiresAuth: import("zod").ZodDefault<import("zod").ZodBoolean>;
+    authType: import("zod").ZodOptional<import("zod").ZodEnum<{
+        bearer: "bearer";
+        "api-key": "api-key";
+        x402: "x402";
+        none: "none";
+    }>>;
+    requiresCSRF: import("zod").ZodDefault<import("zod").ZodBoolean>;
+    requiresCookies: import("zod").ZodDefault<import("zod").ZodBoolean>;
+    corsOrigins: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+    requiredHeaders: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
+}, import("zod/v4/core").$strip>;
+/**
+ * @name createHealthCheckSchema
+ * @description Zod schema for {@link HealthCheckDescriptor}.
+ * @returns A Zod schema for health check validation.
+ * @category Utils
+ * @since v0.6.0
+ */
+export declare function createHealthCheckSchema(): import("zod").ZodObject<{
+    url: import("zod").ZodString;
+    expectedStatus: import("zod").ZodDefault<import("zod").ZodNumber>;
+    timeoutMs: import("zod").ZodDefault<import("zod").ZodNumber>;
+    method: import("zod").ZodDefault<import("zod").ZodEnum<{
+        GET: "GET";
+        HEAD: "HEAD";
+    }>>;
+}, import("zod/v4/core").$strip>;
+/**
+ * @name createToolManifestEntrySchema
+ * @description Zod schema for a single tool in an agent manifest.
+ * @returns A Zod schema for tool manifest entry validation.
+ * @category Utils
+ * @since v0.6.0
+ */
+export declare function createToolManifestEntrySchema(): import("zod").ZodObject<{
+    name: import("zod").ZodString;
+    description: import("zod").ZodString;
+    protocol: import("zod").ZodString;
+    category: import("zod").ZodString;
+    inputSchema: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>;
+    outputSchema: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>;
+    httpMethod: import("zod").ZodDefault<import("zod").ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PUT: "PUT";
+        DELETE: "DELETE";
+        COMPOUND: "COMPOUND";
+    }>>;
+    paymentMode: import("zod").ZodDefault<import("zod").ZodEnum<{
+        subscription: "subscription";
+        x402: "x402";
+        free: "free";
+        prepaid: "prepaid";
+    }>>;
+    pricePerCall: import("zod").ZodDefault<import("zod").ZodNumber>;
+    requiredArgs: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
+    prerequisites: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
+    endpointOverride: import("zod").ZodOptional<import("zod").ZodObject<{
+        url: import("zod").ZodString;
+        method: import("zod").ZodDefault<import("zod").ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PUT: "PUT";
+            DELETE: "DELETE";
+        }>>;
+        contentType: import("zod").ZodDefault<import("zod").ZodString>;
+        requiresAuth: import("zod").ZodDefault<import("zod").ZodBoolean>;
+        authType: import("zod").ZodOptional<import("zod").ZodEnum<{
+            bearer: "bearer";
+            "api-key": "api-key";
+            x402: "x402";
+            none: "none";
+        }>>;
+        requiresCSRF: import("zod").ZodDefault<import("zod").ZodBoolean>;
+        requiresCookies: import("zod").ZodDefault<import("zod").ZodBoolean>;
+        corsOrigins: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        requiredHeaders: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>;
+/**
+ * @name createAgentManifestSchema
+ * @description Zod schema for a complete agent manifest.
+ * @returns A Zod schema for manifest validation.
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * import { createAgentManifestSchema } from "@synapse-sap/sdk";
+ *
+ * const schema = createAgentManifestSchema();
+ * const manifest = schema.parse(JSON.parse(fs.readFileSync("manifest.json", "utf-8")));
+ * ```
+ */
+export declare function createAgentManifestSchema(): import("zod").ZodObject<{
+    version: import("zod").ZodLiteral<"1.0.0">;
+    wallet: import("zod").ZodString;
+    name: import("zod").ZodString;
+    description: import("zod").ZodString;
+    endpoint: import("zod").ZodObject<{
+        url: import("zod").ZodString;
+        method: import("zod").ZodDefault<import("zod").ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PUT: "PUT";
+            DELETE: "DELETE";
+        }>>;
+        contentType: import("zod").ZodDefault<import("zod").ZodString>;
+        requiresAuth: import("zod").ZodDefault<import("zod").ZodBoolean>;
+        authType: import("zod").ZodOptional<import("zod").ZodEnum<{
+            bearer: "bearer";
+            "api-key": "api-key";
+            x402: "x402";
+            none: "none";
+        }>>;
+        requiresCSRF: import("zod").ZodDefault<import("zod").ZodBoolean>;
+        requiresCookies: import("zod").ZodDefault<import("zod").ZodBoolean>;
+        corsOrigins: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        requiredHeaders: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
+    }, import("zod/v4/core").$strip>;
+    healthCheck: import("zod").ZodOptional<import("zod").ZodObject<{
+        url: import("zod").ZodString;
+        expectedStatus: import("zod").ZodDefault<import("zod").ZodNumber>;
+        timeoutMs: import("zod").ZodDefault<import("zod").ZodNumber>;
+        method: import("zod").ZodDefault<import("zod").ZodEnum<{
+            GET: "GET";
+            HEAD: "HEAD";
+        }>>;
+    }, import("zod/v4/core").$strip>>;
+    tools: import("zod").ZodArray<import("zod").ZodObject<{
+        name: import("zod").ZodString;
+        description: import("zod").ZodString;
+        protocol: import("zod").ZodString;
+        category: import("zod").ZodString;
+        inputSchema: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>;
+        outputSchema: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>;
+        httpMethod: import("zod").ZodDefault<import("zod").ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PUT: "PUT";
+            DELETE: "DELETE";
+            COMPOUND: "COMPOUND";
+        }>>;
+        paymentMode: import("zod").ZodDefault<import("zod").ZodEnum<{
+            subscription: "subscription";
+            x402: "x402";
+            free: "free";
+            prepaid: "prepaid";
+        }>>;
+        pricePerCall: import("zod").ZodDefault<import("zod").ZodNumber>;
+        requiredArgs: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
+        prerequisites: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
+        endpointOverride: import("zod").ZodOptional<import("zod").ZodObject<{
+            url: import("zod").ZodString;
+            method: import("zod").ZodDefault<import("zod").ZodEnum<{
+                GET: "GET";
+                POST: "POST";
+                PUT: "PUT";
+                DELETE: "DELETE";
+            }>>;
+            contentType: import("zod").ZodDefault<import("zod").ZodString>;
+            requiresAuth: import("zod").ZodDefault<import("zod").ZodBoolean>;
+            authType: import("zod").ZodOptional<import("zod").ZodEnum<{
+                bearer: "bearer";
+                "api-key": "api-key";
+                x402: "x402";
+                none: "none";
+            }>>;
+            requiresCSRF: import("zod").ZodDefault<import("zod").ZodBoolean>;
+            requiresCookies: import("zod").ZodDefault<import("zod").ZodBoolean>;
+            corsOrigins: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+            requiredHeaders: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>>;
+    supportedNetworks: import("zod").ZodArray<import("zod").ZodString>;
+    generatedAt: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
+/**
+ * @name createPreparePaymentSchema
+ * @description Zod schema for x402 payment preparation parameters.
+ * @returns A Zod schema for payment option validation.
+ * @category Utils
+ * @since v0.6.0
+ */
+export declare function createPreparePaymentSchema(): import("zod").ZodObject<{
+    pricePerCall: import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodBigInt]>;
+    maxCalls: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodBigInt]>>;
+    deposit: import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodBigInt]>;
+    expiresAt: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodBigInt]>>;
+    volumeCurve: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+        afterCalls: import("zod").ZodNumber;
+        pricePerCall: import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodBigInt]>;
+    }, import("zod/v4/core").$strip>>>;
+    tokenMint: import("zod").ZodOptional<import("zod").ZodString>;
+    tokenDecimals: import("zod").ZodDefault<import("zod").ZodNumber>;
+    networkIdentifier: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+/**
+ * @name createRegisterAgentSchema
+ * @description Zod schema for agent registration arguments.
+ * @returns A Zod schema for registration validation.
+ * @category Utils
+ * @since v0.6.0
+ */
+export declare function createRegisterAgentSchema(): import("zod").ZodObject<{
+    name: import("zod").ZodString;
+    description: import("zod").ZodString;
+    agentId: import("zod").ZodNullable<import("zod").ZodOptional<import("zod").ZodString>>;
+    agentUri: import("zod").ZodNullable<import("zod").ZodOptional<import("zod").ZodString>>;
+    x402Endpoint: import("zod").ZodNullable<import("zod").ZodOptional<import("zod").ZodString>>;
+    capabilities: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        description: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+        protocolId: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+        version: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+    }, import("zod/v4/core").$strip>>>;
+    protocols: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
+    pricing: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+        tierId: import("zod").ZodString;
+        pricePerCall: import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString]>;
+        rateLimit: import("zod").ZodNumber;
+        tokenType: import("zod").ZodDefault<import("zod").ZodEnum<{
+            sol: "sol";
+            usdc: "usdc";
+            spl: "spl";
+        }>>;
+        settlementMode: import("zod").ZodDefault<import("zod").ZodEnum<{
+            escrow: "escrow";
+            x402: "x402";
+            instant: "instant";
+            batched: "batched";
+        }>>;
+    }, import("zod/v4/core").$strip>>>;
+}, import("zod/v4/core").$strip>;
+/**
+ * @name createCallArgsSchema
+ * @description Zod schema for `npm run call` script arguments.
+ * Ensures all required fields are present before executing an x402 call.
+ *
+ * @returns A Zod schema for call argument validation.
+ * @category Utils
+ * @since v0.6.0
+ */
+export declare function createCallArgsSchema(): import("zod").ZodObject<{
+    agentWallet: import("zod").ZodString;
+    tool: import("zod").ZodString;
+    args: import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
+    endpoint: import("zod").ZodOptional<import("zod").ZodString>;
+    network: import("zod").ZodOptional<import("zod").ZodString>;
+    maxRetries: import("zod").ZodDefault<import("zod").ZodNumber>;
+    timeoutMs: import("zod").ZodDefault<import("zod").ZodNumber>;
+}, import("zod/v4/core").$strip>;
+/**
+ * @name validateOrThrow
+ * @description Validate a value against a Zod schema, throwing a SapValidationError
+ * with a friendly message if validation fails.
+ *
+ * @param schema - A Zod schema.
+ * @param value - The value to validate.
+ * @param label - A label for error messages (e.g. "environment", "call args").
+ * @returns The parsed and typed value.
+ * @throws {Error} With formatted validation errors.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export declare function validateOrThrow<T>(schema: {
+    parse: (v: unknown) => T;
+    safeParse: (v: unknown) => {
+        success: boolean;
+        error?: {
+            issues: Array<{
+                path: Array<string | number>;
+                message: string;
+            }>;
+        };
+    };
+}, value: unknown, label: string): T;
+//# sourceMappingURL=schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/utils/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA2BH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe;;;;;;;;;;;;;;;;;;;;;iCAsD9B;AAMD;;;;;;GAMG;AACH,wBAAgB,8BAA8B;;;;;;;;;;;;;;;;;;;;iCAc7C;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB;;;;;;;;iCAStC;AAMD;;;;;;GAMG;AACH,wBAAgB,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAiB5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAcxC;AAMD;;;;;;GAMG;AACH,wBAAgB,0BAA0B;;;;;;;;;;;;iCAoBzC;AAMD;;;;;;GAMG;AACH,wBAAgB,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAkCxC;AAMD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB;;;;;;;;iCAYnC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,MAAM,EAAE;IAAE,KAAK,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC;IAAC,SAAS,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE;YAAE,MAAM,EAAE,KAAK,CAAC;gBAAE,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;gBAAC,OAAO,EAAE,MAAM,CAAA;aAAE,CAAC,CAAA;SAAE,CAAA;KAAE,CAAA;CAAE,EACnK,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ,CAAC,CAYH"}

package/{src/utils/serialization.ts → dist/esm/utils/serialization.d.ts}

@@ -18,10 +18,6 @@
  * // { authority: "GBL...", totalCalls: "42", ... }
  * ```
  */
-
-import { PublicKey } from "@solana/web3.js";
-import BN from "bn.js";
-
 /**
  * Recursively convert a single value for JSON serialization.
  *
@@ -46,21 +42,7 @@ import BN from "bn.js";
  * serializeValue(new BN(42)); // "42"
  * ```
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function serializeValue(value: unknown): any {
-  if (value === null || value === undefined) return null;
-  if (value instanceof PublicKey) return value.toBase58();
-  if (BN.isBN(value)) return value.toString();
-  if (value instanceof Uint8Array || Buffer.isBuffer(value))
-    return Buffer.from(value).toString("hex");
-  if (Array.isArray(value)) return value.map(serializeValue);
-  if (typeof value === "object") {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    return serializeAccount(value as Record<string, any>);
-  }
-  return value;
-}
-
+export declare function serializeValue(value: unknown): any;
 /**
  * Serialize an entire on-chain account object to a JSON-safe shape.
  *
@@ -83,16 +65,5 @@ export function serializeValue(value: unknown): any {
  * console.log(JSON.stringify(safe));
  * ```
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function serializeAccount(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  obj: Record<string, any>,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-): Record<string, any> {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const result: Record<string, any> = {};
-  for (const [key, value] of Object.entries(obj)) {
-    result[key] = serializeValue(value);
-  }
-  return result;
-}
+export declare function serializeAccount(obj: Record<string, any>): Record<string, any>;
+//# sourceMappingURL=serialization.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../../src/utils/serialization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,CAYlD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,wBAAgB,gBAAgB,CAE9B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAEvB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOrB"}

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

@@ -0,0 +1,66 @@
+import BN from "bn.js";
+import { PublicKey } from "@solana/web3.js";
+import { SettlementSecurity, VolumeCurvePoint, BillingInterval } from "../types";
+export interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+/** Validate agent creation parameters */
+export declare function validateAgentInput(params: {
+    name: string;
+    endpointUri: string;
+}): ValidationResult;
+/** Compute max_obligation for an escrow (must match on-chain logic) */
+export declare function computeEscrowMaxObligation(pricePerCall: BN, maxCalls: BN, initialDeposit: BN): BN;
+/** Validate escrow V2 creation parameters (mirrors create_escrow_v2 on-chain checks) */
+export declare function validateEscrowCreate(params: {
+    pricePerCall: BN;
+    basePrice: BN;
+    maxCalls: BN;
+    initialDeposit: BN;
+    expiresAt: BN;
+    settlementSecurity: SettlementSecurity;
+    coSigner: PublicKey | null;
+    arbiter: PublicKey | null;
+    disputeWindowSlots: number;
+    volumeCurve: VolumeCurvePoint[];
+    agentWallet: PublicKey;
+}): ValidationResult;
+/** Validate deposit parameters */
+export declare function validateEscrowDeposit(params: {
+    amount: BN;
+    escrowMaxObligation: BN;
+    escrowBalance: BN;
+    escrowPendingAmount: BN;
+}): ValidationResult;
+/** Validate settle_calls_v2 parameters (pre-computation) */
+export declare function validateEscrowSettle(params: {
+    callsToSettle: number;
+    escrowBalance: BN;
+    escrowPendingAmount: BN;
+    escrowTotalCallsSettled: BN;
+    escrowPendingCalls: BN;
+    escrowMaxCalls: BN;
+    pricePerCall: BN;
+    basePrice?: BN;
+    volumeCurve?: VolumeCurvePoint[];
+}): {
+    ok: boolean;
+    errors: string[];
+    amount: BN;
+};
+/** Client-side mirror of on-chain calculate_settle_amount (v0.13) */
+export declare function calculateSettleAmount(pricePerCall: BN, basePrice: BN, volumeCurve: VolumeCurvePoint[], calls: number): BN;
+/** Validate receipt proof submission (C4 bounds check) */
+export declare function validateReceiptProof(receiptHashes: Uint8Array[], merkleProofs: Uint8Array[][]): ValidationResult;
+/** Validate subscription parameters */
+export declare function validateSubscriptionCreate(params: {
+    billingInterval: BillingInterval;
+    pricePerInterval: BN;
+    durationIntervals: number;
+}): ValidationResult;
+/** Validate close_escrow_v2 can proceed (H8 check) */
+export declare function validateEscrowClose(pendingSettlementCount: number, balance: BN, pendingAmount: BN): ValidationResult;
+/** Validate agent close (stake + active_escrows) */
+export declare function validateAgentClose(stakedAmount: BN, activeEscrows: number, unstakeAvailableAt: BN): ValidationResult;
+//# sourceMappingURL=validate.d.ts.map

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

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