@crvouga/mockingbird-notifications 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_PORT,
+  createServer
+} from "./chunk-JQ6KPT2C.js";
+import "./chunk-GRGR3QZM.js";
+import "./chunk-QE3TRUI6.js";
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+var HELP = `mockingbird-notifications \u2014 see every SMS, email and push your app sends through Mockingbird
+
+Usage:
+  mockingbird-notifications serve [options]
+
+Where the emulators are (pick one or combine):
+  --fleet <url>        Running fleet controller adminBase, e.g. http://127.0.0.1:9000/__admin/fleet
+  --manifest <file>    The fleet's --ready-file (re-read on every sync, so restarts are followed)
+  --service <n=url>    An emulator by name, e.g. --service twilio=http://127.0.0.1:8798 (repeatable)
+
+Options:
+  --port <n>           Listen port (default ${DEFAULT_PORT}; 0 picks a free one)
+  --host <host>        Listen host (default 127.0.0.1)
+  --namespace <name>   Namespace to watch in the background (repeatable; default "default",
+                       or every fleet namespace with --fleet)
+  --poll <ms>          Background poll interval (default 750; 0 reads only on demand)
+  --admin-key-env <V>  Environment variable holding the admin key (default MOCKINGBIRD_ADMIN_KEY)
+  --ready-json         Print {"url": \u2026} as one JSON line once listening
+  -h, --help           Show this help
+`;
+var main = async (argv) => {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      fleet: { type: "string" },
+      manifest: { type: "string" },
+      service: { type: "string", multiple: true },
+      port: { type: "string" },
+      host: { type: "string" },
+      namespace: { type: "string", multiple: true },
+      poll: { type: "string" },
+      "admin-key-env": { type: "string" },
+      "ready-json": { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    }
+  });
+  if (values.help || positionals[0] !== "serve") {
+    process.stdout.write(HELP);
+    return values.help ? 0 : 2;
+  }
+  const services = {};
+  for (const entry of values.service ?? []) {
+    const eq = entry.indexOf("=");
+    if (eq <= 0) throw new Error(`--service ${entry}: expected name=url`);
+    services[entry.slice(0, eq)] = entry.slice(eq + 1);
+  }
+  if (!values.fleet && !values.manifest && Object.keys(services).length === 0) {
+    process.stderr.write("mockingbird-notifications: pass --fleet, --manifest or --service\n\n");
+    process.stderr.write(HELP);
+    return 2;
+  }
+  const port = values.port === void 0 ? DEFAULT_PORT : Number(values.port);
+  if (!Number.isInteger(port) || port < 0 || port > 65535)
+    throw new Error("--port: expected 0\u201365535");
+  const poll = values.poll === void 0 ? void 0 : Number(values.poll);
+  if (poll !== void 0 && (!Number.isFinite(poll) || poll < 0))
+    throw new Error("--poll: expected milliseconds");
+  const adminKey = process.env[values["admin-key-env"] ?? "MOCKINGBIRD_ADMIN_KEY"];
+  const server = await createServer({
+    port,
+    ...values.host ? { host: values.host } : {},
+    ...values.fleet ? { fleet: values.fleet } : {},
+    ...values.manifest ? { manifest: values.manifest } : {},
+    ...Object.keys(services).length ? { services } : {},
+    ...values.namespace?.length ? { namespaces: values.namespace } : {},
+    ...poll !== void 0 ? { pollIntervalMs: poll } : {},
+    ...adminKey ? { adminKey } : {}
+  });
+  if (values["ready-json"]) process.stdout.write(`${JSON.stringify({ url: server.url })}
+`);
+  else process.stdout.write(`Notifications harness: ${server.url}
+`);
+  await new Promise((resolve) => {
+    const stop = () => resolve();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+  await server.close();
+  return 0;
+};
+main(process.argv.slice(2)).then(
+  (code) => {
+    if (code !== 0) process.exitCode = code;
+  },
+  (error) => {
+    process.stderr.write(
+      `mockingbird-notifications: ${error instanceof Error ? error.message : String(error)}
+`
+    );
+    process.exitCode = 1;
+  }
+);
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/cli.ts"],
+  "sourcesContent": ["#!/usr/bin/env node\n/// <reference types=\"node\" />\nimport { parseArgs } from \"node:util\"\nimport type { ServiceInput } from \"./discovery.js\"\nimport { createServer, DEFAULT_PORT } from \"./server.js\"\n\nconst HELP = `mockingbird-notifications \u2014 see every SMS, email and push your app sends through Mockingbird\n\nUsage:\n  mockingbird-notifications serve [options]\n\nWhere the emulators are (pick one or combine):\n  --fleet <url>        Running fleet controller adminBase, e.g. http://127.0.0.1:9000/__admin/fleet\n  --manifest <file>    The fleet's --ready-file (re-read on every sync, so restarts are followed)\n  --service <n=url>    An emulator by name, e.g. --service twilio=http://127.0.0.1:8798 (repeatable)\n\nOptions:\n  --port <n>           Listen port (default ${DEFAULT_PORT}; 0 picks a free one)\n  --host <host>        Listen host (default 127.0.0.1)\n  --namespace <name>   Namespace to watch in the background (repeatable; default \"default\",\n                       or every fleet namespace with --fleet)\n  --poll <ms>          Background poll interval (default 750; 0 reads only on demand)\n  --admin-key-env <V>  Environment variable holding the admin key (default MOCKINGBIRD_ADMIN_KEY)\n  --ready-json         Print {\"url\": \u2026} as one JSON line once listening\n  -h, --help           Show this help\n`\n\nconst main = async (argv: string[]): Promise<number> => {\n  const { values, positionals } = parseArgs({\n    args: argv,\n    allowPositionals: true,\n    options: {\n      fleet: { type: \"string\" },\n      manifest: { type: \"string\" },\n      service: { type: \"string\", multiple: true },\n      port: { type: \"string\" },\n      host: { type: \"string\" },\n      namespace: { type: \"string\", multiple: true },\n      poll: { type: \"string\" },\n      \"admin-key-env\": { type: \"string\" },\n      \"ready-json\": { type: \"boolean\" },\n      help: { type: \"boolean\", short: \"h\" },\n    },\n  })\n  if (values.help || positionals[0] !== \"serve\") {\n    process.stdout.write(HELP)\n    return values.help ? 0 : 2\n  }\n  const services: Record<string, ServiceInput> = {}\n  for (const entry of values.service ?? []) {\n    const eq = entry.indexOf(\"=\")\n    if (eq <= 0) throw new Error(`--service ${entry}: expected name=url`)\n    services[entry.slice(0, eq)] = entry.slice(eq + 1)\n  }\n  if (!values.fleet && !values.manifest && Object.keys(services).length === 0) {\n    process.stderr.write(\"mockingbird-notifications: pass --fleet, --manifest or --service\\n\\n\")\n    process.stderr.write(HELP)\n    return 2\n  }\n  const port = values.port === undefined ? DEFAULT_PORT : Number(values.port)\n  if (!Number.isInteger(port) || port < 0 || port > 65535)\n    throw new Error(\"--port: expected 0\u201365535\")\n  const poll = values.poll === undefined ? undefined : Number(values.poll)\n  if (poll !== undefined && (!Number.isFinite(poll) || poll < 0))\n    throw new Error(\"--poll: expected milliseconds\")\n  const adminKey = process.env[values[\"admin-key-env\"] ?? \"MOCKINGBIRD_ADMIN_KEY\"]\n  const server = await createServer({\n    port,\n    ...(values.host ? { host: values.host } : {}),\n    ...(values.fleet ? { fleet: values.fleet } : {}),\n    ...(values.manifest ? { manifest: values.manifest } : {}),\n    ...(Object.keys(services).length ? { services } : {}),\n    ...(values.namespace?.length ? { namespaces: values.namespace } : {}),\n    ...(poll !== undefined ? { pollIntervalMs: poll } : {}),\n    ...(adminKey ? { adminKey } : {}),\n  })\n  if (values[\"ready-json\"]) process.stdout.write(`${JSON.stringify({ url: server.url })}\\n`)\n  else process.stdout.write(`Notifications harness: ${server.url}\\n`)\n  await new Promise<void>((resolve) => {\n    const stop = () => resolve()\n    process.once(\"SIGINT\", stop)\n    process.once(\"SIGTERM\", stop)\n  })\n  await server.close()\n  return 0\n}\n\nmain(process.argv.slice(2)).then(\n  (code) => {\n    if (code !== 0) process.exitCode = code\n  },\n  (error: unknown) => {\n    process.stderr.write(\n      `mockingbird-notifications: ${error instanceof Error ? error.message : String(error)}\\n`,\n    )\n    process.exitCode = 1\n  },\n)\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/index.d.ts

@@ -0,0 +1,411 @@
+/** The three kinds of device a notification lands on. */
+type Channel = "sms" | "email" | "push";
+/** Emulators the harness knows how to read. */
+type ServiceKind = "twilio" | "resend" | "fcm" | "ses" | "sns" | "customerio" | "mailosaur";
+declare const SERVICE_KINDS: readonly ServiceKind[];
+declare const SERVICE_LABELS: Record<ServiceKind, string>;
+type Address = {
+    name: string | null;
+    address: string;
+};
+type SmsContent = {
+    body: string;
+    /** One-time code the sender included (Twilio Verify), when known. */
+    code: string | null;
+    media: string[];
+};
+type EmailAttachment = {
+    filename: string;
+    contentType: string | null;
+    size: number | null;
+};
+type EmailContent = {
+    subject: string;
+    html: string | null;
+    text: string | null;
+    cc: string[];
+    bcc: string[];
+    replyTo: string[];
+    attachments: EmailAttachment[];
+    headers: Record<string, string>;
+};
+type PushPlatform = "android" | "ios" | "web" | "unknown";
+type PushContent = {
+    title: string | null;
+    body: string | null;
+    imageUrl: string | null;
+    /** The app the notification belongs to (the FCM project, for example). */
+    app: string;
+    platform: PushPlatform;
+    data: Record<string, string>;
+    badge: number | null;
+    sound: string | null;
+};
+/** One message as a recipient would receive it, normalized across emulators. */
+type Notification = {
+    /** Stable across polls: `<service entry>:<namespace>:<provider id>`. */
+    id: string;
+    /** The provider's own id (Twilio SID, Resend id, FCM message name, …). */
+    providerId: string;
+    channel: Channel;
+    /** The fleet entry name (`twilio`, or an alias such as `push`). */
+    source: string;
+    service: ServiceKind;
+    namespace: string;
+    /** Phone number, email address, or push registration token. */
+    to: string;
+    from: Address;
+    /** ISO-8601, on the emulator's clock. */
+    createdAt: string;
+    /** Short plain-text preview. */
+    preview: string;
+    /** Provider delivery state when it reports one (`queued`, `delivered`, `suppressed`, …). */
+    status: string | null;
+    sms: SmsContent | null;
+    email: EmailContent | null;
+    push: PushContent | null;
+    /** The record exactly as the emulator reported it. */
+    raw: unknown;
+};
+type NotificationFilter = {
+    channel?: Channel | undefined;
+    service?: ServiceKind | undefined;
+    source?: string | undefined;
+    namespace?: string | undefined;
+    /** Exact recipient (case-insensitive for email). */
+    to?: string | undefined;
+    /** Case-insensitive text search across sender, subject, title and body. */
+    contains?: string | undefined;
+    /** Only notifications created at or after this instant (ISO-8601 or epoch ms). */
+    since?: string | number | undefined;
+};
+type SourceStatus = {
+    name: string;
+    service: ServiceKind | null;
+    url: string;
+    ok: boolean;
+    error: string | null;
+    count: number;
+    lastSyncAt: string | null;
+};
+declare const matches: (n: Notification, filter: NotificationFilter) => boolean;
+
+type NotificationClientOptions = {
+    /** Default namespace for every call that does not name one. */
+    namespace?: string;
+    fetch?: (request: Request) => Response | Promise<Response>;
+};
+/** Talks to a running harness over HTTP, for tests that run in another process. */
+declare class NotificationClient {
+    readonly baseUrl: string;
+    private readonly namespace;
+    private readonly fetchImpl;
+    constructor(baseUrl: string, options?: NotificationClientOptions);
+    private get;
+    /** Every matching notification, oldest first. */
+    list(filter?: NotificationFilter): Promise<Notification[]>;
+    /** The newest match, or `null`. */
+    latest(filter?: NotificationFilter): Promise<Notification | null>;
+    /** Wait until `count` (default 1) notifications match and return them; throws on timeout. */
+    waitFor(filter: NotificationFilter, options?: {
+        timeoutMs?: number;
+        count?: number;
+    }): Promise<Notification[]>;
+    /** Wait for the next SMS to `to` and return its one-time code (Twilio Verify) or first 4–8 digit run. */
+    waitForCode(to: string, filter?: NotificationFilter, timeoutMs?: number): Promise<string>;
+    sources(): Promise<SourceStatus[]>;
+    /** A UI link that opens one device (or one notification) for a screenshot. */
+    link(view?: {
+        channel?: "sms" | "email" | "push";
+        to?: string;
+        id?: string;
+    }): string;
+}
+
+/**
+ * Where the emulators are. The harness reads the same fleet the application uses: the live fleet
+ * controller (`adminBase`), the fleet's ready manifest, or explicit URLs and in-process runtimes.
+ */
+
+type FetchLike = (request: Request) => Response | Promise<Response>;
+/** A service emulator: its base URL, an `{ url, adminUrl?, service? }` entry, or an in-process runtime. */
+type ServiceInput = string | {
+    url: string;
+    adminUrl?: string;
+    service?: ServiceKind;
+} | {
+    fetch: FetchLike;
+    service?: ServiceKind;
+    adminPrefix?: string;
+};
+/** The subset of a fleet ready manifest (`--ready-file`) the harness reads. */
+type FleetManifest = {
+    adminBase?: string;
+    services: Record<string, {
+        protocol?: string;
+        url?: string;
+        adminUrl?: string;
+        target?: string;
+    } | undefined>;
+};
+type Endpoint = {
+    /** The fleet entry name, e.g. `twilio`, or an alias such as `push`. */
+    name: string;
+    /** Null until the emulator's health route has told us what it is. */
+    service: ServiceKind | null;
+    /** Absolute admin prefix, e.g. `http://127.0.0.1:8798/__admin`. */
+    adminUrl: string;
+    fetch: FetchLike;
+};
+
+type HarnessOptions = {
+    /** A running fleet controller's `adminBase` (`http://127.0.0.1:9000/__admin/fleet`). */
+    fleet?: string;
+    /** A fleet ready manifest, or a function that reads the current one (re-read on every sync). */
+    manifest?: FleetManifest | (() => FleetManifest | Promise<FleetManifest>);
+    /** Explicit emulators by name: base URLs, `{ url, adminUrl }`, or in-process runtimes. */
+    services?: Record<string, ServiceInput>;
+    /**
+     * Namespaces to watch in the background. `"all"` follows the fleet's namespace list.
+     * Any namespace an API call or the UI asks for is watched from then on. Default `["default"]`,
+     * or `"all"` with `fleet`.
+     */
+    namespaces?: "all" | string[];
+    /** Background polling interval. `0` turns it off; reads still sync on demand. Default 750 ms. */
+    pollIntervalMs?: number;
+    /** Sent as `x-mockingbird-admin-key` to the fleet and every emulator. */
+    adminKey?: string;
+    /** Transport for URL endpoints. Default: global `fetch`. */
+    fetch?: FetchLike;
+    /** Page title. */
+    title?: string;
+};
+type WaitOptions = {
+    timeoutMs?: number;
+    count?: number;
+};
+type NotificationHarness = {
+    /** The harness UI and JSON API as a Fetch handler. */
+    fetch(request: Request): Promise<Response>;
+    /** Read every emulator now. Resolves after a read that started after this call. */
+    sync(namespace?: string): Promise<void>;
+    /** Notifications matching `filter`, oldest first, after a fresh sync. */
+    list(filter?: NotificationFilter): Promise<Notification[]>;
+    /** Resolve once at least `count` (default 1) notifications match; reject after `timeoutMs`. */
+    waitFor(filter: NotificationFilter, options?: WaitOptions): Promise<Notification[]>;
+    sources(): SourceStatus[];
+    close(): void;
+};
+declare const createNotificationHarness: (options?: HarnessOptions) => NotificationHarness;
+
+/**
+ * A small MIME reader for the raw messages SES `SendRawEmail` receives. It covers what mail
+ * libraries produce (nodemailer, the AWS samples): folded headers, RFC 2047 encoded words,
+ * nested multiparts, base64 and quoted-printable bodies. Everything is decoded as UTF-8.
+ */
+
+type ParsedMime = {
+    headers: Record<string, string>;
+    subject: string;
+    from: string | null;
+    to: string[];
+    cc: string[];
+    html: string | null;
+    text: string | null;
+    attachments: EmailAttachment[];
+};
+declare const parseMime: (raw: string) => ParsedMime;
+
+/**
+ * Every `data-testid` the harness UI renders, and selector helpers for browser tests.
+ *
+ * Elements that show one notification also carry its fields as attributes, so a test can narrow by
+ * what it knows instead of by position:
+ *
+ *   data-notification-id  data-channel  data-service  data-source  data-to  data-from
+ *   data-status  data-created-at  data-unread ("true" | "false")
+ *
+ * The UI root (`TEST_IDS.app`) reports its state the same way: `data-ready` ("true" once the first
+ * read finished), `data-view`, `data-namespace`, `data-count`, `data-version`, `data-connected`,
+ * `data-sound` and `data-motion`.
+ *
+ * This module has no dependencies, so Playwright, Cypress or WebdriverIO specs can import it.
+ */
+declare const TEST_IDS: {
+    /** The UI root. */
+    readonly app: "notifications-app";
+    readonly topbar: "topbar";
+    /** `<select>` of namespaces. */
+    readonly namespace: "namespace";
+    /** Filter `<input>` (recipient, sender, text). */
+    readonly search: "search";
+    /** View tabs; `aria-pressed="true"` on the active one. */
+    readonly viewDevices: "view-devices";
+    readonly viewTimeline: "view-timeline";
+    /** "Follow new" checkbox. */
+    readonly follow: "follow";
+    /** Sound on/off button; `aria-pressed`. */
+    readonly sound: "sound-toggle";
+    /** Live stream indicator; `data-state="live" | "reconnecting"`. */
+    readonly connection: "connection";
+    /** One pill per emulator; `data-name`, `data-service`, `data-ok`, `data-count`. */
+    readonly source: "source";
+    /** Discovery or emulator errors, or the "no emulators" hint; `data-kind="error" | "empty"`. */
+    readonly notice: "notice";
+    /** Bottom-left message after an action, e.g. "Conversation archived." */
+    readonly toast: "toast";
+    readonly toastUndo: "toast-undo";
+    /** The phone; `data-screen="threads" | "conversation"`, `data-recipient`, `data-thread`. */
+    readonly smsDevice: "sms-device";
+    /** Phone number `<select>`; option values are E.164 numbers. */
+    readonly smsRecipient: "sms-recipient";
+    /** Unread SMS badge next to the column title (absent when 0). */
+    readonly smsUnreadCount: "sms-unread-count";
+    /** One conversation in the list; `data-from` (the sender address), `data-unread`, `data-pinned`, `data-muted`. */
+    readonly smsThread: "sms-thread";
+    readonly smsThreadName: "sms-thread-name";
+    readonly smsThreadPreview: "sms-thread-preview";
+    readonly smsThreadTime: "sms-thread-time";
+    readonly smsThreadUnread: "sms-thread-unread";
+    /** Swipe actions behind a thread (also reachable with the keyboard: focus the thread, press Delete). */
+    readonly smsThreadDelete: "sms-thread-delete";
+    readonly smsThreadMute: "sms-thread-mute";
+    readonly smsThreadPin: "sms-thread-pin";
+    readonly smsThreadToggleUnread: "sms-thread-toggle-unread";
+    /** Shown when the phone has no messages. */
+    readonly smsEmpty: "sms-empty";
+    /** An open conversation; `data-from`. */
+    readonly smsConversation: "sms-conversation";
+    readonly smsConversationTitle: "sms-conversation-title";
+    readonly smsBack: "sms-back";
+    /** One message; carries the notification attributes plus `data-code` when it holds a one-time code. */
+    readonly smsBubble: "sms-bubble";
+    readonly smsBubbleMedia: "sms-bubble-media";
+    /** The time revealed by swiping the conversation left. */
+    readonly smsBubbleTime: "sms-bubble-time";
+    /** A reaction added with the long-press menu; `data-tapback`. */
+    readonly smsTapback: "sms-tapback";
+    /** Centered date stamp between messages. */
+    readonly smsTimestamp: "sms-timestamp";
+    /** One-time code suggestion above the keyboard; `data-code`. */
+    readonly smsCode: "sms-code";
+    /** Long-press menu on a bubble. */
+    readonly smsMenu: "sms-menu";
+    readonly smsMenuCopy: "sms-menu-copy";
+    /** One tapback in the menu; `data-tapback="heart" | "like" | "dislike" | "laugh" | "emphasize" | "question"`. */
+    readonly smsMenuTapback: "sms-menu-tapback";
+    /** The phone; `data-skin="ios" | "android"`, `data-recipient`, `data-platform`. */
+    readonly pushDevice: "push-device";
+    /** Device token `<select>`. */
+    readonly pushRecipient: "push-recipient";
+    /** Skin buttons; `data-value`, `aria-pressed`. */
+    readonly pushSkin: "push-skin";
+    readonly pushUnreadCount: "push-unread-count";
+    /** One notification; notification attributes plus `data-expanded`, `data-platform`, `data-app`, `data-stacked`. */
+    readonly pushNotification: "push-notification";
+    readonly pushNotificationApp: "push-notification-app";
+    readonly pushNotificationTitle: "push-notification-title";
+    readonly pushNotificationBody: "push-notification-body";
+    readonly pushNotificationTime: "push-notification-time";
+    readonly pushNotificationImage: "push-notification-image";
+    /** The `data` payload, shown when expanded. */
+    readonly pushNotificationData: "push-notification-data";
+    /** Service, status, badge and sound, shown when expanded. */
+    readonly pushNotificationMeta: "push-notification-meta";
+    /** iOS: a group of notifications from one app; `data-app`, `data-count`, `data-open`. */
+    readonly pushGroup: "push-group";
+    /** iOS: "N more notifications" under a collapsed group (click to open it); `data-count`. */
+    readonly pushGroupMore: "push-group-more";
+    /** iOS: "Show less" on an open group. */
+    readonly pushGroupCollapse: "push-group-collapse";
+    /** iOS: swipe-left actions. */
+    readonly pushClear: "push-clear";
+    readonly pushOptions: "push-options";
+    /** iOS long-press preview; Android long-press settings. */
+    readonly pushPreview: "push-preview";
+    readonly pushSettings: "push-settings";
+    /** Android "Clear all". */
+    readonly pushClearAll: "push-clear-all";
+    readonly pushEmpty: "push-empty";
+    /** The browser window; `data-screen="inbox" | "message"`, `data-recipient`. */
+    readonly emailDevice: "email-device";
+    /** Mailbox `<select>`; option values are lower-case addresses. */
+    readonly emailRecipient: "email-recipient";
+    readonly emailUnreadCount: "email-unread-count";
+    /** One inbox row; notification attributes plus `data-starred`. */
+    readonly emailRow: "email-row";
+    readonly emailRowFrom: "email-row-from";
+    readonly emailRowSubject: "email-row-subject";
+    readonly emailRowSnippet: "email-row-snippet";
+    readonly emailRowDate: "email-row-date";
+    readonly emailRowService: "email-row-service";
+    readonly emailRowAttachment: "email-row-attachment";
+    readonly emailRowStar: "email-row-star";
+    /** Hover actions on a row. */
+    readonly emailRowArchive: "email-row-archive";
+    readonly emailRowDelete: "email-row-delete";
+    readonly emailRowToggleRead: "email-row-toggle-read";
+    readonly emailRefresh: "email-refresh";
+    readonly emailEmpty: "email-empty";
+    /** The open message; notification attributes. */
+    readonly emailOpen: "email-open";
+    readonly emailBack: "email-back";
+    readonly emailArchive: "email-archive";
+    readonly emailDelete: "email-delete";
+    readonly emailMarkUnread: "email-mark-unread";
+    readonly emailSubject: "email-subject";
+    readonly emailFromName: "email-from-name";
+    readonly emailFromAddress: "email-from-address";
+    /** "to me, …" line; click to toggle the details. */
+    readonly emailTo: "email-to";
+    readonly emailDate: "email-date";
+    readonly emailDetails: "email-details";
+    /** One row of the details; `data-field="from" | "to" | "cc" | "bcc" | "reply-to" | "date" | "subject" | "mailed-by" | "message-id"`. */
+    readonly emailDetail: "email-detail";
+    /** The HTML body `<iframe>` (same origin: use `frameLocator`). */
+    readonly emailBody: "email-body";
+    /** The plain-text body when there is no HTML. */
+    readonly emailText: "email-text";
+    readonly emailAttachments: "email-attachments";
+    /** One attachment; `data-filename`, `data-content-type`, `data-size`. */
+    readonly emailAttachment: "email-attachment";
+    readonly timeline: "timeline";
+    /** One row; notification attributes. Click it to inspect. */
+    readonly timelineRow: "timeline-row";
+    readonly timelineEmpty: "timeline-empty";
+    /** The JSON inspector; notification attributes. Opened by clicking a timeline row or double-clicking any notification. */
+    readonly inspector: "inspector";
+    readonly inspectorTitle: "inspector-title";
+    readonly inspectorClose: "inspector-close";
+    readonly inspectorShowOnDevice: "inspector-show-on-device";
+    /** One normalized field; `data-field`. */
+    readonly inspectorField: "inspector-field";
+    /** The full record, normalized fields plus `raw`, as JSON text. */
+    readonly inspectorJson: "inspector-json";
+};
+type TestId = (typeof TEST_IDS)[keyof typeof TEST_IDS];
+/** CSS selectors for the harness UI. Each one works with `page.locator()` or `querySelector`. */
+declare const selectors: {
+    /** `[data-testid="…"]` */
+    testId: (id: TestId) => string;
+    /** The ready UI root: wait for this before asserting. */
+    ready: () => string;
+    /** Any element showing this notification (bubble, thread, card, row, open email, timeline row). */
+    notification: (id: string) => string;
+    /** A message bubble, optionally from one sender. */
+    smsBubble: (filter?: {
+        from?: string;
+        id?: string;
+    }) => string;
+    /** A conversation in the Messages list. */
+    smsThread: (from: string) => string;
+    /** A push notification card, optionally by id. */
+    pushNotification: (id?: string) => string;
+    /** An inbox row, optionally by id. */
+    emailRow: (id?: string) => string;
+    /** A timeline row, optionally by id. */
+    timelineRow: (id?: string) => string;
+};
+
+export { NotificationClient, SERVICE_KINDS, SERVICE_LABELS, TEST_IDS, createNotificationHarness, matches, parseMime, selectors };
+export type { Address, Channel, EmailAttachment, EmailContent, Endpoint, FetchLike, FleetManifest, HarnessOptions, Notification, NotificationClientOptions, NotificationFilter, NotificationHarness, PushContent, PushPlatform, ServiceInput, ServiceKind, SmsContent, SourceStatus, TestId, WaitOptions };

package/dist/index.js

@@ -0,0 +1,95 @@
+import {
+  TEST_IDS,
+  selectors
+} from "./chunk-LM7R7AR7.js";
+import {
+  SERVICE_KINDS,
+  SERVICE_LABELS,
+  createNotificationHarness,
+  filterToSearch,
+  matches,
+  parseMime
+} from "./chunk-GRGR3QZM.js";
+import "./chunk-QE3TRUI6.js";
+
+// src/client.ts
+var NotificationClient = class {
+  baseUrl;
+  namespace;
+  fetchImpl;
+  constructor(baseUrl, options = {}) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.namespace = options.namespace;
+    this.fetchImpl = options.fetch ?? ((request) => fetch(request));
+  }
+  async get(path, filter = {}, extra = {}) {
+    const params = filterToSearch({ namespace: this.namespace, ...filter });
+    for (const [k, v] of Object.entries(extra)) params.set(k, v);
+    const query = params.toString();
+    const response = await this.fetchImpl(
+      new Request(`${this.baseUrl}${path}${query ? `?${query}` : ""}`)
+    );
+    const body = await response.json();
+    if (!response.ok) {
+      const error = new Error(body.error?.message ?? `HTTP ${response.status}`);
+      Object.assign(error, { status: response.status, body });
+      throw error;
+    }
+    return body;
+  }
+  /** Every matching notification, oldest first. */
+  async list(filter = {}) {
+    return (await this.get("/api/notifications", filter)).notifications;
+  }
+  /** The newest match, or `null`. */
+  async latest(filter = {}) {
+    try {
+      return await this.get("/api/notifications/latest", filter);
+    } catch (error) {
+      if (error.status === 404) return null;
+      throw error;
+    }
+  }
+  /** Wait until `count` (default 1) notifications match and return them; throws on timeout. */
+  async waitFor(filter, options = {}) {
+    const extra = {};
+    if (options.timeoutMs !== void 0) extra.timeoutMs = String(options.timeoutMs);
+    if (options.count !== void 0) extra.count = String(options.count);
+    return (await this.get("/api/wait", filter, extra)).notifications;
+  }
+  /** Wait for the next SMS to `to` and return its one-time code (Twilio Verify) or first 4–8 digit run. */
+  async waitForCode(to, filter = {}, timeoutMs) {
+    const found = await this.waitFor(
+      { channel: "sms", to, ...filter },
+      timeoutMs === void 0 ? {} : { timeoutMs }
+    );
+    const last = found.at(-1);
+    const code = last?.sms?.code ?? /\b(\d{4,8})\b/.exec(last?.sms?.body ?? "")?.[1];
+    if (!code) throw new Error(`no code in the latest SMS to ${to}`);
+    return code;
+  }
+  async sources() {
+    return (await this.get("/api/sources")).sources;
+  }
+  /** A UI link that opens one device (or one notification) for a screenshot. */
+  link(view = {}) {
+    const params = new URLSearchParams();
+    if (this.namespace) params.set("namespace", this.namespace);
+    if (view.channel) params.set("view", view.channel);
+    if (view.to) params.set("to", view.to);
+    if (view.id) params.set("id", view.id);
+    const query = params.toString();
+    return `${this.baseUrl}/${query ? `?${query}` : ""}`;
+  }
+};
+export {
+  NotificationClient,
+  SERVICE_KINDS,
+  SERVICE_LABELS,
+  TEST_IDS,
+  createNotificationHarness,
+  matches,
+  parseMime,
+  selectors
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/client.ts"],
+  "sourcesContent": ["import {\n  filterToSearch,\n  type Notification,\n  type NotificationFilter,\n  type SourceStatus,\n} from \"./model.js\"\n\nexport type NotificationClientOptions = {\n  /** Default namespace for every call that does not name one. */\n  namespace?: string\n  fetch?: (request: Request) => Response | Promise<Response>\n}\n\n/** Talks to a running harness over HTTP, for tests that run in another process. */\nexport class NotificationClient {\n  readonly baseUrl: string\n  private readonly namespace: string | undefined\n  private readonly fetchImpl: (request: Request) => Response | Promise<Response>\n\n  constructor(baseUrl: string, options: NotificationClientOptions = {}) {\n    this.baseUrl = baseUrl.replace(/\\/+$/, \"\")\n    this.namespace = options.namespace\n    this.fetchImpl = options.fetch ?? ((request) => fetch(request))\n  }\n\n  private async get<T>(\n    path: string,\n    filter: NotificationFilter = {},\n    extra: Record<string, string> = {},\n  ) {\n    const params = filterToSearch({ namespace: this.namespace, ...filter })\n    for (const [k, v] of Object.entries(extra)) params.set(k, v)\n    const query = params.toString()\n    const response = await this.fetchImpl(\n      new Request(`${this.baseUrl}${path}${query ? `?${query}` : \"\"}`),\n    )\n    const body = (await response.json()) as T & { error?: { message?: string } }\n    if (!response.ok) {\n      const error = new Error(body.error?.message ?? `HTTP ${response.status}`)\n      Object.assign(error, { status: response.status, body })\n      throw error\n    }\n    return body\n  }\n\n  /** Every matching notification, oldest first. */\n  async list(filter: NotificationFilter = {}): Promise<Notification[]> {\n    return (await this.get<{ notifications: Notification[] }>(\"/api/notifications\", filter))\n      .notifications\n  }\n\n  /** The newest match, or `null`. */\n  async latest(filter: NotificationFilter = {}): Promise<Notification | null> {\n    try {\n      return await this.get<Notification>(\"/api/notifications/latest\", filter)\n    } catch (error) {\n      if ((error as { status?: number }).status === 404) return null\n      throw error\n    }\n  }\n\n  /** Wait until `count` (default 1) notifications match and return them; throws on timeout. */\n  async waitFor(\n    filter: NotificationFilter,\n    options: { timeoutMs?: number; count?: number } = {},\n  ): Promise<Notification[]> {\n    const extra: Record<string, string> = {}\n    if (options.timeoutMs !== undefined) extra.timeoutMs = String(options.timeoutMs)\n    if (options.count !== undefined) extra.count = String(options.count)\n    return (await this.get<{ notifications: Notification[] }>(\"/api/wait\", filter, extra))\n      .notifications\n  }\n\n  /** Wait for the next SMS to `to` and return its one-time code (Twilio Verify) or first 4\u20138 digit run. */\n  async waitForCode(\n    to: string,\n    filter: NotificationFilter = {},\n    timeoutMs?: number,\n  ): Promise<string> {\n    const found = await this.waitFor(\n      { channel: \"sms\", to, ...filter },\n      timeoutMs === undefined ? {} : { timeoutMs },\n    )\n    const last = found.at(-1)\n    const code = last?.sms?.code ?? /\\b(\\d{4,8})\\b/.exec(last?.sms?.body ?? \"\")?.[1]\n    if (!code) throw new Error(`no code in the latest SMS to ${to}`)\n    return code\n  }\n\n  async sources(): Promise<SourceStatus[]> {\n    return (await this.get<{ sources: SourceStatus[] }>(\"/api/sources\")).sources\n  }\n\n  /** A UI link that opens one device (or one notification) for a screenshot. */\n  link(view: { channel?: \"sms\" | \"email\" | \"push\"; to?: string; id?: string } = {}): string {\n    const params = new URLSearchParams()\n    if (this.namespace) params.set(\"namespace\", this.namespace)\n    if (view.channel) params.set(\"view\", view.channel)\n    if (view.to) params.set(\"to\", view.to)\n    if (view.id) params.set(\"id\", view.id)\n    const query = params.toString()\n    return `${this.baseUrl}/${query ? `?${query}` : \"\"}`\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}