@oobe-protocol-labs/synapse-sap-sdk 0.4.2 → 0.6.0

package/dist/types/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/types/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/types/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";
+        debug: "debug";
+        info: "info";
+        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<{
+        x402: "x402";
+        free: "free";
+        prepaid: "prepaid";
+        subscription: "subscription";
+    }>>;
+    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<{
+            x402: "x402";
+            free: "free";
+            prepaid: "prepaid";
+            subscription: "subscription";
+        }>>;
+        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<{
+            x402: "x402";
+            instant: "instant";
+            escrow: "escrow";
+            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/types/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/synapse-sap-sdk",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "TypeScript SDK for the Synapse Agent Protocol (SAP v2) on Solana",
   "license": "MIT",
   "main": "dist/cjs/index.js",

package/src/constants/index.ts

@@ -42,6 +42,10 @@ export {
   TOOL_CATEGORY_VALUES,
   HTTP_METHOD_VALUES,
 } from "./limits";
+// ── Network Identifiers (x402) ───────────────────────────────
+export { SapNetwork } from "./network";
+export type { SapNetworkId } from "./network";
+
 // ── Mainnet Addresses ────────────────────────────────────────
 export {
   SAP_PROGRAM,

package/src/constants/network.ts

@@ -0,0 +1,89 @@
+/**
+ * @module constants/network
+ * @description Solana network identifiers for x402 payment headers.
+ *
+ * x402 providers validate the `X-Payment-Network` header against their
+ * own network identifier. Some providers (e.g. Coinbase, Phantom) accept
+ * the human-readable cluster name (`solana:mainnet-beta`), while others
+ * (e.g. Kamiyo, Helius x402) require the Solana genesis-hash form
+ * (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`).
+ *
+ * Use {@link SapNetwork} to select the correct format, or pass any
+ * custom string where needed.
+ *
+ * @category Constants
+ * @since v0.4.3
+ *
+ * @example
+ * ```ts
+ * import { SapNetwork } from "@synapse-sap/sdk";
+ *
+ * // Standard cluster name (default)
+ * const ctx = await x402.preparePayment(agentWallet, {
+ *   pricePerCall: 1000, deposit: 100_000,
+ *   networkIdentifier: SapNetwork.SOLANA_MAINNET,
+ * });
+ *
+ * // Genesis-hash form for providers that require it
+ * const ctx2 = await x402.preparePayment(agentWallet, {
+ *   pricePerCall: 1000, deposit: 100_000,
+ *   networkIdentifier: SapNetwork.SOLANA_MAINNET_GENESIS,
+ * });
+ * ```
+ */
+
+// ═══════════════════════════════════════════════════════════════════
+//  SAP Network Identifiers
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name SapNetwork
+ * @description Network identifier strings for x402 `X-Payment-Network` headers.
+ *
+ * Two mainnet forms exist because x402 providers disagree on the canonical
+ * identifier:
+ *
+ * | Constant                | Value                                        | Accepted by          |
+ * |-------------------------|----------------------------------------------|----------------------|
+ * | `SOLANA_MAINNET`        | `solana:mainnet-beta`                        | Coinbase, Phantom    |
+ * | `SOLANA_MAINNET_GENESIS`| `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`   | Kamiyo, Helius x402  |
+ * | `SOLANA_DEVNET`         | `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`   | Devnet providers     |
+ * | `SOLANA_DEVNET_NAMED`   | `solana:devnet`                              | Local / test flows   |
+ *
+ * If your provider requires a different format, pass a raw string instead.
+ *
+ * @category Constants
+ * @since v0.4.3
+ */
+export const SapNetwork = {
+  /**
+   * Mainnet-beta, human-readable cluster name.
+   * Default value used by the SDK prior to v0.4.3.
+   */
+  SOLANA_MAINNET: "solana:mainnet-beta",
+
+  /**
+   * Mainnet-beta, genesis-hash form (CAIP-2 compliant).
+   * Required by Kamiyo, Helius x402, and other providers that validate
+   * against the Solana genesis hash.
+   */
+  SOLANA_MAINNET_GENESIS: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+
+  /**
+   * Devnet, genesis-hash form (CAIP-2 compliant).
+   */
+  SOLANA_DEVNET: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+
+  /**
+   * Devnet, human-readable cluster name.
+   * Useful for local development and test validators.
+   */
+  SOLANA_DEVNET_NAMED: "solana:devnet",
+} as const;
+
+/**
+ * @name SapNetworkId
+ * @description Union type of all known {@link SapNetwork} values.
+ * Accept `SapNetworkId | string` where custom identifiers are allowed.
+ */
+export type SapNetworkId = (typeof SapNetwork)[keyof typeof SapNetwork];