@jacob-registry-repo/sdk 1.0.0

package/core/fetcher/Fetcher.ts

@@ -0,0 +1,438 @@
+import { toJson } from "../json.js";
+import {
+  createLogger,
+  type LogConfig,
+  type Logger,
+} from "../logging/logger.js";
+import type { APIResponse } from "./APIResponse.js";
+import { createRequestUrl } from "./createRequestUrl.js";
+import type { EndpointMetadata } from "./EndpointMetadata.js";
+import { EndpointSupplier } from "./EndpointSupplier.js";
+import { getErrorResponseBody } from "./getErrorResponseBody.js";
+import { getFetchFn } from "./getFetchFn.js";
+import { getRequestBody } from "./getRequestBody.js";
+import { getResponseBody } from "./getResponseBody.js";
+import { Headers } from "./Headers.js";
+import { makeRequest } from "./makeRequest.js";
+import {
+  abortRawResponse,
+  toRawResponse,
+  unknownRawResponse,
+} from "./RawResponse.js";
+import { requestWithRetries } from "./requestWithRetries.js";
+
+export type FetchFunction = <R = unknown>(
+  args: Fetcher.Args
+) => Promise<APIResponse<R, Fetcher.Error>>;
+
+export declare namespace Fetcher {
+  export interface Args {
+    url: string;
+    method: string;
+    contentType?: string;
+    headers?: Record<
+      string,
+      string | EndpointSupplier<string | null | undefined> | null | undefined
+    >;
+    queryParameters?: Record<string, unknown>;
+    body?: unknown;
+    timeoutMs?: number;
+    maxRetries?: number;
+    withCredentials?: boolean;
+    abortSignal?: AbortSignal;
+    requestType?: "json" | "file" | "bytes" | "form" | "other";
+    responseType?:
+      | "json"
+      | "blob"
+      | "sse"
+      | "streaming"
+      | "text"
+      | "arrayBuffer"
+      | "binary-response";
+    duplex?: "half";
+    endpointMetadata?: EndpointMetadata;
+    fetchFn?: typeof fetch;
+    logging?: LogConfig | Logger;
+  }
+
+  export type Error =
+    | FailedStatusCodeError
+    | NonJsonError
+    | BodyIsNullError
+    | TimeoutError
+    | UnknownError;
+
+  export interface FailedStatusCodeError {
+    reason: "status-code";
+    statusCode: number;
+    body: unknown;
+  }
+
+  export interface NonJsonError {
+    reason: "non-json";
+    statusCode: number;
+    rawBody: string;
+  }
+
+  export interface BodyIsNullError {
+    reason: "body-is-null";
+    statusCode: number;
+  }
+
+  export interface TimeoutError {
+    reason: "timeout";
+  }
+
+  export interface UnknownError {
+    reason: "unknown";
+    errorMessage: string;
+  }
+}
+
+const SENSITIVE_HEADERS = new Set([
+  "authorization",
+  "www-authenticate",
+  "x-api-key",
+  "api-key",
+  "apikey",
+  "x-api-token",
+  "x-auth-token",
+  "auth-token",
+  "cookie",
+  "set-cookie",
+  "proxy-authorization",
+  "proxy-authenticate",
+  "x-csrf-token",
+  "x-xsrf-token",
+  "x-session-token",
+  "x-access-token",
+]);
+
+function redactHeaders(
+  headers: Headers | Record<string, string>
+): Record<string, string> {
+  const filtered: Record<string, string> = {};
+  const entries =
+    headers instanceof Headers
+      ? (headers as any).entries()
+      : Object.entries(headers);
+  for (const [key, value] of entries) {
+    if (SENSITIVE_HEADERS.has(key.toLowerCase())) {
+      filtered[key] = "[REDACTED]";
+    } else {
+      filtered[key] = value;
+    }
+  }
+  return filtered;
+}
+
+const SENSITIVE_QUERY_PARAMS = new Set([
+  "api_key",
+  "api-key",
+  "apikey",
+  "token",
+  "access_token",
+  "access-token",
+  "auth_token",
+  "auth-token",
+  "password",
+  "passwd",
+  "secret",
+  "api_secret",
+  "api-secret",
+  "apisecret",
+  "key",
+  "session",
+  "session_id",
+  "session-id",
+]);
+
+function redactQueryParameters(
+  queryParameters?: Record<string, unknown>
+): Record<string, unknown> | undefined {
+  if (queryParameters == null) {
+    return queryParameters;
+  }
+  const redacted: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(queryParameters)) {
+    if (SENSITIVE_QUERY_PARAMS.has(key.toLowerCase())) {
+      redacted[key] = "[REDACTED]";
+    } else {
+      redacted[key] = value;
+    }
+  }
+  return redacted;
+}
+
+function redactUrl(url: string): string {
+  const protocolIndex = url.indexOf("://");
+  if (protocolIndex === -1) return url;
+
+  const afterProtocol = protocolIndex + 3;
+
+  // Find the first delimiter that marks the end of the authority section
+  const pathStart = url.indexOf("/", afterProtocol);
+  let queryStart = url.indexOf("?", afterProtocol);
+  let fragmentStart = url.indexOf("#", afterProtocol);
+
+  const firstDelimiter = Math.min(
+    pathStart === -1 ? url.length : pathStart,
+    queryStart === -1 ? url.length : queryStart,
+    fragmentStart === -1 ? url.length : fragmentStart
+  );
+
+  // Find the LAST @ before the delimiter (handles multiple @ in credentials)
+  let atIndex = -1;
+  for (let i = afterProtocol; i < firstDelimiter; i++) {
+    if (url[i] === "@") {
+      atIndex = i;
+    }
+  }
+
+  if (atIndex !== -1) {
+    url = `${url.slice(0, afterProtocol)}[REDACTED]@${url.slice(atIndex + 1)}`;
+  }
+
+  // Recalculate queryStart since url might have changed
+  queryStart = url.indexOf("?");
+  if (queryStart === -1) return url;
+
+  fragmentStart = url.indexOf("#", queryStart);
+  const queryEnd = fragmentStart !== -1 ? fragmentStart : url.length;
+  const queryString = url.slice(queryStart + 1, queryEnd);
+
+  if (queryString.length === 0) return url;
+
+  // FAST PATH: Quick check if any sensitive keywords present
+  // Using indexOf is faster than regex for simple substring matching
+  const lower = queryString.toLowerCase();
+  const hasSensitive =
+    lower.includes("token") ||
+    lower.includes("key") ||
+    lower.includes("password") ||
+    lower.includes("passwd") ||
+    lower.includes("secret") ||
+    lower.includes("session") ||
+    lower.includes("auth");
+
+  if (!hasSensitive) {
+    return url;
+  }
+
+  // SLOW PATH: Parse and redact
+  const redactedParams: string[] = [];
+  const params = queryString.split("&");
+
+  for (const param of params) {
+    const equalIndex = param.indexOf("=");
+    if (equalIndex === -1) {
+      redactedParams.push(param);
+      continue;
+    }
+
+    const key = param.slice(0, equalIndex);
+    let shouldRedact = SENSITIVE_QUERY_PARAMS.has(key.toLowerCase());
+
+    if (!shouldRedact && key.includes("%")) {
+      try {
+        const decodedKey = decodeURIComponent(key);
+        shouldRedact = SENSITIVE_QUERY_PARAMS.has(decodedKey.toLowerCase());
+      } catch {}
+    }
+
+    redactedParams.push(shouldRedact ? `${key}=[REDACTED]` : param);
+  }
+
+  return (
+    url.slice(0, queryStart + 1) +
+    redactedParams.join("&") +
+    url.slice(queryEnd)
+  );
+}
+
+async function getHeaders(args: Fetcher.Args): Promise<Headers> {
+  const newHeaders: Headers = new Headers();
+
+  newHeaders.set(
+    "Accept",
+    args.responseType === "json"
+      ? "application/json"
+      : args.responseType === "text"
+      ? "text/plain"
+      : "*/*"
+  );
+  if (args.body !== undefined && args.contentType != null) {
+    newHeaders.set("Content-Type", args.contentType);
+  }
+
+  if (args.headers == null) {
+    return newHeaders;
+  }
+
+  for (const [key, value] of Object.entries(args.headers)) {
+    const result = await EndpointSupplier.get(value, {
+      endpointMetadata: args.endpointMetadata ?? {},
+    });
+    if (typeof result === "string") {
+      newHeaders.set(key, result);
+      continue;
+    }
+    if (result == null) {
+      continue;
+    }
+    newHeaders.set(key, `${result}`);
+  }
+  return newHeaders;
+}
+
+export async function fetcherImpl<R = unknown>(
+  args: Fetcher.Args
+): Promise<APIResponse<R, Fetcher.Error>> {
+  const url = createRequestUrl(args.url, args.queryParameters);
+  const requestBody: BodyInit | undefined = await getRequestBody({
+    body: args.body,
+    type: args.requestType ?? "other",
+  });
+  const fetchFn = args.fetchFn ?? (await getFetchFn());
+  const headers = await getHeaders(args);
+  const logger = createLogger(args.logging);
+
+  if (logger.isDebug()) {
+    const metadata = {
+      method: args.method,
+      url: redactUrl(url),
+      headers: redactHeaders(headers),
+      queryParameters: redactQueryParameters(args.queryParameters),
+      hasBody: requestBody != null,
+    };
+    logger.debug("Making HTTP request", metadata);
+  }
+
+  try {
+    const response = await requestWithRetries(
+      async () =>
+        makeRequest(
+          fetchFn,
+          url,
+          args.method,
+          headers,
+          requestBody,
+          args.timeoutMs,
+          args.abortSignal,
+          args.withCredentials,
+          args.duplex
+        ),
+      args.maxRetries
+    );
+
+    if (response.status >= 200 && response.status < 400) {
+      if (logger.isDebug()) {
+        const metadata = {
+          method: args.method,
+          url: redactUrl(url),
+          statusCode: response.status,
+          responseHeaders: redactHeaders(response.headers),
+        };
+        logger.debug("HTTP request succeeded", metadata);
+      }
+      const body = await getResponseBody(response, args.responseType);
+      return {
+        ok: true,
+        body: body as R,
+        headers: response.headers,
+        rawResponse: toRawResponse(response),
+      };
+    } else {
+      if (logger.isError()) {
+        const metadata = {
+          method: args.method,
+          url: redactUrl(url),
+          statusCode: response.status,
+          responseHeaders: redactHeaders(
+            Object.fromEntries((response.headers as any).entries())
+          ),
+        };
+        logger.error("HTTP request failed with error status", metadata);
+      }
+      return {
+        ok: false,
+        error: {
+          reason: "status-code",
+          statusCode: response.status,
+          body: await getErrorResponseBody(response),
+        },
+        rawResponse: toRawResponse(response),
+      };
+    }
+  } catch (error) {
+    if (args.abortSignal?.aborted) {
+      if (logger.isError()) {
+        const metadata = {
+          method: args.method,
+          url: redactUrl(url),
+        };
+        logger.error("HTTP request was aborted", metadata);
+      }
+      return {
+        ok: false,
+        error: {
+          reason: "unknown",
+          errorMessage: "The user aborted a request",
+        },
+        rawResponse: abortRawResponse,
+      };
+    } else if (error instanceof Error && error.name === "AbortError") {
+      if (logger.isError()) {
+        const metadata = {
+          method: args.method,
+          url: redactUrl(url),
+          timeoutMs: args.timeoutMs,
+        };
+        logger.error("HTTP request timed out", metadata);
+      }
+      return {
+        ok: false,
+        error: {
+          reason: "timeout",
+        },
+        rawResponse: abortRawResponse,
+      };
+    } else if (error instanceof Error) {
+      if (logger.isError()) {
+        const metadata = {
+          method: args.method,
+          url: redactUrl(url),
+          errorMessage: error.message,
+        };
+        logger.error("HTTP request failed with error", metadata);
+      }
+      return {
+        ok: false,
+        error: {
+          reason: "unknown",
+          errorMessage: error.message,
+        },
+        rawResponse: unknownRawResponse,
+      };
+    }
+
+    if (logger.isError()) {
+      const metadata = {
+        method: args.method,
+        url: redactUrl(url),
+        error: toJson(error),
+      };
+      logger.error("HTTP request failed with unknown error", metadata);
+    }
+    return {
+      ok: false,
+      error: {
+        reason: "unknown",
+        errorMessage: toJson(error),
+      },
+      rawResponse: unknownRawResponse,
+    };
+  }
+}
+
+export const fetcher: FetchFunction = fetcherImpl;

package/core/fetcher/Headers.ts

@@ -0,0 +1,100 @@
+let Headers: typeof globalThis.Headers;
+
+if (typeof globalThis.Headers !== "undefined") {
+  Headers = globalThis.Headers;
+} else {
+  Headers = class Headers implements Headers {
+    private headers: Map<string, string[]>;
+
+    constructor(init?: HeadersInit) {
+      this.headers = new Map();
+
+      if (init) {
+        if (init instanceof Headers) {
+          init.forEach((value, key) => this.append(key, value));
+        } else if (Array.isArray(init)) {
+          for (const [key, value] of init) {
+            if (typeof key === "string" && typeof value === "string") {
+              this.append(key, value);
+            } else {
+              throw new TypeError(
+                "Each header entry must be a [string, string] tuple"
+              );
+            }
+          }
+        } else {
+          for (const [key, value] of Object.entries(init)) {
+            if (typeof value === "string") {
+              this.append(key, value);
+            } else {
+              throw new TypeError("Header values must be strings");
+            }
+          }
+        }
+      }
+    }
+
+    append(name: string, value: string): void {
+      const key = name.toLowerCase();
+      const existing = this.headers.get(key) || [];
+      this.headers.set(key, [...existing, value]);
+    }
+
+    delete(name: string): void {
+      const key = name.toLowerCase();
+      this.headers.delete(key);
+    }
+
+    get(name: string): string | null {
+      const key = name.toLowerCase();
+      const values = this.headers.get(key);
+      return values ? values.join(", ") : null;
+    }
+
+    has(name: string): boolean {
+      const key = name.toLowerCase();
+      return this.headers.has(key);
+    }
+
+    set(name: string, value: string): void {
+      const key = name.toLowerCase();
+      this.headers.set(key, [value]);
+    }
+
+    forEach(
+      callbackfn: (value: string, key: string, parent: Headers) => void,
+      thisArg?: unknown
+    ): void {
+      const boundCallback = thisArg ? callbackfn.bind(thisArg) : callbackfn;
+      this.headers.forEach((values, key) =>
+        boundCallback(values.join(", "), key, this)
+      );
+    }
+
+    getSetCookie(): string[] {
+      return this.headers.get("set-cookie") || [];
+    }
+
+    *entries(): HeadersIterator<[string, string]> {
+      for (const [key, values] of this.headers.entries()) {
+        yield [key, values.join(", ")];
+      }
+    }
+
+    *keys(): HeadersIterator<string> {
+      yield* this.headers.keys();
+    }
+
+    *values(): HeadersIterator<string> {
+      for (const values of this.headers.values()) {
+        yield values.join(", ");
+      }
+    }
+
+    [Symbol.iterator](): HeadersIterator<[string, string]> {
+      return this.entries();
+    }
+  };
+}
+
+export { Headers };

package/core/fetcher/HttpResponsePromise.ts

@@ -0,0 +1,116 @@
+import type { WithRawResponse } from "./RawResponse.js";
+
+/**
+ * A promise that returns the parsed response and lets you retrieve the raw response too.
+ */
+export class HttpResponsePromise<T> extends Promise<T> {
+    private innerPromise: Promise<WithRawResponse<T>>;
+    private unwrappedPromise: Promise<T> | undefined;
+
+    private constructor(promise: Promise<WithRawResponse<T>>) {
+        // Initialize with a no-op to avoid premature parsing
+        super((resolve) => {
+            resolve(undefined as unknown as T);
+        });
+        this.innerPromise = promise;
+    }
+
+    /**
+     * Creates an `HttpResponsePromise` from a function that returns a promise.
+     *
+     * @param fn - A function that returns a promise resolving to a `WithRawResponse` object.
+     * @param args - Arguments to pass to the function.
+     * @returns An `HttpResponsePromise` instance.
+     */
+    public static fromFunction<F extends (...args: never[]) => Promise<WithRawResponse<T>>, T>(
+        fn: F,
+        ...args: Parameters<F>
+    ): HttpResponsePromise<T> {
+        return new HttpResponsePromise<T>(fn(...args));
+    }
+
+    /**
+     * Creates a function that returns an `HttpResponsePromise` from a function that returns a promise.
+     *
+     * @param fn - A function that returns a promise resolving to a `WithRawResponse` object.
+     * @returns A function that returns an `HttpResponsePromise` instance.
+     */
+    public static interceptFunction<
+        F extends (...args: never[]) => Promise<WithRawResponse<T>>,
+        T = Awaited<ReturnType<F>>["data"],
+    >(fn: F): (...args: Parameters<F>) => HttpResponsePromise<T> {
+        return (...args: Parameters<F>): HttpResponsePromise<T> => {
+            return HttpResponsePromise.fromPromise<T>(fn(...args));
+        };
+    }
+
+    /**
+     * Creates an `HttpResponsePromise` from an existing promise.
+     *
+     * @param promise - A promise resolving to a `WithRawResponse` object.
+     * @returns An `HttpResponsePromise` instance.
+     */
+    public static fromPromise<T>(promise: Promise<WithRawResponse<T>>): HttpResponsePromise<T> {
+        return new HttpResponsePromise<T>(promise);
+    }
+
+    /**
+     * Creates an `HttpResponsePromise` from an executor function.
+     *
+     * @param executor - A function that takes resolve and reject callbacks to create a promise.
+     * @returns An `HttpResponsePromise` instance.
+     */
+    public static fromExecutor<T>(
+        executor: (resolve: (value: WithRawResponse<T>) => void, reject: (reason?: unknown) => void) => void,
+    ): HttpResponsePromise<T> {
+        const promise = new Promise<WithRawResponse<T>>(executor);
+        return new HttpResponsePromise<T>(promise);
+    }
+
+    /**
+     * Creates an `HttpResponsePromise` from a resolved result.
+     *
+     * @param result - A `WithRawResponse` object to resolve immediately.
+     * @returns An `HttpResponsePromise` instance.
+     */
+    public static fromResult<T>(result: WithRawResponse<T>): HttpResponsePromise<T> {
+        const promise = Promise.resolve(result);
+        return new HttpResponsePromise<T>(promise);
+    }
+
+    private unwrap(): Promise<T> {
+        if (!this.unwrappedPromise) {
+            this.unwrappedPromise = this.innerPromise.then(({ data }) => data);
+        }
+        return this.unwrappedPromise;
+    }
+
+    /** @inheritdoc */
+    public override then<TResult1 = T, TResult2 = never>(
+        onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
+        onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+    ): Promise<TResult1 | TResult2> {
+        return this.unwrap().then(onfulfilled, onrejected);
+    }
+
+    /** @inheritdoc */
+    public override catch<TResult = never>(
+        onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null,
+    ): Promise<T | TResult> {
+        return this.unwrap().catch(onrejected);
+    }
+
+    /** @inheritdoc */
+    public override finally(onfinally?: (() => void) | null): Promise<T> {
+        return this.unwrap().finally(onfinally);
+    }
+
+    /**
+     * Retrieves the data and raw response.
+     *
+     * @returns A promise resolving to a `WithRawResponse` object.
+     */
+    public async withRawResponse(): Promise<WithRawResponse<T>> {
+        return await this.innerPromise;
+    }
+}

package/core/fetcher/RawResponse.ts

@@ -0,0 +1,61 @@
+import { Headers } from "./Headers.js";
+
+/**
+ * The raw response from the fetch call excluding the body.
+ */
+export type RawResponse = Omit<
+    {
+        [K in keyof Response as Response[K] extends Function ? never : K]: Response[K]; // strips out functions
+    },
+    "ok" | "body" | "bodyUsed"
+>; // strips out body and bodyUsed
+
+/**
+ * A raw response indicating that the request was aborted.
+ */
+export const abortRawResponse: RawResponse = {
+    headers: new Headers(),
+    redirected: false,
+    status: 499,
+    statusText: "Client Closed Request",
+    type: "error",
+    url: "",
+} as const;
+
+/**
+ * A raw response indicating an unknown error.
+ */
+export const unknownRawResponse: RawResponse = {
+    headers: new Headers(),
+    redirected: false,
+    status: 0,
+    statusText: "Unknown Error",
+    type: "error",
+    url: "",
+} as const;
+
+/**
+ * Converts a `RawResponse` object into a `RawResponse` by extracting its properties,
+ * excluding the `body` and `bodyUsed` fields.
+ *
+ * @param response - The `RawResponse` object to convert.
+ * @returns A `RawResponse` object containing the extracted properties of the input response.
+ */
+export function toRawResponse(response: Response): RawResponse {
+    return {
+        headers: response.headers,
+        redirected: response.redirected,
+        status: response.status,
+        statusText: response.statusText,
+        type: response.type,
+        url: response.url,
+    };
+}
+
+/**
+ * Creates a `RawResponse` from a standard `Response` object.
+ */
+export interface WithRawResponse<T> {
+    readonly data: T;
+    readonly rawResponse: RawResponse;
+}