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

package/src/utils/rpc-strategy.ts

@@ -1,322 +0,0 @@
-/**
- * @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";
-
-// ═══════════════════════════════════════════════════════════════════
-//  RPC Strategy Types
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @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;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Default Public RPCs
-// ═══════════════════════════════════════════════════════════════════
-
-/** Well-known public fallback RPCs by cluster. */
-const PUBLIC_RPCS: Record<string, string> = {
-  "mainnet-beta": "https://api.mainnet-beta.solana.com",
-  devnet: "https://api.devnet.solana.com",
-  localnet: "http://localhost:8899",
-};
-
-// ═══════════════════════════════════════════════════════════════════
-//  Public API
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @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 function getRpcUrl(
-  config?: Partial<RpcConfig>,
-  cluster: string = "mainnet-beta",
-): string {
-  if (config?.primaryUrl) return config.primaryUrl;
-
-  // Environment variable
-  const envUrl =
-    typeof process !== "undefined" ? process.env?.SOLANA_RPC_URL : undefined;
-  if (envUrl) return envUrl;
-
-  return PUBLIC_RPCS[cluster] ?? PUBLIC_RPCS["mainnet-beta"]!;
-}
-
-/**
- * @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 function getFallbackRpcUrl(
-  config?: Partial<RpcConfig>,
-  cluster: string = "mainnet-beta",
-): string {
-  if (config?.fallbackUrl) return config.fallbackUrl;
-
-  // Env fallback
-  const envUrl =
-    typeof process !== "undefined"
-      ? process.env?.SOLANA_FALLBACK_RPC_URL
-      : undefined;
-  if (envUrl) return envUrl;
-
-  return PUBLIC_RPCS[cluster] ?? PUBLIC_RPCS["mainnet-beta"]!;
-}
-
-/**
- * @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 function createDualConnection(
-  config: Partial<RpcConfig>,
-  cluster: string = "mainnet-beta",
-): DualConnection {
-  const commitment = config.commitment ?? "confirmed";
-  const primaryUrl = getRpcUrl(config, cluster);
-  const fallbackUrl = getFallbackRpcUrl(config, cluster);
-
-  return {
-    primary: new Connection(primaryUrl, { commitment }),
-    fallback: new Connection(fallbackUrl, { commitment }),
-  };
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Idempotent ATA Creation
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @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 function findATA(
-  owner: PublicKey,
-  mint: PublicKey,
-  programId: PublicKey = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"),
-): PublicKey {
-  const ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey(
-    "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
-  );
-
-  const [ata] = PublicKey.findProgramAddressSync(
-    [owner.toBuffer(), programId.toBuffer(), mint.toBuffer()],
-    ASSOCIATED_TOKEN_PROGRAM_ID,
-  );
-  return ata;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Error Classification
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * Anchor error code to friendly message mapping.
- * Converts cryptic Anchor errors into actionable messages.
- */
-const ANCHOR_ERROR_MESSAGES: Record<number, string> = {
-  6000: "Agent already registered for this wallet",
-  6001: "Agent not found — register first",
-  6002: "Name exceeds maximum length (64 bytes)",
-  6003: "Description exceeds maximum length (256 bytes)",
-  6004: "Too many capabilities (max 10)",
-  6005: "Too many pricing tiers (max 5)",
-  6006: "Too many protocols (max 5)",
-  6007: "Feedback score out of range (0-1000)",
-  6008: "Unauthorized — only the agent owner can perform this action",
-  6009: "Escrow expired",
-  6010: "Insufficient escrow balance",
-  6011: "Max calls exceeded",
-  6012: "Invalid settlement — calls must be > 0",
-  6013: "Escrow not empty — withdraw balance before closing",
-  6014: "Invalid token program — make sure you passed TOKEN_PROGRAM_ID as the 3rd remaining account",
-  6015: "Vault already initialized",
-  6016: "Session already exists",
-  6017: "Session closed — cannot write to closed session",
-  6018: "Data exceeds maximum write size (750 bytes)",
-  6019: "Ring buffer overflow — seal before writing more",
-};
-
-/**
- * @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 function classifyAnchorError(errorCode: number): string {
-  return (
-    ANCHOR_ERROR_MESSAGES[errorCode] ??
-    `Unknown SAP program error (code ${errorCode}). Check the IDL for details.`
-  );
-}
-
-/**
- * @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 function extractAnchorErrorCode(err: unknown): number | null {
-  if (err == null || typeof err !== "object") return null;
-
-  // Direct code property
-  const direct = (err as Record<string, unknown>).code;
-  if (typeof direct === "number") return direct;
-
-  // Nested Anchor format: error.error.errorCode.number
-  const nested = (err as Record<string, unknown>).error;
-  if (nested && typeof nested === "object") {
-    const errorCode = (nested as Record<string, unknown>).errorCode;
-    if (errorCode && typeof errorCode === "object") {
-      const num = (errorCode as Record<string, unknown>).number;
-      if (typeof num === "number") return num;
-    }
-  }
-
-  // AnchorError pattern: { logs: [...], error: { errorCode: { number } } }
-  const msg = (err as Error).message;
-  if (typeof msg === "string") {
-    const match = msg.match(/custom program error:\s*0x([0-9a-fA-F]+)/);
-    if (match?.[1]) return parseInt(match[1], 16);
-  }
-
-  return null;
-}

package/src/utils/schemas.ts

@@ -1,359 +0,0 @@
-/**
- * @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
- */
-
-// ═══════════════════════════════════════════════════════════════════
-//  Dynamic Zod import (peer dependency)
-// ═══════════════════════════════════════════════════════════════════
-
-// We use a lazy getter pattern to avoid hard failures when zod is not installed
-let _z: typeof import("zod") | null = null;
-
-function getZod(): typeof import("zod") {
-  if (!_z) {
-    try {
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      _z = require("zod");
-    } catch {
-      throw new Error(
-        "[SAP SDK] Zod is required for schema validation. Install it: npm install zod",
-      );
-    }
-  }
-  return _z!;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Environment Schemas
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @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 function createEnvSchema() {
-  const z = getZod();
-
-  return z.object({
-    SOLANA_CLUSTER: z
-      .enum(["mainnet-beta", "devnet", "localnet"])
-      .default("devnet")
-      .describe("Solana cluster"),
-    SOLANA_RPC_URL: z
-      .string()
-      .url()
-      .optional()
-      .describe("Primary RPC endpoint URL"),
-    SOLANA_FALLBACK_RPC_URL: z
-      .string()
-      .url()
-      .optional()
-      .describe("Fallback RPC for SPL token ops"),
-    SOLANA_WS_URL: z
-      .string()
-      .url()
-      .optional()
-      .describe("WebSocket endpoint URL"),
-    WALLET_KEYPAIR_PATH: z
-      .string()
-      .optional()
-      .describe("Path to keypair JSON file"),
-    WALLET_PRIVATE_KEY: z
-      .string()
-      .optional()
-      .describe("Base58 private key (alternative to file)"),
-    SAP_PROGRAM_ID: z
-      .string()
-      .optional()
-      .describe("Custom SAP program ID override"),
-    DATABASE_URL: z
-      .string()
-      .optional()
-      .describe("PostgreSQL connection URL"),
-    LOG_LEVEL: z
-      .enum(["debug", "info", "warn", "error"])
-      .default("info")
-      .describe("Log level"),
-    X402_ENDPOINT: z
-      .string()
-      .url()
-      .optional()
-      .describe("Agent x402 payment endpoint"),
-    AGENT_URI: z
-      .string()
-      .url()
-      .optional()
-      .describe("Agent public API URI"),
-  });
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Endpoint Schemas
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @name createEndpointDescriptorSchema
- * @description Zod schema for {@link EndpointDescriptor}.
- * @returns A Zod schema for endpoint descriptor validation.
- * @category Utils
- * @since v0.6.0
- */
-export function createEndpointDescriptorSchema() {
-  const z = getZod();
-
-  return z.object({
-    url: z.string().url(),
-    method: z.enum(["GET", "POST", "PUT", "DELETE"]).default("POST"),
-    contentType: z.string().default("application/json"),
-    requiresAuth: z.boolean().default(false),
-    authType: z.enum(["bearer", "api-key", "x402", "none"]).optional(),
-    requiresCSRF: z.boolean().default(false),
-    requiresCookies: z.boolean().default(false),
-    corsOrigins: z.array(z.string()).optional(),
-    requiredHeaders: z.record(z.string(), z.string()).optional(),
-  });
-}
-
-/**
- * @name createHealthCheckSchema
- * @description Zod schema for {@link HealthCheckDescriptor}.
- * @returns A Zod schema for health check validation.
- * @category Utils
- * @since v0.6.0
- */
-export function createHealthCheckSchema() {
-  const z = getZod();
-
-  return z.object({
-    url: z.string().url(),
-    expectedStatus: z.number().int().min(100).max(599).default(200),
-    timeoutMs: z.number().int().min(100).max(60_000).default(5000),
-    method: z.enum(["GET", "HEAD"]).default("GET"),
-  });
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Tool Manifest Schemas
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @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 function createToolManifestEntrySchema() {
-  const z = getZod();
-
-  return z.object({
-    name: z.string().min(1).max(64),
-    description: z.string().max(256),
-    protocol: z.string().min(1).max(64),
-    category: z.string().min(1),
-    inputSchema: z.record(z.string(), z.unknown()),
-    outputSchema: z.record(z.string(), z.unknown()),
-    httpMethod: z.enum(["GET", "POST", "PUT", "DELETE", "COMPOUND"]).default("POST"),
-    paymentMode: z.enum(["x402", "free", "prepaid", "subscription"]).default("x402"),
-    pricePerCall: z.number().int().min(0).default(0),
-    requiredArgs: z.array(z.string()).default([]),
-    prerequisites: z.array(z.string()).default([]),
-    endpointOverride: createEndpointDescriptorSchema().optional(),
-  });
-}
-
-/**
- * @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 function createAgentManifestSchema() {
-  const z = getZod();
-
-  return z.object({
-    version: z.literal("1.0.0"),
-    wallet: z.string().min(32).max(50),
-    name: z.string().min(1).max(64),
-    description: z.string().max(256),
-    endpoint: createEndpointDescriptorSchema(),
-    healthCheck: createHealthCheckSchema().optional(),
-    tools: z.array(createToolManifestEntrySchema()),
-    supportedNetworks: z.array(z.string()).min(1),
-    generatedAt: z.string().datetime(),
-  });
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  x402 Payment Schemas
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @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 function createPreparePaymentSchema() {
-  const z = getZod();
-
-  return z.object({
-    pricePerCall: z.union([z.number(), z.string(), z.bigint()]),
-    maxCalls: z.union([z.number(), z.string(), z.bigint()]).optional(),
-    deposit: z.union([z.number(), z.string(), z.bigint()]),
-    expiresAt: z.union([z.number(), z.string(), z.bigint()]).optional(),
-    volumeCurve: z
-      .array(
-        z.object({
-          afterCalls: z.number().int().min(1),
-          pricePerCall: z.union([z.number(), z.string(), z.bigint()]),
-        }),
-      )
-      .optional(),
-    tokenMint: z.string().optional(),
-    tokenDecimals: z.number().int().min(0).max(18).default(9),
-    networkIdentifier: z.string().optional(),
-  });
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Agent Registration Schemas
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @name createRegisterAgentSchema
- * @description Zod schema for agent registration arguments.
- * @returns A Zod schema for registration validation.
- * @category Utils
- * @since v0.6.0
- */
-export function createRegisterAgentSchema() {
-  const z = getZod();
-
-  return z.object({
-    name: z.string().min(1).max(64),
-    description: z.string().min(1).max(256),
-    agentId: z.string().max(128).optional().nullable(),
-    agentUri: z.string().max(256).optional().nullable(),
-    x402Endpoint: z.string().url().max(256).optional().nullable(),
-    capabilities: z
-      .array(
-        z.object({
-          id: z.string().min(1),
-          description: z.string().nullable().optional(),
-          protocolId: z.string().nullable().optional(),
-          version: z.string().nullable().optional(),
-        }),
-      )
-      .max(10)
-      .default([]),
-    protocols: z.array(z.string()).max(5).default([]),
-    pricing: z
-      .array(
-        z.object({
-          tierId: z.string().min(1),
-          pricePerCall: z.union([z.number(), z.string()]),
-          rateLimit: z.number().int().min(0),
-          tokenType: z.enum(["sol", "usdc", "spl"]).default("sol"),
-          settlementMode: z.enum(["instant", "escrow", "batched", "x402"]).default("x402"),
-        }),
-      )
-      .max(5)
-      .default([]),
-  });
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  CLI Script Argument Schemas
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @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 function createCallArgsSchema() {
-  const z = getZod();
-
-  return z.object({
-    agentWallet: z.string().min(32).max(50).describe("Agent wallet (base58)"),
-    tool: z.string().min(1).describe("Tool name to invoke"),
-    args: z.record(z.string(), z.unknown()).default({}).describe("Tool arguments (JSON)"),
-    endpoint: z.string().url().optional().describe("Endpoint URL override"),
-    network: z.string().optional().describe("Network identifier override"),
-    maxRetries: z.number().int().min(0).max(10).default(2),
-    timeoutMs: z.number().int().min(1000).max(120_000).default(30_000),
-  });
-}
-
-/**
- * @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 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 {
-  const result = schema.safeParse(value);
-  if (result.success) return schema.parse(value);
-
-  const issues = result.error?.issues ?? [];
-  const formatted = issues
-    .map((i) => `  • ${i.path.join(".")}: ${i.message}`)
-    .join("\n");
-
-  throw new Error(
-    `[SAP SDK] Invalid ${label}:\n${formatted}`,
-  );
-}