@oobe-protocol-labs/synapse-client-sdk 1.2.1 → 1.2.2

package/dist/esm/next/index.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @module next
+ * @description Synapse Client SDK — Next.js integration helpers.
+ *
+ * Drop-in utilities for using the Synapse SDK in Next.js 13+ (App Router)
+ * with zero boilerplate for the most common patterns:
+ *
+ * - **`synapseResponse()`** — wraps `NextResponse.json()` with BigInt serialization
+ * - **`withSynapseError()`** — API Route error boundary / handler wrapper
+ * - **`createSynapseProvider()`** — HMR-safe SynapseClient singleton factory
+ * - **`createGatewayProvider()`** — HMR-safe AgentGateway singleton factory
+ *
+ * All exports are framework-independent at the type level: they work with
+ * any object that has `json()` and `status` — so they can be tested outside
+ * of a Next.js environment.
+ *
+ * @example API Route (App Router)
+ * ```ts
+ * // app/api/balance/route.ts
+ * import { synapseResponse, withSynapseError, createSynapseProvider } from '@oobe-protocol-labs/synapse-client-sdk/next';
+ * import { Pubkey } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const getClient = createSynapseProvider({ endpoint: process.env.SYNAPSE_RPC! });
+ *
+ * export const GET = withSynapseError(async (req) => {
+ *   const address = new URL(req.url).searchParams.get('address')!;
+ *   const balance = await getClient().rpc.getBalance(Pubkey(address));
+ *   return synapseResponse({ balance });
+ * });
+ * ```
+ *
+ * @since 1.2.2
+ */
+import { type SingletonOptions } from '../utils/helpers';
+import { SynapseClient, type SynapseClientConfig } from '../core/client';
+/**
+ * @description Options for {@link synapseResponse}.
+ * @since 1.2.2
+ */
+export interface SynapseResponseInit {
+    /** HTTP status code (default: 200). */
+    status?: number;
+    /** Extra headers to include. */
+    headers?: Record<string, string>;
+}
+/**
+ * @description Create a JSON `Response` with automatic BigInt serialization.
+ *
+ * Works with Next.js App Router, edge functions, or any Web-standard
+ * `Response` environment.
+ *
+ * @param data - Any value (may contain `BigInt`).
+ * @param init - Optional status code and headers.
+ * @returns A `Response` with `Content-Type: application/json`.
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * return synapseResponse({ budget: 100_000n, status: 'ok' });
+ * // → Response { body: '{"budget":"100000","status":"ok"}', status: 200 }
+ * ```
+ */
+export declare function synapseResponse(data: unknown, init?: SynapseResponseInit): Response;
+/**
+ * @description Wrap a Next.js API Route handler with error handling.
+ *
+ * Catches thrown errors and returns a structured JSON error response
+ * with the appropriate status code. SDK errors include the error code.
+ *
+ * @param handler - Async handler function `(req) => Response`
+ * @returns Wrapped handler with the same signature
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * export const GET = withSynapseError(async (req) => {
+ *   // If this throws, caller gets { error: '...', code: '...' } with 500
+ *   const data = await client.rpc.getBalance(Pubkey('...'));
+ *   return synapseResponse({ data });
+ * });
+ * ```
+ */
+export declare function withSynapseError<T extends Request = Request>(handler: (req: T, ...args: unknown[]) => Promise<Response>): (req: T, ...args: unknown[]) => Promise<Response>;
+/**
+ * @description Create an HMR-safe SynapseClient singleton for Next.js.
+ *
+ * Uses {@link createSingleton} under the hood to store the instance
+ * on `globalThis`, surviving hot-module reloads in development.
+ *
+ * @param config - SynapseClient configuration
+ * @param opts   - Optional singleton options (version for cache busting)
+ * @returns A zero-arg getter that returns the singleton client
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * // lib/synapse.ts
+ * import { createSynapseProvider } from '@oobe-protocol-labs/synapse-client-sdk/next';
+ *
+ * export const getSynapseClient = createSynapseProvider({
+ *   endpoint: process.env.SYNAPSE_RPC!,
+ *   apiKey: process.env.SYNAPSE_API_KEY,
+ * });
+ *
+ * // Then in any route/server component:
+ * const client = getSynapseClient();
+ * ```
+ */
+export declare function createSynapseProvider(config: SynapseClientConfig, opts?: SingletonOptions): () => SynapseClient;
+/**
+ * @description Create an HMR-safe AgentGateway singleton for Next.js.
+ *
+ * Lazily imports `AgentGateway` to avoid pulling the full AI module
+ * into routes that don't need it.
+ *
+ * @param clientProvider - A getter that returns the SynapseClient (from {@link createSynapseProvider})
+ * @param configFactory  - Function returning the GatewayConfig (evaluated once)
+ * @param opts           - Optional singleton options
+ * @returns A zero-arg getter that returns the singleton gateway
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * import { createSynapseProvider, createGatewayProvider } from '@oobe-protocol-labs/synapse-client-sdk/next';
+ * import { AgentId, DEFAULT_TIERS } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const getClient = createSynapseProvider({ endpoint: process.env.SYNAPSE_RPC! });
+ *
+ * export const getGateway = createGatewayProvider(getClient, () => ({
+ *   identity: {
+ *     id: AgentId('did:synapse:agent:my-agent'),
+ *     name: 'My Agent',
+ *     walletPubkey: process.env.AGENT_WALLET!,
+ *     createdAt: Date.now(),
+ *   },
+ *   defaultTiers: DEFAULT_TIERS,
+ * }));
+ * ```
+ */
+export declare function createGatewayProvider(clientProvider: () => SynapseClient, configFactory: () => import('../ai/gateway/types').GatewayConfig, opts?: SingletonOptions): () => import('../ai/gateway/index').AgentGateway;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/next/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/next/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAMzE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,OAAO,EACb,IAAI,GAAE,mBAAwB,GAC7B,QAAQ,CAUV;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EAC1D,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,GACzD,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,CAenD;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,mBAAmB,EAC3B,IAAI,CAAC,EAAE,gBAAgB,GACtB,MAAM,aAAa,CAMrB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,aAAa,EACnC,aAAa,EAAE,MAAM,OAAO,qBAAqB,EAAE,aAAa,EAChE,IAAI,CAAC,EAAE,gBAAgB,GACtB,MAAM,OAAO,qBAAqB,EAAE,YAAY,CAUlD"}

package/dist/esm/next/index.js

@@ -0,0 +1,171 @@
+/**
+ * @module next
+ * @description Synapse Client SDK — Next.js integration helpers.
+ *
+ * Drop-in utilities for using the Synapse SDK in Next.js 13+ (App Router)
+ * with zero boilerplate for the most common patterns:
+ *
+ * - **`synapseResponse()`** — wraps `NextResponse.json()` with BigInt serialization
+ * - **`withSynapseError()`** — API Route error boundary / handler wrapper
+ * - **`createSynapseProvider()`** — HMR-safe SynapseClient singleton factory
+ * - **`createGatewayProvider()`** — HMR-safe AgentGateway singleton factory
+ *
+ * All exports are framework-independent at the type level: they work with
+ * any object that has `json()` and `status` — so they can be tested outside
+ * of a Next.js environment.
+ *
+ * @example API Route (App Router)
+ * ```ts
+ * // app/api/balance/route.ts
+ * import { synapseResponse, withSynapseError, createSynapseProvider } from '@oobe-protocol-labs/synapse-client-sdk/next';
+ * import { Pubkey } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const getClient = createSynapseProvider({ endpoint: process.env.SYNAPSE_RPC! });
+ *
+ * export const GET = withSynapseError(async (req) => {
+ *   const address = new URL(req.url).searchParams.get('address')!;
+ *   const balance = await getClient().rpc.getBalance(Pubkey(address));
+ *   return synapseResponse({ balance });
+ * });
+ * ```
+ *
+ * @since 1.2.2
+ */
+import { toJsonSafe } from '../utils/helpers.js';
+import { createSingleton } from '../utils/helpers.js';
+import { SynapseClient } from '../core/client.js';
+/**
+ * @description Create a JSON `Response` with automatic BigInt serialization.
+ *
+ * Works with Next.js App Router, edge functions, or any Web-standard
+ * `Response` environment.
+ *
+ * @param data - Any value (may contain `BigInt`).
+ * @param init - Optional status code and headers.
+ * @returns A `Response` with `Content-Type: application/json`.
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * return synapseResponse({ budget: 100_000n, status: 'ok' });
+ * // → Response { body: '{"budget":"100000","status":"ok"}', status: 200 }
+ * ```
+ */
+export function synapseResponse(data, init = {}) {
+    const safe = toJsonSafe(data);
+    const body = JSON.stringify(safe);
+    return new Response(body, {
+        status: init.status ?? 200,
+        headers: {
+            'Content-Type': 'application/json',
+            ...init.headers,
+        },
+    });
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  withSynapseError — API Route error boundary
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Wrap a Next.js API Route handler with error handling.
+ *
+ * Catches thrown errors and returns a structured JSON error response
+ * with the appropriate status code. SDK errors include the error code.
+ *
+ * @param handler - Async handler function `(req) => Response`
+ * @returns Wrapped handler with the same signature
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * export const GET = withSynapseError(async (req) => {
+ *   // If this throws, caller gets { error: '...', code: '...' } with 500
+ *   const data = await client.rpc.getBalance(Pubkey('...'));
+ *   return synapseResponse({ data });
+ * });
+ * ```
+ */
+export function withSynapseError(handler) {
+    return async (req, ...args) => {
+        try {
+            return await handler(req, ...args);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const code = err.code ?? 'INTERNAL_ERROR';
+            const status = err.status ?? 500;
+            return synapseResponse({ error: message, code, timestamp: Date.now() }, { status });
+        }
+    };
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  createSynapseProvider — HMR-safe client singleton
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Create an HMR-safe SynapseClient singleton for Next.js.
+ *
+ * Uses {@link createSingleton} under the hood to store the instance
+ * on `globalThis`, surviving hot-module reloads in development.
+ *
+ * @param config - SynapseClient configuration
+ * @param opts   - Optional singleton options (version for cache busting)
+ * @returns A zero-arg getter that returns the singleton client
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * // lib/synapse.ts
+ * import { createSynapseProvider } from '@oobe-protocol-labs/synapse-client-sdk/next';
+ *
+ * export const getSynapseClient = createSynapseProvider({
+ *   endpoint: process.env.SYNAPSE_RPC!,
+ *   apiKey: process.env.SYNAPSE_API_KEY,
+ * });
+ *
+ * // Then in any route/server component:
+ * const client = getSynapseClient();
+ * ```
+ */
+export function createSynapseProvider(config, opts) {
+    return createSingleton('__synapse_client__', () => new SynapseClient(config), opts);
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  createGatewayProvider — HMR-safe gateway singleton
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Create an HMR-safe AgentGateway singleton for Next.js.
+ *
+ * Lazily imports `AgentGateway` to avoid pulling the full AI module
+ * into routes that don't need it.
+ *
+ * @param clientProvider - A getter that returns the SynapseClient (from {@link createSynapseProvider})
+ * @param configFactory  - Function returning the GatewayConfig (evaluated once)
+ * @param opts           - Optional singleton options
+ * @returns A zero-arg getter that returns the singleton gateway
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * import { createSynapseProvider, createGatewayProvider } from '@oobe-protocol-labs/synapse-client-sdk/next';
+ * import { AgentId, DEFAULT_TIERS } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const getClient = createSynapseProvider({ endpoint: process.env.SYNAPSE_RPC! });
+ *
+ * export const getGateway = createGatewayProvider(getClient, () => ({
+ *   identity: {
+ *     id: AgentId('did:synapse:agent:my-agent'),
+ *     name: 'My Agent',
+ *     walletPubkey: process.env.AGENT_WALLET!,
+ *     createdAt: Date.now(),
+ *   },
+ *   defaultTiers: DEFAULT_TIERS,
+ * }));
+ * ```
+ */
+export function createGatewayProvider(clientProvider, configFactory, opts) {
+    return createSingleton('__synapse_gateway__', () => {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { AgentGateway } = require('../ai/gateway/index');
+        return new AgentGateway(clientProvider(), configFactory());
+    }, opts);
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/next/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/next/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAyB,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAA4B,MAAM,gBAAgB,CAAC;AAiBzE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAa,EACb,OAA4B,EAAE;IAE9B,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;QACxB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,GAAG;QAC1B,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,GAAG,IAAI,CAAC,OAAO;SAChB;KACF,CAAC,CAAC;AACL,CAAC;AAED;;qEAEqE;AAErE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAA0D;IAE1D,OAAO,KAAK,EAAE,GAAM,EAAE,GAAG,IAAe,EAAqB,EAAE;QAC7D,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,IAAI,GAAI,GAAyB,CAAC,IAAI,IAAI,gBAAgB,CAAC;YACjE,MAAM,MAAM,GAAI,GAA2B,CAAC,MAAM,IAAI,GAAG,CAAC;YAE1D,OAAO,eAAe,CACpB,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,EAC/C,EAAE,MAAM,EAAE,CACX,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;qEAEqE;AAErE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAA2B,EAC3B,IAAuB;IAEvB,OAAO,eAAe,CACpB,oBAAoB,EACpB,GAAG,EAAE,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,EAC/B,IAAI,CACL,CAAC;AACJ,CAAC;AAED;;qEAEqE;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,qBAAqB,CACnC,cAAmC,EACnC,aAAgE,EAChE,IAAuB;IAEvB,OAAO,eAAe,CACpB,qBAAqB,EACrB,GAAG,EAAE;QACH,iEAAiE;QACjE,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAyC,CAAC;QAChG,OAAO,IAAI,YAAY,CAAC,cAAc,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;IAC7D,CAAC,EACD,IAAI,CACL,CAAC;AACJ,CAAC"}

package/dist/esm/utils/helpers.d.ts

@@ -2,7 +2,7 @@
  * SDK utility helpers — minimal, zero-dependency.
  *
  * Pure functions for common Solana value conversions, validation,
- * and async control flow.
+ * async control flow, BigInt serialization, and HMR-safe singletons.
  *
  * @module utils/helpers
  * @since 1.0.0
@@ -94,4 +94,82 @@ export declare function chunk<T>(arr: readonly T[], size: number): T[][];
  * ```
  */
 export declare function retry<T>(fn: () => Promise<T>, maxAttempts?: number, baseDelayMs?: number): Promise<T>;
+/**
+ * Recursively convert `BigInt` values to `string` so the result is
+ * safe for `JSON.stringify()`.
+ *
+ * Useful in Next.js API Routes, Express handlers, or anywhere you
+ * need to serialize gateway / x402 objects that contain `BigInt`
+ * fields like `pricePerCall`, `maxBudget`, or `amountCharged`.
+ *
+ * @param obj - Any value (object, array, primitive, BigInt).
+ * @returns A deep clone with every `BigInt` replaced by its string
+ *          representation.
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * import { toJsonSafe } from '@oobe-protocol-labs/synapse-client-sdk/utils';
+ *
+ * return NextResponse.json(toJsonSafe({ budget: 100_000n, data }));
+ * ```
+ */
+export declare function toJsonSafe(obj: unknown): unknown;
+/**
+ * `JSON.stringify` replacer that converts `BigInt` → `string`.
+ *
+ * @example
+ * ```ts
+ * import { bigIntReplacer } from '@oobe-protocol-labs/synapse-client-sdk/utils';
+ *
+ * const json = JSON.stringify(data, bigIntReplacer);
+ * ```
+ *
+ * @since 1.2.2
+ */
+export declare function bigIntReplacer(_key: string, value: unknown): unknown;
+/**
+ * Options for {@link createSingleton}.
+ * @since 1.2.2
+ */
+export interface SingletonOptions {
+    /**
+     * Bump this number to invalidate a cached instance (e.g. after
+     * changing the factory config). The old instance is replaced on
+     * the next call.
+     */
+    version?: number;
+}
+/**
+ * Create an HMR-safe singleton accessor.
+ *
+ * In Next.js (and other HMR-enabled environments) module scope is
+ * re-evaluated on every hot reload, destroying any `let` / `const`
+ * singleton. This helper stores the instance on `globalThis` so it
+ * survives reloads.
+ *
+ * @typeParam T - Type of the singleton instance.
+ * @param key     - Unique global key (e.g. `'synapseClient'`).
+ * @param factory - Function that creates the instance.
+ * @param options - Optional version for cache invalidation.
+ * @returns A zero-arg getter that returns the singleton.
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * import { createSingleton } from '@oobe-protocol-labs/synapse-client-sdk/utils';
+ * import { SynapseClient } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * export const getSynapseClient = createSingleton('synapseClient', () =>
+ *   SynapseClient.fromEndpoint({ network: 'mainnet', region: 'US', apiKey: process.env.SYNAPSE_API_KEY! }),
+ * );
+ *
+ * // With version invalidation — bump to recreate:
+ * export const getGateway = createSingleton('agentGateway', () =>
+ *   createAgentGateway(getSynapseClient(), config),
+ *   { version: 4 },
+ * );
+ * ```
+ */
+export declare function createSingleton<T>(key: string, factory: () => T, options?: SingletonOptions): () => T;
 //# sourceMappingURL=helpers.d.ts.map

package/dist/esm/utils/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGtD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,QAAQ,GAAG,MAAM,KAAG,MACpC,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,QACT,CAAC;AAEpC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,MAAM,KAAG,CAAC,IAAI,MACN,CAAC;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,GAAG,MAAM,KAAG,OACJ,CAAC;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GAAI,IAAI,MAAM,KAAG,OAAO,CAAC,IAAI,CACV,CAAC;AAEtC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAM/D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,WAAW,SAAI,EACf,WAAW,SAAM,GAChB,OAAO,CAAC,CAAC,CAAC,CAWZ"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGtD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,QAAQ,GAAG,MAAM,KAAG,MACpC,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,QACT,CAAC;AAEpC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,MAAM,KAAG,CAAC,IAAI,MACN,CAAC;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,GAAG,MAAM,KAAG,OACJ,CAAC;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GAAI,IAAI,MAAM,KAAG,OAAO,CAAC,IAAI,CACV,CAAC;AAEtC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAM/D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,WAAW,SAAI,EACf,WAAW,SAAM,GAChB,OAAO,CAAC,CAAC,CAAC,CAWZ;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAiBhD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE;AAMD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,CAAC,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,CAAC,CAaT"}

package/dist/esm/utils/helpers.js

@@ -104,4 +104,110 @@ export async function retry(fn, maxAttempts = 3, baseDelayMs = 500) {
     }
     throw lastErr;
 }
+/* ═══════════════════════════════════════════════════════════════
+ *  BigInt-safe JSON serialization
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * Recursively convert `BigInt` values to `string` so the result is
+ * safe for `JSON.stringify()`.
+ *
+ * Useful in Next.js API Routes, Express handlers, or anywhere you
+ * need to serialize gateway / x402 objects that contain `BigInt`
+ * fields like `pricePerCall`, `maxBudget`, or `amountCharged`.
+ *
+ * @param obj - Any value (object, array, primitive, BigInt).
+ * @returns A deep clone with every `BigInt` replaced by its string
+ *          representation.
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * import { toJsonSafe } from '@oobe-protocol-labs/synapse-client-sdk/utils';
+ *
+ * return NextResponse.json(toJsonSafe({ budget: 100_000n, data }));
+ * ```
+ */
+export function toJsonSafe(obj) {
+    if (typeof obj === 'bigint')
+        return obj.toString();
+    if (obj === null || obj === undefined)
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(toJsonSafe);
+    if (obj instanceof Map) {
+        const out = {};
+        for (const [k, v] of obj)
+            out[String(k)] = toJsonSafe(v);
+        return out;
+    }
+    if (typeof obj === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            out[k] = toJsonSafe(v);
+        }
+        return out;
+    }
+    return obj;
+}
+/**
+ * `JSON.stringify` replacer that converts `BigInt` → `string`.
+ *
+ * @example
+ * ```ts
+ * import { bigIntReplacer } from '@oobe-protocol-labs/synapse-client-sdk/utils';
+ *
+ * const json = JSON.stringify(data, bigIntReplacer);
+ * ```
+ *
+ * @since 1.2.2
+ */
+export function bigIntReplacer(_key, value) {
+    return typeof value === 'bigint' ? value.toString() : value;
+}
+// Shared registry on globalThis — survives HMR reloads.
+const _singletonRegistry = globalThis.__synapse_singletons ??= {};
+/**
+ * Create an HMR-safe singleton accessor.
+ *
+ * In Next.js (and other HMR-enabled environments) module scope is
+ * re-evaluated on every hot reload, destroying any `let` / `const`
+ * singleton. This helper stores the instance on `globalThis` so it
+ * survives reloads.
+ *
+ * @typeParam T - Type of the singleton instance.
+ * @param key     - Unique global key (e.g. `'synapseClient'`).
+ * @param factory - Function that creates the instance.
+ * @param options - Optional version for cache invalidation.
+ * @returns A zero-arg getter that returns the singleton.
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * import { createSingleton } from '@oobe-protocol-labs/synapse-client-sdk/utils';
+ * import { SynapseClient } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * export const getSynapseClient = createSingleton('synapseClient', () =>
+ *   SynapseClient.fromEndpoint({ network: 'mainnet', region: 'US', apiKey: process.env.SYNAPSE_API_KEY! }),
+ * );
+ *
+ * // With version invalidation — bump to recreate:
+ * export const getGateway = createSingleton('agentGateway', () =>
+ *   createAgentGateway(getSynapseClient(), config),
+ *   { version: 4 },
+ * );
+ * ```
+ */
+export function createSingleton(key, factory, options) {
+    const versionKey = `${key}__v`;
+    return () => {
+        const versionMismatch = options?.version != null && _singletonRegistry[versionKey] !== options.version;
+        if (!_singletonRegistry[key] || versionMismatch) {
+            _singletonRegistry[key] = factory();
+            if (options?.version != null) {
+                _singletonRegistry[versionKey] = options.version;
+            }
+        }
+        return _singletonRegistry[key];
+    };
+}
 //# sourceMappingURL=helpers.js.map

package/dist/esm/utils/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/utils/helpers.ts"],"names":[],"mappings":"AAUA,OAAO,EAAsB,QAAQ,IAAI,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,QAA2B,EAAU,EAAE,CACnE,MAAM,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,GAAW,EAAY,EAAE,CACrD,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAS,EAAe,EAAE,CACtD,+BAA+B,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAS,EAAW,EAAE,CACrD,+BAA+B,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CACjD,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAEtC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,KAAK,CAAI,GAAiB,EAAE,IAAY;IACtD,MAAM,MAAM,GAAU,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;QAC1C,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAQ,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,EAAoB,EACpB,WAAW,GAAG,CAAC,EACf,WAAW,GAAG,GAAG;IAEjB,IAAI,OAAgB,CAAC;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,GAAG,GAAG,CAAC;YACd,IAAI,CAAC,GAAG,WAAW,GAAG,CAAC;gBAAE,MAAM,KAAK,CAAC,WAAW,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IACD,MAAM,OAAO,CAAC;AAChB,CAAC"}
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/utils/helpers.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/synapse-client-sdk",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Synapse Client SDK -- Typed Solana RPC gateway with @solana/kit native types, 53 JSON-RPC methods, DAS, WebSocket, gRPC/Geyser parser, signers/wallets, and AI agent tooling (LangChain, x402) | Powered by oobeprotocol.ai (OOBE)",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -66,6 +66,11 @@
       "import": "./dist/esm/ai/lazy.js",
       "require": "./dist/cjs/ai/lazy.js"
     },
+    "./ai/persistence": {
+      "types": "./dist/esm/ai/persistence/index.d.ts",
+      "import": "./dist/esm/ai/persistence/index.js",
+      "require": "./dist/cjs/ai/persistence/index.js"
+    },
     "./kit": {
       "types": "./dist/esm/kit/index.d.ts",
       "import": "./dist/esm/kit/index.js",
@@ -155,6 +160,11 @@
       "types": "./dist/esm/context/index.d.ts",
       "import": "./dist/esm/context/index.js",
       "require": "./dist/cjs/context/index.js"
+    },
+    "./next": {
+      "types": "./dist/esm/next/index.d.ts",
+      "import": "./dist/esm/next/index.js",
+      "require": "./dist/cjs/next/index.js"
     }
   },
   "files": [
@@ -243,7 +253,9 @@
   "peerDependencies": {
     "@langchain/core": ">=0.3.0 <0.4.0",
     "typescript": ">=5.0.0",
-    "zod": ">=3.23.0 || >=4.0.0"
+    "zod": ">=3.23.0 || >=4.0.0",
+    "ioredis": ">=5.0.0",
+    "pg": ">=8.0.0"
   },
   "peerDependenciesMeta": {
     "zod": {
@@ -251,6 +263,12 @@
     },
     "@langchain/core": {
       "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
     }
   },
   "engines": {