@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/dist/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- export { D as DEFAULT_BASE_URL, a as DeleteAllResult, I as InboxAddress, b as InboxAttachment, c as InboxHeaders, d as InboxLink, e as InboxMessage, f as InboxMessageData, g as InboxMessageSummary, L as ListMessagesOptions, M as MAX_POLL_SECONDS, h as MailPierInbox, i as MailPierInboxOptions, N as NewAddressOptions, V as VERSION, W as WaitForMessageOptions } from './client-CqysQIQJ.cjs';
1
+ export { D as DEFAULT_BASE_URL, a as DeleteAllResult, b as DeleteWebhooksOptions, I as InboxAddress, c as InboxAttachment, d as InboxHeaders, e as InboxLink, f as InboxMessage, g as InboxMessageData, h as InboxMessageSummary, L as ListMessagesOptions, i as ListWebhooksOptions, M as MAX_POLL_SECONDS, j as MailPierInbox, k as MailPierInboxOptions, N as NewAddressOptions, l as NewWebhookResponse, V as VERSION, m as WaitForMessageOptions, n as WaitForWebhookOptions, o as WebhookEndpoint, p as WebhookHeader, q as WebhookLimits, r as WebhookReplayResult, s as WebhookRequest, t as WebhookRequestData, u as WebhookRequestSummary, v as WebhookResponseRule, W as WebhookUrl } from './client-DD8Tr4-3.cjs';
2
2
 
3
3
  /** The API answered an error: 400 (bad address/prefix), 401 (bad key), 403 (account suspended), 404, 409, 429 (rate limit), 503. */
4
4
  declare class MailPierInboxError extends Error {
@@ -7,11 +7,20 @@ declare class MailPierInboxError extends Error {
7
7
  readonly retryAfterSeconds?: number;
8
8
  constructor(status: number, message: string, retryAfterSeconds?: number);
9
9
  }
10
- /** No matching mail arrived before the timeout. */
10
+ /** No matching mail arrived before the timeout (MailPierWebhookTimeoutError, below, is one too). */
11
11
  declare class MailPierTimeoutError extends Error {
12
12
  readonly address: string;
13
13
  readonly timeoutMs: number;
14
14
  constructor(address: string, timeoutMs: number, subjectContains?: string);
15
15
  }
16
+ /**
17
+ * No matching webhook request arrived before the timeout. A MailPierTimeoutError (one catch handles both waits); `address` holds
18
+ * the path.
19
+ */
20
+ declare class MailPierWebhookTimeoutError extends MailPierTimeoutError {
21
+ readonly path: string;
22
+ readonly method?: string;
23
+ constructor(path: string, timeoutMs: number, method?: string);
24
+ }
16
25
 
17
- export { MailPierInboxError, MailPierTimeoutError };
26
+ export { MailPierInboxError, MailPierTimeoutError, MailPierWebhookTimeoutError };
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- export { D as DEFAULT_BASE_URL, a as DeleteAllResult, I as InboxAddress, b as InboxAttachment, c as InboxHeaders, d as InboxLink, e as InboxMessage, f as InboxMessageData, g as InboxMessageSummary, L as ListMessagesOptions, M as MAX_POLL_SECONDS, h as MailPierInbox, i as MailPierInboxOptions, N as NewAddressOptions, V as VERSION, W as WaitForMessageOptions } from './client-CqysQIQJ.js';
1
+ export { D as DEFAULT_BASE_URL, a as DeleteAllResult, b as DeleteWebhooksOptions, I as InboxAddress, c as InboxAttachment, d as InboxHeaders, e as InboxLink, f as InboxMessage, g as InboxMessageData, h as InboxMessageSummary, L as ListMessagesOptions, i as ListWebhooksOptions, M as MAX_POLL_SECONDS, j as MailPierInbox, k as MailPierInboxOptions, N as NewAddressOptions, l as NewWebhookResponse, V as VERSION, m as WaitForMessageOptions, n as WaitForWebhookOptions, o as WebhookEndpoint, p as WebhookHeader, q as WebhookLimits, r as WebhookReplayResult, s as WebhookRequest, t as WebhookRequestData, u as WebhookRequestSummary, v as WebhookResponseRule, W as WebhookUrl } from './client-DD8Tr4-3.js';
2
2
 
3
3
  /** The API answered an error: 400 (bad address/prefix), 401 (bad key), 403 (account suspended), 404, 409, 429 (rate limit), 503. */
4
4
  declare class MailPierInboxError extends Error {
@@ -7,11 +7,20 @@ declare class MailPierInboxError extends Error {
7
7
  readonly retryAfterSeconds?: number;
8
8
  constructor(status: number, message: string, retryAfterSeconds?: number);
9
9
  }
10
- /** No matching mail arrived before the timeout. */
10
+ /** No matching mail arrived before the timeout (MailPierWebhookTimeoutError, below, is one too). */
11
11
  declare class MailPierTimeoutError extends Error {
12
12
  readonly address: string;
13
13
  readonly timeoutMs: number;
14
14
  constructor(address: string, timeoutMs: number, subjectContains?: string);
15
15
  }
16
+ /**
17
+ * No matching webhook request arrived before the timeout. A MailPierTimeoutError (one catch handles both waits); `address` holds
18
+ * the path.
19
+ */
20
+ declare class MailPierWebhookTimeoutError extends MailPierTimeoutError {
21
+ readonly path: string;
22
+ readonly method?: string;
23
+ constructor(path: string, timeoutMs: number, method?: string);
24
+ }
16
25
 
17
- export { MailPierInboxError, MailPierTimeoutError };
26
+ export { MailPierInboxError, MailPierTimeoutError, MailPierWebhookTimeoutError };
package/dist/index.js CHANGED
@@ -5,8 +5,10 @@ import {
5
5
  MailPierInbox,
6
6
  MailPierInboxError,
7
7
  MailPierTimeoutError,
8
- VERSION
9
- } from "./chunk-FR6JEAV7.js";
8
+ MailPierWebhookTimeoutError,
9
+ VERSION,
10
+ WebhookRequest
11
+ } from "./chunk-2NMZ2IWD.js";
10
12
  export {
11
13
  DEFAULT_BASE_URL,
12
14
  InboxMessage,
@@ -14,5 +16,7 @@ export {
14
16
  MailPierInbox,
15
17
  MailPierInboxError,
16
18
  MailPierTimeoutError,
17
- VERSION
19
+ MailPierWebhookTimeoutError,
20
+ VERSION,
21
+ WebhookRequest
18
22
  };
@@ -50,6 +50,17 @@ var MailPierTimeoutError = class extends Error {
50
50
  this.timeoutMs = timeoutMs;
51
51
  }
52
52
  };
53
+ var MailPierWebhookTimeoutError = class extends MailPierTimeoutError {
54
+ path;
55
+ method;
56
+ constructor(path, timeoutMs, method) {
57
+ super(path, timeoutMs);
58
+ this.message = `No ${method ? `${method.toUpperCase()} ` : ""}webhook request to ${path} arrived within ${Math.round(timeoutMs / 1e3)} seconds.`;
59
+ this.name = "MailPierWebhookTimeoutError";
60
+ this.path = path;
61
+ this.method = method;
62
+ }
63
+ };
53
64
 
54
65
  // src/message.ts
55
66
  var InboxMessage = class {
@@ -112,10 +123,72 @@ function normaliseCodes(codes) {
112
123
  return out;
113
124
  }
114
125
 
126
+ // src/webhook.ts
127
+ var WebhookRequest = class {
128
+ id;
129
+ receivedUtc;
130
+ method = "";
131
+ path = "/";
132
+ query;
133
+ contentType;
134
+ size = 0;
135
+ environment;
136
+ status = 0;
137
+ url;
138
+ headers = [];
139
+ body;
140
+ bodyBase64;
141
+ json;
142
+ form;
143
+ sourceIp;
144
+ headersTruncated = false;
145
+ ruleId;
146
+ forwardStatus;
147
+ constructor(data) {
148
+ Object.assign(this, data);
149
+ this.headers = Array.isArray(data.headers) ? data.headers.filter((h) => h && typeof h.name === "string").map((h) => ({ name: h.name, value: String(h.value ?? "") })) : [];
150
+ this.headersTruncated = data.headersTruncated === true;
151
+ }
152
+ /** The first value of a header (name case-insensitive), or undefined when the request has none. */
153
+ header(name) {
154
+ const n = name.toLowerCase();
155
+ return this.headers.find((h) => h.name.toLowerCase() === n)?.value;
156
+ }
157
+ /** The body bytes (from `body` or `bodyBase64`); empty when the request had no body. */
158
+ bytes() {
159
+ if (typeof this.bodyBase64 === "string" && this.bodyBase64) {
160
+ const bin = atob(this.bodyBase64);
161
+ const out = new Uint8Array(bin.length);
162
+ for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
163
+ return out;
164
+ }
165
+ return new TextEncoder().encode(this.body ?? "");
166
+ }
167
+ /**
168
+ * The body as JSON: the server's parsed `json`, or the text body parsed here (a JSON body sent with another content type).
169
+ * Throws when the body is not JSON.
170
+ */
171
+ jsonBody() {
172
+ if (this.json !== void 0 && this.json !== null) return this.json;
173
+ if (typeof this.body === "string" && this.body.trim()) {
174
+ try {
175
+ return JSON.parse(this.body);
176
+ } catch {
177
+ }
178
+ }
179
+ throw new Error(`The body of ${this.method} ${this.path} (request ${this.id}, ${this.contentType ?? "no content type"}) is not JSON.`);
180
+ }
181
+ /** The plain JSON (what the API returned), e.g. to pass through a Cypress task. */
182
+ toJSON() {
183
+ const { ...plain } = this;
184
+ return plain;
185
+ }
186
+ };
187
+
115
188
  // src/client.ts
116
189
  var DEFAULT_BASE_URL = "https://api.mailpier.io";
117
190
  var MAX_POLL_SECONDS = 120;
118
- var VERSION = "0.1.0";
191
+ var VERSION = "0.1.1";
119
192
  var sleep = (ms, signal) => new Promise((resolve, reject) => {
120
193
  if (signal?.aborted) return reject(signal.reason);
121
194
  const t = setTimeout(() => {
@@ -137,6 +210,11 @@ function env(name) {
137
210
  const v = p?.env?.[name];
138
211
  return v && v.trim() ? v.trim() : void 0;
139
212
  }
213
+ function webhookPath(path) {
214
+ const p = path?.trim();
215
+ if (!p) return void 0;
216
+ return p.startsWith("/") ? p : `/${p}`;
217
+ }
140
218
  var MailPierInbox = class {
141
219
  baseUrl;
142
220
  apiKey;
@@ -245,6 +323,129 @@ var MailPierInbox = class {
245
323
  const resp = await this.request("GET", "/v1/me", {});
246
324
  return await resp.json();
247
325
  }
326
+ // ------------------------------------------------------------------ Webhook inspector (/v1/hooks; 404 while the feature is off)
327
+ /** The environment's catch URL (made on first use), its switches and the plan's webhook limits. */
328
+ async getWebhookEndpoint() {
329
+ const resp = await this.request("GET", "/v1/hooks", {});
330
+ const json = await resp.json();
331
+ if (!json?.url) throw new MailPierInboxError(resp.status, "The server returned no webhook URL.");
332
+ return json;
333
+ }
334
+ /**
335
+ * The catch URL with a fresh random path, e.g. `{ url: "https://hook.gather-io.com/<token>/t-8f2k1x", path: "/t-8f2k1x" }`.
336
+ * Give `url` to the app under test and wait with `waitForWebhook({ path })`. Nothing is stored: any path works without this call.
337
+ */
338
+ async createWebhookUrl() {
339
+ const resp = await this.request("POST", "/v1/hooks/urls", {});
340
+ const json = await resp.json();
341
+ if (!json?.url || !json.path) throw new MailPierInboxError(resp.status, "The server returned no webhook URL.");
342
+ return { url: json.url, path: json.path };
343
+ }
344
+ /**
345
+ * Waits until a request to the catch URL arrives and returns it: the OLDEST match newer than `afterId` / `since`.
346
+ * Throws MailPierWebhookTimeoutError (a MailPierTimeoutError) when nothing arrives within `timeoutSeconds`.
347
+ */
348
+ async waitForWebhook(options = {}) {
349
+ const path = webhookPath(options.path);
350
+ const method = options.method?.trim() || void 0;
351
+ const timeoutSeconds = options.timeoutSeconds ?? 60;
352
+ if (!(timeoutSeconds > 0)) throw new Error("timeoutSeconds must be greater than 0.");
353
+ const timeoutMs = timeoutSeconds * 1e3;
354
+ const deadline = Date.now() + timeoutMs;
355
+ const since = iso(options.since);
356
+ for (; ; ) {
357
+ const left = deadline - Date.now();
358
+ const seconds = Math.min(Math.max(Math.ceil(left / 1e3), 1), MAX_POLL_SECONDS);
359
+ const resp = await this.request("GET", "/v1/hooks/requests/wait", {
360
+ path,
361
+ method,
362
+ afterId: options.afterId,
363
+ since,
364
+ timeoutSeconds: seconds
365
+ }, { signal: options.signal, timeoutMs: (seconds + 30) * 1e3 });
366
+ if (resp.status !== 204) return new WebhookRequest(await resp.json());
367
+ if (Date.now() >= deadline) throw new MailPierWebhookTimeoutError(path ?? "/", timeoutMs, method);
368
+ }
369
+ }
370
+ /** Caught requests of the environment, newest first (at most 100 per call). */
371
+ async listWebhooks(options = {}) {
372
+ const resp = await this.request("GET", "/v1/hooks/requests", {
373
+ path: webhookPath(options.path),
374
+ method: options.method?.trim() || void 0,
375
+ afterId: options.afterId,
376
+ since: iso(options.since),
377
+ take: options.take ?? 50,
378
+ skip: options.skip ?? 0
379
+ }, { signal: options.signal });
380
+ const json = await resp.json();
381
+ return json?.items ?? [];
382
+ }
383
+ /** One caught request with headers and body; null when it does not exist (or expired). */
384
+ async getWebhook(id) {
385
+ const resp = await this.request("GET", `/v1/hooks/requests/${encodeURIComponent(String(id))}`, {}, { allow404: true });
386
+ if (resp.status === 404) return null;
387
+ return new WebhookRequest(await resp.json());
388
+ }
389
+ /** The raw body bytes of a caught request; null when it does not exist. */
390
+ getWebhookBody(id) {
391
+ return this.download(`/v1/hooks/requests/${encodeURIComponent(String(id))}/body`);
392
+ }
393
+ /** Deletes one caught request. False when it did not exist. */
394
+ async deleteWebhook(id) {
395
+ const resp = await this.request("DELETE", `/v1/hooks/requests/${encodeURIComponent(String(id))}`, {}, { allow404: true });
396
+ return resp.status !== 404;
397
+ }
398
+ /** Deletes the caught requests whose path starts with `path` (every request of the environment when omitted); returns how many. */
399
+ async deleteWebhooks(options = {}) {
400
+ const resp = await this.request("DELETE", "/v1/hooks/requests", { path: webhookPath(options.path) });
401
+ const json = await resp.json();
402
+ return json?.deleted ?? 0;
403
+ }
404
+ /**
405
+ * Sends a caught request again (method, path, query, headers, body) to `url`, a PUBLIC http(s) address (MailPier never calls
406
+ * private or loopback addresses: 400). Not retried on 502/504 or network errors, so the target never gets it twice.
407
+ */
408
+ async replayWebhook(id, url) {
409
+ if (!url?.trim()) throw new Error("replayWebhook needs the URL to send the request to.");
410
+ const resp = await this.request(
411
+ "POST",
412
+ `/v1/hooks/requests/${encodeURIComponent(String(id))}/replay`,
413
+ {},
414
+ { body: JSON.stringify({ url: url.trim() }), once: true }
415
+ );
416
+ const json = await resp.json();
417
+ return { status: json?.status ?? null, durationMs: json?.durationMs ?? null, error: json?.error ?? null };
418
+ }
419
+ /**
420
+ * Adds a custom response: requests whose path starts with `rule.path` (and of `rule.method`, when given) get this status,
421
+ * content type, body and delay instead of 200 OK. Throws MailPierInboxError (400) when it is invalid or over the plan's count.
422
+ */
423
+ async addWebhookResponse(rule) {
424
+ const path = webhookPath(rule?.path);
425
+ if (!path) throw new Error('addWebhookResponse needs a path (e.g. "/stripe"; "/" for every request).');
426
+ const isObject = rule.body !== void 0 && rule.body !== null && typeof rule.body === "object";
427
+ const payload = {
428
+ method: rule.method?.trim() ? rule.method.trim().toUpperCase() : null,
429
+ path,
430
+ status: rule.status ?? 200,
431
+ contentType: rule.contentType ?? (isObject ? "application/json" : "text/plain"),
432
+ body: isObject ? JSON.stringify(rule.body) : rule.body ?? "",
433
+ delayMs: rule.delayMs ?? 0
434
+ };
435
+ const resp = await this.request("POST", "/v1/hooks/responses", {}, { body: JSON.stringify(payload), once: true });
436
+ return await resp.json();
437
+ }
438
+ /** The environment's custom responses. */
439
+ async listWebhookResponses() {
440
+ const resp = await this.request("GET", "/v1/hooks/responses", {});
441
+ const json = await resp.json();
442
+ return json?.items ?? [];
443
+ }
444
+ /** Deletes a custom response. False when it did not exist. */
445
+ async deleteWebhookResponse(id) {
446
+ const resp = await this.request("DELETE", `/v1/hooks/responses/${encodeURIComponent(String(id))}`, {}, { allow404: true });
447
+ return resp.status !== 404;
448
+ }
248
449
  // ------------------------------------------------------------------ plumbing
249
450
  async download(path) {
250
451
  const resp = await this.request("GET", path, {}, { allow404: true, accept: "*/*" });
@@ -260,6 +461,8 @@ var MailPierInbox = class {
260
461
  /**
261
462
  * 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
262
463
  * (both capped at maxRetryDelayMs). Other errors throw MailPierInboxError with the server's {"error": "..."} text.
464
+ * `once`: a call that must not run twice (replay, add a rule) is retried only on 429 and 503 (refused before any work), never
465
+ * on 502/504 or network errors (it may have been done).
263
466
  */
264
467
  async request(method, path, query, o = {}) {
265
468
  const url = this.url(path, query);
@@ -285,7 +488,7 @@ var MailPierInbox = class {
285
488
  clearTimeout(timer);
286
489
  o.signal?.removeEventListener("abort", onAbort);
287
490
  if (o.signal?.aborted) throw err;
288
- if (attempt >= this.maxRetries) {
491
+ if (attempt >= this.maxRetries || o.once) {
289
492
  throw new MailPierInboxError(0, `Could not reach MailPier Inbox at ${this.baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
290
493
  }
291
494
  await sleep(this.backoff(attempt), o.signal);
@@ -303,7 +506,8 @@ var MailPierInbox = class {
303
506
  }
304
507
  throw new MailPierInboxError(429, message ?? "Too many requests.", retryAfter);
305
508
  }
306
- if ((resp.status === 502 || resp.status === 503 || resp.status === 504) && attempt < this.maxRetries) {
509
+ const retryable = resp.status === 503 || !o.once && (resp.status === 502 || resp.status === 504);
510
+ if (retryable && attempt < this.maxRetries) {
307
511
  await sleep(this.backoff(attempt), o.signal);
308
512
  continue;
309
513
  }
@@ -342,6 +546,9 @@ var PlaywrightInbox = class {
342
546
  client;
343
547
  created = /* @__PURE__ */ new Map();
344
548
  lastSeen = /* @__PURE__ */ new Map();
549
+ lastWebhook = /* @__PURE__ */ new Map();
550
+ started = new Date(Date.now() - 1e3);
551
+ // one second of slack for clock skew
345
552
  constructor(client) {
346
553
  this.client = client;
347
554
  }
@@ -376,6 +583,28 @@ var PlaywrightInbox = class {
376
583
  if (!link) throw new Error(`The mail "${m.subject ?? ""}" to ${address} holds no link${contains ? ` containing "${contains}"` : ""}.`);
377
584
  return link;
378
585
  }
586
+ /** The webhook catch URL with a fresh random path: give `url` to your app, then `waitForWebhook(path)`. */
587
+ createWebhookUrl() {
588
+ return this.client.createWebhookUrl();
589
+ }
590
+ /**
591
+ * Waits for the next request to the catch URL whose path starts with `path`: the first call returns the first one since this
592
+ * fixture started (an old request to a fixed path like "/stripe" is never picked up), each later call the one after it.
593
+ */
594
+ async waitForWebhook(path, options = {}) {
595
+ const p = webhookPath(path) ?? "/";
596
+ const method = options.method?.trim().toUpperCase() || void 0;
597
+ const key = `${method ?? "*"} ${p}`;
598
+ const afterId = this.lastWebhook.get(key);
599
+ const request = await this.client.waitForWebhook({
600
+ path: p,
601
+ method,
602
+ timeoutSeconds: options.timeoutSeconds,
603
+ ...afterId !== void 0 ? { afterId } : { since: this.started }
604
+ });
605
+ this.lastWebhook.set(key, request.id);
606
+ return request;
607
+ }
379
608
  /** Addresses handed out by this fixture instance. */
380
609
  get addresses() {
381
610
  return [...this.created.keys()];
@@ -1,7 +1,7 @@
1
1
  import * as _playwright_test from '@playwright/test';
2
2
  import { Fixtures, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions } from '@playwright/test';
3
3
  export { expect } from '@playwright/test';
4
- import { MailPierInbox, NewAddressOptions, InboxMessage, MailPierInboxOptions } from './index.cjs';
4
+ import { MailPierInbox, NewAddressOptions, InboxMessage, WebhookUrl, WebhookRequest, MailPierInboxOptions } from './index.cjs';
5
5
 
6
6
  interface InboxWaitOptions {
7
7
  /** Only a mail whose subject contains this (case-insensitive). */
@@ -9,6 +9,12 @@ interface InboxWaitOptions {
9
9
  /** Default 60000. */
10
10
  timeoutMs?: number;
11
11
  }
12
+ interface WebhookWaitOptions {
13
+ /** Only this method (case-insensitive). */
14
+ method?: string;
15
+ /** Default 60. */
16
+ timeoutSeconds?: number;
17
+ }
12
18
  /**
13
19
  * The `inbox` fixture. Every address it hands out remembers when it was made, so a wait only returns mail sent after that
14
20
  * (an old mail to a reused address is never picked up by mistake).
@@ -18,6 +24,8 @@ declare class PlaywrightInbox {
18
24
  readonly client: MailPierInbox;
19
25
  private readonly created;
20
26
  private readonly lastSeen;
27
+ private readonly lastWebhook;
28
+ private readonly started;
21
29
  constructor(client: MailPierInbox);
22
30
  /** A fresh address of the key's environment. */
23
31
  newAddress(options?: NewAddressOptions): Promise<string>;
@@ -30,6 +38,13 @@ declare class PlaywrightInbox {
30
38
  waitForCode(address: string, options?: InboxWaitOptions): Promise<string>;
31
39
  /** Waits for the next mail to `address` and returns its first link containing `contains` (any link when omitted). */
32
40
  waitForLink(address: string, contains?: string, options?: InboxWaitOptions): Promise<string>;
41
+ /** The webhook catch URL with a fresh random path: give `url` to your app, then `waitForWebhook(path)`. */
42
+ createWebhookUrl(): Promise<WebhookUrl>;
43
+ /**
44
+ * Waits for the next request to the catch URL whose path starts with `path`: the first call returns the first one since this
45
+ * fixture started (an old request to a fixed path like "/stripe" is never picked up), each later call the one after it.
46
+ */
47
+ waitForWebhook(path: string, options?: WebhookWaitOptions): Promise<WebhookRequest>;
33
48
  /** Addresses handed out by this fixture instance. */
34
49
  get addresses(): string[];
35
50
  }
@@ -47,4 +62,4 @@ declare const mailpierFixtures: Fixtures<MailPierFixtures, object, PlaywrightTes
47
62
  declare const test: _playwright_test.TestType<PlaywrightTestArgs & PlaywrightTestOptions & MailPierFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
48
63
 
49
64
  export { PlaywrightInbox, mailpierFixtures, test };
50
- export type { InboxWaitOptions, MailPierFixtures };
65
+ export type { InboxWaitOptions, MailPierFixtures, WebhookWaitOptions };
@@ -1,7 +1,7 @@
1
1
  import * as _playwright_test from '@playwright/test';
2
2
  import { Fixtures, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions } from '@playwright/test';
3
3
  export { expect } from '@playwright/test';
4
- import { MailPierInbox, NewAddressOptions, InboxMessage, MailPierInboxOptions } from './index.js';
4
+ import { MailPierInbox, NewAddressOptions, InboxMessage, WebhookUrl, WebhookRequest, MailPierInboxOptions } from './index.js';
5
5
 
6
6
  interface InboxWaitOptions {
7
7
  /** Only a mail whose subject contains this (case-insensitive). */
@@ -9,6 +9,12 @@ interface InboxWaitOptions {
9
9
  /** Default 60000. */
10
10
  timeoutMs?: number;
11
11
  }
12
+ interface WebhookWaitOptions {
13
+ /** Only this method (case-insensitive). */
14
+ method?: string;
15
+ /** Default 60. */
16
+ timeoutSeconds?: number;
17
+ }
12
18
  /**
13
19
  * The `inbox` fixture. Every address it hands out remembers when it was made, so a wait only returns mail sent after that
14
20
  * (an old mail to a reused address is never picked up by mistake).
@@ -18,6 +24,8 @@ declare class PlaywrightInbox {
18
24
  readonly client: MailPierInbox;
19
25
  private readonly created;
20
26
  private readonly lastSeen;
27
+ private readonly lastWebhook;
28
+ private readonly started;
21
29
  constructor(client: MailPierInbox);
22
30
  /** A fresh address of the key's environment. */
23
31
  newAddress(options?: NewAddressOptions): Promise<string>;
@@ -30,6 +38,13 @@ declare class PlaywrightInbox {
30
38
  waitForCode(address: string, options?: InboxWaitOptions): Promise<string>;
31
39
  /** Waits for the next mail to `address` and returns its first link containing `contains` (any link when omitted). */
32
40
  waitForLink(address: string, contains?: string, options?: InboxWaitOptions): Promise<string>;
41
+ /** The webhook catch URL with a fresh random path: give `url` to your app, then `waitForWebhook(path)`. */
42
+ createWebhookUrl(): Promise<WebhookUrl>;
43
+ /**
44
+ * Waits for the next request to the catch URL whose path starts with `path`: the first call returns the first one since this
45
+ * fixture started (an old request to a fixed path like "/stripe" is never picked up), each later call the one after it.
46
+ */
47
+ waitForWebhook(path: string, options?: WebhookWaitOptions): Promise<WebhookRequest>;
33
48
  /** Addresses handed out by this fixture instance. */
34
49
  get addresses(): string[];
35
50
  }
@@ -47,4 +62,4 @@ declare const mailpierFixtures: Fixtures<MailPierFixtures, object, PlaywrightTes
47
62
  declare const test: _playwright_test.TestType<PlaywrightTestArgs & PlaywrightTestOptions & MailPierFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
48
63
 
49
64
  export { PlaywrightInbox, mailpierFixtures, test };
50
- export type { InboxWaitOptions, MailPierFixtures };
65
+ export type { InboxWaitOptions, MailPierFixtures, WebhookWaitOptions };
@@ -1,6 +1,7 @@
1
1
  import {
2
- MailPierInbox
3
- } from "./chunk-FR6JEAV7.js";
2
+ MailPierInbox,
3
+ webhookPath
4
+ } from "./chunk-2NMZ2IWD.js";
4
5
 
5
6
  // src/playwright.ts
6
7
  import { test as base } from "@playwright/test";
@@ -11,6 +12,9 @@ var PlaywrightInbox = class {
11
12
  client;
12
13
  created = /* @__PURE__ */ new Map();
13
14
  lastSeen = /* @__PURE__ */ new Map();
15
+ lastWebhook = /* @__PURE__ */ new Map();
16
+ started = new Date(Date.now() - 1e3);
17
+ // one second of slack for clock skew
14
18
  constructor(client) {
15
19
  this.client = client;
16
20
  }
@@ -45,6 +49,28 @@ var PlaywrightInbox = class {
45
49
  if (!link) throw new Error(`The mail "${m.subject ?? ""}" to ${address} holds no link${contains ? ` containing "${contains}"` : ""}.`);
46
50
  return link;
47
51
  }
52
+ /** The webhook catch URL with a fresh random path: give `url` to your app, then `waitForWebhook(path)`. */
53
+ createWebhookUrl() {
54
+ return this.client.createWebhookUrl();
55
+ }
56
+ /**
57
+ * Waits for the next request to the catch URL whose path starts with `path`: the first call returns the first one since this
58
+ * fixture started (an old request to a fixed path like "/stripe" is never picked up), each later call the one after it.
59
+ */
60
+ async waitForWebhook(path, options = {}) {
61
+ const p = webhookPath(path) ?? "/";
62
+ const method = options.method?.trim().toUpperCase() || void 0;
63
+ const key = `${method ?? "*"} ${p}`;
64
+ const afterId = this.lastWebhook.get(key);
65
+ const request = await this.client.waitForWebhook({
66
+ path: p,
67
+ method,
68
+ timeoutSeconds: options.timeoutSeconds,
69
+ ...afterId !== void 0 ? { afterId } : { since: this.started }
70
+ });
71
+ this.lastWebhook.set(key, request.id);
72
+ return request;
73
+ }
48
74
  /** Addresses handed out by this fixture instance. */
49
75
  get addresses() {
50
76
  return [...this.created.keys()];