1
2import assert from 'node:assert/strict';
3import { after, afterEach, describe, it } from 'node:test';
4
5import type { MockHandler, MockServer } from './helpers.js';
6import { removeStorage, runActor, startMockTomba, startStandbyActor, totalCharges } from './helpers.js';
7
8function person(email: string): Record<string, unknown> {
9 return {
10 email,
11 first_name: 'Patrick',
12 last_name: 'Collison',
13 full_name: 'Patrick Collison',
14 gender: 'male',
15 phone_number: false,
16 type: 'personal',
17 country: 'US',
18 position: 'CEO',
19 twitter: 'https://twitter.com/patrickc',
20 linkedin: 'https://www.linkedin.com/in/patrickcollison',
21 accept_all: false,
22 website_url: 'stripe.com',
23 company: 'Stripe',
24 score: 99,
25 verification: { date: '2026-09-01T00:00:00+02:00', status: 'valid' },
26 sources: [
27 {
28 uri: 'https://stripe.com/about',
29 website_url: 'stripe.com',
30 extracted_on: '2024-09-17T11:26:56+02:00',
31 last_seen_on: '2026-09-06T04:51:06+02:00',
32 still_on_page: true,
33 },
34 ],
35 };
36}
37
38
39const NEGATIVE = {
40 email: null,
41 first_name: null,
42 last_name: null,
43 full_name: null,
44 company: null,
45 score: 0,
46 verification: { date: null, status: null },
47 sources: [],
48};
49
50
51function phonesFor(email: string): Record<string, unknown>[] {
52 if (email.startsWith('nophone@')) return [];
53 if (email.startsWith('two@')) {
54 return [
55 { number: '+14155550123', type: 'mobile' },
56 { number: '+14155550199', type: 'work' },
57 ];
58 }
59 return [{ number: '+14155550123', type: 'mobile' }];
60}
61
62
63const tomba: MockHandler = (req) => {
64 assert.equal(req.method, 'GET');
65 assert.equal(req.path, '/enrich');
66 const { email, enrich_mobile: enrichMobile } = req.query;
67 const phones = enrichMobile === 'true' ? { phone_data: phonesFor(email) } : {};
68 if (email === 'empty@example.com') return { body: { data: null } };
69 if (email === 'emptyobj@example.com') return { body: { data: {} } };
70 if (email === 'unknown@example.com') return { body: { data: { ...NEGATIVE, ...phones } } };
71 if (email === 'invalid@example.com') return { status: 422, body: { errors: { message: 'Invalid email' } } };
72 if (email === 'html@example.com') return { raw: '<html>Bad gateway</html>' };
73 return { body: { data: { ...person(email), ...phones } } };
74};
75
76const servers: MockServer[] = [];
77const dirs: string[] = [];
78
79async function mock(handler: MockHandler = tomba): Promise<MockServer> {
80 const server = await startMockTomba(handler);
81 servers.push(server);
82 return server;
83}
84
85async function run(...args: Parameters<typeof runActor>) {
86 const result = await runActor(...args);
87 dirs.push(result.storageDir);
88 return result;
89}
90
91afterEach(async () => {
92 await Promise.all(servers.splice(0).map(async (s) => s.close()));
93});
94
95after(async () => {
96 await Promise.all(dirs.map(removeStorage));
97});
98
99describe('email-enrichment', () => {
100 it('returns the enriched profile and charges one event per billable email', async () => {
101 const server = await mock();
102 const result = await run({
103 input: { emails: ['patrick@stripe.com', 'empty@example.com', 'emptyobj@example.com'] },
104 endpoint: server.url,
105 });
106
107 assert.equal(result.code, 0, result.output);
108 assert.equal(result.items.length, 3);
109 const found = result.items.find((i) => i.email === 'patrick@stripe.com');
110 assert.deepEqual(found, {
111 ...person('patrick@stripe.com'),
112 source: 'tomba_email_enrichment',
113 phoneNumbers: 0,
114 charged: true,
115 chargedCredits: 1,
116 cached: false,
117 });
118
119 for (const email of ['empty@example.com', 'emptyobj@example.com']) {
120 const item = result.items.find((i) => i.email === email);
121 assert.deepEqual(item, {
122 email,
123 source: 'tomba_email_enrichment',
124 phoneNumbers: 0,
125 charged: false,
126 chargedCredits: 0,
127 cached: false,
128 error: 'No enrichment data found',
129 });
130 }
131
132 assert.deepEqual(result.chargeCounts, { 'tomba-request': 1 });
133 });
134
135 it('charges a negative answer and keeps the input email', async () => {
136 const server = await mock();
137 const result = await run({ input: { emails: ['unknown@example.com'] }, endpoint: server.url });
138
139 assert.equal(result.code, 0, result.output);
140 assert.equal(result.items.length, 1);
141 assert.equal(result.items[0].email, 'unknown@example.com');
142 assert.equal(result.items[0].full_name, null);
143 assert.equal(result.items[0].charged, true);
144 assert.equal(result.items[0].error, undefined);
145 assert.deepEqual(result.chargeCounts, { 'tomba-request': 1 });
146 });
147
148 it('sends the built-in credentials to Tomba', async () => {
149 const server = await mock();
150 await run({ input: { emails: ['patrick@stripe.com'] }, endpoint: server.url });
151 assert.equal(server.requests.length, 1);
152 assert.equal(server.requests[0].headers['x-tomba-key'], 'ta_test_key');
153 assert.equal(server.requests[0].headers['x-tomba-secret'], 'ts_test_secret');
154 });
155
156 it('normalizes and deduplicates emails', async () => {
157 const server = await mock();
158 const result = await run({
159 input: { emails: [' Patrick@Stripe.com ', 'patrick@stripe.com', 'PATRICK@STRIPE.COM', ''] },
160 endpoint: server.url,
161 });
162 assert.deepEqual(
163 server.requests.map((r) => r.query.email),
164 ['patrick@stripe.com'],
165 );
166 assert.equal(result.items.length, 1);
167 assert.equal(result.items[0].email, 'patrick@stripe.com');
168 });
169
170 it('does not charge Tomba error statuses and does not retry them', async () => {
171 const server = await mock();
172 const result = await run({ input: { emails: ['invalid@example.com'] }, endpoint: server.url });
173 assert.equal(result.code, 0, result.output);
174 assert.equal(server.requests.length, 1);
175 assert.equal(result.items[0].charged, false);
176 assert.match(String(result.items[0].error), /422: Invalid email/);
177 assert.equal(totalCharges(result), 0);
178 });
179
180 it('does not charge a non-JSON body', async () => {
181 const server = await mock();
182 const result = await run({ input: { emails: ['html@example.com'] }, endpoint: server.url });
183 assert.equal(result.items[0].charged, false);
184 assert.match(String(result.items[0].error), /Invalid response/);
185 assert.equal(totalCharges(result), 0);
186 });
187
188 it('retries 429 and 5xx responses, then charges the success once', async () => {
189 let calls = 0;
190 const server = await mock(async (req) => {
191 calls++;
192 if (calls === 1)
193 return {
194 status: 429,
195 body: { errors: { message: 'Too many requests' } },
196 headers: { 'retry-after': '1' },
197 };
198 if (calls === 2) return { status: 503, body: {} };
199 return tomba(req);
200 });
201 const result = await run({ input: { emails: ['patrick@stripe.com'], maxRetries: 3 }, endpoint: server.url });
202 assert.equal(server.requests.length, 3);
203 assert.equal(result.items.length, 1);
204 assert.equal(result.items[0].charged, true);
205 assert.deepEqual(result.chargeCounts, { 'tomba-request': 1 });
206 });
207
208 it('serves repeated runs from the cache for free', async () => {
209 const server = await mock();
210 const first = await run({ input: { emails: ['patrick@stripe.com'] }, endpoint: server.url });
211 const second = await run({
212 input: { emails: ['patrick@stripe.com'] },
213 endpoint: server.url,
214 storageDir: first.storageDir,
215 });
216
217 assert.equal(server.requests.length, 1);
218 assert.equal(second.items.length, 1);
219 assert.equal(second.items[0].full_name, 'Patrick Collison');
220 assert.equal(second.items[0].cached, true);
221 assert.equal(second.items[0].charged, false);
222 assert.equal(totalCharges(second), 0);
223 });
224
225 it('calls Tomba again when the cache is disabled', async () => {
226 const server = await mock();
227 const first = await run({ input: { emails: ['patrick@stripe.com'], useCache: false }, endpoint: server.url });
228 await run({
229 input: { emails: ['patrick@stripe.com'], useCache: false },
230 endpoint: server.url,
231 storageDir: first.storageDir,
232 });
233 assert.equal(server.requests.length, 2);
234 });
235
236 it('stops at the max charge limit and resumes without reprocessing', async () => {
237 const server = await mock();
238 const emails = ['a@a.com', 'b@b.com', 'c@c.com', 'd@d.com', 'e@e.com'];
239 const input = { emails, maxConcurrency: 1, useCache: false, maxResults: 100 };
240
241
242 const first = await run({ input, endpoint: server.url, maxTotalChargeUsd: 2 });
243 assert.equal(first.code, 0, first.output);
244 assert.equal(totalCharges(first), 2);
245 assert.equal(server.requests.length, 2);
246 assert.equal(first.items.length, 2);
247
248 const second = await run({ input, endpoint: server.url, storageDir: first.storageDir, keepStorage: true });
249 assert.equal(second.code, 0, second.output);
250 assert.deepEqual(
251 server.requests.map((r) => r.query.email),
252 emails,
253 );
254 assert.equal(second.items.length, 5);
255 });
256
257 it('respects maxResults', async () => {
258 const server = await mock();
259 const result = await run({
260 input: { emails: ['a@a.com', 'b@b.com', 'c@c.com'], maxResults: 2, maxConcurrency: 1 },
261 endpoint: server.url,
262 });
263 assert.equal(result.items.length, 2);
264 assert.equal(server.requests.length, 2);
265 });
266
267 it('runs requests in parallel', async () => {
268 let active = 0;
269 let peak = 0;
270 const server = await mock(async (req) => {
271 active++;
272 peak = Math.max(peak, active);
273 await new Promise((r) => {
274 setTimeout(r, 100);
275 });
276 active--;
277 return tomba(req);
278 });
279 const emails = Array.from({ length: 8 }, (_, i) => `person${i}@example.org`);
280 await run({ input: { emails, maxConcurrency: 4 }, endpoint: server.url });
281 assert.equal(server.requests.length, 8);
282 assert.ok(peak > 1 && peak <= 4, `peak concurrency ${peak}`);
283 });
284
285 it('fails without Tomba credentials and never calls the API', async () => {
286 const server = await mock();
287 const result = await run({
288 input: { emails: ['patrick@stripe.com'] },
289 endpoint: server.url,
290 withCredentials: false,
291 });
292 assert.notEqual(result.code, 0);
293 assert.match(result.output, /misconfigured/);
294 assert.doesNotMatch(result.output, /ta_test_key|ts_test_secret/);
295 assert.equal(server.requests.length, 0);
296 });
297
298 it('sends enrich_mobile and webhook_url only when they are set', async () => {
299 const server = await mock();
300 await run({ input: { emails: ['patrick@stripe.com'], enrichMobile: false }, endpoint: server.url });
301 await run({
302 input: {
303 emails: ['john@stripe.com'],
304 enrichMobile: true,
305 webhookUrl: 'https://hooks.example.com/tomba',
306 },
307 endpoint: server.url,
308 });
309 assert.deepEqual(
310 server.requests.map((r) => r.query),
311 [
312 { email: 'patrick@stripe.com' },
313 { email: 'john@stripe.com', enrich_mobile: 'true', webhook_url: 'https://hooks.example.com/tomba' },
314 ],
315 );
316 });
317
318 it('fails on a webhook URL that is not http(s) and never calls the API', async () => {
319 const server = await mock();
320 const result = await run({
321 input: { emails: ['patrick@stripe.com'], webhookUrl: 'ftp://hooks.example.com' },
322 endpoint: server.url,
323 });
324 assert.notEqual(result.code, 0);
325 assert.equal(server.requests.length, 0);
326 });
327
328 it('charges 1 credit without enrichMobile and returns no phone data', async () => {
329 const server = await mock();
330 const result = await run({ input: { emails: ['two@stripe.com'] }, endpoint: server.url });
331 assert.equal(result.items[0].phone_data, undefined);
332 assert.equal(result.items[0].phoneNumbers, 0);
333 assert.equal(result.items[0].chargedCredits, 1);
334 assert.deepEqual(result.chargeCounts, { 'tomba-request': 1 });
335 });
336
337 it('charges 6 credits per result with phone data, whatever the number of phones', async () => {
338 const server = await mock();
339 const result = await run({
340 input: { emails: ['patrick@stripe.com', 'two@stripe.com'], enrichMobile: true },
341 endpoint: server.url,
342 });
343 assert.equal(result.code, 0, result.output);
344 const one = result.items.find((i) => i.email === 'patrick@stripe.com');
345 const two = result.items.find((i) => i.email === 'two@stripe.com');
346 assert.deepEqual(one?.phone_data, [{ number: '+14155550123', type: 'mobile' }]);
347 assert.equal(one?.phoneNumbers, 1);
348 assert.equal(one?.chargedCredits, 6);
349 assert.equal(one?.charged, true);
350 assert.equal(two?.phoneNumbers, 2);
351 assert.equal(two?.chargedCredits, 6);
352 assert.deepEqual(result.chargeCounts, { 'tomba-request': 12 });
353 });
354
355 it('charges 1 credit with enrichMobile when no phone number is found', async () => {
356 const server = await mock();
357 const result = await run({
358 input: { emails: ['nophone@stripe.com'], enrichMobile: true },
359 endpoint: server.url,
360 });
361 assert.deepEqual(result.items[0].phone_data, []);
362 assert.equal(result.items[0].phoneNumbers, 0);
363 assert.equal(result.items[0].chargedCredits, 1);
364 assert.deepEqual(result.chargeCounts, { 'tomba-request': 1 });
365 });
366
367 it('serves phone data from the cache for free', async () => {
368 const server = await mock();
369 const input = { emails: ['two@stripe.com'], enrichMobile: true };
370 const first = await run({ input, endpoint: server.url });
371 assert.equal(totalCharges(first), 6);
372 const second = await run({ input, endpoint: server.url, storageDir: first.storageDir });
373 assert.equal(server.requests.length, 1);
374 assert.equal(second.items[0].cached, true);
375 assert.equal(second.items[0].charged, false);
376 assert.equal(second.items[0].chargedCredits, 0);
377 assert.equal(second.items[0].phoneNumbers, 2);
378 assert.equal(totalCharges(second), 0);
379 });
380
381 it('does not reuse a cached result without phone data when enrichMobile is turned on', async () => {
382 const server = await mock();
383 const first = await run({ input: { emails: ['patrick@stripe.com'] }, endpoint: server.url });
384 const second = await run({
385 input: { emails: ['patrick@stripe.com'], enrichMobile: true },
386 endpoint: server.url,
387 storageDir: first.storageDir,
388 });
389 assert.equal(server.requests.length, 2);
390 assert.equal(second.items[0].phoneNumbers, 1);
391 assert.equal(totalCharges(second), 6);
392 });
393
394 it('fails on empty input', async () => {
395 const server = await mock();
396 const result = await run({ input: { emails: [] }, endpoint: server.url });
397 assert.notEqual(result.code, 0);
398 assert.equal(server.requests.length, 0);
399 });
400
401 it('skips blank entries without calling Tomba', async () => {
402 const server = await mock();
403 const result = await run({ input: { emails: ['', ' '] }, endpoint: server.url });
404 assert.equal(result.code, 0, result.output);
405 assert.equal(server.requests.length, 0);
406 assert.equal(result.items.length, 0);
407 assert.equal(totalCharges(result), 0);
408 });
409});
410
411describe('email-enrichment standby (real-time API)', () => {
412 it('answers the readiness probe and a bare GET with usage info', async () => {
413 const server = await mock();
414 const actor = await startStandbyActor({ endpoint: server.url });
415 try {
416 const probe = await actor.call('/', { headers: { 'x-apify-container-server-readiness-probe': '1' } });
417 assert.equal(probe.status, 200);
418 const usage = await actor.call('/');
419 assert.equal(usage.status, 200);
420 assert.match(String(usage.body.usage), /GET/);
421 assert.equal(server.requests.length, 0);
422 } finally {
423 await actor.stop();
424 }
425 });
426
427 it('enriches emails from GET query parameters and charges per credit', async () => {
428 const server = await mock();
429 const actor = await startStandbyActor({ endpoint: server.url });
430 let stopped;
431 try {
432 const res = await actor.call('/?email=Patrick@Stripe.com&email=empty@example.com');
433 assert.equal(res.status, 200);
434 const items = res.body.items as Record<string, unknown>[];
435 assert.deepEqual(
436 items.find((i) => i.email === 'patrick@stripe.com'),
437 {
438 ...person('patrick@stripe.com'),
439 source: 'tomba_email_enrichment',
440 phoneNumbers: 0,
441 charged: true,
442 chargedCredits: 1,
443 cached: false,
444 },
445 );
446 assert.equal(items.find((i) => i.email === 'empty@example.com')?.error, 'No enrichment data found');
447
448 const phones = await actor.call('/?emails=two@stripe.com&enrichMobile=true');
449 const [item] = phones.body.items as Record<string, unknown>[];
450 assert.equal(item.phoneNumbers, 2);
451 assert.equal(item.chargedCredits, 6);
452 assert.equal(server.requests.at(-1)?.query.enrich_mobile, 'true');
453 } finally {
454 stopped = await actor.stop();
455 }
456 assert.deepEqual(stopped.chargeCounts, { 'tomba-request': 7 });
457 });
458
459 it('accepts a POST with the same JSON input as a normal run', async () => {
460 const server = await mock();
461 const actor = await startStandbyActor({ endpoint: server.url });
462 try {
463 const res = await actor.call('/', {
464 body: { emails: ['a@stripe.com', 'b@stripe.com', 'c@stripe.com'], maxResults: 2 },
465 });
466 assert.equal(res.status, 200);
467 assert.equal((res.body.items as unknown[]).length, 2);
468 assert.equal(server.requests.length, 2);
469 } finally {
470 await actor.stop();
471 }
472 });
473
474 it('serves repeated requests from the cache for free', async () => {
475 const server = await mock();
476 const actor = await startStandbyActor({ endpoint: server.url });
477 let stopped;
478 try {
479 await actor.call('/?email=patrick@stripe.com');
480 const second = await actor.call('/?email=patrick@stripe.com');
481 assert.ok((second.body.items as Record<string, unknown>[]).every((i) => i.cached === true));
482 assert.equal(server.requests.length, 1);
483 } finally {
484 stopped = await actor.stop();
485 }
486 assert.deepEqual(stopped.chargeCounts, { 'tomba-request': 1 });
487 });
488
489 it('keeps serving after a request hits maxResults', async () => {
490 const server = await mock();
491 const actor = await startStandbyActor({ endpoint: server.url });
492 try {
493 const first = await actor.call('/?email=a@stripe.com,b@stripe.com&maxResults=1');
494 assert.equal((first.body.items as unknown[]).length, 1);
495 const second = await actor.call('/?email=c@stripe.com&email=d@stripe.com');
496 assert.equal((second.body.items as unknown[]).length, 2);
497 } finally {
498 await actor.stop();
499 }
500 });
501
502 it('rejects invalid input with 400 and unknown paths with 404', async () => {
503 const server = await mock();
504 const actor = await startStandbyActor({ endpoint: server.url });
505 try {
506 assert.equal((await actor.call('/', { body: {} })).status, 400);
507 assert.equal((await actor.call('/', { body: 'not json' })).status, 400);
508 assert.equal((await actor.call('/?maxResults=abc&email=a@stripe.com')).status, 400);
509 assert.equal((await actor.call('/?enrichMobile=maybe&email=a@stripe.com')).status, 400);
510 assert.equal((await actor.call('/?email=a@stripe.com&webhookUrl=ftp://x')).status, 400);
511 assert.equal((await actor.call('/nope')).status, 404);
512 assert.equal((await actor.call('/', { method: 'DELETE' })).status, 405);
513 assert.equal(server.requests.length, 0);
514 } finally {
515 await actor.stop();
516 }
517 });
518
519 it('returns 402 once the max charge limit is reached', async () => {
520 const server = await mock();
521 const actor = await startStandbyActor({ endpoint: server.url, maxTotalChargeUsd: 1 });
522 try {
523 const first = await actor.call('/?email=a@stripe.com');
524 assert.equal(first.status, 200);
525 const second = await actor.call('/?email=b@stripe.com');
526 assert.equal(second.status, 402);
527 assert.equal(server.requests.length, 1);
528 } finally {
529 await actor.stop();
530 }
531 });
532});