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

package/dist/cjs/registries/builder.js.map

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

package/dist/cjs/registries/discovery.js

@@ -0,0 +1,362 @@
+"use strict";
+/**
+ * @module registries/discovery
+ * @description High-level agent and tool discovery registry.
+ *
+ * Abstracts the raw PDA-level indexing + fetching into a single
+ * developer-friendly interface for finding agents, tools, and
+ * services across the SAP network.
+ *
+ * Use cases:
+ *   - "Find all agents that support Jupiter swaps"
+ *   - "Find all Swap tools across all agents"
+ *   - "Get the full profile of agent X (identity + stats + tools)"
+ *   - "Get network-wide statistics"
+ *
+ * @category Registries
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * const discovery = client.discovery;
+ *
+ * // Find agents that support Jupiter protocol
+ * const agents = await discovery.findAgentsByProtocol("jupiter");
+ *
+ * // Get full agent profile (identity + stats + attestations)
+ * const profile = await discovery.getAgentProfile(agentWallet);
+ *
+ * // Find all Swap tools across the network
+ * const tools = await discovery.findToolsByCategory("swap");
+ *
+ * // Network overview
+ * const stats = await discovery.getNetworkOverview();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiscoveryRegistry = void 0;
+const pda_1 = require("../pda");
+const utils_1 = require("../utils");
+const constants_1 = require("../constants");
+// ═══════════════════════════════════════════════════════════════════
+//  Discovery Registry
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name DiscoveryRegistry
+ * @description High-level agent and tool discovery registry for the SAP network.
+ *
+ * Provides a developer-friendly API for finding agents by capability,
+ * protocol, or tool category, fetching full agent profiles, and
+ * retrieving network-wide statistics.
+ *
+ * @category Registries
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * const discovery = client.discovery;
+ *
+ * // Find agents by capability
+ * const swapAgents = await discovery.findAgentsByCapability("jupiter:swap");
+ *
+ * // Get agent profile
+ * const profile = await discovery.getAgentProfile(agentWallet);
+ *
+ * // Network statistics
+ * const overview = await discovery.getNetworkOverview();
+ * ```
+ */
+class DiscoveryRegistry {
+    program;
+    constructor(program) {
+        this.program = program;
+    }
+    // ── Agent Discovery ──────────────────────────────────
+    /**
+     * @name findAgentsByCapability
+     * @description Find all agent PDAs registered for a specific capability.
+     * Hashes the capability ID with SHA-256 and looks up the capability index PDA.
+     *
+     * @param capabilityId - The capability identifier string (e.g. `"jupiter:swap"`).
+     * @param opts - Optional settings.
+     * @param opts.hydrate - If `false`, returns only PDAs without fetching identity/stats. Defaults to `true`.
+     * @returns An array of {@link DiscoveredAgent} matching the capability.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const agents = await discovery.findAgentsByCapability("jupiter:swap");
+     * ```
+     */
+    async findAgentsByCapability(capabilityId, opts) {
+        const capHash = (0, utils_1.sha256)(capabilityId);
+        const [pda] = (0, pda_1.deriveCapabilityIndex)(capHash);
+        const index = await this.fetchNullable("capabilityIndex", pda);
+        if (!index)
+            return [];
+        if (opts?.hydrate === false) {
+            return index.agents.map((agentPda) => ({
+                pda: agentPda,
+                identity: null,
+                stats: null,
+            }));
+        }
+        return this.hydrateAgents(index.agents);
+    }
+    /**
+     * @name findAgentsByProtocol
+     * @description Find all agent PDAs registered for a specific protocol.
+     * Hashes the protocol ID with SHA-256 and looks up the protocol index PDA.
+     *
+     * @param protocolId - The protocol identifier string (e.g. `"jupiter"`).
+     * @param opts - Optional settings.
+     * @param opts.hydrate - If `false`, returns only PDAs without fetching identity/stats. Defaults to `true`.
+     * @returns An array of {@link DiscoveredAgent} matching the protocol.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const agents = await discovery.findAgentsByProtocol("jupiter");
+     * ```
+     */
+    async findAgentsByProtocol(protocolId, opts) {
+        const protoHash = (0, utils_1.sha256)(protocolId);
+        const [pda] = (0, pda_1.deriveProtocolIndex)(protoHash);
+        const index = await this.fetchNullable("protocolIndex", pda);
+        if (!index)
+            return [];
+        if (opts?.hydrate === false) {
+            return index.agents.map((agentPda) => ({
+                pda: agentPda,
+                identity: null,
+                stats: null,
+            }));
+        }
+        return this.hydrateAgents(index.agents);
+    }
+    /**
+     * @name findToolsByCategory
+     * @description Find all tool PDAs registered in a specific category.
+     * Accepts either a category name string or a numeric category value.
+     *
+     * @param category - Tool category name (e.g. `"swap"`) or numeric category value.
+     * @param opts - Optional settings.
+     * @param opts.hydrate - If `false`, returns only PDAs without fetching descriptors. Defaults to `true`.
+     * @returns An array of {@link DiscoveredTool} matching the category.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const tools = await discovery.findToolsByCategory("swap");
+     * const tools = await discovery.findToolsByCategory(0); // numeric
+     * ```
+     */
+    async findToolsByCategory(category, opts) {
+        const categoryNum = typeof category === "number"
+            ? category
+            : constants_1.TOOL_CATEGORY_VALUES[category] ?? 9;
+        const [pda] = (0, pda_1.deriveToolCategoryIndex)(categoryNum);
+        const index = await this.fetchNullable("toolCategoryIndex", pda);
+        if (!index)
+            return [];
+        if (opts?.hydrate === false) {
+            return index.tools.map((toolPda) => ({
+                pda: toolPda,
+                descriptor: null,
+            }));
+        }
+        return this.hydrateTools(index.tools);
+    }
+    // ── Agent Profile ────────────────────────────────────
+    /**
+     * @name getAgentProfile
+     * @description Get the full profile of an agent by wallet address.
+     * Combines identity + stats into a single response with computed fields
+     * for easy display (active status, total calls, reputation, etc.).
+     *
+     * @param wallet - The agent owner's wallet public key.
+     * @returns The full {@link AgentProfile}, or `null` if the agent does not exist.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const profile = await discovery.getAgentProfile(agentWallet);
+     * console.log(profile.identity.name);
+     * console.log(profile.computed.isActive);
+     * console.log(profile.computed.totalCalls);
+     * ```
+     */
+    async getAgentProfile(wallet) {
+        const [agentPda] = (0, pda_1.deriveAgent)(wallet);
+        const [statsPda] = (0, pda_1.deriveAgentStats)(agentPda);
+        const [identity, stats] = await Promise.all([
+            this.fetchNullable("agentAccount", agentPda),
+            this.fetchNullable("agentStats", statsPda),
+        ]);
+        if (!identity)
+            return null;
+        const totalCallsBN = stats?.totalCallsServed ?? identity.totalCallsServed;
+        return {
+            pda: agentPda,
+            identity,
+            stats,
+            computed: {
+                isActive: identity.isActive,
+                totalCalls: totalCallsBN.toString(),
+                reputationScore: identity.reputationScore,
+                hasX402: !!identity.x402Endpoint,
+                capabilityCount: identity.capabilities.length,
+                pricingTierCount: identity.pricing.length,
+                protocols: [...identity.protocols],
+            },
+        };
+    }
+    /**
+     * @name isAgentActive
+     * @description Check if an agent exists and is currently active.
+     * Reads the agent stats account to determine active status.
+     *
+     * @param wallet - The agent owner's wallet public key.
+     * @returns `true` if the agent exists and is active, `false` otherwise.
+     * @since v0.1.0
+     */
+    async isAgentActive(wallet) {
+        const [agentPda] = (0, pda_1.deriveAgent)(wallet);
+        const [statsPda] = (0, pda_1.deriveAgentStats)(agentPda);
+        const stats = await this.fetchNullable("agentStats", statsPda);
+        return stats?.isActive ?? false;
+    }
+    // ── Network Overview ─────────────────────────────────
+    /**
+     * @name getNetworkOverview
+     * @description Get network-wide statistics from the GlobalRegistry account.
+     * Returns aggregated counts and metadata for the entire SAP network.
+     *
+     * @returns A {@link NetworkOverview} with all network-level statistics.
+     * @since v0.1.0
+     */
+    async getNetworkOverview() {
+        const [pda] = (0, pda_1.deriveGlobalRegistry)();
+        const reg = await this.fetch("globalRegistry", pda);
+        return {
+            totalAgents: reg.totalAgents.toString(),
+            activeAgents: reg.activeAgents.toString(),
+            totalFeedbacks: reg.totalFeedbacks.toString(),
+            totalTools: reg.totalTools,
+            totalVaults: reg.totalVaults,
+            totalAttestations: reg.totalAttestations,
+            totalCapabilities: reg.totalCapabilities,
+            totalProtocols: reg.totalProtocols,
+            authority: reg.authority,
+        };
+    }
+    // ── Multi-category Search ────────────────────────────
+    /**
+     * @name findAgentsByCapabilities
+     * @description Search across multiple capability IDs at once.
+     * Returns deduplicated agent PDAs aggregated from all matching capability indexes.
+     *
+     * @param capabilityIds - Array of capability identifier strings to search.
+     * @param opts - Optional settings.
+     * @param opts.hydrate - If `false`, returns only PDAs without fetching identity/stats. Defaults to `true`.
+     * @returns A deduplicated array of {@link DiscoveredAgent} matching any of the capabilities.
+     * @since v0.1.0
+     */
+    async findAgentsByCapabilities(capabilityIds, opts) {
+        const seen = new Set();
+        const results = [];
+        for (const capId of capabilityIds) {
+            const agents = await this.findAgentsByCapability(capId, opts);
+            for (const agent of agents) {
+                const key = agent.pda.toBase58();
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    results.push(agent);
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * @name getToolCategorySummary
+     * @description Search across all 10 tool categories and return a summary.
+     * Lists each category with its name, numeric value, and tool count.
+     *
+     * @returns An array of category summary objects with `category`, `categoryNum`, and `toolCount`.
+     * @since v0.1.0
+     */
+    async getToolCategorySummary() {
+        const categories = Object.entries(constants_1.TOOL_CATEGORY_VALUES);
+        const results = [];
+        for (const [name, num] of categories) {
+            const [pda] = (0, pda_1.deriveToolCategoryIndex)(num);
+            const index = await this.fetchNullable("toolCategoryIndex", pda);
+            results.push({
+                category: name,
+                categoryNum: num,
+                toolCount: index?.tools.length ?? 0,
+            });
+        }
+        return results;
+    }
+    // ── Internals ────────────────────────────────────────
+    /**
+     * @name hydrateAgents
+     * @description Hydrate an array of agent PDAs by fetching identity and stats data.
+     * @param agentPdas - Array of agent PDA public keys.
+     * @returns An array of {@link DiscoveredAgent} with populated identity and stats fields.
+     * @private
+     */
+    async hydrateAgents(agentPdas) {
+        return Promise.all(agentPdas.map(async (agentPda) => {
+            const [statsPda] = (0, pda_1.deriveAgentStats)(agentPda);
+            const [identity, stats] = await Promise.all([
+                this.fetchNullable("agentAccount", agentPda),
+                this.fetchNullable("agentStats", statsPda),
+            ]);
+            return { pda: agentPda, identity, stats };
+        }));
+    }
+    /**
+     * @name hydrateTools
+     * @description Hydrate an array of tool PDAs by fetching descriptor data.
+     * @param toolPdas - Array of tool PDA public keys.
+     * @returns An array of {@link DiscoveredTool} with populated descriptor fields.
+     * @private
+     */
+    async hydrateTools(toolPdas) {
+        return Promise.all(toolPdas.map(async (toolPda) => {
+            const descriptor = await this.fetchNullable("toolDescriptor", toolPda);
+            return { pda: toolPda, descriptor };
+        }));
+    }
+    /**
+     * @name fetch
+     * @description Fetch an on-chain account by name and PDA. Throws if not found.
+     * @param name - Anchor account discriminator name.
+     * @param pda - Account public key to fetch.
+     * @returns The deserialized account data.
+     * @throws If the account does not exist.
+     * @private
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetch(name, pda) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+        return this.program.account[name].fetch(pda);
+    }
+    /**
+     * @name fetchNullable
+     * @description Fetch an on-chain account by name and PDA. Returns `null` if not found.
+     * @param name - Anchor account discriminator name.
+     * @param pda - Account public key to fetch.
+     * @returns The deserialized account data, or `null` if the account does not exist.
+     * @private
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetchNullable(name, pda) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+        return this.program.account[name].fetchNullable(pda);
+    }
+}
+exports.DiscoveryRegistry = DiscoveryRegistry;
+//# sourceMappingURL=discovery.js.map

package/dist/cjs/registries/discovery.js.map

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

package/dist/cjs/registries/index.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * @module registries
+ * @description High-level registry barrel export.
+ *
+ * Registries are developer-facing abstractions that combine
+ * multiple raw SDK modules into cohesive, workflow-oriented APIs:
+ *
+ *   - **DiscoveryRegistry** — Find agents, tools, and services across
+ *     the SAP network by capability, protocol, or tool category.
+ *
+ *   - **X402Registry** — Full x402 micropayment lifecycle: pricing
+ *     estimation, escrow management, HTTP header generation,
+ *     settlement, and balance monitoring.
+ *
+ *   - **SessionManager** — Unified memory session lifecycle: create
+ *     vault, open session, write data, read ring buffer, seal
+ *     archives, and close sessions in a single API.
+ *
+ *   - **AgentBuilder** — Fluent builder for agent registration with
+ *     capabilities, pricing tiers, tools, and x402 endpoint config.
+ *
+ * All registries are accessible as lazy singletons on `SapClient`:
+ *
+ * ```ts
+ * const client = SapClient.from(provider);
+ *
+ * client.discovery    // → DiscoveryRegistry
+ * client.x402         // → X402Registry
+ * client.session      // → SessionManager
+ * client.builder      // → AgentBuilder (fresh instance each access)
+ * ```
+ *
+ * @category Registries
+ * @since v0.1.0
+ * @see {@link DiscoveryRegistry}
+ * @see {@link X402Registry}
+ * @see {@link SessionManager}
+ * @see {@link AgentBuilder}
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentBuilder = exports.SessionManager = exports.X402Registry = exports.DiscoveryRegistry = void 0;
+var discovery_1 = require("./discovery");
+Object.defineProperty(exports, "DiscoveryRegistry", { enumerable: true, get: function () { return discovery_1.DiscoveryRegistry; } });
+var x402_1 = require("./x402");
+Object.defineProperty(exports, "X402Registry", { enumerable: true, get: function () { return x402_1.X402Registry; } });
+var session_1 = require("./session");
+Object.defineProperty(exports, "SessionManager", { enumerable: true, get: function () { return session_1.SessionManager; } });
+var builder_1 = require("./builder");
+Object.defineProperty(exports, "AgentBuilder", { enumerable: true, get: function () { return builder_1.AgentBuilder; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/registries/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;;;AAEH,yCAAgD;AAAvC,8GAAA,iBAAiB,OAAA;AAS1B,+BAAsC;AAA7B,oGAAA,YAAY,OAAA;AAWrB,qCAA2C;AAAlC,yGAAA,cAAc,OAAA;AASvB,qCAAyC;AAAhC,uGAAA,YAAY,OAAA"}