alchemy 0.67.0 → 0.68.0

package/src/util/api/core/types.gen.ts

@@ -0,0 +1,118 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import type { Auth, AuthToken } from './auth.gen';
+import type {
+  BodySerializer,
+  QuerySerializer,
+  QuerySerializerOptions,
+} from './bodySerializer.gen';
+
+export type HttpMethod =
+  | 'connect'
+  | 'delete'
+  | 'get'
+  | 'head'
+  | 'options'
+  | 'patch'
+  | 'post'
+  | 'put'
+  | 'trace';
+
+export type Client<
+  RequestFn = never,
+  Config = unknown,
+  MethodFn = never,
+  BuildUrlFn = never,
+  SseFn = never,
+> = {
+  /**
+   * Returns the final request URL.
+   */
+  buildUrl: BuildUrlFn;
+  getConfig: () => Config;
+  request: RequestFn;
+  setConfig: (config: Config) => Config;
+} & {
+  [K in HttpMethod]: MethodFn;
+} & ([SseFn] extends [never]
+    ? { sse?: never }
+    : { sse: { [K in HttpMethod]: SseFn } });
+
+export interface Config {
+  /**
+   * Auth token or a function returning auth token. The resolved value will be
+   * added to the request payload as defined by its `security` array.
+   */
+  auth?: ((auth: Auth) => Promise<AuthToken> | AuthToken) | AuthToken;
+  /**
+   * A function for serializing request body parameter. By default,
+   * {@link JSON.stringify()} will be used.
+   */
+  bodySerializer?: BodySerializer | null;
+  /**
+   * An object containing any HTTP headers that you want to pre-populate your
+   * `Headers` object with.
+   *
+   * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more}
+   */
+  headers?:
+    | RequestInit['headers']
+    | Record<
+        string,
+        | string
+        | number
+        | boolean
+        | (string | number | boolean)[]
+        | null
+        | undefined
+        | unknown
+      >;
+  /**
+   * The request method.
+   *
+   * {@link https://developer.mozilla.org/docs/Web/API/fetch#method See more}
+   */
+  method?: Uppercase<HttpMethod>;
+  /**
+   * A function for serializing request query parameters. By default, arrays
+   * will be exploded in form style, objects will be exploded in deepObject
+   * style, and reserved characters are percent-encoded.
+   *
+   * This method will have no effect if the native `paramsSerializer()` Axios
+   * API function is used.
+   *
+   * {@link https://swagger.io/docs/specification/serialization/#query View examples}
+   */
+  querySerializer?: QuerySerializer | QuerySerializerOptions;
+  /**
+   * A function validating request data. This is useful if you want to ensure
+   * the request conforms to the desired shape, so it can be safely sent to
+   * the server.
+   */
+  requestValidator?: (data: unknown) => Promise<unknown>;
+  /**
+   * A function transforming response data before it's returned. This is useful
+   * for post-processing data, e.g. converting ISO strings into Date objects.
+   */
+  responseTransformer?: (data: unknown) => Promise<unknown>;
+  /**
+   * A function validating response data. This is useful if you want to ensure
+   * the response conforms to the desired shape, so it can be safely passed to
+   * the transformers and returned to the user.
+   */
+  responseValidator?: (data: unknown) => Promise<unknown>;
+}
+
+type IsExactlyNeverOrNeverUndefined<T> = [T] extends [never]
+  ? true
+  : [T] extends [never | undefined]
+    ? [undefined] extends [T]
+      ? false
+      : true
+    : false;
+
+export type OmitNever<T extends Record<string, unknown>> = {
+  [K in keyof T as IsExactlyNeverOrNeverUndefined<T[K]> extends true
+    ? never
+    : K]: T[K];
+};

package/src/util/api/core/utils.gen.ts

@@ -0,0 +1,143 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import type { BodySerializer, QuerySerializer } from './bodySerializer.gen';
+import {
+  type ArraySeparatorStyle,
+  serializeArrayParam,
+  serializeObjectParam,
+  serializePrimitiveParam,
+} from './pathSerializer.gen';
+
+export interface PathSerializer {
+  path: Record<string, unknown>;
+  url: string;
+}
+
+export const PATH_PARAM_RE = /\{[^{}]+\}/g;
+
+export const defaultPathSerializer = ({ path, url: _url }: PathSerializer) => {
+  let url = _url;
+  const matches = _url.match(PATH_PARAM_RE);
+  if (matches) {
+    for (const match of matches) {
+      let explode = false;
+      let name = match.substring(1, match.length - 1);
+      let style: ArraySeparatorStyle = 'simple';
+
+      if (name.endsWith('*')) {
+        explode = true;
+        name = name.substring(0, name.length - 1);
+      }
+
+      if (name.startsWith('.')) {
+        name = name.substring(1);
+        style = 'label';
+      } else if (name.startsWith(';')) {
+        name = name.substring(1);
+        style = 'matrix';
+      }
+
+      const value = path[name];
+
+      if (value === undefined || value === null) {
+        continue;
+      }
+
+      if (Array.isArray(value)) {
+        url = url.replace(
+          match,
+          serializeArrayParam({ explode, name, style, value }),
+        );
+        continue;
+      }
+
+      if (typeof value === 'object') {
+        url = url.replace(
+          match,
+          serializeObjectParam({
+            explode,
+            name,
+            style,
+            value: value as Record<string, unknown>,
+            valueOnly: true,
+          }),
+        );
+        continue;
+      }
+
+      if (style === 'matrix') {
+        url = url.replace(
+          match,
+          `;${serializePrimitiveParam({
+            name,
+            value: value as string,
+          })}`,
+        );
+        continue;
+      }
+
+      const replaceValue = encodeURIComponent(
+        style === 'label' ? `.${value as string}` : (value as string),
+      );
+      url = url.replace(match, replaceValue);
+    }
+  }
+  return url;
+};
+
+export const getUrl = ({
+  baseUrl,
+  path,
+  query,
+  querySerializer,
+  url: _url,
+}: {
+  baseUrl?: string;
+  path?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+  querySerializer: QuerySerializer;
+  url: string;
+}) => {
+  const pathUrl = _url.startsWith('/') ? _url : `/${_url}`;
+  let url = (baseUrl ?? '') + pathUrl;
+  if (path) {
+    url = defaultPathSerializer({ path, url });
+  }
+  let search = query ? querySerializer(query) : '';
+  if (search.startsWith('?')) {
+    search = search.substring(1);
+  }
+  if (search) {
+    url += `?${search}`;
+  }
+  return url;
+};
+
+export function getValidRequestBody(options: {
+  body?: unknown;
+  bodySerializer?: BodySerializer | null;
+  serializedBody?: unknown;
+}) {
+  const hasBody = options.body !== undefined;
+  const isSerializedBody = hasBody && options.bodySerializer;
+
+  if (isSerializedBody) {
+    if ('serializedBody' in options) {
+      const hasSerializedBody =
+        options.serializedBody !== undefined && options.serializedBody !== '';
+
+      return hasSerializedBody ? options.serializedBody : null;
+    }
+
+    // not all clients implement a serializedBody property (i.e. client-axios)
+    return options.body !== '' ? options.body : null;
+  }
+
+  // plain/text body
+  if (hasBody) {
+    return options.body;
+  }
+
+  // no body was provided
+  return undefined;
+}

package/src/util/http.ts

@@ -1,18 +1,29 @@
 import http from "node:http";
 import type { AddressInfo } from "node:net";
-import { Readable } from "node:stream";
+import { Readable, type Duplex } from "node:stream";
+import { WebSocketServer, type WebSocket } from "ws";
 
 export class HTTPServer {
-  httpServer: http.Server;
+  httpServer = http.createServer();
+  webSocketServer?: WebSocketServer;
 
   constructor(options: {
+    websocket?: (request: Request) => Promise<WebSocket>;
     fetch: (request: Request) => Promise<Response>;
   }) {
-    this.httpServer = http.createServer();
     this.httpServer.on("request", async (req, res) => {
       const response = await options.fetch(toWebRequest(req));
       await writeNodeResponse(res, response);
     });
+    const websocket = options.websocket;
+    if (websocket) {
+      const webSocketServer = new WebSocketServer({ noServer: true });
+      this.webSocketServer = webSocketServer;
+      this.httpServer.on("upgrade", async (req, socket, head) => {
+        const ws = await websocket(toWebRequest(req));
+        coupleWebSocket(webSocketServer, req, socket, head, ws);
+      });
+    }
   }
 
   listen(port?: number) {
@@ -36,19 +47,35 @@ export class HTTPServer {
     return `http://${hostname}:${address.port}`;
   }
 
-  close() {
-    return new Promise((resolve, reject) => {
-      this.httpServer.close((err) => {
-        if (err) {
-          reject(err);
-        } else {
-          resolve(undefined);
-        }
+  async close() {
+    const webSocketServer = this.webSocketServer;
+    if (webSocketServer) {
+      await new Promise<void>((resolve, reject) => {
+        webSocketServer.close((err) => (err ? reject(err) : resolve()));
       });
+    }
+    await new Promise<void>((resolve, reject) => {
+      this.httpServer.close((err) => (err ? reject(err) : resolve()));
     });
   }
 }
 
+export function coupleWebSocket(
+  wss: WebSocketServer,
+  req: http.IncomingMessage,
+  socket: Duplex,
+  head: Buffer,
+  server: WebSocket,
+) {
+  wss.handleUpgrade(req, socket, head, (client) => {
+    client.on("message", (event, binary) => server.send(event, { binary }));
+    client.on("close", (code, reason) => server.close(code, reason));
+    server.on("message", (event, binary) => client.send(event, { binary }));
+    server.on("close", (code, reason) => client.close(code, reason));
+    wss.emit("connection", client, req);
+  });
+}
+
 export function toWebRequest(
   req: http.IncomingMessage,
   host?: string,

package/src/util/lock.ts

@@ -0,0 +1,48 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import lockfile from "proper-lockfile";
+
+const LOCK_DIR = path.join(os.homedir(), ".alchemy", "lock");
+
+export class Lock {
+  private path: string;
+  constructor(key: string) {
+    this.path = path.join(LOCK_DIR, encodeURIComponent(key));
+  }
+
+  /**
+   * Acquires the lock.
+   * @returns A function to release the lock, or null if the lock is already acquired.
+   */
+  async acquire() {
+    try {
+      await fs.mkdir(LOCK_DIR, { recursive: true });
+      return await lockfile.lock(LOCK_DIR, {
+        lockfilePath: this.path,
+      });
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Checks if the lock is active.
+   * @returns True if the lock is active, false otherwise.
+   */
+  async check() {
+    return await lockfile.check(LOCK_DIR, {
+      lockfilePath: this.path,
+    });
+  }
+
+  /**
+   * Waits for the lock to be released.
+   * @param interval The interval to wait between checks.
+   */
+  async wait(interval = 100) {
+    while (await this.check()) {
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+  }
+}

package/src/util/memoize.ts

@@ -25,6 +25,32 @@ export function memoize<F extends (...args: any[]) => Promise<any>>(
   };
 }
 
+/**
+ * Single flight memoization.
+ * Ensures only one instance of the function is executed at a time.
+ * If another instance is already executing, returns the in-flight promise.
+ */
+export function singleFlight<F extends (...args: any[]) => Promise<any>>(
+  fn: F,
+  keyFn: (...args: Parameters<F>) => string = defaultKeyFn,
+) {
+  const cache = new Map<string, Promise<AsyncReturnType<F>>>();
+  return async (...args: Parameters<F>): Promise<AsyncReturnType<F>> => {
+    const key = keyFn(...args);
+    const cached = cache.get(key);
+    if (cached) {
+      return await cached;
+    }
+    const promise = fn(...args);
+    cache.set(key, promise);
+    try {
+      return await promise;
+    } finally {
+      cache.delete(key);
+    }
+  };
+}
+
 export function defaultKeyFn(...args: any[]): string {
   return createHash("sha256")
     .update(

package/src/util/oauth-client.ts

@@ -0,0 +1,238 @@
+import crypto from "node:crypto";
+import type { Credentials } from "../auth.ts";
+import { DeferredPromise } from "./deferred-promise.ts";
+import { HTTPServer } from "./http.ts";
+
+export class OAuthError extends Error {
+  readonly error: string;
+  constructor({
+    error,
+    error_description,
+    ...rest
+  }: OAuthClient.ErrorResponse) {
+    super(error_description);
+    this.error = error;
+    this.name = "OAuthError";
+    Object.assign(this, rest);
+  }
+}
+
+/**
+ * Generic OAuth 2.0 client.
+ *
+ * Currently only handles the subset required for Cloudflare, but can be modified easily:
+ * - authorization and refresh code flow
+ * - S256 code challenge
+ * - no client secret
+ */
+export class OAuthClient {
+  constructor(
+    private readonly options: {
+      clientId: string;
+      redirectUri: string;
+      endpoints: {
+        authorize: string;
+        token: string;
+        revoke: string;
+      };
+    },
+  ) {}
+
+  /**
+   * Generate an authorization URL, state, and verifier for the given scopes.
+   */
+  authorize(scopes: string[]): OAuthClient.Authorization {
+    const state = generateState();
+    const pkce = generatePKCE();
+    const url = new URL(this.options.endpoints.authorize);
+    url.searchParams.set("client_id", this.options.clientId);
+    url.searchParams.set("redirect_uri", this.options.redirectUri);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("scope", scopes.join(" "));
+    url.searchParams.set("state", state);
+    url.searchParams.set("code_challenge", pkce.challenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    return { url: url.toString(), state, verifier: pkce.verifier };
+  }
+
+  /**
+   * Exchange an authorization code for credentials.
+   */
+  async exchange(code: string, verifier: string): Promise<Credentials.OAuth> {
+    const res = await this.request(this.options.endpoints.token, {
+      grant_type: "authorization_code",
+      code,
+      code_verifier: verifier,
+      client_id: this.options.clientId,
+      redirect_uri: this.options.redirectUri,
+    });
+    return await extractCredentialsFromResponse(res);
+  }
+
+  /**
+   * Refresh OAuth 2.0 credentials.
+   */
+  async refresh(credentials: Credentials.OAuth): Promise<Credentials.OAuth> {
+    const res = await this.request(this.options.endpoints.token, {
+      grant_type: "refresh_token",
+      refresh_token: credentials.refresh,
+      client_id: this.options.clientId,
+      redirect_uri: this.options.redirectUri,
+    });
+    return await extractCredentialsFromResponse(res);
+  }
+
+  /**
+   * Revoke OAuth 2.0 credentials.
+   */
+  async revoke(credentials: Credentials.OAuth): Promise<void> {
+    await this.request(this.options.endpoints.revoke, {
+      refresh_token: credentials.refresh,
+      client_id: this.options.clientId,
+      redirect_uri: this.options.redirectUri,
+    });
+  }
+
+  /**
+   * Make a POST request to the OAuth provider with the given urlencoded body.
+   */
+  private async request(url: string, body: Record<string, string>) {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: new URLSearchParams(body).toString(),
+    });
+    if (!res.ok) {
+      const json = await res.json();
+      throw new OAuthError(json as OAuthClient.ErrorResponse);
+    }
+    return res;
+  }
+
+  /**
+   * Listens for the callback from the provider by starting a local HTTP server and exchanges the authorization code for credentials.
+   * Should be called with the authorization object returned by {@link authorize}.
+   * Listens for the callback on the client's redirect URI.
+   * Throws if the request is invalid, the code exchange fails, or if no callback is received within 5 minutes.
+   */
+  async callback(
+    authorization: OAuthClient.Authorization,
+  ): Promise<Credentials.OAuth> {
+    const { pathname, port } = new URL(this.options.redirectUri);
+    const promise = new DeferredPromise<Credentials.OAuth>();
+    const handle = async (request: Request) => {
+      const url = new URL(request.url);
+      if (url.pathname !== pathname) {
+        throw new OAuthError({
+          error: "invalid_request",
+          error_description: "Invalid redirect URI",
+        });
+      }
+      const error = url.searchParams.get("error");
+      const errorDescription = url.searchParams.get("error_description");
+      if (error) {
+        throw new OAuthError({
+          error,
+          error_description: errorDescription ?? "An unknown error occurred.",
+        });
+      }
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      if (!code || !state) {
+        throw new OAuthError({
+          error: "invalid_request",
+          error_description: "Missing code or state",
+        });
+      }
+      if (state !== authorization.state) {
+        throw new OAuthError({
+          error: "invalid_request",
+          error_description: "Invalid state",
+        });
+      }
+      return await this.exchange(code, authorization.verifier);
+    };
+    const server = new HTTPServer({
+      fetch: async (req) => {
+        try {
+          const result = await handle(req);
+          promise.resolve(result);
+          return Response.redirect("http://alchemy.run/auth/success");
+        } catch (error) {
+          promise.reject(error);
+          return Response.redirect("http://alchemy.run/auth/error");
+        }
+      },
+    });
+    await server.listen(Number(port));
+    const timeout = setTimeout(
+      () => {
+        promise.reject(
+          new OAuthError({
+            error: "timeout",
+            error_description: "The authorization process timed out.",
+          }),
+        );
+      },
+      1000 * 60 * 5,
+    );
+    try {
+      const result = await promise.value;
+      clearTimeout(timeout);
+      return result;
+    } finally {
+      // Not awaited because the server can take a few seconds to close, don't want to block the login process from completing
+      void server.close();
+    }
+  }
+}
+
+export declare namespace OAuthClient {
+  export interface ErrorResponse {
+    error: string;
+    error_description: string;
+  }
+
+  export interface SuccessResponse {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    scope: string;
+    token_type: string;
+  }
+
+  export interface Authorization {
+    url: string;
+    state: string;
+    verifier: string;
+  }
+}
+
+async function extractCredentialsFromResponse(
+  response: Response,
+): Promise<Credentials.OAuth> {
+  const json = (await response.json()) as OAuthClient.SuccessResponse;
+  return {
+    type: "oauth",
+    access: json.access_token,
+    refresh: json.refresh_token,
+    expires: Date.now() + json.expires_in * 1000,
+    scopes: json.scope.split(" "),
+  };
+}
+
+function generateState(length = 32) {
+  return crypto.randomBytes(length).toString("base64url");
+}
+
+function generatePKCE(length = 96) {
+  const verifier = crypto.randomBytes(length).toString("base64url");
+  const challenge = crypto
+    .createHash("sha256")
+    .update(verifier)
+    .digest("base64url");
+  return { verifier, challenge };
+}

package/src/util/poll.ts

@@ -0,0 +1,55 @@
+/**
+ * Polls a function until it returns a result that satisfies the predicate.
+ */
+export async function poll<T>(input: {
+  /**
+   * A description of the operation being polled.
+   */
+  description: string;
+
+  /**
+   * The function to poll.
+   */
+  fn: () => Promise<T>;
+
+  /**
+   * A predicate that determines if the operation has completed.
+   */
+  predicate: (result: T) => boolean;
+
+  /**
+   * The initial delay between polls.
+   * @default 250ms
+   */
+  initialDelay?: number;
+
+  /**
+   * The maximum delay between polls.
+   * @default 2_500ms (2.5 seconds)
+   */
+  maxDelay?: number;
+
+  /**
+   * The timeout for the poll in milliseconds.
+   * @default 1_000_000 (~16 minutes)
+   */
+  timeout?: number;
+}): Promise<T> {
+  const start = Date.now();
+  let delay = input.initialDelay ?? 250;
+  while (true) {
+    const result = await input.fn();
+    if (input.predicate(result)) {
+      return result;
+    }
+    if (Date.now() - start >= (input.timeout ?? 1_000_000)) {
+      throw new Error(
+        `Timed out waiting for ${input.description} after ${Math.round(
+          (input.timeout ?? 1_000_000) / 1000,
+        )}s`,
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    delay = Math.min(delay * 2, input.maxDelay ?? 5_000);
+  }
+}