@mailstest/playwright 0.0.0-stage → 0.1.0

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.
@@ -0,0 +1,415 @@
1
+ import { z } from "zod";
2
+ /**
3
+ * Links and caller-pattern codes of one message, computed on the caller's own
4
+ * machine from what `getMessage` returned. Pure functions of the message's own
5
+ * text and HTML parts (and, for codes, the subject and the caller's pattern):
6
+ * no fetch, no clock, no verdict. They stand alone, so a REST user can copy
7
+ * them.
8
+ */
9
+ interface MessageLink {
10
+ url: string;
11
+ source: 'html' | 'text';
12
+ }
13
+ interface MessageCode {
14
+ value: string;
15
+ source: 'subject' | 'text' | 'html';
16
+ }
17
+ interface MessageParts {
18
+ subject?: string | null;
19
+ text?: string | null;
20
+ html?: string | null;
21
+ }
22
+ /**
23
+ * The links of the message's own parts, as written: HTML anchors (`a`, `area`
24
+ * with an `href`) in document order, then the text part's URLs, each distinct
25
+ * value once at its first occurrence. Comments, script, style, title and
26
+ * textarea hold none.
27
+ */
28
+ declare function extractLinks(message: MessageParts): MessageLink[];
29
+ /**
30
+ * The codes a pattern finds in the subject, then the text part, then the HTML
31
+ * part's visible text. `pattern` is a string or a `RegExp`, matched globally
32
+ * with JavaScript's engine. A value is the first capturing group when it took
33
+ * part, else the whole match; empty values are skipped; each value once.
34
+ */
35
+ declare function extractCodes(message: MessageParts, pattern: string | RegExp): MessageCode[];
36
+ /** The workspace's inboxes, with the plan's limits on their own for a workspace that has none. */
37
+ declare const listInboxesResponse: z.ZodObject<{
38
+ inboxes: z.ZodArray<z.ZodObject<{
39
+ id: z.ZodString;
40
+ name: z.ZodString;
41
+ username: z.ZodString;
42
+ emailCount: z.ZodNumber;
43
+ lastEmailAt: z.ZodNullable<z.ZodString>;
44
+ frozen: z.ZodBoolean;
45
+ limits: z.ZodObject<{
46
+ ring: z.ZodNumber;
47
+ retentionDays: z.ZodNumber;
48
+ inboxes: z.ZodNumber;
49
+ maxMessageBytes: z.ZodNumber;
50
+ }, z.core.$strip>;
51
+ }, z.core.$strip>>;
52
+ limits: z.ZodObject<{
53
+ ring: z.ZodNumber;
54
+ retentionDays: z.ZodNumber;
55
+ inboxes: z.ZodNumber;
56
+ maxMessageBytes: z.ZodNumber;
57
+ }, z.core.$strip>;
58
+ }, z.core.$strip>;
59
+ /** An inbox's SMTP credential as a create answers it: the password once, or null on a replay of the same idempotency key. */
60
+ declare const credentialRevealResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
61
+ id: z.ZodString;
62
+ name: z.ZodString;
63
+ username: z.ZodString;
64
+ password: z.ZodString;
65
+ replayed: z.ZodLiteral<false>;
66
+ expiresAt: z.ZodNullable<z.ZodString>;
67
+ }, z.core.$strip>, z.ZodObject<{
68
+ id: z.ZodString;
69
+ name: z.ZodString;
70
+ username: z.ZodString;
71
+ password: z.ZodNull;
72
+ replayed: z.ZodLiteral<true>;
73
+ expiresAt: z.ZodNullable<z.ZodString>;
74
+ }, z.core.$strip>], "replayed">;
75
+ /** One captured message as a list row; `deliveredTo` holds the envelope recipients, a Bcc'd address included. */
76
+ declare const messageSummary: z.ZodObject<{
77
+ id: z.ZodString;
78
+ senderName: z.ZodNullable<z.ZodString>;
79
+ senderAddress: z.ZodNullable<z.ZodString>;
80
+ subject: z.ZodNullable<z.ZodString>;
81
+ sizeBytes: z.ZodNumber;
82
+ parseFailed: z.ZodBoolean;
83
+ createdAt: z.ZodString;
84
+ expiresAt: z.ZodString;
85
+ pinned: z.ZodBoolean;
86
+ deliveredTo: z.ZodArray<z.ZodString>;
87
+ }, z.core.$strip>;
88
+ /** One message decoded once at capture: its parts, headers and attachment manifest. */
89
+ declare const messageDetailResponse: z.ZodObject<{
90
+ id: z.ZodString;
91
+ senderName: z.ZodNullable<z.ZodString>;
92
+ senderAddress: z.ZodNullable<z.ZodString>;
93
+ subject: z.ZodNullable<z.ZodString>;
94
+ recipients: z.ZodObject<{
95
+ to: z.ZodArray<z.ZodString>;
96
+ cc: z.ZodArray<z.ZodString>;
97
+ }, z.core.$strip>;
98
+ deliveredTo: z.ZodArray<z.ZodString>;
99
+ date: z.ZodNullable<z.ZodString>;
100
+ messageId: z.ZodNullable<z.ZodString>;
101
+ sizeBytes: z.ZodNumber;
102
+ parseFailed: z.ZodBoolean;
103
+ expiresAt: z.ZodString;
104
+ pinned: z.ZodBoolean;
105
+ text: z.ZodNullable<z.ZodString>;
106
+ html: z.ZodNullable<z.ZodString>;
107
+ headers: z.ZodArray<z.ZodObject<{
108
+ name: z.ZodString;
109
+ value: z.ZodString;
110
+ }, z.core.$strip>>;
111
+ attachments: z.ZodArray<z.ZodObject<{
112
+ index: z.ZodNumber;
113
+ filename: z.ZodNullable<z.ZodString>;
114
+ contentType: z.ZodString;
115
+ disposition: z.ZodEnum<{
116
+ attachment: "attachment";
117
+ inline: "inline";
118
+ }>;
119
+ sizeBytes: z.ZodNumber;
120
+ cid: z.ZodNullable<z.ZodString>;
121
+ }, z.core.$strip>>;
122
+ }, z.core.$strip>;
123
+ /** A wait's outcome: the message that arrived, or the structured timeout; never both, never neither. */
124
+ declare const waitForEmailResponse: z.ZodObject<{
125
+ timedOut: z.ZodBoolean;
126
+ message: z.ZodNullable<z.ZodObject<{
127
+ id: z.ZodString;
128
+ senderName: z.ZodNullable<z.ZodString>;
129
+ senderAddress: z.ZodNullable<z.ZodString>;
130
+ subject: z.ZodNullable<z.ZodString>;
131
+ sizeBytes: z.ZodNumber;
132
+ parseFailed: z.ZodBoolean;
133
+ createdAt: z.ZodString;
134
+ expiresAt: z.ZodString;
135
+ pinned: z.ZodBoolean;
136
+ deliveredTo: z.ZodArray<z.ZodString>;
137
+ }, z.core.$strip>>;
138
+ }, z.core.$strip>;
139
+ /** A run key as a mint answers it: the key once, or null on a replay of the same idempotency key. */
140
+ declare const apiKeyRevealResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
141
+ id: z.ZodString;
142
+ name: z.ZodString;
143
+ fragment: z.ZodString;
144
+ expiresAt: z.ZodNullable<z.ZodString>;
145
+ key: z.ZodString;
146
+ replayed: z.ZodLiteral<false>;
147
+ }, z.core.$strip>, z.ZodObject<{
148
+ id: z.ZodString;
149
+ name: z.ZodString;
150
+ fragment: z.ZodString;
151
+ expiresAt: z.ZodNullable<z.ZodString>;
152
+ key: z.ZodNull;
153
+ replayed: z.ZodLiteral<true>;
154
+ }, z.core.$strip>], "replayed">;
155
+ type InboxSummary = z.infer<typeof listInboxesResponse>['inboxes'][number];
156
+ type MessageSummary = z.infer<typeof messageSummary>;
157
+ type MessageDetail = z.infer<typeof messageDetailResponse>;
158
+ type MessageLinks = {
159
+ links: MessageLink[];
160
+ };
161
+ type MessageCodes = {
162
+ codes: MessageCode[];
163
+ };
164
+ type WaitResult = z.infer<typeof waitForEmailResponse>;
165
+ /**
166
+ * What a create answers: the new inbox's identity plus its SMTP credential —
167
+ * or, for a create repeated under the same idempotency key, that identity
168
+ * with the password null in its place.
169
+ * Named for the credential, not the inbox, because `InboxSummary` above is
170
+ * already the LIST row — and because this is the one shape in the SDK that
171
+ * carries a password.
172
+ */
173
+ type InboxCredentials = z.infer<typeof credentialRevealResponse>;
174
+ /** A create that MADE an inbox — the union's issuance member, so the password is present by the contract's own construction rather than by an intersection bolted on. */
175
+ type InboxIssuance = Extract<InboxCredentials, {
176
+ replayed: false;
177
+ }>;
178
+ /**
179
+ * What a mint answers: the key's identity, its non-secret fragment, the key
180
+ * itself — its single exposure — and the moment it stops (null only for a key
181
+ * the dashboard issued, never for one minted here). A mint repeated under the
182
+ * same idempotency key answers the same identity with the key null.
183
+ */
184
+ type ApiKeyReveal = z.infer<typeof apiKeyRevealResponse>;
185
+ /** A mint that MINTED a key — the union's issuance member, for the reason `InboxIssuance` is. */
186
+ type ApiKeyIssuance = Extract<ApiKeyReveal, {
187
+ replayed: false;
188
+ }>;
189
+ interface MailstestClientOptions {
190
+ /** Origin of the mailstest deployment, e.g. https://app.example.com — the client adds /v1. */
191
+ baseUrl: string;
192
+ /** Workspace API key (mtst_api_…). The ONLY credential the SDK accepts. */
193
+ apiKey: string;
194
+ /** Custom fetch implementation (tests, instrumented transports); defaults to the global fetch. */
195
+ fetchImpl?: typeof fetch;
196
+ }
197
+ declare function redactSecret(text: string, secret: string): string;
198
+ declare class MailstestApiError extends Error {
199
+ readonly status: number;
200
+ readonly body: string;
201
+ /** The request's URL, already redacted of this client's own key — kept so a caller holding a second secret can rebuild a fully redacted copy. */
202
+ readonly url: string;
203
+ constructor(status: number, body: string, url: string);
204
+ }
205
+ /**
206
+ * Raised when a read scoped to one address meets a message that was not
207
+ * delivered to it, and when the run fixture's inbox is asked for mail it does
208
+ * not scope. The server filters by `to`; this is the client refusing to trust
209
+ * the filter alone, so a server that ignored `to` (an older build) cannot hand
210
+ * a test another test's mail. It names the address, never a secret.
211
+ */
212
+ declare class MailstestScopeError extends Error {
213
+ constructor(message: string);
214
+ }
215
+ declare function buildV1Url(baseUrl: string, segments: string[], query?: Record<string, string>): string;
216
+ interface RawResponse {
217
+ bytes: Uint8Array;
218
+ filename: string | null;
219
+ }
220
+ declare function parseFilename(header: string | null): string | null;
221
+ /** One address's view of an inbox: every request carries `to=<address>`, and every message returned is checked to have been delivered to it. */
222
+ interface RecipientHandle {
223
+ readonly inboxId: string;
224
+ readonly address: string;
225
+ /** The dashboard's view of the inbox filtered to this address. */
226
+ readonly dashboardUrl: string;
227
+ listMessagesPage(options?: {
228
+ cursor?: string;
229
+ signal?: AbortSignal;
230
+ }): Promise<{
231
+ messages: MessageSummary[];
232
+ nextCursor: string | null;
233
+ }>;
234
+ listMessages(options?: {
235
+ signal?: AbortSignal;
236
+ }): Promise<MessageSummary[]>;
237
+ waitForEmail(options?: {
238
+ timeout?: number;
239
+ since?: string;
240
+ }): Promise<WaitResult>;
241
+ /** Removes this address's mail only, pinned included; a zero count is a success. */
242
+ clear(options?: {
243
+ signal?: AbortSignal;
244
+ }): Promise<{
245
+ cleared: true;
246
+ count: number;
247
+ }>;
248
+ }
249
+ interface InboxHandle {
250
+ readonly id: string;
251
+ /** Reads, waits and clears scoped to one envelope recipient. */
252
+ recipient(address: string): RecipientHandle;
253
+ /** One raw /v1 page of the backlog, newest-first; nextCursor is null once none remains. */
254
+ listMessagesPage(options?: {
255
+ cursor?: string;
256
+ signal?: AbortSignal;
257
+ }): Promise<{
258
+ messages: MessageSummary[];
259
+ nextCursor: string | null;
260
+ }>;
261
+ /** The whole backlog, newest-first — every /v1 page is followed by its nextCursor internally until none remains. */
262
+ listMessages(options?: {
263
+ signal?: AbortSignal;
264
+ }): Promise<MessageSummary[]>;
265
+ getMessage(messageId: string, options?: {
266
+ signal?: AbortSignal;
267
+ }): Promise<MessageDetail>;
268
+ /** The links of one message as it wrote them, computed here from `getMessage`: HTML anchors in document order, then the text part's URLs; nothing is fetched or judged. */
269
+ getLinks(messageId: string, options?: {
270
+ signal?: AbortSignal;
271
+ }): Promise<MessageLinks>;
272
+ /**
273
+ * The codes the caller's own pattern (a string or a `RegExp`, matched
274
+ * globally with JavaScript's engine) finds in one message's subject, text
275
+ * and visible HTML, computed here from `getMessage`. A value is the first
276
+ * capturing group when it took part, else the whole match.
277
+ */
278
+ getCodes(messageId: string, pattern: string | RegExp, options?: {
279
+ signal?: AbortSignal;
280
+ }): Promise<MessageCodes>;
281
+ getRaw(messageId: string): Promise<RawResponse>;
282
+ clear(): Promise<{
283
+ cleared: true;
284
+ count: number;
285
+ }>;
286
+ /** Deletes one message on demand, pinned or not; a foreign or already-gone id rejects with a 404 MailstestApiError. */
287
+ deleteMessage(messageId: string): Promise<void>;
288
+ /** Pins or unpins one message, idempotently; pinning past the inbox's cap rejects with a 409 MailstestApiError whose body names the cap. */
289
+ setPinned(messageId: string, pinned: boolean): Promise<{
290
+ id: string;
291
+ pinned: boolean;
292
+ }>;
293
+ waitForEmail(options?: {
294
+ timeout?: number;
295
+ since?: string;
296
+ }): Promise<WaitResult>;
297
+ /** Scrubs this client's configured secrets from arbitrary text — used by the matcher's diagnostics. */
298
+ redactSecrets(text: string): string;
299
+ }
300
+ interface MailstestClient {
301
+ listInboxes(): Promise<InboxSummary[]>;
302
+ /**
303
+ * Provisions an inbox on the key's workspace and returns its identity with
304
+ * its SMTP credential. The password is returned HERE and nowhere else,
305
+ * ever — the SDK neither keeps it nor sends it anywhere afterwards, so
306
+ * store it or lose it. A workspace already holding as many inboxes as its
307
+ * plan covers rejects with a 409 MailstestApiError whose body names the cap.
308
+ *
309
+ * `expiresIn` declares how long the inbox may live, in seconds; `maxUses`
310
+ * how many authentications its credential covers (an SMTP AUTH, or a
311
+ * door request that captures), and it requires `expiresIn`. A lifetime
312
+ * declared with no budget derives ONE — one authentication, not one
313
+ * message. Omit both for a durable inbox. Bounds are the platform's: a
314
+ * value outside them rejects with a 400 MailstestApiError.
315
+ *
316
+ * Two shapes, one call. WITHOUT an idempotency key a create can only ever
317
+ * be an issuance — the platform has nothing to replay — so the answer is
318
+ * typed as one and `password` is a string. WITH a key, repeating the
319
+ * identical create answers the inbox the first attempt made: `replayed`
320
+ * true and `password` null, since the password was that attempt's single
321
+ * exposure. The overloads say exactly that, so a caller that never asks
322
+ * for idempotency never has to narrow.
323
+ */
324
+ createInbox(options: {
325
+ name: string;
326
+ expiresIn?: number;
327
+ maxUses?: number;
328
+ idempotencyKey?: undefined;
329
+ signal?: AbortSignal;
330
+ }): Promise<InboxIssuance>;
331
+ createInbox(options: {
332
+ name: string;
333
+ expiresIn?: number;
334
+ maxUses?: number;
335
+ idempotencyKey: string;
336
+ signal?: AbortSignal;
337
+ }): Promise<InboxCredentials>;
338
+ /**
339
+ * The widest form, for wrapper and configuration code forwarding a value
340
+ * typed `string | undefined` — which matches NEITHER narrow overload and
341
+ * would otherwise force a cast or a branch. Last, so a known
342
+ * key and a known absence still pick the narrower answers above.
343
+ */
344
+ createInbox(options: {
345
+ name: string;
346
+ expiresIn?: number;
347
+ maxUses?: number;
348
+ idempotencyKey?: string;
349
+ signal?: AbortSignal;
350
+ }): Promise<InboxCredentials>;
351
+ /**
352
+ * Deletes an inbox with its credential, its captured mail and the bytes
353
+ * behind it. `confirmName` must equal the inbox's name exactly — no trim,
354
+ * no case fold — or it rejects with 400; a foreign or already-gone id
355
+ * rejects with 404.
356
+ */
357
+ deleteInbox(inboxId: string, options: {
358
+ confirmName: string;
359
+ signal?: AbortSignal;
360
+ }): Promise<void>;
361
+ /**
362
+ * Mints a run key on the key's workspace, living `expiresIn` seconds. Only a
363
+ * DURABLE key mints: a run key whose request would mint rejects with a 403
364
+ * MailstestApiError. The answer is the key's single exposure — the SDK
365
+ * neither keeps it nor sends it anywhere afterwards.
366
+ *
367
+ * The create's two shapes, on the mint: without an idempotency key the
368
+ * answer is an issuance and `key` is a string; with one, a repeat answers
369
+ * the key the first attempt minted, `replayed` true and `key` null. A
370
+ * repeat mints nothing, so it is answered to any key of the workspace — a
371
+ * run key included — before the durable-key rule, as are the 409s a spent,
372
+ * in-flight or gone idempotency key draws.
373
+ */
374
+ mintRunKey(options: {
375
+ name: string;
376
+ expiresIn: number;
377
+ idempotencyKey?: undefined;
378
+ signal?: AbortSignal;
379
+ }): Promise<ApiKeyIssuance>;
380
+ mintRunKey(options: {
381
+ name: string;
382
+ expiresIn: number;
383
+ idempotencyKey: string;
384
+ signal?: AbortSignal;
385
+ }): Promise<ApiKeyReveal>;
386
+ /** The widest form, for the reason `createInbox`'s third overload gives. */
387
+ mintRunKey(options: {
388
+ name: string;
389
+ expiresIn: number;
390
+ idempotencyKey?: string;
391
+ signal?: AbortSignal;
392
+ }): Promise<ApiKeyReveal>;
393
+ /**
394
+ * Revokes a run key of the caller's workspace — its own, so a run cleans up
395
+ * after itself, or another run's. A durable key, a foreign key and an id
396
+ * that never existed all reject with a 404 MailstestApiError.
397
+ */
398
+ revokeRunKey(keyId: string, options?: {
399
+ signal?: AbortSignal;
400
+ }): Promise<{
401
+ revoked: true;
402
+ }>;
403
+ inbox(inboxId: string): InboxHandle;
404
+ /**
405
+ * Scrub `secret` from everything this client says from now on — bodies,
406
+ * URLs and transport failures alike. A secret this client ITSELF issued is
407
+ * registered without being asked: a create's password and a mint's key are
408
+ * protected the moment they are parsed. This is for the other case — a
409
+ * secret the client never issued, such as the durable key a run fixture
410
+ * mints with and then reads the workspace under a different one.
411
+ */
412
+ protectSecret(secret: string): void;
413
+ }
414
+ declare function createClient(options: MailstestClientOptions): MailstestClient;
415
+ export { MessageParts as C, MessageLink as S, extractLinks as T, buildV1Url as _, InboxIssuance as a, redactSecret as b, MailstestClient as c, MessageCodes as d, MessageDetail as f, WaitResult as g, RecipientHandle as h, InboxHandle as i, MailstestClientOptions as l, MessageSummary as m, ApiKeyReveal as n, InboxSummary as o, MessageLinks as p, InboxCredentials as r, MailstestApiError as s, ApiKeyIssuance as t, MailstestScopeError as u, createClient as v, extractCodes as w, MessageCode as x, parseFilename as y };