@oobe-protocol-labs/synapse-sap-sdk 0.14.0 → 0.15.0

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

@@ -0,0 +1,171 @@
+/**
+ * @module plugin
+ * @description SynapsePlugin adapter for SAP v2.
+ *
+ * Exposes 52 tools across 8 on-chain protocol domains as a drop-in
+ * `SynapsePlugin` for `SynapseAgentKit`:
+ *
+ * ```ts
+ * import { SynapseAgentKit } from '@oobe-protocol-labs/synapse-client-sdk/ai/plugins';
+ * import { createSAPPlugin } from '@synapse-sap/sdk/plugin';
+ *
+ * const sapPlugin = createSAPPlugin({ provider });
+ * const kit = new SynapseAgentKit({ rpcUrl })
+ *   .use(sapPlugin);
+ *
+ * const tools = kit.getTools();   // → StructuredTool[] (LangChain)
+ * ```
+ *
+ * Architecture:
+ *   1. Schemas (Zod) → runtime validation + LLM-friendly descriptions
+ *   2. Protocols → 8 domain method registries (agent, feedback, …)
+ *   3. Executor → dispatches tool calls to SapClient module methods
+ *   4. Serialization → PublicKey↔string, BN↔string bridging
+ *
+ * @category Plugin
+ * @since v0.1.0
+ */
+import { type AnchorProvider } from "@coral-xyz/anchor";
+import { PublicKey } from "@solana/web3.js";
+import { type PluginProtocol, type ProtocolMethod } from "./protocols";
+/**
+ * Plugin metadata exposed via {@link SynapsePlugin.meta}.
+ *
+ * @interface PluginMeta
+ * @name PluginMeta
+ * @description Describes a SynapsePlugin’s identity, version, and
+ *   discovery tags for the SynapseAgentKit plugin registry.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export interface PluginMeta {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    readonly tags: readonly string[];
+}
+/**
+ * Context injected by SynapseAgentKit during `install()`.
+ *
+ * @interface PluginContext
+ * @name PluginContext
+ * @description Provides the RPC transport and original AgentKit configuration
+ *   to the plugin at installation time.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export interface PluginContext {
+    /** The SynapseClient providing RPC transport. */
+    readonly client: {
+        readonly transport: unknown;
+    };
+    /** Original AgentKitConfig. */
+    readonly config: Record<string, unknown>;
+}
+/**
+ * Result of `install()` containing the tool executor and optional teardown.
+ *
+ * @interface PluginInstallResult
+ * @name PluginInstallResult
+ * @description Returned by {@link SynapsePlugin.install}. The `executor`
+ *   dispatches incoming tool calls to the correct SapClient module method.
+ *   The optional `teardown` callback is invoked on `kit.destroy()`.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export interface PluginInstallResult {
+    /** Main executor dispatching method calls. */
+    executor: (method: ProtocolMethod, input: unknown) => Promise<unknown>;
+    /** Optional teardown for cleanup on `kit.destroy()`. */
+    teardown?: () => Promise<void>;
+}
+/**
+ * The SynapsePlugin interface (duck-typed for zero external deps).
+ *
+ * @interface SynapsePlugin
+ * @name SynapsePlugin
+ * @description Core contract for SynapseAgentKit plugins. Provides metadata,
+ *   protocol definitions, and an `install()` entry point that yields
+ *   a tool executor.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export interface SynapsePlugin {
+    readonly meta: PluginMeta;
+    readonly protocols: readonly PluginProtocol[];
+    install(context: PluginContext): PluginInstallResult;
+}
+/**
+ * Configuration for the SAP plugin.
+ *
+ * @interface SAPPluginConfig
+ * @name SAPPluginConfig
+ * @description Options passed to {@link createSAPPlugin} to instantiate
+ *   the SAP v2 plugin with an Anchor provider and optional program ID override.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export interface SAPPluginConfig {
+    /**
+     * Anchor provider with wallet signer.
+     * Required for all write operations (transactions).
+     */
+    readonly provider: AnchorProvider;
+    /**
+     * Override the SAP program ID.
+     * Defaults to the canonical program ID from constants.
+     */
+    readonly programId?: PublicKey;
+}
+/**
+ * Create a SynapsePlugin for SAP v2.
+ *
+ * @name createSAPPlugin
+ * @description Factory function that returns a fully configured
+ *   {@link SynapsePlugin} exposing 52 tools across 8 on-chain
+ *   protocol domains. The plugin can be installed into a
+ *   `SynapseAgentKit` instance or used standalone.
+ * @param config - Plugin configuration with Anchor provider and optional program ID
+ * @returns A configured {@link SynapsePlugin} instance
+ * @category Plugin
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { createSAPPlugin } from '@synapse-sap/sdk/plugin';
+ *
+ * const sapPlugin = createSAPPlugin({ provider });
+ *
+ * // Use with SynapseAgentKit:
+ * kit.use(sapPlugin);
+ *
+ * // Or standalone:
+ * const executor = sapPlugin.install({ client, config: {} }).executor;
+ * await executor(someMethod, someInput);
+ * ```
+ */
+export declare function createSAPPlugin(config: SAPPluginConfig): SynapsePlugin;
+/**
+ * Pre-built plugin object for static use patterns.
+ *
+ * @name SAPPlugin
+ * @description Convenience namespace exposing a `configure` method
+ *   that delegates to {@link createSAPPlugin}. Useful for concise
+ *   one-liner instantiation.
+ * @category Plugin
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { SAPPlugin } from '@synapse-sap/sdk/plugin';
+ *
+ * const plugin = SAPPlugin.configure({ provider });
+ * kit.use(plugin);
+ * ```
+ */
+export declare const SAPPlugin: {
+    /** Create a configured SynapsePlugin from an AnchorProvider. */
+    readonly configure: typeof createSAPPlugin;
+};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugin/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAoBrB;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;KAC7B,CAAC;IACF,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IAC9C,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,mBAAmB,CAAC;CACtD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AA46BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAgCtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,SAAS;IACpB,gEAAgE;;CAExD,CAAC"}

package/dist/types/plugin/protocols.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @module plugin/protocols
+ * @description Protocol definitions + method registries for the SAP v2 plugin.
+ *
+ * Each protocol maps 1:1 to a SAP SDK domain module.
+ * Methods carry Zod-typed input/output + LLM-friendly descriptions.
+ *
+ * Follows the `SynapsePlugin.protocols` contract exactly.
+ *
+ * @category Plugin
+ * @since v0.1.0
+ */
+import type { z } from "zod";
+/**
+ * A single tool method exposed by a protocol.
+ *
+ * @interface ProtocolMethod
+ * @name ProtocolMethod
+ * @description Defines a callable tool within a SAP protocol domain,
+ *   including its name, LLM-friendly description, Zod input/output schemas,
+ *   and parent protocol identifier.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export interface ProtocolMethod {
+    readonly name: string;
+    readonly description: string;
+    readonly input: z.ZodTypeAny;
+    readonly output: z.ZodTypeAny;
+    readonly protocol: string;
+}
+/**
+ * A protocol group containing typed methods.
+ *
+ * @interface PluginProtocol
+ * @name PluginProtocol
+ * @description Groups related tool methods under a named protocol domain
+ *   (e.g. `"sap-agent"`, `"sap-escrow"`). Each protocol maps 1:1 to a
+ *   SapClient domain module.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export interface PluginProtocol {
+    readonly id: string;
+    readonly name: string;
+    readonly methods: ProtocolMethod[];
+    readonly requiresClient: boolean;
+}
+/**
+ * SAP Agent Identity protocol — 8 tools for on-chain agent registration,
+ * updates, activation lifecycle, call reporting, and reputation metrics.
+ *
+ * @name sapAgentProtocol
+ * @description Covers `registerAgent`, `updateAgent`, `deactivateAgent`,
+ *   `reactivateAgent`, `reportCalls`, `updateReputation`, `fetchAgent`,
+ *   and `fetchGlobalRegistry`.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export declare const sapAgentProtocol: PluginProtocol;
+/**
+ * SAP Trustless Reputation protocol — 4 tools for on-chain feedback
+ * (give, update, revoke, fetch) tied to agent identity PDAs.
+ *
+ * @name sapFeedbackProtocol
+ * @description Covers `giveFeedback`, `updateFeedback`, `revokeFeedback`,
+ *   and `fetchFeedback`.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export declare const sapFeedbackProtocol: PluginProtocol;
+/**
+ * SAP Web of Trust protocol — 3 tools for creating, revoking, and
+ * fetching on-chain attestations between agents.
+ *
+ * @name sapAttestationProtocol
+ * @description Covers `createAttestation`, `revokeAttestation`,
+ *   and `fetchAttestation`.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export declare const sapAttestationProtocol: PluginProtocol;
+/**
+ * SAP x402 Escrow protocol — 6 tools for creating, depositing into,
+ * settling, withdrawing from, batch-settling, and fetching escrow accounts.
+ *
+ * @name sapEscrowProtocol
+ * @description Covers `createEscrow`, `depositEscrow`, `settleEscrow`,
+ *   `withdrawEscrow`, `batchSettle`, and `fetchEscrow`.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export declare const sapEscrowProtocol: PluginProtocol;
+/**
+ * SAP Tool Registry protocol — 7 tools for publishing, updating,
+ * deactivating/reactivating tool descriptors and reporting invocations.
+ *
+ * @name sapToolsProtocol
+ * @description Covers `publishToolByName`, `inscribeToolSchema`, `updateTool`,
+ *   `deactivateTool`, `reactivateTool`, `reportInvocations`, and `fetchTool`.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export declare const sapToolsProtocol: PluginProtocol;
+/**
+ * SAP Encrypted Memory Vault protocol — 10 tools for vault lifecycle,
+ * session management, encrypted memory inscription, nonce rotation,
+ * and delegate authorization.
+ *
+ * @name sapVaultProtocol
+ * @description Covers `initVault`, `openSession`, `inscribeMemory`,
+ *   `closeSession`, `closeVault`, `rotateNonce`, `addDelegate`,
+ *   `revokeDelegate`, `fetchVault`, and `fetchSession`.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export declare const sapVaultProtocol: PluginProtocol;
+/**
+ * SAP Discovery Indexes protocol — 8 tools for creating and managing
+ * capability and protocol indexes used for agent discovery.
+ *
+ * @name sapIndexingProtocol
+ * @description Covers `initCapabilityIndex`, `addToCapabilityIndex`,
+ *   `removeFromCapabilityIndex`, `initProtocolIndex`, `addToProtocolIndex`,
+ *   `removeFromProtocolIndex`, `fetchCapabilityIndex`, and `fetchProtocolIndex`.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export declare const sapIndexingProtocol: PluginProtocol;
+/**
+ * SAP Unified Memory Ledger protocol — 6 tools for initializing,
+ * writing to, sealing, closing, and fetching ring-buffer ledgers
+ * and their sealed archive pages.
+ *
+ * @name sapLedgerProtocol
+ * @description Covers `initLedger`, `writeLedger`, `sealLedger`,
+ *   `closeLedger`, `fetchLedger`, and `fetchLedgerPage`.
+ * @category Plugin
+ * @since v0.1.0
+ */
+export declare const sapLedgerProtocol: PluginProtocol;
+/**
+ * Ordered array of all 8 SAP v2 plugin protocols.
+ *
+ * @name SAP_PROTOCOLS
+ * @description Contains agent, feedback, attestation, escrow, tools,
+ *   vault, indexing, and ledger protocols (52 tools total).
+ * @category Plugin
+ * @since v0.1.0
+ */
+export declare const SAP_PROTOCOLS: readonly PluginProtocol[];
+//# sourceMappingURL=protocols.d.ts.map

package/dist/types/plugin/protocols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocols.d.ts","sourceRoot":"","sources":["../../../src/plugin/protocols.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiBH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC;AAwCD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,cAoB9B,CAAC;AAMF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,cAcjC,CAAC;AAMF;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,cAYpC,CAAC;AAMF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,EAAE,cAkB/B,CAAC;AAMF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,cAkB9B,CAAC;AAMF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,EAAE,cAyB9B,CAAC;AAMF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,EAAE,cAsBjC,CAAC;AAMF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,cAkB/B,CAAC;AAMF;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EASzC,CAAC"}