proxymail-qa 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sidequest Explorers Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# proxymail-qa
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Disposable test inboxes for Playwright, Cypress and scripts. Create an address,
+sign up with it in the app you're testing, and get the verification code or
+link from the email in one call that waits for it.
+
+Get an API key in [app.proxymail.qa](https://app.proxymail.qa) → Project
+settings → API keys (the Free plan includes it), and set it as
+`PROXYMAIL_QA_API_KEY`. Full guide: https://proxymail.qa/docs/api
+
+```ts
+import { ProxyMailQA } from 'proxymail-qa';
+
+const qa = new ProxyMailQA(); // reads PROXYMAIL_QA_API_KEY
+const { address, persona, password } = await qa.createAddress({ persona: true, password: true, label: 'Sign-up test' });
+// ...sign up with the address, persona and password...
+const { value: code } = await qa.waitForCode(address); // waits up to 30 s
+const { value: link } = await qa.waitForLink(address, { type: 'reset', timeout: 60 });
+await qa.deleteAddress(address);
+```
+
+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.
+
+## Playwright
+
+```ts
+import { test as base, expect } from '@playwright/test';
+import { ProxyMailQA } from 'proxymail-qa';
+
+const test = base.extend<{ inbox: { address: string } }>({
+  inbox: async ({}, use) => {
+    const qa = new ProxyMailQA();
+    const created = await qa.createAddress({ persona: true });
+    await use(created);
+    await qa.deleteAddress(created.address);
+  },
+});
+
+test('sign-up sends a working code', async ({ page, inbox }) => {
+  const submitted = new Date();
+  await page.goto('/signup');
+  await page.getByLabel('Email').fill(inbox.address);
+  await page.getByRole('button', { name: 'Sign up' }).click();
+  const { value } = await new ProxyMailQA().waitForCode(inbox.address, { since: submitted });
+  await page.getByLabel('Code').fill(value);
+  await expect(page).toHaveURL(/welcome/);
+});
+```
+
+## Cypress
+
+Register tasks in `cypress.config.ts`, since Cypress runs them in Node:
+
+```ts
+import { ProxyMailQA } from 'proxymail-qa';
+
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on) {
+      const qa = new ProxyMailQA();
+      on('task', {
+        createAddress: () => qa.createAddress({ persona: true }),
+        waitForLink: (address: string) => qa.waitForLink(address, { type: 'verify' }),
+      });
+    },
+  },
+});
+```
+
+```js
+cy.task('createAddress').then(({ address }) => {
+  cy.get('[name=email]').type(address);
+  cy.contains('Sign up').click();
+  cy.task('waitForLink', address, { timeout: 35000 }).then(({ value }) => cy.visit(value));
+});
+```
+
+## More
+
+```ts
+// A persona with a date of birth for an age band, and a country.
+await qa.createAddress({ persona: true, age: 'under13', country: 'GB' });
+
+// 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 });
+
+// The email itself, for template tests (the HTML is cleaned when it arrives).
+const [latest] = await qa.messages(address, { includeHtml: true, limit: 1 });
+
+// Unusual but valid versions of the address, and invalid ones to reject.
+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' });
+```
+
+When a wait comes back empty, the error says why as far as Proxy Mail QA can
+tell, for example that the app's email provider only sends to verified
+addresses (sandbox mode): read `error.hint`, or call `qa.checkDelivery(address)`
+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
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+export interface ClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+export interface Persona {
+    first_name: string | null;
+    last_name: string | null;
+    username: string | null;
+    date_of_birth?: string;
+    country?: string;
+}
+export type AgeBand = 'adult' | 'over21' | 'under18' | 'under15' | 'under13' | 'any' | 'turns18tomorrow' | 'turned18today';
+export interface Address {
+    address: string;
+    label: string | null;
+    created_at: string;
+    expires_at: string;
+    persona: Persona | null;
+    notes: string | null;
+    tags: string[];
+    has_password: boolean;
+    email_count: number;
+    latest: Omit<Match, 'address' | 'email_id' | 'service_domain'> | null;
+}
+export interface CreatedAddress extends Address {
+    password?: string;
+}
+export interface Match {
+    address: string;
+    type: 'code' | 'link';
+    subtype: string;
+    value: string;
+    service: string | null;
+    service_domain: string | null;
+    received_at: string;
+    expires_at: string | null;
+    email_id: string;
+}
+export interface CreateAddressInput {
+    label?: string;
+    name?: string;
+    persona?: boolean;
+    password?: boolean;
+    lifetimeDays?: number;
+    domain?: string;
+    age?: AgeBand;
+    dateOfBirth?: string;
+    country?: string;
+}
+export interface AddressPatch {
+    label?: string | null;
+    notes?: string | null;
+    tags?: string[];
+    first_name?: string | null;
+    last_name?: string | null;
+    username?: string | null;
+    date_of_birth?: string | null;
+    country?: string | null;
+}
+export interface Refusal {
+    reason: 'too_large' | 'address_limit' | 'daily_limit';
+    first_at: string;
+    last_at: string;
+    count: number;
+    size_bytes: number | null;
+}
+export interface DeliveryStatus {
+    address: string;
+    created_at: string;
+    expires_at: string;
+    receiving: boolean;
+    emails: number;
+    last_email_at: string | null;
+    refused: Refusal[];
+    hint: string;
+    help: string;
+}
+export interface Variant {
+    tests: string;
+    address: string;
+}
+export interface Variants {
+    address: string;
+    delivered: Variant[];
+    undeliverable: Variant[];
+    invalid: Variant[];
+}
+export interface WaitOptions {
+    timeout?: number;
+    service?: string;
+    since?: Date | string;
+}
+export type LinkType = 'verify' | 'magic_signin' | 'invite' | 'reset' | 'any';
+export declare class ProxyMailQAError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly hint?: string | undefined;
+    readonly refused?: Refusal[] | undefined;
+    readonly help?: string | undefined;
+    constructor(status: number, code: string, message: string, hint?: string | undefined, refused?: Refusal[] | undefined, help?: string | undefined);
+}
+export declare class ProxyMailQA {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetcher;
+    constructor(options?: ClientOptions);
+    private request;
+    project(): Promise<Record<string, unknown>>;
+    createAddress(input?: CreateAddressInput): Promise<CreatedAddress>;
+    listAddresses(options?: {
+        limit?: number;
+        before?: string;
+    }): Promise<Address[]>;
+    getAddress(address: string): Promise<Address>;
+    updateAddress(address: string, patch: AddressPatch): Promise<Address>;
+    deleteAddress(address: string): Promise<void>;
+    waitForCode(address: string, options?: WaitOptions): Promise<Match>;
+    waitForLink(address: string, options?: WaitOptions & {
+        type?: LinkType | LinkType[];
+        app?: boolean;
+    }): Promise<Match>;
+    messages(address: string, options?: {
+        includeText?: boolean;
+        includeHtml?: boolean;
+        limit?: number;
+    }): Promise<Record<string, unknown>[]>;
+    checkDelivery(address: string): Promise<DeliveryStatus>;
+    variants(address: string): Promise<Variants>;
+    setPassword(address: string, options?: {
+        password?: string;
+        label?: string;
+    }): Promise<{
+        address: string;
+        label: string;
+        saved: boolean;
+        password?: string;
+    }>;
+    savedPassword(address: string, label?: string): Promise<{
+        address: string;
+        label: string;
+        secret: string;
+    }>;
+    private wait;
+}

package/dist/index.js

@@ -0,0 +1,153 @@
+// A small client for the Proxy Mail QA REST API (https://proxymail.qa/docs/api):
+// create disposable test inboxes and wait for the verification code or link
+// from the email the app under test sends. No dependencies; works in Node 18+,
+// Playwright, Cypress tasks and other runtimes with fetch.
+// An API error. When a wait finds nothing, hint says why as far as Proxy Mail
+// QA can tell (an email provider in sandbox mode, say) and refused lists any
+// mail it turned away; both are in the message too.
+export class ProxyMailQAError extends Error {
+    status;
+    code;
+    hint;
+    refused;
+    help;
+    constructor(status, code, message, hint, refused, help) {
+        super(hint ? `${message} ${hint}` : message);
+        this.status = status;
+        this.code = code;
+        this.hint = hint;
+        this.refused = refused;
+        this.help = help;
+        this.name = 'ProxyMailQAError';
+    }
+}
+const TIMED_OUT = /^No (code|link) arrived/;
+const MAX_WAIT_SECONDS = 30;
+export class ProxyMailQA {
+    apiKey;
+    baseUrl;
+    fetcher;
+    constructor(options = {}) {
+        const fromEnv = globalThis.process?.env?.PROXYMAIL_QA_API_KEY;
+        const apiKey = options.apiKey ?? fromEnv;
+        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);
+    }
+    async request(method, path, body) {
+        const response = await this.fetcher(`${this.baseUrl}/v1${path}`, {
+            method,
+            headers: { Authorization: `Bearer ${this.apiKey}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (response.status === 204)
+            return undefined;
+        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);
+        }
+        return payload;
+    }
+    project() {
+        return this.request('GET', '/project');
+    }
+    createAddress(input = {}) {
+        return this.request('POST', '/addresses', {
+            label: input.label,
+            name: input.name,
+            persona: input.persona,
+            password: input.password,
+            lifetime_days: input.lifetimeDays,
+            domain: input.domain,
+            age: input.age,
+            date_of_birth: input.dateOfBirth,
+            country: input.country,
+        });
+    }
+    listAddresses(options = {}) {
+        const query = new URLSearchParams();
+        if (options.limit)
+            query.set('limit', String(options.limit));
+        if (options.before)
+            query.set('before', options.before);
+        return this.request('GET', `/addresses${query.size ? `?${query}` : ''}`);
+    }
+    getAddress(address) {
+        return this.request('GET', `/addresses/${encodeURIComponent(address)}`);
+    }
+    updateAddress(address, patch) {
+        return this.request('PATCH', `/addresses/${encodeURIComponent(address)}`, patch);
+    }
+    deleteAddress(address) {
+        return this.request('DELETE', `/addresses/${encodeURIComponent(address)}`);
+    }
+    // Waits for a verification or login code; throws ProxyMailQAError (404) if
+    // none arrives in time.
+    waitForCode(address, options = {}) {
+        return this.wait(address, 'code', options);
+    }
+    // Waits for a verify, magic sign-in, invite or reset link. When an email has
+    // both a web link and one that opens a mobile app (myapp://…), the web link
+    // comes first: app: true asks for the app one, app: false for a web one.
+    waitForLink(address, options = {}) {
+        return this.wait(address, 'link', options, [options.type ?? []].flat().join(','), options.app);
+    }
+    // Emails with their codes and links. includeText and includeHtml add each
+    // email's content, for tests that check the email itself; it's written by
+    // the sender, so treat it as untrusted. The HTML is the copy cleaned when
+    // the email arrived.
+    messages(address, options = {}) {
+        const query = new URLSearchParams();
+        const include = [options.includeText && 'text', options.includeHtml && 'html'].filter(Boolean);
+        if (include.length)
+            query.set('include', include.join(','));
+        if (options.limit)
+            query.set('limit', String(options.limit));
+        return this.request('GET', `/addresses/${encodeURIComponent(address)}/messages${query.size ? `?${query}` : ''}`);
+    }
+    // What reached the address and what was refused, without waiting: for when
+    // a wait comes back empty.
+    checkDelivery(address) {
+        return this.request('GET', `/addresses/${encodeURIComponent(address)}/delivery`);
+    }
+    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 });
+    }
+    // Needs a key created with "Can read saved passwords"; every reveal is logged.
+    savedPassword(address, label = 'password') {
+        return this.request('GET', `/addresses/${encodeURIComponent(address)}/password?label=${encodeURIComponent(label)}`);
+    }
+    async wait(address, kind, options, type = '', app) {
+        const total = options.timeout ?? MAX_WAIT_SECONDS;
+        const deadline = Date.now() + total * 1000;
+        const since = options.since === undefined ? undefined : new Date(options.since).toISOString();
+        for (;;) {
+            const left = Math.max(0, Math.min(MAX_WAIT_SECONDS, Math.ceil((deadline - Date.now()) / 1000)));
+            const query = new URLSearchParams({ timeout: String(left) });
+            if (options.service)
+                query.set('service', options.service);
+            if (since)
+                query.set('since', since);
+            if (type)
+                query.set('type', type);
+            if (app !== undefined)
+                query.set('app', String(app));
+            try {
+                return await this.request('GET', `/addresses/${encodeURIComponent(address)}/${kind}?${query}`);
+            }
+            catch (error) {
+                const timedOut = error instanceof ProxyMailQAError && error.status === 404 && TIMED_OUT.test(error.message);
+                if (!timedOut || Date.now() >= deadline - 500)
+                    throw error;
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "proxymail-qa",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+  "bugs": {
+    "email": "hello@proxymail.qa"
+  },
+  "keywords": [
+    "email testing",
+    "otp",
+    "magic link",
+    "email verification",
+    "playwright",
+    "cypress",
+    "qa"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
+  "devDependencies": {
+    "vitest": "^5.0.3"
+  }
+}