@kontor/kontor-sdk 1.0.0-alpha.0

package/src/sdk/clients/transports/create-http-transport.ts

@@ -0,0 +1,85 @@
+//src/sdk/clients/transports/base-http.tssrc/sdk/clients/transports/base-http.ts
+import type { Chain } from "../../types/chain.js";
+import type { HttpClientConfig } from "../base/create-http-client.js";
+import { uid as uid_ } from "../../utils/uid.js";
+import type { ErrorType } from "../../errors/utils.js";
+import { buildHttpRequest } from "../../utils/build-http-request.js";
+
+export type CreateTransportErrorType = ErrorType;
+
+export type HttpTransportConfig<
+  type extends string = string,
+  RequestFn extends (args: any) => Promise<any> = (args: any) => Promise<any>,
+> = {
+  /** The name of the transport. */
+  name: string;
+  /** The key of the transport. */
+  key: string;
+  /** The underlying request function (shape is generic). */
+  request: RequestFn;
+  /** The base delay (in ms) between retries. */
+  retryDelay?: number | undefined;
+  /** The max number of times to retry. */
+  retryCount?: number | undefined;
+  /** The timeout (in ms) for requests. */
+  timeout?: number | undefined;
+  /** The type of the transport. */
+  type: type;
+};
+
+export type HttpTransport<
+  type extends string = string,
+  rpcAttributes = Record<string, any>,
+  RequestFn extends (args: any) => Promise<any> = (args: any) => Promise<any>,
+> = <chain extends Chain | undefined = Chain>({
+  chain,
+}: {
+  chain?: chain | undefined;
+  pollingInterval?: HttpClientConfig["pollingInterval"] | undefined;
+  retryCount?: HttpTransportConfig["retryCount"] | undefined;
+  timeout?: HttpTransportConfig["timeout"] | undefined;
+}) => {
+  config: HttpTransportConfig<type, RequestFn>;
+  request: RequestFn;
+  value?: rpcAttributes | undefined;
+};
+
+export function createHttpTransport<
+  type extends string,
+  rpcAttributes extends Record<string, any>,
+  RequestFn extends (args: any) => Promise<any>,
+>(
+  {
+    key,
+    name,
+    request,
+    retryCount = 3,
+    retryDelay = 150,
+    timeout,
+    type,
+  }: HttpTransportConfig<type, RequestFn>,
+  value?: rpcAttributes | undefined,
+): ReturnType<HttpTransport<type, rpcAttributes, RequestFn>> {
+  const uid = uid_();
+
+  const wrappedRequest = buildHttpRequest(request, {
+    retryCount,
+    retryDelay,
+    uid,
+  });
+
+  return {
+    config: {
+      key,
+      name,
+      request,
+      retryCount,
+      retryDelay,
+      timeout,
+      type,
+    },
+    // Note: the *wrapped* one is exposed here.
+    request: wrappedRequest as RequestFn,
+    value,
+  };
+}

package/src/sdk/clients/transports/create-rpc-transport.test.ts

@@ -0,0 +1,66 @@
+import { assertType, expect, test, vi } from "vitest";
+import { createRpcTransport } from "./create-rpc-transport.js";
+import type { RpcRequestFn, RpcSchema } from "../../types/rpc-schema.js";
+
+test("default", () => {
+  const transport = createRpcTransport({
+    key: "mock",
+    name: "Mock Transport",
+    request: vi.fn(async () => null) as unknown as RpcRequestFn<RpcSchema>,
+    type: "mock",
+  });
+
+  assertType<"mock">(transport.config.type);
+
+  expect(transport).toMatchInlineSnapshot(`
+    {
+      "config": {
+        "key": "mock",
+        "methods": undefined,
+        "name": "Mock Transport",
+        "request": [MockFunction],
+        "retryCount": 3,
+        "retryDelay": 150,
+        "timeout": undefined,
+        "type": "mock",
+      },
+      "request": [Function],
+      "value": undefined,
+    }
+  `);
+});
+
+test("value", () => {
+  const transport = createRpcTransport(
+    {
+      key: "mock",
+      name: "Mock Transport",
+      request: vi.fn(async () => null) as unknown as RpcRequestFn<RpcSchema>,
+      type: "mock",
+    },
+    {
+      foo: "bar",
+      baz: "foo",
+    },
+  );
+
+  expect(transport).toMatchInlineSnapshot(`
+    {
+      "config": {
+        "key": "mock",
+        "methods": undefined,
+        "name": "Mock Transport",
+        "request": [MockFunction],
+        "retryCount": 3,
+        "retryDelay": 150,
+        "timeout": undefined,
+        "type": "mock",
+      },
+      "request": [Function],
+      "value": {
+        "baz": "foo",
+        "foo": "bar",
+      },
+    }
+  `);
+});

package/src/sdk/clients/transports/create-rpc-transport.ts

@@ -0,0 +1,91 @@
+// rpc-transport.ts
+import type { OneOf } from "../../../wit/type-utils.js";
+import type { RpcRequestFn, RpcSchema } from "../../types/rpc-schema.js";
+import { buildRpcRequest } from "../../utils/build-rpc-request.js";
+import {
+  type HttpTransportConfig,
+  type HttpTransport,
+  createHttpTransport,
+} from "./create-http-transport.js";
+import { uid as uid_ } from "../../utils/uid.js";
+import type { ErrorType } from "../../errors/utils.js";
+
+export type CreateRpcTransportErrorType = ErrorType;
+
+export type RpcTransportConfig<
+  type extends string = string,
+  Schema extends RpcSchema | undefined = RpcSchema,
+> = HttpTransportConfig<type, RpcRequestFn<Schema>> & {
+  /** Methods to include or exclude from executing RPC requests. */
+  methods?:
+    | OneOf<
+        | {
+            include?: string[] | undefined;
+          }
+        | {
+            exclude?: string[] | undefined;
+          }
+      >
+    | undefined;
+};
+
+export type RpcTransport<
+  type extends string = string,
+  rpcAttributes = Record<string, any>,
+  Schema extends RpcSchema | undefined = RpcSchema,
+> = HttpTransport<type, rpcAttributes, RpcRequestFn<Schema>>;
+
+export function createRpcTransport<
+  type extends string,
+  rpcAttributes extends Record<string, any>,
+  Schema extends RpcSchema | undefined = RpcSchema,
+>(
+  {
+    key,
+    methods,
+    name,
+    request,
+    retryCount = 3,
+    retryDelay = 150,
+    timeout,
+    type,
+  }: RpcTransportConfig<type, Schema>,
+  value?: rpcAttributes | undefined,
+): ReturnType<RpcTransport<type, rpcAttributes, Schema>> {
+  const uid = uid_();
+
+  // Wrap the low-level request with RPC-specific behavior
+  const rpcRequest = buildRpcRequest<RpcRequestFn<Schema>, Schema>(request, {
+    methods,
+    retryCount,
+    retryDelay,
+    uid,
+  });
+
+  // Use the base factory, but pass the *original* request into config
+  // (so config describes the underlying primitive), and expose the
+  // RPC-wrapped `rpcRequest` externally.
+  const base = createHttpTransport<type, rpcAttributes, RpcRequestFn<Schema>>(
+    {
+      key,
+      name,
+      request,
+      retryCount,
+      retryDelay,
+      timeout,
+      type,
+    },
+    value,
+  );
+
+  return {
+    ...base,
+    request: rpcRequest,
+    config: {
+      ...base.config,
+      // carry methods along in config if you want
+      // @ts-expect-error – config type doesn’t know about methods by default
+      methods,
+    },
+  };
+}

package/src/sdk/clients/transports/custom.ts

@@ -0,0 +1,54 @@
+import type { ErrorType } from "../../errors/utils.js";
+import type { WBIP001Schema } from "../../types/wbip001.js";
+import {
+  type CreateRpcTransportErrorType,
+  createRpcTransport,
+  type RpcTransport,
+  type RpcTransportConfig,
+} from "./create-rpc-transport.js";
+
+type WBIP001Provider = { request(...args: any): Promise<any> };
+
+export type CustomTransportConfig = {
+  /** The key of the transport. */
+  key?: RpcTransportConfig["key"] | undefined;
+  /** Methods to include or exclude from executing RPC requests. */
+  methods?: RpcTransportConfig["methods"] | undefined;
+  /** The name of the transport. */
+  name?: RpcTransportConfig["name"] | undefined;
+  /** The max number of times to retry. */
+  retryCount?: RpcTransportConfig["retryCount"] | undefined;
+  /** The base delay (in ms) between retries. */
+  retryDelay?: RpcTransportConfig["retryDelay"] | undefined;
+};
+
+export type CustomTransport = RpcTransport<
+  "custom",
+  {},
+  WBIP001Schema
+  // WBIP001Provider["request"]
+>;
+
+export type CustomTransportErrorType = CreateRpcTransportErrorType | ErrorType;
+
+export function custom<provider extends WBIP001Provider>(
+  provider: provider,
+  config: CustomTransportConfig = {},
+): CustomTransport {
+  const {
+    key = "custom",
+    methods,
+    name = "Custom Provider",
+    retryDelay,
+  } = config;
+  return ({ retryCount: defaultRetryCount }) =>
+    createRpcTransport({
+      key,
+      methods,
+      name,
+      request: provider.request.bind(provider),
+      retryCount: config.retryCount ?? defaultRetryCount,
+      retryDelay,
+      type: "custom",
+    });
+}

package/src/sdk/clients/transports/http-rpc.test.ts

@@ -0,0 +1,161 @@
+import { assertType, describe, expect, test } from "vitest";
+import { type HttpRpcTransport, httpRpc } from "./http-rpc.js";
+import { signet } from "../../chains/definitions/signet.js";
+
+test("default", () => {
+  const transport = httpRpc("https://mockapi.com/rpc");
+
+  assertType<HttpRpcTransport>(transport);
+  assertType<"http-rpc">(transport({}).config.type);
+
+  expect(transport({})).toMatchInlineSnapshot(`
+    {
+      "config": {
+        "key": "http",
+        "methods": undefined,
+        "name": "HTTP JSON-RPC",
+        "request": [Function],
+        "retryCount": 3,
+        "retryDelay": 150,
+        "timeout": 10000,
+        "type": "http-rpc",
+      },
+      "request": [Function],
+      "value": {
+        "fetchOptions": undefined,
+        "url": "https://mockapi.com/rpc",
+      },
+    }
+  `);
+});
+
+describe("config", () => {
+  test("key", () => {
+    const transport = httpRpc("https://mockapi.com/rpc", {
+      key: "mock",
+    })({});
+
+    expect(transport).toMatchInlineSnapshot(`
+      {
+        "config": {
+          "key": "mock",
+          "methods": undefined,
+          "name": "HTTP JSON-RPC",
+          "request": [Function],
+          "retryCount": 3,
+          "retryDelay": 150,
+          "timeout": 10000,
+          "type": "http-rpc",
+        },
+        "request": [Function],
+        "value": {
+          "fetchOptions": undefined,
+          "url": "https://mockapi.com/rpc",
+        },
+      }
+    `);
+  });
+
+  test("name", () => {
+    const transport = httpRpc("https://mockapi.com/rpc", {
+      name: "Mock Transport",
+    })({});
+
+    expect(transport).toMatchInlineSnapshot(`
+      {
+        "config": {
+          "key": "http",
+          "methods": undefined,
+          "name": "Mock Transport",
+          "request": [Function],
+          "retryCount": 3,
+          "retryDelay": 150,
+          "timeout": 10000,
+          "type": "http-rpc",
+        },
+        "request": [Function],
+        "value": {
+          "fetchOptions": undefined,
+          "url": "https://mockapi.com/rpc",
+        },
+      }
+    `);
+  });
+
+  test("url", () => {
+    const transport = httpRpc("https://mockapi.com/rpc")({});
+
+    expect(transport).toMatchInlineSnapshot(`
+      {
+        "config": {
+          "key": "http",
+          "methods": undefined,
+          "name": "HTTP JSON-RPC",
+          "request": [Function],
+          "retryCount": 3,
+          "retryDelay": 150,
+          "timeout": 10000,
+          "type": "http-rpc",
+        },
+        "request": [Function],
+        "value": {
+          "fetchOptions": undefined,
+          "url": "https://mockapi.com/rpc",
+        },
+      }
+    `);
+  });
+
+  test("fetchOptions", () => {
+    const transport = httpRpc("https://mockapi.com/rpc", {
+      fetchOptions: { headers: { Authorization: "wagmi" } },
+    })({});
+
+    expect(transport).toMatchInlineSnapshot(`
+      {
+        "config": {
+          "key": "http",
+          "methods": undefined,
+          "name": "HTTP JSON-RPC",
+          "request": [Function],
+          "retryCount": 3,
+          "retryDelay": 150,
+          "timeout": 10000,
+          "type": "http-rpc",
+        },
+        "request": [Function],
+        "value": {
+          "fetchOptions": {
+            "headers": {
+              "Authorization": "wagmi",
+            },
+          },
+          "url": "https://mockapi.com/rpc",
+        },
+      }
+    `);
+  });
+});
+
+describe("request", () => {
+  test("default", async () => {
+    const transport = httpRpc(undefined, {
+      key: "jsonRpc",
+      name: "JSON RPC",
+      fetchOptions: {
+        headers: {
+          Authorization: `Basic ${Buffer.from("rpc:rpc").toString("base64")}`,
+        },
+      },
+    })({
+      // TODO: probably a better idea to make calls against a local instance here
+      chain: {
+        ...signet,
+      },
+    });
+
+    expect(
+      await transport.request({ method: "getblockchaininfo" }),
+    ).toBeDefined();
+  });
+});

package/src/sdk/clients/transports/http-rpc.ts

@@ -0,0 +1,183 @@
+import { RpcRequestError } from "../../errors/request.js";
+import {
+  UrlRequiredError,
+  type UrlRequiredErrorType,
+} from "../../errors/transport.js";
+import type { ErrorType } from "../../errors/utils.js";
+import type { RpcSchema } from "../../types/rpc-schema.js";
+import type { RpcRequest } from "../../types/rpc.js";
+// import { createBatchScheduler } from '../../utils/promise/createBatchScheduler.js'
+import {
+  getHttpRpcClient,
+  type HttpRpcClientOptions,
+} from "../../utils/rpc/http.js";
+
+import {
+  type CreateRpcTransportErrorType,
+  createRpcTransport,
+  type RpcTransport,
+  type RpcTransportConfig,
+} from "./create-rpc-transport.js";
+
+export type HttpRpcTransportConfig<
+  rpcSchema extends RpcSchema | undefined = undefined,
+  // raw extends boolean = false,
+> = {
+  /**
+   * Whether to enable Batch JSON-RPC.
+   * @link https://www.jsonrpc.org/specification#batch
+   */
+  // batch?:
+  //   | boolean
+  //   | {
+  //       /** The maximum number of JSON-RPC requests to send in a batch. @default 1_000 */
+  //       batchSize?: number | undefined;
+  //       /** The maximum number of milliseconds to wait before sending a batch. @default 0 */
+  //       wait?: number | undefined;
+  //     }
+  //   | undefined;
+
+  fetchFn?: HttpRpcClientOptions["fetchFn"] | undefined;
+  /**
+   * Request configuration to pass to `fetch`.
+   * @link https://developer.mozilla.org/en-US/docs/Web/API/fetch
+   */
+  fetchOptions?: HttpRpcClientOptions["fetchOptions"] | undefined;
+  /** A callback to handle the response from `fetch`. */
+  onFetchRequest?: HttpRpcClientOptions["onRequest"] | undefined;
+  /** A callback to handle the response from `fetch`. */
+  onFetchResponse?: HttpRpcClientOptions["onResponse"] | undefined;
+  /** The key of the HTTP transport. */
+  key?: RpcTransportConfig["key"] | undefined;
+  /** Methods to include or exclude from executing RPC requests. */
+  methods?: RpcTransportConfig["methods"] | undefined;
+  /** The name of the HTTP transport. */
+  name?: RpcTransportConfig["name"] | undefined;
+  /** Whether to return JSON RPC errors as responses instead of throwing. */
+  // raw?: raw | boolean | undefined;
+  /** The max number of times to retry. */
+  retryCount?: RpcTransportConfig["retryCount"] | undefined;
+  /** The base delay (in ms) between retries. */
+  retryDelay?: RpcTransportConfig["retryDelay"] | undefined;
+  /** Typed JSON-RPC schema for the transport. */
+  rpcSchema?: rpcSchema | RpcSchema | undefined;
+  /** The timeout (in ms) for the HTTP request. Default: 10_000 */
+  timeout?: RpcTransportConfig["timeout"] | undefined;
+};
+
+export type HttpRpcTransport<
+  rpcSchema extends RpcSchema | undefined = undefined,
+  // raw extends boolean = false,
+> = RpcTransport<
+  "http-rpc",
+  {
+    fetchOptions?: HttpRpcTransportConfig["fetchOptions"] | undefined;
+    url?: string | undefined;
+  },
+  rpcSchema
+>;
+
+export type HttpRpcTransportErrorType =
+  | CreateRpcTransportErrorType
+  | UrlRequiredErrorType
+  | ErrorType;
+
+/**
+ * @description Creates a HTTP transport that connects to a JSON-RPC API.
+ */
+export function httpRpc<
+  rpcSchema extends RpcSchema | undefined = undefined,
+  // raw extends boolean = false,
+>(
+  /** URL of the JSON-RPC API. Defaults to the chain's public RPC URL. */
+  url?: string | undefined,
+  config: HttpRpcTransportConfig<rpcSchema> = {},
+): HttpRpcTransport<rpcSchema> {
+  const {
+    // batch,
+    fetchFn,
+    fetchOptions,
+    key = "http",
+    methods,
+    name = "HTTP JSON-RPC",
+    onFetchRequest,
+    onFetchResponse,
+    retryDelay,
+    // raw,
+  } = config;
+  return ({ chain, retryCount: retryCount_, timeout: timeout_ }) => {
+    // const { batchSize = 1000, wait = 0 } =
+    //   typeof batch === "object" ? batch : {};
+    const retryCount = config.retryCount ?? retryCount_;
+    const timeout = timeout_ ?? config.timeout ?? 10_000;
+    const url_ = url || chain?.urls.default.bitcoinRpc[0];
+    if (!url_) throw new UrlRequiredError();
+
+    const rpcClient = getHttpRpcClient(url_, {
+      fetchFn,
+      fetchOptions,
+      onRequest: onFetchRequest,
+      onResponse: onFetchResponse,
+      timeout,
+    });
+
+    return createRpcTransport(
+      {
+        key,
+        methods,
+        name,
+        async request({ method, params }) {
+          const body = { method, params };
+
+          // const { schedule } = createBatchScheduler({
+          //   id: url_,
+          //   wait,
+          //   shouldSplitBatch(requests) {
+          //     return requests.length > batchSize;
+          //   },
+          //   fn: (body: RpcRequest[]) =>
+          //     rpcClient.request({
+          //       body,
+          //     }),
+          //   sort: (a, b) => a.id - b.id,
+          // });
+          //
+          // const fn = async (body: RpcRequest) =>
+          // batch
+          //   ? schedule(body)
+          //   : [
+          // [
+          //   await rpcClient.request({
+          //     body,
+          //   }),
+          // ];
+
+          // TODO: implement batching
+          const fn = async (body: RpcRequest) =>
+            await rpcClient.request({
+              body,
+            });
+
+          const { error, result } = await fn(body);
+
+          // if (raw) return { error, result };
+          if (error)
+            throw new RpcRequestError({
+              body,
+              error,
+              url: url_,
+            });
+          return result;
+        },
+        retryCount,
+        retryDelay,
+        timeout,
+        type: "http-rpc",
+      },
+      {
+        fetchOptions,
+        url: url_,
+      },
+    );
+  };
+}