@rpckit/http 0.9.99

package/README.md

@@ -0,0 +1,82 @@
+# @rpckit/http
+
+HTTP transport for rpckit. Stateless JSON-RPC over HTTP POST with request batching.
+
+## Installation
+
+```bash
+npm install @rpckit/core @rpckit/http
+```
+
+## Usage
+
+```typescript
+import { http } from '@rpckit/http'
+
+const transport = http('https://example.com/rpc', {
+  headers: { 'Authorization': 'Bearer token' }
+})
+
+const result = await transport.request('my.method', 'param1')
+await transport.close()
+```
+
+## Electrum Cash Variant
+
+For Electrum Cash servers, use the `electrum-cash` subpath which pre-configures the `server.version` header:
+
+```typescript
+import { http } from '@rpckit/http/electrum-cash'
+
+const transport = http('https://electrum.example.com')
+const tip = await transport.request('blockchain.headers.get_tip')
+```
+
+The electrum-cash variant also accepts:
+
+- `clientName` - Client name sent in server.version header (default: `'rpckit'`)
+- `protocolVersion` - Protocol version (default: `'1.6'`)
+
+## Ethereum Variant
+
+For Ethereum JSON-RPC nodes, use the `ethereum` subpath:
+
+```typescript
+import { http } from '@rpckit/http/ethereum'
+
+const transport = http('https://ethereum-rpc.publicnode.com')
+
+const blockNumber = await transport.request('eth_blockNumber')
+const balance = await transport.request('eth_getBalance', '0x...', 'latest')
+```
+
+## Options
+
+- `timeout` - Request timeout in ms
+- `headers` - Custom HTTP headers
+- `retryCount` - Max retry attempts (default: 3)
+- `retryDelay` - Base delay between retries in ms (default: 150, exponential backoff applied)
+- `batch` - `true` (default), `false`, or `{ wait, batchSize }`
+- `fetchFn` - Custom fetch implementation (e.g., `node-fetch`, `undici`)
+- `fetchOptions` - Extra options passed to fetch (excluding `method`, `headers`, `body`, `signal`)
+- `onRequest` - Callback before each request: `({ url, body }) => void`
+- `onResponse` - Callback after each response: `({ status, body }) => void`
+- `raw` - Return full RPC response objects instead of unwrapping results (default: `false`)
+
+## Raw Mode
+
+When `raw: true`, responses include the full JSON-RPC envelope:
+
+```typescript
+const transport = http('https://example.com', { raw: true })
+
+const response = await transport.request('server.version')
+// { jsonrpc: '2.0', result: ['Server', '1.4'], id: 1 }
+
+// Errors are returned as results instead of thrown:
+// { jsonrpc: '2.0', error: { code: -1, message: '...' }, id: 2 }
+```
+
+## Note
+
+HTTP transport does not support subscriptions. Use WebSocket or TCP for subscription methods.

package/dist/electrum-cash/http.d.ts

@@ -0,0 +1,10 @@
+import type { AnySchema, HttpTransportConfig, Schema, Transport } from '@rpckit/core';
+export interface ElectrumHttpConfig extends HttpTransportConfig {
+    /** Client name sent in server.version header (default: 'rpckit') */
+    clientName?: string;
+    /** Electrum protocol version (default: '1.6') */
+    protocolVersion?: string;
+}
+export declare function http<S extends Schema = AnySchema>(url: string, options?: Omit<ElectrumHttpConfig, 'url'>): Transport<S>;
+export declare function http<S extends Schema = AnySchema>(config: ElectrumHttpConfig): Transport<S>;
+//# sourceMappingURL=http.d.ts.map

package/dist/electrum-cash/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/electrum-cash/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,mBAAmB,EACnB,MAAM,EACN,SAAS,EACV,MAAM,cAAc,CAAA;AAGrB,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iDAAiD;IACjD,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,GAAG,SAAS,EAC/C,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,GACxC,SAAS,CAAC,CAAC,CAAC,CAAA;AACf,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,GAAG,SAAS,EAC/C,MAAM,EAAE,kBAAkB,GACzB,SAAS,CAAC,CAAC,CAAC,CAAA"}

package/dist/electrum-cash/http.js

@@ -0,0 +1,15 @@
+import { http as baseHttp } from '../http.js';
+export function http(configOrUrl, options) {
+    const base = typeof configOrUrl === 'string'
+        ? { ...options, url: configOrUrl }
+        : configOrUrl;
+    const { clientName = 'rpckit', protocolVersion = '1.6', ...rest } = base;
+    return baseHttp({
+        ...rest,
+        headers: {
+            'server.version': `["${clientName}", "${protocolVersion}"]`,
+            ...rest.headers,
+        },
+    });
+}
+//# sourceMappingURL=http.js.map

package/dist/electrum-cash/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/electrum-cash/http.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,YAAY,CAAA;AAgB7C,MAAM,UAAU,IAAI,CAClB,WAAwC,EACxC,OAAyC;IAEzC,MAAM,IAAI,GACR,OAAO,WAAW,KAAK,QAAQ;QAC7B,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE;QAClC,CAAC,CAAC,WAAW,CAAA;IAEjB,MAAM,EAAE,UAAU,GAAG,QAAQ,EAAE,eAAe,GAAG,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAA;IAExE,OAAO,QAAQ,CAAI;QACjB,GAAG,IAAI;QACP,OAAO,EAAE;YACP,gBAAgB,EAAE,KAAK,UAAU,OAAO,eAAe,IAAI;YAC3D,GAAG,IAAI,CAAC,OAAO;SAChB;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/electrum-cash/index.d.ts

@@ -0,0 +1,3 @@
+export type { ElectrumHttpConfig } from './http.js';
+export { http } from './http.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/electrum-cash/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/electrum-cash/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA"}

package/dist/electrum-cash/index.js

@@ -0,0 +1,2 @@
+export { http } from './http.js';
+//# sourceMappingURL=index.js.map

package/dist/electrum-cash/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/electrum-cash/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA"}

package/dist/ethereum/http.d.ts

@@ -0,0 +1,16 @@
+import type { AnySchema, HttpTransportConfig, Schema, Transport } from '@rpckit/core';
+export interface EthereumHttpConfig extends HttpTransportConfig {
+}
+/**
+ * HTTP transport configured for Ethereum JSON-RPC.
+ *
+ * This is a thin wrapper over the base HTTP transport.
+ * Ethereum doesn't require special HTTP handling, but this variant
+ * is provided for consistency with the WebSocket variant.
+ *
+ * Note: HTTP transport does not support subscriptions.
+ * Use the WebSocket variant for `eth_subscribe`.
+ */
+export declare function http<S extends Schema = AnySchema>(url: string, options?: Omit<EthereumHttpConfig, 'url'>): Transport<S>;
+export declare function http<S extends Schema = AnySchema>(config: EthereumHttpConfig): Transport<S>;
+//# sourceMappingURL=http.d.ts.map

package/dist/ethereum/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/ethereum/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,mBAAmB,EACnB,MAAM,EACN,SAAS,EACV,MAAM,cAAc,CAAA;AAGrB,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;CAAG;AAElE;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,GAAG,SAAS,EAC/C,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,GACxC,SAAS,CAAC,CAAC,CAAC,CAAA;AACf,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,GAAG,SAAS,EAC/C,MAAM,EAAE,kBAAkB,GACzB,SAAS,CAAC,CAAC,CAAC,CAAA"}

package/dist/ethereum/http.js

@@ -0,0 +1,8 @@
+import { http as baseHttp } from '../http.js';
+export function http(configOrUrl, options) {
+    const config = typeof configOrUrl === 'string'
+        ? { ...options, url: configOrUrl }
+        : configOrUrl;
+    return baseHttp(config);
+}
+//# sourceMappingURL=http.js.map

package/dist/ethereum/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/ethereum/http.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,YAAY,CAAA;AAqB7C,MAAM,UAAU,IAAI,CAClB,WAAwC,EACxC,OAAyC;IAEzC,MAAM,MAAM,GACV,OAAO,WAAW,KAAK,QAAQ;QAC7B,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE;QAClC,CAAC,CAAC,WAAW,CAAA;IAEjB,OAAO,QAAQ,CAAI,MAAM,CAAC,CAAA;AAC5B,CAAC"}

package/dist/ethereum/index.d.ts

@@ -0,0 +1,3 @@
+export type { EthereumHttpConfig } from './http.js';
+export { http } from './http.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ethereum/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ethereum/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA"}

package/dist/ethereum/index.js

@@ -0,0 +1,2 @@
+export { http } from './http.js';
+//# sourceMappingURL=index.js.map

package/dist/ethereum/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ethereum/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA"}

package/dist/http.d.ts

@@ -0,0 +1,4 @@
+import { type AnySchema, type HttpTransportConfig, type Schema, type Transport } from '@rpckit/core';
+export declare function http<S extends Schema = AnySchema>(url: string, options?: Omit<HttpTransportConfig, 'url'>): Transport<S>;
+export declare function http<S extends Schema = AnySchema>(config: HttpTransportConfig): Transport<S>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EAEd,KAAK,mBAAmB,EAGxB,KAAK,MAAM,EACX,KAAK,SAAS,EAEf,MAAM,cAAc,CAAA;AAErB,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,GAAG,SAAS,EAC/C,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,KAAK,CAAC,GACzC,SAAS,CAAC,CAAC,CAAC,CAAA;AACf,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,GAAG,SAAS,EAC/C,MAAM,EAAE,mBAAmB,GAC1B,SAAS,CAAC,CAAC,CAAC,CAAA"}

package/dist/http.js

@@ -0,0 +1,58 @@
+import { BatchScheduler, withRetry, } from '@rpckit/core';
+export function http(configOrUrl, options) {
+    const config = typeof configOrUrl === 'string'
+        ? { ...options, url: configOrUrl }
+        : configOrUrl;
+    let nextId = 1;
+    const batchScheduler = new BatchScheduler({
+        ...(typeof config.batch === 'object' ? config.batch : {}),
+        raw: config.raw,
+    }, sendBatch);
+    const fetchFn = config.fetchFn ?? fetch;
+    async function sendBatch(requests) {
+        const body = requests.length === 1 ? requests[0] : requests;
+        return withRetry(async () => {
+            config.onRequest?.({ url: config.url, body });
+            const res = await fetchFn(config.url, {
+                ...config.fetchOptions,
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', ...config.headers },
+                body: JSON.stringify(body),
+                signal: config.timeout
+                    ? AbortSignal.timeout(config.timeout)
+                    : undefined,
+            });
+            if (!res.ok) {
+                // Try to get error details from response body
+                let errorBody = '';
+                try {
+                    errorBody = await res.text();
+                }
+                catch {
+                    // Ignore if we can't read the body
+                }
+                throw new Error(`HTTP ${res.status}: ${res.statusText}${errorBody ? ` - ${errorBody}` : ''}`);
+            }
+            const json = await res.json();
+            const responses = Array.isArray(json) ? json : [json];
+            config.onResponse?.({ status: res.status, body: json });
+            return responses;
+        }, { retryCount: config.retryCount, retryDelay: config.retryDelay });
+    }
+    return {
+        url: config.url,
+        async connect() { },
+        async request(method, ...params) {
+            const id = nextId++;
+            const request = { jsonrpc: '2.0', method, params, id };
+            return batchScheduler.enqueue(request);
+        },
+        async subscribe() {
+            throw new Error('HTTP transport does not support subscriptions');
+        },
+        async close() {
+            await batchScheduler.flush();
+        },
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { http } from './http.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { http } from './http.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@rpckit/http",
+  "version": "0.9.99",
+  "description": "HTTP transport for rpckit with request batching",
+  "author": "mainnet_pat",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./electrum-cash": {
+      "types": "./dist/electrum-cash/index.d.ts",
+      "default": "./dist/electrum-cash/index.js"
+    },
+    "./ethereum": {
+      "types": "./dist/ethereum/index.d.ts",
+      "default": "./dist/ethereum/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "json-rpc",
+    "rpc",
+    "http",
+    "electrum",
+    "electrum-cash",
+    "ethereum",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mainnet-pat/rpckit.git",
+    "directory": "packages/http"
+  },
+  "homepage": "https://rpckit.dev",
+  "bugs": {
+    "url": "https://github.com/mainnet-pat/rpckit/issues"
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@rpckit/core": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}