zerodrop-client 0.1.6 → 0.1.7

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.
Files changed (2) hide show
  1. package/README.md +179 -163
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,163 +1,179 @@
1
-
2
- # zerodrop-client
3
-
4
- ![npm version](https://img.shields.io/npm/v/zerodrop-client)
5
- ![npm downloads](https://img.shields.io/npm/dw/zerodrop-client)
6
-
7
- ![ZeroDrop Demo](https://github.com/user-attachments/assets/739602b7-27bc-48c4-a837-5e75cec20b29)
8
-
9
- Instant temporary email inboxes for testing auth flows, CI pipelines, and QA automation.
10
-
11
- No signup. No configuration. Works in 4 lines.
12
-
13
- ## Install
14
-
15
- ```bash
16
- npm install zerodrop-client
17
- ```
18
-
19
- ## Test Isolation
20
-
21
- Every inbox is isolated by default. `generateInbox()` returns a unique address on every call — no shared state, no pools, no configuration needed.
22
-
23
- Zero cross-test contamination. Every test run gets a cryptographically isolated inbox that expires automatically after 30 minutes.
24
-
25
- This means parallel CI builds work out of the box — 10 workers, 10 inboxes, zero race conditions.
26
-
27
- ## Zero-Auth Mode (Local Development)
28
-
29
- ```javascript
30
- import { ZeroDrop } from 'zerodrop-client';
31
-
32
- const mail = new ZeroDrop();
33
- const inbox = mail.generateInbox();
34
- // → "swift-x7k29@zerodrop-sandbox.online"
35
-
36
- const email = await mail.waitForLatest(inbox, { timeout: 10000 });
37
- console.log(email.subject); // "Reset your password"
38
- console.log(email.body); // "Click here to reset..."
39
- ```
40
-
41
- ## CI Pipeline Mode (Playwright / Cypress)
42
-
43
- ```javascript
44
- import { ZeroDrop } from 'zerodrop-client';
45
-
46
- const mail = new ZeroDrop(process.env.ZERODROP_API_KEY);
47
-
48
- test('password reset flow', async ({ page }) => {
49
- const inbox = mail.generateInbox();
50
-
51
- await page.goto('/forgot-password');
52
- await page.fill('[name="email"]', inbox);
53
- await page.click('[type="submit"]');
54
-
55
- const email = await mail.waitForLatest(inbox, { timeout: 15000 });
56
- expect(email.subject).toContain('Reset your password');
57
-
58
- const resetLink = email.body.match(/https?:\/\/[^\s]+/)[0];
59
- await page.goto(resetLink);
60
- });
61
- ```
62
-
63
- ## Parallel CI Runs
64
-
65
- Inbox generation is client-side — no API call, no throttling.
66
- 50 parallel tests generate 50 inboxes instantly.
67
-
68
- ```javascript
69
- // Safe to run in parallel — generateInbox() is local
70
- const inboxes = Array.from({ length: 50 }, () => mail.generateInbox());
71
- ```
72
-
73
- The rate limit applies to the polling endpoint — 20 requests
74
- per 10 seconds per IP on the free tier. For heavy parallel
75
- usage, stagger `waitForLatest()` calls slightly:
76
-
77
- ```javascript
78
- // Stagger polls to avoid burst on shared IP
79
- const results = await Promise.all(
80
- inboxes.map((inbox, i) =>
81
- new Promise(resolve => setTimeout(resolve, i * 100))
82
- .then(() => mail.waitForLatest(inbox, { timeout: 15000 }))
83
- )
84
- );
85
- ```
86
-
87
- For CI pipelines with 20+ parallel tests, use a Workspace
88
- API key — dedicated rate limit bucket, not shared with
89
- the public pool.
90
-
91
- ## Webhook Mode (Staging Servers)
92
-
93
- ```javascript
94
- const mail = new ZeroDrop(process.env.ZERODROP_API_KEY);
95
-
96
- await mail.onReceived('qa-test@yourcompany.com', 'https://your-server.com/webhook');
97
- // ZeroDrop POSTs the email JSON to your URL when it arrives
98
- ```
99
-
100
- ## API
101
-
102
- ### `new ZeroDrop(apiKey?, options?)`
103
- - `apiKey` — optional. Omit for free sandbox mode.
104
- - `options.baseUrl` — override the API base URL.
105
-
106
- ### `mail.generateInbox(): string`
107
- Returns a ready-to-use email address instantly. No network request.
108
-
109
- ### `mail.fetchLatest(inbox): Promise<ZeroDropEmail | null>`
110
- Returns the latest email or null if inbox is empty.
111
-
112
- ### `mail.waitForLatest(inbox, options?): Promise<ZeroDropEmail>`
113
- Polls until an email arrives. Throws `ZeroDropTimeoutError` on timeout.
114
- - `options.timeout` — ms to wait (default: 10000)
115
- - `options.pollInterval` — ms between polls (default: 2000)
116
-
117
- ### `mail.onReceived(inbox, webhookUrl): Promise<{ registered: boolean }>`
118
- Registers a webhook. Requires API key (Workspace tier).
119
-
120
- ## Types
121
-
122
- ```typescript
123
- interface ZeroDropEmail {
124
- id: string;
125
- from: string;
126
- to: string;
127
- subject: string;
128
- body: string;
129
- rawBody: string;
130
- receivedAt: Date;
131
- }
132
- ```
133
-
134
- ## Error Handling
135
-
136
- ```javascript
137
- import { ZeroDrop, ZeroDropTimeoutError } from 'zerodrop-client';
138
-
139
- try {
140
- const email = await mail.waitForLatest(inbox, { timeout: 10000 });
141
- } catch (err) {
142
- if (err instanceof ZeroDropTimeoutError) {
143
- console.error('No email received — check your app is sending correctly');
144
- }
145
- }
146
- ```
147
-
148
- ## Free vs Workspace
149
-
150
- | | Free | Workspace |
151
- |---|---|---|
152
- | Inbox generation | ✓ | ✓ |
153
- | Email retention | 30 min | 7 days |
154
- | Custom domains | ✗ | ✓ |
155
- | API key | ✗ | ✓ |
156
- | Webhooks | ✗ | ✓ |
157
- | AI spam filter | On | Off |
158
-
159
- Get a Workspace at [zerodrop.dev](https://zerodrop.dev)
160
-
161
- ## License
162
-
163
- MIT
1
+ # zerodrop-client
2
+
3
+ Instant temporary email inboxes for testing auth flows, CI pipelines, and QA automation.
4
+
5
+ No signup. No configuration. Works in 4 lines.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install zerodrop-client
11
+ ```
12
+
13
+ ## Test Isolation
14
+
15
+ Every inbox is isolated by default. `generateInbox()` returns a unique address on every call — no shared state, no pools, no configuration needed.
16
+
17
+ Zero cross-test contamination. Every test run gets a cryptographically isolated inbox that expires automatically after 30 minutes.
18
+
19
+ This means parallel CI builds work out of the box — 10 workers, 10 inboxes, zero race conditions.
20
+
21
+ ## Zero-Auth Mode (Local Development)
22
+
23
+ ```javascript
24
+ import { ZeroDrop } from 'zerodrop-client';
25
+
26
+ const mail = new ZeroDrop();
27
+ const inbox = mail.generateInbox();
28
+ // → "swift-x7k29@zerodrop-sandbox.online"
29
+
30
+ const email = await mail.waitForLatest(inbox, { timeout: 10000 });
31
+ console.log(email.subject); // "Reset your password"
32
+ console.log(email.otp); // "123456" — auto-extracted, no regex needed
33
+ console.log(email.magicLink); // "https://..." — auto-extracted verification link
34
+ ```
35
+
36
+ ## CI Pipeline Mode (Playwright / Cypress)
37
+
38
+ ```javascript
39
+ import { ZeroDrop } from 'zerodrop-client';
40
+
41
+ const mail = new ZeroDrop(process.env.ZERODROP_API_KEY);
42
+
43
+ test('password reset flow', async ({ page }) => {
44
+ const inbox = mail.generateInbox();
45
+
46
+ await page.goto('/forgot-password');
47
+ await page.fill('[name="email"]', inbox);
48
+ await page.click('[type="submit"]');
49
+
50
+ const email = await mail.waitForLatest(inbox, { timeout: 15000 });
51
+ expect(email.subject).toContain('Reset your password');
52
+
53
+ // No regex — magicLink is auto-extracted at the edge
54
+ await page.goto(email.magicLink);
55
+ });
56
+ ```
57
+
58
+ ## OTP Auto-Extraction
59
+
60
+ ZeroDrop extracts OTP codes and magic links at the edge before emails reach your test suite. No regex required.
61
+
62
+ ```javascript
63
+ const email = await mail.waitForLatest(inbox);
64
+
65
+ // Auto-extracted fields
66
+ email.otp // "123456" — 4-8 digit verification code
67
+ email.magicLink // "https://app.com/verify?token=abc" — verification/reset link
68
+
69
+ // Raw body still available if you need it
70
+ email.body // Full plain-text body
71
+ ```
72
+
73
+ Both fields are `null` if not detected in the email.
74
+
75
+ ## Parallel CI Runs
76
+
77
+ Inbox generation is client-side — no API call, no throttling.
78
+ 50 parallel tests generate 50 inboxes instantly.
79
+
80
+ ```javascript
81
+ // Safe to run in parallel — generateInbox() is local
82
+ const inboxes = Array.from({ length: 50 }, () => mail.generateInbox());
83
+ ```
84
+
85
+ The rate limit applies to the polling endpoint — 20 requests
86
+ per 10 seconds per IP on the free tier. For heavy parallel
87
+ usage, stagger `waitForLatest()` calls slightly:
88
+
89
+ ```javascript
90
+ // Stagger polls to avoid burst on shared IP
91
+ const results = await Promise.all(
92
+ inboxes.map((inbox, i) =>
93
+ new Promise(resolve => setTimeout(resolve, i * 100))
94
+ .then(() => mail.waitForLatest(inbox, { timeout: 15000 }))
95
+ )
96
+ );
97
+ ```
98
+
99
+ For CI pipelines with 20+ parallel tests, use a Workspace
100
+ API key — dedicated rate limit bucket, not shared with
101
+ the public pool.
102
+
103
+ ## Webhook Mode (Staging Servers)
104
+
105
+ ```javascript
106
+ const mail = new ZeroDrop(process.env.ZERODROP_API_KEY);
107
+
108
+ await mail.onReceived('qa-test@yourcompany.com', 'https://your-server.com/webhook');
109
+ // ZeroDrop POSTs the email JSON to your URL when it arrives
110
+ ```
111
+
112
+ ## API
113
+
114
+ ### `new ZeroDrop(apiKey?, options?)`
115
+ - `apiKey` — optional. Omit for free sandbox mode.
116
+ - `options.baseUrl` — override the API base URL.
117
+
118
+ ### `mail.generateInbox(): string`
119
+ Returns a ready-to-use email address instantly. No network request.
120
+
121
+ ### `mail.fetchLatest(inbox): Promise<ZeroDropEmail | null>`
122
+ Returns the latest email or null if inbox is empty.
123
+
124
+ ### `mail.waitForLatest(inbox, options?): Promise<ZeroDropEmail>`
125
+ Polls until an email arrives. Throws `ZeroDropTimeoutError` on timeout.
126
+ - `options.timeout` — ms to wait (default: 10000)
127
+ - `options.pollInterval` — ms between polls (default: 2000)
128
+
129
+ ### `mail.onReceived(inbox, webhookUrl): Promise<{ registered: boolean }>`
130
+ Registers a webhook. Requires API key (Workspace tier).
131
+
132
+ ## Types
133
+
134
+ ```typescript
135
+ interface ZeroDropEmail {
136
+ id: string;
137
+ from: string;
138
+ to: string;
139
+ subject: string;
140
+ body: string;
141
+ rawBody: string;
142
+ receivedAt: Date;
143
+ otp: string | null; // Auto-extracted OTP code (4-8 digits)
144
+ magicLink: string | null; // Auto-extracted verification/reset link
145
+ }
146
+ ```
147
+
148
+ ## Error Handling
149
+
150
+ ```javascript
151
+ import { ZeroDrop, ZeroDropTimeoutError } from 'zerodrop-client';
152
+
153
+ try {
154
+ const email = await mail.waitForLatest(inbox, { timeout: 10000 });
155
+ } catch (err) {
156
+ if (err instanceof ZeroDropTimeoutError) {
157
+ console.error('No email received — check your app is sending correctly');
158
+ }
159
+ }
160
+ ```
161
+
162
+ ## Free vs Workspace
163
+
164
+ | | Free | Workspace |
165
+ |---|---|---|
166
+ | Inbox generation | ✓ | ✓ |
167
+ | OTP auto-extraction | ✓ | ✓ |
168
+ | Magic link extraction | ✓ | ✓ |
169
+ | Email retention | 30 min | 7 days |
170
+ | Custom domains | ✗ | ✓ |
171
+ | API key | ✗ | ✓ |
172
+ | Webhooks | ✗ | ✓ |
173
+ | AI spam filter | On | Off |
174
+
175
+ Get a Workspace at [zerodrop.dev](https://zerodrop.dev)
176
+
177
+ ## License
178
+
179
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "zerodrop-client",
3
- "version": "0.1.6",
3
+ "version": "0.1.7",
4
4
  "description": "Instant temporary email inboxes for CI pipelines and QA testing",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",