@clipboard-health/playwright-toolkit 1.0.0

package/src/lib/mailpit.js

@@ -0,0 +1,252 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MailpitRequestError = void 0;
+exports.createMailpitClient = createMailpitClient;
+exports.fetchMailpitValue = fetchMailpitValue;
+exports.fetchMagicLinkFromMailpit = fetchMagicLinkFromMailpit;
+exports.fetchEmailOtpCodeFromMailpit = fetchEmailOtpCodeFromMailpit;
+exports.extractMagicLinkFromMailpitMessage = extractMagicLinkFromMailpitMessage;
+exports.extractEmailOtpCodeFromMailpitMessage = extractEmailOtpCodeFromMailpitMessage;
+exports.isTransientMailpitError = isTransientMailpitError;
+const util_ts_1 = require("@clipboard-health/util-ts");
+const retry_1 = require("./retry");
+const setupRetry_1 = require("./setupRetry");
+const DEFAULT_MAILPIT_BASE_URL = "https://mailpit.tools.cbh.rocks/api/v1";
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+const SENT_AFTER_TOLERANCE_MS = 30_000;
+const MAX_MESSAGES_TO_FETCH = 3;
+class MailpitRequestError extends Error {
+    cause;
+    isTransient;
+    status;
+    constructor(params) {
+        super(params.message, { cause: params.cause });
+        this.name = "MailpitRequestError";
+        this.cause = params.cause;
+        this.isTransient = params.isTransient ?? false;
+        this.status = params.status;
+    }
+}
+exports.MailpitRequestError = MailpitRequestError;
+class MailpitValueNotFoundError extends Error {
+}
+function createMailpitClient(params) {
+    if (params.password.length === 0) {
+        throw new Error("Mailpit password must not be empty");
+    }
+    const fetchImplementation = params.fetchImplementation ?? fetch;
+    const baseUrl = params.baseUrl ?? DEFAULT_MAILPIT_BASE_URL;
+    const authorization = `Basic ${Buffer.from(`${params.username ?? "cbh"}:${params.password}`).toString("base64")}`;
+    return {
+        async searchMessages({ query }) {
+            const response = await requestMailpitJson({
+                fetchImplementation,
+                requestTimeoutMs: params.requestTimeoutMs,
+                url: addSearchQuery({ baseUrl, query }),
+                authorization,
+            });
+            if (!(0, util_ts_1.isRecord)(response) || !Array.isArray(response["messages"])) {
+                throw new MailpitRequestError({
+                    message: "Mailpit search response is malformed",
+                });
+            }
+            return response["messages"].filter(isMailpitMessageSummary);
+        },
+        async getMessage({ messageId }) {
+            const response = await requestMailpitJson({
+                fetchImplementation,
+                requestTimeoutMs: params.requestTimeoutMs,
+                url: new URL(`message/${encodeURIComponent(messageId)}`, ensureTrailingSlash(baseUrl)).toString(),
+                authorization,
+            });
+            if (!isMailpitMessage(response)) {
+                throw new MailpitRequestError({
+                    message: "Mailpit message response is malformed",
+                });
+            }
+            return response;
+        },
+    };
+}
+async function fetchMailpitValue(params) {
+    const excludedValues = new Set(params.excludedValues ?? []);
+    const valuesByMessageId = new Map();
+    const result = await (0, retry_1.runWithRetry)({
+        operationName: `wait for Mailpit ${params.valueLabel}`,
+        operation: async () => {
+            const messages = await params.client.searchMessages({
+                query: `to:${params.email}`,
+            });
+            const candidates = messages
+                .filter((message) => isMessageSentAfter({ message, sentAfter: params.sentAfter }))
+                .toSorted(compareMailpitMessagesNewestFirst)
+                .slice(0, MAX_MESSAGES_TO_FETCH);
+            for (const message of candidates) {
+                if (valuesByMessageId.has(message.ID)) {
+                    const cachedValue = valuesByMessageId.get(message.ID);
+                    if (cachedValue !== undefined && !excludedValues.has(cachedValue)) {
+                        return { value: cachedValue, messageId: message.ID };
+                    }
+                    continue;
+                }
+                try {
+                    // eslint-disable-next-line no-await-in-loop -- Candidates are checked newest-first.
+                    const fullMessage = await params.client.getMessage({
+                        messageId: message.ID,
+                    });
+                    const value = params.extractValue({ message: fullMessage });
+                    valuesByMessageId.set(message.ID, value);
+                    if (value !== undefined && !excludedValues.has(value)) {
+                        return { value, messageId: message.ID };
+                    }
+                }
+                catch (error) {
+                    if (!isTransientMailpitError({ error })) {
+                        throw error;
+                    }
+                }
+            }
+            throw new MailpitValueNotFoundError(`No matching Mailpit ${params.valueLabel} is available yet`);
+        },
+        mode: {
+            kind: "poll",
+            timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            intervalsMs: [params.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS],
+            isTransient: ({ error }) => error instanceof MailpitValueNotFoundError || isTransientMailpitError({ error }),
+        },
+        sleepImplementation: params.sleepImplementation,
+        nowImplementation: params.nowImplementation,
+    });
+    return result.value;
+}
+async function fetchMagicLinkFromMailpit(params) {
+    return await fetchMailpitValue({
+        ...params,
+        excludedValues: params.excludeLinks,
+        extractValue: extractMagicLinkFromMailpitMessage,
+        valueLabel: "Cognito magic link",
+    });
+}
+async function fetchEmailOtpCodeFromMailpit(params) {
+    return await fetchMailpitValue({
+        ...params,
+        excludedValues: params.excludeCodes,
+        extractValue: extractEmailOtpCodeFromMailpitMessage,
+        valueLabel: "Cognito email OTP",
+    });
+}
+function extractMagicLinkFromMailpitMessage(params) {
+    for (const content of [params.message.Text, params.message.HTML]) {
+        const match = /https?:\/\/[^\s]+\/v2\/email-login-link\?[^\s<"')]*/i.exec(content);
+        if (match !== null) {
+            return match[0];
+        }
+    }
+    return undefined;
+}
+function extractEmailOtpCodeFromMailpitMessage(params) {
+    const textCode = extractEmailOtpCodeFromContent(params.message.Text);
+    if (textCode !== undefined) {
+        return textCode;
+    }
+    const htmlText = params.message.HTML.replaceAll(/<(style|script)[^>]*>[\s\S]*?<\/\1>/gi, "").replaceAll(/<[^>]+>/g, " ");
+    return extractEmailOtpCodeFromContent(htmlText);
+}
+function extractEmailOtpCodeFromContent(source) {
+    const eightDigits = /(?<!\d)\d{8}(?!\d)/.exec(source);
+    if (eightDigits !== null) {
+        return eightDigits[0];
+    }
+    const twoGroups = /(?<!\d)(\d{4})\s*(\d{4})(?!\d)/.exec(source);
+    return twoGroups === null ? undefined : `${twoGroups[1]}${twoGroups[2]}`;
+}
+function isTransientMailpitError(params) {
+    if (!(params.error instanceof MailpitRequestError)) {
+        return false;
+    }
+    const { status } = params.error;
+    return params.error.isTransient || status === 404 || (0, setupRetry_1.isRetryableHttpStatus)({ status });
+}
+async function requestMailpitJson(params) {
+    const abortController = new AbortController();
+    const timeout = setTimeout(() => {
+        abortController.abort();
+    }, params.requestTimeoutMs ?? 10_000);
+    try {
+        let response;
+        try {
+            response = await params.fetchImplementation(params.url, {
+                headers: { authorization: params.authorization },
+                signal: abortController.signal,
+            });
+        }
+        catch (error) {
+            throw new MailpitRequestError({
+                message: `Mailpit request failed: ${(0, util_ts_1.toErrorMessage)(error)}`,
+                cause: error,
+                isTransient: true,
+            });
+        }
+        if (!response.ok) {
+            throw new MailpitRequestError({
+                message: `Mailpit request failed with HTTP ${response.status}`,
+                status: response.status,
+            });
+        }
+        return await response.json();
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function addSearchQuery(params) {
+    const url = new URL("search", ensureTrailingSlash(params.baseUrl));
+    url.searchParams.set("query", params.query);
+    return url.toString();
+}
+function ensureTrailingSlash(url) {
+    return url.endsWith("/") ? url : `${url}/`;
+}
+function isMessageSentAfter(params) {
+    if (params.sentAfter === undefined) {
+        return true;
+    }
+    const messageTimestamp = Date.parse(params.message.Created);
+    if (!Number.isFinite(messageTimestamp)) {
+        return true;
+    }
+    return messageTimestamp >= params.sentAfter.getTime() - SENT_AFTER_TOLERANCE_MS;
+}
+function compareMailpitMessagesNewestFirst(first, second) {
+    const firstTimestamp = Date.parse(first.Created);
+    const secondTimestamp = Date.parse(second.Created);
+    if (!Number.isFinite(firstTimestamp)) {
+        return Number.isFinite(secondTimestamp) ? 1 : 0;
+    }
+    if (!Number.isFinite(secondTimestamp)) {
+        return -1;
+    }
+    return secondTimestamp - firstTimestamp;
+}
+function isMailpitMessage(value) {
+    return ((0, util_ts_1.isRecord)(value) &&
+        hasMailpitMessageHeaders(value) &&
+        typeof value["Date"] === "string" &&
+        typeof value["Text"] === "string" &&
+        typeof value["HTML"] === "string");
+}
+function isMailpitMessageSummary(value) {
+    return (0, util_ts_1.isRecord)(value) && hasMailpitMessageHeaders(value) && typeof value["Created"] === "string";
+}
+function hasMailpitMessageHeaders(value) {
+    return (typeof value["ID"] === "string" &&
+        typeof value["Subject"] === "string" &&
+        isMailpitAddress(value["From"]) &&
+        Array.isArray(value["To"]) &&
+        value["To"].every(isMailpitAddress));
+}
+function isMailpitAddress(value) {
+    return ((0, util_ts_1.isRecord)(value) && typeof value["Address"] === "string" && typeof value["Name"] === "string");
+}
+//# sourceMappingURL=mailpit.js.map

package/src/lib/mailpit.js.map

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

package/src/lib/retry.d.ts

@@ -0,0 +1,66 @@
+export type RetryFailureReason = "attempts-exhausted" | "non-transient" | "timeout";
+export interface RetryAttemptContext {
+    attemptNumber: number;
+    elapsedMs: number;
+    signal: AbortSignal;
+}
+export interface RetryFailureContext extends RetryAttemptContext {
+    error: unknown;
+}
+export interface ClassifiedRetryMode {
+    kind: "classified";
+    maxAttempts: number;
+    delayMs?: number | ((context: RetryFailureContext) => number) | undefined;
+    isTransient: (context: RetryFailureContext) => boolean;
+}
+export interface PollRetryMode {
+    kind: "poll";
+    timeoutMs: number;
+    intervalsMs?: readonly number[] | undefined;
+    isTransient?: ((context: RetryFailureContext) => boolean) | undefined;
+}
+export type RetryMode = ClassifiedRetryMode | PollRetryMode;
+export interface RetrySuccess<T> {
+    value: T;
+    attempts: number;
+}
+export interface RunWithRetryParams<T> {
+    operationName: string;
+    operation: (context: RetryAttemptContext) => Promise<T>;
+    mode: RetryMode;
+    nowImplementation?: (() => number) | undefined;
+    sleepImplementation?: ((params: {
+        durationMs: number;
+    }) => Promise<void>) | undefined;
+    onFailedAttempt?: ((context: RetryFailureContext) => void | Promise<void>) | undefined;
+}
+interface RetryErrorParams {
+    operationName: string;
+    attempts: number;
+    elapsedMs: number;
+    reason: RetryFailureReason;
+    cause: unknown;
+}
+/**
+ * Rich terminal error for both retry modes.
+ *
+ * `reason` distinguishes deterministic bail-out, attempt exhaustion, and poll
+ * timeout while `cause` retains the last operation error.
+ */
+export declare class RetryError extends Error {
+    readonly attempts: number;
+    readonly cause: unknown;
+    readonly elapsedMs: number;
+    readonly operationName: string;
+    readonly reason: RetryFailureReason;
+    constructor(params: RetryErrorParams);
+}
+/**
+ * Runs one bounded retry policy.
+ *
+ * Classified mode is for operations where the caller can positively identify
+ * transient failures. Poll mode is for idempotent readiness probes where every
+ * failure means "not ready yet" until the timeout expires.
+ */
+export declare function runWithRetry<T>(params: RunWithRetryParams<T>): Promise<RetrySuccess<T>>;
+export {};

package/src/lib/retry.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryError = void 0;
+exports.runWithRetry = runWithRetry;
+const util_ts_1 = require("@clipboard-health/util-ts");
+class PollAttemptTimeoutError extends Error {
+    constructor() {
+        super("Poll attempt exceeded the remaining timeout budget");
+        this.name = "PollAttemptTimeoutError";
+    }
+}
+/**
+ * Rich terminal error for both retry modes.
+ *
+ * `reason` distinguishes deterministic bail-out, attempt exhaustion, and poll
+ * timeout while `cause` retains the last operation error.
+ */
+class RetryError extends Error {
+    attempts;
+    cause;
+    elapsedMs;
+    operationName;
+    reason;
+    constructor(params) {
+        super(formatRetryErrorMessage(params), { cause: params.cause });
+        this.name = "RetryError";
+        this.attempts = params.attempts;
+        this.cause = params.cause;
+        this.elapsedMs = params.elapsedMs;
+        this.operationName = params.operationName;
+        this.reason = params.reason;
+    }
+}
+exports.RetryError = RetryError;
+/**
+ * Runs one bounded retry policy.
+ *
+ * Classified mode is for operations where the caller can positively identify
+ * transient failures. Poll mode is for idempotent readiness probes where every
+ * failure means "not ready yet" until the timeout expires.
+ */
+async function runWithRetry(params) {
+    validateRetryMode(params.mode);
+    const nowImplementation = params.nowImplementation ?? Date.now;
+    const sleepImplementation = params.sleepImplementation ?? sleep;
+    const startedAtMs = nowImplementation();
+    let attemptNumber = 0;
+    let lastError;
+    for (;;) {
+        const elapsedBeforeAttemptMs = getElapsedMs({
+            nowImplementation,
+            startedAtMs,
+        });
+        if (params.mode.kind === "poll" &&
+            attemptNumber > 0 &&
+            elapsedBeforeAttemptMs >= params.mode.timeoutMs) {
+            throw new RetryError({
+                operationName: params.operationName,
+                attempts: attemptNumber,
+                elapsedMs: elapsedBeforeAttemptMs,
+                reason: "timeout",
+                cause: lastError,
+            });
+        }
+        attemptNumber += 1;
+        const abortController = new AbortController();
+        try {
+            // eslint-disable-next-line no-await-in-loop -- Retry attempts are intentionally sequential.
+            const value = await runAttempt({
+                context: {
+                    attemptNumber,
+                    elapsedMs: elapsedBeforeAttemptMs,
+                    signal: abortController.signal,
+                },
+                mode: params.mode,
+                operation: params.operation,
+                abortController,
+            });
+            return { value, attempts: attemptNumber };
+        }
+        catch (error) {
+            lastError = error;
+            const failureContext = {
+                attemptNumber,
+                elapsedMs: getElapsedMs({ nowImplementation, startedAtMs }),
+                error,
+                signal: abortController.signal,
+            };
+            try {
+                // eslint-disable-next-line no-await-in-loop -- Attempt reporting is intentionally sequential.
+                await runWithinRetryBudget({
+                    abortController,
+                    elapsedMs: failureContext.elapsedMs,
+                    mode: params.mode,
+                    promise: Promise.resolve(params.onFailedAttempt?.(failureContext)),
+                });
+            }
+            catch (hookError) {
+                if (hookError instanceof PollAttemptTimeoutError) {
+                    throw createPollTimeoutError({
+                        attempts: attemptNumber,
+                        cause: error,
+                        elapsedMs: getElapsedMs({ nowImplementation, startedAtMs }),
+                        operationName: params.operationName,
+                    });
+                }
+                throw hookError;
+            }
+            failureContext.elapsedMs = getElapsedMs({
+                nowImplementation,
+                startedAtMs,
+            });
+            const terminalReason = getTerminalReason({
+                context: failureContext,
+                mode: params.mode,
+            });
+            if (terminalReason !== undefined) {
+                throw new RetryError({
+                    operationName: params.operationName,
+                    attempts: attemptNumber,
+                    elapsedMs: failureContext.elapsedMs,
+                    reason: terminalReason,
+                    cause: error,
+                });
+            }
+            const durationMs = getRetryDelayMs({
+                context: failureContext,
+                mode: params.mode,
+            });
+            try {
+                // eslint-disable-next-line no-await-in-loop -- Retry attempts are intentionally sequential.
+                await runWithinRetryBudget({
+                    abortController,
+                    elapsedMs: failureContext.elapsedMs,
+                    mode: params.mode,
+                    promise: sleepImplementation({ durationMs }),
+                });
+            }
+            catch (sleepError) {
+                if (sleepError instanceof PollAttemptTimeoutError) {
+                    throw createPollTimeoutError({
+                        attempts: attemptNumber,
+                        cause: error,
+                        elapsedMs: getElapsedMs({ nowImplementation, startedAtMs }),
+                        operationName: params.operationName,
+                    });
+                }
+                throw sleepError;
+            }
+        }
+    }
+}
+function validateRetryMode(mode) {
+    if (mode.kind === "classified") {
+        if (!Number.isInteger(mode.maxAttempts) || mode.maxAttempts < 1) {
+            throw new Error("Classified retry maxAttempts must be a positive integer");
+        }
+        if (typeof mode.delayMs === "number" && (!Number.isFinite(mode.delayMs) || mode.delayMs < 0)) {
+            throw new Error("Classified retry delayMs must be finite and non-negative");
+        }
+        return;
+    }
+    if (!Number.isFinite(mode.timeoutMs) || mode.timeoutMs <= 0) {
+        throw new Error("Poll retry timeoutMs must be positive");
+    }
+    if (mode.intervalsMs?.length === 0) {
+        throw new Error("Poll retry intervalsMs must not be empty");
+    }
+    if (mode.intervalsMs?.some((intervalMs) => !Number.isFinite(intervalMs) || intervalMs < 0) === true) {
+        throw new Error("Poll retry intervalsMs must be finite and non-negative");
+    }
+}
+function getTerminalReason(params) {
+    if (params.mode.kind === "classified") {
+        if (!params.mode.isTransient(params.context)) {
+            return "non-transient";
+        }
+        return params.context.attemptNumber >= params.mode.maxAttempts
+            ? "attempts-exhausted"
+            : undefined;
+    }
+    if (params.context.error instanceof PollAttemptTimeoutError) {
+        return "timeout";
+    }
+    if (params.mode.isTransient?.(params.context) === false) {
+        return "non-transient";
+    }
+    return params.context.elapsedMs >= params.mode.timeoutMs ? "timeout" : undefined;
+}
+async function runAttempt(params) {
+    const operationPromise = params.operation(params.context);
+    return await runWithinRetryBudget({
+        abortController: params.abortController,
+        elapsedMs: params.context.elapsedMs,
+        mode: params.mode,
+        promise: operationPromise,
+    });
+}
+async function runWithinRetryBudget(params) {
+    if (params.mode.kind === "classified") {
+        return await params.promise;
+    }
+    const remainingTimeoutMs = Math.max(params.mode.timeoutMs - params.elapsedMs, 0);
+    let timeout;
+    try {
+        return await Promise.race([
+            params.promise,
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => {
+                    params.abortController.abort();
+                    reject(new PollAttemptTimeoutError());
+                }, remainingTimeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout !== undefined) {
+            clearTimeout(timeout);
+        }
+    }
+}
+function getRetryDelayMs(params) {
+    let durationMs;
+    if (params.mode.kind === "classified") {
+        durationMs =
+            typeof params.mode.delayMs === "function"
+                ? params.mode.delayMs(params.context)
+                : (params.mode.delayMs ?? 0);
+    }
+    else {
+        const intervalsMs = params.mode.intervalsMs ?? [100, 250, 500, 1000];
+        const intervalIndex = Math.min(params.context.attemptNumber - 1, intervalsMs.length - 1);
+        const configuredDelayMs = intervalsMs[intervalIndex] ?? 0;
+        const remainingMs = Math.max(params.mode.timeoutMs - params.context.elapsedMs, 0);
+        durationMs = Math.min(configuredDelayMs, remainingMs);
+    }
+    if (!Number.isFinite(durationMs) || durationMs < 0) {
+        throw new Error("Retry delay must be finite and non-negative");
+    }
+    return durationMs;
+}
+function getElapsedMs(params) {
+    return Math.max(params.nowImplementation() - params.startedAtMs, 0);
+}
+async function sleep(params) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, params.durationMs);
+    });
+}
+function formatRetryErrorMessage(params) {
+    return (`${params.operationName} failed after ${params.attempts} ` +
+        `${params.attempts === 1 ? "attempt" : "attempts"} ` +
+        `(${params.elapsedMs}ms, reason: ${params.reason}). ` +
+        `Last error: ${(0, util_ts_1.toErrorMessage)(params.cause)}`);
+}
+function createPollTimeoutError(params) {
+    return new RetryError({
+        ...params,
+        reason: "timeout",
+    });
+}
+//# sourceMappingURL=retry.js.map

package/src/lib/retry.js.map

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

package/src/lib/setupRetry.d.ts

@@ -0,0 +1,29 @@
+export type SetupRetryClassification = "deterministic" | "identity-collision" | "transient";
+export type SetupRetryDecision = "do-not-retry" | "regenerate-identity" | "retry-same-identity";
+export interface SetupRetryResult {
+    classification: SetupRetryClassification;
+    retryDecision: SetupRetryDecision;
+}
+export interface SetupErrorContext {
+    error: unknown;
+    status: number | undefined;
+}
+export interface ClassifySetupRetryParams {
+    error: unknown;
+    isIdentityCollision?: (context: SetupErrorContext) => boolean;
+    isTransientError?: (context: SetupErrorContext) => boolean;
+}
+/**
+ * Classifies setup failures without conflating identity collisions and
+ * transient infrastructure errors.
+ *
+ * Collision retries must regenerate a fresh identity. Transient retries must
+ * repeat the same identity so they do not change the scenario under test.
+ */
+export declare function classifySetupRetry(params: ClassifySetupRetryParams): SetupRetryResult;
+export declare function isRetryableHttpStatus(params: {
+    status: number | undefined;
+}): boolean;
+export declare function getHttpErrorStatus(params: {
+    error: unknown;
+}): number | undefined;