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

package/dist/esm/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/esm/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;AAqBrB;;;;;;;;;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;AA89BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAgCtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,SAAS;IACpB,gEAAgE;;CAExD,CAAC"}