npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@bye_bouncer/sdk

v0.4.0

Published

Official Node.js SDK for the ByeBouncer email, phone and IP data validation API.

Readme

@bye_bouncer/sdk

Official Node.js/TypeScript SDK for the ByeBouncer data validation API.

Email, IP and phone verification, email-only bulk jobs (up to 5,000 unique emails per job), CSV downloads and HMAC-signed webhooks.

Billable cache hits cost the same as fresh results: email 1 credit, public IP 1, valid local phone 1 or conclusive carrier-enriched phone 3. Before the first purchase, phone checks also use a shared 30-credit starter quota.

Install

npm install @bye_bouncer/sdk
# or
pnpm add @bye_bouncer/sdk
# or
yarn add @bye_bouncer/sdk

Requires Node.js 18+.

The default API URL is https://api.byebouncer.com; each user supplies their own secret API key from the dashboard. Keep keys in environment variables on your server. To upgrade an existing installation, run npm install @bye_bouncer/sdk@latest.

Independent validation services (0.4.0)

Choose an explicit service to control the information returned and its cost. The 0.4.0 methods use the factual validation-v1 contract: independent checks and attributes without scores or a contact acceptance decision. Existing methods and routes remain available for compatibility.

import { ByeBouncer } from "@bye_bouncer/sdk";
const client = new ByeBouncer({ apiKey: process.env.BB_API_KEY! });
const result = await client.validate({ email: "[email protected]", phone: "+12025550123", phone_mode: "local", live: false });
console.log(result.results.email?.deliverability);
console.log(result.results.phone?.checks);

// One service at a time (0.4.0+):
await client.validateEmail("[email protected]");   // POST /verify-email · 1 credit
await client.lookupIP("8.8.8.8");                    // POST /verify-ip · 1 credit
await client.validatePhoneLocal("+12025550123");     // POST /verify-phone/local · 1 credit
await client.lookupPhoneCarrier("+12025550123");     // POST /verify-phone/carrier · 3 credits
await client.lookupPhoneNetwork("+12025550123");     // POST /verify-phone/live · 6 credits
// In client.validate(...), set phone_mode: "local" | "carrier" to choose the phone service.
// Factual email CSV: client.bulk({ emails, result_format: "validation-v1" }).

Examples are illustrative. completed describes execution, not a favorable finding. unavailable does not mean invalid. Domain attributes, number format and network observations do not establish identity, ownership or commercial intent. Mobile network lookup is optional and has its own cost; it does not prove someone will answer.

Existing methods below keep the legacy contract for compatibility. Do not interpret legacy scores as fraud probabilities.

Three phone validation levels

| Level | Information | Credits per billable request | |---|---|---:| | 1 · Local | Numbering-plan format, normalization, country and estimated type; no remote provider call | 1 | | 2 · Carrier | Format validation and available carrier data; no extra format charge | 3 total | | 3 · Mobile network | Last network observation and timestamp; no call or message sent | 6 |

The levels are independent. Network status needs no prior carrier lookup. Local plus network costs up to 7 credits; carrier plus network, up to 9. A valid format does not prove a live line; network registration does not guarantee an answered call. unknown can be a billable network answer, while provider errors and inapplicable lookups are not charged. Billable cache hits retain the same price.

Legacy quickstart

import { ByeBouncer } from "@bye_bouncer/sdk";

const client = new ByeBouncer({ apiKey: process.env.BB_API_KEY! });

const result = await client.verify("[email protected]");
console.log(result.status);       // "deliverable" | "undeliverable" | "risky" | "unknown"
console.log(result.action);       // "allow" | "review" | "block"
console.log(result.signals);      // ["valid_syntax", "mx_found", ...]
console.log(result.credits_remaining);

Get your BB_API_KEY from https://byebouncer.com/dashboard (format bb_live_...).

For CommonJS, use const { ByeBouncer } = require("@bye_bouncer/sdk") in a .cjs file. JavaScript ESM examples run in .mjs files; the ! assertion in the TypeScript example above is only needed by TypeScript.

Bulk verification

const { job, estimated_seconds } = await client.bulk({
  emails: ["[email protected]", "[email protected]"], // up to 5,000 unique emails
  filename: "my_list.csv",
  webhook_url: "https://api.myapp.com/hooks/byebouncer", // optional
});

console.log(`Job ${job.id}, ~${estimated_seconds}s`);

If you pass webhook_url, the creation response includes the effective webhook_secret (generated or supplied). Store it immediately; later job reads never return it.

Polling for completion

For short-running jobs (maximum 5,000 unique emails), poll and download the CSV directly:

import { writeFileSync } from "node:fs";

const { job: final, csv } = await client.bulkAndWait(
  { emails: ["[email protected]", "[email protected]"] },
  {
    intervalMs: 3000,
    timeoutMs: 120_000,
    onProgress: (j) => console.log(`${j.processed}/${j.total_emails}`),
  }
);

writeFileSync("results.csv", csv);

Webhooks (recommended for large jobs)

Prefer webhooks over polling. On completion ByeBouncer POSTs to your URL with:

X-ByeBouncer-Event: bulk.completed
X-ByeBouncer-Signature: <hex HMAC-SHA256(body, webhook_secret)>
Content-Type: application/json

{
  "event": "bulk.completed",
  "job_id": "...",
  "processed": 1234,
  "valid": 800, "invalid": 300, "unknown": 134,
  "credits_refunded": 0,
  "timestamp": "2026-09-05T14:30:00Z"
}

Attach or rotate the webhook after creating the job:

const { webhook_secret } = await client.bulkSetWebhook(job.id, {
  webhook_url: "https://api.myapp.com/hooks/byebouncer",
});
// Store webhook_secret NOW — it is returned only once.

Manual polling + download

Download URLs expire after 15 minutes (900 seconds); request a fresh one when needed. Result CSVs are retained for 7 days after the job reaches a terminal state.

const status = await client.bulkStatus(job.id);
if (status.status === "completed" && status.result_available) {
  const { url } = await client.bulkDownloadUrl(job.id);
  const res = await fetch(url, { signal: AbortSignal.timeout(30_000) });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const csv = await res.text();
}

Cancel

Cancel a pending or processing job; a completed job can no longer be cancelled.

const cancelled = await client.bulkCancel(job.id);
console.log(`Refunded ${cancelled.credits_refunded} credits`);

Error handling

All non-2xx responses throw a ByeBouncerError (or subclass) with code, status, and detail.

import { ByeBouncer, InsufficientCreditsError, RateLimitError } from "@bye_bouncer/sdk";

try {
  await client.verify("[email protected]");
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    console.error(`Out of credits (${err.creditsRemaining ?? "?"} left)`);
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited, retry after ${err.retryAfterSeconds}s`);
  } else {
    throw err;
  }
}

API reference

The supported methods are listed below. Endpoints are relative to /api/v1; see the public API documentation for complete setup and REST examples.

| Method | Endpoint | Description | |--------|----------|-------------| | verify(email) | POST /verify | Verify a single email | | verifyIP(ip) | POST /verify-ip | Analyze a single IP | | verifyPhone(phone, options) | POST /verify-phone | Validate and enrich a phone number | | addPhoneBlacklist(options) | POST /phone/blacklist | Add a number to your blacklist | | removePhoneBlacklist(phone, country) | DELETE /phone/blacklist | Remove a number from your blacklist | | credits() | GET /credits | Get balance | | bulk(options) | POST /bulk | Enqueue a bulk job | | bulkStatus(id) | GET /bulk/{id} | Fetch job | | bulkCancel(id) | DELETE /bulk/{id} | Cancel | | bulkDownloadUrl(id) | GET /bulk/{id}/download | Signed CSV URL | | bulkSetWebhook(id, opts) | POST /bulk/{id}/webhook | Attach/rotate webhook | | bulkWaitForCompletion(id, opts) | polls bulkStatus | Convenience helper | | bulkAndWait(input, opts) | create+poll+download | Convenience helper |

The score-free data-validation methods (return validation-v1) let you pick one service at a time:

| Method | Endpoint | Credits | |--------|----------|---------| | validate(input) | POST /lead/verify | per channel; phone_mode: "local" \| "carrier" picks the phone service | | validateEmail(email) | POST /verify-email | 1 | | lookupIP(ip, options) | POST /verify-ip | 1 | | validatePhoneLocal(phone, options) | POST /verify-phone/local | 1 | | lookupPhoneCarrier(phone, options) | POST /verify-phone/carrier | 3 | | lookupPhoneNetwork(phone, options) | POST /verify-phone/live | 6 |

validatePhone(phone, options) keeps the legacy behavior: carrier when configured, otherwise local. Suggestions and domain lookups remain available through REST. bulkIP() and bulkPhone() are retired and fail locally; bulk supports email only.

Use a live server key for credits, bulk and blacklist operations. Public keys can verify email, IP and phone with an allowed Origin and an explicit allocation. credits is spendable key balance; wallet_balance, when present, is the shared account total. Buying credits does not automatically increase key allocations.

Options

new ByeBouncer({
  apiKey: "bb_live_...",             // required
  baseUrl: "https://api.byebouncer.com", // default
  timeoutMs: 30_000,                 // per-request timeout
  fetch: customFetch,                // optional custom transport
});

Production use

timeoutMs applies to each HTTP request until its complete response body has been read, including CSV downloads. Network timeouts propagate to the caller. Bulk helpers raise bulk_not_completed for failed, cancelled or expired jobs and for completed jobs without downloadable results. Prefer webhooks for large jobs.

Requests are not automatically retried: a timed-out verification may already have consumed credits. To retry bulk creation safely, reuse the same idempotency key with bulk(options, idempotencyKey).

bulkAndWait() does not accept an idempotency key. If creation needs safe retries, use bulk() with a unique key per logical import and preserve that key and its request body across retries, then poll and download separately.

Charges and limits

  • Email: 1 credit per verification, including cached answers.
  • IP: 1 credit per public, routable IP; invalid_scope results are free.
  • Phone: 1 credit for a valid local result or 3 for a billable enriched result. Inconclusive and blacklisted results are free; billable cached answers are charged.
  • HLR is an optional REST operation costing 6 additional credits per conclusive lookup.
  • Bulk: email only, up to 5,000 unique emails per job. Credits are reserved on creation. Cancellation refunds unprocessed items; failed jobs refund the full debit.

Support

Local IP checks (requires the updated server)

const result = await client.lookupIP('8.8.8.8', {
  checks: ['network_data', 'tor', 'geolocation', 'infrastructure', 'anonymization_catalog'],
});

Omit checks to retain the existing default. The selection above performs no DNS/rDNS/DNSBL calls during IP validation. Catalogs must be installed on the server; absent or expired evidence is unavailable. no_match does not prove the absence of a VPN or proxy. Public IP pricing is unchanged. Combined validation accepts ip_checks in client.validate(...).

  • Docs: https://byebouncer.com/docs
  • Email: [email protected]
  • Issues: https://github.com/fidelp27/byebouncer/issues

License

MIT © ByeBouncer