proxymail-qa 0.1.0 → 0.2.0

package/README.md

@@ -19,6 +19,9 @@ const { value: link } = await qa.waitForLink(address, { type: 'reset', timeout:
 await qa.deleteAddress(address);
 ```
 
+With `password: true` the result's `password` is typed as a `string` (pass the
+options inline, or `as const`, so TypeScript sees `true`).
+
 Waits return the code or link on its own, with the sending service and its
 expiry, never the email's text. They throw `ProxyMailQAError` (status 404) when
 nothing arrives in time.
@@ -104,6 +107,12 @@ at any time. Retrying won't help until the app can email any address.
 Mobile apps (XCUITest, Espresso, Maestro, Flutter, Detox and Appium):
 https://proxymail.qa/docs/mobile
 
+## Source
+
+https://github.com/aaquib90/proxymail-qa-js. Releases are published to npm from
+GitHub Actions with provenance, so npm shows which commit and workflow built
+each version.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -26,6 +26,15 @@ export interface Address {
 export interface CreatedAddress extends Address {
     password?: string;
 }
+export interface CreatedAddressWithPassword extends CreatedAddress {
+    password: string;
+}
+export interface SavedPassword {
+    address: string;
+    label: string;
+    saved: boolean;
+    password?: string;
+}
 export interface Match {
     address: string;
     type: 'code' | 'link';
@@ -92,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;
@@ -107,6 +142,9 @@ export declare class ProxyMailQA {
     constructor(options?: ClientOptions);
     private request;
     project(): Promise<Record<string, unknown>>;
+    createAddress(input: CreateAddressInput & {
+        password: true;
+    }): Promise<CreatedAddressWithPassword>;
     createAddress(input?: CreateAddressInput): Promise<CreatedAddress>;
     listAddresses(options?: {
         limit?: number;
@@ -125,16 +163,21 @@ 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: {
+        password: string;
+        label?: string;
+    }): Promise<SavedPassword>;
     setPassword(address: string, options?: {
-        password?: string;
+        password?: undefined;
         label?: string;
-    }): Promise<{
-        address: string;
-        label: string;
-        saved: boolean;
-        password?: string;
+    }): Promise<SavedPassword & {
+        password: string;
     }>;
     savedPassword(address: string, label?: string): Promise<{
         address: string;

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) {
@@ -115,9 +154,6 @@ export class ProxyMailQA {
     variants(address) {
         return this.request('GET', `/addresses/${encodeURIComponent(address)}/variants`);
     }
-    // Saves the password the test account uses now, after the app under test
-    // changed or reset it. Without one, a strong password is generated and
-    // returned this once.
     setPassword(address, options = {}) {
         return this.request('PUT', `/addresses/${encodeURIComponent(address)}/password`, { password: options.password, label: options.label });
     }

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "proxymail-qa",
-  "version": "0.1.0",
+  "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)",
-  "homepage": "https://proxymail.qa/docs/api",
+  "homepage": "https://proxymail.qa/docs/node",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aaquib90/proxymail-qa-js.git"
+  },
   "bugs": {
+    "url": "https://github.com/aaquib90/proxymail-qa-js/issues",
     "email": "hello@proxymail.qa"
   },
   "keywords": [
@@ -39,9 +44,10 @@
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "pnpm build && pnpm test"
+    "prepublishOnly": "npm run build && npm test"
   },
   "devDependencies": {
+    "typescript": "^5.6.0",
     "vitest": "^5.0.3"
   }
 }