{"_id":"@bye_bouncer/sdk","_rev":"2-f3824f3464573a11792a3ccb701a9ee5","name":"@bye_bouncer/sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@bye_bouncer/sdk","version":"0.1.0","keywords":["email","verification","bounce","byebouncer","smtp","email-validation"],"author":{"name":"ByeBouncer","email":"hello@byebouncer.com"},"license":"MIT","_id":"@bye_bouncer/sdk@0.1.0","maintainers":[{"name":"byebouncer","email":"hello@byebouncer.com"}],"homepage":"https://byebouncer.com","bugs":{"url":"https://github.com/fidelp27/byebouncer/issues","email":"hello@byebouncer.com"},"dist":{"shasum":"e18ed3fdbe150e0d40db6b12266f32bf294fca40","tarball":"https://registry.npmjs.org/@bye_bouncer/sdk/-/sdk-0.1.0.tgz","fileCount":16,"integrity":"sha512-XiGZF1vnyGWejH139nrxYZrtsQkdxD/3/+KBhpQZDKghOGOzA2RZ2sCp4Y9amI7uEfwC+TvGnG3bI2/ZK9V3Sg==","signatures":[{"sig":"MEYCIQCRtwryVh9NPvoDYAtA+mdi76sIErFKyXOZ2Y8vJUQkdQIhAN1DnNLwUX1rwVPpyq88RxU3p9ZaiFj1k/YB3NxT6BB+","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":31376},"main":"./dist-cjs/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist-cjs/index.js"}},"gitHead":"7b77e4699b722e68f3e4ad365b2d3deb45fb9366","scripts":{"test":"npm run build && node --test --import tsx test/*.test.ts","build":"tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && node scripts/prepare-cjs.mjs","prepack":"npm run build"},"_npmUser":{"name":"byebouncer","email":"hello@byebouncer.com"},"repository":{"url":"git+https://github.com/fidelp27/byebouncer.git","type":"git","directory":"sdks/node"},"_npmVersion":"11.13.0","description":"Official Node.js SDK for the ByeBouncer email verification API.","directories":{},"_nodeVersion":"24.13.1","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.6.3"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1788707487306_0.8785238309727323","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"_id":"@bye_bouncer/sdk@0.2.0","bugs":{"url":"https://github.com/fidelp27/byebouncer/issues","email":"hello@byebouncer.com"},"dist":{"shasum":"2c6116baf34df2f6ca1f7fa184cc9cedba273078","tarball":"https://registry.npmjs.org/@bye_bouncer/sdk/-/sdk-0.2.0.tgz","fileCount":16,"integrity":"sha512-R0YSfLx5oG6shraLHLPc3Mdqr2raMFRCaWzkSwlDDx4w3JKs42yoCzGl/8OQaUlVgdRulqBAdGRfilU4v6pjTw==","signatures":[{"sig":"MEQCIDAS0WKVnmFv4nmKHHUteCg64dnPZj9I0An7uN3URlQPAiBNN/dYOkPQ6eAo6xOPKIm0jSfuYBa7ruQWM8TSn8djNA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHHRh2OquHw+ZY1/V+AhDKNreZVU0p+ll7/vww9zPxksAiBluiZmeHa/10r3vebem6cDDgMSnQxwx6dQUo5US7P5qg=="}],"unpackedSize":40654},"main":"./dist-cjs/index.js","name":"@bye_bouncer/sdk","type":"module","types":"./dist/index.d.ts","author":{"name":"ByeBouncer","email":"hello@byebouncer.com"},"module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist-cjs/index.js"}},"gitHead":"6975a76051deb02a19249ca0c1e80c417a5509c1","license":"MIT","scripts":{"test":"npm run build && node --test --import tsx test/*.test.ts","build":"tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && node scripts/prepare-cjs.mjs","prepack":"npm run build"},"version":"0.2.0","_npmUser":{"name":"byebouncer","email":"hello@byebouncer.com"},"homepage":"https://byebouncer.com","keywords":["email","verification","bounce","byebouncer","smtp","email-validation"],"repository":{"url":"git+https://github.com/fidelp27/byebouncer.git","type":"git","directory":"sdks/node"},"_npmVersion":"11.13.0","description":"Official Node.js SDK for the ByeBouncer email verification API.","directories":{},"maintainers":[{"name":"byebouncer","email":"hello@byebouncer.com"}],"_nodeVersion":"24.13.1","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.6.3"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.2.0_1789985216668_0.38701189369344857"}}},"time":{"created":"2026-09-06T15:11:27.070Z","modified":"2026-09-21T10:06:56.942Z","0.1.0":"2026-09-06T15:11:27.440Z","0.2.0":"2026-09-21T10:06:56.766Z"},"bugs":{"url":"https://github.com/fidelp27/byebouncer/issues","email":"hello@byebouncer.com"},"author":{"name":"ByeBouncer","email":"hello@byebouncer.com"},"license":"MIT","homepage":"https://byebouncer.com","keywords":["email","verification","bounce","byebouncer","smtp","email-validation"],"repository":{"url":"git+https://github.com/fidelp27/byebouncer.git","type":"git","directory":"sdks/node"},"description":"Official Node.js SDK for the ByeBouncer email verification API.","maintainers":[{"name":"byebouncer","email":"hello@byebouncer.com"}],"readme":"# @bye_bouncer/sdk\n\nOfficial Node.js/TypeScript SDK for the [ByeBouncer](https://byebouncer.com) email verification API.\n\nReal-time single-email verification, bulk CSV verification (up to 50k emails per job), credits management, HMAC-signed webhooks.\n\n## Install\n\n```bash\nnpm install @bye_bouncer/sdk\n# or\npnpm add @bye_bouncer/sdk\n# or\nyarn add @bye_bouncer/sdk\n```\n\nRequires Node.js 18+.\n\n## Quickstart\n\n```ts\nimport { ByeBouncer } from \"@bye_bouncer/sdk\";\n\nconst client = new ByeBouncer({ apiKey: process.env.BB_API_KEY! });\n\nconst result = await client.verify(\"user@gmail.com\");\nconsole.log(result.status);       // \"deliverable\" | \"undeliverable\" | \"risky\" | \"unknown\"\nconsole.log(result.action);       // \"allow\" | \"review\" | \"block\"\nconsole.log(result.signals);      // [\"valid_syntax\", \"mx_found\", ...]\nconsole.log(result.credits_remaining);\n```\n\nGet your `BB_API_KEY` from https://byebouncer.com/dashboard (format `bb_live_...`).\n\n## Bulk verification\n\n```ts\nconst { job, estimated_seconds } = await client.bulk({\n  emails: [\"a@gmail.com\", \"b@outlook.com\", /* ...up to 5.000 */],\n  filename: \"my_list.csv\",\n  webhook_url: \"https://api.myapp.com/hooks/byebouncer\", // optional\n});\n\nconsole.log(`Job ${job.id}, ~${estimated_seconds}s`);\n```\n\nIf you pass `webhook_url`, the creation response includes the effective\n`webhook_secret` (generated or supplied). Store it immediately; later job reads\nnever return it.\n\n### Polling for completion\n\nFor small jobs (<5k emails), poll and download the CSV directly:\n\n```ts\nconst { job: final, csv } = await client.bulkAndWait(\n  { emails: [...] },\n  {\n    intervalMs: 3000,\n    onProgress: (j) => console.log(`${j.processed}/${j.total_emails}`),\n  }\n);\n\nrequire(\"fs\").writeFileSync(\"results.csv\", csv);\n```\n\n### Webhooks (recommended for large jobs)\n\nPrefer webhooks over polling. On completion ByeBouncer POSTs to your URL with:\n\n```\nX-ByeBouncer-Event: bulk.completed\nX-ByeBouncer-Signature: <hex HMAC-SHA256(body, webhook_secret)>\nContent-Type: application/json\n\n{\n  \"event\": \"bulk.completed\",\n  \"job_id\": \"...\",\n  \"processed\": 1234,\n  \"valid\": 800, \"invalid\": 300, \"unknown\": 134,\n  \"credits_refunded\": 0,\n  \"timestamp\": \"2026-09-05T14:30:00Z\"\n}\n```\n\nAttach or rotate the webhook after creating the job:\n\n```ts\nconst { webhook_secret } = await client.bulkSetWebhook(job.id, {\n  webhook_url: \"https://api.myapp.com/hooks/byebouncer\",\n});\n// Store webhook_secret NOW — it is returned only once.\n```\n\n### Manual polling + download\n\n```ts\nconst status = await client.bulkStatus(jobId);\nif (status.status === \"completed\") {\n  const { url } = await client.bulkDownloadUrl(jobId);\n  const res = await fetch(url);\n  const csv = await res.text();\n}\n```\n\n### Cancel\n\n```ts\nconst cancelled = await client.bulkCancel(jobId);\nconsole.log(`Refunded ${cancelled.credits_refunded} credits`);\n```\n\n## Error handling\n\nAll non-2xx responses throw a `ByeBouncerError` (or subclass) with `code`, `status`, and `detail`.\n\n```ts\nimport { ByeBouncer, InsufficientCreditsError, RateLimitError } from \"@bye_bouncer/sdk\";\n\ntry {\n  await client.verify(\"user@gmail.com\");\n} catch (err) {\n  if (err instanceof InsufficientCreditsError) {\n    console.error(`Out of credits (${err.creditsRemaining ?? \"?\"} left)`);\n  } else if (err instanceof RateLimitError) {\n    console.error(`Rate limited, retry after ${err.retryAfterSeconds}s`);\n  } else {\n    throw err;\n  }\n}\n```\n\n## API reference\n\nEvery method mirrors the [OpenAPI spec](https://github.com/fidelp27/byebouncer/blob/master/docs/api/openapi.yaml).\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `verify(email)` | `POST /verify` | Verify a single email |\n| `credits()` | `GET /credits` | Get balance |\n| `bulk(options)` | `POST /bulk` | Enqueue a bulk job |\n| `bulkStatus(id)` | `GET /bulk/{id}` | Fetch job |\n| `bulkCancel(id)` | `DELETE /bulk/{id}` | Cancel |\n| `bulkDownloadUrl(id)` | `GET /bulk/{id}/download` | Signed CSV URL |\n| `bulkSetWebhook(id, opts)` | `POST /bulk/{id}/webhook` | Attach/rotate webhook |\n| `bulkWaitForCompletion(id, opts)` | polls `bulkStatus` | Convenience helper |\n| `bulkAndWait(input, opts)` | create+poll+download | Convenience helper |\n\n## Options\n\n```ts\nnew ByeBouncer({\n  apiKey: \"bb_live_...\",             // required\n  baseUrl: \"https://api.byebouncer.com\", // default\n  timeoutMs: 30_000,                 // per-request timeout\n  fetch: customFetch,                // custom fetch (Node < 18)\n});\n```\n\n## Support\n\n- Docs: https://byebouncer.com/docs\n- Email: hello@byebouncer.com\n- Issues: https://github.com/fidelp27/byebouncer/issues\n\n## License\n\nMIT © ByeBouncer\n","readmeFilename":"README.md"}