@mailpier/inbox 0.1.0 → 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 +16 -1
- package/README.md +62 -2
- package/dist/{chunk-FR6JEAV7.js → chunk-2NMZ2IWD.js} +210 -3
- 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 +17 -2
- package/dist/cypress/commands.d.cts +13 -3
- package/dist/cypress/commands.d.ts +13 -3
- package/dist/cypress/commands.js +17 -2
- package/dist/cypress/index.cjs +221 -4
- package/dist/cypress/index.d.cts +17 -2
- package/dist/cypress/index.d.ts +17 -2
- package/dist/cypress/index.js +15 -2
- package/dist/index.cjs +213 -5
- package/dist/index.d.cts +12 -3
- package/dist/index.d.ts +12 -3
- package/dist/index.js +7 -3
- package/dist/playwright.cjs +232 -3
- package/dist/playwright.d.cts +17 -2
- package/dist/playwright.d.ts +17 -2
- package/dist/playwright.js +28 -2
- package/dist/testing/index.cjs +353 -20
- package/dist/testing/index.d.cts +32 -1
- package/dist/testing/index.d.ts +32 -1
- package/dist/testing/index.js +353 -20
- package/package.json +8 -3
- package/dist/client-CqysQIQJ.d.cts +0 -194
- package/dist/client-CqysQIQJ.d.ts +0 -194
package/dist/cypress/index.cjs
CHANGED
|
@@ -46,6 +46,17 @@ var MailPierTimeoutError = class extends Error {
|
|
|
46
46
|
this.timeoutMs = timeoutMs;
|
|
47
47
|
}
|
|
48
48
|
};
|
|
49
|
+
var MailPierWebhookTimeoutError = class extends MailPierTimeoutError {
|
|
50
|
+
path;
|
|
51
|
+
method;
|
|
52
|
+
constructor(path, timeoutMs, method) {
|
|
53
|
+
super(path, timeoutMs);
|
|
54
|
+
this.message = `No ${method ? `${method.toUpperCase()} ` : ""}webhook request to ${path} arrived within ${Math.round(timeoutMs / 1e3)} seconds.`;
|
|
55
|
+
this.name = "MailPierWebhookTimeoutError";
|
|
56
|
+
this.path = path;
|
|
57
|
+
this.method = method;
|
|
58
|
+
}
|
|
59
|
+
};
|
|
49
60
|
|
|
50
61
|
// src/message.ts
|
|
51
62
|
var InboxMessage = class {
|
|
@@ -108,10 +119,72 @@ function normaliseCodes(codes) {
|
|
|
108
119
|
return out;
|
|
109
120
|
}
|
|
110
121
|
|
|
122
|
+
// src/webhook.ts
|
|
123
|
+
var WebhookRequest = class {
|
|
124
|
+
id;
|
|
125
|
+
receivedUtc;
|
|
126
|
+
method = "";
|
|
127
|
+
path = "/";
|
|
128
|
+
query;
|
|
129
|
+
contentType;
|
|
130
|
+
size = 0;
|
|
131
|
+
environment;
|
|
132
|
+
status = 0;
|
|
133
|
+
url;
|
|
134
|
+
headers = [];
|
|
135
|
+
body;
|
|
136
|
+
bodyBase64;
|
|
137
|
+
json;
|
|
138
|
+
form;
|
|
139
|
+
sourceIp;
|
|
140
|
+
headersTruncated = false;
|
|
141
|
+
ruleId;
|
|
142
|
+
forwardStatus;
|
|
143
|
+
constructor(data) {
|
|
144
|
+
Object.assign(this, data);
|
|
145
|
+
this.headers = Array.isArray(data.headers) ? data.headers.filter((h) => h && typeof h.name === "string").map((h) => ({ name: h.name, value: String(h.value ?? "") })) : [];
|
|
146
|
+
this.headersTruncated = data.headersTruncated === true;
|
|
147
|
+
}
|
|
148
|
+
/** The first value of a header (name case-insensitive), or undefined when the request has none. */
|
|
149
|
+
header(name) {
|
|
150
|
+
const n = name.toLowerCase();
|
|
151
|
+
return this.headers.find((h) => h.name.toLowerCase() === n)?.value;
|
|
152
|
+
}
|
|
153
|
+
/** The body bytes (from `body` or `bodyBase64`); empty when the request had no body. */
|
|
154
|
+
bytes() {
|
|
155
|
+
if (typeof this.bodyBase64 === "string" && this.bodyBase64) {
|
|
156
|
+
const bin = atob(this.bodyBase64);
|
|
157
|
+
const out = new Uint8Array(bin.length);
|
|
158
|
+
for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
|
|
159
|
+
return out;
|
|
160
|
+
}
|
|
161
|
+
return new TextEncoder().encode(this.body ?? "");
|
|
162
|
+
}
|
|
163
|
+
/**
|
|
164
|
+
* The body as JSON: the server's parsed `json`, or the text body parsed here (a JSON body sent with another content type).
|
|
165
|
+
* Throws when the body is not JSON.
|
|
166
|
+
*/
|
|
167
|
+
jsonBody() {
|
|
168
|
+
if (this.json !== void 0 && this.json !== null) return this.json;
|
|
169
|
+
if (typeof this.body === "string" && this.body.trim()) {
|
|
170
|
+
try {
|
|
171
|
+
return JSON.parse(this.body);
|
|
172
|
+
} catch {
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
throw new Error(`The body of ${this.method} ${this.path} (request ${this.id}, ${this.contentType ?? "no content type"}) is not JSON.`);
|
|
176
|
+
}
|
|
177
|
+
/** The plain JSON (what the API returned), e.g. to pass through a Cypress task. */
|
|
178
|
+
toJSON() {
|
|
179
|
+
const { ...plain } = this;
|
|
180
|
+
return plain;
|
|
181
|
+
}
|
|
182
|
+
};
|
|
183
|
+
|
|
111
184
|
// src/client.ts
|
|
112
185
|
var DEFAULT_BASE_URL = "https://api.mailpier.io";
|
|
113
186
|
var MAX_POLL_SECONDS = 120;
|
|
114
|
-
var VERSION = "0.1.
|
|
187
|
+
var VERSION = "0.1.1";
|
|
115
188
|
var sleep = (ms, signal) => new Promise((resolve, reject) => {
|
|
116
189
|
if (signal?.aborted) return reject(signal.reason);
|
|
117
190
|
const t = setTimeout(() => {
|
|
@@ -133,6 +206,11 @@ function env(name) {
|
|
|
133
206
|
const v = p?.env?.[name];
|
|
134
207
|
return v && v.trim() ? v.trim() : void 0;
|
|
135
208
|
}
|
|
209
|
+
function webhookPath(path) {
|
|
210
|
+
const p = path?.trim();
|
|
211
|
+
if (!p) return void 0;
|
|
212
|
+
return p.startsWith("/") ? p : `/${p}`;
|
|
213
|
+
}
|
|
136
214
|
var MailPierInbox = class {
|
|
137
215
|
baseUrl;
|
|
138
216
|
apiKey;
|
|
@@ -241,6 +319,129 @@ var MailPierInbox = class {
|
|
|
241
319
|
const resp = await this.request("GET", "/v1/me", {});
|
|
242
320
|
return await resp.json();
|
|
243
321
|
}
|
|
322
|
+
// ------------------------------------------------------------------ Webhook inspector (/v1/hooks; 404 while the feature is off)
|
|
323
|
+
/** The environment's catch URL (made on first use), its switches and the plan's webhook limits. */
|
|
324
|
+
async getWebhookEndpoint() {
|
|
325
|
+
const resp = await this.request("GET", "/v1/hooks", {});
|
|
326
|
+
const json = await resp.json();
|
|
327
|
+
if (!json?.url) throw new MailPierInboxError(resp.status, "The server returned no webhook URL.");
|
|
328
|
+
return json;
|
|
329
|
+
}
|
|
330
|
+
/**
|
|
331
|
+
* The catch URL with a fresh random path, e.g. `{ url: "https://hook.gather-io.com/<token>/t-8f2k1x", path: "/t-8f2k1x" }`.
|
|
332
|
+
* Give `url` to the app under test and wait with `waitForWebhook({ path })`. Nothing is stored: any path works without this call.
|
|
333
|
+
*/
|
|
334
|
+
async createWebhookUrl() {
|
|
335
|
+
const resp = await this.request("POST", "/v1/hooks/urls", {});
|
|
336
|
+
const json = await resp.json();
|
|
337
|
+
if (!json?.url || !json.path) throw new MailPierInboxError(resp.status, "The server returned no webhook URL.");
|
|
338
|
+
return { url: json.url, path: json.path };
|
|
339
|
+
}
|
|
340
|
+
/**
|
|
341
|
+
* Waits until a request to the catch URL arrives and returns it: the OLDEST match newer than `afterId` / `since`.
|
|
342
|
+
* Throws MailPierWebhookTimeoutError (a MailPierTimeoutError) when nothing arrives within `timeoutSeconds`.
|
|
343
|
+
*/
|
|
344
|
+
async waitForWebhook(options = {}) {
|
|
345
|
+
const path = webhookPath(options.path);
|
|
346
|
+
const method = options.method?.trim() || void 0;
|
|
347
|
+
const timeoutSeconds = options.timeoutSeconds ?? 60;
|
|
348
|
+
if (!(timeoutSeconds > 0)) throw new Error("timeoutSeconds must be greater than 0.");
|
|
349
|
+
const timeoutMs = timeoutSeconds * 1e3;
|
|
350
|
+
const deadline = Date.now() + timeoutMs;
|
|
351
|
+
const since = iso(options.since);
|
|
352
|
+
for (; ; ) {
|
|
353
|
+
const left = deadline - Date.now();
|
|
354
|
+
const seconds = Math.min(Math.max(Math.ceil(left / 1e3), 1), MAX_POLL_SECONDS);
|
|
355
|
+
const resp = await this.request("GET", "/v1/hooks/requests/wait", {
|
|
356
|
+
path,
|
|
357
|
+
method,
|
|
358
|
+
afterId: options.afterId,
|
|
359
|
+
since,
|
|
360
|
+
timeoutSeconds: seconds
|
|
361
|
+
}, { signal: options.signal, timeoutMs: (seconds + 30) * 1e3 });
|
|
362
|
+
if (resp.status !== 204) return new WebhookRequest(await resp.json());
|
|
363
|
+
if (Date.now() >= deadline) throw new MailPierWebhookTimeoutError(path ?? "/", timeoutMs, method);
|
|
364
|
+
}
|
|
365
|
+
}
|
|
366
|
+
/** Caught requests of the environment, newest first (at most 100 per call). */
|
|
367
|
+
async listWebhooks(options = {}) {
|
|
368
|
+
const resp = await this.request("GET", "/v1/hooks/requests", {
|
|
369
|
+
path: webhookPath(options.path),
|
|
370
|
+
method: options.method?.trim() || void 0,
|
|
371
|
+
afterId: options.afterId,
|
|
372
|
+
since: iso(options.since),
|
|
373
|
+
take: options.take ?? 50,
|
|
374
|
+
skip: options.skip ?? 0
|
|
375
|
+
}, { signal: options.signal });
|
|
376
|
+
const json = await resp.json();
|
|
377
|
+
return json?.items ?? [];
|
|
378
|
+
}
|
|
379
|
+
/** One caught request with headers and body; null when it does not exist (or expired). */
|
|
380
|
+
async getWebhook(id) {
|
|
381
|
+
const resp = await this.request("GET", `/v1/hooks/requests/${encodeURIComponent(String(id))}`, {}, { allow404: true });
|
|
382
|
+
if (resp.status === 404) return null;
|
|
383
|
+
return new WebhookRequest(await resp.json());
|
|
384
|
+
}
|
|
385
|
+
/** The raw body bytes of a caught request; null when it does not exist. */
|
|
386
|
+
getWebhookBody(id) {
|
|
387
|
+
return this.download(`/v1/hooks/requests/${encodeURIComponent(String(id))}/body`);
|
|
388
|
+
}
|
|
389
|
+
/** Deletes one caught request. False when it did not exist. */
|
|
390
|
+
async deleteWebhook(id) {
|
|
391
|
+
const resp = await this.request("DELETE", `/v1/hooks/requests/${encodeURIComponent(String(id))}`, {}, { allow404: true });
|
|
392
|
+
return resp.status !== 404;
|
|
393
|
+
}
|
|
394
|
+
/** Deletes the caught requests whose path starts with `path` (every request of the environment when omitted); returns how many. */
|
|
395
|
+
async deleteWebhooks(options = {}) {
|
|
396
|
+
const resp = await this.request("DELETE", "/v1/hooks/requests", { path: webhookPath(options.path) });
|
|
397
|
+
const json = await resp.json();
|
|
398
|
+
return json?.deleted ?? 0;
|
|
399
|
+
}
|
|
400
|
+
/**
|
|
401
|
+
* Sends a caught request again (method, path, query, headers, body) to `url`, a PUBLIC http(s) address (MailPier never calls
|
|
402
|
+
* private or loopback addresses: 400). Not retried on 502/504 or network errors, so the target never gets it twice.
|
|
403
|
+
*/
|
|
404
|
+
async replayWebhook(id, url) {
|
|
405
|
+
if (!url?.trim()) throw new Error("replayWebhook needs the URL to send the request to.");
|
|
406
|
+
const resp = await this.request(
|
|
407
|
+
"POST",
|
|
408
|
+
`/v1/hooks/requests/${encodeURIComponent(String(id))}/replay`,
|
|
409
|
+
{},
|
|
410
|
+
{ body: JSON.stringify({ url: url.trim() }), once: true }
|
|
411
|
+
);
|
|
412
|
+
const json = await resp.json();
|
|
413
|
+
return { status: json?.status ?? null, durationMs: json?.durationMs ?? null, error: json?.error ?? null };
|
|
414
|
+
}
|
|
415
|
+
/**
|
|
416
|
+
* Adds a custom response: requests whose path starts with `rule.path` (and of `rule.method`, when given) get this status,
|
|
417
|
+
* content type, body and delay instead of 200 OK. Throws MailPierInboxError (400) when it is invalid or over the plan's count.
|
|
418
|
+
*/
|
|
419
|
+
async addWebhookResponse(rule) {
|
|
420
|
+
const path = webhookPath(rule?.path);
|
|
421
|
+
if (!path) throw new Error('addWebhookResponse needs a path (e.g. "/stripe"; "/" for every request).');
|
|
422
|
+
const isObject = rule.body !== void 0 && rule.body !== null && typeof rule.body === "object";
|
|
423
|
+
const payload = {
|
|
424
|
+
method: rule.method?.trim() ? rule.method.trim().toUpperCase() : null,
|
|
425
|
+
path,
|
|
426
|
+
status: rule.status ?? 200,
|
|
427
|
+
contentType: rule.contentType ?? (isObject ? "application/json" : "text/plain"),
|
|
428
|
+
body: isObject ? JSON.stringify(rule.body) : rule.body ?? "",
|
|
429
|
+
delayMs: rule.delayMs ?? 0
|
|
430
|
+
};
|
|
431
|
+
const resp = await this.request("POST", "/v1/hooks/responses", {}, { body: JSON.stringify(payload), once: true });
|
|
432
|
+
return await resp.json();
|
|
433
|
+
}
|
|
434
|
+
/** The environment's custom responses. */
|
|
435
|
+
async listWebhookResponses() {
|
|
436
|
+
const resp = await this.request("GET", "/v1/hooks/responses", {});
|
|
437
|
+
const json = await resp.json();
|
|
438
|
+
return json?.items ?? [];
|
|
439
|
+
}
|
|
440
|
+
/** Deletes a custom response. False when it did not exist. */
|
|
441
|
+
async deleteWebhookResponse(id) {
|
|
442
|
+
const resp = await this.request("DELETE", `/v1/hooks/responses/${encodeURIComponent(String(id))}`, {}, { allow404: true });
|
|
443
|
+
return resp.status !== 404;
|
|
444
|
+
}
|
|
244
445
|
// ------------------------------------------------------------------ plumbing
|
|
245
446
|
async download(path) {
|
|
246
447
|
const resp = await this.request("GET", path, {}, { allow404: true, accept: "*/*" });
|
|
@@ -256,6 +457,8 @@ var MailPierInbox = class {
|
|
|
256
457
|
/**
|
|
257
458
|
* One call with retries: 429 waits Retry-After (default 1 s), 502/503/504 and network errors back off 0.5, 1, 2, 4 ... s
|
|
258
459
|
* (both capped at maxRetryDelayMs). Other errors throw MailPierInboxError with the server's {"error": "..."} text.
|
|
460
|
+
* `once`: a call that must not run twice (replay, add a rule) is retried only on 429 and 503 (refused before any work), never
|
|
461
|
+
* on 502/504 or network errors (it may have been done).
|
|
259
462
|
*/
|
|
260
463
|
async request(method, path, query, o = {}) {
|
|
261
464
|
const url = this.url(path, query);
|
|
@@ -281,7 +484,7 @@ var MailPierInbox = class {
|
|
|
281
484
|
clearTimeout(timer);
|
|
282
485
|
o.signal?.removeEventListener("abort", onAbort);
|
|
283
486
|
if (o.signal?.aborted) throw err;
|
|
284
|
-
if (attempt >= this.maxRetries) {
|
|
487
|
+
if (attempt >= this.maxRetries || o.once) {
|
|
285
488
|
throw new MailPierInboxError(0, `Could not reach MailPier Inbox at ${this.baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
|
|
286
489
|
}
|
|
287
490
|
await sleep(this.backoff(attempt), o.signal);
|
|
@@ -299,7 +502,8 @@ var MailPierInbox = class {
|
|
|
299
502
|
}
|
|
300
503
|
throw new MailPierInboxError(429, message ?? "Too many requests.", retryAfter);
|
|
301
504
|
}
|
|
302
|
-
|
|
505
|
+
const retryable = resp.status === 503 || !o.once && (resp.status === 502 || resp.status === 504);
|
|
506
|
+
if (retryable && attempt < this.maxRetries) {
|
|
303
507
|
await sleep(this.backoff(attempt), o.signal);
|
|
304
508
|
continue;
|
|
305
509
|
}
|
|
@@ -349,7 +553,20 @@ function mailpierTasks(options = {}) {
|
|
|
349
553
|
});
|
|
350
554
|
return { ...m.toJSON(), code: m.code ?? null, firstLink: m.firstLink() ?? null };
|
|
351
555
|
},
|
|
352
|
-
"mailpier:deleteAll": async (args) => inbox().deleteAll(args.to)
|
|
556
|
+
"mailpier:deleteAll": async (args) => inbox().deleteAll(args.to),
|
|
557
|
+
"mailpier:createWebhookUrl": async () => inbox().createWebhookUrl(),
|
|
558
|
+
"mailpier:waitForWebhook": async (args) => {
|
|
559
|
+
if (!args?.path) throw new Error("mailpier:waitForWebhook needs { path }.");
|
|
560
|
+
const r = await inbox().waitForWebhook({
|
|
561
|
+
path: args.path,
|
|
562
|
+
method: args.method,
|
|
563
|
+
timeoutSeconds: args.timeoutSeconds,
|
|
564
|
+
since: args.since,
|
|
565
|
+
afterId: args.afterId
|
|
566
|
+
});
|
|
567
|
+
const plain = r.toJSON();
|
|
568
|
+
return { ...plain, body: plain.body ?? null, bodyBase64: plain.bodyBase64 ?? null, json: plain.json ?? null, form: plain.form ?? null };
|
|
569
|
+
}
|
|
353
570
|
};
|
|
354
571
|
}
|
|
355
572
|
// Annotate the CommonJS export names for ESM import in node:
|
package/dist/cypress/index.d.cts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { InboxMessageData, MailPierInboxOptions } from '../index.cjs';
|
|
1
|
+
import { InboxMessageData, WebhookRequestData, WebhookUrl, MailPierInboxOptions } from '../index.cjs';
|
|
2
2
|
|
|
3
3
|
interface MailPierWaitTaskArgs {
|
|
4
4
|
to: string;
|
|
@@ -14,6 +14,19 @@ type MailPierTaskMessage = InboxMessageData & {
|
|
|
14
14
|
code: string | null;
|
|
15
15
|
firstLink: string | null;
|
|
16
16
|
};
|
|
17
|
+
interface MailPierWebhookWaitTaskArgs {
|
|
18
|
+
/** Path prefix after the token (e.g. the path of mailpier:createWebhookUrl). */
|
|
19
|
+
path: string;
|
|
20
|
+
method?: string;
|
|
21
|
+
/** Default 60. */
|
|
22
|
+
timeoutSeconds?: number;
|
|
23
|
+
/** ISO time; only requests received at or after it. */
|
|
24
|
+
since?: string;
|
|
25
|
+
/** Only a request with a larger id. */
|
|
26
|
+
afterId?: number;
|
|
27
|
+
}
|
|
28
|
+
/** What cy.mailpierWaitForWebhook yields: the request JSON (method, path, query, headers, body, json, form ...). */
|
|
29
|
+
type MailPierTaskWebhook = WebhookRequestData;
|
|
17
30
|
interface MailPierTasks {
|
|
18
31
|
"mailpier:newAddress"(args?: {
|
|
19
32
|
prefix?: string;
|
|
@@ -23,10 +36,12 @@ interface MailPierTasks {
|
|
|
23
36
|
"mailpier:deleteAll"(args: {
|
|
24
37
|
to: string;
|
|
25
38
|
}): Promise<number>;
|
|
39
|
+
"mailpier:createWebhookUrl"(args?: null): Promise<WebhookUrl>;
|
|
40
|
+
"mailpier:waitForWebhook"(args: MailPierWebhookWaitTaskArgs): Promise<MailPierTaskWebhook>;
|
|
26
41
|
[name: string]: (args: never) => unknown;
|
|
27
42
|
}
|
|
28
43
|
/** The cy.task handlers. Options default to MAILPIER_API_KEY / MAILPIER_BASE_URL in the Cypress Node process. */
|
|
29
44
|
declare function mailpierTasks(options?: MailPierInboxOptions): MailPierTasks;
|
|
30
45
|
|
|
31
46
|
export { mailpierTasks };
|
|
32
|
-
export type { MailPierTaskMessage, MailPierTasks, MailPierWaitTaskArgs };
|
|
47
|
+
export type { MailPierTaskMessage, MailPierTaskWebhook, MailPierTasks, MailPierWaitTaskArgs, MailPierWebhookWaitTaskArgs };
|
package/dist/cypress/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { InboxMessageData, MailPierInboxOptions } from '../index.js';
|
|
1
|
+
import { InboxMessageData, WebhookRequestData, WebhookUrl, MailPierInboxOptions } from '../index.js';
|
|
2
2
|
|
|
3
3
|
interface MailPierWaitTaskArgs {
|
|
4
4
|
to: string;
|
|
@@ -14,6 +14,19 @@ type MailPierTaskMessage = InboxMessageData & {
|
|
|
14
14
|
code: string | null;
|
|
15
15
|
firstLink: string | null;
|
|
16
16
|
};
|
|
17
|
+
interface MailPierWebhookWaitTaskArgs {
|
|
18
|
+
/** Path prefix after the token (e.g. the path of mailpier:createWebhookUrl). */
|
|
19
|
+
path: string;
|
|
20
|
+
method?: string;
|
|
21
|
+
/** Default 60. */
|
|
22
|
+
timeoutSeconds?: number;
|
|
23
|
+
/** ISO time; only requests received at or after it. */
|
|
24
|
+
since?: string;
|
|
25
|
+
/** Only a request with a larger id. */
|
|
26
|
+
afterId?: number;
|
|
27
|
+
}
|
|
28
|
+
/** What cy.mailpierWaitForWebhook yields: the request JSON (method, path, query, headers, body, json, form ...). */
|
|
29
|
+
type MailPierTaskWebhook = WebhookRequestData;
|
|
17
30
|
interface MailPierTasks {
|
|
18
31
|
"mailpier:newAddress"(args?: {
|
|
19
32
|
prefix?: string;
|
|
@@ -23,10 +36,12 @@ interface MailPierTasks {
|
|
|
23
36
|
"mailpier:deleteAll"(args: {
|
|
24
37
|
to: string;
|
|
25
38
|
}): Promise<number>;
|
|
39
|
+
"mailpier:createWebhookUrl"(args?: null): Promise<WebhookUrl>;
|
|
40
|
+
"mailpier:waitForWebhook"(args: MailPierWebhookWaitTaskArgs): Promise<MailPierTaskWebhook>;
|
|
26
41
|
[name: string]: (args: never) => unknown;
|
|
27
42
|
}
|
|
28
43
|
/** The cy.task handlers. Options default to MAILPIER_API_KEY / MAILPIER_BASE_URL in the Cypress Node process. */
|
|
29
44
|
declare function mailpierTasks(options?: MailPierInboxOptions): MailPierTasks;
|
|
30
45
|
|
|
31
46
|
export { mailpierTasks };
|
|
32
|
-
export type { MailPierTaskMessage, MailPierTasks, MailPierWaitTaskArgs };
|
|
47
|
+
export type { MailPierTaskMessage, MailPierTaskWebhook, MailPierTasks, MailPierWaitTaskArgs, MailPierWebhookWaitTaskArgs };
|
package/dist/cypress/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import {
|
|
2
2
|
MailPierInbox
|
|
3
|
-
} from "../chunk-
|
|
3
|
+
} from "../chunk-2NMZ2IWD.js";
|
|
4
4
|
|
|
5
5
|
// src/cypress/tasks.ts
|
|
6
6
|
function mailpierTasks(options = {}) {
|
|
@@ -19,7 +19,20 @@ function mailpierTasks(options = {}) {
|
|
|
19
19
|
});
|
|
20
20
|
return { ...m.toJSON(), code: m.code ?? null, firstLink: m.firstLink() ?? null };
|
|
21
21
|
},
|
|
22
|
-
"mailpier:deleteAll": async (args) => inbox().deleteAll(args.to)
|
|
22
|
+
"mailpier:deleteAll": async (args) => inbox().deleteAll(args.to),
|
|
23
|
+
"mailpier:createWebhookUrl": async () => inbox().createWebhookUrl(),
|
|
24
|
+
"mailpier:waitForWebhook": async (args) => {
|
|
25
|
+
if (!args?.path) throw new Error("mailpier:waitForWebhook needs { path }.");
|
|
26
|
+
const r = await inbox().waitForWebhook({
|
|
27
|
+
path: args.path,
|
|
28
|
+
method: args.method,
|
|
29
|
+
timeoutSeconds: args.timeoutSeconds,
|
|
30
|
+
since: args.since,
|
|
31
|
+
afterId: args.afterId
|
|
32
|
+
});
|
|
33
|
+
const plain = r.toJSON();
|
|
34
|
+
return { ...plain, body: plain.body ?? null, bodyBase64: plain.bodyBase64 ?? null, json: plain.json ?? null, form: plain.form ?? null };
|
|
35
|
+
}
|
|
23
36
|
};
|
|
24
37
|
}
|
|
25
38
|
export {
|
package/dist/index.cjs
CHANGED
|
@@ -26,7 +26,9 @@ __export(src_exports, {
|
|
|
26
26
|
MailPierInbox: () => MailPierInbox,
|
|
27
27
|
MailPierInboxError: () => MailPierInboxError,
|
|
28
28
|
MailPierTimeoutError: () => MailPierTimeoutError,
|
|
29
|
-
|
|
29
|
+
MailPierWebhookTimeoutError: () => MailPierWebhookTimeoutError,
|
|
30
|
+
VERSION: () => VERSION,
|
|
31
|
+
WebhookRequest: () => WebhookRequest
|
|
30
32
|
});
|
|
31
33
|
module.exports = __toCommonJS(src_exports);
|
|
32
34
|
|
|
@@ -52,6 +54,17 @@ var MailPierTimeoutError = class extends Error {
|
|
|
52
54
|
this.timeoutMs = timeoutMs;
|
|
53
55
|
}
|
|
54
56
|
};
|
|
57
|
+
var MailPierWebhookTimeoutError = class extends MailPierTimeoutError {
|
|
58
|
+
path;
|
|
59
|
+
method;
|
|
60
|
+
constructor(path, timeoutMs, method) {
|
|
61
|
+
super(path, timeoutMs);
|
|
62
|
+
this.message = `No ${method ? `${method.toUpperCase()} ` : ""}webhook request to ${path} arrived within ${Math.round(timeoutMs / 1e3)} seconds.`;
|
|
63
|
+
this.name = "MailPierWebhookTimeoutError";
|
|
64
|
+
this.path = path;
|
|
65
|
+
this.method = method;
|
|
66
|
+
}
|
|
67
|
+
};
|
|
55
68
|
|
|
56
69
|
// src/message.ts
|
|
57
70
|
var InboxMessage = class {
|
|
@@ -114,10 +127,72 @@ function normaliseCodes(codes) {
|
|
|
114
127
|
return out;
|
|
115
128
|
}
|
|
116
129
|
|
|
130
|
+
// src/webhook.ts
|
|
131
|
+
var WebhookRequest = class {
|
|
132
|
+
id;
|
|
133
|
+
receivedUtc;
|
|
134
|
+
method = "";
|
|
135
|
+
path = "/";
|
|
136
|
+
query;
|
|
137
|
+
contentType;
|
|
138
|
+
size = 0;
|
|
139
|
+
environment;
|
|
140
|
+
status = 0;
|
|
141
|
+
url;
|
|
142
|
+
headers = [];
|
|
143
|
+
body;
|
|
144
|
+
bodyBase64;
|
|
145
|
+
json;
|
|
146
|
+
form;
|
|
147
|
+
sourceIp;
|
|
148
|
+
headersTruncated = false;
|
|
149
|
+
ruleId;
|
|
150
|
+
forwardStatus;
|
|
151
|
+
constructor(data) {
|
|
152
|
+
Object.assign(this, data);
|
|
153
|
+
this.headers = Array.isArray(data.headers) ? data.headers.filter((h) => h && typeof h.name === "string").map((h) => ({ name: h.name, value: String(h.value ?? "") })) : [];
|
|
154
|
+
this.headersTruncated = data.headersTruncated === true;
|
|
155
|
+
}
|
|
156
|
+
/** The first value of a header (name case-insensitive), or undefined when the request has none. */
|
|
157
|
+
header(name) {
|
|
158
|
+
const n = name.toLowerCase();
|
|
159
|
+
return this.headers.find((h) => h.name.toLowerCase() === n)?.value;
|
|
160
|
+
}
|
|
161
|
+
/** The body bytes (from `body` or `bodyBase64`); empty when the request had no body. */
|
|
162
|
+
bytes() {
|
|
163
|
+
if (typeof this.bodyBase64 === "string" && this.bodyBase64) {
|
|
164
|
+
const bin = atob(this.bodyBase64);
|
|
165
|
+
const out = new Uint8Array(bin.length);
|
|
166
|
+
for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
|
|
167
|
+
return out;
|
|
168
|
+
}
|
|
169
|
+
return new TextEncoder().encode(this.body ?? "");
|
|
170
|
+
}
|
|
171
|
+
/**
|
|
172
|
+
* The body as JSON: the server's parsed `json`, or the text body parsed here (a JSON body sent with another content type).
|
|
173
|
+
* Throws when the body is not JSON.
|
|
174
|
+
*/
|
|
175
|
+
jsonBody() {
|
|
176
|
+
if (this.json !== void 0 && this.json !== null) return this.json;
|
|
177
|
+
if (typeof this.body === "string" && this.body.trim()) {
|
|
178
|
+
try {
|
|
179
|
+
return JSON.parse(this.body);
|
|
180
|
+
} catch {
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
throw new Error(`The body of ${this.method} ${this.path} (request ${this.id}, ${this.contentType ?? "no content type"}) is not JSON.`);
|
|
184
|
+
}
|
|
185
|
+
/** The plain JSON (what the API returned), e.g. to pass through a Cypress task. */
|
|
186
|
+
toJSON() {
|
|
187
|
+
const { ...plain } = this;
|
|
188
|
+
return plain;
|
|
189
|
+
}
|
|
190
|
+
};
|
|
191
|
+
|
|
117
192
|
// src/client.ts
|
|
118
193
|
var DEFAULT_BASE_URL = "https://api.mailpier.io";
|
|
119
194
|
var MAX_POLL_SECONDS = 120;
|
|
120
|
-
var VERSION = "0.1.
|
|
195
|
+
var VERSION = "0.1.1";
|
|
121
196
|
var sleep = (ms, signal) => new Promise((resolve, reject) => {
|
|
122
197
|
if (signal?.aborted) return reject(signal.reason);
|
|
123
198
|
const t = setTimeout(() => {
|
|
@@ -139,6 +214,11 @@ function env(name) {
|
|
|
139
214
|
const v = p?.env?.[name];
|
|
140
215
|
return v && v.trim() ? v.trim() : void 0;
|
|
141
216
|
}
|
|
217
|
+
function webhookPath(path) {
|
|
218
|
+
const p = path?.trim();
|
|
219
|
+
if (!p) return void 0;
|
|
220
|
+
return p.startsWith("/") ? p : `/${p}`;
|
|
221
|
+
}
|
|
142
222
|
var MailPierInbox = class {
|
|
143
223
|
baseUrl;
|
|
144
224
|
apiKey;
|
|
@@ -247,6 +327,129 @@ var MailPierInbox = class {
|
|
|
247
327
|
const resp = await this.request("GET", "/v1/me", {});
|
|
248
328
|
return await resp.json();
|
|
249
329
|
}
|
|
330
|
+
// ------------------------------------------------------------------ Webhook inspector (/v1/hooks; 404 while the feature is off)
|
|
331
|
+
/** The environment's catch URL (made on first use), its switches and the plan's webhook limits. */
|
|
332
|
+
async getWebhookEndpoint() {
|
|
333
|
+
const resp = await this.request("GET", "/v1/hooks", {});
|
|
334
|
+
const json = await resp.json();
|
|
335
|
+
if (!json?.url) throw new MailPierInboxError(resp.status, "The server returned no webhook URL.");
|
|
336
|
+
return json;
|
|
337
|
+
}
|
|
338
|
+
/**
|
|
339
|
+
* The catch URL with a fresh random path, e.g. `{ url: "https://hook.gather-io.com/<token>/t-8f2k1x", path: "/t-8f2k1x" }`.
|
|
340
|
+
* Give `url` to the app under test and wait with `waitForWebhook({ path })`. Nothing is stored: any path works without this call.
|
|
341
|
+
*/
|
|
342
|
+
async createWebhookUrl() {
|
|
343
|
+
const resp = await this.request("POST", "/v1/hooks/urls", {});
|
|
344
|
+
const json = await resp.json();
|
|
345
|
+
if (!json?.url || !json.path) throw new MailPierInboxError(resp.status, "The server returned no webhook URL.");
|
|
346
|
+
return { url: json.url, path: json.path };
|
|
347
|
+
}
|
|
348
|
+
/**
|
|
349
|
+
* Waits until a request to the catch URL arrives and returns it: the OLDEST match newer than `afterId` / `since`.
|
|
350
|
+
* Throws MailPierWebhookTimeoutError (a MailPierTimeoutError) when nothing arrives within `timeoutSeconds`.
|
|
351
|
+
*/
|
|
352
|
+
async waitForWebhook(options = {}) {
|
|
353
|
+
const path = webhookPath(options.path);
|
|
354
|
+
const method = options.method?.trim() || void 0;
|
|
355
|
+
const timeoutSeconds = options.timeoutSeconds ?? 60;
|
|
356
|
+
if (!(timeoutSeconds > 0)) throw new Error("timeoutSeconds must be greater than 0.");
|
|
357
|
+
const timeoutMs = timeoutSeconds * 1e3;
|
|
358
|
+
const deadline = Date.now() + timeoutMs;
|
|
359
|
+
const since = iso(options.since);
|
|
360
|
+
for (; ; ) {
|
|
361
|
+
const left = deadline - Date.now();
|
|
362
|
+
const seconds = Math.min(Math.max(Math.ceil(left / 1e3), 1), MAX_POLL_SECONDS);
|
|
363
|
+
const resp = await this.request("GET", "/v1/hooks/requests/wait", {
|
|
364
|
+
path,
|
|
365
|
+
method,
|
|
366
|
+
afterId: options.afterId,
|
|
367
|
+
since,
|
|
368
|
+
timeoutSeconds: seconds
|
|
369
|
+
}, { signal: options.signal, timeoutMs: (seconds + 30) * 1e3 });
|
|
370
|
+
if (resp.status !== 204) return new WebhookRequest(await resp.json());
|
|
371
|
+
if (Date.now() >= deadline) throw new MailPierWebhookTimeoutError(path ?? "/", timeoutMs, method);
|
|
372
|
+
}
|
|
373
|
+
}
|
|
374
|
+
/** Caught requests of the environment, newest first (at most 100 per call). */
|
|
375
|
+
async listWebhooks(options = {}) {
|
|
376
|
+
const resp = await this.request("GET", "/v1/hooks/requests", {
|
|
377
|
+
path: webhookPath(options.path),
|
|
378
|
+
method: options.method?.trim() || void 0,
|
|
379
|
+
afterId: options.afterId,
|
|
380
|
+
since: iso(options.since),
|
|
381
|
+
take: options.take ?? 50,
|
|
382
|
+
skip: options.skip ?? 0
|
|
383
|
+
}, { signal: options.signal });
|
|
384
|
+
const json = await resp.json();
|
|
385
|
+
return json?.items ?? [];
|
|
386
|
+
}
|
|
387
|
+
/** One caught request with headers and body; null when it does not exist (or expired). */
|
|
388
|
+
async getWebhook(id) {
|
|
389
|
+
const resp = await this.request("GET", `/v1/hooks/requests/${encodeURIComponent(String(id))}`, {}, { allow404: true });
|
|
390
|
+
if (resp.status === 404) return null;
|
|
391
|
+
return new WebhookRequest(await resp.json());
|
|
392
|
+
}
|
|
393
|
+
/** The raw body bytes of a caught request; null when it does not exist. */
|
|
394
|
+
getWebhookBody(id) {
|
|
395
|
+
return this.download(`/v1/hooks/requests/${encodeURIComponent(String(id))}/body`);
|
|
396
|
+
}
|
|
397
|
+
/** Deletes one caught request. False when it did not exist. */
|
|
398
|
+
async deleteWebhook(id) {
|
|
399
|
+
const resp = await this.request("DELETE", `/v1/hooks/requests/${encodeURIComponent(String(id))}`, {}, { allow404: true });
|
|
400
|
+
return resp.status !== 404;
|
|
401
|
+
}
|
|
402
|
+
/** Deletes the caught requests whose path starts with `path` (every request of the environment when omitted); returns how many. */
|
|
403
|
+
async deleteWebhooks(options = {}) {
|
|
404
|
+
const resp = await this.request("DELETE", "/v1/hooks/requests", { path: webhookPath(options.path) });
|
|
405
|
+
const json = await resp.json();
|
|
406
|
+
return json?.deleted ?? 0;
|
|
407
|
+
}
|
|
408
|
+
/**
|
|
409
|
+
* Sends a caught request again (method, path, query, headers, body) to `url`, a PUBLIC http(s) address (MailPier never calls
|
|
410
|
+
* private or loopback addresses: 400). Not retried on 502/504 or network errors, so the target never gets it twice.
|
|
411
|
+
*/
|
|
412
|
+
async replayWebhook(id, url) {
|
|
413
|
+
if (!url?.trim()) throw new Error("replayWebhook needs the URL to send the request to.");
|
|
414
|
+
const resp = await this.request(
|
|
415
|
+
"POST",
|
|
416
|
+
`/v1/hooks/requests/${encodeURIComponent(String(id))}/replay`,
|
|
417
|
+
{},
|
|
418
|
+
{ body: JSON.stringify({ url: url.trim() }), once: true }
|
|
419
|
+
);
|
|
420
|
+
const json = await resp.json();
|
|
421
|
+
return { status: json?.status ?? null, durationMs: json?.durationMs ?? null, error: json?.error ?? null };
|
|
422
|
+
}
|
|
423
|
+
/**
|
|
424
|
+
* Adds a custom response: requests whose path starts with `rule.path` (and of `rule.method`, when given) get this status,
|
|
425
|
+
* content type, body and delay instead of 200 OK. Throws MailPierInboxError (400) when it is invalid or over the plan's count.
|
|
426
|
+
*/
|
|
427
|
+
async addWebhookResponse(rule) {
|
|
428
|
+
const path = webhookPath(rule?.path);
|
|
429
|
+
if (!path) throw new Error('addWebhookResponse needs a path (e.g. "/stripe"; "/" for every request).');
|
|
430
|
+
const isObject = rule.body !== void 0 && rule.body !== null && typeof rule.body === "object";
|
|
431
|
+
const payload = {
|
|
432
|
+
method: rule.method?.trim() ? rule.method.trim().toUpperCase() : null,
|
|
433
|
+
path,
|
|
434
|
+
status: rule.status ?? 200,
|
|
435
|
+
contentType: rule.contentType ?? (isObject ? "application/json" : "text/plain"),
|
|
436
|
+
body: isObject ? JSON.stringify(rule.body) : rule.body ?? "",
|
|
437
|
+
delayMs: rule.delayMs ?? 0
|
|
438
|
+
};
|
|
439
|
+
const resp = await this.request("POST", "/v1/hooks/responses", {}, { body: JSON.stringify(payload), once: true });
|
|
440
|
+
return await resp.json();
|
|
441
|
+
}
|
|
442
|
+
/** The environment's custom responses. */
|
|
443
|
+
async listWebhookResponses() {
|
|
444
|
+
const resp = await this.request("GET", "/v1/hooks/responses", {});
|
|
445
|
+
const json = await resp.json();
|
|
446
|
+
return json?.items ?? [];
|
|
447
|
+
}
|
|
448
|
+
/** Deletes a custom response. False when it did not exist. */
|
|
449
|
+
async deleteWebhookResponse(id) {
|
|
450
|
+
const resp = await this.request("DELETE", `/v1/hooks/responses/${encodeURIComponent(String(id))}`, {}, { allow404: true });
|
|
451
|
+
return resp.status !== 404;
|
|
452
|
+
}
|
|
250
453
|
// ------------------------------------------------------------------ plumbing
|
|
251
454
|
async download(path) {
|
|
252
455
|
const resp = await this.request("GET", path, {}, { allow404: true, accept: "*/*" });
|
|
@@ -262,6 +465,8 @@ var MailPierInbox = class {
|
|
|
262
465
|
/**
|
|
263
466
|
* One call with retries: 429 waits Retry-After (default 1 s), 502/503/504 and network errors back off 0.5, 1, 2, 4 ... s
|
|
264
467
|
* (both capped at maxRetryDelayMs). Other errors throw MailPierInboxError with the server's {"error": "..."} text.
|
|
468
|
+
* `once`: a call that must not run twice (replay, add a rule) is retried only on 429 and 503 (refused before any work), never
|
|
469
|
+
* on 502/504 or network errors (it may have been done).
|
|
265
470
|
*/
|
|
266
471
|
async request(method, path, query, o = {}) {
|
|
267
472
|
const url = this.url(path, query);
|
|
@@ -287,7 +492,7 @@ var MailPierInbox = class {
|
|
|
287
492
|
clearTimeout(timer);
|
|
288
493
|
o.signal?.removeEventListener("abort", onAbort);
|
|
289
494
|
if (o.signal?.aborted) throw err;
|
|
290
|
-
if (attempt >= this.maxRetries) {
|
|
495
|
+
if (attempt >= this.maxRetries || o.once) {
|
|
291
496
|
throw new MailPierInboxError(0, `Could not reach MailPier Inbox at ${this.baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
|
|
292
497
|
}
|
|
293
498
|
await sleep(this.backoff(attempt), o.signal);
|
|
@@ -305,7 +510,8 @@ var MailPierInbox = class {
|
|
|
305
510
|
}
|
|
306
511
|
throw new MailPierInboxError(429, message ?? "Too many requests.", retryAfter);
|
|
307
512
|
}
|
|
308
|
-
|
|
513
|
+
const retryable = resp.status === 503 || !o.once && (resp.status === 502 || resp.status === 504);
|
|
514
|
+
if (retryable && attempt < this.maxRetries) {
|
|
309
515
|
await sleep(this.backoff(attempt), o.signal);
|
|
310
516
|
continue;
|
|
311
517
|
}
|
|
@@ -345,5 +551,7 @@ function parseRetryAfter(v) {
|
|
|
345
551
|
MailPierInbox,
|
|
346
552
|
MailPierInboxError,
|
|
347
553
|
MailPierTimeoutError,
|
|
348
|
-
|
|
554
|
+
MailPierWebhookTimeoutError,
|
|
555
|
+
VERSION,
|
|
556
|
+
WebhookRequest
|
|
349
557
|
});
|