proxymail-qa 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -23,6 +23,20 @@ export interface Address {
     has_password: boolean;
     email_count: number;
     latest: Omit<Match, 'address' | 'email_id' | 'service_domain'> | null;
+    checked_out_until?: string;
+}
+export interface CheckoutOptions extends Omit<ListAddressesOptions, 'limit' | 'before'> {
+    minutes?: number;
+}
+export interface CheckedOutAccount extends Address {
+    checkout: {
+        token: string;
+        until: string;
+    };
+}
+export interface ReturnState {
+    addTags?: string[];
+    removeTags?: string[];
 }
 export interface CreatedAddress extends Address {
     password?: string;
@@ -110,6 +124,7 @@ export interface WaitOptions {
     timeout?: number;
     service?: string;
     since?: Date | string;
+    unused?: boolean;
 }
 export type LinkType = 'verify' | 'magic_signin' | 'invite' | 'reset' | 'any';
 export interface EmailSummary {
@@ -216,6 +231,16 @@ export declare class ProxyMailQA {
     createAddress(input?: CreateAddressInput): Promise<CreatedAddress>;
     listAddresses(options?: ListAddressesOptions): Promise<Address[]>;
     getAddress(address: string): Promise<Address>;
+    checkOutAccount(options?: CheckoutOptions): Promise<CheckedOutAccount>;
+    extendCheckout(account: CheckedOutAccount, minutes?: number): Promise<{
+        address: string;
+        checkout: {
+            token: string;
+            until: string;
+        };
+    }>;
+    returnAccount(account: CheckedOutAccount, state?: ReturnState): Promise<Address>;
+    withAccount<T>(options: CheckoutOptions, fn: (account: CheckedOutAccount) => Promise<T>): Promise<T>;
     updateAddress(address: string, patch: AddressPatch): Promise<Address>;
     deleteAddress(address: string): Promise<void>;
     waitForCode(address: string, options?: WaitOptions): Promise<Match>;

package/dist/index.js

@@ -115,6 +115,51 @@ export class ProxyMailQA {
     getAddress(address) {
         return this.request('GET', `/addresses/${encodeURIComponent(address)}`);
     }
+    // Checks out an account matching every filter that nobody else holds, the
+    // least recently used first, for `minutes` (default 10). Throws
+    // ProxyMailQAError 409 when every match is checked out, 404 when none
+    // match. Tag accounts with their state (verified, premium…) to make pools.
+    checkOutAccount(options = {}) {
+        return this.request('POST', '/addresses/checkout', {
+            tags: options.tags,
+            country: options.country,
+            min_age: options.minAge,
+            max_age: options.maxAge,
+            has_password: options.hasPassword,
+            search: options.search,
+            minutes: options.minutes,
+        });
+    }
+    // More time from now (default 10 minutes).
+    extendCheckout(account, minutes) {
+        return this.request('POST', `/addresses/${encodeURIComponent(account.address)}/extend`, {
+            token: account.checkout.token,
+            minutes,
+        });
+    }
+    // Frees it for the next test, recording any change to its state.
+    returnAccount(account, state = {}) {
+        return this.request('POST', `/addresses/${encodeURIComponent(account.address)}/return`, {
+            token: account.checkout.token,
+            add_tags: state.addTags,
+            remove_tags: state.removeTags,
+        });
+    }
+    // Checks out an account, runs fn with it, and always returns it. fn can
+    // say what state it left the account in by returning { addTags, removeTags }.
+    async withAccount(options, fn) {
+        const account = await this.checkOutAccount(options);
+        let state = {};
+        try {
+            const result = await fn(account);
+            if (result && typeof result === 'object' && ('addTags' in result || 'removeTags' in result))
+                state = result;
+            return result;
+        }
+        finally {
+            await this.returnAccount(account, state).catch(() => { });
+        }
+    }
     updateAddress(address, patch) {
         return this.request('PATCH', `/addresses/${encodeURIComponent(address)}`, patch);
     }
@@ -254,6 +299,8 @@ export class ProxyMailQA {
                 query.set('type', type);
             if (app !== undefined)
                 query.set('app', String(app));
+            if (options.unused)
+                query.set('unused', 'true');
             const more = Date.now() + left * 1000 < deadline - 500;
             try {
                 return await this.request('GET', `/addresses/${encodeURIComponent(address)}/${kind}?${query}`, undefined, more);

package/package.json

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