@oobe-protocol-labs/synapse-client-sdk 2.0.0 → 2.0.5

package/dist/esm/ai/sap/provider.d.ts

@@ -0,0 +1,180 @@
+/**
+ * @module ai/sap/provider
+ * @description HMR-safe factories and React integration blueprints for SAP.
+ *
+ * Provides:
+ *  - **`createSapProvider`** — HMR-safe singleton factory for `SynapseAnchorSap`
+ *    (follows the same pattern as `createSynapseProvider` from `@oobe-protocol-labs/synapse-client-sdk/next`)
+ *  - **`createSapContextBlueprint`** — Returns a typed React context + hook
+ *    factory that consumers wire into their own Next.js providers
+ *
+ * The SDK does **not** depend on React — these utilities produce typed
+ * blueprints that consumers implement with their own React installation.
+ *
+ * @since 2.1.0
+ */
+import { type SingletonOptions } from '../../utils/helpers';
+import { SynapseAnchorSap } from './client';
+import type { SapBridgeConfig, SapProviderConfig, SapWallet, SapContextValue } from './types';
+/**
+ * Create an HMR-safe `SynapseAnchorSap` singleton factory.
+ *
+ * Stores the instance on `globalThis` to survive hot-module reloads
+ * in Next.js development. Identical in spirit to
+ * `createSynapseProvider` and `createGatewayProvider`.
+ *
+ * **Server-side only** — requires a static wallet (e.g., a Keypair
+ * loaded from an environment variable). For client-side usage with
+ * wallet-adapter, use {@link createSapContextBlueprint} instead.
+ *
+ * @param wallet - Server wallet with signing capability
+ * @param config - Network, region, and SAP configuration
+ * @param opts   - Singleton options (version for cache busting)
+ * @returns A zero-arg getter that always returns the same instance
+ *
+ * @example
+ * ```ts
+ * // lib/sap.ts (Next.js server)
+ * import { createSapProvider } from '@oobe-protocol-labs/synapse-client-sdk/ai/sap';
+ * import { loadWallet } from './wallet';
+ *
+ * export const getSap = createSapProvider(loadWallet(), {
+ *   network: SynapseNetwork.Mainnet,
+ *   commitment: 'confirmed',
+ * });
+ *
+ * // API route
+ * export async function GET() {
+ *   const sap = getSap();
+ *   const agent = await sap.agent.fetch();
+ *   return Response.json(agent);
+ * }
+ * ```
+ */
+export declare function createSapProvider(wallet: SapWallet, config?: SapProviderConfig, opts?: SingletonOptions): () => SynapseAnchorSap;
+/**
+ * Blueprint result returned by {@link createSapContextBlueprint}.
+ *
+ * Contains everything needed to wire SAP into a React tree,
+ * without importing React in the SDK itself.
+ */
+export interface SapContextBlueprint {
+    /**
+     * The default context value (disconnected state).
+     * Use as the initial value for `React.createContext<SapContextValue>()`.
+     */
+    defaultValue: SapContextValue<SynapseAnchorSap>;
+    /**
+     * Create a state manager for the SAP provider.
+     *
+     * Call this inside your provider component to get `connect`,
+     * `disconnect`, and the current context value.
+     *
+     * @returns Object with `{ value, connect, disconnect }` — pass
+     * `value` to your context provider.
+     */
+    createManager(): SapStateManager;
+}
+/**
+ * State manager returned by `SapContextBlueprint.createManager()`.
+ *
+ * This is a plain-object state machine — no React hooks inside.
+ * Use it in a `useEffect` + `useState` pattern in your provider.
+ */
+export interface SapStateManager {
+    /** Connect to SAP with the given wallet. Creates a SynapseAnchorSap. */
+    connect(wallet: SapWallet): void;
+    /** Disconnect and clear the client. */
+    disconnect(): void;
+    /** Get the current context value (snapshot). */
+    getValue(): SapContextValue<SynapseAnchorSap>;
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Create a React context blueprint for SAP integration.
+ *
+ * Returns a blueprint object with the default context value and a
+ * state manager factory. The consumer wires these into their own
+ * React provider using `createContext`, `useState`, and `useEffect`.
+ *
+ * This approach keeps the SDK free of React dependencies while
+ * providing full type safety and a clear integration pattern.
+ *
+ * @param config - SAP bridge configuration (network, region, etc.)
+ * @returns Blueprint with default value and manager factory
+ *
+ * @example Next.js App Router provider
+ * ```tsx
+ * // app/providers/sap-provider.tsx
+ * 'use client';
+ *
+ * import { createContext, useContext, useState, useCallback, useMemo, type ReactNode } from 'react';
+ * import { useWallet } from '@solana/wallet-adapter-react';
+ * import {
+ *   createSapContextBlueprint,
+ *   type SapContextValue,
+ *   type SynapseAnchorSap,
+ * } from '@oobe-protocol-labs/synapse-client-sdk/ai/sap';
+ * import { SynapseNetwork } from '@oobe-protocol-labs/synapse-client-sdk/utils';
+ *
+ * const blueprint = createSapContextBlueprint({ network: SynapseNetwork.Mainnet });
+ * const SapContext = createContext<SapContextValue<SynapseAnchorSap>>(blueprint.defaultValue);
+ *
+ * export function SapProvider({ children }: { children: ReactNode }) {
+ *   const { wallet, connected } = useWallet();
+ *   const [client, setClient] = useState<SynapseAnchorSap | null>(null);
+ *   const [loading, setLoading] = useState(false);
+ *   const [error, setError] = useState<Error | null>(null);
+ *
+ *   const connect = useCallback(async (w: any) => {
+ *     setLoading(true);
+ *     setError(null);
+ *     try {
+ *       const mgr = blueprint.createManager();
+ *       mgr.connect(w);
+ *       setClient(mgr.getValue().client);
+ *     } catch (e) {
+ *       setError(e instanceof Error ? e : new Error(String(e)));
+ *     } finally {
+ *       setLoading(false);
+ *     }
+ *   }, []);
+ *
+ *   const disconnect = useCallback(() => {
+ *     setClient(null);
+ *     setError(null);
+ *   }, []);
+ *
+ *   const value = useMemo(() => ({
+ *     client,
+ *     loading,
+ *     error,
+ *     connect,
+ *     disconnect,
+ *   }), [client, loading, error, connect, disconnect]);
+ *
+ *   return <SapContext.Provider value={value}>{children}</SapContext.Provider>;
+ * }
+ *
+ * export const useSap = () => useContext(SapContext);
+ * ```
+ *
+ * @example Using the hook
+ * ```tsx
+ * 'use client';
+ * import { useSap } from './sap-provider';
+ *
+ * export function AgentDashboard() {
+ *   const { client, loading, error } = useSap();
+ *
+ *   if (!client) return <p>Connect your wallet to use SAP</p>;
+ *   if (loading) return <p>Initializing SAP...</p>;
+ *   if (error) return <p>Error: {error.message}</p>;
+ *
+ *   return <AgentPanel sap={client} />;
+ * }
+ * ```
+ */
+export declare function createSapContextBlueprint(config?: Omit<SapBridgeConfig, 'wallet'>): SapContextBlueprint;
+//# sourceMappingURL=provider.d.ts.map

package/dist/esm/ai/sap/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../../src/ai/sap/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,eAAe,EAChB,MAAM,SAAS,CAAC;AAMjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,IAAI,CAAC,EAAE,gBAAgB,GACtB,MAAM,gBAAgB,CAUxB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,YAAY,EAAE,eAAe,CAAC,gBAAgB,CAAC,CAAC;IAEhD;;;;;;;;OAQG;IACH,aAAa,IAAI,eAAe,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IACjC,uCAAuC;IACvC,UAAU,IAAI,IAAI,CAAC;IACnB,gDAAgD;IAChD,QAAQ,IAAI,eAAe,CAAC,gBAAgB,CAAC,CAAC;IAC9C,mEAAmE;IACnE,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,GACvC,mBAAmB,CAwErB"}

package/dist/esm/ai/sap/provider.js

@@ -0,0 +1,215 @@
+/**
+ * @module ai/sap/provider
+ * @description HMR-safe factories and React integration blueprints for SAP.
+ *
+ * Provides:
+ *  - **`createSapProvider`** — HMR-safe singleton factory for `SynapseAnchorSap`
+ *    (follows the same pattern as `createSynapseProvider` from `@oobe-protocol-labs/synapse-client-sdk/next`)
+ *  - **`createSapContextBlueprint`** — Returns a typed React context + hook
+ *    factory that consumers wire into their own Next.js providers
+ *
+ * The SDK does **not** depend on React — these utilities produce typed
+ * blueprints that consumers implement with their own React installation.
+ *
+ * @since 2.1.0
+ */
+import { createSingleton } from '../../utils/helpers.js';
+import { SynapseAnchorSap } from './client.js';
+/* ═══════════════════════════════════════════════════════════════
+ *  createSapProvider — HMR-safe singleton (server-side / Node.js)
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * Create an HMR-safe `SynapseAnchorSap` singleton factory.
+ *
+ * Stores the instance on `globalThis` to survive hot-module reloads
+ * in Next.js development. Identical in spirit to
+ * `createSynapseProvider` and `createGatewayProvider`.
+ *
+ * **Server-side only** — requires a static wallet (e.g., a Keypair
+ * loaded from an environment variable). For client-side usage with
+ * wallet-adapter, use {@link createSapContextBlueprint} instead.
+ *
+ * @param wallet - Server wallet with signing capability
+ * @param config - Network, region, and SAP configuration
+ * @param opts   - Singleton options (version for cache busting)
+ * @returns A zero-arg getter that always returns the same instance
+ *
+ * @example
+ * ```ts
+ * // lib/sap.ts (Next.js server)
+ * import { createSapProvider } from '@oobe-protocol-labs/synapse-client-sdk/ai/sap';
+ * import { loadWallet } from './wallet.js';
+ *
+ * export const getSap = createSapProvider(loadWallet(), {
+ *   network: SynapseNetwork.Mainnet,
+ *   commitment: 'confirmed',
+ * });
+ *
+ * // API route
+ * export async function GET() {
+ *   const sap = getSap();
+ *   const agent = await sap.agent.fetch();
+ *   return Response.json(agent);
+ * }
+ * ```
+ */
+export function createSapProvider(wallet, config, opts) {
+    const singletonOpts = {
+        ...opts,
+        ...(config?.version != null ? { version: Number(config.version) || 0 } : {}),
+    };
+    return createSingleton('__synapse_sap__', () => SynapseAnchorSap.create({ wallet, ...config }), singletonOpts);
+}
+/**
+ * Create a React context blueprint for SAP integration.
+ *
+ * Returns a blueprint object with the default context value and a
+ * state manager factory. The consumer wires these into their own
+ * React provider using `createContext`, `useState`, and `useEffect`.
+ *
+ * This approach keeps the SDK free of React dependencies while
+ * providing full type safety and a clear integration pattern.
+ *
+ * @param config - SAP bridge configuration (network, region, etc.)
+ * @returns Blueprint with default value and manager factory
+ *
+ * @example Next.js App Router provider
+ * ```tsx
+ * // app/providers/sap-provider.tsx
+ * 'use client';
+ *
+ * import { createContext, useContext, useState, useCallback, useMemo, type ReactNode } from 'react';
+ * import { useWallet } from '@solana/wallet-adapter-react';
+ * import {
+ *   createSapContextBlueprint,
+ *   type SapContextValue,
+ *   type SynapseAnchorSap,
+ * } from '@oobe-protocol-labs/synapse-client-sdk/ai/sap';
+ * import { SynapseNetwork } from '@oobe-protocol-labs/synapse-client-sdk/utils';
+ *
+ * const blueprint = createSapContextBlueprint({ network: SynapseNetwork.Mainnet });
+ * const SapContext = createContext<SapContextValue<SynapseAnchorSap>>(blueprint.defaultValue);
+ *
+ * export function SapProvider({ children }: { children: ReactNode }) {
+ *   const { wallet, connected } = useWallet();
+ *   const [client, setClient] = useState<SynapseAnchorSap | null>(null);
+ *   const [loading, setLoading] = useState(false);
+ *   const [error, setError] = useState<Error | null>(null);
+ *
+ *   const connect = useCallback(async (w: any) => {
+ *     setLoading(true);
+ *     setError(null);
+ *     try {
+ *       const mgr = blueprint.createManager();
+ *       mgr.connect(w);
+ *       setClient(mgr.getValue().client);
+ *     } catch (e) {
+ *       setError(e instanceof Error ? e : new Error(String(e)));
+ *     } finally {
+ *       setLoading(false);
+ *     }
+ *   }, []);
+ *
+ *   const disconnect = useCallback(() => {
+ *     setClient(null);
+ *     setError(null);
+ *   }, []);
+ *
+ *   const value = useMemo(() => ({
+ *     client,
+ *     loading,
+ *     error,
+ *     connect,
+ *     disconnect,
+ *   }), [client, loading, error, connect, disconnect]);
+ *
+ *   return <SapContext.Provider value={value}>{children}</SapContext.Provider>;
+ * }
+ *
+ * export const useSap = () => useContext(SapContext);
+ * ```
+ *
+ * @example Using the hook
+ * ```tsx
+ * 'use client';
+ * import { useSap } from './sap-provider.js';
+ *
+ * export function AgentDashboard() {
+ *   const { client, loading, error } = useSap();
+ *
+ *   if (!client) return <p>Connect your wallet to use SAP</p>;
+ *   if (loading) return <p>Initializing SAP...</p>;
+ *   if (error) return <p>Error: {error.message}</p>;
+ *
+ *   return <AgentPanel sap={client} />;
+ * }
+ * ```
+ */
+export function createSapContextBlueprint(config) {
+    const defaultValue = {
+        client: null,
+        loading: false,
+        error: null,
+        connect: async () => {
+            /* no-op until provider mounts */
+        },
+        disconnect: () => {
+            /* no-op until provider mounts */
+        },
+    };
+    function createManager() {
+        let client = null;
+        let loading = false;
+        let error = null;
+        const listeners = new Set();
+        function notify() {
+            for (const fn of listeners)
+                fn();
+        }
+        return {
+            connect(wallet) {
+                loading = true;
+                error = null;
+                notify();
+                try {
+                    client = SynapseAnchorSap.create({ wallet, ...config });
+                    loading = false;
+                    notify();
+                }
+                catch (e) {
+                    error = e instanceof Error ? e : new Error(String(e));
+                    loading = false;
+                    client = null;
+                    notify();
+                }
+            },
+            disconnect() {
+                client = null;
+                error = null;
+                loading = false;
+                notify();
+            },
+            getValue() {
+                return {
+                    client,
+                    loading,
+                    error,
+                    connect: async (w) => {
+                        this.connect(w);
+                    },
+                    disconnect: () => {
+                        this.disconnect();
+                    },
+                };
+            },
+            subscribe(listener) {
+                listeners.add(listener);
+                return () => {
+                    listeners.delete(listener);
+                };
+            },
+        };
+    }
+    return { defaultValue, createManager };
+}
+//# sourceMappingURL=provider.js.map

package/dist/esm/ai/sap/provider.js.map

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