amogus-sdk-internal-utils 0.35.2

package/dist/utils/request.cjs

@@ -0,0 +1,100 @@
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
+const require_request = require('../errors/request.cjs');
+const require_isNetworkError = require('../errors/utils/isNetworkError.cjs');
+const require_toError = require('../errors/utils/toError.cjs');
+const require_abortSignal = require('./abortSignal.cjs');
+const require_withTimeout = require('./promise/withTimeout.cjs');
+const require_requestShouldRetry = require('./requestShouldRetry.cjs');
+let _lifeomic_attempt = require("@lifeomic/attempt");
+
+//#region src/utils/request.ts
+async function request({ retryOptions = { maxAttempts: 1 }, logger, ...params }) {
+	const overallStartTime = performance.now();
+	let totalNetworkTime = 0;
+	let attemptCount = 0;
+	const response = await (0, _lifeomic_attempt.retry)(async (ctx) => {
+		attemptCount = ctx.attemptNum + 1;
+		const attemptStartTime = performance.now();
+		logger?.debug("Sending HTTP request", {
+			url: params.url.toString(),
+			method: params.fetchOptions?.method || "GET",
+			body: JSON.stringify(params.body),
+			attempt: ctx.attemptNum
+		});
+		const response$1 = await request_(params);
+		const attemptDuration = performance.now() - attemptStartTime;
+		totalNetworkTime += attemptDuration;
+		logger?.debug("HTTP request attempt completed", {
+			attempt: ctx.attemptNum,
+			attemptDuration: Math.floor(attemptDuration),
+			statusCode: response$1.status,
+			success: response$1.ok,
+			responseSize: response$1.headers.get("content-length")
+		});
+		return response$1;
+	}, {
+		...retryOptions,
+		handleError: (err, context) => {
+			logger?.error("HTTP request attempt failed", {
+				attempt: context.attemptNum,
+				errorMessage: require_toError.toError(err).message
+			});
+			if (!require_requestShouldRetry.requestShouldRetry(err) || params.fetchOptions?.signal?.reason === err) context.abort();
+		}
+	});
+	const overallDuration = performance.now() - overallStartTime;
+	const retryOverhead = overallDuration - totalNetworkTime;
+	logger?.[attemptCount > 1 ? "info" : "debug"]("HTTP request completed", {
+		statusCode: response.status,
+		success: response.ok,
+		totalDuration: Math.floor(overallDuration),
+		networkTime: Math.floor(totalNetworkTime),
+		retryOverhead: Math.floor(retryOverhead),
+		attempts: attemptCount,
+		responseSize: response.headers.get("content-length")
+	});
+	return response;
+}
+async function request_({ url, body, timeout = 1e4, fetchOptions }) {
+	const { headers: customHeaders, method, signal: signal_ } = fetchOptions ?? {};
+	try {
+		const headers = new Headers(customHeaders);
+		headers.set("Content-Type", "application/json");
+		const response = await require_withTimeout.withTimeout(({ signal }) => {
+			return fetch(url, {
+				...fetchOptions,
+				method,
+				headers,
+				body: JSON.stringify(body),
+				signal: require_abortSignal.mergeAbortSignals([signal_, timeout > 0 ? signal : null].filter(Boolean))
+			});
+		}, {
+			errorInstance: new require_request.TimeoutError({
+				body,
+				url: url.toString()
+			}),
+			timeout,
+			signal: true
+		});
+		if (!response.ok) throw new require_request.HttpRequestError({
+			body,
+			details: response.statusText,
+			headers: response.headers,
+			status: response.status,
+			url: url.toString()
+		});
+		return response;
+	} catch (err) {
+		if (err instanceof require_request.HttpRequestError) throw err;
+		if (err instanceof require_request.TimeoutError) throw err;
+		if (require_isNetworkError.isNetworkError(err)) throw new require_request.HttpRequestError({
+			body,
+			cause: err,
+			url: url.toString()
+		});
+		throw err;
+	}
+}
+
+//#endregion
+exports.request = request;

package/dist/utils/request.d.cts

@@ -0,0 +1,27 @@
+import { HttpRequestError, TimeoutError } from "../errors/request.cjs";
+import { ILogger } from "../logger.cjs";
+import { RetryOptions } from "./retry.cjs";
+
+//#region src/utils/request.d.ts
+type RequestErrorType = HttpRequestError | TimeoutError;
+declare function request({
+  retryOptions,
+  logger,
+  ...params
+}: Parameters<typeof request_>[0] & {
+  retryOptions?: RetryOptions;
+  logger?: ILogger;
+}): Promise<Response>;
+declare function request_({
+  url,
+  body,
+  timeout,
+  fetchOptions
+}: {
+  url: string | URL;
+  body?: unknown | undefined;
+  timeout?: number | undefined;
+  fetchOptions?: Omit<RequestInit, "body"> | undefined;
+}): Promise<Response>;
+//#endregion
+export { RequestErrorType, request };

package/dist/utils/request.d.ts

@@ -0,0 +1,27 @@
+import { HttpRequestError, TimeoutError } from "../errors/request.js";
+import { ILogger } from "../logger.js";
+import { RetryOptions } from "./retry.js";
+
+//#region src/utils/request.d.ts
+type RequestErrorType = HttpRequestError | TimeoutError;
+declare function request({
+  retryOptions,
+  logger,
+  ...params
+}: Parameters<typeof request_>[0] & {
+  retryOptions?: RetryOptions;
+  logger?: ILogger;
+}): Promise<Response>;
+declare function request_({
+  url,
+  body,
+  timeout,
+  fetchOptions
+}: {
+  url: string | URL;
+  body?: unknown | undefined;
+  timeout?: number | undefined;
+  fetchOptions?: Omit<RequestInit, "body"> | undefined;
+}): Promise<Response>;
+//#endregion
+export { RequestErrorType, request };

package/dist/utils/request.js

@@ -0,0 +1,99 @@
+import { HttpRequestError, TimeoutError } from "../errors/request.js";
+import { isNetworkError } from "../errors/utils/isNetworkError.js";
+import { toError } from "../errors/utils/toError.js";
+import { mergeAbortSignals } from "./abortSignal.js";
+import { withTimeout } from "./promise/withTimeout.js";
+import { requestShouldRetry } from "./requestShouldRetry.js";
+import { retry } from "@lifeomic/attempt";
+
+//#region src/utils/request.ts
+async function request({ retryOptions = { maxAttempts: 1 }, logger, ...params }) {
+	const overallStartTime = performance.now();
+	let totalNetworkTime = 0;
+	let attemptCount = 0;
+	const response = await retry(async (ctx) => {
+		attemptCount = ctx.attemptNum + 1;
+		const attemptStartTime = performance.now();
+		logger?.debug("Sending HTTP request", {
+			url: params.url.toString(),
+			method: params.fetchOptions?.method || "GET",
+			body: JSON.stringify(params.body),
+			attempt: ctx.attemptNum
+		});
+		const response$1 = await request_(params);
+		const attemptDuration = performance.now() - attemptStartTime;
+		totalNetworkTime += attemptDuration;
+		logger?.debug("HTTP request attempt completed", {
+			attempt: ctx.attemptNum,
+			attemptDuration: Math.floor(attemptDuration),
+			statusCode: response$1.status,
+			success: response$1.ok,
+			responseSize: response$1.headers.get("content-length")
+		});
+		return response$1;
+	}, {
+		...retryOptions,
+		handleError: (err, context) => {
+			logger?.error("HTTP request attempt failed", {
+				attempt: context.attemptNum,
+				errorMessage: toError(err).message
+			});
+			if (!requestShouldRetry(err) || params.fetchOptions?.signal?.reason === err) context.abort();
+		}
+	});
+	const overallDuration = performance.now() - overallStartTime;
+	const retryOverhead = overallDuration - totalNetworkTime;
+	logger?.[attemptCount > 1 ? "info" : "debug"]("HTTP request completed", {
+		statusCode: response.status,
+		success: response.ok,
+		totalDuration: Math.floor(overallDuration),
+		networkTime: Math.floor(totalNetworkTime),
+		retryOverhead: Math.floor(retryOverhead),
+		attempts: attemptCount,
+		responseSize: response.headers.get("content-length")
+	});
+	return response;
+}
+async function request_({ url, body, timeout = 1e4, fetchOptions }) {
+	const { headers: customHeaders, method, signal: signal_ } = fetchOptions ?? {};
+	try {
+		const headers = new Headers(customHeaders);
+		headers.set("Content-Type", "application/json");
+		const response = await withTimeout(({ signal }) => {
+			return fetch(url, {
+				...fetchOptions,
+				method,
+				headers,
+				body: JSON.stringify(body),
+				signal: mergeAbortSignals([signal_, timeout > 0 ? signal : null].filter(Boolean))
+			});
+		}, {
+			errorInstance: new TimeoutError({
+				body,
+				url: url.toString()
+			}),
+			timeout,
+			signal: true
+		});
+		if (!response.ok) throw new HttpRequestError({
+			body,
+			details: response.statusText,
+			headers: response.headers,
+			status: response.status,
+			url: url.toString()
+		});
+		return response;
+	} catch (err) {
+		if (err instanceof HttpRequestError) throw err;
+		if (err instanceof TimeoutError) throw err;
+		if (isNetworkError(err)) throw new HttpRequestError({
+			body,
+			cause: err,
+			url: url.toString()
+		});
+		throw err;
+	}
+}
+
+//#endregion
+export { request };

package/dist/utils/requestShouldRetry.cjs

@@ -0,0 +1,20 @@
+const require_request = require('../errors/request.cjs');
+
+//#region src/utils/requestShouldRetry.ts
+function requestShouldRetry(error) {
+	if (error instanceof require_request.HttpRequestError && error.status != null) {
+		if (error.status === 403) return true;
+		if (error.status === 408) return true;
+		if (error.status === 413) return true;
+		if (error.status === 429) return true;
+		if (error.status === 500) return true;
+		if (error.status === 502) return true;
+		if (error.status === 503) return true;
+		if (error.status === 504) return true;
+		return false;
+	}
+	return true;
+}
+
+//#endregion
+exports.requestShouldRetry = requestShouldRetry;

package/dist/utils/requestShouldRetry.js

@@ -0,0 +1,20 @@
+import { HttpRequestError } from "../errors/request.js";
+
+//#region src/utils/requestShouldRetry.ts
+function requestShouldRetry(error) {
+	if (error instanceof HttpRequestError && error.status != null) {
+		if (error.status === 403) return true;
+		if (error.status === 408) return true;
+		if (error.status === 413) return true;
+		if (error.status === 429) return true;
+		if (error.status === 500) return true;
+		if (error.status === 502) return true;
+		if (error.status === 503) return true;
+		if (error.status === 504) return true;
+		return false;
+	}
+	return true;
+}
+
+//#endregion
+export { requestShouldRetry };

package/dist/utils/retry.cjs

@@ -0,0 +1,66 @@
+
+//#region src/utils/retry.ts
+const RETRY_CONFIGS = {
+	THIRTY_SECS_AGGRESSIVE: {
+		delay: 500,
+		minDelay: 500,
+		factor: 2,
+		maxAttempts: 6,
+		jitter: true
+	},
+	ONE_MIN_MODERATE: {
+		delay: 1e3,
+		minDelay: 1e3,
+		factor: 1.5,
+		maxAttempts: 8,
+		jitter: true
+	},
+	TWO_MINS_GRADUAL: {
+		delay: 500,
+		minDelay: 500,
+		factor: 1.5,
+		maxAttempts: 12,
+		jitter: true
+	},
+	FIVE_MINS_STEADY: {
+		delay: 2e3,
+		minDelay: 2e3,
+		factor: 1.4,
+		maxAttempts: 12,
+		jitter: true
+	},
+	THIRTY_MINS_PATIENT: {
+		delay: 5e3,
+		minDelay: 5e3,
+		factor: 1.3,
+		maxAttempts: 18,
+		jitter: true
+	},
+	TWO_HOURS_PERSISTENT: {
+		delay: 1e4,
+		minDelay: 1e4,
+		factor: 1.2,
+		maxAttempts: 27,
+		jitter: true
+	}
+};
+/**
+* Calculates how many attempts fit within a timeout budget.
+*
+* @returns number of attempts that fit within the timeout
+*/
+function calculateMaxAttempts(timeout, delay, factor) {
+	let totalDelay = 0;
+	let currentDelay = delay;
+	let attempts = 1;
+	while (totalDelay + currentDelay <= timeout) {
+		totalDelay += currentDelay;
+		attempts++;
+		currentDelay *= factor;
+	}
+	return Math.max(1, attempts);
+}
+
+//#endregion
+exports.RETRY_CONFIGS = RETRY_CONFIGS;
+exports.calculateMaxAttempts = calculateMaxAttempts;

package/dist/utils/retry.d.cts

@@ -0,0 +1,56 @@
+import { AttemptOptions } from "@lifeomic/attempt";
+
+//#region src/utils/retry.d.ts
+type RetryOptions = Partial<Pick<AttemptOptions<unknown>, "delay" | "initialDelay" | "minDelay" | "maxDelay" | "factor" | "maxAttempts" | "timeout" | "jitter" | "initialJitter">>;
+declare const RETRY_CONFIGS: {
+  THIRTY_SECS_AGGRESSIVE: {
+    delay: number;
+    minDelay: number;
+    factor: number;
+    maxAttempts: number;
+    jitter: boolean;
+  };
+  ONE_MIN_MODERATE: {
+    delay: number;
+    minDelay: number;
+    factor: number;
+    maxAttempts: number;
+    jitter: boolean;
+  };
+  TWO_MINS_GRADUAL: {
+    delay: number;
+    minDelay: number;
+    factor: number;
+    maxAttempts: number;
+    jitter: boolean;
+  };
+  FIVE_MINS_STEADY: {
+    delay: number;
+    minDelay: number;
+    factor: number;
+    maxAttempts: number;
+    jitter: boolean;
+  };
+  THIRTY_MINS_PATIENT: {
+    delay: number;
+    minDelay: number;
+    factor: number;
+    maxAttempts: number;
+    jitter: boolean;
+  };
+  TWO_HOURS_PERSISTENT: {
+    delay: number;
+    minDelay: number;
+    factor: number;
+    maxAttempts: number;
+    jitter: boolean;
+  };
+};
+/**
+ * Calculates how many attempts fit within a timeout budget.
+ *
+ * @returns number of attempts that fit within the timeout
+ */
+declare function calculateMaxAttempts(timeout: number, delay: number, factor: number): number;
+//#endregion
+export { RETRY_CONFIGS, RetryOptions, calculateMaxAttempts };

package/dist/utils/retry.d.ts

@@ -0,0 +1,56 @@
+import { AttemptOptions } from "@lifeomic/attempt";
+
+//#region src/utils/retry.d.ts
+type RetryOptions = Partial<Pick<AttemptOptions<unknown>, "delay" | "initialDelay" | "minDelay" | "maxDelay" | "factor" | "maxAttempts" | "timeout" | "jitter" | "initialJitter">>;
+declare const RETRY_CONFIGS: {
+  THIRTY_SECS_AGGRESSIVE: {
+    delay: number;
+    minDelay: number;
+    factor: number;
+    maxAttempts: number;
+    jitter: boolean;
+  };
+  ONE_MIN_MODERATE: {
+    delay: number;
+    minDelay: number;
+    factor: number;
+    maxAttempts: number;
+    jitter: boolean;
+  };
+  TWO_MINS_GRADUAL: {
+    delay: number;
+    minDelay: number;
+    factor: number;
+    maxAttempts: number;
+    jitter: boolean;
+  };
+  FIVE_MINS_STEADY: {
+    delay: number;
+    minDelay: number;
+    factor: number;
+    maxAttempts: number;
+    jitter: boolean;
+  };
+  THIRTY_MINS_PATIENT: {
+    delay: number;
+    minDelay: number;
+    factor: number;
+    maxAttempts: number;
+    jitter: boolean;
+  };
+  TWO_HOURS_PERSISTENT: {
+    delay: number;
+    minDelay: number;
+    factor: number;
+    maxAttempts: number;
+    jitter: boolean;
+  };
+};
+/**
+ * Calculates how many attempts fit within a timeout budget.
+ *
+ * @returns number of attempts that fit within the timeout
+ */
+declare function calculateMaxAttempts(timeout: number, delay: number, factor: number): number;
+//#endregion
+export { RETRY_CONFIGS, RetryOptions, calculateMaxAttempts };

package/dist/utils/retry.js

@@ -0,0 +1,64 @@
+//#region src/utils/retry.ts
+const RETRY_CONFIGS = {
+	THIRTY_SECS_AGGRESSIVE: {
+		delay: 500,
+		minDelay: 500,
+		factor: 2,
+		maxAttempts: 6,
+		jitter: true
+	},
+	ONE_MIN_MODERATE: {
+		delay: 1e3,
+		minDelay: 1e3,
+		factor: 1.5,
+		maxAttempts: 8,
+		jitter: true
+	},
+	TWO_MINS_GRADUAL: {
+		delay: 500,
+		minDelay: 500,
+		factor: 1.5,
+		maxAttempts: 12,
+		jitter: true
+	},
+	FIVE_MINS_STEADY: {
+		delay: 2e3,
+		minDelay: 2e3,
+		factor: 1.4,
+		maxAttempts: 12,
+		jitter: true
+	},
+	THIRTY_MINS_PATIENT: {
+		delay: 5e3,
+		minDelay: 5e3,
+		factor: 1.3,
+		maxAttempts: 18,
+		jitter: true
+	},
+	TWO_HOURS_PERSISTENT: {
+		delay: 1e4,
+		minDelay: 1e4,
+		factor: 1.2,
+		maxAttempts: 27,
+		jitter: true
+	}
+};
+/**
+* Calculates how many attempts fit within a timeout budget.
+*
+* @returns number of attempts that fit within the timeout
+*/
+function calculateMaxAttempts(timeout, delay, factor) {
+	let totalDelay = 0;
+	let currentDelay = delay;
+	let attempts = 1;
+	while (totalDelay + currentDelay <= timeout) {
+		totalDelay += currentDelay;
+		attempts++;
+		currentDelay *= factor;
+	}
+	return Math.max(1, attempts);
+}
+
+//#endregion
+export { RETRY_CONFIGS, calculateMaxAttempts };

package/dist/utils/rpc-endpoint.cjs

@@ -0,0 +1,56 @@
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
+let _scure_base = require("@scure/base");
+
+//#region src/utils/rpc-endpoint.ts
+/**
+* Parses URL with embedded credentials (http://user:pass@host) and extracts
+* Authorization header. Returns cleaned URL without credentials.
+*/
+function parseUrlCredentials(urlString) {
+	const url = new URL(urlString);
+	const headers = {};
+	if (url.username || url.password) {
+		const credentials = `${url.username}:${url.password}`;
+		headers.Authorization = `Basic ${_scure_base.base64.encode(new TextEncoder().encode(credentials))}`;
+		url.username = "";
+		url.password = "";
+		return {
+			url: url.toString(),
+			headers
+		};
+	}
+	return {
+		url: urlString,
+		headers
+	};
+}
+/**
+* Normalizes RpcEndpoint to RpcEndpointConfig, parsing credentials from URL if present.
+*/
+function normalizeRpcEndpoint(endpoint) {
+	const config = typeof endpoint === "string" ? { url: endpoint } : endpoint;
+	const { url, headers: parsedHeaders } = parseUrlCredentials(config.url);
+	return {
+		url,
+		headers: {
+			...parsedHeaders,
+			...config.headers
+		}
+	};
+}
+/**
+* Extracts plain URLs from RpcEndpoint array.
+* Use this when passing RPC endpoints to external SDKs that only support URL strings.
+*
+* @note This strips credentials from URLs. For credential-containing URLs,
+* use normalizeRpcEndpoint() to properly convert them to auth headers.
+*/
+function extractRpcUrls(endpoints) {
+	return endpoints.map((endpoint) => {
+		return parseUrlCredentials(typeof endpoint === "string" ? endpoint : endpoint.url).url;
+	});
+}
+
+//#endregion
+exports.extractRpcUrls = extractRpcUrls;
+exports.normalizeRpcEndpoint = normalizeRpcEndpoint;

package/dist/utils/rpc-endpoint.d.cts

@@ -0,0 +1,20 @@
+//#region src/utils/rpc-endpoint.d.ts
+interface RpcEndpointConfig {
+  url: string;
+  headers?: Record<string, string>;
+}
+type RpcEndpoint = string | RpcEndpointConfig;
+/**
+ * Normalizes RpcEndpoint to RpcEndpointConfig, parsing credentials from URL if present.
+ */
+declare function normalizeRpcEndpoint(endpoint: RpcEndpoint): RpcEndpointConfig;
+/**
+ * Extracts plain URLs from RpcEndpoint array.
+ * Use this when passing RPC endpoints to external SDKs that only support URL strings.
+ *
+ * @note This strips credentials from URLs. For credential-containing URLs,
+ * use normalizeRpcEndpoint() to properly convert them to auth headers.
+ */
+declare function extractRpcUrls(endpoints: RpcEndpoint[]): string[];
+//#endregion
+export { RpcEndpoint, RpcEndpointConfig, extractRpcUrls, normalizeRpcEndpoint };

package/dist/utils/rpc-endpoint.d.ts

@@ -0,0 +1,20 @@
+//#region src/utils/rpc-endpoint.d.ts
+interface RpcEndpointConfig {
+  url: string;
+  headers?: Record<string, string>;
+}
+type RpcEndpoint = string | RpcEndpointConfig;
+/**
+ * Normalizes RpcEndpoint to RpcEndpointConfig, parsing credentials from URL if present.
+ */
+declare function normalizeRpcEndpoint(endpoint: RpcEndpoint): RpcEndpointConfig;
+/**
+ * Extracts plain URLs from RpcEndpoint array.
+ * Use this when passing RPC endpoints to external SDKs that only support URL strings.
+ *
+ * @note This strips credentials from URLs. For credential-containing URLs,
+ * use normalizeRpcEndpoint() to properly convert them to auth headers.
+ */
+declare function extractRpcUrls(endpoints: RpcEndpoint[]): string[];
+//#endregion
+export { RpcEndpoint, RpcEndpointConfig, extractRpcUrls, normalizeRpcEndpoint };

package/dist/utils/rpc-endpoint.js

@@ -0,0 +1,54 @@
+import { base64 } from "@scure/base";
+
+//#region src/utils/rpc-endpoint.ts
+/**
+* Parses URL with embedded credentials (http://user:pass@host) and extracts
+* Authorization header. Returns cleaned URL without credentials.
+*/
+function parseUrlCredentials(urlString) {
+	const url = new URL(urlString);
+	const headers = {};
+	if (url.username || url.password) {
+		const credentials = `${url.username}:${url.password}`;
+		headers.Authorization = `Basic ${base64.encode(new TextEncoder().encode(credentials))}`;
+		url.username = "";
+		url.password = "";
+		return {
+			url: url.toString(),
+			headers
+		};
+	}
+	return {
+		url: urlString,
+		headers
+	};
+}
+/**
+* Normalizes RpcEndpoint to RpcEndpointConfig, parsing credentials from URL if present.
+*/
+function normalizeRpcEndpoint(endpoint) {
+	const config = typeof endpoint === "string" ? { url: endpoint } : endpoint;
+	const { url, headers: parsedHeaders } = parseUrlCredentials(config.url);
+	return {
+		url,
+		headers: {
+			...parsedHeaders,
+			...config.headers
+		}
+	};
+}
+/**
+* Extracts plain URLs from RpcEndpoint array.
+* Use this when passing RPC endpoints to external SDKs that only support URL strings.
+*
+* @note This strips credentials from URLs. For credential-containing URLs,
+* use normalizeRpcEndpoint() to properly convert them to auth headers.
+*/
+function extractRpcUrls(endpoints) {
+	return endpoints.map((endpoint) => {
+		return parseUrlCredentials(typeof endpoint === "string" ? endpoint : endpoint.url).url;
+	});
+}
+
+//#endregion
+export { extractRpcUrls, normalizeRpcEndpoint };