@apiddress/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 APIddress
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# apiddress
+
+Official Node.js SDK for the [APIddress](https://api.apiddress.com) email validation API.
+
+- Zero runtime dependencies (built on global `fetch`)
+- Node 18+, ESM, full TypeScript types
+- Automatic retry with backoff on `429` and `5xx` (batch creation is never retried)
+
+## Install
+
+```bash
+npm install @apiddress/sdk
+```
+
+## Quickstart
+
+```js
+import { APIddress } from "@apiddress/sdk";
+
+const client = new APIddress("YOUR_API_KEY");
+
+const result = await client.validateEmail("ada@stripe.com");
+console.log(result.status); // "valid"
+console.log(result.score);  // 0.98
+```
+
+## Configuration
+
+```js
+const client = new APIddress("YOUR_API_KEY", {
+  baseUrl: "https://api.apiddress.com", // default
+  timeoutMs: 10_000,                    // per-request timeout, default 10s
+  maxRetries: 2,                        // retries on 429/5xx, default 2
+});
+```
+
+## Usage
+
+### Validate one email
+
+```js
+const result = await client.validateEmail("john@company.com", {
+  check_smtp: false,       // default
+  allow_role_based: true,  // default
+});
+// result.status: "valid" | "invalid" | "risky" | "disposable" | "unknown"
+// result.suggestion: "john@gmail.com" for typo-like addresses, else null
+// result.checks: { syntax, domain_exists, mx, smtp, disposable, ... }
+```
+
+A malformed value (e.g. `"not-an-email"`) is a verdict, not an error: you get
+`status: "invalid"` with `reason: "invalid_syntax"`.
+
+### Validate up to 100 emails synchronously
+
+```js
+const { count, results } = await client.validateEmails([
+  "a@example.com",
+  "b@example.com",
+]);
+```
+
+### Batch jobs (up to 5000 emails)
+
+```js
+const batch = await client.createBatch(emails, {
+  callback_url: "https://yourapp.com/webhooks/apiddress", // optional
+});
+
+const done = await client.waitForBatch(batch.batch_id, {
+  pollMs: 1_000,     // default
+  timeoutMs: 60_000, // default
+});
+console.log(done.status, done.results.length);
+
+// Or poll yourself:
+const status = await client.getBatch(batch.batch_id);
+```
+
+`waitForBatch` resolves with the terminal state (`"completed"` or `"failed"`) —
+check `status` before using `results`.
+
+### Account
+
+```js
+const profile = await client.me();        // plan, limits, usage
+const usage = await client.usage();       // current month
+const may = await client.usage("2026-05"); // specific month
+const health = await client.health();     // no auth required
+```
+
+## Error handling
+
+Every failed request throws an `APIddressError`:
+
+```js
+import { APIddress, APIddressError } from "@apiddress/sdk";
+
+try {
+  await client.validateEmail("john@company.com");
+} catch (err) {
+  if (err instanceof APIddressError) {
+    console.error(err.status, err.code, err.message, err.details);
+    // 429 quota_exceeded "Monthly request limit exceeded." { requests_used: ..., requests_limit: ... }
+  }
+}
+```
+
+| `status` | `code` |
+| -------- | ------------------ |
+| 400 | `invalid_request` |
+| 401 | `unauthorized` |
+| 404 | `not_found` |
+| 429 | `quota_exceeded` |
+| 500 | `internal_error` |
+| 0 | `timeout` (request or `waitForBatch` timeout) |
+
+## Development
+
+```bash
+npm install
+npm run build   # tsc -> dist/ (ESM + .d.ts)
+
+# Integration tests need a live backend:
+APIDDRESS_BASE_URL=http://localhost:3000 APIDDRESS_API_KEY=test_key_local_dev npm test
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+import type { ApiKeyProfileResponse, BatchAcceptedResponse, BatchStatusResponse, BulkValidateResponse, CreateBatchOptions, HealthResponse, UsageResponse, ValidateEmailOptions, ValidateEmailResponse, ValidateEmailsOptions, WaitForBatchOptions } from "./types.js";
+/** Client configuration. */
+export interface APIddressOptions {
+    /** API origin. Default: "https://api.apiddress.com". */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default: 10000. */
+    timeoutMs?: number;
+    /** Retries on 429 and 5xx responses. Default: 2. Batch creation is never retried. */
+    maxRetries?: number;
+}
+/**
+ * Official APIddress client.
+ *
+ * ```js
+ * import { APIddress } from "@apiddress/sdk";
+ *
+ * const client = new APIddress("YOUR_API_KEY");
+ * const result = await client.validateEmail("ada@stripe.com");
+ * console.log(result.status); // "valid"
+ * ```
+ */
+export declare class APIddress {
+    #private;
+    constructor(apiKey: string, options?: APIddressOptions);
+    /** Validate a single email address. Costs 1 request. */
+    validateEmail(email: string, options?: ValidateEmailOptions): Promise<ValidateEmailResponse>;
+    /** Validate 1-100 email addresses synchronously. Costs one request per email. */
+    validateEmails(emails: string[], options?: ValidateEmailsOptions): Promise<BulkValidateResponse>;
+    /**
+     * Create an asynchronous batch job for 1-5000 email addresses.
+     * Never retried automatically (to avoid duplicate jobs).
+     */
+    createBatch(emails: string[], options?: CreateBatchOptions): Promise<BatchAcceptedResponse>;
+    /** Get the current state (and results, when completed) of a batch job. */
+    getBatch(batchId: string): Promise<BatchStatusResponse>;
+    /**
+     * Poll a batch job until it reaches a terminal state ("completed" or "failed")
+     * and return that final state. Throws an `APIddressError` with `code: "timeout"`
+     * if the job is still running after `timeoutMs`.
+     */
+    waitForBatch(batchId: string, options?: WaitForBatchOptions): Promise<BatchStatusResponse>;
+    /** Get the profile (plan, limits, usage) of the authenticated API key. */
+    me(): Promise<ApiKeyProfileResponse>;
+    /** Get usage for a month ("YYYY-MM"). Defaults to the current month. */
+    usage(month?: string): Promise<UsageResponse>;
+    /** Service health check. Does not require authentication. */
+    health(): Promise<HealthResponse>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,4BAA4B;AAC5B,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAkBD;;;;;;;;;;GAUG;AACH,qBAAa,SAAS;;gBAMR,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB;IAU1D,wDAAwD;IACxD,aAAa,CACX,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,qBAAqB,CAAC;IAQjC,iFAAiF;IACjF,cAAc,CACZ,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,oBAAoB,CAAC;IAQhC;;;OAGG;IACH,WAAW,CACT,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,qBAAqB,CAAC;IAajC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAOvD;;;;OAIG;IACG,YAAY,CAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,mBAAmB,CAAC;IAqB/B,0EAA0E;IAC1E,EAAE,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAIpC,wEAAwE;IACxE,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAQ7C,6DAA6D;IAC7D,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;CA8ClC"}

package/dist/client.js

@@ -0,0 +1,172 @@
+import { APIddressError } from "./error.js";
+const DEFAULT_BASE_URL = "https://api.apiddress.com";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_RETRIES = 2;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Official APIddress client.
+ *
+ * ```js
+ * import { APIddress } from "@apiddress/sdk";
+ *
+ * const client = new APIddress("YOUR_API_KEY");
+ * const result = await client.validateEmail("ada@stripe.com");
+ * console.log(result.status); // "valid"
+ * ```
+ */
+export class APIddress {
+    #apiKey;
+    #baseUrl;
+    #timeoutMs;
+    #maxRetries;
+    constructor(apiKey, options = {}) {
+        if (!apiKey || typeof apiKey !== "string") {
+            throw new TypeError("APIddress: an API key string is required");
+        }
+        this.#apiKey = apiKey;
+        this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.#maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    }
+    /** Validate a single email address. Costs 1 request. */
+    validateEmail(email, options = {}) {
+        return this.#request({
+            method: "POST",
+            path: "/api/v1/validate-email",
+            body: { email, check_smtp: options.check_smtp ?? false, ...optional("allow_role_based", options.allow_role_based) },
+        });
+    }
+    /** Validate 1-100 email addresses synchronously. Costs one request per email. */
+    validateEmails(emails, options = {}) {
+        return this.#request({
+            method: "POST",
+            path: "/api/v1/validate-emails",
+            body: { emails, check_smtp: options.check_smtp ?? false },
+        });
+    }
+    /**
+     * Create an asynchronous batch job for 1-5000 email addresses.
+     * Never retried automatically (to avoid duplicate jobs).
+     */
+    createBatch(emails, options = {}) {
+        return this.#request({
+            method: "POST",
+            path: "/api/v1/batches",
+            body: {
+                emails,
+                check_smtp: options.check_smtp ?? false,
+                ...optional("callback_url", options.callback_url),
+            },
+            retryable: false,
+        });
+    }
+    /** Get the current state (and results, when completed) of a batch job. */
+    getBatch(batchId) {
+        return this.#request({
+            method: "GET",
+            path: `/api/v1/batches/${encodeURIComponent(batchId)}`,
+        });
+    }
+    /**
+     * Poll a batch job until it reaches a terminal state ("completed" or "failed")
+     * and return that final state. Throws an `APIddressError` with `code: "timeout"`
+     * if the job is still running after `timeoutMs`.
+     */
+    async waitForBatch(batchId, options = {}) {
+        const pollMs = options.pollMs ?? 1_000;
+        const timeoutMs = options.timeoutMs ?? 60_000;
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const batch = await this.getBatch(batchId);
+            if (batch.status === "completed" || batch.status === "failed") {
+                return batch;
+            }
+            if (Date.now() + pollMs > deadline) {
+                throw new APIddressError(0, "timeout", `Batch ${batchId} did not complete within ${timeoutMs}ms (last status: ${batch.status})`);
+            }
+            await sleep(pollMs);
+        }
+    }
+    /** Get the profile (plan, limits, usage) of the authenticated API key. */
+    me() {
+        return this.#request({ method: "GET", path: "/api/v1/me" });
+    }
+    /** Get usage for a month ("YYYY-MM"). Defaults to the current month. */
+    usage(month) {
+        return this.#request({
+            method: "GET",
+            path: "/api/v1/usage",
+            query: { month },
+        });
+    }
+    /** Service health check. Does not require authentication. */
+    health() {
+        return this.#request({ method: "GET", path: "/api/v1/health", auth: false });
+    }
+    async #request(options) {
+        const { method, path, body, query, auth = true, retryable = true } = options;
+        const url = new URL(this.#baseUrl + path);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(key, value);
+        }
+        const headers = { accept: "application/json" };
+        if (auth)
+            headers["x-api-key"] = this.#apiKey;
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        const maxAttempts = retryable ? this.#maxRetries + 1 : 1;
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                const init = {
+                    method,
+                    headers,
+                    signal: AbortSignal.timeout(this.#timeoutMs),
+                };
+                if (body !== undefined)
+                    init.body = JSON.stringify(body);
+                response = await fetch(url, init);
+            }
+            catch (cause) {
+                if (cause instanceof Error && (cause.name === "TimeoutError" || cause.name === "AbortError")) {
+                    throw new APIddressError(0, "timeout", `Request to ${path} timed out after ${this.#timeoutMs}ms`);
+                }
+                throw cause;
+            }
+            if (response.ok) {
+                return (await response.json());
+            }
+            const error = await parseErrorEnvelope(response);
+            const shouldRetry = attempt + 1 < maxAttempts && (response.status === 429 || response.status >= 500);
+            if (!shouldRetry)
+                throw error;
+            await sleep(backoffMs(attempt));
+        }
+    }
+}
+function optional(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+/** Exponential backoff with a little jitter: ~250ms, ~500ms, ~1s, capped at 4s. */
+function backoffMs(attempt) {
+    return Math.min(250 * 2 ** attempt, 4_000) + Math.floor(Math.random() * 100);
+}
+async function parseErrorEnvelope(response) {
+    let code = "unknown_error";
+    let message = `HTTP ${response.status}`;
+    let details = null;
+    try {
+        const payload = (await response.json());
+        if (payload?.error) {
+            code = payload.error.code ?? code;
+            message = payload.error.message ?? message;
+            details = payload.error.details ?? null;
+        }
+    }
+    catch {
+        // Non-JSON error body; keep defaults.
+    }
+    return new APIddressError(response.status, code, message, details);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/error.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Error thrown for any failed APIddress request.
+ *
+ * - For HTTP errors, `status` is the response status code and `code`/`message`/
+ *   `details` come from the API error envelope `{error: {code, message, details}}`.
+ * - For client-side failures (request timeout, batch polling timeout), `status`
+ *   is 0 and `code` is `"timeout"`.
+ */
+export declare class APIddressError extends Error {
+    /** HTTP status code, or 0 for client-side failures. */
+    readonly status: number;
+    /** Machine-readable error code, e.g. "unauthorized", "quota_exceeded". */
+    readonly code: string;
+    /** Extra context from the API, or null. */
+    readonly details: Record<string, unknown> | null;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown> | null);
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;gBAG/C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAW;CAQjD"}

package/dist/error.js

@@ -0,0 +1,24 @@
+/**
+ * Error thrown for any failed APIddress request.
+ *
+ * - For HTTP errors, `status` is the response status code and `code`/`message`/
+ *   `details` come from the API error envelope `{error: {code, message, details}}`.
+ * - For client-side failures (request timeout, batch polling timeout), `status`
+ *   is 0 and `code` is `"timeout"`.
+ */
+export class APIddressError extends Error {
+    /** HTTP status code, or 0 for client-side failures. */
+    status;
+    /** Machine-readable error code, e.g. "unauthorized", "quota_exceeded". */
+    code;
+    /** Extra context from the API, or null. */
+    details;
+    constructor(status, code, message, details = null) {
+        super(message);
+        this.name = "APIddressError";
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,uDAAuD;IAC9C,MAAM,CAAS;IACxB,0EAA0E;IACjE,IAAI,CAAS;IACtB,2CAA2C;IAClC,OAAO,CAAiC;IAEjD,YACE,MAAc,EACd,IAAY,EACZ,OAAe,EACf,UAA0C,IAAI;QAE9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { APIddress } from "./client.js";
+export type { APIddressOptions } from "./client.js";
+export { APIddressError } from "./error.js";
+export type { ApiKeyProfileResponse, BatchAcceptedResponse, BatchStatus, BatchStatusResponse, BulkValidateResponse, CreateBatchOptions, EmailStatus, ErrorResponse, HealthResponse, Plan, SpamTrapRisk, UsageResponse, ValidateEmailOptions, ValidateEmailResponse, ValidateEmailsOptions, ValidationChecks, WaitForBatchOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EACV,qBAAqB,EACrB,qBAAqB,EACrB,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,cAAc,EACd,IAAI,EACJ,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { APIddress } from "./client.js";
+export { APIddressError } from "./error.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Request and response types for the APIddress API.
+ *
+ * Hand-mapped 1:1 from the OpenAPI 3.1 contract (`backend/openapi.yaml`).
+ * Field names match the wire format exactly.
+ */
+/** Verdict for a validated email address. */
+export type EmailStatus = "valid" | "invalid" | "risky" | "disposable" | "unknown";
+/** Lifecycle state of an asynchronous batch job. */
+export type BatchStatus = "pending" | "processing" | "completed" | "failed";
+/** Plan associated with an API key. */
+export type Plan = "free" | "paid" | "enterprise";
+/** Spam-trap risk level, or null when not assessed. */
+export type SpamTrapRisk = "low" | "medium" | "high" | null;
+/** Options for `validateEmail`. Field names match the API request body. */
+export interface ValidateEmailOptions {
+    /** Attempt an SMTP-level deliverability probe. Default: false. */
+    check_smtp?: boolean;
+    /** Treat role-based addresses (support@, info@, ...) as acceptable. Default: true. */
+    allow_role_based?: boolean;
+}
+/** Options for `validateEmails`. */
+export interface ValidateEmailsOptions {
+    /** Attempt an SMTP-level deliverability probe. Default: false. */
+    check_smtp?: boolean;
+}
+/** Options for `createBatch`. */
+export interface CreateBatchOptions {
+    /** Webhook URL invoked when the batch completes. */
+    callback_url?: string | null;
+    /** Attempt an SMTP-level deliverability probe. Default: false. */
+    check_smtp?: boolean;
+}
+/** Options for `waitForBatch`. */
+export interface WaitForBatchOptions {
+    /** Delay between polls, in milliseconds. Default: 1000. */
+    pollMs?: number;
+    /** Give up after this many milliseconds. Default: 60000. */
+    timeoutMs?: number;
+}
+/** Individual checks performed on an email address. */
+export interface ValidationChecks {
+    syntax: boolean;
+    domain_exists: boolean;
+    mx: boolean;
+    /** null when the SMTP probe was skipped or inconclusive. */
+    smtp: boolean | null;
+    disposable: boolean;
+    role_based: boolean;
+    free_provider: boolean;
+    /** null when not determined. */
+    catch_all: boolean | null;
+    typo: boolean;
+    spam_trap_risk: SpamTrapRisk;
+}
+/** Result of validating a single email address. */
+export interface ValidateEmailResponse {
+    email: string;
+    normalized_email: string;
+    status: EmailStatus;
+    valid: boolean;
+    /** Confidence score between 0 and 1. */
+    score: number;
+    /** Machine-readable reason, e.g. "accepted_email", "invalid_syntax". */
+    reason: string;
+    /** Suggested correction for typo-like addresses, or null. */
+    suggestion: string | null;
+    checks: ValidationChecks;
+    provider: string | null;
+    created_at: string;
+}
+/** Result of a synchronous bulk validation. */
+export interface BulkValidateResponse {
+    count: number;
+    results: ValidateEmailResponse[];
+}
+/** Returned when an asynchronous batch job is accepted (HTTP 202). */
+export interface BatchAcceptedResponse {
+    batch_id: string;
+    status: "pending";
+    submitted_count: number;
+    created_at: string;
+}
+/** Current state of an asynchronous batch job. */
+export interface BatchStatusResponse {
+    batch_id: string;
+    status: BatchStatus;
+    submitted_count: number;
+    processed_count: number;
+    created_at: string;
+    completed_at: string | null;
+    /** Per-email results once the batch is completed, otherwise null. */
+    results: ValidateEmailResponse[] | null;
+}
+/** Profile of the authenticated API key. */
+export interface ApiKeyProfileResponse {
+    id: string;
+    email: string;
+    plan: Plan;
+    is_active: boolean;
+    requests_limit: number;
+    requests_used: number;
+    created_at: string;
+}
+/** Monthly usage for the authenticated API key. */
+export interface UsageResponse {
+    /** Month in YYYY-MM format. */
+    month: string;
+    requests_used: number;
+    requests_limit: number;
+    remaining: number;
+}
+/** Service health payload. */
+export interface HealthResponse {
+    status: "ok";
+    timestamp: string;
+    version: string;
+}
+/** Error envelope returned by the API on 4xx/5xx. */
+export interface ErrorResponse {
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown> | null;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Request and response types for the APIddress API.
+ *
+ * Hand-mapped 1:1 from the OpenAPI 3.1 contract (`backend/openapi.yaml`).
+ * Field names match the wire format exactly.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@apiddress/sdk",
+  "version": "0.1.0",
+  "description": "Official Node.js SDK for the APIddress email validation API",
+  "keywords": ["email", "validation", "email-verification", "apiddress"],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": { "access": "public" },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  }
+}