@mailsai/cypress 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mails.ai
+
+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,165 @@
-# Temporary Holding Version
+# @mailsai/cypress
 
-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.
+Cypress commands for testing the email your app sends at sign-up, sign-in and password reset. Each test run gets an email address of its own, a plus address of one mails.ai agent, then waits for the email sent to that address and reads the code or the link in it.
+
+```ts
+cy.mailsaiPlusAddress().then((email) => {
+  // …sign up with `email`…
+  cy.mailsaiWaitForCode({ to: email }).then((code) => cy.get("[data-cy=code]").type(code));
+});
+```
+
+## What you need
+
+- A mails.ai API key with the `read` scope.
+- A mails.ai agent whose receiving address gets the test mail, such as `qa.acme@in.mails.ai`. Mail to any plus address of it, such as `qa.acme+run-1842@in.mails.ai`, reaches the same agent.
+- Cypress 13 or later.
+
+## Install
+
+```sh
+npm install --save-dev @mailsai/cypress
+```
+
+Then import it once, in your support file (`cypress/support/e2e.ts`, or `e2e.js`):
+
+```ts
+import "@mailsai/cypress";
+```
+
+That registers the four commands and adds their types to `cy`. TypeScript sees the types through this import when your tsconfig includes the support file. If it does not, add `"@mailsai/cypress"` to `compilerOptions.types` next to `"cypress"`.
+
+## Settings
+
+Put the settings in the `env` block of your Cypress config, read from your environment, so no key is written into the repository:
+
+```ts
+// cypress.config.ts
+import { defineConfig } from "cypress";
+
+export default defineConfig({
+  e2e: {
+    baseUrl: "http://localhost:3000",
+  },
+  env: {
+    MAILS_API_KEY: process.env.MAILS_API_KEY,
+    MAILS_RECEIVING_ADDRESS: process.env.MAILS_RECEIVING_ADDRESS,
+  },
+});
+```
+
+Or leave the block out and set each one as an environment variable with the `CYPRESS_` prefix, which Cypress removes:
+
+```sh
+CYPRESS_MAILS_API_KEY=mk_live_… CYPRESS_MAILS_RECEIVING_ADDRESS=qa.acme@in.mails.ai npx cypress run
+```
+
+| Setting | |
+| --- | --- |
+| `MAILS_API_KEY` | Required by the three wait commands. |
+| `MAILS_RECEIVING_ADDRESS` | Required by `mailsaiPlusAddress`: the receiving address of the agent the test mail goes to. |
+| `MAILS_BASE_URL` | Optional. `https://api.mails.ai` when unset. |
+| `MAILS_AGENT_ID` | Optional. The wait commands' `agentId` when they are not given one. |
+
+The key never appears in the Command Log, a screenshot or a video. The commands read the settings with `cy.env()`, which keeps their values in the Cypress process, and make their requests with `log: false`. Each command writes one Command Log line of its own, showing its filters. On Cypress older than 15.10, which has no `cy.env()`, the settings are read with `Cypress.env()`.
+
+## Example
+
+A sign-up that sends a 6-digit code:
+
+```ts
+// cypress/e2e/signup.cy.ts
+describe("sign-up", () => {
+  it("verifies a new account with the emailed code", () => {
+    cy.mailsaiPlusAddress().then((email) => {
+      cy.visit("/signup");
+      cy.get("[data-cy=email]").type(email);
+      cy.get("[data-cy=submit]").click();
+
+      cy.mailsaiWaitForCode({ to: email }).then((code) => {
+        cy.get("[data-cy=code]").type(code);
+      });
+      cy.get("[data-cy=verify]").click();
+
+      cy.contains("Your account is verified");
+    });
+  });
+});
+```
+
+For a sign-in link or a password reset, wait for the link and visit it:
+
+```ts
+cy.mailsaiWaitForLink({ to: email, kind: "reset_password" }).then((url) => cy.visit(url));
+```
+
+## Commands
+
+### `cy.mailsaiPlusAddress(tag?)`
+
+Yields a new address for this run: `MAILS_RECEIVING_ADDRESS` with `+<tag>` before the `@`. Without a tag, each call makes a new one from `run-`, the time and 4 random characters, such as `qa.acme+run-mgt2k4x1-7q3z@in.mails.ai`.
+
+A tag is 1 to 40 letters, digits, `.`, `_`, `-` or `+`, and is lowercased. Pass a tag of your own when the address must be known in advance, such as `cy.mailsaiPlusAddress("checkout")`. Mail sent to it by an earlier run then counts too, unless the wait is given `since`.
+
+The part of an address before the `@` holds at most 64 characters, the `+` and the tag included. When the receiving address leaves room for fewer than the 17 characters of the default tag, the default is as many random characters as fit. With room for fewer than 6, the command fails and says how much room there is, as it does for a tag of your own that is too long.
+
+### `cy.mailsaiWaitForMessage(options?)`
+
+Yields the newest received email that matches the options, waiting for one to arrive.
+
+| Option | |
+| --- | --- |
+| `to` | Only mail sent to this address. Pass the plus address the test signed up with, so an email meant for another run is never taken. |
+| `from` | Only mail from this address (`noreply@github.com`), or from this domain and its subdomains (`github.com`). |
+| `has` | `"code"`: only mail with a verification code. `"link"`: only mail with a verify, sign-in or password-reset link. |
+| `since` | Only mail received at or after this time (ISO 8601). Without it, the API looks back 5 minutes, so an email that arrived just before the wait began still counts. |
+| `timeout` | Seconds to wait in all, 60 when not given. The command waits in calls of at most 50 seconds each until the time is used up. |
+| `agentId` | Only this agent's mail. `MAILS_AGENT_ID` when not given. |
+
+The message it yields carries `codes` and `links` (below), `subject`, `from`, `delivered_to` (the address it was sent to) and the other fields of a received message in the API reference.
+
+When nothing arrives in time, the test fails with a message that names the filters:
+
+```
+mailsaiWaitForMessage: no email arrived within 60 s matching to: qa.acme+run-mgt2k4x1-7q3z@in.mails.ai.
+```
+
+### `cy.mailsaiWaitForCode(options?)`
+
+Waits as `mailsaiWaitForMessage` does, for mail with a code, and yields the code: `codes[0].value`, the most likely code in the email. Takes the same options, without `has`.
+
+### `cy.mailsaiWaitForLink(options?)`
+
+Waits as `mailsaiWaitForMessage` does, for mail with a verify, sign-in or password-reset link, and yields a URL. Takes the same options, without `has`, and one more:
+
+| Option | |
+| --- | --- |
+| `kind` | `"verify"`, `"sign_in"`, `"reset_password"` or `"other"`: yield the first link of this kind. Without it, the first `verify`, `sign_in` or `reset_password` link. |
+
+It never yields an unsubscribe link, and fails when the email has no link it may yield. Only mail with a verify, sign-in or password-reset link is waited for, so `kind: "other"` finds a link of that kind only in such an email.
+
+## When a call is refused
+
+A refused call fails the test with the API's error code and message, such as:
+
+```
+mailsaiWaitForCode: mails.ai answered 401 invalid_api_key: Invalid API key (request req_…)
+```
+
+The API takes 60 waits a minute for one workspace. When it answers 429, the command pauses for as long as the answer asks and tries again, as long as what is left of its `timeout` covers the pause.
+
+Past the plan's daily plus-address limit, a wait given `to` fails at once with 402 `plan_limit_exceeded` instead of running out its `timeout`, and its message ends with the link to change plan.
+
+## Limits
+
+A workspace may receive mail at a limited number of different plus addresses a day, set by its plan. Past that, mail to a new plus address keeps only a record, which a wait never yields, while the addresses already used that day keep working. The numbers for each plan are at https://mails.ai/docs/limits.
+
+A sign-in code or link from a service such as Google, Microsoft, Apple, a payment app or a bank never reaches a plus address either: such mail keeps only a record, so a wait for it runs out its `timeout`. Unless your app is one of those services, its own emails are not affected.
+
+## Tests
+
+[`packages/cypress/e2e`](https://github.com/mailsai/mailsai/tree/main/packages/cypress/e2e) in the repository is a Cypress project that uses these commands the way a test suite would, against a stand-in for the mails.ai API and a small sign-up page. In `packages/cypress`, `npm run test:e2e` builds and packs the package, installs it there and runs it headless. After `npm run build`, `node --test test/*.test.mjs` runs the unit tests.
+
+## License
+
+MIT

package/dist/core.d.ts

@@ -0,0 +1,285 @@
+/** Where the API is when MAILS_BASE_URL is not set. */
+export declare const DEFAULT_BASE_URL = "https://api.mails.ai";
+/** The longest one wait call may hold, in seconds: the route's own limit. */
+export declare const MAX_WAIT_SECONDS = 50;
+/** A wait command's whole timeout when none is given, in seconds. */
+export declare const DEFAULT_TIMEOUT_SECONDS = 60;
+/** How much longer than the wait it asked for one request may take, in seconds. */
+export declare const REQUEST_GRACE_SECONDS = 15;
+/** The longest pause after a 429 before the next try, in seconds. The route's limit counts a
+ *  minute, so it never asks for more. */
+export declare const MAX_RETRY_PAUSE_SECONDS = 60;
+export type LinkKind = "verify" | "sign_in" | "reset_password" | "unsubscribe" | "other";
+/** The kinds mailsaiWaitForLink can be asked for: every kind but `unsubscribe`, which it never yields. */
+export type MailsaiLinkKind = Exclude<LinkKind, "unsubscribe">;
+/** The links that are the point of an email: what `has=link` matches on the API, and what
+ *  mailsaiWaitForLink yields when no kind is given. */
+export declare const ACTION_LINK_KINDS: readonly LinkKind[];
+/** A file on a received message, as @mailsai/sdk types it. */
+export type MailsaiReceivedAttachment = {
+    /** Attachment id (`att_…`), unique within the message. */
+    id: string;
+    /** The file's name, cleaned: no path, no control characters, at most 255 characters. */
+    filename: string;
+    /** The MIME type the sender declared, e.g. `application/pdf`. */
+    content_type: string;
+    /** Size in bytes of the decoded file. */
+    size: number;
+    /** The part's Content-ID without angle brackets, which the HTML body references as `cid:`. */
+    content_id: string | null;
+    /** True for an image embedded in the HTML body rather than attached as a file. */
+    inline: boolean;
+};
+/** A file the message carried that was not kept, with the reason. */
+export type MailsaiOmittedAttachment = {
+    filename: string;
+    content_type: string;
+    size: number | null;
+    reason: "too_large" | "budget" | "over_quota" | "unavailable" | "too_many";
+};
+/** A received message, as @mailsai/sdk types it (its `ReceivedMessage`). */
+export type MailsaiReceivedMessage = {
+    id: string;
+    agent_id: string;
+    thread_id?: string;
+    /** The first mailbox of the From header. Proven only when `dmarc` is "pass". */
+    from: {
+        address: string;
+        name?: string;
+    };
+    /** The envelope sender (SMTP MAIL FROM), where bounces go. Null on mail received before this field was added. */
+    envelope_from?: string | null;
+    to: string;
+    /** The address the email was sent to: the agent's receiving address, or a plus address of it.
+     *  What the `to` filter matches. Null on mail received before 2026-10-16. */
+    delivered_to?: string | null;
+    subject?: string;
+    is_thread_reply?: boolean;
+    in_reply_to_message_id?: string;
+    thread_root_message_id?: string;
+    /** Full body: single-message `get` only. */
+    body_text?: string;
+    /** The HTML part: single-message `get` only, when the injection scan read it. */
+    body_html?: string;
+    extracted_text?: string;
+    extracted_html?: string;
+    body_text_excerpt?: string;
+    /** Verification codes in the email (sign-up, sign-in, one-time), most likely first, at most 5. */
+    codes?: {
+        value: string;
+    }[];
+    /** The email's links, `verify`, `sign_in` and `reset_password` first, `unsubscribe` last, at most 25. */
+    links?: {
+        url: string;
+        kind: LinkKind;
+    }[];
+    spf_pass?: boolean;
+    dkim_pass?: boolean;
+    dkim?: "pass" | "fail" | "none" | "unknown";
+    /** The domain of a passing DKIM signature that matches the domain of `from.address`, or null. */
+    dkim_domain?: string | null;
+    /** "pass" when the domain of `from.address` publishes DMARC and a DKIM signature aligned with it verifies. */
+    dmarc?: "pass" | "fail" | "none" | "unknown";
+    /** True when the sender was judged forged. */
+    auth_failed?: boolean;
+    /** True when the message carries at least one file attachment (embedded images do not count). */
+    has_attachment?: boolean;
+    /** Every part of the message that is a file, embedded images included. */
+    attachments?: MailsaiReceivedAttachment[];
+    attachments_omitted?: MailsaiOmittedAttachment[];
+    attachments_omitted_count?: number;
+    /** Present when the raw email was not kept, and why. */
+    raw_omitted?: "too_large" | "budget" | "over_quota" | "unavailable";
+    parse_status?: "parsed" | "quarantined" | "pending" | "failed" | "quota_skipped";
+    received_at: string;
+    created_at?: string;
+};
+export type MailsaiWaitOptions = {
+    /** Only mail sent to this address, such as the plus address the test signed up with. */
+    to?: string;
+    /** Only mail from this address, or from this domain and its subdomains. */
+    from?: string;
+    /** Only mail with a verification code, or with a verify, sign-in or password-reset link. */
+    has?: "code" | "link";
+    /** Only mail received at or after this time (ISO 8601). Without it the API looks back 5 minutes. */
+    since?: string;
+    /** Seconds to wait in all, 60 by default. Spent as waits of at most 50 seconds each. */
+    timeout?: number;
+    /** Only this agent's mail. MAILS_AGENT_ID by default. */
+    agentId?: string;
+};
+export type MailsaiWaitForCodeOptions = Omit<MailsaiWaitOptions, "has">;
+export type MailsaiWaitForLinkOptions = Omit<MailsaiWaitOptions, "has"> & {
+    /** The kind of link to yield. Without it: the first verify, sign_in or reset_password link. */
+    kind?: MailsaiLinkKind;
+};
+export type WaitCommand = "mailsaiWaitForMessage" | "mailsaiWaitForCode" | "mailsaiWaitForLink";
+/** The settings the commands read, from the `env` block of the Cypress config or CYPRESS_* variables. */
+export declare const CONFIG_KEYS: readonly ["MAILS_API_KEY", "MAILS_RECEIVING_ADDRESS", "MAILS_BASE_URL", "MAILS_AGENT_ID"];
+export type MailsaiConfig = {
+    apiKey: string;
+    receivingAddress: string;
+    baseUrl: string;
+    agentId: string;
+};
+/** The settings as the commands use them: trimmed, and "" for one that is unset. */
+export declare function configFrom(env: Record<string, unknown>): MailsaiConfig;
+/** The error a command fails with when a setting it needs is unset. */
+export declare function missingSetting(command: string, key: "MAILS_API_KEY" | "MAILS_RECEIVING_ADDRESS"): Error;
+/** The API's address: MAILS_BASE_URL without its trailing slashes, or https://api.mails.ai when it
+ *  is empty, as in @mailsai/sdk. */
+export declare function baseUrlOf(raw: string): string;
+/** The most characters the part of an address before the @ may hold: RFC 5321's limit, and what
+ *  the API's `to` filter takes. A receiving address that already has 64 leaves no room for a tag. */
+export declare const MAX_LOCAL_PART = 64;
+/** The most characters a tag may have. */
+export declare const MAX_TAG = 40;
+/** The fewest random characters a shortened default tag may have and still be unique to its run. */
+export declare const MIN_UNIQUE_TAG = 6;
+/**
+ * A plus address of an agent: its receiving address with `+<tag>` before the `@`, which reaches the
+ * same agent. The same rules as `plusAddress()` in @mailsai/sdk: the tag is trimmed of ASCII
+ * whitespace and lowercased and must be 1 to 40 letters, digits, `.`, `_`, `-` or `+`; only the part
+ * of the local part before its first `+` is kept, and with the tag it may hold at most 64
+ * characters; the whole address is lowercased.
+ */
+export declare function plusAddress(receivingAddress: string, tag: string): string;
+/** How many characters a tag on `receivingAddress` may have: 40, or fewer when the part before its
+ *  @ leaves less room under MAX_LOCAL_PART (0 or less: none). */
+export declare function tagRoom(receivingAddress: string): number;
+/**
+ * A tag for one run: `run-`, the time in base 36 and 4 random letters or digits, such as
+ * `run-mgt2k4x1-7q3z` (17 characters). When `room` (tagRoom()) is less than that, as many random
+ * characters as fit, which keep the tag unique while at least MIN_UNIQUE_TAG fit; with fewer, the
+ * full tag, which plusAddress() then refuses, naming the room there is.
+ */
+export declare function defaultTag(now?: number, random?: (n: number) => string, room?: number): string;
+/** The address mailsaiPlusAddress yields: plusAddress() with the tag given, or with a new default
+ *  tag per call that fits the receiving address. */
+export declare function plusAddressFor(receivingAddress: string, tag: unknown, now?: number, random?: (n: number) => string): string;
+/** A wait command's options, checked: the filters as the API takes them and the whole timeout. */
+export type WaitPlan = {
+    to?: string;
+    from?: string;
+    has?: "code" | "link";
+    since?: string;
+    agentId?: string;
+    /** Whole seconds to wait in all. */
+    timeout: number;
+    /** mailsaiWaitForLink only: the kind of link to yield. */
+    kind?: MailsaiLinkKind;
+};
+/** A wait command's options, checked: an unknown option, an empty filter or a bad timeout throws,
+ *  and mailsaiWaitForCode and mailsaiWaitForLink set `has` themselves. */
+export declare function waitPlan(command: WaitCommand, input: unknown): WaitPlan;
+/** The filters, as the Command Log line and the errors show them. */
+export declare function describeFilters(plan: WaitPlan): string;
+/** The seconds the next wait call asks for: what is left of the timeout, at most 50. */
+export declare function nextWaitSeconds(left: number): number;
+/** How a timeout is spent when nothing arrives: 60 → [50, 10], 120 → [50, 50, 20], 0 → [0]. */
+export declare function splitTimeout(total: number): number[];
+export type WaitRequest = {
+    method: "GET";
+    url: string;
+    headers: Record<string, string>;
+    timeout: number;
+};
+/** One call to GET /v1/messages/received/wait asking to hold for `seconds`. `timeout` is how long
+ *  Cypress gives the request, in milliseconds: the wait and REQUEST_GRACE_SECONDS more. `since` is
+ *  sent only when given, so the API's own look-back applies. */
+export declare function waitRequest(baseUrl: string, apiKey: string, plan: WaitPlan, seconds: number): WaitRequest;
+/** The API's error body (lib/errors.ts), as read from a refused call. */
+export type ApiErrorDetails = {
+    status: number;
+    type: string;
+    code: string;
+    message: string;
+    param: string | null;
+    requestId: string | null;
+    /** Where to change plan: the `upgrade_url` every 402 (payment_error) carries, such as a wait
+     *  for mail the plan's daily plus-address limit refused. Null otherwise. */
+    upgradeUrl: string | null;
+};
+export type WaitAnswer = {
+    kind: "message";
+    message: MailsaiReceivedMessage;
+} | {
+    kind: "timed_out";
+} | {
+    kind: "rate_limited";
+    error: ApiErrorDetails;
+    /** Seconds until the limit lets a wait through, from Retry-After or the body's
+     *  retry_after_seconds; null when the answer did not say. */
+    retryAfterSeconds: number | null;
+    /** False when the body's resets_at is null: no wait lifts the limit. */
+    waitHelps: boolean;
+} | {
+    kind: "error";
+    error: ApiErrorDetails;
+};
+type Headers = Record<string, string | string[] | undefined>;
+/** `Retry-After` in seconds: a number of seconds or an HTTP date. Null when absent or unreadable. */
+export declare function parseRetryAfter(value: string | null, now?: number): number | null;
+/** What one wait call's answer means: a message, nothing in time, a 429, or an error. */
+export declare function readWaitResponse(status: number, body: unknown, headers?: Headers): WaitAnswer;
+/** Whole seconds to pause after a 429 before trying again: what the answer asked for, else 1, 2,
+ *  4 then 8 for 429s in a row (`times` is how many came before this one), at most
+ *  MAX_RETRY_PAUSE_SECONDS. Null when no wait lifts the limit. */
+export declare function retryPause(answer: {
+    retryAfterSeconds: number | null;
+    waitHelps: boolean;
+}, times: number): number | null;
+/** The error of a refused wait, carrying the API's code and message, and on a 402 ending with the
+ *  link to change plan, so a failed CI run says where to go. */
+export declare class MailsaiApiError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly code: string;
+    readonly param: string | null;
+    readonly requestId: string | null;
+    readonly upgradeUrl: string | null;
+    constructor(command: string, e: ApiErrorDetails, extra?: string);
+}
+/** The error of a 429 the rest of the timeout cannot wait out. */
+export declare function rateLimitError(command: string, e: ApiErrorDetails, pause: number | null, left: number, timeout: number): MailsaiApiError;
+/** The error when nothing matching arrived within the timeout. */
+export declare function noMailError(command: string, plan: WaitPlan): Error;
+/** Where a wait stands: `left` is the seconds of its timeout not yet spent, `limited` how many 429s
+ *  in a row came before the next call. A wait starts at { left: timeout, limited: 0 }. */
+export type PollState = {
+    left: number;
+    limited: number;
+};
+export type PollStep = {
+    do: "yield";
+    message: MailsaiReceivedMessage;
+} | {
+    do: "call";
+    state: PollState;
+} | {
+    do: "pause";
+    seconds: number;
+    state: PollState;
+} | {
+    do: "fail";
+    error: Error;
+};
+/**
+ * What a wait does after the answer to a call that asked to hold for `seconds`: yield the message,
+ * make the next call while time is left (a timeout of 60 is a 50 s call, then a 10 s one), pause
+ * after a 429 for as long as it asks when the rest of the timeout covers the pause, or fail.
+ */
+export declare function afterAnswer(command: WaitCommand, plan: WaitPlan, state: PollState, seconds: number, answer: WaitAnswer): PollStep;
+/** The message, as the Command Log and the errors name it. */
+export declare function messageLabel(message: MailsaiReceivedMessage): string;
+/** The code mailsaiWaitForCode yields: `codes[0].value`, or null when there is none. */
+export declare function codeOf(message: MailsaiReceivedMessage): string | null;
+/** The link mailsaiWaitForLink yields: the first of `kind`, or without one the first verify,
+ *  sign_in or reset_password link. Never an unsubscribe link; null when none fits. */
+export declare function linkOf(message: MailsaiReceivedMessage, kind?: MailsaiLinkKind): string | null;
+/** The error when the message mailsaiWaitForCode got has no code. */
+export declare function noCodeError(command: string, message: MailsaiReceivedMessage): Error;
+/** The error when the message mailsaiWaitForLink got has no link it may yield, naming the kinds it has. */
+export declare function noLinkError(command: string, message: MailsaiReceivedMessage, kind?: MailsaiLinkKind): Error;
+export {};
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAQA,uDAAuD;AACvD,eAAO,MAAM,gBAAgB,yBAAyB,CAAC;AACvD,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC;yCACyC;AACzC,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,gBAAgB,GAAG,aAAa,GAAG,OAAO,CAAC;AACzF,0GAA0G;AAC1G,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;AAC/D;uDACuD;AACvD,eAAO,MAAM,iBAAiB,EAAE,SAAS,QAAQ,EAA4C,CAAC;AAG9F,8DAA8D;AAC9D,MAAM,MAAM,yBAAyB,GAAG;IACtC,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,kFAAkF;IAClF,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,qEAAqE;AACrE,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,YAAY,GAAG,aAAa,GAAG,UAAU,CAAC;CAC5E,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,iHAAiH;IACjH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX;iFAC6E;IAC7E,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kGAAkG;IAClG,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5B,yGAAyG;IACzG,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,EAAE,CAAC;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC5C,iGAAiG;IACjG,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,8GAA8G;IAC9G,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7C,8CAA8C;IAC9C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iGAAiG;IACjG,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,yBAAyB,EAAE,CAAC;IAC1C,mBAAmB,CAAC,EAAE,wBAAwB,EAAE,CAAC;IACjD,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,wDAAwD;IACxD,WAAW,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,YAAY,GAAG,aAAa,CAAC;IACpE,YAAY,CAAC,EAAE,QAAQ,GAAG,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,eAAe,CAAC;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,wFAAwF;IACxF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AACF,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;AACxE,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,GAAG;IACxE,+FAA+F;IAC/F,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,uBAAuB,GAAG,oBAAoB,GAAG,oBAAoB,CAAC;AAIhG,yGAAyG;AACzG,eAAO,MAAM,WAAW,2FAA4F,CAAC;AAErH,MAAM,MAAM,aAAa,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAQ3G,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,CAOtE;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,yBAAyB,GAAG,KAAK,CAQvG;AAED;oCACoC;AACpC,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM7C;AAID;qGACqG;AACrG,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,0CAA0C;AAC1C,eAAO,MAAM,OAAO,KAAK,CAAC;AAC1B,oGAAoG;AACpG,eAAO,MAAM,cAAc,IAAI,CAAC;AAYhC;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,gBAAgB,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAezE;AAED;iEACiE;AACjE,wBAAgB,OAAO,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAIxD;AAYD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAmB,EAAE,MAAM,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAoB,EAAE,IAAI,GAAE,MAAgB,GAAG,MAAM,CAIhI;AAED;oDACoD;AACpD,wBAAgB,cAAc,CAC5B,gBAAgB,EAAE,MAAM,EACxB,GAAG,EAAE,OAAO,EACZ,GAAG,GAAE,MAAmB,EACxB,MAAM,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAoB,GAC1C,MAAM,CAIR;AAID,kGAAkG;AAClG,MAAM,MAAM,QAAQ,GAAG;IACrB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB,CAAC;AAoCF;0EAC0E;AAC1E,wBAAgB,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,GAAG,QAAQ,CA6BvE;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAStD;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,+FAA+F;AAC/F,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAIpD;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3G;;gEAEgE;AAChE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAczG;AAID,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;gFAC4E;IAC5E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,eAAe,CAAC;IACvB;iEAC6D;IAC7D,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;CACpB,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,CAAC;AAE9C,KAAK,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAU7D,qGAAqG;AACrG,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAM7F;AAmBD,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,UAAU,CAkC7F;AAED;;kEAEkE;AAClE,wBAAgB,UAAU,CAAC,MAAM,EAAE;IAAE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIzH;AAED;gEACgE;AAChE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;gBACvB,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,eAAe,EAAE,KAAK,SAAK;CAW5D;AAED,kEAAkE;AAClE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,CAMxI;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,KAAK,CAElE;AAED;0FAC0F;AAC1F,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,MAAM,QAAQ,GAChB;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,GAChD;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAClD;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEjC;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,QAAQ,CAgBjI;AAID,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAEpE;AAED,wFAAwF;AACxF,wBAAgB,MAAM,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,GAAG,IAAI,CAGrE;AAED;sFACsF;AACtF,wBAAgB,MAAM,CAAC,OAAO,EAAE,sBAAsB,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAY7F;AAED,qEAAqE;AACrE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,KAAK,CAEnF;AAED,2GAA2G;AAC3G,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,KAAK,CAM3G"}

package/dist/core.js

@@ -0,0 +1,432 @@
+// @mailsai/cypress, the part with no Cypress in it: the plus address, the settings, the wait
+// request, reading its answer, picking the code or the link, and spending a command's timeout as
+// waits the API allows. index.ts turns these into Cypress commands; test/ runs them under node:test.
+//
+// The API side is GET /v1/messages/received/wait (app/api/v1/messages/received/wait/route.ts): it
+// holds for up to 50 seconds and answers 200 `{ message, timed_out }`, with `message` null when
+// nothing matched in time, and 429 past 60 waits a minute for one workspace.
+/** Where the API is when MAILS_BASE_URL is not set. */
+export const DEFAULT_BASE_URL = "https://api.mails.ai";
+/** The longest one wait call may hold, in seconds: the route's own limit. */
+export const MAX_WAIT_SECONDS = 50;
+/** A wait command's whole timeout when none is given, in seconds. */
+export const DEFAULT_TIMEOUT_SECONDS = 60;
+/** How much longer than the wait it asked for one request may take, in seconds. */
+export const REQUEST_GRACE_SECONDS = 15;
+/** The longest pause after a 429 before the next try, in seconds. The route's limit counts a
+ *  minute, so it never asks for more. */
+export const MAX_RETRY_PAUSE_SECONDS = 60;
+/** The links that are the point of an email: what `has=link` matches on the API, and what
+ *  mailsaiWaitForLink yields when no kind is given. */
+export const ACTION_LINK_KINDS = ["verify", "sign_in", "reset_password"];
+const WANTED_KINDS = ["verify", "sign_in", "reset_password", "other"];
+// ── settings ────────────────────────────────────────────────────────────────────────────────
+/** The settings the commands read, from the `env` block of the Cypress config or CYPRESS_* variables. */
+export const CONFIG_KEYS = ["MAILS_API_KEY", "MAILS_RECEIVING_ADDRESS", "MAILS_BASE_URL", "MAILS_AGENT_ID"];
+function setting(v) {
+    if (typeof v === "string")
+        return v.trim();
+    if (typeof v === "number" && Number.isFinite(v))
+        return String(v);
+    return "";
+}
+/** The settings as the commands use them: trimmed, and "" for one that is unset. */
+export function configFrom(env) {
+    return {
+        apiKey: setting(env.MAILS_API_KEY),
+        receivingAddress: setting(env.MAILS_RECEIVING_ADDRESS),
+        baseUrl: setting(env.MAILS_BASE_URL),
+        agentId: setting(env.MAILS_AGENT_ID),
+    };
+}
+/** The error a command fails with when a setting it needs is unset. */
+export function missingSetting(command, key) {
+    const what = key === "MAILS_API_KEY"
+        ? "a mails.ai API key with the read scope"
+        : "the receiving address of the mails.ai agent the test mail goes to, such as qa.acme@in.mails.ai";
+    return new Error(`${command} needs ${key}: ${what}. Set it in the env block of cypress.config.ts (env: { ${key}: process.env.${key} }) or as the environment variable CYPRESS_${key}.`);
+}
+/** The API's address: MAILS_BASE_URL without its trailing slashes, or https://api.mails.ai when it
+ *  is empty, as in @mailsai/sdk. */
+export function baseUrlOf(raw) {
+    const base = (raw.trim() || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    if (!/^https?:\/\/[^/\s]/i.test(base)) {
+        throw new Error(`MAILS_BASE_URL must be an http:// or https:// address, such as ${DEFAULT_BASE_URL}. Received: ${JSON.stringify(raw)}`);
+    }
+    return base;
+}
+// ── plus addresses ──────────────────────────────────────────────────────────────────────────
+/** The most characters the part of an address before the @ may hold: RFC 5321's limit, and what
+ *  the API's `to` filter takes. A receiving address that already has 64 leaves no room for a tag. */
+export const MAX_LOCAL_PART = 64;
+/** The most characters a tag may have. */
+export const MAX_TAG = 40;
+/** The fewest random characters a shortened default tag may have and still be unique to its run. */
+export const MIN_UNIQUE_TAG = 6;
+/** `s` without leading and trailing ASCII whitespace (space, tab, CR, LF), as the Python SDK trims a tag. */
+function trimAscii(s) {
+    return s.replace(/^[ \t\r\n]+|[ \t\r\n]+$/g, "");
+}
+/** The part of the receiving address before its @, cut at its first `+`. */
+function baseLocalPart(receivingAddress, at) {
+    return receivingAddress.slice(0, at).split("+")[0];
+}
+/**
+ * A plus address of an agent: its receiving address with `+<tag>` before the `@`, which reaches the
+ * same agent. The same rules as `plusAddress()` in @mailsai/sdk: the tag is trimmed of ASCII
+ * whitespace and lowercased and must be 1 to 40 letters, digits, `.`, `_`, `-` or `+`; only the part
+ * of the local part before its first `+` is kept, and with the tag it may hold at most 64
+ * characters; the whole address is lowercased.
+ */
+export function plusAddress(receivingAddress, tag) {
+    const at = receivingAddress.lastIndexOf("@");
+    if (at < 1)
+        throw new Error(`Not an address: ${JSON.stringify(receivingAddress)}`);
+    const t = trimAscii(tag).toLowerCase();
+    if (!/^[a-z0-9._+-]{1,40}$/.test(t))
+        throw new Error(`A tag is 1 to 40 letters, digits, ".", "_", "-" or "+". Received: ${JSON.stringify(tag)}`);
+    const local = baseLocalPart(receivingAddress, at);
+    if (local.length + 1 + t.length > MAX_LOCAL_PART) {
+        const room = MAX_LOCAL_PART - local.length - 1;
+        throw new Error(room < 1
+            ? `${receivingAddress} has no room for a tag: the part of an address before the @ holds at most ${MAX_LOCAL_PART} characters, and it already has ${local.length}.`
+            : `The part of an address before the @ holds at most ${MAX_LOCAL_PART} characters, so a tag on ${receivingAddress} can have at most ${room}. Received ${t.length}: ${JSON.stringify(tag)}`);
+    }
+    return `${local}+${t}@${receivingAddress.slice(at + 1)}`.toLowerCase();
+}
+/** How many characters a tag on `receivingAddress` may have: 40, or fewer when the part before its
+ *  @ leaves less room under MAX_LOCAL_PART (0 or less: none). */
+export function tagRoom(receivingAddress) {
+    const at = receivingAddress.lastIndexOf("@");
+    const local = at < 1 ? "" : baseLocalPart(receivingAddress, at);
+    return Math.min(MAX_TAG, MAX_LOCAL_PART - local.length - 1);
+}
+const TAG_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+function randomChars(n) {
+    const bytes = new Uint8Array(n);
+    const c = globalThis.crypto;
+    if (c?.getRandomValues)
+        c.getRandomValues(bytes);
+    else
+        for (let i = 0; i < n; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    return Array.from(bytes, (b) => TAG_ALPHABET[b % TAG_ALPHABET.length]).join("");
+}
+/**
+ * A tag for one run: `run-`, the time in base 36 and 4 random letters or digits, such as
+ * `run-mgt2k4x1-7q3z` (17 characters). When `room` (tagRoom()) is less than that, as many random
+ * characters as fit, which keep the tag unique while at least MIN_UNIQUE_TAG fit; with fewer, the
+ * full tag, which plusAddress() then refuses, naming the room there is.
+ */
+export function defaultTag(now = Date.now(), random = randomChars, room = MAX_TAG) {
+    const time = now.toString(36);
+    if (`run-${time}-xxxx`.length <= room || room < MIN_UNIQUE_TAG)
+        return `run-${time}-${random(4)}`;
+    return random(room);
+}
+/** The address mailsaiPlusAddress yields: plusAddress() with the tag given, or with a new default
+ *  tag per call that fits the receiving address. */
+export function plusAddressFor(receivingAddress, tag, now = Date.now(), random = randomChars) {
+    if (tag === undefined || tag === null)
+        return plusAddress(receivingAddress, defaultTag(now, random, tagRoom(receivingAddress)));
+    if (typeof tag !== "string")
+        throw new TypeError(`mailsaiPlusAddress takes a tag that is a string, or nothing. Received: ${describe(tag)}`);
+    return plusAddress(receivingAddress, tag);
+}
+const OPTION_NAMES = {
+    mailsaiWaitForMessage: ["to", "from", "has", "since", "timeout", "agentId"],
+    mailsaiWaitForCode: ["to", "from", "since", "timeout", "agentId"],
+    mailsaiWaitForLink: ["to", "from", "since", "timeout", "agentId", "kind"],
+};
+function describe(v) {
+    if (typeof v === "string")
+        return JSON.stringify(v);
+    if (v === null || typeof v !== "object")
+        return String(v);
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return Object.prototype.toString.call(v);
+    }
+}
+function stringOption(command, name, v) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "string")
+        throw new TypeError(`${command}: ${name} must be a string. Received: ${describe(v)}`);
+    const s = v.trim();
+    // An empty filter is a mistake (an address that was never set), and leaving it out would widen
+    // the wait to mail meant for another test run.
+    if (!s)
+        throw new TypeError(`${command}: ${name} is empty. Give a value, or leave ${name} out.`);
+    return s;
+}
+function timeoutOf(command, v) {
+    if (v === undefined)
+        return DEFAULT_TIMEOUT_SECONDS;
+    if (typeof v !== "number" || !Number.isFinite(v) || v < 0) {
+        throw new TypeError(`${command}: timeout is the seconds to wait in all, a number from 0 up. Received: ${describe(v)}`);
+    }
+    return Math.ceil(v);
+}
+/** A wait command's options, checked: an unknown option, an empty filter or a bad timeout throws,
+ *  and mailsaiWaitForCode and mailsaiWaitForLink set `has` themselves. */
+export function waitPlan(command, input) {
+    const given = input === undefined || input === null ? {} : input;
+    if (typeof given !== "object" || Array.isArray(given)) {
+        throw new TypeError(`${command} takes an options object, such as { to: email }. Received: ${describe(input)}`);
+    }
+    const o = given;
+    const names = OPTION_NAMES[command];
+    for (const key of Object.keys(o)) {
+        if (o[key] !== undefined && !names.includes(key))
+            throw new TypeError(`${command} has no option "${key}". Its options are ${names.join(", ")}.`);
+    }
+    const plan = { timeout: timeoutOf(command, o.timeout) };
+    for (const key of ["to", "from", "since", "agentId"]) {
+        const v = stringOption(command, key, o[key]);
+        if (v !== undefined)
+            plan[key] = v;
+    }
+    if (command === "mailsaiWaitForCode")
+        plan.has = "code";
+    else if (command === "mailsaiWaitForLink") {
+        plan.has = "link";
+        if (o.kind !== undefined) {
+            if (!WANTED_KINDS.includes(o.kind)) {
+                throw new TypeError(`${command}: kind must be one of ${WANTED_KINDS.map((k) => `"${k}"`).join(", ")}. Received: ${describe(o.kind)}`);
+            }
+            plan.kind = o.kind;
+        }
+    }
+    else if (o.has !== undefined) {
+        if (o.has !== "code" && o.has !== "link")
+            throw new TypeError(`${command}: has must be "code" or "link". Received: ${describe(o.has)}`);
+        plan.has = o.has;
+    }
+    return plan;
+}
+/** The filters, as the Command Log line and the errors show them. */
+export function describeFilters(plan) {
+    const parts = [];
+    if (plan.to)
+        parts.push(`to: ${plan.to}`);
+    if (plan.from)
+        parts.push(`from: ${plan.from}`);
+    if (plan.has)
+        parts.push(`has: ${plan.has}`);
+    if (plan.kind)
+        parts.push(`kind: ${plan.kind}`);
+    if (plan.since)
+        parts.push(`since: ${plan.since}`);
+    if (plan.agentId)
+        parts.push(`agent: ${plan.agentId}`);
+    return parts.length ? parts.join(", ") : "any received mail";
+}
+/** The seconds the next wait call asks for: what is left of the timeout, at most 50. */
+export function nextWaitSeconds(left) {
+    return Math.max(0, Math.min(MAX_WAIT_SECONDS, left));
+}
+/** How a timeout is spent when nothing arrives: 60 → [50, 10], 120 → [50, 50, 20], 0 → [0]. */
+export function splitTimeout(total) {
+    const parts = [nextWaitSeconds(total)];
+    for (let left = total - parts[0]; left > 0; left -= parts[parts.length - 1])
+        parts.push(nextWaitSeconds(left));
+    return parts;
+}
+/** One call to GET /v1/messages/received/wait asking to hold for `seconds`. `timeout` is how long
+ *  Cypress gives the request, in milliseconds: the wait and REQUEST_GRACE_SECONDS more. `since` is
+ *  sent only when given, so the API's own look-back applies. */
+export function waitRequest(baseUrl, apiKey, plan, seconds) {
+    const qs = new URLSearchParams();
+    if (plan.agentId)
+        qs.set("agent_id", plan.agentId);
+    if (plan.from)
+        qs.set("from", plan.from);
+    if (plan.to)
+        qs.set("to", plan.to);
+    if (plan.since)
+        qs.set("since", plan.since);
+    if (plan.has)
+        qs.set("has", plan.has);
+    qs.set("timeout", String(seconds));
+    return {
+        method: "GET",
+        url: `${baseUrlOf(baseUrl)}/api/v1/messages/received/wait?${qs.toString()}`,
+        headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+        timeout: (seconds + REQUEST_GRACE_SECONDS) * 1000,
+    };
+}
+function header(headers, name) {
+    if (!headers)
+        return null;
+    for (const [k, v] of Object.entries(headers)) {
+        if (k.toLowerCase() === name)
+            return Array.isArray(v) ? (v[0] ?? null) : (v ?? null);
+    }
+    return null;
+}
+/** `Retry-After` in seconds: a number of seconds or an HTTP date. Null when absent or unreadable. */
+export function parseRetryAfter(value, now = Date.now()) {
+    if (!value || !value.trim())
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds);
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? null : Math.max(0, (at - now) / 1000);
+}
+function asObject(body) {
+    let b = body;
+    // cy.request parses a JSON body only when the answer says it is JSON.
+    if (typeof b === "string") {
+        try {
+            b = JSON.parse(b);
+        }
+        catch {
+            return null;
+        }
+    }
+    return b !== null && typeof b === "object" && !Array.isArray(b) ? b : null;
+}
+function str(v) {
+    return typeof v === "string" && v ? v : null;
+}
+/** What one wait call's answer means: a message, nothing in time, a 429, or an error. */
+export function readWaitResponse(status, body, headers) {
+    const b = asObject(body);
+    if (status >= 200 && status < 300) {
+        if (b && b.message !== null && typeof b.message === "object" && !Array.isArray(b.message)) {
+            return { kind: "message", message: b.message };
+        }
+        if (b && b.message === null)
+            return { kind: "timed_out" };
+        return {
+            kind: "error",
+            error: {
+                status,
+                type: "api_error",
+                code: "unexpected_response",
+                message: "The answer was not a mails.ai wait result ({ message, timed_out }). Is MAILS_BASE_URL the API's address?",
+                param: null,
+                requestId: null,
+                upgradeUrl: null,
+            },
+        };
+    }
+    const e = b && b.error !== null && typeof b.error === "object" ? b.error : null;
+    const error = {
+        status,
+        type: str(e?.type) ?? (status === 429 ? "rate_limit_error" : "api_error"),
+        code: str(e?.code) ?? "unknown",
+        message: str(e?.message) ?? `The API answered ${status} without a mails.ai error body. Is MAILS_BASE_URL the API's address?`,
+        param: str(e?.param),
+        requestId: str(e?.request_id) ?? header(headers, "x-request-id"),
+        upgradeUrl: str(e?.upgrade_url),
+    };
+    if (status !== 429)
+        return { kind: "error", error };
+    const fromHeader = parseRetryAfter(header(headers, "retry-after"));
+    const fromBody = typeof e?.retry_after_seconds === "number" && Number.isFinite(e.retry_after_seconds) ? e.retry_after_seconds : null;
+    return { kind: "rate_limited", error, retryAfterSeconds: fromHeader ?? fromBody, waitHelps: !(e && e.resets_at === null) };
+}
+/** Whole seconds to pause after a 429 before trying again: what the answer asked for, else 1, 2,
+ *  4 then 8 for 429s in a row (`times` is how many came before this one), at most
+ *  MAX_RETRY_PAUSE_SECONDS. Null when no wait lifts the limit. */
+export function retryPause(answer, times) {
+    if (!answer.waitHelps)
+        return null;
+    const s = answer.retryAfterSeconds ?? Math.min(8, 2 ** times);
+    return Math.min(MAX_RETRY_PAUSE_SECONDS, Math.max(1, Math.ceil(s)));
+}
+/** The error of a refused wait, carrying the API's code and message, and on a 402 ending with the
+ *  link to change plan, so a failed CI run says where to go. */
+export class MailsaiApiError extends Error {
+    status;
+    type;
+    code;
+    param;
+    requestId;
+    upgradeUrl;
+    constructor(command, e, extra = "") {
+        const upgrade = e.upgradeUrl ? ` Change your plan: ${e.upgradeUrl}` : "";
+        super(`${command}: mails.ai answered ${e.status} ${e.code}: ${e.message}${extra}${upgrade}${e.requestId ? ` (request ${e.requestId})` : ""}`);
+        this.name = "MailsaiApiError";
+        this.status = e.status;
+        this.type = e.type;
+        this.code = e.code;
+        this.param = e.param;
+        this.requestId = e.requestId;
+        this.upgradeUrl = e.upgradeUrl ?? null;
+    }
+}
+/** The error of a 429 the rest of the timeout cannot wait out. */
+export function rateLimitError(command, e, pause, left, timeout) {
+    const why = pause === null
+        ? " Waiting does not lift this limit."
+        : ` Waiting for it takes ${pause} s, more than the ${left} s left of this command's ${timeout} s timeout.`;
+    return new MailsaiApiError(command, e, why);
+}
+/** The error when nothing matching arrived within the timeout. */
+export function noMailError(command, plan) {
+    return new Error(`${command}: no email arrived within ${plan.timeout} s matching ${describeFilters(plan)}.`);
+}
+/**
+ * What a wait does after the answer to a call that asked to hold for `seconds`: yield the message,
+ * make the next call while time is left (a timeout of 60 is a 50 s call, then a 10 s one), pause
+ * after a 429 for as long as it asks when the rest of the timeout covers the pause, or fail.
+ */
+export function afterAnswer(command, plan, state, seconds, answer) {
+    switch (answer.kind) {
+        case "message":
+            return { do: "yield", message: answer.message };
+        case "timed_out": {
+            const left = state.left - seconds;
+            return left > 0 ? { do: "call", state: { left, limited: 0 } } : { do: "fail", error: noMailError(command, plan) };
+        }
+        case "rate_limited": {
+            const pause = retryPause(answer, state.limited);
+            if (pause === null || pause > state.left)
+                return { do: "fail", error: rateLimitError(command, answer.error, pause, state.left, plan.timeout) };
+            return { do: "pause", seconds: pause, state: { left: state.left - pause, limited: state.limited + 1 } };
+        }
+        case "error":
+            return { do: "fail", error: new MailsaiApiError(command, answer.error) };
+    }
+}
+// ── what the commands yield ─────────────────────────────────────────────────────────────────
+/** The message, as the Command Log and the errors name it. */
+export function messageLabel(message) {
+    return message.subject ? `${message.id} ("${message.subject}")` : String(message.id);
+}
+/** The code mailsaiWaitForCode yields: `codes[0].value`, or null when there is none. */
+export function codeOf(message) {
+    const first = Array.isArray(message.codes) ? message.codes[0] : undefined;
+    return first && typeof first.value === "string" && first.value ? first.value : null;
+}
+/** The link mailsaiWaitForLink yields: the first of `kind`, or without one the first verify,
+ *  sign_in or reset_password link. Never an unsubscribe link; null when none fits. */
+export function linkOf(message, kind) {
+    const links = Array.isArray(message.links) ? message.links : [];
+    const hit = links.find((l) => l !== null &&
+        typeof l === "object" &&
+        typeof l.url === "string" &&
+        l.url !== "" &&
+        l.kind !== "unsubscribe" &&
+        (kind ? l.kind === kind : ACTION_LINK_KINDS.includes(l.kind)));
+    return hit ? hit.url : null;
+}
+/** The error when the message mailsaiWaitForCode got has no code. */
+export function noCodeError(command, message) {
+    return new Error(`${command}: the email ${messageLabel(message)} has no code.`);
+}
+/** The error when the message mailsaiWaitForLink got has no link it may yield, naming the kinds it has. */
+export function noLinkError(command, message, kind) {
+    const wanted = kind ? `link of kind "${kind}"` : "verify, sign_in or reset_password link";
+    const counts = new Map();
+    for (const l of Array.isArray(message.links) ? message.links : [])
+        counts.set(String(l?.kind), (counts.get(String(l?.kind)) ?? 0) + 1);
+    const has = counts.size ? ` Its links: ${[...counts].map(([k, n]) => `${k} (${n})`).join(", ")}.` : " It has no links.";
+    return new Error(`${command}: the email ${messageLabel(message)} has no ${wanted}.${has}`);
+}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/// <reference types="cypress" preserve="true" />
+import { type MailsaiReceivedMessage, type MailsaiWaitForCodeOptions, type MailsaiWaitForLinkOptions, type MailsaiWaitOptions } from "./core.js";
+export type { LinkKind, MailsaiLinkKind, MailsaiOmittedAttachment, MailsaiReceivedAttachment, MailsaiReceivedMessage, MailsaiWaitForCodeOptions, MailsaiWaitForLinkOptions, MailsaiWaitOptions, } from "./core.js";
+export { MailsaiApiError } from "./core.js";
+declare global {
+    namespace Cypress {
+        interface Chainable<Subject = any> {
+            /**
+             * A new email address for this test run: a plus address of MAILS_RECEIVING_ADDRESS, which
+             * reaches the same agent. Without a tag, a new one per call (`run-<time>-<4 random>`).
+             * @example cy.mailsaiPlusAddress().then((email) => cy.get("[data-cy=email]").type(email))
+             */
+            mailsaiPlusAddress(tag?: string): Chainable<string>;
+            /**
+             * The newest received email matching the filters, waiting for one to arrive for up to
+             * `timeout` seconds in all (60 by default). Fails the test when none arrives.
+             * @example cy.mailsaiWaitForMessage({ to: email }).its("subject").should("contain", "Welcome")
+             */
+            mailsaiWaitForMessage(options?: MailsaiWaitOptions): Chainable<MailsaiReceivedMessage>;
+            /**
+             * The verification code in the newest email with one that matches the filters, waiting for
+             * it as mailsaiWaitForMessage does.
+             * @example cy.mailsaiWaitForCode({ to: email }).then((code) => cy.get("[data-cy=code]").type(code))
+             */
+            mailsaiWaitForCode(options?: MailsaiWaitForCodeOptions): Chainable<string>;
+            /**
+             * The link in the newest email with a verify, sign-in or password-reset link that matches
+             * the filters: the first of `kind`, or without it the first verify, sign_in or
+             * reset_password link. Never an unsubscribe link.
+             * @example cy.mailsaiWaitForLink({ to: email }).then((url) => cy.visit(url))
+             */
+            mailsaiWaitForLink(options?: MailsaiWaitForLinkOptions): Chainable<string>;
+        }
+    }
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAeA,OAAO,EAkBL,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,EAIxB,MAAM,WAAW,CAAC;AAEnB,YAAY,EACV,QAAQ,EACR,eAAe,EACf,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,yBAAyB,EACzB,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,SAAS,CAAC,OAAO,GAAG,GAAG;YAC/B;;;;eAIG;YACH,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;YACpD;;;;eAIG;YACH,qBAAqB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC,sBAAsB,CAAC,CAAC;YACvF;;;;eAIG;YACH,kBAAkB,CAAC,OAAO,CAAC,EAAE,yBAAyB,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;YAC3E;;;;;eAKG;YACH,kBAAkB,CAAC,OAAO,CAAC,EAAE,yBAAyB,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;SAC5E;KACF;CACF"}

package/dist/index.js

@@ -0,0 +1,108 @@
+/// <reference types="cypress" preserve="true" />
+// @mailsai/cypress: Cypress commands for testing the email an app sends at sign-up, sign-in and
+// password reset. `import "@mailsai/cypress"` in the support file registers them:
+//
+//   cy.mailsaiPlusAddress()            a new address for this run (a plus address of one agent)
+//   cy.mailsaiWaitForMessage({ to })   the email sent to it, once it arrives
+//   cy.mailsaiWaitForCode({ to })      its verification code
+//   cy.mailsaiWaitForLink({ to })      its verify, sign-in or password-reset link
+//
+// The logic is in core.ts. This file reads the settings, makes the requests and writes one Command
+// Log line per command. The API key never reaches the Command Log, a screenshot or a video: the
+// settings are read with cy.env() and { log: false }, and every request is made with { log: false }
+// and failOnStatusCode: false, since Cypress's own error for a failed status prints the request's
+// headers, the key among them.
+import { afterAnswer, baseUrlOf, codeOf, CONFIG_KEYS, configFrom, describeFilters, linkOf, messageLabel, missingSetting, nextWaitSeconds, noCodeError, noLinkError, plusAddressFor, readWaitResponse, waitPlan, waitRequest, } from "./core.js";
+export { MailsaiApiError } from "./core.js";
+/** The settings, read so that their values never reach the Command Log: with cy.env() (Cypress
+ *  15.10 and later; Cypress 16 removed Cypress.env()), else with Cypress.env(). */
+function settings() {
+    const keys = [...CONFIG_KEYS];
+    if (typeof cy.env === "function") {
+        return cy.env(keys, { log: false }).then((env) => configFrom(env));
+    }
+    const legacy = Cypress;
+    return cy.wrap(configFrom(Object.fromEntries(keys.map((k) => [k, legacy.env(k)]))), { log: false });
+}
+/** Marks the command's log line failed, then fails the test with `err`. */
+function fail(log, err) {
+    if (err instanceof Error)
+        log.error(err);
+    throw err;
+}
+/** `fn()`, with a throw marking the log line failed first. */
+function attempt(log, fn) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        return fail(log, err);
+    }
+}
+Cypress.Commands.add("mailsaiPlusAddress", (tag) => {
+    const log = Cypress.log({ name: "mailsaiPlusAddress", message: tag ?? "", autoEnd: false });
+    return settings().then((config) => {
+        const address = attempt(log, () => {
+            if (!config.receivingAddress)
+                throw missingSetting("mailsaiPlusAddress", "MAILS_RECEIVING_ADDRESS");
+            return plusAddressFor(config.receivingAddress, tag);
+        });
+        log.set({ message: address, consoleProps: () => ({ "Receiving address": config.receivingAddress, Yielded: address }) }).end();
+        return cy.wrap(address, { log: false });
+    });
+});
+/** One wait call, then what afterAnswer() says: yield, call again, pause after a 429, or fail. */
+function poll(w, state) {
+    const seconds = nextWaitSeconds(state.left);
+    const req = waitRequest(w.baseUrl, w.apiKey, w.plan, seconds);
+    return cy
+        .request({ method: req.method, url: req.url, headers: req.headers, timeout: req.timeout, failOnStatusCode: false, log: false })
+        .then((res) => {
+        const step = afterAnswer(w.command, w.plan, state, seconds, readWaitResponse(res.status, res.body, res.headers));
+        switch (step.do) {
+            case "yield":
+                return cy.wrap(step.message, { log: false });
+            case "call":
+                return poll(w, step.state);
+            case "pause":
+                return cy.wait(step.seconds * 1000, { log: false }).then(() => poll(w, step.state));
+            case "fail":
+                return fail(w.log, step.error);
+        }
+    });
+}
+/** A wait command: check the options, read the settings, wait, then yield what `pick` takes from
+ *  the message. */
+function waitFor(command, options, pick) {
+    const log = Cypress.log({ name: command, message: "", autoEnd: false });
+    const given = attempt(log, () => waitPlan(command, options));
+    return settings().then((config) => {
+        const w = attempt(log, () => {
+            if (!config.apiKey)
+                throw missingSetting(command, "MAILS_API_KEY");
+            const plan = !given.agentId && config.agentId ? { ...given, agentId: config.agentId } : given;
+            return { command, plan, baseUrl: baseUrlOf(config.baseUrl), apiKey: config.apiKey, log };
+        });
+        const filters = describeFilters(w.plan);
+        const props = { Filters: filters, "Timeout (s)": w.plan.timeout, API: w.baseUrl };
+        log.set({ message: `${filters}, within ${w.plan.timeout} s`, consoleProps: () => props });
+        return poll(w, { left: w.plan.timeout, limited: 0 }).then((message) => {
+            const { value, shown } = attempt(log, () => pick(message, w.plan));
+            log.set({ message: `${filters} → ${shown}`, consoleProps: () => ({ ...props, Message: message, Yielded: value }) }).end();
+            return cy.wrap(value, { log: false });
+        });
+    });
+}
+Cypress.Commands.add("mailsaiWaitForMessage", (options) => waitFor("mailsaiWaitForMessage", options, (message) => ({ value: message, shown: messageLabel(message) })));
+Cypress.Commands.add("mailsaiWaitForCode", (options) => waitFor("mailsaiWaitForCode", options, (message) => {
+    const code = codeOf(message);
+    if (code === null)
+        throw noCodeError("mailsaiWaitForCode", message);
+    return { value: code, shown: code };
+}));
+Cypress.Commands.add("mailsaiWaitForLink", (options) => waitFor("mailsaiWaitForLink", options, (message, plan) => {
+    const url = linkOf(message, plan.kind);
+    if (url === null)
+        throw noLinkError("mailsaiWaitForLink", message, plan.kind);
+    return { value: url, shown: url };
+}));

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@mailsai/cypress",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Cypress commands for mails.ai: give each test run its own email address, then wait for the sign-up code or link sent to it.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test:e2e": "npm run build && node e2e/run.mjs"
+  },
+  "keywords": [
+    "cypress",
+    "cypress-plugin",
+    "email",
+    "email-testing",
+    "otp",
+    "verification-code",
+    "magic-link",
+    "e2e",
+    "mails.ai"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mailsai/mailsai.git",
+    "directory": "packages/cypress"
+  },
+  "homepage": "https://mails.ai",
+  "bugs": { "url": "https://mails.ai/contact" },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "cypress": ">=13.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "cypress": "^16.2.0",
+    "typescript": "^5"
+  }
+}