@letsrunit/mailbox 0.1.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@letsrunit/mailbox",
+  "version": "0.1.0",
+  "description": "Test email mailbox integration for letsrunit",
+  "keywords": [
+    "testing",
+    "email",
+    "mailbox",
+    "letsrunit"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/letsrunit/letsrunit.git",
+    "directory": "packages/mailbox"
+  },
+  "bugs": "https://github.com/letsrunit/letsrunit/issues",
+  "homepage": "https://github.com/letsrunit/letsrunit#readme",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "../../node_modules/.bin/tsup",
+    "test": "vitest run",
+    "test:cov": "vitest run --coverage",
+    "typecheck": "tsc--noEmit"
+  },
+  "packageManager": "yarn@4.10.3",
+  "dependencies": {
+    "@letsrunit/utils": "workspace:*",
+    "graphql": "^16.12.0",
+    "graphql-request": "^7.4.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.17"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  }
+}

package/src/constants.ts

@@ -0,0 +1,14 @@
+const testValue = (value: string) => process.env.NODE_ENV === 'test' ? value : null;
+
+export const TESTMAIL_DOMAIN = 'inbox.testmail.app';
+export const TESTMAIL_API_KEY = process.env.TESTMAIL_API_KEY || testValue('test_key');
+export const TESTMAIL_NAMESPACE = process.env.TESTMAIL_NAMESPACE || testValue('test_ns');
+export const TESTMAIL_GRAPHQL_URL = 'https://api.testmail.app/api/graphql';
+
+export const MAILHOG_BASE_URL = process.env.MAILHOG_BASE_URL || 'http://localhost:8025';
+
+export const MAILPIT_BASE_URL = process.env.MAILPIT_BASE_URL || 'http://localhost:8025';
+
+export const MAILBOX_SERVICE = process.env.MAILBOX_SERVICE || 'mailpit';
+export const MAILBOX_DOMAIN = process.env.MAILBOX_DOMAIN
+  || (MAILBOX_SERVICE === 'testmail' ? TESTMAIL_DOMAIN : 'example.com');

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './mailbox';
+export * from './receive';
+export * from './serialize';

package/src/mailbox.ts

@@ -0,0 +1,12 @@
+import type { UUID } from '@letsrunit/utils';
+import { clean, uuidToTag } from '@letsrunit/utils';
+import { MAILBOX_DOMAIN, TESTMAIL_DOMAIN, TESTMAIL_NAMESPACE } from './constants';
+
+export function getMailbox(seed: UUID, name?: string, domain?: string) {
+  domain ??= MAILBOX_DOMAIN;
+
+  const ns = domain === TESTMAIL_DOMAIN ? TESTMAIL_NAMESPACE : null;
+  const local = clean([ns, uuidToTag(seed), name]).join('.');
+
+  return `${local}@${domain}`;
+}

package/src/mailhog/receive.ts

@@ -0,0 +1,101 @@
+import { sleep } from '@letsrunit/utils';
+import { MAILHOG_BASE_URL } from '../constants';
+import type { Email, ReceiveOptions } from '../types';
+
+async function fetchOnce(emailAddress: string, signal: AbortSignal): Promise<any[]> {
+  const url = `${MAILHOG_BASE_URL.replace(/\/$/, '')}/api/v2/search?kind=to&query=${encodeURIComponent(emailAddress)}`;
+  const res = await fetch(url, { signal });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Failed to fetch response from mailhog: ${res.status} ${text}`);
+  }
+  const body = await res.json();
+  return body?.items ?? body?.Items ?? [];
+}
+
+function getHeaderValue(headers: Record<string, string[] | string> | undefined, name: string): string | undefined {
+  if (!headers) return undefined;
+  const v = headers[name] ?? headers[name.toLowerCase() as keyof typeof headers];
+  if (!v) return undefined;
+  return Array.isArray(v) ? v[0] : v;
+}
+
+function mapItemsToEmails(items: any[]): Email[] {
+  return items.map((item) => {
+    // timestamp
+    const created = item.Created || item.created || item.Time;
+    const timestamp = typeof created === 'number' ? created : Date.parse(created);
+
+    // headers
+    const headers: Record<string, string[] | string> | undefined = item.Content?.Headers || item.Content?.headers;
+
+    // bodies from parts
+    const parts: any[] = item.MIME?.Parts || item.MIME?.parts || [];
+    const htmlPart = parts.find((p) => (p.ContentType || p.contentType || '').startsWith('text/html'));
+    const textPart = parts.find((p) => (p.ContentType || p.contentType || '').startsWith('text/plain'));
+
+    const html = htmlPart?.Body || htmlPart?.body || undefined;
+    const text = (textPart?.Body || textPart?.body || item.Content?.Body || item.Content?.body || '').toString();
+
+    // basic fields
+    const subject = getHeaderValue(headers, 'Subject') || '';
+    const from = getHeaderValue(headers, 'From') || '';
+    const to = getHeaderValue(headers, 'To') || '';
+    const cc = getHeaderValue(headers, 'Cc') || undefined;
+
+    // attachments
+    const attachments = parts
+      .filter((p) => {
+        const ct = (p.ContentType || p.contentType || '').toString();
+        const filename = p.FileName || p.Filename || p.filename;
+        if (filename) return true;
+        return ct && !ct.startsWith('text/');
+      })
+      .map((p) => ({
+        filename: p.FileName || p.Filename || p.filename || 'attachment',
+        contentType: p.ContentType || p.contentType || 'application/octet-stream',
+      }));
+
+    const email: Email = {
+      timestamp,
+      from,
+      to,
+      cc,
+      subject,
+      html,
+      text,
+      attachments: attachments.length ? attachments : undefined,
+    };
+
+    return email;
+  });
+}
+
+export async function receiveMail(emailAddress: string, options: ReceiveOptions = {}): Promise<Email[]> {
+  const deadline = Date.now() + (options.timeout || (options.wait ? 120_000 : 5_000));
+  const pollInterval = 1_000;
+  const signal: AbortSignal = options.signal ?? AbortSignal.timeout(Math.max(0, deadline - Date.now()));
+
+  while (!signal.aborted) {
+    try {
+      const items = await fetchOnce(emailAddress, signal);
+      let emails = mapItemsToEmails(items);
+
+      if (options.after) emails = emails.filter((e) => e.timestamp > options.after!);
+      if (options.subject) emails = emails.filter((e) => e.subject.includes(options.subject!));
+      if (options.limit && options.limit > 0) emails = emails.slice(0, options.limit);
+
+      if (emails.length > 0) {
+        return emails;
+      }
+    } catch (e) {
+      // bubble up fetch errors except when aborted due to signal; then just end loop
+      if (!signal.aborted) throw e;
+    }
+
+    if (!options.wait) break;
+    await sleep(pollInterval, { signal });
+  }
+
+  return [];
+}

package/src/mailpit/receive.ts

@@ -0,0 +1,119 @@
+import { sleep } from '@letsrunit/utils';
+import { MAILPIT_BASE_URL } from '../constants';
+import type { Email, ReceiveOptions } from '../types';
+
+function buildSearchQuery(emailAddress: string, options: ReceiveOptions): string {
+  const terms: string[] = [`to:${emailAddress}`];
+  if (options.subject) {
+    const escaped = options.subject.replace(/"/g, '\\"');
+    terms.push(`subject:"${escaped}"`);
+  }
+  if (options.after) {
+    const iso = new Date(options.after).toISOString();
+    terms.push(`after:${iso}`);
+  }
+  return terms.join(' ');
+}
+
+async function search(emailAddress: string, options: ReceiveOptions, signal: AbortSignal): Promise<any[]> {
+  const base = MAILPIT_BASE_URL.replace(/\/$/, '');
+  const query = buildSearchQuery(emailAddress, options);
+  const limitParam = options.limit && options.limit > 0 ? `&limit=${encodeURIComponent(String(options.limit))}` : '';
+  const url = `${base}/api/v1/search?query=${encodeURIComponent(query)}${limitParam}`;
+  const res = await fetch(url, { signal });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Failed to fetch response from mailpit: ${res.status} ${text}`);
+  }
+  const body = await res.json();
+  return body?.messages ?? [];
+}
+
+async function fetchFullMessage(
+  id: string,
+  signal: AbortSignal,
+): Promise<{
+  Html?: string;
+  Text?: string;
+  Attachments?: any[];
+  Created?: string | number;
+  Subject?: string;
+  From?: any;
+  To?: any[];
+  Cc?: any[];
+} | null> {
+  const base = MAILPIT_BASE_URL.replace(/\/$/, '');
+  const url = `${base}/api/v1/message/${encodeURIComponent(id)}`;
+  const res = await fetch(url, { signal });
+  if (!res.ok) return null;
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+function pickAddress(obj: any): string {
+  if (!obj) return '';
+  if (typeof obj === 'string') return obj;
+  const name = obj.Name;
+  const addr = obj.Address || '';
+  return name ? `${name} <${addr}>` : addr;
+}
+
+function joinAddresses(list?: any[]): string {
+  if (!Array.isArray(list) || list.length === 0) return '';
+  return list.map(pickAddress).filter(Boolean).join(', ');
+}
+
+function mapMessageToEmail(m: any): Email {
+  const attachments = Array.isArray(m.Attachments)
+    ? m.Attachments.map((a: any) => ({
+        filename: a.FileName,
+        contentType: a.ContentType,
+      }))
+    : undefined;
+
+  return {
+    timestamp: Date.parse(m.Created ?? m.Date),
+    from: pickAddress(m.From),
+    to: joinAddresses(m.To),
+    cc: m.Cc && joinAddresses(m.Cc),
+    subject: m.Subject,
+    html: m.HTML,
+    text: m.Text,
+    attachments,
+  };
+}
+
+async function fetchFullEmails(messages: any[], signal: AbortSignal): Promise<Email[]> {
+  const ids: string[] = messages.map((m: any) => m.ID).filter(Boolean);
+  const details = await Promise.all(ids.map((id) => fetchFullMessage(id, signal)));
+  return details.filter(Boolean).map((d) => mapMessageToEmail(d));
+}
+
+export async function receiveMail(emailAddress: string, options: ReceiveOptions = {}): Promise<Email[]> {
+  const pollInterval = 1_000;
+  const timeout = options.timeout || (options.wait ? 60_000 : 5_000);
+  const signal: AbortSignal = options.signal ?? AbortSignal.timeout(timeout);
+
+  while (!signal.aborted) {
+    try {
+      const messages = await search(emailAddress, options, signal);
+      const emails = options.full
+        ? await fetchFullEmails(messages, signal)
+        : messages.map((m) => mapMessageToEmail(m));
+
+      if (emails.length > 0) {
+        return emails;
+      }
+    } catch (e) {
+      if (!signal.aborted) throw e;
+    }
+
+    if (!options.wait) break;
+    await sleep(pollInterval, { signal });
+  }
+
+  return [];
+}

package/src/receive.ts

@@ -0,0 +1,18 @@
+import { MAILBOX_SERVICE } from './constants';
+import { receiveMail as mailhogReceive } from './mailhog/receive';
+import { receiveMail as mailpitReceive } from './mailpit/receive';
+import { receiveMail as testmailReceive } from './testmail/receive';
+import type { Email, ReceiveOptions } from './types';
+
+export async function receiveMail(emailAddress: string, options: ReceiveOptions = {}): Promise<Email[]> {
+  switch (MAILBOX_SERVICE) {
+    case 'testmail':
+      return await testmailReceive(emailAddress, options);
+    case 'mailhog':
+      return await mailhogReceive(emailAddress, options);
+    case 'mailpit':
+      return await mailpitReceive(emailAddress, options);
+    default:
+      throw new Error(`Unsupported mailbox service ${MAILBOX_SERVICE}`);
+  }
+}

package/src/serialize.ts

@@ -0,0 +1,259 @@
+import type { Email } from './types';
+
+export function toEml(email: Email): string {
+  const lines: string[] = [];
+  const crlf = (s: string) => s.replace(/\n/g, '\r\n');
+
+  const date = new Date(email.timestamp);
+  // Use RFC 2822 format via toUTCString
+  lines.push(`Date: ${date.toUTCString()}`);
+  lines.push(`From: ${email.from}`);
+  lines.push(`To: ${email.to}`);
+  if (email.cc) lines.push(`Cc: ${email.cc}`);
+  lines.push(`Subject: ${email.subject}`);
+  lines.push('MIME-Version: 1.0');
+
+  const hasText = typeof email.text === 'string' && email.text.length > 0;
+  const hasHtml = typeof email.html === 'string' && email.html.length > 0;
+  const hasAttachments = Array.isArray(email.attachments) && email.attachments.length > 0;
+
+  const boundary = `===============lr_${Math.random().toString(36).slice(2)}_${Date.now()}==`;
+  const altBoundary = `===============lr_alt_${Math.random().toString(36).slice(2)}_${Date.now()}==`;
+
+  function pushTextPart() {
+    lines.push(`Content-Type: text/plain; charset=utf-8`);
+    lines.push('Content-Transfer-Encoding: 7bit');
+    lines.push('');
+    lines.push(crlf(hasText ? email.text! : ''));
+  }
+
+  function pushHtmlPart() {
+    lines.push(`Content-Type: text/html; charset=utf-8`);
+    lines.push('Content-Transfer-Encoding: 7bit');
+    lines.push('');
+    lines.push(crlf(hasHtml ? email.html! : ''));
+  }
+
+  // Build structure
+  if (hasAttachments) {
+    // multipart/mixed enclosing either single/alternative plus attachments
+    lines.push(`Content-Type: multipart/mixed; boundary="${boundary}"`);
+    lines.push('');
+    lines.push(`--${boundary}`);
+    if (hasText && hasHtml) {
+      // nested multipart/alternative
+      lines.push(`Content-Type: multipart/alternative; boundary="${altBoundary}"`);
+      lines.push('');
+      // text part
+      lines.push(`--${altBoundary}`);
+      pushTextPart();
+      // html part
+      lines.push(`--${altBoundary}`);
+      pushHtmlPart();
+      // end alternative
+      lines.push(`--${altBoundary}--`);
+    } else if (hasText) {
+      pushTextPart();
+    } else {
+      pushHtmlPart();
+    }
+
+    // attachments (metadata only; empty bodies)
+    for (const a of email.attachments || []) {
+      lines.push(`--${boundary}`);
+      const disp = `attachment; filename="${a.filename}"`;
+      lines.push(`Content-Type: ${a.contentType}; name="${a.filename}"`);
+      lines.push(`Content-Disposition: ${disp}`);
+      lines.push('Content-Transfer-Encoding: base64');
+      lines.push('');
+      // No content stored in type, emit empty body to keep structure valid
+      lines.push('');
+    }
+    lines.push(`--${boundary}--`);
+  } else if (hasText && hasHtml) {
+    // multipart/alternative
+    lines.push(`Content-Type: multipart/alternative; boundary="${altBoundary}"`);
+    lines.push('');
+    lines.push(`--${altBoundary}`);
+    pushTextPart();
+    lines.push(`--${altBoundary}`);
+    pushHtmlPart();
+    lines.push(`--${altBoundary}--`);
+  } else if (hasText) {
+    pushTextPart();
+  } else {
+    pushHtmlPart();
+  }
+
+  // Ensure CRLF endings
+  return lines.join('\r\n');
+}
+
+export function fromEml(contents: string): Email {
+  // Normalize line endings to \n for parsing
+  const raw = contents.replace(/\r\n/g, '\n');
+  const [rawHeader, ...rest] = raw.split(/\n\n/);
+  const headerLines = rawHeader.split('\n');
+  // Handle folded headers (lines starting with space or tab)
+  const unfolded: string[] = [];
+  for (const line of headerLines) {
+    if (/^[ \t]/.test(line) && unfolded.length > 0) {
+      unfolded[unfolded.length - 1] += line.replace(/^\s+/, ' ');
+    } else {
+      unfolded.push(line);
+    }
+  }
+  const headers = new Map<string, string>();
+  for (const l of unfolded) {
+    const idx = l.indexOf(':');
+    if (idx === -1) continue;
+    const key = l.slice(0, idx).trim().toLowerCase();
+    const val = l.slice(idx + 1).trim();
+    headers.set(key, val);
+  }
+  const body = rest.join('\n\n');
+
+  const email: Email = {
+    timestamp: Date.parse(headers.get('date') || new Date().toUTCString()),
+    from: headers.get('from') || '',
+    to: headers.get('to') || '',
+    cc: headers.get('cc') || undefined,
+    subject: headers.get('subject') || '',
+  } as Email;
+
+  // Parse body depending on content-type
+  const ct = (headers.get('content-type') || '').toLowerCase();
+
+  function parseParts(contentType: string, data: string): { text?: string; html?: string; attachments?: { filename: string; contentType: string }[] } {
+    const result: { text?: string; html?: string; attachments?: { filename: string; contentType: string }[] } = { attachments: [] };
+    if (contentType.startsWith('multipart/')) {
+      const m = contentType.match(/boundary="?([^";]+)"?/);
+      const boundary = m ? m[1] : '';
+      if (!boundary) return result;
+      // Line-oriented multipart parsing
+      const lines = data.split('\n');
+      let i = 0;
+      while (i < lines.length) {
+        const line = lines[i];
+        if (line === `--${boundary}`) {
+          // Parse headers
+          i++;
+          const pHeaders = new Map<string, string>();
+          const headAccum: string[] = [];
+          for (; i < lines.length; i++) {
+            const l = lines[i];
+            if (l === '') break;
+            headAccum.push(l);
+          }
+          // skip empty line
+          if (i < lines.length && lines[i] === '') i++;
+          // unfold and map headers
+          const unfolded: string[] = [];
+          for (const h of headAccum) {
+            if ((h.startsWith(' ') || h.startsWith('\t')) && unfolded.length) {
+              unfolded[unfolded.length - 1] += h.replace(/^\s+/, ' ');
+            } else {
+              unfolded.push(h);
+            }
+          }
+          for (const h of unfolded) {
+            const idx = h.indexOf(':');
+            if (idx !== -1) pHeaders.set(h.slice(0, idx).trim().toLowerCase(), h.slice(idx + 1).trim());
+          }
+          // Collect body until next boundary marker
+          const bodyLines: string[] = [];
+          for (; i < lines.length; i++) {
+            const l = lines[i];
+            if (l === `--${boundary}` || l === `--${boundary}--`) break;
+            bodyLines.push(l);
+          }
+          const pBody = bodyLines.join('\n');
+
+          const pct = (pHeaders.get('content-type') || '').toLowerCase();
+          const disp = (pHeaders.get('content-disposition') || '').toLowerCase();
+          if (pct.startsWith('multipart/')) {
+            const nested = parseParts(pct, pBody);
+            if (nested.text && !result.text) result.text = nested.text;
+            if (nested.html && !result.html) result.html = nested.html;
+            if (nested.attachments && nested.attachments.length) result.attachments!.push(...nested.attachments);
+          } else if (pct.startsWith('text/plain')) {
+            result.text = pBody;
+          } else if (pct.startsWith('text/html')) {
+            result.html = pBody;
+          } else if (disp.startsWith('attachment') || disp.includes('filename=')) {
+            let filename = '';
+            const fnm = disp.match(/filename="?([^";]+)"?/);
+            if (fnm) filename = fnm[1];
+            if (!filename) {
+              const nm = pct.match(/name="?([^";]+)"?/);
+              if (nm) filename = nm[1];
+            }
+            const contentTypeHeader = pHeaders.get('content-type') || 'application/octet-stream';
+            result.attachments!.push({ filename, contentType: contentTypeHeader.split(';')[0] });
+          }
+
+          // If current line is closing boundary, advance past it and stop
+          if (i < lines.length && lines[i] === `--${boundary}--`) {
+            break;
+          }
+          // continue to next line (which is next boundary or end)
+        } else if (line === `--${boundary}--`) {
+          break;
+        } else {
+          i++;
+        }
+      }
+      // Fallback pass: ensure we didn't miss any attachment headers
+      const segs = (`\n${data}`).split(`\n--${boundary}`);
+      const have = new Set(result.attachments!.map((a) => `${a.filename}|${a.contentType}`));
+      for (let seg of segs) {
+        seg = seg.replace(/^\n/, '');
+        if (!seg || seg.startsWith('--')) continue;
+        const [head] = seg.split(/\n\n/);
+        const disp = (head.match(/(^|\n)content-disposition:\s*([^\n]+)/i)?.[2] || '').toLowerCase();
+        if (!disp.includes('attachment')) continue;
+        let filename = '';
+        const fnm = disp.match(/filename="?([^";]+)"?/);
+        if (fnm) filename = fnm[1];
+        const ct = (head.match(/(^|\n)content-type:\s*([^\n]+)/i)?.[2] || 'application/octet-stream').split(';')[0];
+        const key = `${filename}|${ct}`;
+        if (!have.has(key)) {
+          have.add(key);
+          result.attachments!.push({ filename, contentType: ct });
+        }
+      }
+      // Order attachments by first appearance in the original data
+      if (result.attachments && result.attachments.length > 1) {
+        const positions = new Map<string, number>();
+        for (const a of result.attachments) {
+          const key = `${a.filename}|${a.contentType}`;
+          if (!positions.has(key)) {
+            const re = new RegExp(`filename=\"?${a.filename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\"?`, 'i');
+            const idx = data.search(re);
+            positions.set(key, idx === -1 ? Number.MAX_SAFE_INTEGER : idx);
+          }
+        }
+        result.attachments.sort((a, b) => {
+          const ka = `${a.filename}|${a.contentType}`;
+          const kb = `${b.filename}|${b.contentType}`;
+          return (positions.get(ka) ?? 0) - (positions.get(kb) ?? 0);
+        });
+      }
+      return result;
+    }
+    // single part
+    if (contentType.startsWith('text/plain')) {
+      result.text = data;
+    } else if (contentType.startsWith('text/html')) {
+      result.html = data;
+    }
+    return result;
+  }
+
+  const parsed = parseParts(ct, body);
+  if (parsed.text !== undefined) email.text = parsed.text;
+  if (parsed.html !== undefined) email.html = parsed.html;
+  if (parsed.attachments && parsed.attachments.length) email.attachments = parsed.attachments;
+
+  return email;
+}

package/src/testmail/receive.ts

@@ -0,0 +1,60 @@
+import { clean } from '@letsrunit/utils';
+import { GraphQLClient } from 'graphql-request';
+import { TESTMAIL_API_KEY, TESTMAIL_GRAPHQL_URL } from '../constants';
+import type { Email, ReceiveOptions } from '../types';
+
+export async function receiveMail(emailAddress: string, options: ReceiveOptions = {}): Promise<Email[]> {
+  if (!TESTMAIL_API_KEY) throw new Error('TESTMAIL_API_KEY environment var not set');
+
+  const match = emailAddress.match(/^(?<namespace>[^.@]+)\.(?<tag>[^@]+)@/);
+  if (!match) throw new Error('Email address is not a valid testmail address');
+
+  const namespace = match.groups!.namespace;
+  const tag = match.groups!.tag;
+
+  const signal = options.signal ?? AbortSignal.timeout(options.timeout || (options.wait ? 120_000 : 5000));
+
+  const client = new GraphQLClient(TESTMAIL_GRAPHQL_URL, {
+    headers: { apikey: TESTMAIL_API_KEY },
+    fetch: (input, init = {}) => {
+      return fetch(input as RequestInfo, { ...init, signal });
+    },
+  });
+
+  const fields = ['timestamp', 'from', 'to', 'cc', 'subject'];
+  if (options.full) fields.push('html', 'text', 'attachments { filename contentType }');
+
+  const query = `
+    query Inbox($namespace: String!, $tag: String!, $timestampFrom: Long, $subject: String, $limit: Int) {
+      inbox(
+        namespace: $namespace
+        tag: $tag
+        ${options.wait ? 'livequery: true' : ''}
+        ${options.after ? 'timestamp_from: $timestampFrom' : ''}
+        ${options.subject ? `advanced_filters: [{ field: subject, match: exact, action: include, value: $subject }]` : ''}
+        ${options.limit ? 'limit: $limit' : ''}
+        advanced_sorts: [{ field: timestamp, order: desc }]
+      ) {
+        emails {
+          ${fields.join('\n          ')}
+        }
+      }
+    }
+  `;
+
+  const variables: Record<string, any> = clean({
+    namespace,
+    tag,
+    timestampFrom: options.after,
+    subject: options.subject,
+    limit: options.limit,
+  });
+
+  try {
+    const data: any = await client.request(query, variables);
+    return data?.inbox?.emails || [];
+  } catch (err: any) {
+    const message = err?.response?.errors?.[0]?.message || err?.message || 'Unknown error';
+    throw new Error(`Failed to fetch response from testmail: ${message}`);
+  }
+}

package/src/types.ts

@@ -0,0 +1,25 @@
+export interface ReceiveOptions {
+  wait?: boolean;
+  timeout?: number;
+  signal?: AbortSignal;
+  after?: number;
+  subject?: string;
+  limit?: number;
+  full?: boolean;
+}
+
+export interface Email {
+  timestamp: number;
+  from: string;
+  to: string;
+  cc?: string;
+  subject: string;
+  html?: string;
+  text?: string;
+  attachments?: Attachment[];
+}
+
+export interface Attachment {
+  filename: string;
+  contentType: string;
+}