bavimail 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,879 @@
+interface HttpClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(options: HttpClientOptions);
+    private headers;
+    request<T>(method: string, path: string, options?: {
+        body?: Record<string, unknown>;
+        params?: Record<string, unknown>;
+    }): Promise<T>;
+    requestBytes(method: string, path: string, options?: {
+        params?: Record<string, unknown>;
+    }): Promise<ArrayBuffer>;
+    private buildUrl;
+}
+
+declare abstract class BaseResource {
+    protected readonly http: HttpClient;
+    constructor(http: HttpClient);
+}
+
+interface Alias {
+    id: string;
+    userId: string;
+    domainId: string;
+    alias: string;
+    fullEmail: string;
+    domainName: string;
+    signatureHtml: string | null;
+    signatureText: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface AliasCreateParams {
+    domainId: string;
+    alias: string;
+    signatureHtml?: string | null;
+}
+interface AliasUpdateParams {
+    alias: string;
+    signatureHtml?: string | null;
+}
+
+type DomainStatus = "pending" | "verifying" | "verified" | "failed";
+type EmailProviderKey = "AWS";
+type DNSRecordVerificationStatus = "verified" | "not_configured" | "incorrect_value" | "checking" | "error";
+type MailFromStatus = "not_started" | "pending" | "success" | "failed" | "temporary_failure";
+interface Domain {
+    id: string;
+    userId: string;
+    domain: string;
+    status: DomainStatus;
+    isActive: boolean;
+    providerKey: EmailProviderKey;
+    providerConfig: Record<string, unknown> | null;
+    sesVerificationToken: string | null;
+    sesDkimTokens: string[] | null;
+    sesMailFromDomain: string | null;
+    sesMailFromStatus: MailFromStatus | null;
+    sesMailFromError: string | null;
+    verifiedAt: string | null;
+    lastVerificationAttempt: string | null;
+    verificationError: string | null;
+    stripTrackingOnRead: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface DomainCreateParams {
+    domain: string;
+    providerKey: EmailProviderKey;
+    providerConfig?: Record<string, unknown> | null;
+}
+interface DomainUpdateParams {
+    isActive?: boolean | null;
+    providerConfig?: Record<string, unknown> | null;
+    stripTrackingOnRead?: boolean | null;
+}
+interface DNSRecord {
+    type: string;
+    name: string;
+    value: string;
+    priority: number | null;
+    ttl: number | null;
+    description: string | null;
+}
+interface DNSRecordWithStatus extends DNSRecord {
+    status: DNSRecordVerificationStatus;
+    actualValue: string | null;
+    errorMessage: string | null;
+    lastChecked: string;
+}
+interface DNSVerificationProgress {
+    totalRecords: number;
+    verified: number;
+    notConfigured: number;
+    incorrect: number;
+    errors: number;
+}
+interface MailFromStatusInfo {
+    mailFromDomain: string | null;
+    status: MailFromStatus;
+    error: string | null;
+    message: string;
+}
+interface DNSVerificationResponse {
+    domain: string;
+    overallProgress: DNSVerificationProgress;
+    records: DNSRecordWithStatus[];
+    mailFromStatus: MailFromStatusInfo | null;
+    lastChecked: string;
+}
+interface DomainSetup {
+    domain: string;
+    dnsRecords: DNSRecord[];
+    verificationInstructions: string;
+}
+
+type EmailStatus = "scheduled" | "queued" | "sending" | "sent" | "delivered" | "failed" | "bounced" | "complained" | "cancelled";
+type TagType = "tag" | "folder";
+type TaggedBy = "user" | "system" | "rule";
+type WebhookEventType = "email.inbound.received" | "email.outbound.sent" | "email.outbound.failed" | "email.outbound.opened" | "email.outbound.clicked" | "email.outbound.scheduled" | "email.outbound.cancelled" | "domain.verified" | "domain.failed" | "webhook.test";
+
+interface AttachmentMetadata {
+    filename: string;
+    sizeBytes: number;
+    mimeType: string;
+    contentId: string | null;
+}
+interface AttachmentCreateParams {
+    filename: string;
+    content: string;
+    mimeType?: string | null;
+    contentId?: string | null;
+}
+interface Email {
+    id: string;
+    userId: string;
+    aliasId: string;
+    domainId: string;
+    conversationId: string | null;
+    fromEmail: string;
+    toEmail: string;
+    subject: string;
+    bodyText: string;
+    bodyHtml: string | null;
+    inReplyTo: string | null;
+    references: string | null;
+    attachments: AttachmentMetadata[] | null;
+    attachmentCount: number;
+    providerMessageId: string;
+    providerMetadata: Record<string, unknown>;
+    status: EmailStatus;
+    sentAt: string | null;
+    deliveredAt: string | null;
+    errorMessage: string | null;
+    sendAt: string | null;
+    sendAtTimezone: string | null;
+    sendAtUtc: string | null;
+    cancelledAt: string | null;
+    trackingId: string | null;
+    trackOpens: boolean;
+    firstOpenedAt: string | null;
+    openCount: number;
+    trackClicks: boolean;
+    clickCount: number;
+    firstClickedAt: string | null;
+    lastClickedAt: string | null;
+    trackedLinksCount: number;
+    aliasName: string | null;
+    domainName: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface EmailSendParams {
+    aliasId: string;
+    toEmail: string;
+    subject: string;
+    body: string;
+    trackOpens?: boolean;
+    trackClicks?: boolean;
+    clickTrackingPatterns?: string[] | null;
+    conversationId?: string | null;
+    inReplyTo?: string | null;
+    sendAt?: string | null;
+    sendAtTimezone?: string | null;
+    attachments?: AttachmentCreateParams[] | null;
+}
+interface EmailClickListResponse {
+    clicks: EmailClick[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface EmailClick {
+    id: string;
+    linkId: string;
+    originalUrl: string;
+    position: number;
+    clickedAt: string;
+    userAgent: string | null;
+    ipAddress: string | null;
+    referer: string | null;
+    deviceType: string | null;
+    browserName: string | null;
+    osName: string | null;
+    isFirstClick: boolean;
+    isBot: boolean;
+    botReason: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface TrackedLink {
+    id: string;
+    linkId: string;
+    originalUrl: string;
+    position: number;
+    anchorText: string | null;
+    clickCount: number;
+    uniqueClickCount: number;
+    firstClickedAt: string | null;
+    lastClickedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface BatchEmailResponse {
+    total: number;
+    accepted: number;
+    rejected: number;
+    results: BatchEmailItemResult[];
+}
+interface BatchEmailItemResult {
+    index: number;
+    status: string;
+    email: Email | null;
+    error: BatchEmailItemError | null;
+}
+interface BatchEmailItemError {
+    message: string;
+    code: string | null;
+    category: string | null;
+}
+
+interface Tag {
+    id: string;
+    userId: string;
+    name: string;
+    description: string | null;
+    type: TagType;
+    color: string | null;
+    icon: string | null;
+    sortOrder: number;
+    isPinned: boolean;
+    isSystem: boolean;
+    emailCount: number;
+    isVisible: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface TagSummary {
+    id: string;
+    name: string;
+    type: TagType;
+    color: string | null;
+    icon: string | null;
+}
+interface TagCreateParams {
+    name: string;
+    description?: string | null;
+    type?: TagType;
+    color?: string | null;
+    icon?: string | null;
+    sortOrder?: number;
+    isPinned?: boolean;
+}
+interface TagUpdateParams {
+    name?: string | null;
+    description?: string | null;
+    type?: TagType | null;
+    color?: string | null;
+    icon?: string | null;
+    sortOrder?: number | null;
+    isPinned?: boolean | null;
+    isVisible?: boolean | null;
+}
+interface EmailTag {
+    tag: TagSummary;
+    taggedAt: string;
+    taggedBy: TaggedBy;
+    note: string | null;
+}
+
+interface Verdict {
+    status: string;
+    details: string | null;
+}
+interface InboundAttachmentMetadata {
+    filename: string | null;
+    sizeBytes: number;
+    mimeType: string;
+    contentId: string | null;
+    isInline: boolean;
+    storageUri: string | null;
+    storageScheme: string | null;
+}
+interface InboundEmailSummary {
+    id: string;
+    userId: string;
+    aliasId: string;
+    domainId: string;
+    conversationId: string | null;
+    fromEmail: string;
+    fromName: string | null;
+    subject: string;
+    providerReceivedAt: string;
+    processedAt: string | null;
+    processingError: string | null;
+    providerMessageId: string;
+    rawEmailUri: string;
+    providerMetadata: Record<string, unknown>;
+    aliasName: string;
+    domainName: string;
+    fullEmail: string;
+    attachmentCount: number;
+    hasHtml: boolean;
+    tags: TagSummary[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface InboundEmailDetail {
+    id: string;
+    userId: string;
+    aliasId: string;
+    domainId: string;
+    conversationId: string | null;
+    fromEmail: string;
+    fromName: string | null;
+    replyTo: string | null;
+    toEmail: string;
+    ccEmails: string[] | null;
+    bccEmails: string[] | null;
+    subject: string;
+    bodyText: string | null;
+    bodyHtml: string | null;
+    rawEmailSize: number | null;
+    headers: Record<string, string> | null;
+    messageId: string | null;
+    inReplyTo: string | null;
+    references: string[] | null;
+    attachments: InboundAttachmentMetadata[] | null;
+    providerMessageId: string;
+    providerReceivedAt: string;
+    spamVerdict: Verdict | null;
+    virusVerdict: Verdict | null;
+    spfVerdict: Verdict | null;
+    dkimVerdict: Verdict | null;
+    dmarcVerdict: Verdict | null;
+    processedAt: string | null;
+    processingError: string | null;
+    aliasName: string;
+    domainName: string;
+    fullEmail: string;
+    attachmentCount: number;
+    hasHtml: boolean;
+    rawEmailUri: string;
+    providerMetadata: Record<string, unknown>;
+    tags: TagSummary[];
+    createdAt: string;
+    updatedAt: string;
+}
+
+interface ConversationSummary {
+    id: string;
+    userId: string;
+    subject: string;
+    firstMessageAt: string;
+    lastMessageAt: string;
+    messageCount: number;
+    firstFromEmail: string | null;
+    firstToEmail: string | null;
+    totalAttachmentCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ConversationDetail {
+    id: string;
+    userId: string;
+    subject: string;
+    firstMessageAt: string;
+    lastMessageAt: string;
+    messageCount: number;
+    messages: ConversationMessage[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface ConversationMessage {
+    id: string;
+    direction: string;
+    fromEmail: string;
+    fromName: string | null;
+    toEmail: string;
+    subject: string;
+    timestamp: string;
+    bodyText: string | null;
+    bodyHtml: string | null;
+    attachmentCount: number;
+    messageId: string | null;
+}
+
+interface Webhook {
+    id: string;
+    url: string;
+    description: string | null;
+    eventTypes: string[];
+    isActive: boolean;
+    isVerified: boolean;
+    consecutiveFailures: number;
+    disabledAt: string | null;
+    integrationId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface WebhookCreated extends Webhook {
+    secret: string;
+}
+interface WebhookSecret {
+    secret: string;
+}
+interface WebhookCreateParams {
+    url: string;
+    eventTypes: WebhookEventType[];
+    description?: string | null;
+}
+interface WebhookUpdateParams {
+    url?: string | null;
+    eventTypes?: WebhookEventType[] | null;
+    description?: string | null;
+    isActive?: boolean | null;
+}
+
+interface IntegrationInfo {
+    id: string;
+    displayName: string;
+    authMode: string;
+}
+interface BootstrapApiKeyResponse {
+    apiKey: string;
+    created: boolean;
+    expiresAt: string | null;
+}
+interface RevokeApiKeyResponse {
+    revoked: boolean;
+}
+
+interface WebhookEvent<T = unknown> {
+    eventId: string;
+    eventType: WebhookEventType;
+    timestamp: string;
+    data: T;
+}
+interface InboundReceivedData {
+    emailId: string;
+    aliasId: string;
+    domainId: string;
+    fromEmail: string;
+    fromName: string | null;
+    toEmail: string;
+    subject: string | null;
+    bodyPreview: string | null;
+    receivedAt: string | null;
+    attachmentCount: number;
+    hasHtml: boolean;
+}
+interface OutboundSentData {
+    emailId: string;
+    fromEmail: string;
+    toEmail: string;
+    subject: string | null;
+    bodyPreview: string | null;
+    sentAt: string | null;
+    providerMessageId: string | null;
+}
+interface OutboundFailedData {
+    emailId: string;
+    fromEmail: string;
+    toEmail: string;
+    subject: string | null;
+    errorMessage: string | null;
+}
+interface OutboundOpenedData {
+    emailId: string;
+    fromEmail: string;
+    toEmail: string;
+    subject: string | null;
+    openedAt: string | null;
+    isFirstOpen: boolean;
+    isBot: boolean;
+    botReason: string | null;
+    openCount: number;
+}
+interface OutboundClickedData {
+    emailId: string;
+    fromEmail: string;
+    toEmail: string;
+    subject: string | null;
+    linkId: string;
+    originalUrl: string;
+    position: number | null;
+    anchorText: string | null;
+    clickedAt: string | null;
+    isFirstClick: boolean;
+    isBot: boolean;
+    botReason: string | null;
+    deviceType: string | null;
+    browserName: string | null;
+    osName: string | null;
+    linkClickCount: number;
+    linkUniqueClickCount: number;
+    emailClickCount: number;
+}
+interface OutboundScheduledData {
+    emailId: string;
+    fromEmail: string;
+    toEmail: string;
+    subject: string | null;
+    sendAt: string | null;
+    sendAtTimezone: string | null;
+    sendAtUtc: string | null;
+}
+interface OutboundCancelledData {
+    emailId: string;
+    fromEmail: string;
+    toEmail: string;
+    subject: string | null;
+    cancelledAt: string | null;
+}
+interface DomainVerifiedData {
+    domainId: string;
+    domain: string;
+    verifiedAt: string | null;
+}
+interface DomainFailedData {
+    domainId: string;
+    domain: string;
+    error: string | null;
+}
+interface WebhookTestData {
+    webhookId: string;
+    test: boolean;
+}
+interface EventDataMap {
+    "email.inbound.received": InboundReceivedData;
+    "email.outbound.sent": OutboundSentData;
+    "email.outbound.failed": OutboundFailedData;
+    "email.outbound.opened": OutboundOpenedData;
+    "email.outbound.clicked": OutboundClickedData;
+    "email.outbound.scheduled": OutboundScheduledData;
+    "email.outbound.cancelled": OutboundCancelledData;
+    "domain.verified": DomainVerifiedData;
+    "domain.failed": DomainFailedData;
+    "webhook.test": WebhookTestData;
+}
+
+declare class Domains extends BaseResource {
+    /** Register a new domain. */
+    create(params: DomainCreateParams): Promise<Domain>;
+    /** List all domains. */
+    list(): Promise<Domain[]>;
+    /** Get a domain by ID. */
+    get(domainId: string): Promise<Domain>;
+    /** Get DNS setup instructions for a domain. */
+    getSetup(domainId: string): Promise<DomainSetup>;
+    /** Get live DNS verification status. */
+    getDnsStatus(domainId: string, options?: {
+        forceRefresh?: boolean;
+    }): Promise<DNSVerificationResponse>;
+    /** Trigger domain verification. */
+    verify(domainId: string, options?: {
+        force?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /** Update domain settings. */
+    update(domainId: string, params: DomainUpdateParams): Promise<Domain>;
+    /** Delete a domain. */
+    delete(domainId: string): Promise<void>;
+}
+
+declare class Aliases extends BaseResource {
+    /** Create a new email alias. */
+    create(params: AliasCreateParams): Promise<Alias>;
+    /** List aliases, optionally filtered by domain. */
+    list(options?: {
+        domainId?: string;
+    }): Promise<Alias[]>;
+    /** Get an alias by ID. */
+    get(aliasId: string): Promise<Alias>;
+    /** Update an alias. */
+    update(aliasId: string, params: AliasUpdateParams): Promise<Alias>;
+    /** Delete an alias. */
+    delete(aliasId: string): Promise<void>;
+}
+
+declare class Emails extends BaseResource {
+    /** Send an email. */
+    send(params: EmailSendParams): Promise<Email>;
+    /** List sent emails with optional filters. */
+    list(options?: {
+        aliasId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<Email[]>;
+    /** Get a sent email by ID. */
+    get(emailId: string): Promise<Email>;
+    /** Send a batch of emails. */
+    batchSend(emails: EmailSendParams[]): Promise<BatchEmailResponse>;
+    /** Cancel a scheduled email. */
+    cancel(emailId: string): Promise<Email>;
+    /** List click events for an email. */
+    listClicks(emailId: string, options?: {
+        linkId?: string;
+        includeBots?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<EmailClickListResponse>;
+    /** List tracked links in an email. */
+    listLinks(emailId: string): Promise<TrackedLink[]>;
+}
+
+declare class InboundEmails extends BaseResource {
+    /** List inbound emails with optional filters. */
+    list(options?: {
+        aliasId?: string;
+        tagIds?: string[];
+        tagMatch?: "any" | "all";
+        limit?: number;
+        offset?: number;
+    }): Promise<InboundEmailSummary[]>;
+    /** Get full details of an inbound email. */
+    get(emailId: string): Promise<InboundEmailDetail>;
+    /** Download the raw RFC822 email. */
+    downloadRaw(emailId: string): Promise<ArrayBuffer>;
+    /** Download an attachment by zero-based index. */
+    downloadAttachment(emailId: string, index: number): Promise<ArrayBuffer>;
+    /** Delete an inbound email. */
+    delete(emailId: string): Promise<void>;
+    /** Add tags to an inbound email. */
+    addTags(emailId: string, tagIds: string[], note?: string | null): Promise<EmailTag[]>;
+    /** Get tags for an inbound email. */
+    getTags(emailId: string): Promise<EmailTag[]>;
+    /** Replace all tags on an inbound email. */
+    replaceTags(emailId: string, tagIds: string[], note?: string | null): Promise<EmailTag[]>;
+    /** Remove a single tag from an inbound email. */
+    removeTag(emailId: string, tagId: string): Promise<void>;
+}
+
+declare class Conversations extends BaseResource {
+    /** List conversation threads with optional filters. */
+    list(options?: {
+        aliasId?: string;
+        domainId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ConversationSummary[]>;
+    /** Get a conversation with all messages. */
+    get(conversationId: string): Promise<ConversationDetail>;
+}
+
+declare class Tags extends BaseResource {
+    /** Create a new tag. */
+    create(params: TagCreateParams): Promise<Tag>;
+    /** List tags. */
+    list(options?: {
+        includeHidden?: boolean;
+    }): Promise<Tag[]>;
+    /** Get a tag by ID. */
+    get(tagId: string): Promise<Tag>;
+    /** Update a tag. */
+    update(tagId: string, params: TagUpdateParams): Promise<Tag>;
+    /** Delete a tag. */
+    delete(tagId: string): Promise<void>;
+}
+
+declare class Webhooks extends BaseResource {
+    /** Create a new webhook subscription. Returns secret (shown once). */
+    create(params: WebhookCreateParams): Promise<WebhookCreated>;
+    /** List all webhooks. */
+    list(): Promise<Webhook[]>;
+    /** Get a webhook by ID. */
+    get(webhookId: string): Promise<Webhook>;
+    /** Update a webhook. */
+    update(webhookId: string, params: WebhookUpdateParams): Promise<Webhook>;
+    /** Delete a webhook. */
+    delete(webhookId: string): Promise<void>;
+    /** Verify a webhook URL with the verification code. */
+    verify(webhookId: string, verificationCode: string): Promise<Webhook>;
+    /** Resend the verification code for a webhook. */
+    resendVerification(webhookId: string): Promise<Webhook>;
+    /** Send a test event to the webhook. */
+    test(webhookId: string): Promise<Record<string, unknown>>;
+    /** Rotate the webhook's HMAC signing secret. */
+    rotateSecret(webhookId: string): Promise<WebhookSecret>;
+}
+
+/** Handler for a specific webhook event. */
+type EventHandler<T = unknown> = (event: WebhookEvent<T>) => void | Promise<void>;
+/** Error callback invoked when a handler throws. */
+type ErrorHandler = (error: unknown, event: WebhookEvent) => void | Promise<void>;
+/** Internal handler map: event type string → array of handler functions. */
+type HandlerMap = Map<string, EventHandler<any>[]>;
+/**
+ * Web Standard webhook request handler.
+ *
+ * Accepts a `Request` and returns a `Response`, making it compatible with
+ * Next.js App Router, Hono, Bun, Deno, Cloudflare Workers, and any other
+ * runtime that implements the Web Standard `Request`/`Response` API.
+ */
+declare class WebhookRequestHandler {
+    private readonly handlers;
+    private readonly secret;
+    private readonly path;
+    private readonly onError?;
+    constructor(options: {
+        handlers: HandlerMap;
+        secret: string;
+        path?: string;
+        onError?: ErrorHandler;
+    });
+    /** Handle an incoming Web Standard Request. */
+    fetch(request: Request): Promise<Response>;
+}
+
+interface ListenOptions {
+    /** Public URL where Bavimail will send webhooks (triggers auto-create). */
+    webhookUrl?: string;
+    /** Pre-existing webhook HMAC secret (skip auto-create). */
+    secret?: string;
+    /** Port to listen on (default: 8000). */
+    port?: number;
+    /** Host to bind to (default: "0.0.0.0"). */
+    host?: string;
+    /** URL path for the webhook endpoint (default: "/webhooks"). */
+    path?: string;
+    /** Delete the auto-created webhook on shutdown (default: true). */
+    cleanup?: boolean;
+    /** AbortSignal for programmatic shutdown. */
+    signal?: AbortSignal;
+    /** Error handler for individual handler failures. */
+    onError?: ErrorHandler;
+    /** Description for the auto-created webhook. */
+    description?: string;
+}
+
+interface BavimailOptions {
+    /** Your Bavimail API key. */
+    apiKey: string;
+    /** Override the base API URL (default: https://api.bavimail.com). */
+    baseUrl?: string;
+}
+declare class Bavimail {
+    private readonly http;
+    private readonly _handlers;
+    /** Domain management (register, verify, DNS status). */
+    readonly domains: Domains;
+    /** Email alias management. */
+    readonly aliases: Aliases;
+    /** Outbound email sending and tracking. */
+    readonly emails: Emails;
+    /** Inbound email retrieval and tagging. */
+    readonly inboundEmails: InboundEmails;
+    /** Conversation thread management. */
+    readonly conversations: Conversations;
+    /** Tag management for organizing emails. */
+    readonly tags: Tags;
+    /** Webhook subscription management. */
+    readonly webhooks: Webhooks;
+    constructor(options: BavimailOptions);
+    /** Register a handler for a single event type. */
+    on<E extends WebhookEventType>(eventType: E, handler: EventHandler<EventDataMap[E]>): void;
+    /** Register a handler for multiple event types. */
+    on<E extends WebhookEventType>(eventType: E[], handler: EventHandler<EventDataMap[E]>): void;
+    /**
+     * Start a standalone HTTP server that receives and dispatches webhook events.
+     *
+     * If `webhookUrl` is provided, a webhook is auto-created via the API and
+     * cleaned up on shutdown. If `secret` is provided instead, the server uses
+     * the pre-existing webhook secret directly.
+     */
+    listen(options: ListenOptions): Promise<void>;
+    /**
+     * Create a Web Standard webhook request handler for framework integration.
+     *
+     * The returned handler's `.fetch(request)` method accepts a `Request` and
+     * returns a `Response`, compatible with Next.js App Router, Hono, Bun, Deno,
+     * Cloudflare Workers, and similar runtimes.
+     */
+    createHandler(options: {
+        secret: string;
+        path?: string;
+        onError?: ErrorHandler;
+    }): WebhookRequestHandler;
+}
+
+declare class BavimailError extends Error {
+    constructor(message: string);
+}
+declare class APIError extends BavimailError {
+    readonly statusCode: number;
+    readonly code: string | null;
+    readonly category: string | null;
+    readonly context: Record<string, unknown> | null;
+    readonly requestId: string | null;
+    constructor(message: string, statusCode: number, code?: string | null, category?: string | null, context?: Record<string, unknown> | null, requestId?: string | null);
+}
+declare class NotFoundError extends APIError {
+    constructor(message: string, code?: string | null, category?: string | null, context?: Record<string, unknown> | null, requestId?: string | null);
+}
+declare class ValidationError extends APIError {
+    constructor(message: string, code?: string | null, category?: string | null, context?: Record<string, unknown> | null, requestId?: string | null);
+}
+declare class ConflictError extends APIError {
+    constructor(message: string, code?: string | null, category?: string | null, context?: Record<string, unknown> | null, requestId?: string | null);
+}
+declare class AuthenticationError extends APIError {
+    constructor(message: string, code?: string | null, category?: string | null, context?: Record<string, unknown> | null, requestId?: string | null);
+}
+declare class ForbiddenError extends APIError {
+    constructor(message: string, code?: string | null, category?: string | null, context?: Record<string, unknown> | null, requestId?: string | null);
+}
+declare class RateLimitError extends APIError {
+    constructor(message: string, code?: string | null, category?: string | null, context?: Record<string, unknown> | null, requestId?: string | null);
+}
+declare class InternalServerError extends APIError {
+    constructor(message: string, code?: string | null, category?: string | null, context?: Record<string, unknown> | null, requestId?: string | null);
+}
+declare class ProviderError extends APIError {
+    constructor(message: string, statusCode?: number, code?: string | null, category?: string | null, context?: Record<string, unknown> | null, requestId?: string | null);
+}
+declare class WebhookVerificationError extends BavimailError {
+    constructor(message: string);
+}
+
+/**
+ * Async generator that auto-paginates through list endpoints.
+ *
+ * Usage:
+ * ```ts
+ * for await (const email of iterPages(
+ *   (opts) => client.emails.list(opts),
+ *   { pageSize: 50 }
+ * )) {
+ *   console.log(email.subject);
+ * }
+ * ```
+ */
+declare function iterPages<T>(method: (params: {
+    limit?: number;
+    offset?: number;
+}) => Promise<T[]>, options?: {
+    pageSize?: number;
+    params?: Record<string, unknown>;
+}): AsyncGenerator<T, void, undefined>;
+
+/**
+ * Verify an incoming webhook signature and parse the event.
+ *
+ * Uses the Web Crypto API (available in browsers and Node.js 18+).
+ *
+ * @param payload - Raw request body string
+ * @param signature - Value of the `x-webhook-signature` header
+ * @param timestamp - Value of the `x-webhook-timestamp` header
+ * @param secret - Your webhook HMAC signing secret
+ * @param toleranceSeconds - Max age of the timestamp in seconds (default: 300 = 5 min)
+ */
+declare function verifyWebhookSignature<E extends WebhookEventType = WebhookEventType>(payload: string, signature: string, timestamp: string, secret: string, toleranceSeconds?: number): Promise<WebhookEvent<E extends keyof EventDataMap ? EventDataMap[E] : unknown>>;
+
+declare const VERSION = "0.1.0";
+
+export { APIError, type Alias, type AliasCreateParams, type AliasUpdateParams, type AttachmentCreateParams, type AttachmentMetadata, AuthenticationError, type BatchEmailItemError, type BatchEmailItemResult, type BatchEmailResponse, Bavimail, BavimailError, type BavimailOptions, type BootstrapApiKeyResponse, ConflictError, type ConversationDetail, type ConversationMessage, type ConversationSummary, type DNSRecord, type DNSRecordVerificationStatus, type DNSRecordWithStatus, type DNSVerificationProgress, type DNSVerificationResponse, type Domain, type DomainCreateParams, type DomainFailedData, type DomainSetup, type DomainStatus, type DomainUpdateParams, type DomainVerifiedData, type Email, type EmailClick, type EmailClickListResponse, type EmailProviderKey, type EmailSendParams, type EmailStatus, type EmailTag, type ErrorHandler, type EventDataMap, type EventHandler, ForbiddenError, type InboundAttachmentMetadata, type InboundEmailDetail, type InboundEmailSummary, type InboundReceivedData, type IntegrationInfo, InternalServerError, type ListenOptions, type MailFromStatus, type MailFromStatusInfo, NotFoundError, type OutboundCancelledData, type OutboundClickedData, type OutboundFailedData, type OutboundOpenedData, type OutboundScheduledData, type OutboundSentData, ProviderError, RateLimitError, type RevokeApiKeyResponse, type Tag, type TagCreateParams, type TagSummary, type TagType, type TagUpdateParams, type TaggedBy, type TrackedLink, VERSION, ValidationError, type Verdict, type Webhook, type WebhookCreateParams, type WebhookCreated, type WebhookEvent, type WebhookEventType, WebhookRequestHandler, type WebhookSecret, type WebhookTestData, type WebhookUpdateParams, WebhookVerificationError, iterPages, verifyWebhookSignature };