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

package/dist/cjs/core/client.js

@@ -0,0 +1,391 @@
+"use strict";
+/**
+ * @module core/client
+ * @description Core SapClient — thin wrapper around the Anchor program
+ * that wires up provider, IDL, and exposes typed module accessors.
+ *
+ * This is the primary entry point for the `@synapse-sap/sdk` package.
+ * All protocol domains (agent lifecycle, reputation, vault, escrow, etc.)
+ * are available as lazily-instantiated, strongly-typed module accessors.
+ *
+ * @since v0.1.0
+ * @category Core
+ *
+ * @example
+ * ```ts
+ * import { SapClient } from "@synapse-sap/sdk";
+ *
+ * const client = SapClient.from(provider);          // auto-IDL
+ * const client = SapClient.fromProgram(program);    // existing program
+ *
+ * // Use domain modules:
+ * await client.agent.register({ ... });
+ * await client.vault.initVault(vaultNonce);
+ * const escrow = await client.escrow.fetch(escrowPda);
+ * ```
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SapClient = void 0;
+const anchor_1 = require("@coral-xyz/anchor");
+const constants_1 = require("../constants");
+const agent_1 = require("../modules/agent");
+const feedback_1 = require("../modules/feedback");
+const indexing_1 = require("../modules/indexing");
+const tools_1 = require("../modules/tools");
+const vault_1 = require("../modules/vault");
+const escrow_1 = require("../modules/escrow");
+const attestation_1 = require("../modules/attestation");
+const ledger_1 = require("../modules/ledger");
+const events_1 = require("../events");
+const discovery_1 = require("../registries/discovery");
+const x402_1 = require("../registries/x402");
+const session_1 = require("../registries/session");
+const builder_1 = require("../registries/builder");
+// IDL is embedded inside the SDK — no external workspace dependency
+const synapse_agent_sap_json_1 = __importDefault(require("../idl/synapse_agent_sap.json"));
+/**
+ * @name SapClient
+ * @description Root entry point for the Solana Agent Protocol v2 TypeScript SDK.
+ *
+ * Each protocol domain is exposed as a lazily-instantiated module:
+ * `agent`, `feedback`, `indexing`, `tools`, `vault`, `escrow`,
+ * `attestation`, `ledger`, `events`.
+ *
+ * Higher-level abstractions (`discovery`, `x402`, `session`, `builder`)
+ * compose the low-level modules into ergonomic workflows.
+ *
+ * Instantiate via the static factory methods {@link SapClient.from} or
+ * {@link SapClient.fromProgram} — the constructor is private.
+ *
+ * @category Core
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { SapClient } from "@synapse-sap/sdk";
+ * import { AnchorProvider } from "@coral-xyz/anchor";
+ *
+ * const provider = AnchorProvider.env();
+ * const client = SapClient.from(provider);
+ *
+ * // Register an agent
+ * await client.agent.register({
+ *   name: "SwapBot",
+ *   description: "AI-powered swap agent",
+ * });
+ *
+ * // Discover agents
+ * const agents = await client.discovery.findAgentsByProtocol("jupiter");
+ * ```
+ */
+class SapClient {
+    /**
+     * @name program
+     * @description The underlying Anchor `Program` instance used for all RPC
+     * calls and account deserialization.
+     * @readonly
+     * @category Core
+     * @since v0.1.0
+     */
+    program;
+    /**
+     * @name walletPubkey
+     * @description The provider wallet's public key, extracted from the
+     * Anchor provider for convenience. This is the default authority /
+     * payer used by module instructions unless overridden.
+     * @readonly
+     * @category Core
+     * @since v0.1.0
+     */
+    walletPubkey;
+    // ── Lazy module singletons ────────────────────────
+    #agent;
+    #feedback;
+    #indexing;
+    #tools;
+    #vault;
+    #escrow;
+    #attestation;
+    #ledger;
+    #events;
+    // ── Lazy registry singletons ──────────────────────
+    #discovery;
+    #x402;
+    #session;
+    constructor(program) {
+        this.program = program;
+        this.walletPubkey = program.provider.wallet.publicKey;
+    }
+    // ═════════════════════════════════════════════
+    //  Factory Methods
+    // ═════════════════════════════════════════════
+    /**
+     * @name from
+     * @description Create a {@link SapClient} from an `AnchorProvider`.
+     * Automatically loads the embedded IDL shipped with the SDK.
+     *
+     * @param provider - A configured `AnchorProvider` with wallet and connection.
+     * @param programId - Optional override for the SAP program ID.
+     *   Defaults to `SAP_PROGRAM_ID` from `@synapse-sap/sdk/constants`.
+     * @returns A fully-initialised `SapClient` ready for use.
+     *
+     * @category Core
+     * @since v0.1.0
+     * @see {@link SapClient.fromProgram} for an alternative accepting a pre-built `Program`.
+     *
+     * @example
+     * ```ts
+     * import { SapClient } from "@synapse-sap/sdk";
+     * import { AnchorProvider } from "@coral-xyz/anchor";
+     *
+     * const provider = AnchorProvider.env();
+     * const client = SapClient.from(provider);
+     * ```
+     *
+     * @example Custom program ID (e.g. localnet)
+     * ```ts
+     * const client = SapClient.from(provider, myLocalProgramId);
+     * ```
+     */
+    static from(provider, programId = constants_1.SAP_PROGRAM_ID) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const program = new anchor_1.Program(synapse_agent_sap_json_1.default, provider);
+        // Override program ID if non-default
+        if (!programId.equals(constants_1.SAP_PROGRAM_ID)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            program.programId = programId;
+        }
+        return new SapClient(program);
+    }
+    /**
+     * @name fromProgram
+     * @description Create a {@link SapClient} from an existing Anchor `Program`
+     * instance. Useful when the caller already has a configured program or
+     * needs full control over IDL resolution.
+     *
+     * @param program - A pre-built Anchor `Program` targeting the SAP program.
+     * @returns A fully-initialised `SapClient` wrapping the supplied program.
+     *
+     * @category Core
+     * @since v0.1.0
+     * @see {@link SapClient.from} for the convenience factory that auto-loads the IDL.
+     *
+     * @example
+     * ```ts
+     * import { Program } from "@coral-xyz/anchor";
+     * import { SapClient } from "@synapse-sap/sdk";
+     *
+     * const program = new Program(idl, provider);
+     * const client = SapClient.fromProgram(program);
+     * ```
+     */
+    static fromProgram(program) {
+        return new SapClient(program);
+    }
+    // ═════════════════════════════════════════════
+    //  Module Accessors (lazy singletons)
+    // ═════════════════════════════════════════════
+    /**
+     * @name agent
+     * @description Agent lifecycle: register, update, deactivate, close, and
+     * query agent metrics on-chain.
+     * @returns {AgentModule} The lazily-instantiated `AgentModule` singleton.
+     * @category Modules
+     * @since v0.1.0
+     * @see {@link AgentModule}
+     */
+    get agent() {
+        return (this.#agent ??= new agent_1.AgentModule(this.program));
+    }
+    /**
+     * @name feedback
+     * @description Trustless reputation: give, update, revoke, and close
+     * on-chain feedback entries for agents.
+     * @returns {FeedbackModule} The lazily-instantiated `FeedbackModule` singleton.
+     * @category Modules
+     * @since v0.1.0
+     * @see {@link FeedbackModule}
+     */
+    get feedback() {
+        return (this.#feedback ??= new feedback_1.FeedbackModule(this.program));
+    }
+    /**
+     * @name indexing
+     * @description Scalable discovery: capability, protocol, and tool-category
+     * on-chain indexes for agent search.
+     * @returns {IndexingModule} The lazily-instantiated `IndexingModule` singleton.
+     * @category Modules
+     * @since v0.1.0
+     * @see {@link IndexingModule}
+     */
+    get indexing() {
+        return (this.#indexing ??= new indexing_1.IndexingModule(this.program));
+    }
+    /**
+     * @name tools
+     * @description Tool schema registry: publish, inscribe, update, and close
+     * on-chain tool definitions.
+     * @returns {ToolsModule} The lazily-instantiated `ToolsModule` singleton.
+     * @category Modules
+     * @since v0.1.0
+     * @see {@link ToolsModule}
+     */
+    get tools() {
+        return (this.#tools ??= new tools_1.ToolsModule(this.program));
+    }
+    /**
+     * @name vault
+     * @description Encrypted memory vault: initialise vaults, manage sessions,
+     * inscribe data, and delegate access.
+     * @returns {VaultModule} The lazily-instantiated `VaultModule` singleton.
+     * @category Modules
+     * @since v0.1.0
+     * @see {@link VaultModule}
+     */
+    get vault() {
+        return (this.#vault ??= new vault_1.VaultModule(this.program));
+    }
+    /**
+     * @name escrow
+     * @description x402 escrow settlement: create escrow accounts, deposit
+     * funds, settle payments, and withdraw balances.
+     * @returns {EscrowModule} The lazily-instantiated `EscrowModule` singleton.
+     * @category Modules
+     * @since v0.1.0
+     * @see {@link EscrowModule}
+     */
+    get escrow() {
+        return (this.#escrow ??= new escrow_1.EscrowModule(this.program));
+    }
+    /**
+     * @name attestation
+     * @description Web of trust: create, revoke, and close on-chain
+     * attestations between agents.
+     * @returns {AttestationModule} The lazily-instantiated `AttestationModule` singleton.
+     * @category Modules
+     * @since v0.1.0
+     * @see {@link AttestationModule}
+     */
+    get attestation() {
+        return (this.#attestation ??= new attestation_1.AttestationModule(this.program));
+    }
+    /**
+     * @name ledger
+     * @description Unified on-chain memory: initialise ledger accounts, write
+     * entries, seal pages, and close ledgers.
+     * @returns {LedgerModule} The lazily-instantiated `LedgerModule` singleton.
+     * @category Modules
+     * @since v0.1.0
+     * @see {@link LedgerModule}
+     */
+    get ledger() {
+        return (this.#ledger ??= new ledger_1.LedgerModule(this.program));
+    }
+    /**
+     * @name events
+     * @description Decode SAP protocol events from on-chain transaction logs.
+     * @returns {EventParser} The lazily-instantiated `EventParser` singleton.
+     * @category Modules
+     * @since v0.1.0
+     * @see {@link EventParser}
+     */
+    get events() {
+        return (this.#events ??= new events_1.EventParser(this.program));
+    }
+    // ═════════════════════════════════════════════
+    //  Registry Accessors (high-level abstractions)
+    // ═════════════════════════════════════════════
+    /**
+     * @name discovery
+     * @description Agent & tool discovery across the SAP network.
+     * Provides high-level queries for locating agents by capability,
+     * protocol, or wallet address.
+     *
+     * @returns {DiscoveryRegistry} The lazily-instantiated `DiscoveryRegistry` singleton.
+     * @category Registries
+     * @since v0.1.0
+     * @see {@link DiscoveryRegistry}
+     *
+     * @example
+     * ```ts
+     * const agents = await client.discovery.findAgentsByProtocol("jupiter");
+     * const profile = await client.discovery.getAgentProfile(wallet);
+     * ```
+     */
+    get discovery() {
+        return (this.#discovery ??= new discovery_1.DiscoveryRegistry(this.program));
+    }
+    /**
+     * @name x402
+     * @description x402 micropayment lifecycle — pricing, escrow, headers,
+     * and settlement. Orchestrates the full pay-per-call flow between
+     * consumer and agent.
+     *
+     * @returns {X402Registry} The lazily-instantiated `X402Registry` singleton.
+     * @category Registries
+     * @since v0.1.0
+     * @see {@link X402Registry}
+     *
+     * @example
+     * ```ts
+     * const ctx = await client.x402.preparePayment(agentWallet, { ... });
+     * const headers = client.x402.buildPaymentHeaders(ctx);
+     * const receipt = await client.x402.settle(depositor, 5, serviceData);
+     * ```
+     */
+    get x402() {
+        return (this.#x402 ??= new x402_1.X402Registry(this.program));
+    }
+    /**
+     * @name session
+     * @description Unified memory session lifecycle — vault, session, and
+     * ledger management. Provides a single interface for starting
+     * conversations, writing messages, and reading back history.
+     *
+     * @returns {SessionManager} The lazily-instantiated `SessionManager` singleton.
+     * @category Registries
+     * @since v0.1.0
+     * @see {@link SessionManager}
+     *
+     * @example
+     * ```ts
+     * const ctx = await client.session.start("conversation-123");
+     * await client.session.write(ctx, "Hello from agent");
+     * const msgs = await client.session.readLatest(ctx);
+     * ```
+     */
+    get session() {
+        return (this.#session ??= new session_1.SessionManager(this.program));
+    }
+    /**
+     * @name builder
+     * @description Fluent agent registration builder.
+     * Returns a **new** `AgentBuilder` on every access — use for one-shot
+     * registration flows. Chain configuration calls and finalise with
+     * `.register()`.
+     *
+     * @returns {AgentBuilder} A fresh `AgentBuilder` instance.
+     * @category Registries
+     * @since v0.1.0
+     * @see {@link AgentBuilder}
+     *
+     * @example
+     * ```ts
+     * await client.builder
+     *   .agent("SwapBot")
+     *   .description("AI-powered swap agent")
+     *   .x402Endpoint("https://api.example.com/x402")
+     *   .addCapability("jupiter:swap", { protocol: "jupiter" })
+     *   .addPricingTier({ tierId: "standard", pricePerCall: 1000, rateLimit: 60 })
+     *   .register();
+     * ```
+     */
+    get builder() {
+        return new builder_1.AgentBuilder(this.program);
+    }
+}
+exports.SapClient = SapClient;
+//# sourceMappingURL=client.js.map

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

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