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

package/dist/cjs/utils/network-normalizer.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * @module utils/network-normalizer
+ * @description Network identifier normalization for x402 payment headers.
+ *
+ * Solves the canonical-string mismatch between SAP clients and servers:
+ * some providers accept `solana:mainnet-beta` while others require
+ * the genesis-hash form `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`.
+ *
+ * This module provides a single source of truth for normalizing
+ * network identifiers so that both clients and agents canonicalize
+ * before comparing. Catches the Kamiyo "sap network mismatch" error
+ * at the SDK level.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeNetworkId = normalizeNetworkId;
+exports.isNetworkEquivalent = isNetworkEquivalent;
+exports.getNetworkGenesisHash = getNetworkGenesisHash;
+exports.getNetworkClusterName = getNetworkClusterName;
+exports.isKnownNetwork = isKnownNetwork;
+const network_1 = require("../constants/network");
+// ═══════════════════════════════════════════════════════════════════
+//  Canonical Mapping
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Bidirectional alias map: for every known network string, stores the
+ * canonical SapNetworkId it resolves to, plus all known aliases.
+ */
+const NETWORK_ALIASES = new Map([
+    // ── Mainnet ───────────────────────────────
+    // Canonical: genesis-hash form
+    ["solana:mainnet-beta", network_1.SapNetwork.SOLANA_MAINNET],
+    ["solana:mainnet", network_1.SapNetwork.SOLANA_MAINNET],
+    ["mainnet-beta", network_1.SapNetwork.SOLANA_MAINNET],
+    ["mainnet", network_1.SapNetwork.SOLANA_MAINNET],
+    ["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", network_1.SapNetwork.SOLANA_MAINNET_GENESIS],
+    ["5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", network_1.SapNetwork.SOLANA_MAINNET_GENESIS],
+    // ── Devnet ────────────────────────────────
+    ["solana:devnet", network_1.SapNetwork.SOLANA_DEVNET_NAMED],
+    ["devnet", network_1.SapNetwork.SOLANA_DEVNET_NAMED],
+    ["solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", network_1.SapNetwork.SOLANA_DEVNET],
+    ["EtWTRABZaYq6iMfeYKouRu166VU2xqa1", network_1.SapNetwork.SOLANA_DEVNET],
+]);
+/**
+ * Mainnet equivalence set: all strings that refer to Solana mainnet-beta,
+ * regardless of format.
+ */
+const MAINNET_EQUIVALENTS = new Set([
+    network_1.SapNetwork.SOLANA_MAINNET,
+    network_1.SapNetwork.SOLANA_MAINNET_GENESIS,
+    "solana:mainnet",
+    "mainnet-beta",
+    "mainnet",
+    "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+]);
+/**
+ * Devnet equivalence set.
+ */
+const DEVNET_EQUIVALENTS = new Set([
+    network_1.SapNetwork.SOLANA_DEVNET,
+    network_1.SapNetwork.SOLANA_DEVNET_NAMED,
+    "devnet",
+    "EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+]);
+// ═══════════════════════════════════════════════════════════════════
+//  Public API
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name normalizeNetworkId
+ * @description Normalize a raw network identifier string to its canonical
+ * {@link SapNetworkId} form.
+ *
+ * Handles:
+ *   - Case-insensitive matching
+ *   - Stripping whitespace
+ *   - Resolving genesis-hash vs. cluster-name aliases
+ *   - Unknown strings are returned as-is (passthrough)
+ *
+ * @param raw - Raw network identifier string from headers, env vars, or config.
+ * @returns The canonical {@link SapNetworkId}, or the trimmed input if unknown.
+ *
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * import { normalizeNetworkId } from "@synapse-sap/sdk";
+ *
+ * normalizeNetworkId("solana:mainnet-beta");
+ * // → "solana:mainnet-beta"
+ *
+ * normalizeNetworkId("5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp");
+ * // → "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
+ *
+ * normalizeNetworkId("  MAINNET  ");
+ * // → "solana:mainnet-beta"
+ * ```
+ */
+function normalizeNetworkId(raw) {
+    const trimmed = raw.trim();
+    // Exact match first
+    const exact = NETWORK_ALIASES.get(trimmed);
+    if (exact)
+        return exact;
+    // Case-insensitive lookup
+    const lower = trimmed.toLowerCase();
+    for (const [alias, canonical] of NETWORK_ALIASES) {
+        if (alias.toLowerCase() === lower)
+            return canonical;
+    }
+    // Passthrough for unknown networks (custom chains, etc.)
+    return trimmed;
+}
+/**
+ * @name isNetworkEquivalent
+ * @description Check if two network identifier strings refer to the same network,
+ * even if they use different formats (cluster-name vs. genesis-hash).
+ *
+ * This is the key function that prevents the Kamiyo "sap network mismatch"
+ * error — instead of comparing strings literally, we compare their
+ * canonical equivalence class.
+ *
+ * @param a - First network identifier.
+ * @param b - Second network identifier.
+ * @returns `true` if both identifiers refer to the same Solana network.
+ *
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * import { isNetworkEquivalent } from "@synapse-sap/sdk";
+ *
+ * isNetworkEquivalent("solana:mainnet-beta", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp");
+ * // → true
+ *
+ * isNetworkEquivalent("solana:devnet", "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1");
+ * // → true
+ *
+ * isNetworkEquivalent("solana:mainnet-beta", "solana:devnet");
+ * // → false
+ * ```
+ */
+function isNetworkEquivalent(a, b) {
+    const normA = a.trim();
+    const normB = b.trim();
+    // Fast path: identical strings
+    if (normA === normB)
+        return true;
+    // Check if both are in the same equivalence set
+    if (MAINNET_EQUIVALENTS.has(normA) && MAINNET_EQUIVALENTS.has(normB))
+        return true;
+    if (DEVNET_EQUIVALENTS.has(normA) && DEVNET_EQUIVALENTS.has(normB))
+        return true;
+    // Case-insensitive match
+    const lowerA = normA.toLowerCase();
+    const lowerB = normB.toLowerCase();
+    if (lowerA === lowerB)
+        return true;
+    // Resolve both to canonical and compare
+    const canonA = normalizeNetworkId(normA);
+    const canonB = normalizeNetworkId(normB);
+    if (canonA === canonB)
+        return true;
+    // Final check: both resolve to the same equivalence set
+    if (MAINNET_EQUIVALENTS.has(canonA) && MAINNET_EQUIVALENTS.has(canonB))
+        return true;
+    if (DEVNET_EQUIVALENTS.has(canonA) && DEVNET_EQUIVALENTS.has(canonB))
+        return true;
+    return false;
+}
+/**
+ * @name getNetworkGenesisHash
+ * @description Get the genesis-hash form of a network identifier.
+ * Returns the genesis-hash variant for known networks, or the input as-is.
+ *
+ * Useful for agents that require the genesis-hash form (Kamiyo, Helius x402).
+ *
+ * @param networkId - Any network identifier.
+ * @returns The genesis-hash form, or the input if unknown.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+function getNetworkGenesisHash(networkId) {
+    const norm = normalizeNetworkId(networkId);
+    if (MAINNET_EQUIVALENTS.has(networkId) || MAINNET_EQUIVALENTS.has(norm)) {
+        return network_1.SapNetwork.SOLANA_MAINNET_GENESIS;
+    }
+    if (DEVNET_EQUIVALENTS.has(networkId) || DEVNET_EQUIVALENTS.has(norm)) {
+        return network_1.SapNetwork.SOLANA_DEVNET;
+    }
+    return norm;
+}
+/**
+ * @name getNetworkClusterName
+ * @description Get the cluster-name form of a network identifier.
+ * Returns the human-readable cluster name for known networks.
+ *
+ * Useful for providers that accept cluster names (Coinbase, Phantom).
+ *
+ * @param networkId - Any network identifier.
+ * @returns The cluster-name form, or the input if unknown.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+function getNetworkClusterName(networkId) {
+    const norm = normalizeNetworkId(networkId);
+    if (MAINNET_EQUIVALENTS.has(networkId) || MAINNET_EQUIVALENTS.has(norm)) {
+        return network_1.SapNetwork.SOLANA_MAINNET;
+    }
+    if (DEVNET_EQUIVALENTS.has(networkId) || DEVNET_EQUIVALENTS.has(norm)) {
+        return network_1.SapNetwork.SOLANA_DEVNET_NAMED;
+    }
+    return norm;
+}
+/**
+ * @name isKnownNetwork
+ * @description Check if a network identifier is recognized by the SDK.
+ *
+ * @param networkId - The network identifier to check.
+ * @returns `true` if the identifier maps to a known Solana network.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+function isKnownNetwork(networkId) {
+    const trimmed = networkId.trim();
+    return MAINNET_EQUIVALENTS.has(trimmed) || DEVNET_EQUIVALENTS.has(trimmed) ||
+        NETWORK_ALIASES.has(trimmed);
+}
+//# sourceMappingURL=network-normalizer.js.map

package/dist/cjs/utils/network-normalizer.js.map

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

package/dist/cjs/utils/rpc-strategy.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRpcUrl = getRpcUrl;
+exports.getFallbackRpcUrl = getFallbackRpcUrl;
+exports.createDualConnection = createDualConnection;
+exports.findATA = findATA;
+exports.classifyAnchorError = classifyAnchorError;
+exports.extractAnchorErrorCode = extractAnchorErrorCode;
+const web3_js_1 = require("@solana/web3.js");
+// ═══════════════════════════════════════════════════════════════════
+//  Default Public RPCs
+// ═══════════════════════════════════════════════════════════════════
+/** Well-known public fallback RPCs by cluster. */
+const PUBLIC_RPCS = {
+    "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
+ */
+function getRpcUrl(config, cluster = "mainnet-beta") {
+    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
+ */
+function getFallbackRpcUrl(config, cluster = "mainnet-beta") {
+    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);
+ * ```
+ */
+function createDualConnection(config, cluster = "mainnet-beta") {
+    const commitment = config.commitment ?? "confirmed";
+    const primaryUrl = getRpcUrl(config, cluster);
+    const fallbackUrl = getFallbackRpcUrl(config, cluster);
+    return {
+        primary: new web3_js_1.Connection(primaryUrl, { commitment }),
+        fallback: new web3_js_1.Connection(fallbackUrl, { commitment }),
+    };
+}
+/**
+ * @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
+ */
+function findATA(owner, mint, programId = new web3_js_1.PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA")) {
+    const ASSOCIATED_TOKEN_PROGRAM_ID = new web3_js_1.PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
+    const [ata] = web3_js_1.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 = {
+    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));
+ *   }
+ * }
+ * ```
+ */
+function classifyAnchorError(errorCode) {
+    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
+ */
+function extractAnchorErrorCode(err) {
+    if (err == null || typeof err !== "object")
+        return null;
+    // Direct code property
+    const direct = err.code;
+    if (typeof direct === "number")
+        return direct;
+    // Nested Anchor format: error.error.errorCode.number
+    const nested = err.error;
+    if (nested && typeof nested === "object") {
+        const errorCode = nested.errorCode;
+        if (errorCode && typeof errorCode === "object") {
+            const num = errorCode.number;
+            if (typeof num === "number")
+                return num;
+        }
+    }
+    // AnchorError pattern: { logs: [...], error: { errorCode: { number } } }
+    const msg = err.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;
+}
+//# sourceMappingURL=rpc-strategy.js.map

package/dist/cjs/utils/rpc-strategy.js.map

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