@jacob-registry-repo/sdk 1.0.0

package/core/fetcher/Supplier.ts

@@ -0,0 +1,11 @@
+export type Supplier<T> = T | Promise<T> | (() => T | Promise<T>);
+
+export const Supplier = {
+    get: async <T>(supplier: Supplier<T>): Promise<T> => {
+        if (typeof supplier === "function") {
+            return (supplier as () => T)();
+        } else {
+            return supplier;
+        }
+    },
+};

package/core/fetcher/createRequestUrl.ts

@@ -0,0 +1,6 @@
+import { toQueryString } from "../url/qs.js";
+
+export function createRequestUrl(baseUrl: string, queryParameters?: Record<string, unknown>): string {
+    const queryString = toQueryString(queryParameters, { arrayFormat: "repeat" });
+    return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+}

package/core/fetcher/getErrorResponseBody.ts

@@ -0,0 +1,33 @@
+import { fromJson } from "../json.js";
+import { getResponseBody } from "./getResponseBody.js";
+
+export async function getErrorResponseBody(response: Response): Promise<unknown> {
+    let contentType = response.headers.get("Content-Type")?.toLowerCase();
+    if (contentType == null || contentType.length === 0) {
+        return getResponseBody(response);
+    }
+
+    if (contentType.indexOf(";") !== -1) {
+        contentType = contentType.split(";")[0]?.trim() ?? "";
+    }
+    switch (contentType) {
+        case "application/hal+json":
+        case "application/json":
+        case "application/ld+json":
+        case "application/problem+json":
+        case "application/vnd.api+json":
+        case "text/json": {
+            const text = await response.text();
+            return text.length > 0 ? fromJson(text) : undefined;
+        }
+        default:
+            if (contentType.startsWith("application/vnd.") && contentType.endsWith("+json")) {
+                const text = await response.text();
+                return text.length > 0 ? fromJson(text) : undefined;
+            }
+
+            // Fallback to plain text if content type is not recognized
+            // Even if no body is present, the response will be an empty string
+            return await response.text();
+    }
+}

package/core/fetcher/getFetchFn.ts

@@ -0,0 +1,3 @@
+export async function getFetchFn(): Promise<typeof fetch> {
+    return fetch;
+}

package/core/fetcher/getHeader.ts

@@ -0,0 +1,8 @@
+export function getHeader(headers: Record<string, any>, header: string): string | undefined {
+    for (const [headerKey, headerValue] of Object.entries(headers)) {
+        if (headerKey.toLowerCase() === header.toLowerCase()) {
+            return headerValue;
+        }
+    }
+    return undefined;
+}

package/core/fetcher/getRequestBody.ts

@@ -0,0 +1,20 @@
+import { toJson } from "../json.js";
+import { toQueryString } from "../url/qs.js";
+
+export declare namespace GetRequestBody {
+    interface Args {
+        body: unknown;
+        type: "json" | "file" | "bytes" | "form" | "other";
+    }
+}
+
+export async function getRequestBody({ body, type }: GetRequestBody.Args): Promise<BodyInit | undefined> {
+    if (type === "form") {
+        return toQueryString(body, { arrayFormat: "repeat", encode: true });
+    }
+    if (type.includes("json")) {
+        return toJson(body);
+    } else {
+        return body as BodyInit;
+    }
+}

package/core/fetcher/getResponseBody.ts

@@ -0,0 +1,58 @@
+import { fromJson } from "../json.js";
+import { getBinaryResponse } from "./BinaryResponse.js";
+
+export async function getResponseBody(response: Response, responseType?: string): Promise<unknown> {
+    switch (responseType) {
+        case "binary-response":
+            return getBinaryResponse(response);
+        case "blob":
+            return await response.blob();
+        case "arrayBuffer":
+            return await response.arrayBuffer();
+        case "sse":
+            if (response.body == null) {
+                return {
+                    ok: false,
+                    error: {
+                        reason: "body-is-null",
+                        statusCode: response.status,
+                    },
+                };
+            }
+            return response.body;
+        case "streaming":
+            if (response.body == null) {
+                return {
+                    ok: false,
+                    error: {
+                        reason: "body-is-null",
+                        statusCode: response.status,
+                    },
+                };
+            }
+
+            return response.body;
+
+        case "text":
+            return await response.text();
+    }
+
+    // if responseType is "json" or not specified, try to parse as JSON
+    const text = await response.text();
+    if (text.length > 0) {
+        try {
+            const responseBody = fromJson(text);
+            return responseBody;
+        } catch (_err) {
+            return {
+                ok: false,
+                error: {
+                    reason: "non-json",
+                    statusCode: response.status,
+                    rawBody: text,
+                },
+            };
+        }
+    }
+    return undefined;
+}

package/core/fetcher/index.ts

@@ -0,0 +1,11 @@
+export type { APIResponse } from "./APIResponse.js";
+export type { BinaryResponse } from "./BinaryResponse.js";
+export type { EndpointMetadata } from "./EndpointMetadata.js";
+export { EndpointSupplier } from "./EndpointSupplier.js";
+export type { Fetcher, FetchFunction } from "./Fetcher.js";
+export { fetcher } from "./Fetcher.js";
+export { getHeader } from "./getHeader.js";
+export { HttpResponsePromise } from "./HttpResponsePromise.js";
+export type { RawResponse, WithRawResponse } from "./RawResponse.js";
+export { abortRawResponse, toRawResponse, unknownRawResponse } from "./RawResponse.js";
+export { Supplier } from "./Supplier.js";

package/core/fetcher/makeRequest.ts

@@ -0,0 +1,42 @@
+import { anySignal, getTimeoutSignal } from "./signals.js";
+
+export const makeRequest = async (
+    fetchFn: (url: string, init: RequestInit) => Promise<Response>,
+    url: string,
+    method: string,
+    headers: Headers | Record<string, string>,
+    requestBody: BodyInit | undefined,
+    timeoutMs?: number,
+    abortSignal?: AbortSignal,
+    withCredentials?: boolean,
+    duplex?: "half",
+): Promise<Response> => {
+    const signals: AbortSignal[] = [];
+
+    let timeoutAbortId: ReturnType<typeof setTimeout> | undefined;
+    if (timeoutMs != null) {
+        const { signal, abortId } = getTimeoutSignal(timeoutMs);
+        timeoutAbortId = abortId;
+        signals.push(signal);
+    }
+
+    if (abortSignal != null) {
+        signals.push(abortSignal);
+    }
+    const newSignals = anySignal(signals);
+    const response = await fetchFn(url, {
+        method: method,
+        headers,
+        body: requestBody,
+        signal: newSignals,
+        credentials: withCredentials ? "include" : undefined,
+        // @ts-ignore
+        duplex,
+    });
+
+    if (timeoutAbortId != null) {
+        clearTimeout(timeoutAbortId);
+    }
+
+    return response;
+};

package/core/fetcher/requestWithRetries.ts

@@ -0,0 +1,64 @@
+const INITIAL_RETRY_DELAY = 1000; // in milliseconds
+const MAX_RETRY_DELAY = 60000; // in milliseconds
+const DEFAULT_MAX_RETRIES = 2;
+const JITTER_FACTOR = 0.2; // 20% random jitter
+
+function addPositiveJitter(delay: number): number {
+    const jitterMultiplier = 1 + Math.random() * JITTER_FACTOR;
+    return delay * jitterMultiplier;
+}
+
+function addSymmetricJitter(delay: number): number {
+    const jitterMultiplier = 1 + (Math.random() - 0.5) * JITTER_FACTOR;
+    return delay * jitterMultiplier;
+}
+
+function getRetryDelayFromHeaders(response: Response, retryAttempt: number): number {
+    const retryAfter = response.headers.get("Retry-After");
+    if (retryAfter) {
+        const retryAfterSeconds = parseInt(retryAfter, 10);
+        if (!Number.isNaN(retryAfterSeconds) && retryAfterSeconds > 0) {
+            return Math.min(retryAfterSeconds * 1000, MAX_RETRY_DELAY);
+        }
+
+        const retryAfterDate = new Date(retryAfter);
+        if (!Number.isNaN(retryAfterDate.getTime())) {
+            const delay = retryAfterDate.getTime() - Date.now();
+            if (delay > 0) {
+                return Math.min(Math.max(delay, 0), MAX_RETRY_DELAY);
+            }
+        }
+    }
+
+    const rateLimitReset = response.headers.get("X-RateLimit-Reset");
+    if (rateLimitReset) {
+        const resetTime = parseInt(rateLimitReset, 10);
+        if (!Number.isNaN(resetTime)) {
+            const delay = resetTime * 1000 - Date.now();
+            if (delay > 0) {
+                return addPositiveJitter(Math.min(delay, MAX_RETRY_DELAY));
+            }
+        }
+    }
+
+    return addSymmetricJitter(Math.min(INITIAL_RETRY_DELAY * 2 ** retryAttempt, MAX_RETRY_DELAY));
+}
+
+export async function requestWithRetries(
+    requestFn: () => Promise<Response>,
+    maxRetries: number = DEFAULT_MAX_RETRIES,
+): Promise<Response> {
+    let response: Response = await requestFn();
+
+    for (let i = 0; i < maxRetries; ++i) {
+        if ([408, 429].includes(response.status) || response.status >= 500) {
+            const delay = getRetryDelayFromHeaders(response, i);
+
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            response = await requestFn();
+        } else {
+            break;
+        }
+    }
+    return response!;
+}

package/core/fetcher/signals.ts

@@ -0,0 +1,26 @@
+const TIMEOUT = "timeout";
+
+export function getTimeoutSignal(timeoutMs: number): { signal: AbortSignal; abortId: ReturnType<typeof setTimeout> } {
+    const controller = new AbortController();
+    const abortId = setTimeout(() => controller.abort(TIMEOUT), timeoutMs);
+    return { signal: controller.signal, abortId };
+}
+
+export function anySignal(...args: AbortSignal[] | [AbortSignal[]]): AbortSignal {
+    const signals = (args.length === 1 && Array.isArray(args[0]) ? args[0] : args) as AbortSignal[];
+
+    const controller = new AbortController();
+
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort((signal as any)?.reason);
+            break;
+        }
+
+        signal.addEventListener("abort", () => controller.abort((signal as any)?.reason), {
+            signal: controller.signal,
+        });
+    }
+
+    return controller.signal;
+}

package/core/headers.ts

@@ -0,0 +1,35 @@
+export function mergeHeaders<THeaderValue>(
+    ...headersArray: (Record<string, THeaderValue> | null | undefined)[]
+): Record<string, string | THeaderValue> {
+    const result: Record<string, THeaderValue> = {};
+
+    for (const [key, value] of headersArray
+        .filter((headers) => headers != null)
+        .flatMap((headers) => Object.entries(headers))) {
+        const insensitiveKey = key.toLowerCase();
+        if (value != null) {
+            result[insensitiveKey] = value;
+        } else if (insensitiveKey in result) {
+            delete result[insensitiveKey];
+        }
+    }
+
+    return result;
+}
+
+export function mergeOnlyDefinedHeaders<THeaderValue>(
+    ...headersArray: (Record<string, THeaderValue> | null | undefined)[]
+): Record<string, THeaderValue> {
+    const result: Record<string, THeaderValue> = {};
+
+    for (const [key, value] of headersArray
+        .filter((headers) => headers != null)
+        .flatMap((headers) => Object.entries(headers))) {
+        const insensitiveKey = key.toLowerCase();
+        if (value != null) {
+            result[insensitiveKey] = value;
+        }
+    }
+
+    return result;
+}

package/core/index.ts

@@ -0,0 +1,6 @@
+export * from "./auth/index.js";
+export * from "./base64.js";
+export * from "./fetcher/index.js";
+export * as logging from "./logging/index.js";
+export * from "./runtime/index.js";
+export * as url from "./url/index.js";

package/core/json.ts

@@ -0,0 +1,27 @@
+/**
+ * Serialize a value to JSON
+ * @param value A JavaScript value, usually an object or array, to be converted.
+ * @param replacer A function that transforms the results.
+ * @param space Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.
+ * @returns JSON string
+ */
+export const toJson = (
+    value: unknown,
+    replacer?: (this: unknown, key: string, value: unknown) => unknown,
+    space?: string | number,
+): string => {
+    return JSON.stringify(value, replacer, space);
+};
+
+/**
+ * Parse JSON string to object, array, or other type
+ * @param text A valid JSON string.
+ * @param reviver A function that transforms the results. This function is called for each member of the object. If a member contains nested objects, the nested objects are transformed before the parent object is.
+ * @returns Parsed object, array, or other type
+ */
+export function fromJson<T = unknown>(
+    text: string,
+    reviver?: (this: unknown, key: string, value: unknown) => unknown,
+): T {
+    return JSON.parse(text, reviver);
+}

package/core/logging/exports.ts

@@ -0,0 +1,19 @@
+import * as logger from "./logger.js";
+
+export namespace logging {
+    /**
+     * Configuration for logger instances.
+     */
+    export type LogConfig = logger.LogConfig;
+    export type LogLevel = logger.LogLevel;
+    export const LogLevel: typeof logger.LogLevel = logger.LogLevel;
+    export type ILogger = logger.ILogger;
+    /**
+     * Console logger implementation that outputs to the console.
+     */
+    export type ConsoleLogger = logger.ConsoleLogger;
+    /**
+     * Console logger implementation that outputs to the console.
+     */
+    export const ConsoleLogger: typeof logger.ConsoleLogger = logger.ConsoleLogger;
+}

package/core/logging/index.ts

@@ -0,0 +1 @@
+export * from "./logger.js";

package/core/logging/logger.ts

@@ -0,0 +1,203 @@
+export const LogLevel = {
+    Debug: "debug",
+    Info: "info",
+    Warn: "warn",
+    Error: "error",
+} as const;
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+const logLevelMap: Record<LogLevel, number> = {
+    [LogLevel.Debug]: 1,
+    [LogLevel.Info]: 2,
+    [LogLevel.Warn]: 3,
+    [LogLevel.Error]: 4,
+};
+
+export interface ILogger {
+    /**
+     * Logs a debug message.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Logs an info message.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Logs a warning message.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Logs an error message.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    error(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * Configuration for logger initialization.
+ */
+export interface LogConfig {
+    /**
+     * Minimum log level to output.
+     * @default LogLevel.Info
+     */
+    level?: LogLevel;
+    /**
+     * Logger implementation to use.
+     * @default new ConsoleLogger()
+     */
+    logger?: ILogger;
+    /**
+     * Whether logging should be silenced.
+     * @default true
+     */
+    silent?: boolean;
+}
+
+/**
+ * Default console-based logger implementation.
+ */
+export class ConsoleLogger implements ILogger {
+    debug(message: string, ...args: unknown[]): void {
+        console.debug(message, ...args);
+    }
+    info(message: string, ...args: unknown[]): void {
+        console.info(message, ...args);
+    }
+    warn(message: string, ...args: unknown[]): void {
+        console.warn(message, ...args);
+    }
+    error(message: string, ...args: unknown[]): void {
+        console.error(message, ...args);
+    }
+}
+
+/**
+ * Logger class that provides level-based logging functionality.
+ */
+export class Logger {
+    private readonly level: number;
+    private readonly logger: ILogger;
+    private readonly silent: boolean;
+
+    /**
+     * Creates a new logger instance.
+     * @param config - Logger configuration
+     */
+    constructor(config: Required<LogConfig>) {
+        this.level = logLevelMap[config.level];
+        this.logger = config.logger;
+        this.silent = config.silent;
+    }
+
+    /**
+     * Checks if a log level should be output based on configuration.
+     * @param level - The log level to check
+     * @returns True if the level should be logged
+     */
+    public shouldLog(level: LogLevel): boolean {
+        return !this.silent && this.level <= logLevelMap[level];
+    }
+
+    /**
+     * Checks if debug logging is enabled.
+     * @returns True if debug logs should be output
+     */
+    public isDebug(): boolean {
+        return this.shouldLog(LogLevel.Debug);
+    }
+
+    /**
+     * Logs a debug message if debug logging is enabled.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    public debug(message: string, ...args: unknown[]): void {
+        if (this.isDebug()) {
+            this.logger.debug(message, ...args);
+        }
+    }
+
+    /**
+     * Checks if info logging is enabled.
+     * @returns True if info logs should be output
+     */
+    public isInfo(): boolean {
+        return this.shouldLog(LogLevel.Info);
+    }
+
+    /**
+     * Logs an info message if info logging is enabled.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    public info(message: string, ...args: unknown[]): void {
+        if (this.isInfo()) {
+            this.logger.info(message, ...args);
+        }
+    }
+
+    /**
+     * Checks if warning logging is enabled.
+     * @returns True if warning logs should be output
+     */
+    public isWarn(): boolean {
+        return this.shouldLog(LogLevel.Warn);
+    }
+
+    /**
+     * Logs a warning message if warning logging is enabled.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    public warn(message: string, ...args: unknown[]): void {
+        if (this.isWarn()) {
+            this.logger.warn(message, ...args);
+        }
+    }
+
+    /**
+     * Checks if error logging is enabled.
+     * @returns True if error logs should be output
+     */
+    public isError(): boolean {
+        return this.shouldLog(LogLevel.Error);
+    }
+
+    /**
+     * Logs an error message if error logging is enabled.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    public error(message: string, ...args: unknown[]): void {
+        if (this.isError()) {
+            this.logger.error(message, ...args);
+        }
+    }
+}
+
+export function createLogger(config?: LogConfig | Logger): Logger {
+    if (config == null) {
+        return defaultLogger;
+    }
+    if (config instanceof Logger) {
+        return config;
+    }
+    config = config ?? {};
+    config.level ??= LogLevel.Info;
+    config.logger ??= new ConsoleLogger();
+    config.silent ??= true;
+    return new Logger(config as Required<LogConfig>);
+}
+
+const defaultLogger: Logger = new Logger({
+    level: LogLevel.Info,
+    logger: new ConsoleLogger(),
+    silent: true,
+});

package/core/runtime/index.ts

@@ -0,0 +1 @@
+export { RUNTIME } from "./runtime.js";