proxymail-qa 0.3.0 → 0.5.0

package/README.md

@@ -100,6 +100,18 @@ const { delivered, invalid } = await qa.variants(address);
 
 // After the app changes the test account's password, keep the saved one in step.
 await qa.setPassword(address, { password: 'the-new-test-password' });
+
+// Check the email that arrived: SPF, DKIM, DMARC, local or http links, where
+// its link goes, a stated expiry and more. Verdicts only, never its content.
+const result = await qa.checkEmail(address, { type: 'link', expectHost: 'staging.example.com' });
+expect(result.failed).toEqual([]);
+
+// A run: this client's calls add what they saw, for a report on the pull
+// request. In GitHub Actions, the Proxy Mail QA action does this for you and
+// the client picks the run up from PROXYMAIL_QA_RUN.
+await qa.startRun({ name: 'Sign-up tests' });
+// …the tests…
+await qa.finishRun({ failed: testsFailed });
 ```
 
 When a wait comes back empty, the error says why as far as Proxy Mail QA can

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export interface ClientOptions {
     apiKey?: string;
     baseUrl?: string;
     fetch?: typeof fetch;
+    run?: string | null;
 }
 export interface Persona {
     first_name: string | null;
@@ -132,11 +133,67 @@ export interface CountOptions {
     subtype?: CountSubtype | CountSubtype[];
 }
 export type CountSubtype = 'otp' | 'coupon' | 'verify' | 'magic_signin' | 'invite' | 'reset' | 'other' | 'any';
+export type CheckId = 'spf' | 'dkim' | 'dmarc' | 'local_links' | 'plain_http' | 'expected_host' | 'expiry' | 'plain_text' | 'size' | 'images_only';
+export interface EmailCheck {
+    check: CheckId;
+    status: 'pass' | 'fail' | 'warn' | 'skip';
+    detail: string;
+}
+export interface EmailChecks {
+    address: string;
+    email: {
+        id: string;
+        received_at: string;
+        service: string | null;
+        service_domain: string | null;
+        type: 'code' | 'link' | null;
+        subtype: string | null;
+    };
+    passed: boolean;
+    failed: CheckId[];
+    warnings: CheckId[];
+    checks: EmailCheck[];
+}
+export interface CheckOptions extends CountOptions {
+    emailId?: string;
+    expectHost?: string;
+}
 export interface NoEmail {
     address: string;
     since: string;
     until: string;
 }
+export interface RunInput {
+    name?: string;
+    source?: 'ci' | 'agent' | 'api';
+    meta?: {
+        repository?: string;
+        branch?: string;
+        commit?: string;
+        pull_request?: number;
+        workflow?: string;
+        job_url?: string;
+        agent?: string;
+    };
+}
+export interface RunEvent {
+    at: string;
+    kind: 'address' | 'email' | 'missing' | 'none' | 'count' | 'checks' | 'note';
+    address: string | null;
+    failed: boolean;
+    detail: Record<string, unknown>;
+}
+export interface Run {
+    id: string;
+    name: string;
+    source: 'ci' | 'agent' | 'api';
+    status: 'running' | 'passed' | 'failed';
+    meta: NonNullable<RunInput['meta']>;
+    started_at: string;
+    finished_at: string | null;
+    url: string;
+    events?: RunEvent[];
+}
 export declare class ProxyMailQAError extends Error {
     readonly status: number;
     readonly code: string;
@@ -149,6 +206,7 @@ export declare class ProxyMailQA {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly fetcher;
+    run: string | null;
     constructor(options?: ClientOptions);
     private request;
     project(): Promise<Record<string, unknown>>;
@@ -171,6 +229,7 @@ export declare class ProxyMailQA {
         limit?: number;
     }): Promise<Record<string, unknown>[]>;
     countEmails(address: string, options?: CountOptions): Promise<EmailCount>;
+    checkEmail(address: string, options?: CheckOptions): Promise<EmailChecks>;
     expectNoEmail(address: string, options?: CountOptions & {
         timeout?: number;
     }): Promise<NoEmail>;
@@ -191,5 +250,19 @@ export declare class ProxyMailQA {
         label: string;
         secret: string;
     }>;
+    startRun(input?: RunInput): Promise<Run>;
+    getRun(id?: string): Promise<Run>;
+    runReport(id?: string): Promise<string>;
+    listRuns(limit?: number): Promise<Run[]>;
+    addRunNote(text: string, options?: {
+        failed?: boolean;
+        address?: string;
+        run?: string;
+    }): Promise<void>;
+    finishRun(options?: {
+        failed?: boolean;
+        run?: string;
+    }): Promise<Run>;
+    private requireRun;
     private wait;
 }

package/dist/index.js

@@ -40,23 +40,34 @@ export class ProxyMailQA {
     apiKey;
     baseUrl;
     fetcher;
+    // The run this client's calls add to, if any.
+    run;
     constructor(options = {}) {
-        const fromEnv = globalThis.process?.env?.PROXYMAIL_QA_API_KEY;
-        const apiKey = options.apiKey ?? fromEnv;
+        const env = globalThis.process?.env;
+        const apiKey = options.apiKey ?? env?.PROXYMAIL_QA_API_KEY;
         if (!apiKey)
             throw new Error('Pass apiKey or set PROXYMAIL_QA_API_KEY. Create a key in Project settings → API keys.');
         this.apiKey = apiKey;
         this.baseUrl = (options.baseUrl ?? 'https://api.proxymail.qa').replace(/\/+$/, '');
         this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.run = options.run === undefined ? env?.PROXYMAIL_QA_RUN?.trim() || null : options.run;
     }
-    async request(method, path, body) {
+    // retry: this call is asked again if nothing arrives, so the run only
+    // records the last try's "nothing arrived".
+    async request(method, path, body, retry = false) {
         const response = await this.fetcher(`${this.baseUrl}/v1${path}`, {
             method,
-            headers: { Authorization: `Bearer ${this.apiKey}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                ...(this.run ? { 'Proxy-Mail-QA-Run': this.run, ...(retry ? { 'Proxy-Mail-QA-Run-Retry': 'true' } : {}) } : {}),
+            },
             body: body === undefined ? undefined : JSON.stringify(body),
         });
         if (response.status === 204)
             return undefined;
+        if ((response.headers.get('Content-Type') ?? '').startsWith('text/markdown') && response.ok)
+            return (await response.text());
         const payload = (await response.json().catch(() => ({})));
         if (!response.ok) {
             throw new ProxyMailQAError(response.status, payload.error ?? 'error', payload.message ?? `Request failed with ${response.status}`, payload.hint, payload.refused, payload.help);
@@ -141,6 +152,18 @@ export class ProxyMailQA {
     countEmails(address, options = {}) {
         return this.request('GET', `/addresses/${encodeURIComponent(address)}/count${countQuery(options)}`);
     }
+    // Checks one email the address received: SPF, DKIM and DMARC, links to
+    // localhost or plain http, where its link goes (expectHost), a stated
+    // expiry, a plain-text part, size and image-only emails. Doesn't wait: wait
+    // for the email first. Throws ProxyMailQAError (404) when none matches.
+    checkEmail(address, options = {}) {
+        const extra = {};
+        if (options.emailId)
+            extra.email_id = options.emailId;
+        if (options.expectHost)
+            extra.expect_host = options.expectHost;
+        return this.request('GET', `/addresses/${encodeURIComponent(address)}/checks${countQuery(options, extra)}`);
+    }
     // Resolves when no matching email arrives within timeout seconds (default
     // 30; longer repeats the request), for checks such as "an unsubscribed user
     // gets nothing". Throws ProxyMailQAError (status 409, code email_arrived)
@@ -152,7 +175,8 @@ export class ProxyMailQA {
         for (;;) {
             const left = Math.max(0, Math.min(MAX_WAIT_SECONDS, Math.ceil((deadline - Date.now()) / 1000)));
             const query = countQuery({ ...options, since }, { timeout: String(left) });
-            const result = await this.request('GET', `/addresses/${encodeURIComponent(address)}/none${query}`);
+            const more = Date.now() + left * 1000 < deadline - 500;
+            const result = await this.request('GET', `/addresses/${encodeURIComponent(address)}/none${query}`, undefined, more);
             // The server's since, so later requests watch from the same moment
             // whatever this machine's clock says.
             since = result.since;
@@ -175,6 +199,46 @@ export class ProxyMailQA {
     savedPassword(address, label = 'password') {
         return this.request('GET', `/addresses/${encodeURIComponent(address)}/password?label=${encodeURIComponent(label)}`);
     }
+    // Starts a run: a CI job or agent session whose calls add what they saw
+    // (addresses, emails and how long after since, codes, a link's site and
+    // path, checks, and emails that never came). This client's later calls add
+    // to it; to add calls from other processes, pass them its id as
+    // PROXYMAIL_QA_RUN. The GitHub Action starts and finishes one for you.
+    async startRun(input = {}) {
+        const run = await this.request('POST', '/runs', input);
+        this.run = run.id;
+        return run;
+    }
+    getRun(id = this.requireRun()) {
+        return this.request('GET', `/runs/${encodeURIComponent(id)}`);
+    }
+    // The report in Markdown, for a pull request comment or a job summary.
+    runReport(id = this.requireRun()) {
+        return this.request('GET', `/runs/${encodeURIComponent(id)}?format=markdown`);
+    }
+    listRuns(limit) {
+        return this.request('GET', `/runs${limit ? `?limit=${limit}` : ''}`).then((r) => r.runs);
+    }
+    // A line of your own in the run, such as a test that failed for a reason
+    // of its own. failed: true fails the run.
+    addRunNote(text, options = {}) {
+        const id = options.run ?? this.requireRun();
+        return this.request('POST', `/runs/${encodeURIComponent(id)}/notes`, { text, failed: options.failed ?? false, address: options.address });
+    }
+    // Passed unless an email was missing, came when none should have, failed
+    // a check, or failed says your tests failed.
+    async finishRun(options = {}) {
+        const id = options.run ?? this.requireRun();
+        const run = await this.request('POST', `/runs/${encodeURIComponent(id)}/finish`, { failed: options.failed ?? false });
+        if (this.run === id)
+            this.run = null;
+        return run;
+    }
+    requireRun() {
+        if (!this.run)
+            throw new Error('No run: call startRun first, or set PROXYMAIL_QA_RUN.');
+        return this.run;
+    }
     async wait(address, kind, options, type = '', app) {
         const total = options.timeout ?? MAX_WAIT_SECONDS;
         const deadline = Date.now() + total * 1000;
@@ -190,8 +254,9 @@ export class ProxyMailQA {
                 query.set('type', type);
             if (app !== undefined)
                 query.set('app', String(app));
+            const more = Date.now() + left * 1000 < deadline - 500;
             try {
-                return await this.request('GET', `/addresses/${encodeURIComponent(address)}/${kind}?${query}`);
+                return await this.request('GET', `/addresses/${encodeURIComponent(address)}/${kind}?${query}`, undefined, more);
             }
             catch (error) {
                 const timedOut = error instanceof ProxyMailQAError && error.status === 404 && TIMED_OUT.test(error.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proxymail-qa",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Disposable test inboxes for Playwright, Cypress and scripts: create an address, then wait for its verification code or link.",
   "license": "MIT",
   "author": "Proxy Mail QA <hello@proxymail.qa> (https://proxymail.qa)",