proxymail-qa 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -101,6 +101,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;
@@ -137,6 +163,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;
@@ -107,6 +120,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.2.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)",