@kontor/kontor-sdk 1.0.0-alpha.0

package/src/sdk/utils/get-action.ts

@@ -0,0 +1,69 @@
+import type { Account } from "../accounts/types.js";
+
+import type { RpcClient } from "../clients/base/create-rpc-client.js"; // TODO: this import seems wrong
+import type { KontorPublicActions } from "../clients/decorators/kontor/public.js";
+import type { PublicActions } from "../clients/decorators/public.js";
+// TODO: this probably needs to take a generic transport
+import type { RpcTransport } from "../clients/transports/create-rpc-transport.js";
+import type { Chain } from "../types/chain.js";
+import type { RpcSchema } from "../types/rpc-schema.js";
+import type { WalletActions } from "../clients/decorators/wallet.js";
+import type { HttpTransport } from "../clients/transports/create-http-transport.js";
+import type { HttpSchema } from "../types/http-schema.js";
+import type { HttpClient } from "../clients/base/create-http-client.js";
+
+export function getAction<
+  transport extends RpcTransport,
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  rpcSchema extends RpcSchema | undefined,
+  extended extends { [key: string]: unknown },
+  client extends RpcClient<transport, chain, account, rpcSchema, extended>,
+  parameters,
+  returnType,
+>(
+  client: client,
+  actionFn: (_: any, parameters: parameters) => returnType,
+  // Some minifiers drop `Function.prototype.name`, or replace it with short letters,
+  // meaning that `actionFn.name` will not always work. For that case, the consumer
+  // needs to pass the name explicitly.
+  name: keyof PublicActions | keyof WalletActions,
+): (parameters: parameters) => returnType {
+  const action_implicit = client[actionFn.name];
+  if (typeof action_implicit === "function")
+    return action_implicit as (params: parameters) => returnType;
+
+  const action_explicit = client[name];
+  if (typeof action_explicit === "function")
+    return action_explicit as (params: parameters) => returnType;
+
+  return (params) => actionFn(client, params);
+}
+
+export function getKontorAction<
+  transport extends HttpTransport,
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+  httpSchema extends HttpSchema | undefined,
+  extended extends { [key: string]: unknown },
+  client extends HttpClient<transport, chain, account, httpSchema, extended>,
+  parameters,
+  returnType,
+>(
+  client: client,
+  actionFn: (_: any, parameters: parameters) => returnType,
+  // Some minifiers drop `Function.prototype.name`, or replace it with short letters,
+  // meaning that `actionFn.name` will not always work. For that case, the consumer
+  // needs to pass the name explicitly.
+  name: keyof KontorPublicActions,
+): (parameters: parameters) => returnType {
+  const action_implicit = client[actionFn.name];
+  if (typeof action_implicit === "function")
+    return action_implicit as (params: parameters) => returnType;
+
+  const action_explicit = client[name];
+  if (typeof action_explicit === "function")
+    return action_explicit as (params: parameters) => returnType;
+
+  return (params) => actionFn(client, params);
+}

package/src/sdk/utils/http.ts

@@ -0,0 +1,271 @@
+import type { TimeoutErrorType } from "../errors/request.js";
+import type { ErrorType } from "../errors/utils.js";
+import type { MaybePromise } from "../types/utils.js";
+import {
+  withTimeout,
+  type WithTimeoutErrorType,
+} from "./promise/with-timeout.js";
+import {
+  HttpRequestError,
+  TimeoutError,
+  type HttpRequestErrorType as HttpRequestErrorType_,
+} from "../errors/request.js";
+import type {
+  BodyParams,
+  ExtractRouteEntry,
+  HttpSchema,
+  PathParams,
+  QueryParams,
+} from "../types/http-schema.js";
+import { stringify } from "./stringify.js";
+
+// TODO: these are identical to options defined in rpc/http.ts
+export type HttpClientOptions = {
+  /** Override for the fetch function used to make requests. */
+  fetchFn?:
+    | ((input: string | URL | Request, init?: RequestInit) => Promise<Response>)
+    | undefined;
+  /** Request configuration to pass to `fetch`. */
+  fetchOptions?: Omit<RequestInit, "body"> | undefined;
+  /** A callback to handle the request. */
+  onRequest?:
+    | ((
+        request: Request,
+        init: RequestInit,
+      ) => MaybePromise<
+        void | undefined | (RequestInit & { url?: string | undefined })
+      >)
+    | undefined;
+  /** A callback to handle the response. */
+  onResponse?: ((response: Response) => Promise<void> | void) | undefined;
+  /** The timeout (in ms) for the request. */
+  timeout?: number | undefined;
+};
+type IsRequired<T> = undefined extends T ? false : true;
+
+type NormalizePathParams<P> = P extends readonly (readonly [string, any])[]
+  ? { [K in P[number][0]]: Extract<P[number], readonly [K, any]>[1] }
+  : P extends PathParams
+    ? P
+    : never;
+
+type BuildRequestParams<Entry extends { Parameters?: any }> =
+  Entry["Parameters"] extends {
+    path?: infer Path;
+    query?: infer Query;
+    body?: infer Body;
+  }
+    ? (IsRequired<Path> extends true
+        ? { path: NormalizePathParams<Path> }
+        : { path?: NormalizePathParams<Path> }) &
+        (IsRequired<Query> extends true
+          ? { query: Query }
+          : { query?: Query }) &
+        (IsRequired<Body> extends true ? { body: Body } : { body?: Body })
+    : { path?: PathParams; query?: QueryParams; body?: BodyParams };
+
+export type HttpRequestParameters<
+  Schema extends HttpSchema,
+  Route extends Schema[number]["Route"],
+> = {
+  method: ExtractRouteEntry<Schema, Route>["Method"];
+  /** The route to request */
+  route: Route;
+  /** Override for the fetch function used to make requests. */
+  fetchFn?: HttpClientOptions["fetchFn"] | undefined;
+  /** Request configuration to pass to `fetch`. */
+  fetchOptions?: HttpClientOptions["fetchOptions"] | undefined;
+  /** A callback to handle the request. */
+  onRequest?: HttpClientOptions["onRequest"] | undefined;
+  /** A callback to handle the response. */
+  onResponse?: HttpClientOptions["onResponse"] | undefined;
+  /** The timeout (in ms) for the request. */
+  timeout?: HttpClientOptions["timeout"] | undefined;
+} & BuildRequestParams<ExtractRouteEntry<Schema, Route>>;
+
+export type HttpRequestReturnType<
+  Schema extends HttpSchema,
+  Route extends Schema[number]["Route"],
+> = ExtractRouteEntry<Schema, Route>["ReturnType"];
+
+export type HttpRpcRequestErrorType =
+  | HttpRequestErrorType_
+  | TimeoutErrorType
+  | WithTimeoutErrorType
+  | ErrorType;
+
+export type HttpClient<Schema extends HttpSchema> = {
+  request<Route extends Schema[number]["Route"]>(
+    params: HttpRequestParameters<Schema, Route>,
+  ): Promise<HttpRequestReturnType<Schema, Route>>;
+};
+// function getMethodForRoute<Schema extends HttpSchema>(
+//   schema: Schema,
+//   route: string,
+// ): HttpMethod {
+//   const entry = schema.find((e) => e.Route === route);
+//   return entry?.Method ?? "GET";
+// }
+
+function buildUrl(
+  baseUrl: string,
+  pathTemplate: string,
+  pathParams?: Record<string, string | number>,
+  queryParams?: Record<
+    string,
+    string | number | boolean | (string | number | boolean)[] | undefined
+  >,
+): string {
+  let path = pathTemplate;
+
+  // Replace path parameters
+  if (pathParams) {
+    for (const [key, value] of Object.entries(pathParams)) {
+      path = path.replace(`:${key}`, encodeURIComponent(String(value)));
+    }
+  }
+
+  // Start from baseUrl and manually join paths so we don't lose `/api`
+  const url = new URL(baseUrl);
+
+  const basePath = url.pathname.replace(/\/+$/, ""); // strip trailing slashes
+  const relPath = path.replace(/^\/+/, ""); // strip leading slashes
+
+  url.pathname = basePath ? `${basePath}/${relPath}` : `/${relPath}`;
+
+  // Add query parameters
+  if (queryParams) {
+    for (const [key, value] of Object.entries(queryParams)) {
+      if (value === undefined) continue;
+
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          url.searchParams.append(key, String(item));
+        }
+      } else {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+
+  return url.toString();
+}
+
+export function getHttpClient<Schema extends HttpSchema>(
+  baseUrl: string,
+  options: HttpClientOptions = {},
+): HttpClient<Schema> {
+  return {
+    async request(params) {
+      const {
+        route,
+        method,
+        path: pathParams,
+        query: queryParams,
+        body: bodyParams,
+        fetchFn = options.fetchFn ?? fetch,
+        onRequest = options.onRequest,
+        onResponse = options.onResponse,
+        timeout = options.timeout ?? 10_000,
+      } = params as any;
+
+      console.log({ route, method, pathParams, queryParams, bodyParams });
+
+      const fetchOptions = {
+        ...(options.fetchOptions ?? {}),
+        ...(params.fetchOptions ?? {}),
+      };
+
+      const { headers, signal: signal_ } = fetchOptions;
+      // const method = getMethodForRoute(schema, route);
+      const url = buildUrl(baseUrl, route, pathParams, queryParams);
+
+      console.log("\n\n\n");
+      console.log({ url });
+
+      try {
+        const response = await withTimeout(
+          async ({ signal }) => {
+            const init: RequestInit = {
+              ...fetchOptions,
+              method,
+              headers: {
+                ...(bodyParams !== undefined && {
+                  "Content-Type": "application/json",
+                }),
+                ...headers,
+              },
+              body: bodyParams !== undefined ? stringify(bodyParams) : null,
+              signal: signal_ || (timeout > 0 ? signal : null),
+            };
+
+            const request = new Request(url, init);
+            const args = (await onRequest?.(request, init)) ?? { ...init, url };
+            const response = await fetchFn(args.url ?? url, args);
+            return response;
+          },
+          {
+            errorInstance: new TimeoutError({
+              body: {
+                route,
+                path: pathParams,
+                query: queryParams,
+                body: bodyParams,
+              },
+              url,
+            }),
+            timeout,
+            signal: true,
+          },
+        );
+
+        if (onResponse) await onResponse(response);
+
+        let data: any;
+        if (
+          response.headers.get("Content-Type")?.startsWith("application/json")
+        )
+          data = await response.json();
+        else {
+          data = await response.text();
+          try {
+            data = JSON.parse(data || "{}");
+          } catch (err) {
+            if (response.ok) throw err;
+            data = { error: data };
+          }
+        }
+
+        if (!response.ok) {
+          throw new HttpRequestError({
+            body: {
+              route,
+              path: pathParams,
+              query: queryParams,
+              body: bodyParams,
+            },
+            details: stringify(data.error) || response.statusText,
+            headers: response.headers,
+            status: response.status,
+            url,
+          });
+        }
+
+        return data;
+      } catch (err) {
+        if (err instanceof HttpRequestError) throw err;
+        if (err instanceof TimeoutError) throw err;
+        throw new HttpRequestError({
+          body: {
+            route,
+            path: pathParams,
+            query: queryParams,
+            body: bodyParams,
+          },
+          cause: err as Error,
+          url,
+        });
+      }
+    },
+  };
+}

package/src/sdk/utils/lru.ts

@@ -0,0 +1,33 @@
+/**
+ * Map with a LRU (Least recently used) policy.
+ *
+ * @link https://en.wikipedia.org/wiki/Cache_replacement_policies#LRU
+ */
+export class LruMap<value = unknown> extends Map<string, value> {
+  maxSize: number;
+
+  constructor(size: number) {
+    super();
+    this.maxSize = size;
+  }
+
+  override get(key: string) {
+    const value = super.get(key);
+
+    if (super.has(key) && value !== undefined) {
+      this.delete(key);
+      super.set(key, value);
+    }
+
+    return value;
+  }
+
+  override set(key: string, value: value) {
+    super.set(key, value);
+    if (this.maxSize && this.size > this.maxSize) {
+      const firstKey = this.keys().next().value;
+      if (firstKey) this.delete(firstKey);
+    }
+    return this;
+  }
+}

package/src/sdk/utils/promise/create-batch-scheduler.ts

@@ -0,0 +1,113 @@
+import type { ErrorType } from "../../errors/utils.js";
+import { type PromiseWithResolvers, withResolvers } from "./with-resolvers.js";
+
+type Resolved<returnType extends readonly unknown[] = any> = [
+  result: returnType[number],
+  results: returnType,
+];
+
+type SchedulerItem = {
+  args: unknown;
+  resolve: PromiseWithResolvers<unknown>["resolve"];
+  reject: PromiseWithResolvers<unknown>["reject"];
+};
+
+type BatchResultsCompareFn<result = unknown> = (a: result, b: result) => number;
+
+type CreateBatchSchedulerArguments<
+  parameters = unknown,
+  returnType extends readonly unknown[] = readonly unknown[],
+> = {
+  fn: (args: parameters[]) => Promise<returnType>;
+  id: number | string;
+  shouldSplitBatch?: ((args: parameters[]) => boolean) | undefined;
+  wait?: number | undefined;
+  sort?: BatchResultsCompareFn<returnType[number]> | undefined;
+};
+
+type CreateBatchSchedulerReturnType<
+  parameters = unknown,
+  returnType extends readonly unknown[] = readonly unknown[],
+> = {
+  flush: () => void;
+  schedule: parameters extends undefined
+    ? (args?: parameters | undefined) => Promise<Resolved<returnType>>
+    : (args: parameters) => Promise<Resolved<returnType>>;
+};
+
+export type CreateBatchSchedulerErrorType = ErrorType;
+
+const schedulerCache = /*#__PURE__*/ new Map<
+  number | string,
+  SchedulerItem[]
+>();
+
+/** @internal */
+export function createBatchScheduler<
+  parameters,
+  returnType extends readonly unknown[],
+>({
+  fn,
+  id,
+  shouldSplitBatch,
+  wait = 0,
+  sort,
+}: CreateBatchSchedulerArguments<
+  parameters,
+  returnType
+>): CreateBatchSchedulerReturnType<parameters, returnType> {
+  const exec = async () => {
+    const scheduler = getScheduler();
+    flush();
+
+    const args = scheduler.map(({ args }) => args);
+
+    if (args.length === 0) return;
+
+    fn(args as parameters[])
+      .then((data) => {
+        if (sort && Array.isArray(data)) data.sort(sort);
+        for (let i = 0; i < scheduler.length; i++) {
+          const { resolve } = scheduler[i]!;
+          resolve?.([data[i], data]);
+        }
+      })
+      .catch((err) => {
+        for (let i = 0; i < scheduler.length; i++) {
+          const { reject } = scheduler[i]!;
+          reject?.(err);
+        }
+      });
+  };
+
+  const flush = () => schedulerCache.delete(id);
+
+  const getBatchedArgs = () =>
+    getScheduler().map(({ args }) => args) as parameters[];
+
+  const getScheduler = () => schedulerCache.get(id) || [];
+
+  const setScheduler = (item: SchedulerItem) =>
+    schedulerCache.set(id, [...getScheduler(), item]);
+
+  return {
+    flush,
+    async schedule(args: parameters) {
+      const { promise, resolve, reject } = withResolvers();
+
+      const split = shouldSplitBatch?.([...getBatchedArgs(), args]);
+
+      if (split) exec();
+
+      const hasActiveScheduler = getScheduler().length > 0;
+      if (hasActiveScheduler) {
+        setScheduler({ args, resolve, reject });
+        return promise;
+      }
+
+      setScheduler({ args, resolve, reject });
+      setTimeout(exec, wait);
+      return promise;
+    },
+  } as unknown as CreateBatchSchedulerReturnType<parameters, returnType>;
+}

package/src/sdk/utils/promise/with-dedupe.ts

@@ -0,0 +1,21 @@
+import { LruMap } from "../lru.js";
+
+/** @internal */
+export const promiseCache = /*#__PURE__*/ new LruMap<Promise<any>>(8192);
+
+type WithDedupeOptions = {
+  enabled?: boolean | undefined;
+  id?: string | undefined;
+};
+
+/** Deduplicates in-flight promises. */
+export function withDedupe<data>(
+  fn: () => Promise<data>,
+  { enabled = true, id }: WithDedupeOptions,
+): Promise<data> {
+  if (!enabled || !id) return fn();
+  if (promiseCache.get(id)) return promiseCache.get(id)!;
+  const promise = fn().finally(() => promiseCache.delete(id));
+  promiseCache.set(id, promise);
+  return promise;
+}

package/src/sdk/utils/promise/with-resolvers.ts

@@ -0,0 +1,17 @@
+export type PromiseWithResolvers<type> = {
+  promise: Promise<type>;
+  resolve: (value: type | PromiseLike<type>) => void;
+  reject: (reason?: unknown) => void;
+};
+
+export function withResolvers<type>(): PromiseWithResolvers<type> {
+  let resolve: PromiseWithResolvers<type>["resolve"] = () => undefined;
+  let reject: PromiseWithResolvers<type>["reject"] = () => undefined;
+
+  const promise = new Promise<type>((resolve_, reject_) => {
+    resolve = resolve_;
+    reject = reject_;
+  });
+
+  return { promise, resolve, reject };
+}

package/src/sdk/utils/promise/with-retry.ts

@@ -0,0 +1,57 @@
+import type { ErrorType } from "../../errors/utils.js";
+import { wait } from "../wait.js";
+
+export type WithRetryParameters = {
+  // The delay (in ms) between retries.
+  delay?:
+    | ((config: { count: number; error: Error }) => number)
+    | number
+    | undefined;
+  // The max number of times to retry.
+  retryCount?: number | undefined;
+  // Whether or not to retry when an error is thrown.
+  shouldRetry?:
+    | (({
+        count,
+        error,
+      }: {
+        count: number;
+        error: Error;
+      }) => Promise<boolean> | boolean)
+    | undefined;
+};
+
+export type WithRetryErrorType = ErrorType;
+
+export function withRetry<data>(
+  fn: () => Promise<data>,
+  {
+    delay: delay_ = 100,
+    retryCount = 2,
+    shouldRetry = () => true,
+  }: WithRetryParameters = {},
+) {
+  return new Promise<data>((resolve, reject) => {
+    const attemptRetry = async ({ count = 0 } = {}) => {
+      const retry = async ({ error }: { error: Error }) => {
+        const delay =
+          typeof delay_ === "function" ? delay_({ count, error }) : delay_;
+        if (delay) await wait(delay);
+        attemptRetry({ count: count + 1 });
+      };
+
+      try {
+        const data = await fn();
+        resolve(data);
+      } catch (err) {
+        if (
+          count < retryCount &&
+          (await shouldRetry({ count, error: err as Error }))
+        )
+          return retry({ error: err as Error });
+        reject(err);
+      }
+    };
+    attemptRetry();
+  });
+}

package/src/sdk/utils/promise/with-timeout.ts

@@ -0,0 +1,47 @@
+import type { ErrorType } from "../../errors/utils.js";
+
+export type WithTimeoutErrorType = ErrorType;
+
+export function withTimeout<data>(
+  fn: ({
+    signal,
+  }: {
+    signal: AbortController["signal"] | null;
+  }) => Promise<data>,
+  {
+    errorInstance = new Error("timed out"),
+    timeout,
+    signal,
+  }: {
+    // The error instance to throw when the timeout is reached.
+    errorInstance?: Error | undefined;
+    // The timeout (in ms).
+    timeout: number;
+    // Whether or not the timeout should use an abort signal.
+    signal?: boolean | undefined;
+  },
+): Promise<data> {
+  return new Promise((resolve, reject) => {
+    (async () => {
+      let timeoutId!: NodeJS.Timeout;
+      try {
+        const controller = new AbortController();
+        if (timeout > 0) {
+          timeoutId = setTimeout(() => {
+            if (signal) {
+              controller.abort();
+            } else {
+              reject(errorInstance);
+            }
+          }, timeout) as NodeJS.Timeout; // need to cast because bun globals.d.ts overrides @types/node
+        }
+        resolve(await fn({ signal: controller?.signal || null }));
+      } catch (err) {
+        if ((err as Error)?.name === "AbortError") reject(errorInstance);
+        reject(err);
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    })();
+  });
+}