@oobe-protocol-labs/synapse-sap-sdk 0.1.0

package/dist/cjs/core/connection.js

@@ -0,0 +1,319 @@
+"use strict";
+/**
+ * @module core/connection
+ * @description RPC connection factory for SAP v2 SDK.
+ *
+ * Provides a high-level, synapse-client-sdk–compatible entry point
+ * for creating {@link SapClient} instances from an RPC URL and wallet.
+ *
+ * @category Core
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { SapConnection } from "@synapse-sap/sdk";
+ *
+ * // Quick start — RPC URL + Keypair
+ * const sap = SapConnection.fromKeypair("https://api.devnet.solana.com", keypair);
+ * const agent = await sap.client.agent.fetch();
+ *
+ * // Or build step-by-step
+ * const conn = new SapConnection({
+ *   rpcUrl: "https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=xxx",
+ *   cluster: "mainnet-beta",
+ *   commitment: "confirmed",
+ * });
+ * const client = conn.createClient(wallet);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SapConnection = void 0;
+const web3_js_1 = require("@solana/web3.js");
+const anchor_1 = require("@coral-xyz/anchor");
+const constants_1 = require("../constants");
+const client_1 = require("./client");
+// ═══════════════════════════════════════════════════════════════════
+//  Implementation
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name SapConnection
+ * @description Lightweight RPC connection wrapper that creates
+ * properly-configured {@link SapClient} instances.
+ *
+ * Compatible with the `synapse-client-sdk` connection model:
+ * start from an RPC URL, attach a wallet, get a typed client.
+ *
+ * @category Core
+ * @since v0.1.0
+ * @see {@link SapClient}
+ * @see {@link SapConnectionConfig}
+ *
+ * @example
+ * ```ts
+ * // Factory shortcut for devnet
+ * const conn = SapConnection.devnet();
+ * const client = conn.createClient(wallet);
+ *
+ * // One-liner with Keypair
+ * const { client } = SapConnection.fromKeypair(
+ *   "https://api.devnet.solana.com",
+ *   keypair,
+ * );
+ * ```
+ */
+class SapConnection {
+    /**
+     * @readonly
+     * @description Raw Solana {@link Connection}. Exposed for advanced
+     * use-cases that need direct RPC access.
+     */
+    connection;
+    /**
+     * @readonly
+     * @description The resolved Solana cluster for this connection,
+     * either explicitly provided or auto-detected from the RPC URL.
+     */
+    cluster;
+    /**
+     * @readonly
+     * @description Commitment level used for all queries and
+     * transaction confirmations on this connection.
+     */
+    commitment;
+    /**
+     * @readonly
+     * @description The SAP on-chain program {@link PublicKey} resolved
+     * for the current {@link cluster}.
+     * @see {@link SapConnection.programIdForCluster}
+     */
+    programId;
+    constructor(config) {
+        this.commitment = config.commitment ?? "confirmed";
+        this.cluster = config.cluster ?? SapConnection.detectCluster(config.rpcUrl);
+        this.programId = SapConnection.programIdForCluster(this.cluster);
+        this.connection = new web3_js_1.Connection(config.rpcUrl, {
+            commitment: this.commitment,
+            wsEndpoint: config.wsUrl,
+        });
+    }
+    // ─────────────────────────────────────────────
+    //  Factory helpers
+    // ─────────────────────────────────────────────
+    /**
+     * Create a {@link SapConnection} for **devnet** with sensible defaults.
+     *
+     * @static
+     * @param {Commitment} [commitment="confirmed"] — Commitment level.
+     * @returns {SapConnection} A connection targeting Solana devnet.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const conn = SapConnection.devnet();
+     * ```
+     */
+    static devnet(commitment = "confirmed") {
+        return new SapConnection({
+            rpcUrl: "https://api.devnet.solana.com",
+            cluster: "devnet",
+            commitment,
+        });
+    }
+    /**
+     * Create a {@link SapConnection} for **mainnet-beta** with sensible defaults.
+     *
+     * @static
+     * @param {string} [rpcUrl="https://api.mainnet-beta.solana.com"] — Custom RPC URL.
+     * @param {Commitment} [commitment="confirmed"] — Commitment level.
+     * @returns {SapConnection} A connection targeting Solana mainnet-beta.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const conn = SapConnection.mainnet("https://my-rpc.example.com");
+     * ```
+     */
+    static mainnet(rpcUrl = "https://api.mainnet-beta.solana.com", commitment = "confirmed") {
+        return new SapConnection({ rpcUrl, cluster: "mainnet-beta", commitment });
+    }
+    /**
+     * Create a {@link SapConnection} for **localnet** (`localhost:8899`).
+     *
+     * @static
+     * @param {Commitment} [commitment="confirmed"] — Commitment level.
+     * @returns {SapConnection} A connection targeting a local validator.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const conn = SapConnection.localnet();
+     * ```
+     */
+    static localnet(commitment = "confirmed") {
+        return new SapConnection({
+            rpcUrl: "http://localhost:8899",
+            cluster: "localnet",
+            commitment,
+        });
+    }
+    /**
+     * One-liner: create a {@link SapConnection} + {@link SapClient} from
+     * an RPC URL and a `Keypair`. Perfect for scripts and CLI tools.
+     *
+     * @static
+     * @param {string} rpcUrl — Solana JSON-RPC endpoint.
+     * @param {Keypair} keypair — Signer keypair.
+     * @param {object} [opts] — Optional overrides.
+     * @param {Commitment} [opts.commitment] — Commitment level.
+     * @param {SapCluster} [opts.cluster] — Explicit cluster hint.
+     * @returns {SapConnection & { readonly client: SapClient }} Connection with an attached client.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const { client, connection } = SapConnection.fromKeypair(
+     *   "https://api.devnet.solana.com",
+     *   Keypair.generate(),
+     * );
+     * ```
+     */
+    static fromKeypair(rpcUrl, keypair, opts) {
+        const conn = new SapConnection({
+            rpcUrl,
+            commitment: opts?.commitment,
+            cluster: opts?.cluster,
+        });
+        const client = conn.createClient(new anchor_1.Wallet(keypair));
+        return Object.assign(conn, { client });
+    }
+    // ─────────────────────────────────────────────
+    //  Client creation
+    // ─────────────────────────────────────────────
+    /**
+     * Create a {@link SapClient} from an Anchor {@link Wallet} (signer).
+     *
+     * @param {Wallet} wallet — An Anchor-compatible wallet/signer.
+     * @returns {SapClient} A fully-configured SAP client.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const client = conn.createClient(new Wallet(keypair));
+     * ```
+     */
+    createClient(wallet) {
+        const provider = new anchor_1.AnchorProvider(this.connection, wallet, {
+            commitment: this.commitment,
+        });
+        return client_1.SapClient.from(provider, this.programId);
+    }
+    /**
+     * Create a {@link SapClient} from a raw {@link Keypair}.
+     *
+     * @param {Keypair} keypair — The signer keypair.
+     * @returns {SapClient} A fully-configured SAP client.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const client = conn.fromKeypair(Keypair.generate());
+     * ```
+     */
+    fromKeypair(keypair) {
+        return this.createClient(new anchor_1.Wallet(keypair));
+    }
+    // ─────────────────────────────────────────────
+    //  Utility methods
+    // ─────────────────────────────────────────────
+    /**
+     * Request an airdrop (devnet / localnet only).
+     *
+     * @param {PublicKey} to — Recipient public key.
+     * @param {number} solAmount — Amount of SOL to airdrop.
+     * @returns {Promise<string>} The confirmed transaction signature.
+     * @throws {Error} If the airdrop request or confirmation fails (e.g. on mainnet).
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const sig = await conn.airdrop(wallet.publicKey, 2);
+     * ```
+     */
+    async airdrop(to, solAmount) {
+        const sig = await this.connection.requestAirdrop(to, solAmount * web3_js_1.LAMPORTS_PER_SOL);
+        await this.connection.confirmTransaction(sig, this.commitment);
+        return sig;
+    }
+    /**
+     * Get the SOL balance of an address in **lamports**.
+     *
+     * @param {PublicKey} address — The account to query.
+     * @returns {Promise<number>} Balance in lamports.
+     * @since v0.1.0
+     */
+    async getBalance(address) {
+        return this.connection.getBalance(address, this.commitment);
+    }
+    /**
+     * Get the SOL balance of an address in **SOL** (human-readable).
+     *
+     * @param {PublicKey} address — The account to query.
+     * @returns {Promise<number>} Balance in SOL.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const sol = await conn.getBalanceSol(wallet.publicKey);
+     * console.log(`Balance: ${sol} SOL`);
+     * ```
+     */
+    async getBalanceSol(address) {
+        const lamports = await this.getBalance(address);
+        return lamports / web3_js_1.LAMPORTS_PER_SOL;
+    }
+    // ─────────────────────────────────────────────
+    //  Internal helpers
+    // ─────────────────────────────────────────────
+    /**
+     * Infer the {@link SapCluster} from an RPC URL by inspecting
+     * well-known substrings (`devnet`, `localhost`, `:8899`).
+     *
+     * @static
+     * @param {string} rpcUrl — The RPC endpoint to inspect.
+     * @returns {SapCluster} The detected cluster, defaulting to `"mainnet-beta"`.
+     * @since v0.1.0
+     */
+    static detectCluster(rpcUrl) {
+        const lower = rpcUrl.toLowerCase();
+        if (lower.includes("devnet"))
+            return "devnet";
+        if (lower.includes("localhost") ||
+            lower.includes("127.0.0.1") ||
+            lower.includes(":8899"))
+            return "localnet";
+        return "mainnet-beta";
+    }
+    /**
+     * Map a {@link SapCluster} to the canonical SAP on-chain program ID.
+     *
+     * @static
+     * @param {SapCluster} cluster — Target cluster.
+     * @returns {PublicKey} The program {@link PublicKey} for the given cluster.
+     * @since v0.1.0
+     * @see {@link SAP_PROGRAM_ID}
+     */
+    static programIdForCluster(cluster) {
+        switch (cluster) {
+            case "mainnet-beta":
+                return constants_1.MAINNET_SAP_PROGRAM_ID;
+            case "devnet":
+                return constants_1.DEVNET_SAP_PROGRAM_ID;
+            case "localnet":
+                return constants_1.LOCALNET_SAP_PROGRAM_ID;
+            default:
+                return constants_1.SAP_PROGRAM_ID;
+        }
+    }
+}
+exports.SapConnection = SapConnection;
+//# sourceMappingURL=connection.js.map

package/dist/cjs/core/connection.js.map

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

package/dist/cjs/core/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * @module core
+ * @description Core infrastructure — client creation and RPC connection.
+ *
+ * @example
+ * ```ts
+ * import { SapClient, SapConnection } from "@synapse-sap/sdk";
+ *
+ * // From Anchor provider
+ * const client = SapClient.from(provider);
+ *
+ * // From RPC URL + keypair (synapse-client-sdk compatible)
+ * const conn = SapConnection.devnet();
+ * const client2 = conn.fromKeypair(keypair);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SapConnection = exports.SapClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "SapClient", { enumerable: true, get: function () { return client_1.SapClient; } });
+var connection_1 = require("./connection");
+Object.defineProperty(exports, "SapConnection", { enumerable: true, get: function () { return connection_1.SapConnection; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAEH,mCAAqC;AAA5B,mGAAA,SAAS,OAAA;AAClB,2CAA6C;AAApC,2GAAA,aAAa,OAAA"}

package/dist/cjs/errors/index.js

@@ -0,0 +1,334 @@
+"use strict";
+/**
+ * @module errors
+ * @description Typed error classes for the SAP v2 SDK.
+ *
+ * All SDK errors extend {@link SapError} to allow catch-all handling,
+ * while concrete subclasses enable fine-grained error matching.
+ *
+ * @category Errors
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { SapError, SapRpcError, SapAccountNotFoundError } from "@synapse-sap/sdk/errors";
+ *
+ * try {
+ *   const agent = await client.agent.fetch();
+ * } catch (err) {
+ *   if (err instanceof SapAccountNotFoundError) {
+ *     console.log("Agent not registered yet");
+ *   } else if (err instanceof SapRpcError) {
+ *     console.error("RPC failure:", err.rpcCode);
+ *   } else if (err instanceof SapError) {
+ *     console.error("SAP error:", err.message);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapError}
+ * @see {@link SapValidationError}
+ * @see {@link SapRpcError}
+ * @see {@link SapAccountNotFoundError}
+ * @see {@link SapTimeoutError}
+ * @see {@link SapPermissionError}
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SapPermissionError = exports.SapTimeoutError = exports.SapAccountNotFoundError = exports.SapRpcError = exports.SapValidationError = exports.SapError = void 0;
+// ═══════════════════════════════════════════════════════════════════
+//  Base Error
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name SapError
+ * @description Base class for all SAP SDK errors.
+ *
+ * Extends `Error` and sets `name` automatically so `instanceof`
+ * checks work correctly in both CJS and ESM environments.
+ *
+ * @category Errors
+ * @since v0.1.0
+ * @extends {Error}
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.agent.fetch();
+ * } catch (err) {
+ *   if (err instanceof SapError) {
+ *     console.error(`[${err.code}] ${err.message}`);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapValidationError}
+ * @see {@link SapRpcError}
+ * @see {@link SapAccountNotFoundError}
+ * @see {@link SapTimeoutError}
+ * @see {@link SapPermissionError}
+ */
+class SapError extends Error {
+    /**
+     * @description Machine-readable error code for programmatic handling.
+     * @readonly
+     */
+    code;
+    /**
+     * @param message - A human-readable description of the error.
+     * @param code    - Machine-readable error code (defaults to `"SAP_ERROR"`).
+     */
+    constructor(message, code = "SAP_ERROR") {
+        super(message);
+        this.name = "SapError";
+        this.code = code;
+        // Fix prototype chain for instanceof checks
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.SapError = SapError;
+// ═══════════════════════════════════════════════════════════════════
+//  Validation Error
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name SapValidationError
+ * @description Thrown when SDK-side input validation fails before sending a
+ * transaction or making an RPC call.
+ *
+ * @category Errors
+ * @since v0.1.0
+ * @extends {SapError}
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.agent.register({ name: "" });
+ * } catch (err) {
+ *   if (err instanceof SapValidationError) {
+ *     console.error(`Validation failed on field "${err.field}": ${err.message}`);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapError}
+ */
+class SapValidationError extends SapError {
+    /**
+     * @description Field or parameter that failed validation (if applicable).
+     * @readonly
+     */
+    field;
+    /**
+     * @param message - A human-readable description of the validation failure.
+     * @param field   - The name of the field or parameter that failed validation.
+     */
+    constructor(message, field) {
+        super(message, "SAP_VALIDATION_ERROR");
+        this.name = "SapValidationError";
+        this.field = field;
+    }
+}
+exports.SapValidationError = SapValidationError;
+// ═══════════════════════════════════════════════════════════════════
+//  RPC / Transaction Error
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name SapRpcError
+ * @description Wraps Solana RPC or Anchor transaction errors with additional
+ * context (error code, logs).
+ *
+ * @category Errors
+ * @since v0.1.0
+ * @extends {SapError}
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.agent.register(params);
+ * } catch (err) {
+ *   if (err instanceof SapRpcError) {
+ *     console.error(`RPC error ${err.rpcCode}: ${err.message}`);
+ *     err.logs?.forEach((log) => console.debug(log));
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapRpcError.fromAnchor}
+ * @see {@link SapError}
+ */
+class SapRpcError extends SapError {
+    /**
+     * @description Anchor / program error code, if available.
+     * @readonly
+     */
+    rpcCode;
+    /**
+     * @description Transaction logs returned by the RPC node.
+     * @readonly
+     */
+    logs;
+    /**
+     * @param message - A human-readable description of the RPC or transaction error.
+     * @param opts    - Optional additional context.
+     * @param opts.rpcCode - Anchor or Solana program error code.
+     * @param opts.logs    - Raw transaction logs from the RPC node.
+     */
+    constructor(message, opts) {
+        super(message, "SAP_RPC_ERROR");
+        this.name = "SapRpcError";
+        this.rpcCode = opts?.rpcCode;
+        this.logs = opts?.logs;
+    }
+    /**
+     * @static
+     * @description Create a {@link SapRpcError} from an Anchor-style error object.
+     * Extracts `code` and `logs` automatically from the Anchor error shape.
+     *
+     * @param err - The raw Anchor or Solana error object.
+     * @returns A new {@link SapRpcError} populated with extracted code, logs, and message.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   await program.methods.registerAgent(args).rpc();
+     * } catch (raw) {
+     *   throw SapRpcError.fromAnchor(raw);
+     * }
+     * ```
+     *
+     * @see {@link SapRpcError}
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static fromAnchor(err) {
+        const code = err?.error?.errorCode?.number ?? err?.code;
+        const logs = err?.logs ?? err?.error?.logs ?? [];
+        const msg = err?.error?.errorMessage ?? err?.message ?? "Unknown RPC error";
+        return new SapRpcError(msg, { rpcCode: code, logs });
+    }
+}
+exports.SapRpcError = SapRpcError;
+// ═══════════════════════════════════════════════════════════════════
+//  Account Not Found
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name SapAccountNotFoundError
+ * @description Thrown when an expected on-chain account does not exist or has
+ * been closed.
+ *
+ * @category Errors
+ * @since v0.1.0
+ * @extends {SapError}
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const agent = await client.agent.fetch(agentPda);
+ * } catch (err) {
+ *   if (err instanceof SapAccountNotFoundError) {
+ *     console.warn(`Missing ${err.accountType ?? "account"}: ${err.address}`);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapError}
+ */
+class SapAccountNotFoundError extends SapError {
+    /**
+     * @description The base-58 encoded account address that was not found.
+     * @readonly
+     */
+    address;
+    /**
+     * @description The expected account type (e.g. `"AgentRecord"`, `"VaultAccount"`).
+     * @readonly
+     */
+    accountType;
+    /**
+     * @param address     - The base-58 encoded address of the missing account.
+     * @param accountType - Optional label for the expected account type.
+     */
+    constructor(address, accountType) {
+        const label = accountType ? `${accountType} account` : "Account";
+        super(`${label} not found: ${address}`, "SAP_ACCOUNT_NOT_FOUND");
+        this.name = "SapAccountNotFoundError";
+        this.address = address;
+        this.accountType = accountType;
+    }
+}
+exports.SapAccountNotFoundError = SapAccountNotFoundError;
+// ═══════════════════════════════════════════════════════════════════
+//  Timeout Error
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name SapTimeoutError
+ * @description Thrown when an operation (e.g., transaction confirmation) exceeds
+ * the configured timeout.
+ *
+ * @category Errors
+ * @since v0.1.0
+ * @extends {SapError}
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.agent.register(params, { timeoutMs: 30_000 });
+ * } catch (err) {
+ *   if (err instanceof SapTimeoutError) {
+ *     console.error(`Timed out after ${err.timeoutMs}ms: ${err.message}`);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapError}
+ */
+class SapTimeoutError extends SapError {
+    /**
+     * @description Timeout duration in milliseconds that was exceeded.
+     * @readonly
+     */
+    timeoutMs;
+    /**
+     * @param message   - A human-readable description of the timeout.
+     * @param timeoutMs - The timeout threshold in milliseconds.
+     */
+    constructor(message, timeoutMs) {
+        super(message, "SAP_TIMEOUT");
+        this.name = "SapTimeoutError";
+        this.timeoutMs = timeoutMs;
+    }
+}
+exports.SapTimeoutError = SapTimeoutError;
+// ═══════════════════════════════════════════════════════════════════
+//  Permission Error
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name SapPermissionError
+ * @description Thrown when the current wallet lacks the required permission
+ * (authority, delegate, etc.) for an operation.
+ *
+ * @category Errors
+ * @since v0.1.0
+ * @extends {SapError}
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.agent.update(agentPda, updates);
+ * } catch (err) {
+ *   if (err instanceof SapPermissionError) {
+ *     console.error(`Permission denied: ${err.message}`);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapError}
+ */
+class SapPermissionError extends SapError {
+    /**
+     * @param message - A human-readable description of the permission failure.
+     */
+    constructor(message) {
+        super(message, "SAP_PERMISSION_DENIED");
+        this.name = "SapPermissionError";
+    }
+}
+exports.SapPermissionError = SapPermissionError;
+//# sourceMappingURL=index.js.map

package/dist/cjs/errors/index.js.map

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