@metriport/shared 0.33.1 → 0.33.4-alpha.0

package/dist/src/net/retry.js

@@ -0,0 +1,134 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultOptionsRequestNotAccepted = exports.tooManyRequestsStatus = void 0;
+exports.getHttpStatusFromError = getHttpStatusFromError;
+exports.getHttpStatusFromErrorOrServerError = getHttpStatusFromErrorOrServerError;
+exports.getHttpCodeFromError = getHttpCodeFromError;
+exports.executeWithNetworkRetries = executeWithNetworkRetries;
+exports.simpleExecuteWithRetries = simpleExecuteWithRetries;
+const axios_1 = __importDefault(require("axios"));
+const dayjs_1 = __importDefault(require("dayjs"));
+const duration_1 = __importDefault(require("dayjs/plugin/duration"));
+const http_status_1 = __importDefault(require("http-status"));
+const retry_1 = require("../common/retry");
+const metriport_error_1 = require("../error/metriport-error");
+const error_1 = require("./error");
+dayjs_1.default.extend(duration_1.default);
+exports.tooManyRequestsStatus = 429;
+const tooManyRequestsMultiplier = 3;
+exports.defaultOptionsRequestNotAccepted = {
+    httpCodesToRetry: [
+        // https://nodejs.org/docs/latest-v18.x/api/errors.html#common-system-errors
+        "ECONNREFUSED", // (Connection refused): No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service that is inactive on the foreign host.
+        "ENOTFOUND", //  (DNS lookup failed): Indicates a DNS failure of either EAI_NODATA or EAI_NONAME. This is not a standard POSIX error.
+        "EAI_AGAIN",
+        "ENETUNREACH",
+        "EHOSTUNREACH",
+    ],
+    httpStatusCodesToRetry: [exports.tooManyRequestsStatus],
+};
+const defaultOptions = {
+    ...retry_1.defaultOptions,
+    initialDelay: 1000,
+    httpCodesToRetry: [...exports.defaultOptionsRequestNotAccepted.httpCodesToRetry],
+    httpStatusCodesToRetry: [...exports.defaultOptionsRequestNotAccepted.httpStatusCodesToRetry],
+    retryOnTimeout: false,
+};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getHttpStatusFromError(error) {
+    if (!error)
+        return undefined;
+    if (axios_1.default.isAxiosError(error))
+        return error.response?.status;
+    if (error.cause)
+        return getHttpStatusFromError(error.cause);
+    if ((0, metriport_error_1.isMetriportError)(error))
+        return error.status;
+    return undefined;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getHttpStatusFromErrorOrServerError(error) {
+    const status = getHttpStatusFromError(error);
+    return status ?? http_status_1.default.INTERNAL_SERVER_ERROR;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getHttpCodeFromError(error) {
+    if (!error)
+        return undefined;
+    if (axios_1.default.isAxiosError(error))
+        return error.code;
+    if ("cause" in error)
+        return getHttpCodeFromError(error.cause);
+    return undefined;
+}
+/**
+ * Custom getTimeToWait function for network retries. Has special handling for 429 Too Many Requests. Else regular backoff.
+ * @param initialDelay The initial delay in milliseconds.
+ * @param backoffMultiplier The backoff multiplier.
+ * @param attempt The current attempt number.
+ * @param maxDelay The maximum delay in milliseconds.
+ * @param error The error that occurred.
+ * @returns The time to wait before the next retry.
+ */
+function networkGetTimeToWait({ initialDelay, backoffMultiplier, attempt, maxDelay, error, }) {
+    const status = getHttpStatusFromError(error);
+    const effectiveInitialDelay = status === exports.tooManyRequestsStatus ? initialDelay * tooManyRequestsMultiplier : initialDelay;
+    return (0, retry_1.defaultGetTimeToWait)({
+        initialDelay: effectiveInitialDelay,
+        backoffMultiplier,
+        attempt,
+        maxDelay,
+    });
+}
+/**
+ * Executes a function with retries and backoff with jitter. If the function throws a network
+ * error, it will retry up to maxAttempts-1, waiting between each retry.
+ * If the function throws an error on the last attempt, it will throw the error.
+ * If the function succeeds, it will return the result.
+ * This is a specialization of `executeWithRetries` for network errors.
+ * By default it retries on ECONNREFUSED and ECONNRESET (customize the errors to retry
+ * setting the option `httpCodesToRetry`).
+ * By default it also retries on HTTP status code 429 (Too Many Requests).
+ *
+ * @param fn the function to be executed
+ * @param options the options to be used; see `ExecuteWithHttpRetriesOptions` for components and
+ *        `defaultOptions` for defaults.
+ * @returns the result of calling the `fn` function
+ * @see `executeWithRetries()`
+ *
+ */
+async function executeWithNetworkRetries(fn, options) {
+    const actualOptions = { ...defaultOptions, ...options };
+    const { httpCodesToRetry: httpCodesFromParams, httpStatusCodesToRetry } = actualOptions;
+    const httpCodesToRetry = actualOptions.retryOnTimeout
+        ? [...httpCodesFromParams, ...error_1.networkTimeoutErrors]
+        : httpCodesFromParams;
+    const codesAsString = httpCodesToRetry.map(String);
+    return (0, retry_1.executeWithRetries)(fn, {
+        ...actualOptions,
+        shouldRetry: (_, error) => {
+            const networkCode = getHttpCodeFromError(error);
+            const networkStatus = getHttpStatusFromError(error);
+            return ((networkCode && codesAsString.includes(networkCode)) ||
+                (networkStatus && httpStatusCodesToRetry.includes(networkStatus)) ||
+                false);
+        },
+        getTimeToWait: networkGetTimeToWait,
+    });
+}
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_INITIAL_DELAY_DURATION = dayjs_1.default.duration({ seconds: 1 });
+/**
+ * @deprecated Use executeWithNetworkRetries instead.
+ */
+async function simpleExecuteWithRetries(functionToExecute, log, maxAttempts = DEFAULT_MAX_ATTEMPTS, initialDelay = DEFAULT_INITIAL_DELAY_DURATION) {
+    return await executeWithNetworkRetries(functionToExecute, {
+        maxAttempts,
+        initialDelay: initialDelay.asMilliseconds(),
+        log,
+    });
+}
+//# sourceMappingURL=retry.js.map

package/dist/src/net/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/net/retry.ts"],"names":[],"mappings":"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"}

package/dist/src/net/url.d.ts

@@ -0,0 +1,2 @@
+export declare function isValidUrl(url: string | undefined): boolean;
+//# sourceMappingURL=url.d.ts.map

package/dist/src/net/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../../src/net/url.ts"],"names":[],"mappings":"AAAA,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAQ3D"}

package/dist/src/net/url.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidUrl = isValidUrl;
+function isValidUrl(url) {
+    if (!url)
+        return false;
+    try {
+        new URL(url);
+        return true;
+    }
+    catch (e) {
+        return false;
+    }
+}
+//# sourceMappingURL=url.js.map

package/dist/src/net/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../../src/net/url.ts"],"names":[],"mappings":";;AAAA,gCAQC;AARD,SAAgB,UAAU,CAAC,GAAuB;IAChD,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvB,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/src/util/__tests__/base64.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=base64.test.d.ts.map

package/dist/src/util/__tests__/base64.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.test.d.ts","sourceRoot":"","sources":["../../../../src/util/__tests__/base64.test.ts"],"names":[],"mappings":""}

package/dist/src/util/__tests__/base64.test.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const base64_1 = require("../base64");
+beforeEach(() => {
+    jest.restoreAllMocks();
+});
+describe("base64", () => {
+    describe("stringToBase64", () => {
+        it("returns empty string when gets empty string", async () => {
+            const original = "";
+            const expected = "";
+            const res = (0, base64_1.stringToBase64)(original);
+            expect(res).toEqual(expected);
+        });
+        it("encodes simple, ascii only string", async () => {
+            const original = "hello world";
+            const expected = "aGVsbG8gd29ybGQ=";
+            const res = (0, base64_1.stringToBase64)(original);
+            expect(res).toEqual(expected);
+        });
+        it("encodes non-ascii string", async () => {
+            const original = "a Ā 𐀀 文 🦄";
+            const expected = "YSDEgCDwkICAIOaWhyDwn6aE";
+            const res = (0, base64_1.stringToBase64)(original);
+            expect(res).toEqual(expected);
+        });
+    });
+    describe("base64ToString", () => {
+        it("returns empty string when gets empty string", async () => {
+            const original = "";
+            const expected = "";
+            const res = (0, base64_1.base64ToString)(original);
+            expect(res).toEqual(expected);
+        });
+        it("encodes simple, ascii only string", async () => {
+            const original = "aGVsbG8gd29ybGQ=";
+            const expected = "hello world";
+            const res = (0, base64_1.base64ToString)(original);
+            expect(res).toEqual(expected);
+        });
+        it("encodes non-ascii string", async () => {
+            const original = "YSDEgCDwkICAIOaWhyDwn6aE";
+            const expected = "a Ā 𐀀 文 🦄";
+            const res = (0, base64_1.base64ToString)(original);
+            expect(res).toEqual(expected);
+        });
+    });
+    describe("encode and decode together", () => {
+        it("returns empty string when gets empty string", async () => {
+            const original = "";
+            const res = (0, base64_1.base64ToString)((0, base64_1.stringToBase64)(original));
+            expect(res).toEqual(original);
+        });
+        it("encodes simple, ascii only string", async () => {
+            const original = "hello world";
+            const res = (0, base64_1.base64ToString)((0, base64_1.stringToBase64)(original));
+            expect(res).toEqual(original);
+        });
+        it("encodes non-ascii string", async () => {
+            const original = "a Ā 𐀀 文 🦄";
+            const res = (0, base64_1.base64ToString)((0, base64_1.stringToBase64)(original));
+            expect(res).toEqual(original);
+        });
+    });
+});
+//# sourceMappingURL=base64.test.js.map

package/dist/src/util/__tests__/base64.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.test.js","sourceRoot":"","sources":["../../../../src/util/__tests__/base64.test.ts"],"names":[],"mappings":"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"}

package/dist/src/util/base64.d.ts

@@ -0,0 +1,25 @@
+export declare function base64ToBuffer(value: string): Buffer;
+export declare function base64ToString(value: string): string;
+export declare function stringToBase64(value: string): string;
+/**
+ * Validate that a string contains only base64 characters
+ * @param str - The string to validate
+ * @returns True if string is valid base64, false otherwise
+ */
+export declare function isValidBase64(str: string): boolean;
+/**
+ * Turns a b64 string into hex by going through each character.
+ * Warning removes padding from the b64 before turning it into hex.
+ * @param b64 - The b64 string to convert to hex.
+ * @returns converted hex string
+ */
+export declare function b64CharsToHex(b64: string): string;
+/**
+ * Turns a hex string into b64 by going through each character.
+ * Warning adds padding to the resulting b64 string.
+ * @param hex - The hex string to convert to b64
+ * @returns converted b64 string
+ */
+export declare function hexToB64Chars(hex: string): string;
+export declare const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+//# sourceMappingURL=base64.d.ts.map

package/dist/src/util/base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../../../src/util/base64.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGlD;AAGD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKjD;AAED,eAAO,MAAM,YAAY,qEAAqE,CAAC"}

package/dist/src/util/base64.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASE64_CHARS = void 0;
+exports.base64ToBuffer = base64ToBuffer;
+exports.base64ToString = base64ToString;
+exports.stringToBase64 = stringToBase64;
+exports.isValidBase64 = isValidBase64;
+exports.b64CharsToHex = b64CharsToHex;
+exports.hexToB64Chars = hexToB64Chars;
+function base64ToBuffer(value) {
+    return Buffer.from(value, "base64");
+}
+function base64ToString(value) {
+    return base64ToBuffer(value).toString();
+}
+function stringToBase64(value) {
+    return Buffer.from(value).toString("base64");
+}
+/**
+ * Validate that a string contains only base64 characters
+ * @param str - The string to validate
+ * @returns True if string is valid base64, false otherwise
+ */
+function isValidBase64(str) {
+    const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
+    return base64Regex.test(str);
+}
+const findPaddingRegex = /=+$/;
+/**
+ * Turns a b64 string into hex by going through each character.
+ * Warning removes padding from the b64 before turning it into hex.
+ * @param b64 - The b64 string to convert to hex.
+ * @returns converted hex string
+ */
+function b64CharsToHex(b64) {
+    const noPaddingB64 = b64.replace(findPaddingRegex, "");
+    return Buffer.from(noPaddingB64).toString("hex");
+}
+/**
+ * Turns a hex string into b64 by going through each character.
+ * Warning adds padding to the resulting b64 string.
+ * @param hex - The hex string to convert to b64
+ * @returns converted b64 string
+ */
+function hexToB64Chars(hex) {
+    const b64 = Buffer.from(hex, "hex").toString();
+    // Add back padding since we removed it when converting to hex
+    const padLen = (4 - (b64.length % 4)) % 4;
+    return b64 + "=".repeat(padLen);
+}
+exports.BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+//# sourceMappingURL=base64.js.map

package/dist/src/util/base64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.js","sourceRoot":"","sources":["../../../src/util/base64.ts"],"names":[],"mappings":";;;AAAA,wCAEC;AAED,wCAEC;AAED,wCAEC;AAOD,sCAGC;AASD,sCAGC;AAQD,sCAKC;AA7CD,SAAgB,cAAc,CAAC,KAAa;IAC1C,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AACtC,CAAC;AAED,SAAgB,cAAc,CAAC,KAAa;IAC1C,OAAO,cAAc,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC;AAC1C,CAAC;AAED,SAAgB,cAAc,CAAC,KAAa;IAC1C,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,SAAgB,aAAa,CAAC,GAAW;IACvC,MAAM,WAAW,GAAG,wBAAwB,CAAC;IAC7C,OAAO,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAC/B;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,GAAW;IACvC,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;IACvD,OAAO,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,GAAW;IACvC,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC/C,8DAA8D;IAC9D,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1C,OAAO,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC;AAEY,QAAA,YAAY,GAAG,kEAAkE,CAAC"}

package/dist/src/util/duration.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Wraps a function and logs the time it took to execute it.
+ *
+ * @deprecated Unify with logDuration(), choose one to keep around.
+ *
+ * @param fn - The function to execute.
+ * @param name - The name of the function to log.
+ * @param log - The logger to use.
+ * @returns The result of the function.
+ */
+export declare function timed<T>(fn: () => Promise<T>, name: string, log: typeof console.log): Promise<T>;
+export declare function elapsedTimeAsStr(startedAt: number, finishedAt?: number): string;
+//# sourceMappingURL=duration.d.ts.map

package/dist/src/util/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../../../src/util/duration.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,OAAO,CAAC,GAAG,cAMzF;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,SAAa,UAK1E"}

package/dist/src/util/duration.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timed = timed;
+exports.elapsedTimeAsStr = elapsedTimeAsStr;
+const numbers_1 = require("../common/numbers");
+const dayjs_1 = __importDefault(require("dayjs"));
+const duration_1 = __importDefault(require("dayjs/plugin/duration"));
+dayjs_1.default.extend(duration_1.default);
+/**
+ * Wraps a function and logs the time it took to execute it.
+ *
+ * @deprecated Unify with logDuration(), choose one to keep around.
+ *
+ * @param fn - The function to execute.
+ * @param name - The name of the function to log.
+ * @param log - The logger to use.
+ * @returns The result of the function.
+ */
+async function timed(fn, name, log) {
+    const startedAt = Date.now();
+    const res = await fn();
+    const elapsedTime = Date.now() - startedAt;
+    log(`Done ${name} in ${elapsedTime} ms`);
+    return res;
+}
+function elapsedTimeAsStr(startedAt, finishedAt = Date.now()) {
+    const elapsedTime = dayjs_1.default.duration(finishedAt - startedAt);
+    const timeInMin = (0, numbers_1.formatNumber)(elapsedTime.asMinutes());
+    const timeInMillis = (0, numbers_1.formatNumber)(elapsedTime.asMilliseconds());
+    return `${timeInMillis} millis / ${timeInMin} min`;
+}
+//# sourceMappingURL=duration.js.map

package/dist/src/util/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../../../src/util/duration.ts"],"names":[],"mappings":";;;;;AAgBA,sBAMC;AAED,4CAKC;AA7BD,+CAAiD;AACjD,kDAA0B;AAC1B,qEAA6C;AAE7C,eAAK,CAAC,MAAM,CAAC,kBAAQ,CAAC,CAAC;AAEvB;;;;;;;;;GASG;AACI,KAAK,UAAU,KAAK,CAAI,EAAoB,EAAE,IAAY,EAAE,GAAuB;IACxF,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAG,MAAM,EAAE,EAAE,CAAC;IACvB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IAC3C,GAAG,CAAC,QAAQ,IAAI,OAAO,WAAW,KAAK,CAAC,CAAC;IACzC,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAgB,gBAAgB,CAAC,SAAiB,EAAE,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE;IACzE,MAAM,WAAW,GAAG,eAAK,CAAC,QAAQ,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAC3D,MAAM,SAAS,GAAG,IAAA,sBAAY,EAAC,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC;IACxD,MAAM,YAAY,GAAG,IAAA,sBAAY,EAAC,WAAW,CAAC,cAAc,EAAE,CAAC,CAAC;IAChE,OAAO,GAAG,YAAY,aAAa,SAAS,MAAM,CAAC;AACrD,CAAC"}

package/dist/src/util/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./base64";
+export * from "./duration";
+export * from "./sqs-delay-from-uuid";
+export * from "./uuid-v7";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/util/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/util/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC"}

package/dist/src/util/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./base64"), exports);
+__exportStar(require("./duration"), exports);
+__exportStar(require("./sqs-delay-from-uuid"), exports);
+__exportStar(require("./uuid-v7"), exports);
+//# sourceMappingURL=index.js.map

package/dist/src/util/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/util/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,6CAA2B;AAC3B,wDAAsC;AACtC,4CAA0B"}

package/dist/src/util/sqs-delay-from-uuid.d.ts

@@ -0,0 +1,11 @@
+/** SQS max delivery delay is 15 minutes (900 seconds). Delay must not exceed this. */
+export declare const SQS_MAX_DELAY_SECONDS = 900;
+/**
+ * Maps a string (e.g. cxId or UUID v4) to a delivery delay in seconds for SQS,
+ * evenly distributed across 0 to 15 minutes (max). Same input always gets the same delay (deterministic).
+ *
+ * @param id - Any string identifier (e.g. cxId, UUID v4)
+ * @returns Delay in seconds in [0, 900] (≤ 15 min, SQS max)
+ */
+export declare function uuidToDelaySeconds(id: string, maxDelaySeconds?: number): number;
+//# sourceMappingURL=sqs-delay-from-uuid.d.ts.map

package/dist/src/util/sqs-delay-from-uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqs-delay-from-uuid.d.ts","sourceRoot":"","sources":["../../../src/util/sqs-delay-from-uuid.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,EACV,eAAe,GAAE,MAA8B,GAC9C,MAAM,CAKR"}

package/dist/src/util/sqs-delay-from-uuid.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQS_MAX_DELAY_SECONDS = void 0;
+exports.uuidToDelaySeconds = uuidToDelaySeconds;
+const node_crypto_1 = require("node:crypto");
+/** SQS max delivery delay is 15 minutes (900 seconds). Delay must not exceed this. */
+exports.SQS_MAX_DELAY_SECONDS = 900;
+/**
+ * Maps a string (e.g. cxId or UUID v4) to a delivery delay in seconds for SQS,
+ * evenly distributed across 0 to 15 minutes (max). Same input always gets the same delay (deterministic).
+ *
+ * @param id - Any string identifier (e.g. cxId, UUID v4)
+ * @returns Delay in seconds in [0, 900] (≤ 15 min, SQS max)
+ */
+function uuidToDelaySeconds(id, maxDelaySeconds = exports.SQS_MAX_DELAY_SECONDS) {
+    const BUCKET_COUNT = maxDelaySeconds + 1; // maxDelaySeconds + 1 → 0..maxDelaySeconds
+    const hash = (0, node_crypto_1.createHash)("sha256").update(id, "utf8").digest();
+    const value = hash.readUInt32BE(0) * 0x100000000 + hash.readUInt32BE(4);
+    return value % BUCKET_COUNT; // always in [0, maxDelaySeconds]
+}
+//# sourceMappingURL=sqs-delay-from-uuid.js.map

package/dist/src/util/sqs-delay-from-uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqs-delay-from-uuid.js","sourceRoot":"","sources":["../../../src/util/sqs-delay-from-uuid.ts"],"names":[],"mappings":";;;AAYA,gDAQC;AApBD,6CAAyC;AAEzC,sFAAsF;AACzE,QAAA,qBAAqB,GAAG,GAAG,CAAC;AAEzC;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAChC,EAAU,EACV,kBAA0B,6BAAqB;IAE/C,MAAM,YAAY,GAAG,eAAe,GAAG,CAAC,CAAC,CAAC,2CAA2C;IACrF,MAAM,IAAI,GAAG,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;IAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACxE,OAAO,KAAK,GAAG,YAAY,CAAC,CAAC,iCAAiC;AAChE,CAAC"}

package/dist/src/util/stack-trace.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Returns the top N callers in the stack trace.
+ *
+ * @param numberOfCallers - The number of callers to include in the array. Defaults to 2.
+ * @returns An array of strings, each representing a caller in the stack trace.
+ */
+export declare function getCallerDetails(numberOfCallers?: number): string[];
+/**
+ * Returns the top N callers in the stack trace as a string, with one caller per line (as a regular
+ * stack trace).
+ *
+ * @param numberOfCallers - The number of callers to include in the string.
+ * @returns A string with one caller per line (as a regular stack trace).
+ * @see getCallerDetails for details/defaults
+ */
+export declare function getCallerDetailsAsString(numberOfCallers?: number): string;
+//# sourceMappingURL=stack-trace.d.ts.map

package/dist/src/util/stack-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-trace.d.ts","sourceRoot":"","sources":["../../../src/util/stack-trace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,eAAe,SAAI,GAAG,MAAM,EAAE,CAQ9D;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAGzE"}

package/dist/src/util/stack-trace.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCallerDetails = getCallerDetails;
+exports.getCallerDetailsAsString = getCallerDetailsAsString;
+/**
+ * Returns the top N callers in the stack trace.
+ *
+ * @param numberOfCallers - The number of callers to include in the array. Defaults to 2.
+ * @returns An array of strings, each representing a caller in the stack trace.
+ */
+function getCallerDetails(numberOfCallers = 2) {
+    const stack = new Error().stack;
+    // Split into lines and remove the first 3 lines:
+    // 0: Error
+    // 1: at getCallerDetails (this function)
+    // 2: at the actual caller
+    const stackLines = stack?.split("\n").slice(3, numberOfCallers + 3) ?? [];
+    return stackLines;
+}
+/**
+ * Returns the top N callers in the stack trace as a string, with one caller per line (as a regular
+ * stack trace).
+ *
+ * @param numberOfCallers - The number of callers to include in the string.
+ * @returns A string with one caller per line (as a regular stack trace).
+ * @see getCallerDetails for details/defaults
+ */
+function getCallerDetailsAsString(numberOfCallers) {
+    const stackLines = getCallerDetails(numberOfCallers);
+    return stackLines.join("\n");
+}
+//# sourceMappingURL=stack-trace.js.map

package/dist/src/util/stack-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-trace.js","sourceRoot":"","sources":["../../../src/util/stack-trace.ts"],"names":[],"mappings":";;AAMA,4CAQC;AAUD,4DAGC;AA3BD;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,eAAe,GAAG,CAAC;IAClD,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,KAAK,CAAC;IAChC,iDAAiD;IACjD,WAAW;IACX,yCAAyC;IACzC,0BAA0B;IAC1B,MAAM,UAAU,GAAG,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1E,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,wBAAwB,CAAC,eAAwB;IAC/D,MAAM,UAAU,GAAG,gBAAgB,CAAC,eAAe,CAAC,CAAC;IACrD,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC"}