email-domain-classifier

TypeScript client and shared wire protocol for the email-domain-classifier service, which classifies an email domain as free, disposable, or unknown.

Install

bun add email-domain-classifier effect

effect is an optional peer — required by the root, ./promises, and ./effect entry points. ./protocol is dependency-free.

Usage

The namespace is EmailDomains and the operation is classify, so a call site reads as EmailDomains.classify(...).

category is free | disposable | business | unknown. This service never emits business — it is reserved for the consumer's own downstream classifier — so unknown means "not in either list", not "business".

Promises

import { createClient, EmailDomains } from "email-domain-classifier/promises";

// Zero-config, against the hosted service.
const result = await EmailDomains.classify("[email protected]");
result.category; // "free" | "disposable" | "unknown"

// Configured client.
const classifier = createClient({ timeoutMs: 1500 });
const results = await classifier.classifyMany(["[email protected]", "[email protected]"]);

classify accepts a bare domain, an email, or a URL. classifyMany chunks at the contract limit and preserves order. Failures reject with the shared errors:

import { HttpError, NotSeededError } from "email-domain-classifier/promises";

Effect

import { Effect } from "effect";
import { EmailDomains } from "email-domain-classifier/effect";

const program = Effect.gen(function* () {
  const domains = yield* EmailDomains.Service;
  return yield* domains.classify("[email protected]");
});

program.pipe(Effect.provide(EmailDomains.layerFetch({})));

EmailDomains.layer requires an HttpClient; EmailDomains.layerFetch provides the Fetch transport. Errors are Schema.TaggedErrors, so recover with Effect.catchTag:

yield* EmailDomains.classify(email).pipe(
  Effect.catchTag("EmailDomains.NotSeededError", () => fallThroughToContextDev),
);

The service does not impose a timeout or status retry policy; compose Effect.timeout and retry in the caller. Transport failures are retried transiently at the boundary.

Protocol

email-domain-classifier/protocol exports the shared wire types and constants with no runtime dependencies:

import { MAX_BATCH_SIZE, type Classification } from "email-domain-classifier/protocol";

Errors

| Error | Meaning | | --- | --- | | EmailDomains.NetworkError | Transport failure (connection, DNS, TLS, abort) | | EmailDomains.TimeoutError | A caller-composed timeout elapsed | | EmailDomains.HttpError | Non-2xx status other than 503 (carries status) | | EmailDomains.NotSeededError | 503 — the service is up but its lists are not seeded | | EmailDomains.DecodeError | A 2xx body did not match the contract |

License

MIT