@inboxical/cypress 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ozer SUBASI
+
+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

@@ -0,0 +1,81 @@
+# @inboxical/cypress
+
+[Inboxical](https://inboxical.com) plugin for [Cypress](https://www.cypress.io/) — test email flows in your E2E tests.
+
+## Install
+
+```bash
+npm install @inboxical/cypress @inboxical/sdk
+```
+
+## Setup
+
+### 1. Register tasks in `cypress.config.ts`
+
+```ts
+import { defineConfig } from "cypress";
+import { setupInboxical } from "@inboxical/cypress";
+
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on, config) {
+      setupInboxical(on, config, {
+        apiKey: process.env.INBOXICAL_API_KEY,
+      });
+      return config;
+    },
+  },
+});
+```
+
+### 2. Import commands in `cypress/support/commands.ts`
+
+```ts
+import "@inboxical/cypress/commands";
+```
+
+## Usage
+
+```ts
+describe("Email verification", () => {
+  it("should verify email with OTP", () => {
+    cy.inboxicalCreateInbox().then(({ id, email }) => {
+      cy.visit("/signup");
+      cy.get("#email").type(email);
+      cy.get("form").submit();
+
+      cy.inboxicalWaitForMessage(id, { timeout: 30 }).then((message) => {
+        expect(message.subject).to.include("Verify");
+
+        cy.inboxicalExtractCode(message).then((code) => {
+          cy.get("#otp-input").type(code);
+          cy.get("#verify-btn").click();
+          cy.contains("Welcome").should("be.visible");
+        });
+      });
+
+      cy.inboxicalDeleteInbox(id);
+    });
+  });
+});
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `cy.inboxicalCreateInbox(options?)` | Create a disposable test inbox |
+| `cy.inboxicalWaitForMessage(inboxId, options?)` | Wait for a message (long-poll) |
+| `cy.inboxicalGetMessages(inboxId)` | Get all messages in inbox |
+| `cy.inboxicalGetLatestMessage(inboxId)` | Get the latest message |
+| `cy.inboxicalDeleteInbox(inboxId)` | Delete inbox and messages |
+| `cy.inboxicalExtractCode(message, pattern?)` | Extract OTP/verification code |
+
+## Related
+
+- [`@inboxical/sdk`](https://github.com/ozers/inboxical-sdk) — Core Node.js SDK
+- [`@inboxical/playwright`](https://github.com/ozers/inboxical-playwright) — Playwright helper
+
+## License
+
+MIT

package/dist/commands.d.ts

@@ -0,0 +1,66 @@
+import type { Message } from "@inboxical/sdk";
+/**
+ * Type declarations for Inboxical Cypress custom commands.
+ */
+declare global {
+    namespace Cypress {
+        interface Chainable {
+            /**
+             * Create a new Inboxical test inbox.
+             * @returns Object with `id` and `email` properties.
+             *
+             * @example
+             * ```ts
+             * cy.inboxicalCreateInbox().then(({ id, email }) => {
+             *   cy.get("#email-input").type(email);
+             * });
+             * ```
+             */
+            inboxicalCreateInbox(options?: {
+                name?: string;
+                domain?: string;
+            }): Chainable<{
+                id: string;
+                email: string;
+            }>;
+            /**
+             * Wait for a message to arrive in the inbox (long-poll).
+             * @param inboxId - The inbox ID to watch.
+             * @param options - Optional timeout (seconds) and since (ISO date).
+             *
+             * @example
+             * ```ts
+             * cy.inboxicalWaitForMessage(inboxId, { timeout: 30 }).then((msg) => {
+             *   expect(msg.subject).to.include("Verify");
+             * });
+             * ```
+             */
+            inboxicalWaitForMessage(inboxId: string, options?: {
+                timeout?: number;
+                since?: string;
+            }): Chainable<Message>;
+            /**
+             * Get all messages in an inbox.
+             * @param inboxId - The inbox ID.
+             */
+            inboxicalGetMessages(inboxId: string): Chainable<Message[]>;
+            /**
+             * Get the latest message in an inbox.
+             * @param inboxId - The inbox ID.
+             */
+            inboxicalGetLatestMessage(inboxId: string): Chainable<Message>;
+            /**
+             * Delete a Inboxical test inbox and all its messages.
+             * @param inboxId - The inbox ID to delete.
+             */
+            inboxicalDeleteInbox(inboxId: string): Chainable<void>;
+            /**
+             * Extract an OTP/verification code from a message.
+             * @param message - The message to extract from.
+             * @param pattern - Optional regex pattern string (must contain a capture group).
+             */
+            inboxicalExtractCode(message: Message, pattern?: string): Chainable<string | null>;
+        }
+    }
+}
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;GAEG;AACH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,SAAS;YACjB;;;;;;;;;;eAUG;YACH,oBAAoB,CAAC,OAAO,CAAC,EAAE;gBAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;gBACd,MAAM,CAAC,EAAE,MAAM,CAAC;aACjB,GAAG,SAAS,CAAC;gBAAE,EAAE,EAAE,MAAM,CAAC;gBAAC,KAAK,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;YAE7C;;;;;;;;;;;eAWG;YACH,uBAAuB,CACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;gBAAE,OAAO,CAAC,EAAE,MAAM,CAAC;gBAAC,KAAK,CAAC,EAAE,MAAM,CAAA;aAAE,GAC7C,SAAS,CAAC,OAAO,CAAC,CAAC;YAEtB;;;eAGG;YACH,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;YAE5D;;;eAGG;YACH,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;YAE/D;;;eAGG;YACH,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YAEvD;;;;eAIG;YACH,oBAAoB,CAClB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;SAC7B;KACF;CACF"}

package/dist/commands.js

@@ -0,0 +1,28 @@
+/**
+ * Register Inboxical custom commands.
+ *
+ * Import this file in your `cypress/support/commands.ts`:
+ * ```ts
+ * import "@inboxical/cypress/commands";
+ * ```
+ */
+Cypress.Commands.add("inboxicalCreateInbox", (options) => {
+    return cy.task("inboxicalCreateInbox", options ?? null);
+});
+Cypress.Commands.add("inboxicalWaitForMessage", (inboxId, options) => {
+    return cy.task("inboxicalWaitForMessage", { inboxId, ...options }, { timeout: ((options?.timeout ?? 30) + 10) * 1000 });
+});
+Cypress.Commands.add("inboxicalGetMessages", (inboxId) => {
+    return cy.task("inboxicalGetMessages", inboxId);
+});
+Cypress.Commands.add("inboxicalGetLatestMessage", (inboxId) => {
+    return cy.task("inboxicalGetLatestMessage", inboxId);
+});
+Cypress.Commands.add("inboxicalDeleteInbox", (inboxId) => {
+    return cy.task("inboxicalDeleteInbox", inboxId);
+});
+Cypress.Commands.add("inboxicalExtractCode", (message, pattern) => {
+    return cy.task("inboxicalExtractCode", { message, pattern });
+});
+export {};
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAwEA;;;;;;;GAOG;AACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAClB,sBAAsB,EACtB,CAAC,OAA4C,EAAE,EAAE;IAC/C,OAAO,EAAE,CAAC,IAAI,CAAC,sBAAsB,EAAE,OAAO,IAAI,IAAI,CAAC,CAAC;AAC1D,CAAC,CACF,CAAC;AAEF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAClB,yBAAyB,EACzB,CAAC,OAAe,EAAE,OAA8C,EAAE,EAAE;IAClE,OAAO,EAAE,CAAC,IAAI,CACZ,yBAAyB,EACzB,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,EACvB,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,CACpD,CAAC;AACJ,CAAC,CACF,CAAC;AAEF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,sBAAsB,EAAE,CAAC,OAAe,EAAE,EAAE;IAC/D,OAAO,EAAE,CAAC,IAAI,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,2BAA2B,EAAE,CAAC,OAAe,EAAE,EAAE;IACpE,OAAO,EAAE,CAAC,IAAI,CAAC,2BAA2B,EAAE,OAAO,CAAC,CAAC;AACvD,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,sBAAsB,EAAE,CAAC,OAAe,EAAE,EAAE;IAC/D,OAAO,EAAE,CAAC,IAAI,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAClB,sBAAsB,EACtB,CAAC,OAAgB,EAAE,OAAgB,EAAE,EAAE;IACrC,OAAO,EAAE,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;AAC/D,CAAC,CACF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import type { Inbox, Message } from "@inboxical/sdk";
+export type { Inbox, Message };
+export interface InboxicalCypressConfig {
+    /** Inboxical API key. Defaults to INBOXICAL_API_KEY env var. */
+    apiKey?: string;
+    /** Base URL override. */
+    baseUrl?: string;
+}
+/**
+ * Register Inboxical tasks in your Cypress config file.
+ *
+ * @example
+ * ```ts
+ * // cypress.config.ts
+ * import { defineConfig } from "cypress";
+ * import { setupInboxical } from "@inboxical/cypress";
+ *
+ * export default defineConfig({
+ *   e2e: {
+ *     setupNodeEvents(on, config) {
+ *       setupInboxical(on, config, {
+ *         apiKey: process.env.INBOXICAL_API_KEY,
+ *       });
+ *       return config;
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function setupInboxical(on: Cypress.PluginEvents, config: Cypress.PluginConfigOptions, options?: InboxicalCypressConfig): void;
+//# 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":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAErD,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAE/B,MAAM,WAAW,sBAAsB;IACrC,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,OAAO,CAAC,YAAY,EACxB,MAAM,EAAE,OAAO,CAAC,mBAAmB,EACnC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,IAAI,CAiEN"}

package/dist/index.js

@@ -0,0 +1,70 @@
+import { Inboxical } from "@inboxical/sdk";
+/**
+ * Register Inboxical tasks in your Cypress config file.
+ *
+ * @example
+ * ```ts
+ * // cypress.config.ts
+ * import { defineConfig } from "cypress";
+ * import { setupInboxical } from "@inboxical/cypress";
+ *
+ * export default defineConfig({
+ *   e2e: {
+ *     setupNodeEvents(on, config) {
+ *       setupInboxical(on, config, {
+ *         apiKey: process.env.INBOXICAL_API_KEY,
+ *       });
+ *       return config;
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function setupInboxical(on, config, options) {
+    const apiKey = options?.apiKey || config.env["INBOXICAL_API_KEY"] || process.env.INBOXICAL_API_KEY;
+    if (!apiKey) {
+        throw new Error("Inboxical API key is required. Set INBOXICAL_API_KEY env var or pass apiKey in options.");
+    }
+    const client = new Inboxical({
+        apiKey,
+        baseUrl: options?.baseUrl,
+    });
+    on("task", {
+        async inboxicalCreateInbox(args) {
+            const inbox = await client.createInbox(args ?? undefined);
+            return { id: inbox.id, email: inbox.email_address };
+        },
+        async inboxicalGetInbox(inboxId) {
+            return client.getInbox(inboxId);
+        },
+        async inboxicalDeleteInbox(inboxId) {
+            await client.deleteInbox(inboxId);
+            return null;
+        },
+        async inboxicalGetMessages(inboxId) {
+            const result = await client.getMessages(inboxId);
+            return result.messages;
+        },
+        async inboxicalGetLatestMessage(inboxId) {
+            return client.getLatestMessage(inboxId);
+        },
+        async inboxicalWaitForMessage(args) {
+            return client.waitForMessage(args.inboxId, {
+                timeout: args.timeout,
+                since: args.since,
+            });
+        },
+        async inboxicalGetMessage(messageId) {
+            return client.getMessage(messageId);
+        },
+        async inboxicalDeleteMessage(messageId) {
+            await client.deleteMessage(messageId);
+            return null;
+        },
+        inboxicalExtractCode(args) {
+            const patternRegex = args.pattern ? new RegExp(args.pattern) : undefined;
+            return client.extractCode(args.message, { pattern: patternRegex });
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAY3C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,cAAc,CAC5B,EAAwB,EACxB,MAAmC,EACnC,OAAgC;IAEhC,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IAEnG,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,MAAM;QACN,OAAO,EAAE,OAAO,EAAE,OAAO;KAC1B,CAAC,CAAC;IAEH,EAAE,CAAC,MAAM,EAAE;QACT,KAAK,CAAC,oBAAoB,CACxB,IAA+C;YAE/C,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,IAAI,IAAI,SAAS,CAAC,CAAC;YAC1D,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC;QACtD,CAAC;QAED,KAAK,CAAC,iBAAiB,CAAC,OAAe;YACrC,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QAED,KAAK,CAAC,oBAAoB,CAAC,OAAe;YACxC,MAAM,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAClC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,KAAK,CAAC,oBAAoB,CAAC,OAAe;YACxC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YACjD,OAAO,MAAM,CAAC,QAAQ,CAAC;QACzB,CAAC;QAED,KAAK,CAAC,yBAAyB,CAAC,OAAe;YAC7C,OAAO,MAAM,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;QAED,KAAK,CAAC,uBAAuB,CAC3B,IAA2D;YAE3D,OAAO,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE;gBACzC,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,KAAK,EAAE,IAAI,CAAC,KAAK;aAClB,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,mBAAmB,CAAC,SAAiB;YACzC,OAAO,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QACtC,CAAC;QAED,KAAK,CAAC,sBAAsB,CAAC,SAAiB;YAC5C,MAAM,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;YACtC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,oBAAoB,CAClB,IAA4C;YAE5C,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACzE,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;QACrE,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@inboxical/cypress",
+  "version": "0.1.0",
+  "description": "Inboxical Cypress plugin — Email testing commands for Cypress",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./commands": {
+      "import": "./dist/commands.js",
+      "types": "./dist/commands.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "email",
+    "testing",
+    "cypress",
+    "qa",
+    "inbox",
+    "inboxical",
+    "e2e",
+    "otp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ozers/inboxical-cypress.git"
+  },
+  "homepage": "https://inboxical.com",
+  "bugs": {
+    "url": "https://github.com/ozers/inboxical-cypress/issues"
+  },
+  "author": "Inboxical",
+  "license": "MIT",
+  "peerDependencies": {
+    "cypress": ">=12.0.0"
+  },
+  "dependencies": {
+    "@inboxical/sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "cypress": "^13.0.0",
+    "typescript": "^5.4.0"
+  }
+}