@bugmole/cli 0.4.0

package/src/integrations/temp-email.ts

@@ -0,0 +1,175 @@
+/**
+ * A real, disposable email inbox for QA flows -- so a signup/confirmation
+ * journey can be tested against a real message a real mail provider
+ * actually delivered, not just a database row that says "confirmed."
+ *
+ * Backed by mail.tm's public REST API (https://api.mail.tm), not browser
+ * automation against a temp-mail website: no CAPTCHA to solve (several
+ * disposable-inbox sites gate message content behind one), a stable typed
+ * response instead of scraping rendered HTML, and no dependency on which
+ * inbox UI happens to be reachable this week.
+ */
+
+const API_BASE = "https://api.mail.tm";
+
+export type TempEmailInbox = {
+  address: string;
+  password: string;
+  accountId: string;
+  token: string;
+};
+
+export type TempEmailMessage = {
+  id: string;
+  from: string;
+  subject: string;
+  text: string;
+  html: string;
+  receivedAt: string;
+};
+
+type MailTmDomain = { domain: string };
+type MailTmDomainList = { "hydra:member": MailTmDomain[] };
+type MailTmAccount = { id: string; address: string };
+type MailTmTokenResponse = { token: string };
+type MailTmMessageSummary = { id: string; from: { address: string }; subject: string; createdAt: string };
+type MailTmMessageList = { "hydra:member": MailTmMessageSummary[] };
+type MailTmMessageDetail = { id: string; from: { address: string }; subject: string; text?: string; html?: string[]; createdAt: string };
+
+async function mailTmFetch<T>(path: string, init?: RequestInit): Promise<T> {
+  const response = await fetch(`${API_BASE}${path}`, {
+    ...init,
+    headers: { "content-type": "application/json", ...init?.headers },
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(`mail.tm ${init?.method ?? "GET"} ${path} failed: ${response.status} ${body.slice(0, 200)}`);
+  }
+  return (await response.json()) as T;
+}
+
+function randomLocalPart(): string {
+  return Array.from({ length: 12 }, () => "abcdefghijklmnopqrstuvwxyz0123456789"[Math.floor(Math.random() * 36)]).join("");
+}
+
+/**
+ * Creates a fresh, real, receivable inbox. Each call is a brand-new address
+ * on a domain mail.tm currently serves -- callers never need to manage
+ * inbox lifecycles across runs, since a new one is cheap and disposable by
+ * design.
+ */
+export async function createTempEmailInbox(): Promise<TempEmailInbox> {
+  const domains = await mailTmFetch<MailTmDomainList>("/domains");
+  const domain = domains["hydra:member"].find((entry) => entry.domain)?.domain;
+  if (!domain) throw new Error("mail.tm has no active domain to create an inbox on right now.");
+
+  const address = `${randomLocalPart()}@${domain}`;
+  // A per-inbox random password, never reused or exposed to the flow author;
+  // this account exists only to receive one QA message and then be deleted.
+  const password = randomLocalPart() + randomLocalPart();
+
+  const account = await mailTmFetch<MailTmAccount>("/accounts", {
+    method: "POST",
+    body: JSON.stringify({ address, password }),
+  });
+  const tokenResponse = await mailTmFetch<MailTmTokenResponse>("/token", {
+    method: "POST",
+    body: JSON.stringify({ address, password }),
+  });
+
+  return { address, password, accountId: account.id, token: tokenResponse.token };
+}
+
+export type WaitForTempEmailOptions = {
+  /** Substring match against the message's From address, case-insensitive. */
+  from?: string;
+  /** Substring match against the message's subject, case-insensitive. */
+  subject?: string;
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+};
+
+/**
+ * Polls the inbox until a message matching the given criteria arrives, then
+ * fetches its full body. Matching happens on the lightweight summary list
+ * first so a busy inbox isn't fetching full bodies for messages that were
+ * never going to match.
+ */
+export async function waitForTempEmailMessage(inbox: TempEmailInbox, options: WaitForTempEmailOptions = {}): Promise<TempEmailMessage> {
+  const timeoutMs = options.timeoutMs ?? 30_000;
+  const pollIntervalMs = options.pollIntervalMs ?? 2_000;
+  const fromFilter = options.from?.toLowerCase();
+  const subjectFilter = options.subject?.toLowerCase();
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    const list = await mailTmFetch<MailTmMessageList>("/messages", {
+      headers: { Authorization: `Bearer ${inbox.token}` },
+    });
+    const match = list["hydra:member"].find(
+      (summary) =>
+        (!fromFilter || summary.from.address.toLowerCase().includes(fromFilter)) &&
+        (!subjectFilter || summary.subject.toLowerCase().includes(subjectFilter)),
+    );
+    if (match) {
+      const detail = await mailTmFetch<MailTmMessageDetail>(`/messages/${match.id}`, {
+        headers: { Authorization: `Bearer ${inbox.token}` },
+      });
+      return {
+        id: detail.id,
+        from: detail.from.address,
+        subject: detail.subject,
+        text: detail.text ?? "",
+        html: (detail.html ?? []).join("\n"),
+        receivedAt: detail.createdAt,
+      };
+    }
+    if (Date.now() >= deadline) {
+      const criteria = [fromFilter && `from containing "${fromFilter}"`, subjectFilter && `subject containing "${subjectFilter}"`]
+        .filter(Boolean)
+        .join(" and ");
+      throw new Error(`No message${criteria ? ` (${criteria})` : ""} arrived at ${inbox.address} within ${timeoutMs}ms.`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+}
+
+/**
+ * Pulls the first link out of a message body, optionally requiring the link
+ * text or the URL itself to contain a substring (e.g. "confirm"). Real
+ * transactional email routes links through the sending provider's own
+ * click-tracking redirect, so this deliberately returns that URL as-is
+ * rather than trying to guess the "real" destination underneath it --
+ * following the redirect is the whole point of the test.
+ */
+export function extractFirstLink(message: Pick<TempEmailMessage, "html" | "text">, match?: string): string {
+  const hrefPattern = /<a\b[^>]*\bhref=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi;
+  const candidates: { href: string; text: string }[] = [];
+  for (const found of message.html.matchAll(hrefPattern)) {
+    candidates.push({ href: found[1], text: found[2].replace(/<[^>]*>/g, "").trim() });
+  }
+  if (candidates.length === 0) {
+    const bareUrl = message.text.match(/https?:\/\/\S+/);
+    if (bareUrl) candidates.push({ href: bareUrl[0], text: "" });
+  }
+
+  const needle = match?.toLowerCase();
+  const chosen = needle
+    ? candidates.find((candidate) => candidate.href.toLowerCase().includes(needle) || candidate.text.toLowerCase().includes(needle))
+    : candidates[0];
+
+  if (!chosen) {
+    throw new Error(
+      `No link${match ? ` matching "${match}"` : ""} found in message "${message.html ? "(html body)" : "(text body)"}".`,
+    );
+  }
+  return chosen.href;
+}
+
+/** Deletes the inbox. Best-effort: a QA run's cleanup should never fail the run over it. */
+export async function deleteTempEmailInbox(inbox: TempEmailInbox): Promise<void> {
+  await mailTmFetch(`/accounts/${inbox.accountId}`, {
+    method: "DELETE",
+    headers: { Authorization: `Bearer ${inbox.token}` },
+  }).catch(() => undefined);
+}

package/src/integrations/testflight-feedback.test.ts

@@ -0,0 +1,51 @@
+import assert from "node:assert/strict";
+import { createHmac } from "node:crypto";
+import test from "node:test";
+import {
+  normalizeTestFlightFeedback,
+  TestFlightFeedbackValidationError,
+  verifyTestFlightSignature,
+} from "./testflight-feedback.js";
+
+test("normalizes common TestFlight feedback fields", () => {
+  const feedback = normalizeTestFlightFeedback({
+    feedback: "The checkout button is clipped.",
+    tester: { name: "Test User", email: "tester@example.invalid" },
+    app: { name: "Bugmole", bundleId: "com.example.bugmole" },
+    appVersion: "1.4.0",
+    buildNumber: 42,
+    device: { model: "iPhone 15", os: "iOS", osVersion: "18.5" },
+    timestamp: "2026-07-13T05:00:00.000Z",
+    attachments: [{ url: "https://example.invalid/screenshot.png" }],
+  });
+
+  assert.equal(feedback.feedbackText, "The checkout button is clipped.");
+  assert.equal(feedback.tester?.email, "tester@example.invalid");
+  assert.equal(feedback.app.build, "42");
+  assert.equal(feedback.device?.osVersion, "18.5");
+  assert.deepEqual(feedback.attachments, ["https://example.invalid/screenshot.png"]);
+  assert.equal(feedback.source, "testflight");
+  assert.equal(feedback.status, "new");
+});
+
+test("rejects malformed feedback", () => {
+  assert.throws(
+    () => normalizeTestFlightFeedback({ appVersion: "1.0" }),
+    (error: unknown) =>
+      error instanceof TestFlightFeedbackValidationError &&
+      error.message === "Payload must include feedback text.",
+  );
+  assert.throws(() => normalizeTestFlightFeedback("not-an-object"));
+});
+
+test("verifies sha256 and sha256= HMAC signatures", () => {
+  const body = JSON.stringify({ feedback: "Hello" });
+  const secret = "testflight-placeholder-secret";
+  const digest = createHmac("sha256", secret).update(body).digest("hex");
+
+  assert.equal(verifyTestFlightSignature(body, digest, secret), true);
+  assert.equal(verifyTestFlightSignature(body, `sha256=${digest}`, secret), true);
+  assert.equal(verifyTestFlightSignature(body, `${digest.slice(0, -1)}0`, secret), false);
+  assert.equal(verifyTestFlightSignature(body, digest, "wrong-secret"), false);
+  assert.equal(verifyTestFlightSignature(body, null, secret), false);
+});

package/src/integrations/testflight-feedback.ts

@@ -0,0 +1,173 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export type TestFlightFeedbackPayload = {
+  feedback?: string;
+  comment?: string;
+  feedbackText?: string;
+  tester?: {
+    name?: string;
+    email?: string;
+    contact?: string;
+  };
+  testerName?: string;
+  testerEmail?: string;
+  contactEmail?: string;
+  app?: {
+    name?: string;
+    bundleId?: string;
+  };
+  appName?: string;
+  bundleId?: string;
+  build?: string | number;
+  buildNumber?: string | number;
+  version?: string;
+  appVersion?: string;
+  device?: {
+    model?: string;
+    name?: string;
+    os?: string;
+    osVersion?: string;
+  };
+  deviceModel?: string;
+  deviceName?: string;
+  os?: string;
+  osVersion?: string;
+  submittedAt?: string;
+  timestamp?: string;
+  createdAt?: string;
+  attachments?: Array<string | { url?: string; name?: string }>;
+  links?: string[];
+  source?: string;
+  environment?: string;
+};
+
+export type QaFeedbackStatus = "new" | "triaged" | "linked";
+
+export type QaFeedback = {
+  id: string;
+  source: "testflight";
+  feedbackText: string;
+  tester?: {
+    name?: string;
+    email?: string;
+    contact?: string;
+  };
+  app: {
+    name?: string;
+    bundleId?: string;
+    version?: string;
+    build?: string;
+  };
+  device?: {
+    model?: string;
+    name?: string;
+    os?: string;
+    osVersion?: string;
+  };
+  submittedAt?: string;
+  receivedAt: string;
+  attachments: string[];
+  environment?: string;
+  status: QaFeedbackStatus;
+  links: {
+    testCase?: string;
+    defect?: string;
+    evidence?: string;
+  };
+};
+
+export class TestFlightFeedbackValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TestFlightFeedbackValidationError";
+  }
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function stringFrom(value: unknown): string | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return optionalString(value);
+}
+
+function objectFrom(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function firstString(...values: unknown[]): string | undefined {
+  return values.map(stringFrom).find(Boolean);
+}
+
+export function normalizeTestFlightFeedback(
+  input: unknown,
+  options: { id?: string; receivedAt?: string } = {},
+): QaFeedback {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new TestFlightFeedbackValidationError("Payload must be a JSON object.");
+  }
+
+  const payload = input as TestFlightFeedbackPayload;
+  const feedbackText = firstString(payload.feedbackText, payload.feedback, payload.comment);
+  if (!feedbackText) {
+    throw new TestFlightFeedbackValidationError("Payload must include feedback text.");
+  }
+
+  const tester = objectFrom(payload.tester);
+  const app = objectFrom(payload.app);
+  const device = objectFrom(payload.device);
+  const attachmentValues = Array.isArray(payload.attachments) ? payload.attachments : [];
+  const attachments = [
+    ...attachmentValues
+      .map((item) => (typeof item === "string" ? item : objectFrom(item).url))
+      .map(optionalString)
+      .filter((item): item is string => Boolean(item)),
+    ...(Array.isArray(payload.links) ? payload.links : [])
+      .map(optionalString)
+      .filter((item): item is string => Boolean(item)),
+  ];
+
+  return {
+    id: options.id ?? `testflight-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    source: "testflight",
+    feedbackText,
+    tester: {
+      name: firstString(tester.name, payload.testerName),
+      email: firstString(tester.email, payload.testerEmail, payload.contactEmail),
+      contact: firstString(tester.contact),
+    },
+    app: {
+      name: firstString(app.name, payload.appName),
+      bundleId: firstString(app.bundleId, payload.bundleId),
+      version: firstString(payload.appVersion, payload.version),
+      build: firstString(payload.buildNumber, payload.build),
+    },
+    device: {
+      model: firstString(device.model, payload.deviceModel),
+      name: firstString(device.name, payload.deviceName),
+      os: firstString(device.os, payload.os),
+      osVersion: firstString(device.osVersion, payload.osVersion),
+    },
+    submittedAt: firstString(payload.submittedAt, payload.timestamp, payload.createdAt),
+    receivedAt: options.receivedAt ?? new Date().toISOString(),
+    attachments,
+    environment: optionalString(payload.environment),
+    status: "new",
+    links: {},
+  };
+}
+
+export function verifyTestFlightSignature(
+  rawBody: string,
+  suppliedSignature: string | null,
+  secret: string,
+): boolean {
+  if (!suppliedSignature || !secret) return false;
+  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
+  const provided = suppliedSignature.trim().replace(/^sha256=/i, "");
+  if (!/^[a-f0-9]{64}$/i.test(provided)) return false;
+  return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(provided, "hex"));
+}

package/src/integrations/webdriver-client.ts

@@ -0,0 +1,131 @@
+// A small W3C WebDriver client: enough to drive Appium sessions on device
+// clouds (BrowserStack, Kobiton, AWS Device Farm) without a heavy dependency.
+
+export const ELEMENT_KEY = "element-6066-11e4-a52e-4f735466cecf";
+
+export class WebDriverError extends Error {
+  constructor(readonly status: number, readonly error: string, message: string) {
+    super(message);
+    this.name = "WebDriverError";
+  }
+}
+
+export type SessionOptions = {
+  /** Hub URL, e.g. https://hub.browserstack.com/wd/hub. Credentials may be in the URL or in `authorization`. */
+  hubUrl: string;
+  capabilities: Record<string, unknown>;
+  authorization?: string;
+  fetch?: typeof fetch;
+  /** Per-command timeout. */
+  timeoutMs?: number;
+};
+
+export type Locator = { using: string; value: string };
+
+function splitCredentials(hubUrl: string): { url: string; authorization?: string } {
+  const url = new URL(hubUrl);
+  if (!url.username) return { url: url.toString().replace(/\/$/, "") };
+  const authorization = `Basic ${btoa(`${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}`)}`;
+  url.username = "";
+  url.password = "";
+  return { url: url.toString().replace(/\/$/, ""), authorization };
+}
+
+export class WebDriverSession {
+  private constructor(
+    readonly id: string,
+    readonly capabilities: Record<string, unknown>,
+    private readonly base: string,
+    private readonly authorization: string | undefined,
+    private readonly doFetch: typeof fetch,
+    private readonly timeoutMs: number,
+  ) {}
+
+  static async create(options: SessionOptions): Promise<WebDriverSession> {
+    const { url, authorization } = splitCredentials(options.hubUrl);
+    const doFetch = options.fetch ?? fetch;
+    const auth = options.authorization ?? authorization;
+    const reply = await send(doFetch, `${url}/session`, "POST", auth, { capabilities: { alwaysMatch: options.capabilities, firstMatch: [{}] } }, 5 * 60_000);
+    const value = reply as { sessionId?: string; capabilities?: Record<string, unknown> };
+    if (!value.sessionId) throw new WebDriverError(500, "session not created", "The device cloud didn't start a session");
+    return new WebDriverSession(value.sessionId, value.capabilities ?? {}, `${url}/session/${value.sessionId}`, auth, doFetch, options.timeoutMs ?? 60_000);
+  }
+
+  command<T = unknown>(method: string, path: string, body?: unknown): Promise<T> {
+    return send(this.doFetch, `${this.base}${path}`, method, this.authorization, body, this.timeoutMs) as Promise<T>;
+  }
+
+  navigate(url: string) {
+    return this.command("POST", "/url", { url });
+  }
+
+  async findElements(locator: Locator): Promise<string[]> {
+    const found = await this.command<Array<Record<string, string>>>("POST", "/elements", locator);
+    return found.map((element) => element[ELEMENT_KEY] ?? Object.values(element)[0]);
+  }
+
+  click(element: string) {
+    return this.command("POST", `/element/${element}/click`, {});
+  }
+
+  sendKeys(element: string, text: string) {
+    return this.command("POST", `/element/${element}/value`, { text, value: [...text] });
+  }
+
+  clear(element: string) {
+    return this.command("POST", `/element/${element}/clear`, {});
+  }
+
+  async isDisplayed(element: string): Promise<boolean> {
+    try {
+      return Boolean(await this.command("GET", `/element/${element}/displayed`));
+    } catch (error) {
+      if (error instanceof WebDriverError && error.error === "stale element reference") return false;
+      throw error;
+    }
+  }
+
+  async activeElement(): Promise<string | null> {
+    try {
+      const value = await this.command<Record<string, string>>("GET", "/element/active");
+      return value[ELEMENT_KEY] ?? Object.values(value)[0] ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Sends keys to whatever has focus. */
+  keys(text: string) {
+    return this.command("POST", "/actions", {
+      actions: [{ type: "key", id: "keyboard", actions: [...text].flatMap((value) => [{ type: "keyDown", value }, { type: "keyUp", value }]) }],
+    });
+  }
+
+  execute<T = unknown>(script: string, args: unknown[] = []): Promise<T> {
+    return this.command<T>("POST", "/execute/sync", { script, args });
+  }
+
+  async screenshot(): Promise<Uint8Array> {
+    const base64 = await this.command<string>("GET", "/screenshot");
+    return Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+  }
+
+  async delete(): Promise<void> {
+    await this.command("DELETE", "").catch(() => undefined);
+  }
+}
+
+async function send(doFetch: typeof fetch, url: string, method: string, authorization: string | undefined, body: unknown, timeoutMs: number): Promise<unknown> {
+  const response = await doFetch(url, {
+    method,
+    headers: { "content-type": "application/json; charset=utf-8", ...(authorization ? { authorization } : {}) },
+    body: body === undefined || method === "GET" || method === "DELETE" ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const payload = await response.json().catch(() => ({})) as { value?: any };
+  const value = payload.value;
+  if (!response.ok || (value && typeof value === "object" && typeof value.error === "string")) {
+    throw new WebDriverError(response.status, value?.error ?? `http ${response.status}`, value?.message ?? `WebDriver ${method} failed (${response.status})`);
+  }
+  return value;
+}