proxymail-qa 0.1.1 → 0.3.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 });
 

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;
@@ -101,6 +111,32 @@ export interface WaitOptions {
     since?: Date | string;
 }
 export type LinkType = 'verify' | 'magic_signin' | 'invite' | 'reset' | 'any';
+export interface EmailSummary {
+    received_at: string;
+    service: string | null;
+    service_domain: string | null;
+    type: 'code' | 'link' | null;
+    subtype: string | null;
+    email_id: string;
+}
+export interface EmailCount {
+    address: string;
+    since: string | null;
+    count: number;
+    emails: EmailSummary[];
+}
+export interface CountOptions {
+    since?: Date | string;
+    service?: string;
+    type?: 'code' | 'link';
+    subtype?: CountSubtype | CountSubtype[];
+}
+export type CountSubtype = 'otp' | 'coupon' | 'verify' | 'magic_signin' | 'invite' | 'reset' | 'other' | 'any';
+export interface NoEmail {
+    address: string;
+    since: string;
+    until: string;
+}
 export declare class ProxyMailQAError extends Error {
     readonly status: number;
     readonly code: string;
@@ -120,10 +156,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>;
@@ -137,6 +170,10 @@ export declare class ProxyMailQA {
         includeHtml?: boolean;
         limit?: number;
     }): Promise<Record<string, unknown>[]>;
+    countEmails(address: string, options?: CountOptions): Promise<EmailCount>;
+    expectNoEmail(address: string, options?: CountOptions & {
+        timeout?: number;
+    }): Promise<NoEmail>;
     checkDelivery(address: string): Promise<DeliveryStatus>;
     variants(address: string): Promise<Variants>;
     setPassword(address: string, options: {

package/dist/index.js

@@ -22,6 +22,19 @@ export class ProxyMailQAError extends Error {
     }
 }
 const TIMED_OUT = /^No (code|link) arrived/;
+function countQuery(options, extra = {}) {
+    const query = new URLSearchParams(extra);
+    if (options.since !== undefined)
+        query.set('since', new Date(options.since).toISOString());
+    if (options.service)
+        query.set('service', options.service);
+    if (options.type)
+        query.set('type', options.type);
+    const subtype = [options.subtype ?? []].flat().join(',');
+    if (subtype)
+        query.set('subtype', subtype);
+    return query.size ? `?${query}` : '';
+}
 const MAX_WAIT_SECONDS = 30;
 export class ProxyMailQA {
     apiKey;
@@ -66,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) {
@@ -107,6 +134,32 @@ export class ProxyMailQA {
             query.set('limit', String(options.limit));
         return this.request('GET', `/addresses/${encodeURIComponent(address)}/messages${query.size ? `?${query}` : ''}`);
     }
+    // How many emails reached the address (since a time, from a service, with a
+    // code or link), each summarised without its content. Doesn't wait: count
+    // after the wait for the first email returns, so a duplicate has had time
+    // to arrive. Without since, every email the address has received.
+    countEmails(address, options = {}) {
+        return this.request('GET', `/addresses/${encodeURIComponent(address)}/count${countQuery(options)}`);
+    }
+    // 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)
+    // as soon as one does. Pass since as the time of the action, so an email
+    // that came before the call still counts; without it, from now.
+    async expectNoEmail(address, options = {}) {
+        const deadline = Date.now() + (options.timeout ?? MAX_WAIT_SECONDS) * 1000;
+        let since = options.since;
+        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}`);
+            // The server's since, so later requests watch from the same moment
+            // whatever this machine's clock says.
+            since = result.since;
+            if (Date.now() >= deadline - 500)
+                return { address: result.address, since: result.since, until: result.until };
+        }
+    }
     // What reached the address and what was refused, without waiting: for when
     // a wait comes back empty.
     checkDelivery(address) {

package/package.json

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