@oobe-protocol-labs/synapse-client-sdk 1.0.0-beta → 1.0.2

package/dist/cjs/core/client.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * SynapseClient -- top-level orchestrator that binds transport to typed RPC modules.
+ *
+ * Lazy-initializes sub-clients (`.rpc`, `.das`, `.ws`, `.grpc`) on first
+ * access -- zero cost if a module is never used. This is the main entry
+ * point for most consumers of the SDK.
+ *
+ * Since v1.1.0, exposes `@solana/kit` native RPC and subscription clients
+ * via `.kitRpc` and `.kitSubscriptions` for full Kit interop.
+ *
+ * @module core/client
+ * @since 1.0.0
+ *
+ * @example
+ * ```ts
+ * import { SynapseClient } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const client = new SynapseClient({ endpoint: 'https://rpc.synapse.com', apiKey: 'sk-...' });
+ * const slot = await client.rpc.getSlot();
+ * const balance = await client.rpc.getBalance(Pubkey('...'));
+ * client.destroy();
+ * ```
+ *
+ * @example Kit-native RPC
+ * ```ts
+ * import { SynapseClient } from '@oobe-protocol-labs/synapse-client-sdk';
+ * import { address } from '@oobe-protocol-labs/synapse-client-sdk/kit';
+ *
+ * const client = new SynapseClient({ endpoint: 'https://rpc.synapse.com' });
+ * const { value: balance } = await client.kitRpc
+ *   .getBalance(address('So11111111111111111111111111111111111111112'))
+ *   .send();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SynapseClient = void 0;
+const transport_1 = require("./transport");
+const env_1 = require("../utils/env");
+const synapse_1 = require("../utils/synapse");
+class SynapseClient {
+    transport;
+    cfg;
+    // Lazy singletons
+    _rpc;
+    _das;
+    _ws;
+    _grpc;
+    // Kit-native lazy singletons
+    _kitRpc;
+    _kitSubs;
+    constructor(config) {
+        this.cfg = config;
+        this.transport = new transport_1.HttpTransport(config);
+        if (config.debug)
+            console.log('[Synapse SDK] initialized:', config.endpoint, `(${(0, env_1.isBrowser)() ? 'browser' : 'server'})`);
+    }
+    /* ═══════════════════════════════════════════════════════════════
+     *  Static factories
+     * ═══════════════════════════════════════════════════════════════ */
+    /**
+     * Create a SynapseClient from a network + region specification.
+     * Resolves the endpoint from the built-in registry and configures
+     * RPC, WebSocket, and gRPC transports automatically.
+     *
+     * @example
+     * ```ts
+     * import { SynapseClient } from '@oobe-protocol-labs/synapse-client-sdk';
+     * import { SynapseNetwork, SynapseRegion } from '@oobe-protocol-labs/synapse-client-sdk/utils';
+     *
+     * const client = SynapseClient.fromEndpoint({
+     *   network: SynapseNetwork.Mainnet,
+     *   region: SynapseRegion.US,
+     *   apiKey: 'sk-...',
+     * });
+     * ```
+     */
+    static fromEndpoint(config) {
+        const endpoint = (0, synapse_1.resolveEndpoint)(config.network, config.region);
+        const clientCfg = (0, synapse_1.toClientConfig)(endpoint, {
+            apiKey: config.apiKey,
+            timeout: config.timeout,
+            debug: config.debug,
+            headers: config.headers,
+        });
+        return new SynapseClient(clientCfg);
+    }
+    // ── Convenience pass-through ──────────────────────────────────
+    /**
+     * Raw RPC call pass-through to the underlying transport.
+     *
+     * @typeParam T - Expected result type.
+     * @param method - RPC method name.
+     * @param params - Positional parameters.
+     * @param opts   - Per-call overrides.
+     * @returns The result payload.
+     * @since 1.0.0
+     */
+    call(method, params = [], opts = {}) {
+        return this.transport.request(method, params, opts);
+    }
+    /**
+     * Batch multiple RPC calls in a single HTTP request.
+     *
+     * @typeParam T - Expected result type per call.
+     * @param requests - Array of `{ method, params }` objects.
+     * @param opts     - Per-call overrides applied to the batch.
+     * @returns Array of results.
+     * @since 1.0.0
+     */
+    batch(requests, opts = {}) {
+        return this.transport.batch(requests, opts);
+    }
+    // ── Lazy sub-clients (tree-shakeable, zero cost if unused) ────
+    /**
+     * Typed Solana JSON-RPC facade — 53 methods.
+     * Lazy-loaded on first access.
+     * @since 1.0.0
+     */
+    get rpc() {
+        if (!this._rpc) {
+            const { SolanaRpc: Ctor } = require('../rpc/solana-rpc');
+            this._rpc = new Ctor(this.transport);
+        }
+        return this._rpc;
+    }
+    /**
+     * Digital Asset Standard (DAS) client — Metaplex Read API / cNFT queries.
+     * Lazy-loaded on first access.
+     * @since 1.0.0
+     */
+    get das() {
+        if (!this._das) {
+            const { DasClient: Ctor } = require('../das/client');
+            this._das = new Ctor(this.transport);
+        }
+        return this._das;
+    }
+    /**
+     * WebSocket subscription client — real-time account, program, logs, slot changes.
+     * Lazy-loaded on first access.
+     * @since 1.0.0
+     */
+    get ws() {
+        if (!this._ws) {
+            const { WsClient: Ctor } = require('../websocket/client');
+            this._ws = new Ctor({ endpoint: this.cfg.wsEndpoint ?? this.cfg.endpoint.replace('http', 'ws') });
+        }
+        return this._ws;
+    }
+    /**
+     * gRPC transport for Yellowstone/Geyser streaming.
+     * Lazy-loaded on first access.
+     *
+     * **Node.js only** — throws a descriptive error in browser environments.
+     * Use RPC or WebSocket for browser/Next.js client components.
+     *
+     * @since 1.0.0
+     */
+    get grpc() {
+        if ((0, env_1.isBrowser)()) {
+            throw new Error('GrpcTransport is not available in browser environments. ' +
+                'gRPC requires native Node.js bindings (@grpc/grpc-js). ' +
+                'Use client.rpc or client.ws for browser/Next.js client components.');
+        }
+        if (!this._grpc) {
+            const { GrpcTransport: Ctor } = require('../grpc/transport');
+            this._grpc = new Ctor({ endpoint: this.cfg.grpcEndpoint ?? this.cfg.endpoint });
+        }
+        return this._grpc;
+    }
+    // ── Lifecycle ─────────────────────────────────────────────────
+    /**
+     * Gracefully shut down all active connections (WebSocket, gRPC).
+     * @since 1.0.0
+     */
+    destroy() {
+        this._ws?.close();
+    }
+    // ── @solana/kit native accessors ─────────────────────────────
+    /**
+     * Kit-native fully-typed Solana RPC client.
+     *
+     * Uses the same endpoint as the Synapse transport but returns a
+     * `Rpc<SolanaRpcApi>` instance from `@solana/kit`, giving you
+     * access to Kit's type-safe `.send()` pattern with all 53+ methods.
+     *
+     * Lazy-loaded on first access.
+     *
+     * @since 1.1.0
+     *
+     * @example
+     * ```ts
+     * import { address } from '@oobe-protocol-labs/synapse-client-sdk/kit';
+     *
+     * const { value: balance } = await client.kitRpc
+     *   .getBalance(address('So11111111111111111111111111111111111111112'))
+     *   .send();
+     * ```
+     */
+    get kitRpc() {
+        if (!this._kitRpc) {
+            const { createRpc, createSolanaRpcApi, createDefaultRpcTransport, DEFAULT_RPC_CONFIG, } = require('@solana/kit');
+            this._kitRpc = createRpc({
+                api: createSolanaRpcApi(DEFAULT_RPC_CONFIG),
+                transport: createDefaultRpcTransport({ url: this.cfg.endpoint }),
+            });
+        }
+        return this._kitRpc;
+    }
+    /**
+     * Kit-native fully-typed Solana RPC Subscriptions client.
+     *
+     * Returns a `RpcSubscriptions<SolanaRpcSubscriptionsApi>` from `@solana/kit`
+     * for real-time WebSocket subscriptions (account, slot, logs, signature, etc.)
+     * with the Kit `.subscribe()` pattern.
+     *
+     * Uses the WebSocket endpoint derived from the HTTP endpoint.
+     * Lazy-loaded on first access.
+     *
+     * @since 1.1.0
+     *
+     * @example
+     * ```ts
+     * const subs = client.kitSubscriptions;
+     * const notifications = await subs
+     *   .slotNotifications()
+     *   .subscribe({ abortSignal: AbortSignal.timeout(30_000) });
+     *
+     * for await (const slot of notifications) {
+     *   console.log('New slot:', slot.slot);
+     * }
+     * ```
+     */
+    get kitSubscriptions() {
+        if (!this._kitSubs) {
+            const { createSubscriptionRpc, createSolanaRpcSubscriptionsApi, createDefaultRpcSubscriptionsTransport, createDefaultSolanaRpcSubscriptionsChannelCreator, DEFAULT_RPC_SUBSCRIPTIONS_CONFIG, } = require('@solana/kit');
+            const wsUrl = this.cfg.wsEndpoint ?? this.cfg.endpoint.replace('http', 'ws');
+            this._kitSubs = createSubscriptionRpc({
+                api: createSolanaRpcSubscriptionsApi(DEFAULT_RPC_SUBSCRIPTIONS_CONFIG),
+                transport: createDefaultRpcSubscriptionsTransport({
+                    createChannel: createDefaultSolanaRpcSubscriptionsChannelCreator({ url: wsUrl }),
+                }),
+            });
+        }
+        return this._kitSubs;
+    }
+}
+exports.SynapseClient = SynapseClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/core/client.js.map

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

package/dist/cjs/core/errors.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Synapse SDK error hierarchy — minimal, strongly typed.
+ *
+ * All SDK errors extend {@link SynapseError} so consumers can catch
+ * the entire tree with a single `catch (e) { if (e instanceof SynapseError) … }`.
+ *
+ * @module core/errors
+ * @since 1.0.0
+ */
+/**
+ * Base error for all Synapse SDK failures.
+ *
+ * @since 1.0.0
+ * @example
+ * ```ts
+ * try { await client.call('getSlot'); }
+ * catch (e) { if (e instanceof SynapseError) console.error(e.code, e.message); }
+ * ```
+ */
+export declare class SynapseError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    /**
+     * @param message - Human-readable error description.
+     * @param code    - JSON-RPC-style numeric error code (default `-32000`).
+     * @param data    - Optional payload with extra context.
+     */
+    constructor(message: string, code?: number, data?: unknown | undefined);
+}
+/**
+ * Network-level failure (DNS, TCP, TLS, HTTP non-200).
+ *
+ * @since 1.0.0
+ */
+export declare class NetworkError extends SynapseError {
+    readonly cause?: Error | undefined;
+    /**
+     * @param message - Description of the network failure.
+     * @param cause   - Original error that triggered this (e.g. `fetch` error).
+     */
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Request timed out.
+ *
+ * @since 1.0.0
+ */
+export declare class TimeoutError extends SynapseError {
+    /**
+     * @param ms - Timeout threshold in milliseconds.
+     */
+    constructor(ms: number);
+}
+/**
+ * The requested RPC method does not exist on the upstream.
+ *
+ * @since 1.0.0
+ */
+export declare class RpcMethodNotFoundError extends SynapseError {
+    /**
+     * @param method - The method name that was not found.
+     */
+    constructor(method: string);
+}
+/**
+ * Error forwarded from an upstream RPC provider.
+ *
+ * @since 1.0.0
+ */
+export declare class UpstreamError extends SynapseError {
+    readonly upstreamName?: string | undefined;
+    readonly upstreamUrl?: string | undefined;
+    /**
+     * @param message      - Error message from the upstream.
+     * @param code         - JSON-RPC error code.
+     * @param upstreamName - Upstream provider name (if known).
+     * @param upstreamUrl  - Upstream endpoint URL (if known).
+     */
+    constructor(message: string, code: number, upstreamName?: string | undefined, upstreamUrl?: string | undefined);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;GASG;AACH,qBAAa,YAAa,SAAQ,KAAK;aAQnB,IAAI,EAAE,MAAM;aACZ,IAAI,CAAC,EAAE,OAAO;IARhC;;;;OAIG;gBAED,OAAO,EAAE,MAAM,EACC,IAAI,GAAE,MAAe,EACrB,IAAI,CAAC,EAAE,OAAO,YAAA;CAKjC;AAED;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,YAAY;aAKC,KAAK,CAAC,EAAE,KAAK;IAJ1D;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,KAAK,YAAA;CAI3D;AAED;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,YAAY;IAC5C;;OAEG;gBACS,EAAE,EAAE,MAAM;CAIvB;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,YAAY;IACtD;;OAEG;gBACS,MAAM,EAAE,MAAM;CAI3B;AAED;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,YAAY;aAU3B,YAAY,CAAC,EAAE,MAAM;aACrB,WAAW,CAAC,EAAE,MAAM;IAVtC;;;;;OAKG;gBAED,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACI,YAAY,CAAC,EAAE,MAAM,YAAA,EACrB,WAAW,CAAC,EAAE,MAAM,YAAA;CAKvC"}

package/dist/cjs/core/errors.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Synapse SDK error hierarchy — minimal, strongly typed.
+ *
+ * All SDK errors extend {@link SynapseError} so consumers can catch
+ * the entire tree with a single `catch (e) { if (e instanceof SynapseError) … }`.
+ *
+ * @module core/errors
+ * @since 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpstreamError = exports.RpcMethodNotFoundError = exports.TimeoutError = exports.NetworkError = exports.SynapseError = void 0;
+/**
+ * Base error for all Synapse SDK failures.
+ *
+ * @since 1.0.0
+ * @example
+ * ```ts
+ * try { await client.call('getSlot'); }
+ * catch (e) { if (e instanceof SynapseError) console.error(e.code, e.message); }
+ * ```
+ */
+class SynapseError extends Error {
+    code;
+    data;
+    /**
+     * @param message - Human-readable error description.
+     * @param code    - JSON-RPC-style numeric error code (default `-32000`).
+     * @param data    - Optional payload with extra context.
+     */
+    constructor(message, code = -32000, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'SynapseError';
+    }
+}
+exports.SynapseError = SynapseError;
+/**
+ * Network-level failure (DNS, TCP, TLS, HTTP non-200).
+ *
+ * @since 1.0.0
+ */
+class NetworkError extends SynapseError {
+    cause;
+    /**
+     * @param message - Description of the network failure.
+     * @param cause   - Original error that triggered this (e.g. `fetch` error).
+     */
+    constructor(message, cause) {
+        super(message, -32001);
+        this.cause = cause;
+        this.name = 'NetworkError';
+    }
+}
+exports.NetworkError = NetworkError;
+/**
+ * Request timed out.
+ *
+ * @since 1.0.0
+ */
+class TimeoutError extends SynapseError {
+    /**
+     * @param ms - Timeout threshold in milliseconds.
+     */
+    constructor(ms) {
+        super(`Request timed out after ${ms}ms`, -32002);
+        this.name = 'TimeoutError';
+    }
+}
+exports.TimeoutError = TimeoutError;
+/**
+ * The requested RPC method does not exist on the upstream.
+ *
+ * @since 1.0.0
+ */
+class RpcMethodNotFoundError extends SynapseError {
+    /**
+     * @param method - The method name that was not found.
+     */
+    constructor(method) {
+        super(`RPC method not found: ${method}`, -32601);
+        this.name = 'RpcMethodNotFoundError';
+    }
+}
+exports.RpcMethodNotFoundError = RpcMethodNotFoundError;
+/**
+ * Error forwarded from an upstream RPC provider.
+ *
+ * @since 1.0.0
+ */
+class UpstreamError extends SynapseError {
+    upstreamName;
+    upstreamUrl;
+    /**
+     * @param message      - Error message from the upstream.
+     * @param code         - JSON-RPC error code.
+     * @param upstreamName - Upstream provider name (if known).
+     * @param upstreamUrl  - Upstream endpoint URL (if known).
+     */
+    constructor(message, code, upstreamName, upstreamUrl) {
+        super(message, code);
+        this.upstreamName = upstreamName;
+        this.upstreamUrl = upstreamUrl;
+        this.name = 'UpstreamError';
+    }
+}
+exports.UpstreamError = UpstreamError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH;;;;;;;;;GASG;AACH,MAAa,YAAa,SAAQ,KAAK;IAQnB;IACA;IARlB;;;;OAIG;IACH,YACE,OAAe,EACC,OAAe,CAAC,KAAK,EACrB,IAAc;QAE9B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAiB;QACrB,SAAI,GAAJ,IAAI,CAAU;QAG9B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAdD,oCAcC;AAED;;;;GAIG;AACH,MAAa,YAAa,SAAQ,YAAY;IAKC;IAJ7C;;;OAGG;IACH,YAAY,OAAe,EAAkB,KAAa;QACxD,KAAK,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QADoB,UAAK,GAAL,KAAK,CAAQ;QAExD,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AATD,oCASC;AAED;;;;GAIG;AACH,MAAa,YAAa,SAAQ,YAAY;IAC5C;;OAEG;IACH,YAAY,EAAU;QACpB,KAAK,CAAC,2BAA2B,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AARD,oCAQC;AAED;;;;GAIG;AACH,MAAa,sBAAuB,SAAQ,YAAY;IACtD;;OAEG;IACH,YAAY,MAAc;QACxB,KAAK,CAAC,yBAAyB,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AARD,wDAQC;AAED;;;;GAIG;AACH,MAAa,aAAc,SAAQ,YAAY;IAU3B;IACA;IAVlB;;;;;OAKG;IACH,YACE,OAAe,EACf,IAAY,EACI,YAAqB,EACrB,WAAoB;QAEpC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAHL,iBAAY,GAAZ,YAAY,CAAS;QACrB,gBAAW,GAAX,WAAW,CAAS;QAGpC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAhBD,sCAgBC"}

package/dist/cjs/core/transport.d.ts

@@ -0,0 +1,106 @@
+/**
+ * JSON-RPC HTTP transport — the single I/O boundary for all RPC calls.
+ *
+ * Handles serialization, timeout abort via `AbortController`,
+ * upstream rotation on method-not-allowed, retry with configurable
+ * max attempts, and optional debug logging.
+ *
+ * @module core/transport
+ * @since 1.0.0
+ *
+ * @example
+ * ```ts
+ * import { HttpTransport } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const t = new HttpTransport({ endpoint: 'https://rpc.synapse.com', apiKey: 'sk-…' });
+ * const slot = await t.request<number>('getSlot');
+ * ```
+ */
+import type { Commitment } from './types';
+/**
+ * Configuration for {@link HttpTransport}.
+ * @since 1.0.0
+ */
+export interface TransportConfig {
+    /** RPC endpoint URL. */
+    endpoint: string;
+    /** Optional Bearer API key. */
+    apiKey?: string;
+    /** Request timeout in ms (default `30 000`). */
+    timeout?: number;
+    /** Max retry attempts on method-not-allowed (default `3`). */
+    maxRetries?: number;
+    /** Enable debug logging to `console.log`. */
+    debug?: boolean;
+    /** Extra HTTP headers merged into every request. */
+    headers?: Record<string, string>;
+}
+/**
+ * Per-call options that override transport-level defaults.
+ * @since 1.0.0
+ */
+export interface CallOptions {
+    /** Override timeout for this call. */
+    timeout?: number;
+    /** Override max retries for this call. */
+    maxRetries?: number;
+    /** Commitment level hint. */
+    commitment?: Commitment;
+    /** Upstream selection strategy. */
+    routeHint?: 'rotate' | 'sticky';
+    /** Explicit upstream index. */
+    routeIndex?: number;
+}
+/**
+ * Low-level JSON-RPC 2.0 HTTP transport.
+ *
+ * All Synapse SDK RPC calls flow through this class. It is instantiated
+ * once by {@link SynapseClient} and shared by every sub-module.
+ *
+ * @since 1.0.0
+ */
+export declare class HttpTransport {
+    private cfg;
+    private id;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly debug;
+    private readonly headers;
+    constructor(cfg: TransportConfig);
+    /**
+     * Execute a single JSON-RPC 2.0 call.
+     *
+     * Retries transparently on `method-not-allowed` (code `-32601`) up to
+     * `maxRetries` times, rotating upstreams if configured.
+     *
+     * @typeParam T - Expected result type.
+     * @param method - RPC method name (e.g. `'getBalance'`).
+     * @param params - Positional parameters array.
+     * @param opts   - Per-call overrides.
+     * @returns The JSON-RPC `result` payload, typed as `T`.
+     * @throws {TimeoutError} If the request exceeds the timeout.
+     * @throws {NetworkError} On HTTP / network failures.
+     * @throws {UpstreamError} If the upstream returns an RPC error with upstream metadata.
+     * @throws {SynapseError} For all other RPC errors.
+     * @since 1.0.0
+     */
+    request<T = unknown>(method: string, params?: unknown[], opts?: CallOptions): Promise<T>;
+    /**
+     * Execute a batch of JSON-RPC 2.0 calls in a single HTTP request.
+     *
+     * @typeParam T - Expected result type for each call.
+     * @param requests - Array of `{ method, params }` objects.
+     * @param opts     - Per-call overrides (applied to the batch request).
+     * @returns Array of results in the same order as `requests`.
+     * @throws {TimeoutError} If the batch exceeds the timeout.
+     * @throws {NetworkError} On HTTP / network failures.
+     * @since 1.0.0
+     */
+    batch<T = unknown>(requests: {
+        method: string;
+        params?: unknown[];
+    }[], opts?: CallOptions): Promise<T[]>;
+    private send;
+    private throwRpcError;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/cjs/core/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/core/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAA2B,UAAU,EAAE,MAAM,SAAS,CAAC;AAMnE;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,mCAAmC;IACnC,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAChC,+BAA+B;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID;;;;;;;GAOG;AACH,qBAAa,aAAa;IAOZ,OAAO,CAAC,GAAG;IANvB,OAAO,CAAC,EAAE,CAAK;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;gBAE7B,GAAG,EAAE,eAAe;IAaxC;;;;;;;;;;;;;;;;OAgBG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;IAgCtG;;;;;;;;;;OAUG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAA;KAAE,EAAE,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;YAqCpG,IAAI;IAwBlB,OAAO,CAAC,aAAa;CAOtB"}