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

package/dist/types/registries/discovery.d.ts

@@ -0,0 +1,333 @@
+/**
+ * @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();
+ * ```
+ */
+import type { PublicKey } from "@solana/web3.js";
+import type { SapProgram } from "../modules/base";
+import { TOOL_CATEGORY_VALUES } from "../constants";
+import type { AgentAccountData, AgentStatsData, ToolDescriptorData } from "../types";
+/**
+ * @interface DiscoveredAgent
+ * @name DiscoveredAgent
+ * @description Compact agent identity returned by discovery queries.
+ * Contains the agent PDA, optional identity data, and optional stats.
+ * Returned by {@link DiscoveryRegistry.findAgentsByCapability},
+ * {@link DiscoveryRegistry.findAgentsByProtocol}, and
+ * {@link DiscoveryRegistry.findAgentsByCapabilities}.
+ * @category Registries
+ * @since v0.1.0
+ */
+export interface DiscoveredAgent {
+    /** Agent PDA address. */
+    readonly pda: PublicKey;
+    /** Agent identity data (null if account not found). */
+    readonly identity: AgentAccountData | null;
+    /** Agent stats (null if account not found). */
+    readonly stats: AgentStatsData | null;
+}
+/**
+ * @interface AgentProfile
+ * @name AgentProfile
+ * @description Full agent profile with all discoverable data.
+ * Combines identity, stats, and computed fields into a single
+ * display-ready structure. Returned by {@link DiscoveryRegistry.getAgentProfile}.
+ * @category Registries
+ * @since v0.1.0
+ */
+export interface AgentProfile {
+    /** Agent PDA. */
+    readonly pda: PublicKey;
+    /** Agent identity (name, description, capabilities, pricing, etc.). */
+    readonly identity: AgentAccountData;
+    /** Lightweight metrics (total calls, active status). */
+    readonly stats: AgentStatsData | null;
+    /** Computed fields for display. */
+    readonly computed: {
+        /** Is the agent currently active? */
+        readonly isActive: boolean;
+        /** Total calls served (from stats or identity fallback). */
+        readonly totalCalls: string;
+        /** Reputation score (0-1000). */
+        readonly reputationScore: number;
+        /** Has x402 endpoint configured? */
+        readonly hasX402: boolean;
+        /** Number of capabilities. */
+        readonly capabilityCount: number;
+        /** Number of pricing tiers. */
+        readonly pricingTierCount: number;
+        /** Protocol list. */
+        readonly protocols: string[];
+    };
+}
+/**
+ * @interface DiscoveredTool
+ * @name DiscoveredTool
+ * @description Discovered tool with agent context.
+ * Contains the tool PDA and optional descriptor data.
+ * Returned by {@link DiscoveryRegistry.findToolsByCategory}.
+ * @category Registries
+ * @since v0.1.0
+ */
+export interface DiscoveredTool {
+    /** Tool PDA address. */
+    readonly pda: PublicKey;
+    /** Tool descriptor data (null if not found). */
+    readonly descriptor: ToolDescriptorData | null;
+}
+/**
+ * @interface NetworkOverview
+ * @name NetworkOverview
+ * @description Network-wide statistics aggregated from the GlobalRegistry account.
+ * Provides counts of agents, tools, vaults, attestations, and more.
+ * Returned by {@link DiscoveryRegistry.getNetworkOverview}.
+ * @category Registries
+ * @since v0.1.0
+ */
+export interface NetworkOverview {
+    /** Total registered agents. */
+    readonly totalAgents: string;
+    /** Currently active agents. */
+    readonly activeAgents: string;
+    /** Total feedback entries. */
+    readonly totalFeedbacks: string;
+    /** Total registered tools. */
+    readonly totalTools: number;
+    /** Total memory vaults. */
+    readonly totalVaults: number;
+    /** Total attestations. */
+    readonly totalAttestations: number;
+    /** Total capability indexes. */
+    readonly totalCapabilities: number;
+    /** Total protocol indexes. */
+    readonly totalProtocols: number;
+    /** Protocol authority. */
+    readonly authority: PublicKey;
+}
+/**
+ * @typedef {string} ToolCategoryName
+ * @name ToolCategoryName
+ * @description Tool category string literal type derived from `TOOL_CATEGORY_VALUES`.
+ * Valid values include: `"swap"`, `"data"`, `"lending"`, `"governance"`, etc.
+ * @category Registries
+ * @since v0.1.0
+ * @see {@link DiscoveryRegistry.findToolsByCategory}
+ */
+export type ToolCategoryName = keyof typeof TOOL_CATEGORY_VALUES;
+/**
+ * @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();
+ * ```
+ */
+export declare class DiscoveryRegistry {
+    private readonly program;
+    constructor(program: SapProgram);
+    /**
+     * @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");
+     * ```
+     */
+    findAgentsByCapability(capabilityId: string, opts?: {
+        hydrate?: boolean;
+    }): Promise<DiscoveredAgent[]>;
+    /**
+     * @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");
+     * ```
+     */
+    findAgentsByProtocol(protocolId: string, opts?: {
+        hydrate?: boolean;
+    }): Promise<DiscoveredAgent[]>;
+    /**
+     * @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
+     * ```
+     */
+    findToolsByCategory(category: ToolCategoryName | number, opts?: {
+        hydrate?: boolean;
+    }): Promise<DiscoveredTool[]>;
+    /**
+     * @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);
+     * ```
+     */
+    getAgentProfile(wallet: PublicKey): Promise<AgentProfile | null>;
+    /**
+     * @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
+     */
+    isAgentActive(wallet: PublicKey): Promise<boolean>;
+    /**
+     * @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
+     */
+    getNetworkOverview(): Promise<NetworkOverview>;
+    /**
+     * @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
+     */
+    findAgentsByCapabilities(capabilityIds: string[], opts?: {
+        hydrate?: boolean;
+    }): Promise<DiscoveredAgent[]>;
+    /**
+     * @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
+     */
+    getToolCategorySummary(): Promise<Array<{
+        category: string;
+        categoryNum: number;
+        toolCount: number;
+    }>>;
+    /**
+     * @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
+     */
+    private hydrateAgents;
+    /**
+     * @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
+     */
+    private hydrateTools;
+    /**
+     * @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
+     */
+    private fetch;
+    /**
+     * @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
+     */
+    private fetchNullable;
+}
+//# sourceMappingURL=discovery.d.ts.map

package/dist/types/registries/discovery.d.ts.map

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

package/dist/types/registries/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @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}
+ */
+export { DiscoveryRegistry } from "./discovery";
+export type { DiscoveredAgent, AgentProfile, DiscoveredTool, NetworkOverview, ToolCategoryName, } from "./discovery";
+export { X402Registry } from "./x402";
+export type { CostEstimate, PaymentContext, PreparePaymentOptions, X402Headers, EscrowBalance, SettlementResult, BatchSettlementResult, } from "./x402";
+export { SessionManager } from "./session";
+export type { SessionContext, WriteResult, SealResult, RingBufferEntry, SessionStatus, } from "./session";
+export { AgentBuilder } from "./builder";
+export type { CapabilityInput, PricingTierInput, ToolInput, RegisterResult, RegisterWithToolsResult, } from "./builder";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/registries/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/registries/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EACV,eAAe,EACf,YAAY,EACZ,cAAc,EACd,eAAe,EACf,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,YAAY,EACV,YAAY,EACZ,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,QAAQ,CAAC;AAEhB,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,YAAY,EACV,cAAc,EACd,WAAW,EACX,UAAU,EACV,eAAe,EACf,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,cAAc,EACd,uBAAuB,GACxB,MAAM,WAAW,CAAC"}