verifymailapi 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,327 @@
+interface ClientOptions {
+    apiKey: string;
+    /** Defaults to https://api.verifymailapi.com */
+    baseUrl?: string;
+    /** Max retry attempts on retryable failures (429, 5xx). Default 2 (so up to 3 total tries). */
+    retries?: number;
+    /** Per-request timeout in ms. Default 30000. */
+    timeoutMs?: number;
+    /** Override fetch — useful for tests or non-Node runtimes. */
+    fetch?: typeof fetch;
+    /** Default risk profile sent as X-Risk-Profile on every call (overridable per request). */
+    riskProfile?: "strict" | "balanced" | "permissive";
+}
+
+/**
+ * Response types — mirror the backend Pydantic models in app/models/check.py.
+ * Kept hand-written rather than codegen so the surface stays small and readable.
+ */
+type Recommendation = "allow" | "allow_with_flag" | "block";
+type RiskLevel = "low" | "medium" | "high" | "critical";
+type ConfidenceLevel = "low" | "medium" | "high";
+type RiskProfile = "strict" | "balanced" | "permissive";
+type ModelPhase = "bootstrap" | "calibrated" | "optimised";
+type SignalDirection = "risk" | "trust";
+interface Meta {
+    request_id: string;
+    email: string;
+    domain: string;
+    checked_at: string;
+    latency_ms: number;
+    api_version: string;
+    model_phase: ModelPhase;
+    model_version: string;
+    path_taken: string;
+    cached: boolean;
+    cache_age_seconds: number | null;
+}
+interface Verdict {
+    recommendation: Recommendation;
+    risk_level: RiskLevel;
+    disposable: boolean;
+    catch_all: boolean | null;
+    catch_all_checked: boolean;
+    valid_address: boolean;
+    safe_to_send: boolean;
+    summary: string;
+    degraded_mode?: boolean;
+    degraded_reason?: string | null;
+}
+interface ScoreComponents {
+    strong_signals: number;
+    corroborating: number;
+    trust_adjustments: number;
+    compounding_bonus: number;
+    final_clamped: number;
+}
+interface Thresholds {
+    block_at: number;
+    flag_at: number;
+    your_profile: RiskProfile;
+}
+interface CatchAllDetail {
+    detected: boolean;
+    probability: number;
+    confidence: number;
+    legitimate_use_likely: boolean;
+    type: "confirmed" | "suspected" | "cleared";
+}
+interface Score {
+    value: number;
+    confidence: number;
+    confidence_level: ConfidenceLevel;
+    components: ScoreComponents;
+    thresholds: Thresholds;
+    catch_all_detail: CatchAllDetail | null;
+}
+interface Signal {
+    name: string;
+    category: string;
+    direction: SignalDirection;
+    weight: number;
+    description: string;
+    value?: unknown;
+    unit?: string | null;
+    probe_result?: Record<string, unknown> | null;
+    extra?: Record<string, unknown>;
+}
+interface Compounding {
+    applied: boolean;
+    signal_count: number;
+    bonus_applied: number;
+    explanation: string;
+}
+interface Signals {
+    fired: Signal[];
+    trust_signals: Signal[];
+    suppressed?: {
+        name: string;
+        reason: string;
+    }[];
+    compounding: Compounding;
+}
+interface CheckStep {
+    name: string;
+    status: string;
+    duration_ms: number;
+    result: string | null;
+    probe_detail?: Record<string, unknown> | null;
+}
+interface ChecksBlock {
+    run: CheckStep[];
+    skipped?: CheckStep[];
+    failed?: CheckStep[];
+    path_explanation: string;
+}
+/** Full /v1/check response (5-block schema). */
+interface CheckResponse {
+    meta: Meta;
+    verdict: Verdict;
+    score: Score;
+    signals: Signals;
+    checks: ChecksBlock;
+}
+interface BulkSummary {
+    total: number;
+    credits_charged: number;
+    credits_remaining: number;
+    elapsed_ms: number;
+}
+interface BulkCheckResponse {
+    items: CheckResponse[];
+    summary: BulkSummary;
+}
+/** One line from /v1/check/bulk/stream. */
+type BulkStreamEvent = {
+    index: number;
+    result: CheckResponse;
+} | {
+    event: "summary";
+    total: number;
+    credits_charged: number;
+    credits_remaining: number;
+    elapsed_ms: number;
+};
+interface AsyncCheckResponse {
+    request_id: string;
+    status: "pending";
+    preliminary: CheckResponse;
+    webhook_url: string;
+    estimated_completion_ms: number;
+}
+interface ReportRequest {
+    domain: string;
+    outcome: "confirmed_throwaway" | "confirmed_legitimate" | "suspected_throwaway";
+    notes?: string;
+}
+interface ReportResponse {
+    accepted: boolean;
+    queued_for_review: boolean;
+    review_sla_hours: number;
+    report_id: string;
+    message: string;
+}
+interface UsageMeResponse {
+    total_checks: number;
+    checks_this_period: number;
+    period_start: string;
+    blocks: number;
+    allow_with_flag: number;
+    allows: number;
+    avg_latency_ms: number;
+    cache_hit_rate: number;
+    credit_balance_checks: number;
+}
+interface StatusResponse {
+    status: "ok" | "degraded";
+    components: {
+        redis: "ok" | "degraded";
+        postgres: "ok" | "degraded";
+        dns: "ok" | "degraded";
+    };
+    latency_ms: number;
+}
+/** Async webhook event posted to the customer's webhook_url. */
+interface CheckCompletedEvent {
+    request_id: string;
+    event: "check.completed";
+    result: CheckResponse;
+}
+
+/**
+ * Error class hierarchy. All HTTP errors from the API are translated into one
+ * of these — customers can `instanceof` them to branch cleanly:
+ *
+ *   try { await vm.check(email) }
+ *   catch (e) {
+ *     if (e instanceof QuotaExceededError) return showBilling();
+ *     if (e instanceof RateLimitError)     return retryLater(e.retryAfter);
+ *     if (e instanceof VerifyMailError)    return logAndShowGeneric(e);
+ *     throw e;
+ *   }
+ */
+interface ErrorBody {
+    code: string;
+    http_status: number;
+    message: string;
+    request_id?: string;
+    docs_url?: string;
+    limit?: number;
+    reset_at?: string;
+    upgrade_url?: string;
+}
+declare class VerifyMailError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly requestId: string | undefined;
+    readonly docsUrl: string | undefined;
+    readonly body: ErrorBody | undefined;
+    constructor(message: string, opts?: {
+        code?: string;
+        status?: number;
+        requestId?: string;
+        docsUrl?: string;
+        body?: ErrorBody;
+    });
+}
+declare class InvalidApiKeyError extends VerifyMailError {
+    constructor(opts: NonNullable<ConstructorParameters<typeof VerifyMailError>[1]>);
+}
+declare class QuotaExceededError extends VerifyMailError {
+    readonly upgradeUrl: string | undefined;
+    constructor(opts: NonNullable<ConstructorParameters<typeof VerifyMailError>[1]>);
+}
+declare class RateLimitError extends VerifyMailError {
+    readonly retryAfter: number;
+    readonly limit: number | undefined;
+    readonly resetAt: string | undefined;
+    constructor(opts: NonNullable<ConstructorParameters<typeof VerifyMailError>[1]> & {
+        retryAfter: number;
+    });
+}
+declare class IdempotencyConflictError extends VerifyMailError {
+    constructor(opts: NonNullable<ConstructorParameters<typeof VerifyMailError>[1]>);
+}
+declare class ValidationError extends VerifyMailError {
+    constructor(message: string, opts: NonNullable<ConstructorParameters<typeof VerifyMailError>[1]>);
+}
+declare class ServiceDegradedError extends VerifyMailError {
+    constructor(opts: NonNullable<ConstructorParameters<typeof VerifyMailError>[1]>);
+}
+/**
+ * Map an HTTP response to the right error class. The backend's error envelope
+ * is `{ error: { code, http_status, message, ... } }`.
+ */
+declare function errorFromResponse(status: number, body: {
+    error?: ErrorBody;
+} | unknown, retryAfterHeader?: string | null): VerifyMailError;
+
+/**
+ * Verify an incoming webhook signature from a `/v1/check/async` completion.
+ *
+ *   const ok = verifyWebhook(rawBody, req.header("X-VerifyMail-Signature"), secret);
+ *   if (!ok) return res.status(401).end();
+ *
+ * Pass the *raw* request body bytes — not the parsed JSON. In Express:
+ *   app.post("/webhook", express.raw({ type: "application/json" }), handler)
+ */
+declare function verifyWebhook(rawBody: Buffer | Uint8Array | string, signatureHeader: string | null | undefined, secret: string): boolean;
+
+/**
+ * Official SDK for the VerifyMail API.
+ *
+ *   import { VerifyMail } from "verifymailapi";
+ *   const vm = new VerifyMail({ apiKey: process.env.VERIFYMAIL_KEY! });
+ *   const r = await vm.check("user@example.com");
+ *   if (r.verdict.recommendation === "block") { ... }
+ *
+ * Docs: https://verifymailapi.com/docs
+ */
+
+interface CheckOptions {
+    /** Override the SDK-wide risk profile for this call. */
+    riskProfile?: "strict" | "balanced" | "permissive";
+    /** Make the call idempotent. Pass `true` to auto-generate a UUID, or a fixed string. */
+    idempotencyKey?: string | boolean;
+}
+interface AsyncCheckArgs {
+    email: string;
+    webhookUrl: string;
+    /** Optional HMAC-SHA256 key used to sign the final webhook payload. */
+    webhookSecret?: string;
+}
+declare class VerifyMail {
+    private readonly http;
+    constructor(opts: ClientOptions);
+    /** Check a single email. Charges 1 credit. */
+    check(email: string, opts?: CheckOptions): Promise<CheckResponse>;
+    /** Check a domain only (no local part). Charges 1 credit. */
+    checkDomain(domain: string, opts?: CheckOptions): Promise<CheckResponse>;
+    /** Bulk check 1–100 emails. Charges N credits up front (all-or-nothing). */
+    checkBulk(emails: string[], opts?: CheckOptions): Promise<BulkCheckResponse>;
+    /**
+     * Stream bulk-check results as each row completes. Calls `onEvent` once
+     * per result (in finish-order) plus once with a final `{event: "summary"}`.
+     *
+     *   await vm.checkBulkStream(emails, (e) => {
+     *     if ("event" in e) console.log("done", e);
+     *     else processRow(e.index, e.result);
+     *   });
+     */
+    checkBulkStream(emails: string[], onEvent: (e: BulkStreamEvent) => void | Promise<void>, opts?: Omit<CheckOptions, "idempotencyKey">): Promise<void>;
+    /**
+     * Async deep check. Returns 202 immediately with a preliminary verdict;
+     * VerifyMail POSTs the final result to your webhook URL once the deep
+     * SMTP probe completes. Verify the signature with `verifyWebhook()` in
+     * your handler before trusting the payload.
+     */
+    checkAsync(args: AsyncCheckArgs, opts?: CheckOptions): Promise<AsyncCheckResponse>;
+    /** File a /v1/report for a domain outcome (feedback loop). */
+    report(req: ReportRequest): Promise<ReportResponse>;
+    /** Programmatic equivalent of the dashboard's Usage summary. */
+    usage(): Promise<UsageMeResponse>;
+    /** Component health (Redis / Postgres / DNS). Always returns 200. */
+    status(): Promise<StatusResponse>;
+}
+
+export { type AsyncCheckArgs, type AsyncCheckResponse, type BulkCheckResponse, type BulkStreamEvent, type BulkSummary, type CatchAllDetail, type CheckCompletedEvent, type CheckOptions, type CheckResponse, type CheckStep, type ChecksBlock, type Compounding, type ConfidenceLevel, type ErrorBody, IdempotencyConflictError, InvalidApiKeyError, type Meta, type ModelPhase, QuotaExceededError, RateLimitError, type Recommendation, type ReportRequest, type ReportResponse, type RiskLevel, type RiskProfile, type Score, type ScoreComponents, ServiceDegradedError, type Signal, type SignalDirection, type Signals, type StatusResponse, type Thresholds, type UsageMeResponse, ValidationError, type Verdict, VerifyMail, VerifyMailError, VerifyMail as default, errorFromResponse, verifyWebhook };

package/dist/index.d.ts

@@ -0,0 +1,327 @@
+interface ClientOptions {
+    apiKey: string;
+    /** Defaults to https://api.verifymailapi.com */
+    baseUrl?: string;
+    /** Max retry attempts on retryable failures (429, 5xx). Default 2 (so up to 3 total tries). */
+    retries?: number;
+    /** Per-request timeout in ms. Default 30000. */
+    timeoutMs?: number;
+    /** Override fetch — useful for tests or non-Node runtimes. */
+    fetch?: typeof fetch;
+    /** Default risk profile sent as X-Risk-Profile on every call (overridable per request). */
+    riskProfile?: "strict" | "balanced" | "permissive";
+}
+
+/**
+ * Response types — mirror the backend Pydantic models in app/models/check.py.
+ * Kept hand-written rather than codegen so the surface stays small and readable.
+ */
+type Recommendation = "allow" | "allow_with_flag" | "block";
+type RiskLevel = "low" | "medium" | "high" | "critical";
+type ConfidenceLevel = "low" | "medium" | "high";
+type RiskProfile = "strict" | "balanced" | "permissive";
+type ModelPhase = "bootstrap" | "calibrated" | "optimised";
+type SignalDirection = "risk" | "trust";
+interface Meta {
+    request_id: string;
+    email: string;
+    domain: string;
+    checked_at: string;
+    latency_ms: number;
+    api_version: string;
+    model_phase: ModelPhase;
+    model_version: string;
+    path_taken: string;
+    cached: boolean;
+    cache_age_seconds: number | null;
+}
+interface Verdict {
+    recommendation: Recommendation;
+    risk_level: RiskLevel;
+    disposable: boolean;
+    catch_all: boolean | null;
+    catch_all_checked: boolean;
+    valid_address: boolean;
+    safe_to_send: boolean;
+    summary: string;
+    degraded_mode?: boolean;
+    degraded_reason?: string | null;
+}
+interface ScoreComponents {
+    strong_signals: number;
+    corroborating: number;
+    trust_adjustments: number;
+    compounding_bonus: number;
+    final_clamped: number;
+}
+interface Thresholds {
+    block_at: number;
+    flag_at: number;
+    your_profile: RiskProfile;
+}
+interface CatchAllDetail {
+    detected: boolean;
+    probability: number;
+    confidence: number;
+    legitimate_use_likely: boolean;
+    type: "confirmed" | "suspected" | "cleared";
+}
+interface Score {
+    value: number;
+    confidence: number;
+    confidence_level: ConfidenceLevel;
+    components: ScoreComponents;
+    thresholds: Thresholds;
+    catch_all_detail: CatchAllDetail | null;
+}
+interface Signal {
+    name: string;
+    category: string;
+    direction: SignalDirection;
+    weight: number;
+    description: string;
+    value?: unknown;
+    unit?: string | null;
+    probe_result?: Record<string, unknown> | null;
+    extra?: Record<string, unknown>;
+}
+interface Compounding {
+    applied: boolean;
+    signal_count: number;
+    bonus_applied: number;
+    explanation: string;
+}
+interface Signals {
+    fired: Signal[];
+    trust_signals: Signal[];
+    suppressed?: {
+        name: string;
+        reason: string;
+    }[];
+    compounding: Compounding;
+}
+interface CheckStep {
+    name: string;
+    status: string;
+    duration_ms: number;
+    result: string | null;
+    probe_detail?: Record<string, unknown> | null;
+}
+interface ChecksBlock {
+    run: CheckStep[];
+    skipped?: CheckStep[];
+    failed?: CheckStep[];
+    path_explanation: string;
+}
+/** Full /v1/check response (5-block schema). */
+interface CheckResponse {
+    meta: Meta;
+    verdict: Verdict;
+    score: Score;
+    signals: Signals;
+    checks: ChecksBlock;
+}
+interface BulkSummary {
+    total: number;
+    credits_charged: number;
+    credits_remaining: number;
+    elapsed_ms: number;
+}
+interface BulkCheckResponse {
+    items: CheckResponse[];
+    summary: BulkSummary;
+}
+/** One line from /v1/check/bulk/stream. */
+type BulkStreamEvent = {
+    index: number;
+    result: CheckResponse;
+} | {
+    event: "summary";
+    total: number;
+    credits_charged: number;
+    credits_remaining: number;
+    elapsed_ms: number;
+};
+interface AsyncCheckResponse {
+    request_id: string;
+    status: "pending";
+    preliminary: CheckResponse;
+    webhook_url: string;
+    estimated_completion_ms: number;
+}
+interface ReportRequest {
+    domain: string;
+    outcome: "confirmed_throwaway" | "confirmed_legitimate" | "suspected_throwaway";
+    notes?: string;
+}
+interface ReportResponse {
+    accepted: boolean;
+    queued_for_review: boolean;
+    review_sla_hours: number;
+    report_id: string;
+    message: string;
+}
+interface UsageMeResponse {
+    total_checks: number;
+    checks_this_period: number;
+    period_start: string;
+    blocks: number;
+    allow_with_flag: number;
+    allows: number;
+    avg_latency_ms: number;
+    cache_hit_rate: number;
+    credit_balance_checks: number;
+}
+interface StatusResponse {
+    status: "ok" | "degraded";
+    components: {
+        redis: "ok" | "degraded";
+        postgres: "ok" | "degraded";
+        dns: "ok" | "degraded";
+    };
+    latency_ms: number;
+}
+/** Async webhook event posted to the customer's webhook_url. */
+interface CheckCompletedEvent {
+    request_id: string;
+    event: "check.completed";
+    result: CheckResponse;
+}
+
+/**
+ * Error class hierarchy. All HTTP errors from the API are translated into one
+ * of these — customers can `instanceof` them to branch cleanly:
+ *
+ *   try { await vm.check(email) }
+ *   catch (e) {
+ *     if (e instanceof QuotaExceededError) return showBilling();
+ *     if (e instanceof RateLimitError)     return retryLater(e.retryAfter);
+ *     if (e instanceof VerifyMailError)    return logAndShowGeneric(e);
+ *     throw e;
+ *   }
+ */
+interface ErrorBody {
+    code: string;
+    http_status: number;
+    message: string;
+    request_id?: string;
+    docs_url?: string;
+    limit?: number;
+    reset_at?: string;
+    upgrade_url?: string;
+}
+declare class VerifyMailError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly requestId: string | undefined;
+    readonly docsUrl: string | undefined;
+    readonly body: ErrorBody | undefined;
+    constructor(message: string, opts?: {
+        code?: string;
+        status?: number;
+        requestId?: string;
+        docsUrl?: string;
+        body?: ErrorBody;
+    });
+}
+declare class InvalidApiKeyError extends VerifyMailError {
+    constructor(opts: NonNullable<ConstructorParameters<typeof VerifyMailError>[1]>);
+}
+declare class QuotaExceededError extends VerifyMailError {
+    readonly upgradeUrl: string | undefined;
+    constructor(opts: NonNullable<ConstructorParameters<typeof VerifyMailError>[1]>);
+}
+declare class RateLimitError extends VerifyMailError {
+    readonly retryAfter: number;
+    readonly limit: number | undefined;
+    readonly resetAt: string | undefined;
+    constructor(opts: NonNullable<ConstructorParameters<typeof VerifyMailError>[1]> & {
+        retryAfter: number;
+    });
+}
+declare class IdempotencyConflictError extends VerifyMailError {
+    constructor(opts: NonNullable<ConstructorParameters<typeof VerifyMailError>[1]>);
+}
+declare class ValidationError extends VerifyMailError {
+    constructor(message: string, opts: NonNullable<ConstructorParameters<typeof VerifyMailError>[1]>);
+}
+declare class ServiceDegradedError extends VerifyMailError {
+    constructor(opts: NonNullable<ConstructorParameters<typeof VerifyMailError>[1]>);
+}
+/**
+ * Map an HTTP response to the right error class. The backend's error envelope
+ * is `{ error: { code, http_status, message, ... } }`.
+ */
+declare function errorFromResponse(status: number, body: {
+    error?: ErrorBody;
+} | unknown, retryAfterHeader?: string | null): VerifyMailError;
+
+/**
+ * Verify an incoming webhook signature from a `/v1/check/async` completion.
+ *
+ *   const ok = verifyWebhook(rawBody, req.header("X-VerifyMail-Signature"), secret);
+ *   if (!ok) return res.status(401).end();
+ *
+ * Pass the *raw* request body bytes — not the parsed JSON. In Express:
+ *   app.post("/webhook", express.raw({ type: "application/json" }), handler)
+ */
+declare function verifyWebhook(rawBody: Buffer | Uint8Array | string, signatureHeader: string | null | undefined, secret: string): boolean;
+
+/**
+ * Official SDK for the VerifyMail API.
+ *
+ *   import { VerifyMail } from "verifymailapi";
+ *   const vm = new VerifyMail({ apiKey: process.env.VERIFYMAIL_KEY! });
+ *   const r = await vm.check("user@example.com");
+ *   if (r.verdict.recommendation === "block") { ... }
+ *
+ * Docs: https://verifymailapi.com/docs
+ */
+
+interface CheckOptions {
+    /** Override the SDK-wide risk profile for this call. */
+    riskProfile?: "strict" | "balanced" | "permissive";
+    /** Make the call idempotent. Pass `true` to auto-generate a UUID, or a fixed string. */
+    idempotencyKey?: string | boolean;
+}
+interface AsyncCheckArgs {
+    email: string;
+    webhookUrl: string;
+    /** Optional HMAC-SHA256 key used to sign the final webhook payload. */
+    webhookSecret?: string;
+}
+declare class VerifyMail {
+    private readonly http;
+    constructor(opts: ClientOptions);
+    /** Check a single email. Charges 1 credit. */
+    check(email: string, opts?: CheckOptions): Promise<CheckResponse>;
+    /** Check a domain only (no local part). Charges 1 credit. */
+    checkDomain(domain: string, opts?: CheckOptions): Promise<CheckResponse>;
+    /** Bulk check 1–100 emails. Charges N credits up front (all-or-nothing). */
+    checkBulk(emails: string[], opts?: CheckOptions): Promise<BulkCheckResponse>;
+    /**
+     * Stream bulk-check results as each row completes. Calls `onEvent` once
+     * per result (in finish-order) plus once with a final `{event: "summary"}`.
+     *
+     *   await vm.checkBulkStream(emails, (e) => {
+     *     if ("event" in e) console.log("done", e);
+     *     else processRow(e.index, e.result);
+     *   });
+     */
+    checkBulkStream(emails: string[], onEvent: (e: BulkStreamEvent) => void | Promise<void>, opts?: Omit<CheckOptions, "idempotencyKey">): Promise<void>;
+    /**
+     * Async deep check. Returns 202 immediately with a preliminary verdict;
+     * VerifyMail POSTs the final result to your webhook URL once the deep
+     * SMTP probe completes. Verify the signature with `verifyWebhook()` in
+     * your handler before trusting the payload.
+     */
+    checkAsync(args: AsyncCheckArgs, opts?: CheckOptions): Promise<AsyncCheckResponse>;
+    /** File a /v1/report for a domain outcome (feedback loop). */
+    report(req: ReportRequest): Promise<ReportResponse>;
+    /** Programmatic equivalent of the dashboard's Usage summary. */
+    usage(): Promise<UsageMeResponse>;
+    /** Component health (Redis / Postgres / DNS). Always returns 200. */
+    status(): Promise<StatusResponse>;
+}
+
+export { type AsyncCheckArgs, type AsyncCheckResponse, type BulkCheckResponse, type BulkStreamEvent, type BulkSummary, type CatchAllDetail, type CheckCompletedEvent, type CheckOptions, type CheckResponse, type CheckStep, type ChecksBlock, type Compounding, type ConfidenceLevel, type ErrorBody, IdempotencyConflictError, InvalidApiKeyError, type Meta, type ModelPhase, QuotaExceededError, RateLimitError, type Recommendation, type ReportRequest, type ReportResponse, type RiskLevel, type RiskProfile, type Score, type ScoreComponents, ServiceDegradedError, type Signal, type SignalDirection, type Signals, type StatusResponse, type Thresholds, type UsageMeResponse, ValidationError, type Verdict, VerifyMail, VerifyMailError, VerifyMail as default, errorFromResponse, verifyWebhook };