@settlemint/sdk-utils 2.3.2 → 2.3.3-main6f8f814c

package/dist/http.cjs

@@ -1,91 +1,229 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
+
+//#region src/logging/mask-tokens.ts
+/**
+* Masks sensitive SettleMint tokens in output text by replacing them with asterisks.
+* Handles personal access tokens (PAT), application access tokens (AAT), and service account tokens (SAT).
+*
+* @param output - The text string that may contain sensitive tokens
+* @returns The text with any sensitive tokens masked with asterisks
+* @example
+* import { maskTokens } from "@settlemint/sdk-utils/terminal";
+*
+* // Masks a token in text
+* const masked = maskTokens("Token: sm_pat_****"); // "Token: ***"
+*/
+const maskTokens = (output) => {
+	return output.replace(/sm_(pat|aat|sat)_[0-9a-zA-Z]+/g, "***");
 };
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/http.ts
-var http_exports = {};
-__export(http_exports, {
-  fetchWithRetry: () => fetchWithRetry,
-  graphqlFetchWithRetry: () => graphqlFetchWithRetry
-});
-module.exports = __toCommonJS(http_exports);
+//#endregion
+//#region src/logging/logger.ts
+/**
+* Creates a simple logger with configurable log level
+*
+* @param options - Configuration options for the logger
+* @param options.level - The minimum log level to output (default: warn)
+* @param options.prefix - The prefix to add to the log message (default: "")
+* @returns A logger instance with debug, info, warn, and error methods
+*
+* @example
+* import { createLogger } from "@/utils/logging/logger";
+*
+* const logger = createLogger({ level: 'info' });
+*
+* logger.info('User logged in', { userId: '123' });
+* logger.error('Operation failed', new Error('Connection timeout'));
+*/
+function createLogger(options = {}) {
+	const { level = "warn", prefix = "" } = options;
+	const logLevels = {
+		debug: 0,
+		info: 1,
+		warn: 2,
+		error: 3,
+		none: 4
+	};
+	const currentLevelValue = logLevels[level];
+	const formatArgs = (args) => {
+		if (args.length === 0 || args.every((arg) => arg === undefined || arg === null)) {
+			return "";
+		}
+		const formatted = args.map((arg) => {
+			if (arg instanceof Error) {
+				return `\n${arg.stack || arg.message}`;
+			}
+			if (typeof arg === "object" && arg !== null) {
+				return `\n${JSON.stringify(arg, null, 2)}`;
+			}
+			return ` ${String(arg)}`;
+		}).join("");
+		return `, args:${formatted}`;
+	};
+	const shouldLog = (level$1) => {
+		return logLevels[level$1] >= currentLevelValue;
+	};
+	return {
+		debug: (message, ...args) => {
+			if (shouldLog("debug")) {
+				console.debug(`\x1b[32m${prefix}[DEBUG] ${maskTokens(message)}${maskTokens(formatArgs(args))}\x1b[0m`);
+			}
+		},
+		info: (message, ...args) => {
+			if (shouldLog("info")) {
+				console.info(`\x1b[34m${prefix}[INFO] ${maskTokens(message)}${maskTokens(formatArgs(args))}\x1b[0m`);
+			}
+		},
+		warn: (message, ...args) => {
+			if (shouldLog("warn")) {
+				console.warn(`\x1b[33m${prefix}[WARN] ${maskTokens(message)}${maskTokens(formatArgs(args))}\x1b[0m`);
+			}
+		},
+		error: (message, ...args) => {
+			if (shouldLog("error")) {
+				console.error(`\x1b[31m${prefix}[ERROR] ${maskTokens(message)}${maskTokens(formatArgs(args))}\x1b[0m`);
+			}
+		}
+	};
+}
+/**
+* Default logger instance with standard configuration
+*/
+const logger = createLogger();
 
-// src/retry.ts
+//#endregion
+//#region src/retry.ts
+/**
+* Retry a function when it fails.
+* @param fn - The function to retry.
+* @param maxRetries - The maximum number of retries.
+* @param initialSleepTime - The initial time to sleep between exponential backoff retries.
+* @param stopOnError - The function to stop on error.
+* @returns The result of the function or undefined if it fails.
+* @example
+* import { retryWhenFailed } from "@settlemint/sdk-utils";
+* import { readFile } from "node:fs/promises";
+*
+* const result = await retryWhenFailed(() => readFile("/path/to/file.txt"), 3, 1_000);
+*/
 async function retryWhenFailed(fn, maxRetries = 5, initialSleepTime = 1e3, stopOnError) {
-  let attempt = 0;
-  while (attempt < maxRetries) {
-    try {
-      return await fn();
-    } catch (e) {
-      if (typeof stopOnError === "function") {
-        const error = e;
-        if (stopOnError(error)) {
-          throw error;
-        }
-      }
-      attempt += 1;
-      if (attempt >= maxRetries) {
-        throw e;
-      }
-      const jitter = Math.random();
-      const delay = 2 ** attempt * initialSleepTime * jitter;
-      await new Promise((resolve) => setTimeout(resolve, delay));
-    }
-  }
-  throw new Error("Retry failed");
+	let retries = 0;
+	const maxAttempts = maxRetries + 1;
+	while (retries < maxAttempts) {
+		try {
+			return await fn();
+		} catch (e) {
+			const error = e;
+			if (typeof stopOnError === "function") {
+				if (stopOnError(error)) {
+					throw error;
+				}
+			}
+			if (retries >= maxRetries) {
+				throw e;
+			}
+			const baseDelay = 2 ** retries * initialSleepTime;
+			const jitterAmount = initialSleepTime * (Math.random() / 10);
+			const delay = baseDelay + jitterAmount;
+			retries += 1;
+			logger.warn(`An error occurred ${error.message}, retrying in ${delay.toFixed(0)}ms (retry ${retries} of ${maxRetries})...`);
+			await new Promise((resolve) => setTimeout(resolve, delay));
+		}
+	}
+	throw new Error("Retry failed");
 }
 
-// src/http/fetch-with-retry.ts
+//#endregion
+//#region src/http/fetch-with-retry.ts
+/**
+* Retry an HTTP request with exponential backoff and jitter.
+* Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors.
+*
+* @param input - The URL or Request object to fetch
+* @param init - The fetch init options
+* @param maxRetries - Maximum number of retry attempts
+* @param initialSleepTime - Initial sleep time between retries in ms
+* @returns The fetch Response
+* @throws Error if all retries fail
+* @example
+* import { fetchWithRetry } from "@settlemint/sdk-utils/http";
+*
+* const response = await fetchWithRetry("https://api.example.com/data");
+*/
 async function fetchWithRetry(input, init, maxRetries = 5, initialSleepTime = 3e3) {
-  return retryWhenFailed(
-    async () => {
-      const response = await fetch(input, init);
-      if (response.ok) {
-        return response;
-      }
-      if (response.status < 500 && response.status !== 429 && response.status !== 408 && response.status !== 0) {
-        return response;
-      }
-      throw new Error(`HTTP error! status: ${response.status} ${response.statusText}`);
-    },
-    maxRetries,
-    initialSleepTime
-  );
+	return retryWhenFailed(async () => {
+		const response = await fetch(input, init);
+		if (response.ok) {
+			return response;
+		}
+		if (response.status < 500 && response.status !== 429 && response.status !== 408 && response.status !== 0) {
+			return response;
+		}
+		throw new Error(`HTTP error! status: ${response.status} ${response.statusText}`);
+	}, maxRetries, initialSleepTime);
 }
 
-// src/http/graphql-fetch-with-retry.ts
+//#endregion
+//#region src/http/graphql-fetch-with-retry.ts
+/**
+* Executes a GraphQL request with automatic retries using exponential backoff and jitter.
+* Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors.
+* Will also retry if the GraphQL response contains errors.
+*
+* @param input - The URL or Request object for the GraphQL endpoint
+* @param init - Optional fetch configuration options
+* @param maxRetries - Maximum retry attempts before failing (default: 5)
+* @param initialSleepTime - Initial delay between retries in milliseconds (default: 3000)
+* @returns The parsed GraphQL response data
+* @throws Error if all retries fail or if GraphQL response contains errors
+* @example
+* import { graphqlFetchWithRetry } from "@settlemint/sdk-utils/http";
+*
+* const data = await graphqlFetchWithRetry<{ user: { id: string } }>(
+*   "https://api.example.com/graphql",
+*   {
+*     method: "POST",
+*     headers: { "Content-Type": "application/json" },
+*     body: JSON.stringify({
+*       query: `query GetUser($id: ID!) {
+*         user(id: $id) {
+*           id
+*         }
+*       }`,
+*       variables: { id: "123" }
+*     })
+*   }
+* );
+*/
 async function graphqlFetchWithRetry(input, init, maxRetries = 5, initialSleepTime = 3e3) {
-  return retryWhenFailed(
-    async () => {
-      const response = await fetchWithRetry(input, init);
-      const json = await response.json();
-      if (json.errors) {
-        throw new Error(`GraphQL errors in response: ${json.errors.map((error) => error.message).join(", ")}`);
-      }
-      return json.data;
-    },
-    maxRetries,
-    initialSleepTime
-  );
+	return retryWhenFailed(async () => {
+		const response = await fetchWithRetry(input, init);
+		const json = await response.json();
+		if (json.errors) {
+			throw new Error(`GraphQL errors in response: ${json.errors.map((error) => error.message).join(", ")}`);
+		}
+		return json.data;
+	}, maxRetries, initialSleepTime);
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  fetchWithRetry,
-  graphqlFetchWithRetry
-});
+
+//#endregion
+//#region src/http/headers.ts
+function appendHeaders(headers, additionalHeaders) {
+	const defaultHeaders = typeof headers === "function" ? headers() : headers;
+	const filteredAdditionalHeaders = Object.entries(additionalHeaders).filter(([_, value]) => value !== undefined);
+	if (Array.isArray(defaultHeaders)) {
+		return [...defaultHeaders, ...filteredAdditionalHeaders];
+	}
+	if (defaultHeaders instanceof Headers) {
+		return new Headers([...defaultHeaders, ...filteredAdditionalHeaders]);
+	}
+	return {
+		...defaultHeaders,
+		...Object.fromEntries(filteredAdditionalHeaders)
+	};
+}
+
+//#endregion
+exports.appendHeaders = appendHeaders;
+exports.fetchWithRetry = fetchWithRetry;
+exports.graphqlFetchWithRetry = graphqlFetchWithRetry;
 //# sourceMappingURL=http.cjs.map

package/dist/http.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/http.ts","../src/retry.ts","../src/http/fetch-with-retry.ts","../src/http/graphql-fetch-with-retry.ts"],"sourcesContent":["export { fetchWithRetry } from \"./http/fetch-with-retry.js\";\nexport { graphqlFetchWithRetry } from \"./http/graphql-fetch-with-retry.js\";\n","/**\n * Retry a function when it fails.\n * @param fn - The function to retry.\n * @param maxRetries - The maximum number of retries.\n * @param initialSleepTime - The initial time to sleep between exponential backoff retries.\n * @param stopOnError - The function to stop on error.\n * @returns The result of the function or undefined if it fails.\n * @example\n * import { retryWhenFailed } from \"@settlemint/sdk-utils\";\n * import { readFile } from \"node:fs/promises\";\n *\n * const result = await retryWhenFailed(() => readFile(\"/path/to/file.txt\"), 3, 1_000);\n */\nexport async function retryWhenFailed<T>(\n  fn: () => Promise<T>,\n  maxRetries = 5,\n  initialSleepTime = 1_000,\n  stopOnError?: (error: Error) => boolean,\n): Promise<T> {\n  let attempt = 0;\n\n  while (attempt < maxRetries) {\n    try {\n      return await fn();\n    } catch (e) {\n      if (typeof stopOnError === \"function\") {\n        const error = e as Error;\n        if (stopOnError(error)) {\n          throw error;\n        }\n      }\n      attempt += 1;\n      if (attempt >= maxRetries) {\n        throw e;\n      }\n      // Exponential backoff with full jitter to prevent thundering herd\n      const jitter = Math.random();\n      const delay = 2 ** attempt * initialSleepTime * jitter; // 0-1x of 1s, 2s, 4s base\n      await new Promise((resolve) => setTimeout(resolve, delay));\n    }\n  }\n\n  throw new Error(\"Retry failed\");\n}\n","import { retryWhenFailed } from \"../retry.js\";\n\n/**\n * Retry an HTTP request with exponential backoff and jitter.\n * Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors.\n *\n * @param input - The URL or Request object to fetch\n * @param init - The fetch init options\n * @param maxRetries - Maximum number of retry attempts\n * @param initialSleepTime - Initial sleep time between retries in ms\n * @returns The fetch Response\n * @throws Error if all retries fail\n * @example\n * import { fetchWithRetry } from \"@settlemint/sdk-utils/http\";\n *\n * const response = await fetchWithRetry(\"https://api.example.com/data\");\n */\nexport async function fetchWithRetry(\n  input: RequestInfo | URL,\n  init?: RequestInit,\n  maxRetries = 5,\n  initialSleepTime = 3_000,\n): Promise<Response> {\n  return retryWhenFailed(\n    async () => {\n      const response = await fetch(input, init);\n      if (response.ok) {\n        return response;\n      }\n      // Only retry on 5xx server errors, 429 rate limit, timeout, and network errors\n      if (response.status < 500 && response.status !== 429 && response.status !== 408 && response.status !== 0) {\n        return response;\n      }\n      throw new Error(`HTTP error! status: ${response.status} ${response.statusText}`);\n    },\n    maxRetries,\n    initialSleepTime,\n  );\n}\n","import { retryWhenFailed } from \"../retry.js\";\nimport { fetchWithRetry } from \"./fetch-with-retry.js\";\n\n/**\n * Executes a GraphQL request with automatic retries using exponential backoff and jitter.\n * Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors.\n * Will also retry if the GraphQL response contains errors.\n *\n * @param input - The URL or Request object for the GraphQL endpoint\n * @param init - Optional fetch configuration options\n * @param maxRetries - Maximum retry attempts before failing (default: 5)\n * @param initialSleepTime - Initial delay between retries in milliseconds (default: 3000)\n * @returns The parsed GraphQL response data\n * @throws Error if all retries fail or if GraphQL response contains errors\n * @example\n * import { graphqlFetchWithRetry } from \"@settlemint/sdk-utils/http\";\n *\n * const data = await graphqlFetchWithRetry<{ user: { id: string } }>(\n *   \"https://api.example.com/graphql\",\n *   {\n *     method: \"POST\",\n *     headers: { \"Content-Type\": \"application/json\" },\n *     body: JSON.stringify({\n *       query: `query GetUser($id: ID!) {\n *         user(id: $id) {\n *           id\n *         }\n *       }`,\n *       variables: { id: \"123\" }\n *     })\n *   }\n * );\n */\nexport async function graphqlFetchWithRetry<Data>(\n  input: RequestInfo | URL,\n  init?: RequestInit,\n  maxRetries = 5,\n  initialSleepTime = 3_000,\n): Promise<Data> {\n  return retryWhenFailed<Data>(\n    async () => {\n      const response = await fetchWithRetry(input, init);\n      const json: { errors?: { message: string }[]; data: Data } = await response.json();\n      if (json.errors) {\n        throw new Error(`GraphQL errors in response: ${json.errors.map((error) => error.message).join(\", \")}`);\n      }\n      return json.data;\n    },\n    maxRetries,\n    initialSleepTime,\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACaA,eAAsB,gBACpB,IACA,aAAa,GACb,mBAAmB,KACnB,aACY;AACZ,MAAI,UAAU;AAEd,SAAO,UAAU,YAAY;AAC3B,QAAI;AACF,aAAO,MAAM,GAAG;AAAA,IAClB,SAAS,GAAG;AACV,UAAI,OAAO,gBAAgB,YAAY;AACrC,cAAM,QAAQ;AACd,YAAI,YAAY,KAAK,GAAG;AACtB,gBAAM;AAAA,QACR;AAAA,MACF;AACA,iBAAW;AACX,UAAI,WAAW,YAAY;AACzB,cAAM;AAAA,MACR;AAEA,YAAM,SAAS,KAAK,OAAO;AAC3B,YAAM,QAAQ,KAAK,UAAU,mBAAmB;AAChD,YAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,KAAK,CAAC;AAAA,IAC3D;AAAA,EACF;AAEA,QAAM,IAAI,MAAM,cAAc;AAChC;;;AC1BA,eAAsB,eACpB,OACA,MACA,aAAa,GACb,mBAAmB,KACA;AACnB,SAAO;AAAA,IACL,YAAY;AACV,YAAM,WAAW,MAAM,MAAM,OAAO,IAAI;AACxC,UAAI,SAAS,IAAI;AACf,eAAO;AAAA,MACT;AAEA,UAAI,SAAS,SAAS,OAAO,SAAS,WAAW,OAAO,SAAS,WAAW,OAAO,SAAS,WAAW,GAAG;AACxG,eAAO;AAAA,MACT;AACA,YAAM,IAAI,MAAM,uBAAuB,SAAS,MAAM,IAAI,SAAS,UAAU,EAAE;AAAA,IACjF;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;;;ACLA,eAAsB,sBACpB,OACA,MACA,aAAa,GACb,mBAAmB,KACJ;AACf,SAAO;AAAA,IACL,YAAY;AACV,YAAM,WAAW,MAAM,eAAe,OAAO,IAAI;AACjD,YAAM,OAAuD,MAAM,SAAS,KAAK;AACjF,UAAI,KAAK,QAAQ;AACf,cAAM,IAAI,MAAM,+BAA+B,KAAK,OAAO,IAAI,CAAC,UAAU,MAAM,OAAO,EAAE,KAAK,IAAI,CAAC,EAAE;AAAA,MACvG;AACA,aAAO,KAAK;AAAA,IACd;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;","names":[]}
+{"version":3,"file":"http.cjs","names":["output: string","options: LoggerOptions","logLevels: Record<LogLevel, number>","args: unknown[]","level: LogLevel","level","message: string","fn: () => Promise<T>","stopOnError?: (error: Error) => boolean","input: RequestInfo | URL","init?: RequestInit","input: RequestInfo | URL","init?: RequestInit","json: { errors?: { message: string }[]; data: Data }","headers: MaybeLazy<HeadersInit> | undefined","additionalHeaders: Record<string, string | undefined>"],"sources":["../src/logging/mask-tokens.ts","../src/logging/logger.ts","../src/retry.ts","../src/http/fetch-with-retry.ts","../src/http/graphql-fetch-with-retry.ts","../src/http/headers.ts"],"sourcesContent":["/**\n * Masks sensitive SettleMint tokens in output text by replacing them with asterisks.\n * Handles personal access tokens (PAT), application access tokens (AAT), and service account tokens (SAT).\n *\n * @param output - The text string that may contain sensitive tokens\n * @returns The text with any sensitive tokens masked with asterisks\n * @example\n * import { maskTokens } from \"@settlemint/sdk-utils/terminal\";\n *\n * // Masks a token in text\n * const masked = maskTokens(\"Token: sm_pat_****\"); // \"Token: ***\"\n */\nexport const maskTokens = (output: string): string => {\n  return output.replace(/sm_(pat|aat|sat)_[0-9a-zA-Z]+/g, \"***\");\n};\n","import { maskTokens } from \"./mask-tokens.js\";\n\n/**\n * Log levels supported by the logger\n */\nexport type LogLevel = \"debug\" | \"info\" | \"warn\" | \"error\" | \"none\";\n\n/**\n * Configuration options for the logger\n * @interface LoggerOptions\n */\nexport interface LoggerOptions {\n  /** The minimum log level to output */\n  level?: LogLevel;\n  /** The prefix to add to the log message */\n  prefix?: string;\n}\n\n/**\n * Simple logger interface with basic logging methods\n * @interface Logger\n */\nexport interface Logger {\n  /** Log debug information */\n  debug: (message: string, ...args: unknown[]) => void;\n  /** Log general information */\n  info: (message: string, ...args: unknown[]) => void;\n  /** Log warnings */\n  warn: (message: string, ...args: unknown[]) => void;\n  /** Log errors */\n  error: (message: string, ...args: unknown[]) => void;\n}\n\n/**\n * Creates a simple logger with configurable log level\n *\n * @param options - Configuration options for the logger\n * @param options.level - The minimum log level to output (default: warn)\n * @param options.prefix - The prefix to add to the log message (default: \"\")\n * @returns A logger instance with debug, info, warn, and error methods\n *\n * @example\n * import { createLogger } from \"@/utils/logging/logger\";\n *\n * const logger = createLogger({ level: 'info' });\n *\n * logger.info('User logged in', { userId: '123' });\n * logger.error('Operation failed', new Error('Connection timeout'));\n */\nexport function createLogger(options: LoggerOptions = {}): Logger {\n  const { level = \"warn\", prefix = \"\" } = options;\n\n  const logLevels: Record<LogLevel, number> = {\n    debug: 0,\n    info: 1,\n    warn: 2,\n    error: 3,\n    none: 4,\n  };\n\n  const currentLevelValue = logLevels[level];\n\n  const formatArgs = (args: unknown[]): string => {\n    if (args.length === 0 || args.every((arg) => arg === undefined || arg === null)) {\n      return \"\";\n    }\n\n    const formatted = args\n      .map((arg) => {\n        if (arg instanceof Error) {\n          return `\\n${arg.stack || arg.message}`;\n        }\n        if (typeof arg === \"object\" && arg !== null) {\n          return `\\n${JSON.stringify(arg, null, 2)}`;\n        }\n        return ` ${String(arg)}`;\n      })\n      .join(\"\");\n\n    return `, args:${formatted}`;\n  };\n\n  const shouldLog = (level: LogLevel): boolean => {\n    return logLevels[level] >= currentLevelValue;\n  };\n\n  return {\n    debug: (message: string, ...args: unknown[]) => {\n      if (shouldLog(\"debug\")) {\n        console.debug(`\\x1b[32m${prefix}[DEBUG] ${maskTokens(message)}${maskTokens(formatArgs(args))}\\x1b[0m`);\n      }\n    },\n    info: (message: string, ...args: unknown[]) => {\n      if (shouldLog(\"info\")) {\n        console.info(`\\x1b[34m${prefix}[INFO] ${maskTokens(message)}${maskTokens(formatArgs(args))}\\x1b[0m`);\n      }\n    },\n    warn: (message: string, ...args: unknown[]) => {\n      if (shouldLog(\"warn\")) {\n        console.warn(`\\x1b[33m${prefix}[WARN] ${maskTokens(message)}${maskTokens(formatArgs(args))}\\x1b[0m`);\n      }\n    },\n    error: (message: string, ...args: unknown[]) => {\n      if (shouldLog(\"error\")) {\n        console.error(`\\x1b[31m${prefix}[ERROR] ${maskTokens(message)}${maskTokens(formatArgs(args))}\\x1b[0m`);\n      }\n    },\n  };\n}\n\n/**\n * Default logger instance with standard configuration\n */\nexport const logger = createLogger();\n","import { logger } from \"./logging/logger.js\";\n\n/**\n * Retry a function when it fails.\n * @param fn - The function to retry.\n * @param maxRetries - The maximum number of retries.\n * @param initialSleepTime - The initial time to sleep between exponential backoff retries.\n * @param stopOnError - The function to stop on error.\n * @returns The result of the function or undefined if it fails.\n * @example\n * import { retryWhenFailed } from \"@settlemint/sdk-utils\";\n * import { readFile } from \"node:fs/promises\";\n *\n * const result = await retryWhenFailed(() => readFile(\"/path/to/file.txt\"), 3, 1_000);\n */\nexport async function retryWhenFailed<T>(\n  fn: () => Promise<T>,\n  maxRetries = 5,\n  initialSleepTime = 1_000,\n  stopOnError?: (error: Error) => boolean,\n): Promise<T> {\n  let retries = 0;\n  const maxAttempts = maxRetries + 1;\n\n  while (retries < maxAttempts) {\n    try {\n      return await fn();\n    } catch (e) {\n      const error = e as Error;\n      if (typeof stopOnError === \"function\") {\n        if (stopOnError(error)) {\n          throw error;\n        }\n      }\n      if (retries >= maxRetries) {\n        throw e;\n      }\n      // Exponential backoff with jitter to prevent thundering herd\n      // Jitter: Random value between 0-10% of initialSleepTime\n      const baseDelay = 2 ** retries * initialSleepTime;\n      const jitterAmount = initialSleepTime * (Math.random() / 10);\n      const delay = baseDelay + jitterAmount;\n      retries += 1;\n      logger.warn(\n        `An error occurred ${error.message}, retrying in ${delay.toFixed(0)}ms (retry ${retries} of ${maxRetries})...`,\n      );\n      await new Promise((resolve) => setTimeout(resolve, delay));\n    }\n  }\n\n  throw new Error(\"Retry failed\");\n}\n","import { retryWhenFailed } from \"../retry.js\";\n\n/**\n * Retry an HTTP request with exponential backoff and jitter.\n * Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors.\n *\n * @param input - The URL or Request object to fetch\n * @param init - The fetch init options\n * @param maxRetries - Maximum number of retry attempts\n * @param initialSleepTime - Initial sleep time between retries in ms\n * @returns The fetch Response\n * @throws Error if all retries fail\n * @example\n * import { fetchWithRetry } from \"@settlemint/sdk-utils/http\";\n *\n * const response = await fetchWithRetry(\"https://api.example.com/data\");\n */\nexport async function fetchWithRetry(\n  input: RequestInfo | URL,\n  init?: RequestInit,\n  maxRetries = 5,\n  initialSleepTime = 3_000,\n): Promise<Response> {\n  return retryWhenFailed(\n    async () => {\n      const response = await fetch(input, init);\n      if (response.ok) {\n        return response;\n      }\n      // Only retry on 5xx server errors, 429 rate limit, timeout, and network errors\n      if (response.status < 500 && response.status !== 429 && response.status !== 408 && response.status !== 0) {\n        return response;\n      }\n      throw new Error(`HTTP error! status: ${response.status} ${response.statusText}`);\n    },\n    maxRetries,\n    initialSleepTime,\n  );\n}\n","import { retryWhenFailed } from \"../retry.js\";\nimport { fetchWithRetry } from \"./fetch-with-retry.js\";\n\n/**\n * Executes a GraphQL request with automatic retries using exponential backoff and jitter.\n * Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors.\n * Will also retry if the GraphQL response contains errors.\n *\n * @param input - The URL or Request object for the GraphQL endpoint\n * @param init - Optional fetch configuration options\n * @param maxRetries - Maximum retry attempts before failing (default: 5)\n * @param initialSleepTime - Initial delay between retries in milliseconds (default: 3000)\n * @returns The parsed GraphQL response data\n * @throws Error if all retries fail or if GraphQL response contains errors\n * @example\n * import { graphqlFetchWithRetry } from \"@settlemint/sdk-utils/http\";\n *\n * const data = await graphqlFetchWithRetry<{ user: { id: string } }>(\n *   \"https://api.example.com/graphql\",\n *   {\n *     method: \"POST\",\n *     headers: { \"Content-Type\": \"application/json\" },\n *     body: JSON.stringify({\n *       query: `query GetUser($id: ID!) {\n *         user(id: $id) {\n *           id\n *         }\n *       }`,\n *       variables: { id: \"123\" }\n *     })\n *   }\n * );\n */\nexport async function graphqlFetchWithRetry<Data>(\n  input: RequestInfo | URL,\n  init?: RequestInit,\n  maxRetries = 5,\n  initialSleepTime = 3_000,\n): Promise<Data> {\n  return retryWhenFailed<Data>(\n    async () => {\n      const response = await fetchWithRetry(input, init);\n      const json: { errors?: { message: string }[]; data: Data } = await response.json();\n      if (json.errors) {\n        throw new Error(`GraphQL errors in response: ${json.errors.map((error) => error.message).join(\", \")}`);\n      }\n      return json.data;\n    },\n    maxRetries,\n    initialSleepTime,\n  );\n}\n","type MaybeLazy<T> = T | (() => T);\n\nexport function appendHeaders(\n  headers: MaybeLazy<HeadersInit> | undefined,\n  additionalHeaders: Record<string, string | undefined>,\n) {\n  const defaultHeaders = typeof headers === \"function\" ? headers() : headers;\n  const filteredAdditionalHeaders = Object.entries(additionalHeaders).filter(([_, value]) => value !== undefined) as [\n    string,\n    string,\n  ][];\n  if (Array.isArray(defaultHeaders)) {\n    return [...defaultHeaders, ...filteredAdditionalHeaders];\n  }\n  if (defaultHeaders instanceof Headers) {\n    return new Headers([...defaultHeaders, ...filteredAdditionalHeaders]);\n  }\n  return {\n    ...defaultHeaders,\n    ...Object.fromEntries(filteredAdditionalHeaders),\n  };\n}\n"],"mappings":"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"}

package/dist/http.d.cts

@@ -1,3 +1,4 @@
+//#region src/http/fetch-with-retry.d.ts
 /**
  * Retry an HTTP request with exponential backoff and jitter.
  * Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors.
@@ -15,6 +16,9 @@
  */
 declare function fetchWithRetry(input: RequestInfo | URL, init?: RequestInit, maxRetries?: number, initialSleepTime?: number): Promise<Response>;
 
+//#endregion
+//#region src/http/graphql-fetch-with-retry.d.ts
+
 /**
  * Executes a GraphQL request with automatic retries using exponential backoff and jitter.
  * Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors.
@@ -47,4 +51,13 @@ declare function fetchWithRetry(input: RequestInfo | URL, init?: RequestInit, ma
  */
 declare function graphqlFetchWithRetry<Data>(input: RequestInfo | URL, init?: RequestInit, maxRetries?: number, initialSleepTime?: number): Promise<Data>;
 
-export { fetchWithRetry, graphqlFetchWithRetry };
+//#endregion
+//#region src/http/headers.d.ts
+type MaybeLazy<T> = T | (() => T);
+declare function appendHeaders(headers: MaybeLazy<HeadersInit> | undefined, additionalHeaders: Record<string, string | undefined>): [string, string][] | Headers | {
+  [x: string]: string;
+};
+
+//#endregion
+export { appendHeaders, fetchWithRetry, graphqlFetchWithRetry };
+//# sourceMappingURL=http.d.cts.map

package/dist/http.d.ts

@@ -1,3 +1,4 @@
+//#region src/http/fetch-with-retry.d.ts
 /**
  * Retry an HTTP request with exponential backoff and jitter.
  * Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors.
@@ -15,6 +16,9 @@
  */
 declare function fetchWithRetry(input: RequestInfo | URL, init?: RequestInit, maxRetries?: number, initialSleepTime?: number): Promise<Response>;
 
+//#endregion
+//#region src/http/graphql-fetch-with-retry.d.ts
+
 /**
  * Executes a GraphQL request with automatic retries using exponential backoff and jitter.
  * Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors.
@@ -47,4 +51,13 @@ declare function fetchWithRetry(input: RequestInfo | URL, init?: RequestInit, ma
  */
 declare function graphqlFetchWithRetry<Data>(input: RequestInfo | URL, init?: RequestInit, maxRetries?: number, initialSleepTime?: number): Promise<Data>;
 
-export { fetchWithRetry, graphqlFetchWithRetry };
+//#endregion
+//#region src/http/headers.d.ts
+type MaybeLazy<T> = T | (() => T);
+declare function appendHeaders(headers: MaybeLazy<HeadersInit> | undefined, additionalHeaders: Record<string, string | undefined>): [string, string][] | Headers | {
+  [x: string]: string;
+};
+
+//#endregion
+export { appendHeaders, fetchWithRetry, graphqlFetchWithRetry };
+//# sourceMappingURL=http.d.ts.map

package/dist/http.js

@@ -0,0 +1,226 @@
+//#region src/logging/mask-tokens.ts
+/**
+* Masks sensitive SettleMint tokens in output text by replacing them with asterisks.
+* Handles personal access tokens (PAT), application access tokens (AAT), and service account tokens (SAT).
+*
+* @param output - The text string that may contain sensitive tokens
+* @returns The text with any sensitive tokens masked with asterisks
+* @example
+* import { maskTokens } from "@settlemint/sdk-utils/terminal";
+*
+* // Masks a token in text
+* const masked = maskTokens("Token: sm_pat_****"); // "Token: ***"
+*/
+const maskTokens = (output) => {
+	return output.replace(/sm_(pat|aat|sat)_[0-9a-zA-Z]+/g, "***");
+};
+
+//#endregion
+//#region src/logging/logger.ts
+/**
+* Creates a simple logger with configurable log level
+*
+* @param options - Configuration options for the logger
+* @param options.level - The minimum log level to output (default: warn)
+* @param options.prefix - The prefix to add to the log message (default: "")
+* @returns A logger instance with debug, info, warn, and error methods
+*
+* @example
+* import { createLogger } from "@/utils/logging/logger";
+*
+* const logger = createLogger({ level: 'info' });
+*
+* logger.info('User logged in', { userId: '123' });
+* logger.error('Operation failed', new Error('Connection timeout'));
+*/
+function createLogger(options = {}) {
+	const { level = "warn", prefix = "" } = options;
+	const logLevels = {
+		debug: 0,
+		info: 1,
+		warn: 2,
+		error: 3,
+		none: 4
+	};
+	const currentLevelValue = logLevels[level];
+	const formatArgs = (args) => {
+		if (args.length === 0 || args.every((arg) => arg === undefined || arg === null)) {
+			return "";
+		}
+		const formatted = args.map((arg) => {
+			if (arg instanceof Error) {
+				return `\n${arg.stack || arg.message}`;
+			}
+			if (typeof arg === "object" && arg !== null) {
+				return `\n${JSON.stringify(arg, null, 2)}`;
+			}
+			return ` ${String(arg)}`;
+		}).join("");
+		return `, args:${formatted}`;
+	};
+	const shouldLog = (level$1) => {
+		return logLevels[level$1] >= currentLevelValue;
+	};
+	return {
+		debug: (message, ...args) => {
+			if (shouldLog("debug")) {
+				console.debug(`\x1b[32m${prefix}[DEBUG] ${maskTokens(message)}${maskTokens(formatArgs(args))}\x1b[0m`);
+			}
+		},
+		info: (message, ...args) => {
+			if (shouldLog("info")) {
+				console.info(`\x1b[34m${prefix}[INFO] ${maskTokens(message)}${maskTokens(formatArgs(args))}\x1b[0m`);
+			}
+		},
+		warn: (message, ...args) => {
+			if (shouldLog("warn")) {
+				console.warn(`\x1b[33m${prefix}[WARN] ${maskTokens(message)}${maskTokens(formatArgs(args))}\x1b[0m`);
+			}
+		},
+		error: (message, ...args) => {
+			if (shouldLog("error")) {
+				console.error(`\x1b[31m${prefix}[ERROR] ${maskTokens(message)}${maskTokens(formatArgs(args))}\x1b[0m`);
+			}
+		}
+	};
+}
+/**
+* Default logger instance with standard configuration
+*/
+const logger = createLogger();
+
+//#endregion
+//#region src/retry.ts
+/**
+* Retry a function when it fails.
+* @param fn - The function to retry.
+* @param maxRetries - The maximum number of retries.
+* @param initialSleepTime - The initial time to sleep between exponential backoff retries.
+* @param stopOnError - The function to stop on error.
+* @returns The result of the function or undefined if it fails.
+* @example
+* import { retryWhenFailed } from "@settlemint/sdk-utils";
+* import { readFile } from "node:fs/promises";
+*
+* const result = await retryWhenFailed(() => readFile("/path/to/file.txt"), 3, 1_000);
+*/
+async function retryWhenFailed(fn, maxRetries = 5, initialSleepTime = 1e3, stopOnError) {
+	let retries = 0;
+	const maxAttempts = maxRetries + 1;
+	while (retries < maxAttempts) {
+		try {
+			return await fn();
+		} catch (e) {
+			const error = e;
+			if (typeof stopOnError === "function") {
+				if (stopOnError(error)) {
+					throw error;
+				}
+			}
+			if (retries >= maxRetries) {
+				throw e;
+			}
+			const baseDelay = 2 ** retries * initialSleepTime;
+			const jitterAmount = initialSleepTime * (Math.random() / 10);
+			const delay = baseDelay + jitterAmount;
+			retries += 1;
+			logger.warn(`An error occurred ${error.message}, retrying in ${delay.toFixed(0)}ms (retry ${retries} of ${maxRetries})...`);
+			await new Promise((resolve) => setTimeout(resolve, delay));
+		}
+	}
+	throw new Error("Retry failed");
+}
+
+//#endregion
+//#region src/http/fetch-with-retry.ts
+/**
+* Retry an HTTP request with exponential backoff and jitter.
+* Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors.
+*
+* @param input - The URL or Request object to fetch
+* @param init - The fetch init options
+* @param maxRetries - Maximum number of retry attempts
+* @param initialSleepTime - Initial sleep time between retries in ms
+* @returns The fetch Response
+* @throws Error if all retries fail
+* @example
+* import { fetchWithRetry } from "@settlemint/sdk-utils/http";
+*
+* const response = await fetchWithRetry("https://api.example.com/data");
+*/
+async function fetchWithRetry(input, init, maxRetries = 5, initialSleepTime = 3e3) {
+	return retryWhenFailed(async () => {
+		const response = await fetch(input, init);
+		if (response.ok) {
+			return response;
+		}
+		if (response.status < 500 && response.status !== 429 && response.status !== 408 && response.status !== 0) {
+			return response;
+		}
+		throw new Error(`HTTP error! status: ${response.status} ${response.statusText}`);
+	}, maxRetries, initialSleepTime);
+}
+
+//#endregion
+//#region src/http/graphql-fetch-with-retry.ts
+/**
+* Executes a GraphQL request with automatic retries using exponential backoff and jitter.
+* Only retries on server errors (5xx), rate limits (429), timeouts (408), and network errors.
+* Will also retry if the GraphQL response contains errors.
+*
+* @param input - The URL or Request object for the GraphQL endpoint
+* @param init - Optional fetch configuration options
+* @param maxRetries - Maximum retry attempts before failing (default: 5)
+* @param initialSleepTime - Initial delay between retries in milliseconds (default: 3000)
+* @returns The parsed GraphQL response data
+* @throws Error if all retries fail or if GraphQL response contains errors
+* @example
+* import { graphqlFetchWithRetry } from "@settlemint/sdk-utils/http";
+*
+* const data = await graphqlFetchWithRetry<{ user: { id: string } }>(
+*   "https://api.example.com/graphql",
+*   {
+*     method: "POST",
+*     headers: { "Content-Type": "application/json" },
+*     body: JSON.stringify({
+*       query: `query GetUser($id: ID!) {
+*         user(id: $id) {
+*           id
+*         }
+*       }`,
+*       variables: { id: "123" }
+*     })
+*   }
+* );
+*/
+async function graphqlFetchWithRetry(input, init, maxRetries = 5, initialSleepTime = 3e3) {
+	return retryWhenFailed(async () => {
+		const response = await fetchWithRetry(input, init);
+		const json = await response.json();
+		if (json.errors) {
+			throw new Error(`GraphQL errors in response: ${json.errors.map((error) => error.message).join(", ")}`);
+		}
+		return json.data;
+	}, maxRetries, initialSleepTime);
+}
+
+//#endregion
+//#region src/http/headers.ts
+function appendHeaders(headers, additionalHeaders) {
+	const defaultHeaders = typeof headers === "function" ? headers() : headers;
+	const filteredAdditionalHeaders = Object.entries(additionalHeaders).filter(([_, value]) => value !== undefined);
+	if (Array.isArray(defaultHeaders)) {
+		return [...defaultHeaders, ...filteredAdditionalHeaders];
+	}
+	if (defaultHeaders instanceof Headers) {
+		return new Headers([...defaultHeaders, ...filteredAdditionalHeaders]);
+	}
+	return {
+		...defaultHeaders,
+		...Object.fromEntries(filteredAdditionalHeaders)
+	};
+}
+
+//#endregion
+export { appendHeaders, fetchWithRetry, graphqlFetchWithRetry };
+//# sourceMappingURL=http.js.map