@mailpier/inbox 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +24 -0
- package/LICENSE +21 -0
- package/README.md +159 -2
- package/dist/chunk-2NMZ2IWD.js +524 -0
- package/dist/cli.cjs +751 -0
- package/dist/cli.d.cts +1 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +244 -0
- package/dist/client-DD8Tr4-3.d.cts +415 -0
- package/dist/client-DD8Tr4-3.d.ts +415 -0
- package/dist/cypress/commands.cjs +94 -0
- package/dist/cypress/commands.d.cts +58 -0
- package/dist/cypress/commands.d.ts +58 -0
- package/dist/cypress/commands.js +68 -0
- package/dist/cypress/index.cjs +575 -0
- package/dist/cypress/index.d.cts +47 -0
- package/dist/cypress/index.d.ts +47 -0
- package/dist/cypress/index.js +40 -0
- package/dist/index.cjs +557 -0
- package/dist/index.d.cts +26 -0
- package/dist/index.d.ts +26 -0
- package/dist/index.js +22 -0
- package/dist/playwright.cjs +639 -0
- package/dist/playwright.d.cts +65 -0
- package/dist/playwright.d.ts +65 -0
- package/dist/playwright.js +104 -0
- package/dist/testing/index.cjs +683 -0
- package/dist/testing/index.d.cts +106 -0
- package/dist/testing/index.d.ts +106 -0
- package/dist/testing/index.js +654 -0
- package/package.json +112 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.1 (2026-11-16)
|
|
4
|
+
- Webhook inspector: `getWebhookEndpoint`, `createWebhookUrl`, `waitForWebhook` (long-poll, `MailPierWebhookTimeoutError`, a
|
|
5
|
+
`MailPierTimeoutError`), `listWebhooks`, `getWebhook`, `getWebhookBody`, `deleteWebhook`, `deleteWebhooks`, `replayWebhook`,
|
|
6
|
+
`addWebhookResponse`, `listWebhookResponses`, `deleteWebhookResponse`; `WebhookRequest` with `jsonBody()`, `header()`, `bytes()`.
|
|
7
|
+
Replay and adding a custom response are not retried on 502/504/network errors (they must not run twice).
|
|
8
|
+
- `mailpier listen <port|url> [--path] [--key] [--api]` (npm bin; `npx @mailpier/inbox listen 5000`): forwards caught requests to
|
|
9
|
+
localhost. The caught path stays below the target's path (`%` escaped except `%2F`, a path that would climb out with `/../` is
|
|
10
|
+
skipped), control characters from the request are printed as `\xHH`, and every header "Hide secrets" masks is left out.
|
|
11
|
+
- Fake API: like the real catcher, no `X-MailPier-Request-Id` on catch answers, and "Hide secrets" also masks `X-Api-Key`, `Api-Key`,
|
|
12
|
+
`X-Auth-Token`, `X-Access-Token` and `X-Amz-Security-Token`.
|
|
13
|
+
- Playwright fixture: `inbox.createWebhookUrl()`, `inbox.waitForWebhook(path)` (next request per path, none from before the test).
|
|
14
|
+
Cypress: `cy.mailpierCreateWebhookUrl()`, `cy.mailpierWaitForWebhook(path)` (tasks `mailpier:createWebhookUrl`,
|
|
15
|
+
`mailpier:waitForWebhook`).
|
|
16
|
+
- Fake API: the `/v1/hooks/*` endpoints, `catchWebhook()`, a catch route at `webhookUrl`, `replays`, option `webhooks: false`.
|
|
17
|
+
|
|
18
|
+
## 0.1.0 (2026-11-14)
|
|
19
|
+
- First version: `MailPierInbox` (newAddress, waitForMessage, waitForNextMessage, listMessages, getMessage, getRaw,
|
|
20
|
+
getAttachment, deleteMessage, deleteAll, me), `message.code` / `message.firstLink()`, retries on 429 (Retry-After) and
|
|
21
|
+
502/503/504/network errors, ESM + CJS builds with types.
|
|
22
|
+
- `@mailpier/inbox/playwright`: `test`/`expect` with the `inbox` fixture (newAddress, waitForMessage, waitForCode, waitForLink).
|
|
23
|
+
- `@mailpier/inbox/cypress` (`mailpierTasks`) and `@mailpier/inbox/cypress/commands` (`cy.mailpier*`).
|
|
24
|
+
- `@mailpier/inbox/testing`: in-process fake MailPier Inbox API.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Solutions Group Unlimited
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,160 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @mailpier/inbox
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Node.js client for [MailPier Inbox](https://mailpier.io): give each test its own email address, wait for the mail your app
|
|
4
|
+
sends, and read its one-time code and links. Catch your app's **webhooks** too, and forward them to localhost. TypeScript
|
|
5
|
+
types, ESM and CommonJS, Node 18+, no runtime dependencies. Includes a **Playwright fixture**, **Cypress commands**, the
|
|
6
|
+
`mailpier listen` command and a **fake MailPier API** for offline tests.
|
|
7
|
+
|
|
8
|
+
## Quick start
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
import { MailPierInbox } from "@mailpier/inbox";
|
|
12
|
+
const inbox = new MailPierInbox({ apiKey: process.env.MAILPIER_API_KEY });
|
|
13
|
+
const address = await inbox.newAddress({ prefix: "signup" }); // signup-k3v9q2mz7a@qa.acme.mailpier.io
|
|
14
|
+
await signUp(address); // your app sends the mail
|
|
15
|
+
const mail = await inbox.waitForMessage({ to: address, subjectContains: "Confirm", timeoutMs: 60_000 });
|
|
16
|
+
console.log(mail.code, mail.firstLink("verify")); // "482913", "https://app.example.com/verify?t=..."
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Create the API key on your environment's **API keys** page and keep it in a secret (`MAILPIER_API_KEY`).
|
|
20
|
+
|
|
21
|
+
## API
|
|
22
|
+
|
|
23
|
+
| Call | What it does |
|
|
24
|
+
|---|---|
|
|
25
|
+
| `new MailPierInbox({ apiKey?, baseUrl?, maxRetries?, maxRetryDelayMs?, fetch? })` | `apiKey` defaults to `MAILPIER_API_KEY`, `baseUrl` to `MAILPIER_BASE_URL` or `https://api.mailpier.io`. |
|
|
26
|
+
| `newAddress({ prefix?, domain? })` | A fresh random address of the key's environment. |
|
|
27
|
+
| `waitForMessage({ to, subjectContains?, timeoutMs?, since?, afterId?, signal? })` | The **oldest** matching mail received at or after `since`; long-polls (120 s per poll); throws `MailPierTimeoutError`. |
|
|
28
|
+
| `waitForNextMessage(previous, { to, ... })` | The mail after `previous` (never `previous` again, even in the same millisecond). |
|
|
29
|
+
| `listMessages({ to?, subjectContains?, since?, take?, skip? })` | Newest first, at most 100 per call. |
|
|
30
|
+
| `getMessage(id)` / `getRaw(id)` / `getAttachment(id, index)` | Full mail / `.eml` bytes / attachment bytes; `null` when gone. |
|
|
31
|
+
| `deleteMessage(id)` / `deleteAll(to)` | Clean up after a test. |
|
|
32
|
+
| `message.code` / `message.firstLink(contains?)` | The first one-time code; the first link whose URL or text contains `contains`. |
|
|
33
|
+
|
|
34
|
+
Errors throw `MailPierInboxError` with `status` (400, 401 bad key, 403 suspended, 404, 409, 429, 503; 0 = unreachable) and the
|
|
35
|
+
server's message. **429** is retried after `Retry-After`, **502/503/504** and network errors with backoff (0.5, 1, 2 ... s),
|
|
36
|
+
up to `maxRetries` (5) times; other errors are not retried.
|
|
37
|
+
|
|
38
|
+
## Playwright
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
import { test, expect } from "@mailpier/inbox/playwright"; // Playwright's test + an `inbox` fixture
|
|
42
|
+
|
|
43
|
+
test("sign up", async ({ page, inbox }) => {
|
|
44
|
+
const email = await inbox.newAddress();
|
|
45
|
+
await page.getByLabel("Email").fill(email);
|
|
46
|
+
await page.getByRole("button", { name: "Create account" }).click();
|
|
47
|
+
await page.getByLabel("Code").fill(await inbox.waitForCode(email));
|
|
48
|
+
// or: await page.goto(await inbox.waitForLink(email, "verify"));
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The key comes from `MAILPIER_API_KEY` (or `test.use({ mailpierOptions: { apiKey } })`). Each wait returns the **next** mail to that
|
|
53
|
+
address since `newAddress()`. `test.use({ mailpierCleanup: true })` deletes the test's mail afterwards. To merge into your own
|
|
54
|
+
fixtures: `base.extend<MailPierFixtures>(mailpierFixtures)`. Example: `playwright/signup.spec.ts` (runs against a local demo app
|
|
55
|
+
and the fake API: `npm run build && npm run test:e2e`).
|
|
56
|
+
|
|
57
|
+
## Cypress
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
// cypress.config.ts
|
|
61
|
+
import { mailpierTasks } from "@mailpier/inbox/cypress";
|
|
62
|
+
export default defineConfig({ e2e: { setupNodeEvents(on) { on("task", mailpierTasks()); } } });
|
|
63
|
+
|
|
64
|
+
// cypress/support/e2e.ts
|
|
65
|
+
import "@mailpier/inbox/cypress/commands";
|
|
66
|
+
|
|
67
|
+
// a spec
|
|
68
|
+
cy.mailpierNewAddress().then((email) => {
|
|
69
|
+
cy.get("input[name=email]").type(email);
|
|
70
|
+
cy.contains("button", "Create account").click();
|
|
71
|
+
cy.mailpierWaitForCode(email).then((code) => cy.get("input[name=code]").type(code));
|
|
72
|
+
});
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Commands: `cy.mailpierNewAddress({prefix?, domain?})`, `cy.mailpierWaitForMessage(to, {subjectContains?, timeoutMs?})` (yields
|
|
76
|
+
the message JSON plus `code` and `firstLink`), `cy.mailpierWaitForCode(to)`, `cy.mailpierWaitForLink(to, contains?)`,
|
|
77
|
+
`cy.mailpierDeleteAll(to)`. The API key stays in the Cypress Node process (`MAILPIER_API_KEY`); it never reaches the browser.
|
|
78
|
+
Example: `cypress/`.
|
|
79
|
+
|
|
80
|
+
## Webhooks
|
|
81
|
+
|
|
82
|
+
Every environment has a catch URL (`https://hook.gather-io.com/<token>`): any request to it, or to any path below it, is stored
|
|
83
|
+
(method, path, query, headers, body) and can be waited for like a mail. Use a unique path per test, as with addresses.
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
import { test, expect } from "@mailpier/inbox/playwright";
|
|
87
|
+
|
|
88
|
+
test("paying an order sends the order.paid webhook", async ({ page, inbox }) => {
|
|
89
|
+
const hook = await inbox.createWebhookUrl(); // { url: "https://hook.gather-io.com/<token>/t-8f2k1x", path: "/t-8f2k1x" }
|
|
90
|
+
await page.goto("/settings/webhooks");
|
|
91
|
+
await page.getByLabel("Webhook URL").fill(hook.url); // your app sends its webhooks there
|
|
92
|
+
await page.goto("/orders/42");
|
|
93
|
+
await page.getByRole("button", { name: "Pay" }).click();
|
|
94
|
+
|
|
95
|
+
const request = await inbox.waitForWebhook(hook.path, { method: "POST", timeoutSeconds: 30 });
|
|
96
|
+
expect(request.jsonBody()).toMatchObject({ event: "order.paid", orderId: "42" });
|
|
97
|
+
expect(request.header("X-Signature")).toBeTruthy();
|
|
98
|
+
});
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The fixture's `waitForWebhook(path)` returns the next request to that path on each call, and never one caught before the test
|
|
102
|
+
started (so a fixed path like `/stripe` is safe too). Cypress: `cy.mailpierCreateWebhookUrl()` and
|
|
103
|
+
`cy.mailpierWaitForWebhook(path, { method?, timeoutSeconds? })` (yields the request JSON). Runnable examples:
|
|
104
|
+
`playwright/webhook.spec.ts`, `cypress/e2e/webhook.cy.ts`.
|
|
105
|
+
|
|
106
|
+
| Call | What it does |
|
|
107
|
+
|---|---|
|
|
108
|
+
| `getWebhookEndpoint()` | The catch URL, `paused`, `hideSecrets`, `forwardUrl` and the plan's `limits`. |
|
|
109
|
+
| `createWebhookUrl()` | `{ url, path }` with a fresh random path (nothing is stored; any path works without it). |
|
|
110
|
+
| `waitForWebhook({ path?, method?, afterId?, since?, timeoutSeconds?, signal? })` | The **oldest** request newer than `afterId`/`since` whose path starts with `path`; long-polls; throws `MailPierWebhookTimeoutError` (a `MailPierTimeoutError`). Default 60 s. |
|
|
111
|
+
| `listWebhooks({ path?, method?, afterId?, since?, take?, skip? })` | Newest first, at most 100 per call. |
|
|
112
|
+
| `getWebhook(id)` / `getWebhookBody(id)` | Full request / raw body bytes; `null` when gone. |
|
|
113
|
+
| `deleteWebhook(id)` / `deleteWebhooks({ path? })` | Clean up (without `path`: every request of the environment). |
|
|
114
|
+
| `replayWebhook(id, url)` | Sends it again to a **public** URL; `{ status, durationMs }` of the target. A refused URL throws 400, a target that gave no answer 502; never retried on 502/504/network errors (it must not arrive twice). |
|
|
115
|
+
| `addWebhookResponse({ path, status?, method?, contentType?, body?, delayMs? })` | A custom answer (status 200-299/400-599, JSON/text/XML, delay) for requests whose path starts with `path`. |
|
|
116
|
+
| `listWebhookResponses()` / `deleteWebhookResponse(id)` | The environment's custom answers. |
|
|
117
|
+
| `request.jsonBody()` / `request.header(name)` / `request.bytes()` | The body as JSON (throws when it is not), a header (case-insensitive), the body bytes. |
|
|
118
|
+
|
|
119
|
+
A request also has `body` (UTF-8 text, else `null` and `bodyBase64`), `json`, `form` (url-encoded fields), `query`, `headers`,
|
|
120
|
+
`sourceIp` and `status` (what the catch URL answered). With "Hide secrets" on (the default) `Authorization`, `Proxy-Authorization`,
|
|
121
|
+
`Cookie`, `X-Api-Key`, `Api-Key`, `X-Auth-Token`, `X-Access-Token` and `X-Amz-Security-Token` read `***` (webhook signature headers stay
|
|
122
|
+
visible); the query string is stored as sent. Requests are deleted with the environment's mail retention.
|
|
123
|
+
|
|
124
|
+
### Forward webhooks to localhost
|
|
125
|
+
|
|
126
|
+
```
|
|
127
|
+
npx @mailpier/inbox listen 5000 # or: listen http://localhost:5000/api --path /stripe
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Prints the catch URL, then sends every new request to `http://localhost:5000` + its path (same method, query, headers and body)
|
|
131
|
+
and prints `POST /stripe -> 200 (34 ms)`. The key comes from `--key` or `MAILPIER_API_KEY` (`--api` / `MAILPIER_BASE_URL` for
|
|
132
|
+
the API root). It starts after the newest request already caught, reconnects with backoff, and stops on Ctrl+C. Only the given
|
|
133
|
+
target is called; the caller of the catch URL already got the environment's answer.
|
|
134
|
+
|
|
135
|
+
## Offline tests: the fake API
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
import { startFakeMailPier } from "@mailpier/inbox/testing";
|
|
139
|
+
const fake = await startFakeMailPier(); // 127.0.0.1, key "mpi_test_key", zone qa.demo.mailpier.io
|
|
140
|
+
const inbox = new MailPierInbox({ apiKey: fake.apiKey, baseUrl: fake.url });
|
|
141
|
+
fake.deliver({ to: address, subject: "Confirm", text: "Your code is 482913" }); // what MailPier would have received
|
|
142
|
+
await fake.close();
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
It implements every public endpoint with the real JSON shapes and errors, extracts links and 4-8 digit codes like the service,
|
|
146
|
+
and can simulate failures (`fake.failNext({ status: 429, retryAfter: 1 })`). `POST /_fake/deliver` lets another process add mail.
|
|
147
|
+
Webhooks: `fake.catchWebhook({ method, path, query, headers, body })` stores a request in-process, and `fake.webhookUrl`
|
|
148
|
+
(`http://127.0.0.1:<port>/_fake/hook/<token>`) catches real HTTP calls like the hosted catch URL, custom responses included.
|
|
149
|
+
The fake never sends anything: replays are only recorded (`fake.replays`). `startFakeMailPier({ webhooks: false })` answers
|
|
150
|
+
404 like the service while the feature is off.
|
|
151
|
+
|
|
152
|
+
## Develop
|
|
153
|
+
|
|
154
|
+
`npm install`, `npm run typecheck`, `npm run build`, `npm test` (vitest), `npm run test:e2e` (Playwright; `PW_CHANNEL=msedge`
|
|
155
|
+
uses an installed Edge). `..\test-all.ps1` runs everything.
|
|
156
|
+
|
|
157
|
+
Mail is kept for the environment's retention period (15 minutes to 24 hours) and permanently deleted when the retention period ends. The message `html` is as received and NOT
|
|
158
|
+
sanitised: never render it in a page of your own origin.
|
|
159
|
+
|
|
160
|
+
License: MIT.
|