proxymail-qa 0.2.0 → 0.4.0

package/README.md

@@ -86,6 +86,9 @@ cy.task('createAddress').then(({ address }) => {
 // A persona with a date of birth for an age band, and a country.
 await qa.createAddress({ persona: true, age: 'under13', country: 'GB' });
 
+// Find a test account made earlier: an under-18 in GB with a saved password.
+const [teen] = await qa.listAddresses({ tags: ['age-gate'], country: 'GB', maxAge: 17, hasPassword: true });
+
 // The link that opens a mobile app (myapp://…) when the email also has a web one.
 const { value: appLink } = await qa.waitForLink(address, { app: true });
 
@@ -97,6 +100,11 @@ 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([]);
 ```
 
 When a wait comes back empty, the error says why as far as Proxy Mail QA can

package/dist/index.d.ts

@@ -57,6 +57,16 @@ export interface CreateAddressInput {
     dateOfBirth?: string;
     country?: string;
 }
+export interface ListAddressesOptions {
+    limit?: number;
+    before?: string;
+    tags?: string[];
+    country?: string;
+    minAge?: number;
+    maxAge?: number;
+    hasPassword?: boolean;
+    search?: string;
+}
 export interface AddressPatch {
     label?: string | null;
     notes?: string | null;
@@ -122,6 +132,31 @@ 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;
@@ -146,10 +181,7 @@ export declare class ProxyMailQA {
         password: true;
     }): Promise<CreatedAddressWithPassword>;
     createAddress(input?: CreateAddressInput): Promise<CreatedAddress>;
-    listAddresses(options?: {
-        limit?: number;
-        before?: string;
-    }): Promise<Address[]>;
+    listAddresses(options?: ListAddressesOptions): Promise<Address[]>;
     getAddress(address: string): Promise<Address>;
     updateAddress(address: string, patch: AddressPatch): Promise<Address>;
     deleteAddress(address: string): Promise<void>;
@@ -164,6 +196,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>;

package/dist/index.js

@@ -79,12 +79,26 @@ export class ProxyMailQA {
             country: input.country,
         });
     }
+    // Newest first. With filters, finds test accounts made earlier, such as
+    // an under-18 in GB with a saved password: every filter given must match.
     listAddresses(options = {}) {
         const query = new URLSearchParams();
         if (options.limit)
             query.set('limit', String(options.limit));
         if (options.before)
             query.set('before', options.before);
+        for (const tag of options.tags ?? [])
+            query.append('tag', tag);
+        if (options.country)
+            query.set('country', options.country);
+        if (options.minAge !== undefined)
+            query.set('min_age', String(options.minAge));
+        if (options.maxAge !== undefined)
+            query.set('max_age', String(options.maxAge));
+        if (options.hasPassword !== undefined)
+            query.set('has_password', String(options.hasPassword));
+        if (options.search)
+            query.set('search', options.search);
         return this.request('GET', `/addresses${query.size ? `?${query}` : ''}`);
     }
     getAddress(address) {
@@ -127,6 +141,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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proxymail-qa",
-  "version": "0.2.0",
+  "version": "0.4.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)",