@messagebird/sdk 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,1692 @@
+/** Transport metadata exposed to callers via `.withResponse()`. */
+interface BirdResponse {
+    status: number;
+    headers: Headers;
+    /** Correlation ID — the `X-Request-Id` header. */
+    requestId: string;
+}
+/** Per-request lifecycle inputs, supplied by the resource method. */
+interface RequestLifecycleOptions {
+    /** HTTP method — decides idempotency-key generation and retry safety. */
+    method: string;
+    /** Caller-supplied idempotency key; auto-generated for mutations if absent. */
+    idempotencyKey?: string;
+    /** Caller cancellation. */
+    signal?: AbortSignal;
+    /** Per-attempt timeout (ms). Overrides the client default. */
+    timeout?: number;
+    /** Max retry attempts. Overrides the client default. */
+    maxRetries?: number;
+}
+/** The shape a generated hey-api SDK call resolves to. */
+interface FetchOutcome<T> {
+    data?: T;
+    error?: unknown;
+    /** Present whenever the HTTP round-trip completed; absent only on a rejected call. */
+    response?: Response;
+}
+/** Context handed to the call thunk on each attempt. */
+interface AttemptContext {
+    signal: AbortSignal;
+    idempotencyKey?: string;
+}
+interface CoreDefaults {
+    /** Per-attempt timeout (ms). */
+    timeout: number;
+    /** Max retry attempts. */
+    maxRetries: number;
+}
+declare class BirdHTTPClient {
+    private readonly defaults;
+    constructor(defaults: CoreDefaults);
+    /**
+     * Run a generated hey-api SDK call through the request lifecycle.
+     *
+     * @param call  Invokes the SDK function; receives the per-attempt signal and
+     *              the idempotency key to set as a header.
+     * @returns the parsed body plus transport metadata.
+     * @throws  a `BirdError` subclass on terminal failure; the native
+     *          `AbortError` if the caller's signal aborts.
+     */
+    request<T>(call: (ctx: AttemptContext) => Promise<FetchOutcome<T>>, options: RequestLifecycleOptions): Promise<{
+        data: T;
+        response: BirdResponse;
+    }>;
+}
+
+/** Root of the hierarchy. Catch this to catch anything the SDK throws. */
+declare class BirdError extends Error {
+    constructor(message: string);
+}
+/** Network-level failure with no HTTP response (DNS, refused, socket hangup). */
+declare class BirdConnectionError extends BirdError {
+    constructor(message: string);
+}
+/** A single attempt exceeded its timeout. Retryable. */
+declare class BirdTimeoutError extends BirdError {
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number);
+}
+/** A webhook payload failed signature verification (bad signature, stale timestamp, malformed headers). */
+declare class BirdWebhookVerificationError extends BirdError {
+    constructor(message: string);
+}
+/** One per-field validation failure (the `details` array on a 422). */
+interface ErrorDetail {
+    /** Dotted field path, e.g. `to[0].email`, `subject`, `.`. */
+    param: string;
+    /** What is wrong with this field. */
+    message: string;
+}
+/** Constructor fields shared by every API error, mapped from the wire body. */
+interface BirdAPIErrorFields {
+    statusCode: number;
+    /** Opaque, stable error code (`E#####`). */
+    code: string;
+    /** Coarse category — the value callers branch on. */
+    type: string;
+    /** Human-readable slug for logs. Paired with `code`, never replaces it. */
+    errorName: string;
+    message: string;
+    /** Stable link to the docs page for this code. */
+    docUrl: string;
+    /** Correlation ID — also the `X-Request-Id` response header. */
+    requestId: string;
+    /** Offending field, when applicable. */
+    param?: string;
+    /** Verbatim code from a downstream system (SMTP reply, payment decline). */
+    vendorCode?: string;
+}
+/** The server returned an error body. Base for every `type`-specific class. */
+declare class BirdAPIError extends BirdError {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly type: string;
+    readonly errorName: string;
+    readonly docUrl: string;
+    readonly requestId: string;
+    readonly param?: string;
+    readonly vendorCode?: string;
+    constructor(fields: BirdAPIErrorFields);
+}
+/** 401 — authentication failed or missing. */
+declare class BirdAuthError extends BirdAPIError {
+    constructor(fields: BirdAPIErrorFields);
+}
+/** 403 — authenticated but not allowed. */
+declare class BirdPermissionError extends BirdAPIError {
+    constructor(fields: BirdAPIErrorFields);
+}
+/** 404 — resource does not exist. */
+declare class BirdNotFoundError extends BirdAPIError {
+    constructor(fields: BirdAPIErrorFields);
+}
+/** 409 — semantic conflict (e.g. a unique value already taken). */
+declare class BirdConflictError extends BirdAPIError {
+    constructor(fields: BirdAPIErrorFields);
+}
+/** 400 — malformed request. */
+declare class BirdBadRequestError extends BirdAPIError {
+    constructor(fields: BirdAPIErrorFields);
+}
+/** 402 — billing/balance problem. */
+declare class BirdBillingError extends BirdAPIError {
+    constructor(fields: BirdAPIErrorFields);
+}
+/** 412/428 — a precondition was not met. */
+declare class BirdPreconditionError extends BirdAPIError {
+    constructor(fields: BirdAPIErrorFields);
+}
+/** 413 — request body too large. */
+declare class BirdPayloadTooLargeError extends BirdAPIError {
+    constructor(fields: BirdAPIErrorFields);
+}
+/** 500 — unexpected server error. */
+declare class BirdInternalError extends BirdAPIError {
+    constructor(fields: BirdAPIErrorFields);
+}
+/** 501 — endpoint not implemented. */
+declare class BirdNotImplementedError extends BirdAPIError {
+    constructor(fields: BirdAPIErrorFields);
+}
+/** 421 — request reached the wrong region (ADR-0036). */
+declare class BirdMisdirectedError extends BirdAPIError {
+    constructor(fields: BirdAPIErrorFields);
+}
+/** 503 — service temporarily unavailable. */
+declare class BirdServiceUnavailableError extends BirdAPIError {
+    constructor(fields: BirdAPIErrorFields);
+}
+/** 422 — field validation failed; `details` carries the per-field errors. */
+declare class BirdValidationError extends BirdAPIError {
+    readonly details: ErrorDetail[];
+    constructor(fields: BirdAPIErrorFields & {
+        details: ErrorDetail[];
+    });
+}
+/** 429 — rate limited; `retryAfter` is the server-advised wait in seconds. */
+declare class BirdRateLimitError extends BirdAPIError {
+    readonly retryAfter?: number;
+    constructor(fields: BirdAPIErrorFields & {
+        retryAfter?: number;
+    });
+}
+
+/** Per-request overrides accepted by every resource method. */
+interface RequestOptions$1 {
+    /** Idempotency key; auto-generated for mutations if omitted, reused on retry. */
+    idempotencyKey?: string;
+    /** Caller cancellation. Rejects with the native `AbortError`. */
+    signal?: AbortSignal;
+    /** Per-attempt timeout (ms). Overrides the client default. */
+    timeout?: number;
+    /** Max retry attempts. Overrides the client default. */
+    maxRetries?: number;
+    /** Extra headers for this request. SDK-internal headers win on conflict. */
+    headers?: Record<string, string>;
+}
+/**
+ * The result of `.safe()` — the value or the error, never thrown. On success
+ * `data` and the `response` envelope are present and `error` is `null`. On
+ * failure `error` is a `BirdError` you can `instanceof`-narrow, and `data`/
+ * `response` are `null` — the metadata you need (status, request id) is on the
+ * error itself. A caller-initiated abort is not a Bird failure and still throws
+ * (the native `AbortError`, ADR-0042 §1).
+ */
+type SafeResult<T> = {
+    data: T;
+    error: null;
+    response: BirdResponse;
+} | {
+    data: null;
+    error: BirdError;
+    response: null;
+};
+/** Single-result return: `await` for the value, `.withResponse()` for metadata. */
+interface APIPromise<T> extends Promise<T> {
+    withResponse(): Promise<{
+        data: T;
+        response: BirdResponse;
+    }>;
+    /** Resolve to `{ data, error }` instead of throwing. */
+    safe(): Promise<SafeResult<T>>;
+}
+/** One cursor-paginated page — the wire envelope shape (snake), verbatim. */
+interface CursorPage<T> {
+    data: T[];
+    /** Pass back as `starting_after` to advance. Null at the end. */
+    next_cursor: string | null;
+    /** Pass back as `ending_before` to step back. Null at the start. */
+    prev_cursor: string | null;
+    /** Refresh anchor; pass as `ending_before` later for items since this page. */
+    refresh_cursor: string | null;
+    /** Total across all pages — only when `include_total=true` was passed. */
+    total?: number | null;
+}
+/**
+ * List return (R1): `await` resolves the first page; `for await` walks every
+ * item across all pages, fetching subsequent pages lazily.
+ */
+interface PaginatedPromise<T> extends Promise<CursorPage<T>>, AsyncIterable<T> {
+    withResponse(): Promise<{
+        data: CursorPage<T>;
+        response: BirdResponse;
+    }>;
+    /** Resolve the first page as `{ data, error }` instead of throwing. */
+    safe(): Promise<SafeResult<CursorPage<T>>>;
+}
+
+/**
+ * An email address was added to the workspace's suppression list (manually, via complaint, or via hard bounce). Payload schema not yet finalized.
+ */
+type EventEmailSuppressionCreated = {
+    /**
+     * Event type.
+     */
+    type: "email_suppression.created";
+    /**
+     * When the event occurred.
+     */
+    timestamp: string;
+    /**
+     * Event payload. The fields for this event are not yet finalized.
+     */
+    data: {
+        [key: string]: never;
+    };
+};
+/**
+ * Payload of the email.unsubscribed event.
+ */
+type EventEmailUnsubscribedData = EventEmailBase;
+/**
+ * Structured key/value tag attached to an email send. Surfaces in list filters, the event log, and webhook payloads. Use tags for low-cardinality filtering dimensions (category, experiment ID, template ID). For arbitrary per-send context that does not need to be filterable, use `metadata`.
+ * Tag count and per-tag size are capped to keep per-send tag payloads small — see EmailMessageSendRequest for the array maximum.
+ *
+ */
+type EmailTag = {
+    /**
+     * Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
+     *
+     */
+    name: string;
+    /**
+     * Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
+     *
+     */
+    value: string;
+};
+/**
+ * Envelope position of a recipient on an outbound email event.
+ */
+type RecipientRole = "to" | "cc" | "bcc";
+type WorkspaceId = string;
+type RecipientId = string;
+type EmailId = string;
+/**
+ * Identity fields shared by every email lifecycle event payload.
+ */
+type EventEmailBase = {
+    /**
+     * ID of the email send.
+     */
+    email_id: EmailId;
+    /**
+     * ID of the recipient.
+     */
+    recipient_id: RecipientId;
+    /**
+     * ID of the workspace.
+     */
+    workspace_id: WorkspaceId;
+    /**
+     * Recipient address as it appeared on the envelope.
+     */
+    recipient: string;
+    /**
+     * Envelope position of the recipient.
+     */
+    recipient_role: RecipientRole;
+    /**
+     * Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
+     *
+     */
+    tags: Array<EmailTag> | null;
+    /**
+     * The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
+     *
+     */
+    metadata: {
+        [key: string]: unknown;
+    } | null;
+};
+/**
+ * Recipient unsubscribed by clicking a tracked unsubscribe link in the email. Fires once per recipient.
+ */
+type EventEmailUnsubscribed = {
+    /**
+     * Event type.
+     */
+    type: "email.unsubscribed";
+    /**
+     * Time the unsubscribe was recorded.
+     */
+    timestamp: string;
+    data: EventEmailUnsubscribedData;
+};
+/**
+ * Why an email was rejected before delivery.
+ * `recipient_suppressed` means the recipient is on the workspace suppression list, so Bird did not attempt delivery. `transmission_failed` means the message could not be transmitted for delivery. `generation_failure` means the message could not be built for delivery (a template or content issue). `policy_rejection` means the message was refused by sending policy.
+ *
+ */
+type EmailRejectionReason = "recipient_suppressed" | "transmission_failed" | "generation_failure" | "policy_rejection";
+/**
+ * Payload of the email.rejected event.
+ */
+type EventEmailRejectedData = EventEmailBase & {
+    rejection_reason: EmailRejectionReason;
+};
+/**
+ * Bird rejected the email before sending it (suppression list hit, transmission failure, or a content/policy guard). Fires once per recipient.
+ */
+type EventEmailRejected = {
+    /**
+     * Event type.
+     */
+    type: "email.rejected";
+    /**
+     * Time the rejection was recorded.
+     */
+    timestamp: string;
+    data: EventEmailRejectedData;
+};
+/**
+ * Payload of the email.received event.
+ */
+type EventEmailReceivedData = {
+    /**
+     * ID of the received email (rem_ prefix). Use it with GET /v1/email/inbound-messages/{id} to fetch the body.
+     */
+    inbound_message_id: string;
+    /**
+     * ID of the workspace.
+     */
+    workspace_id: WorkspaceId;
+    /**
+     * RFC 5322 Message-ID header from the sender, or null when the sender did not include one.
+     */
+    message_id: string | null;
+    /**
+     * Envelope-from address.
+     */
+    from: string;
+    /**
+     * Subject line as received.
+     */
+    subject: string;
+};
+/**
+ * Bird received and parsed an inbound email. The payload includes message metadata, extracted text, and threading headers (not the raw body). Additional fields — cc/bcc recipients, attachment metadata, and authentication results — will be added in a future release.
+ */
+type EventEmailReceived = {
+    /**
+     * Event type.
+     */
+    type: "email.received";
+    /**
+     * When Bird received the message.
+     */
+    timestamp: string;
+    data: EventEmailReceivedData;
+};
+/**
+ * Payload of the email.processed event.
+ */
+type EventEmailProcessedData = EventEmailBase;
+/**
+ * Bird processed the message and queued it for delivery to the recipient's mail server. Fires once per recipient when the message enters the SMTP delivery queue.
+ */
+type EventEmailProcessed = {
+    /**
+     * Event type.
+     */
+    type: "email.processed";
+    /**
+     * Time Bird processed the message and queued it for SMTP delivery.
+     */
+    timestamp: string;
+    data: EventEmailProcessedData;
+};
+/**
+ * Payload of the email.out_of_band_bounce event.
+ */
+type EventEmailOutOfBandBounceData = EventEmailBase & {
+    bounce_type: EmailBounceType;
+    /**
+     * Numeric bounce classification for fine-grained deliverability triage, or null when the receiving server's response could not be classified.
+     *
+     */
+    bounce_class: number | null;
+    /**
+     * SMTP reply code returned by the receiving mail server, or null when none was provided.
+     */
+    bounce_code: string | null;
+    /**
+     * Human-readable reason the receiving mail server gave for the bounce, or null when none was provided.
+     */
+    bounce_description: string | null;
+    /**
+     * The IP address used to send this message, or null when it is not known.
+     */
+    sending_ip: string | null;
+};
+/**
+ * Bounce classification. `hard` is a permanent failure (invalid address or non-existent domain). `soft` is a transient failure (mailbox full, server temporarily unavailable). `block` indicates the receiving mail server blocked the sending IP for reputation reasons. `admin` indicates an administrative refusal (relaying denied, blocklisted domain). `undetermined` is used when the receiving server's response is ambiguous.
+ *
+ */
+type EmailBounceType = "hard" | "soft" | "undetermined" | "admin" | "block";
+/**
+ * A bounce notification arrived after the message had already been accepted for delivery. Fires once per recipient.
+ */
+type EventEmailOutOfBandBounce = {
+    /**
+     * Event type.
+     */
+    type: "email.out_of_band_bounce";
+    /**
+     * Time the bounce notification was recorded.
+     */
+    timestamp: string;
+    data: EventEmailOutOfBandBounceData;
+};
+/**
+ * Payload of the email.opened event.
+ */
+type EventEmailOpenedData = EventEmailBase & {
+    /**
+     * IP address of the client that opened the email, or null when it is not known.
+     */
+    ip_address: string | null;
+    /**
+     * User-agent string of the client that opened the email, or null when it is not known.
+     */
+    user_agent: string | null;
+};
+/**
+ * The recipient opened the email (the tracking pixel was loaded). May fire more than once per recipient.
+ */
+type EventEmailOpened = {
+    /**
+     * Event type.
+     */
+    type: "email.opened";
+    /**
+     * Time the open was recorded.
+     */
+    timestamp: string;
+    data: EventEmailOpenedData;
+};
+/**
+ * Payload of the email.list_unsubscribed event.
+ */
+type EventEmailListUnsubscribedData = EventEmailBase;
+/**
+ * Recipient unsubscribed via the RFC 8058 one-click List-Unsubscribe mechanism. Fires once per recipient.
+ */
+type EventEmailListUnsubscribed = {
+    /**
+     * Event type.
+     */
+    type: "email.list_unsubscribed";
+    /**
+     * Time the unsubscribe was recorded.
+     */
+    timestamp: string;
+    data: EventEmailListUnsubscribedData;
+};
+/**
+ * Payload of the email.delivered event.
+ */
+type EventEmailDeliveredData = EventEmailBase;
+/**
+ * An outbound email reached the recipient's mail server and was accepted.
+ */
+type EventEmailDelivered = {
+    /**
+     * Event type.
+     */
+    type: "email.delivered";
+    /**
+     * Time the recipient's mail server accepted the message.
+     */
+    timestamp: string;
+    data: EventEmailDeliveredData;
+};
+/**
+ * Payload of the email.deferred event.
+ */
+type EventEmailDeferredData = EventEmailBase & {
+    bounce_type: EmailBounceType;
+    /**
+     * Numeric bounce classification for fine-grained deliverability triage, or null when the receiving server's response could not be classified. Distinguishes, for example, a greylisting deferral from a full mailbox.
+     *
+     */
+    bounce_class: number | null;
+    /**
+     * Human-readable reason the receiving mail server gave for the deferral, or null when none was provided.
+     */
+    defer_reason: string | null;
+    /**
+     * The IP address used to send this message, or null when it is not known.
+     */
+    sending_ip: string | null;
+};
+/**
+ * The recipient's mail server temporarily refused the email; delivery will be retried. May fire more than once per recipient.
+ */
+type EventEmailDeferred = {
+    /**
+     * Event type.
+     */
+    type: "email.deferred";
+    /**
+     * Time the deferral was recorded.
+     */
+    timestamp: string;
+    data: EventEmailDeferredData;
+};
+/**
+ * Payload of the email.complained event.
+ */
+type EventEmailComplainedData = EventEmailBase & {
+    /**
+     * The kind of feedback the mailbox provider reported (such as `abuse` or `fraud`), or null when the provider did not specify one.
+     */
+    feedback_type: string | null;
+};
+/**
+ * The recipient marked the email as spam through their mailbox provider's feedback loop. Fires once per recipient.
+ */
+type EventEmailComplained = {
+    /**
+     * Event type.
+     */
+    type: "email.complained";
+    /**
+     * Time the complaint was recorded.
+     */
+    timestamp: string;
+    data: EventEmailComplainedData;
+};
+/**
+ * Payload of the email.clicked event.
+ */
+type EventEmailClickedData = EventEmailBase & {
+    /**
+     * The URL the recipient clicked.
+     */
+    url: string;
+    /**
+     * IP address of the client that clicked the link, or null when it is not known.
+     */
+    ip_address: string | null;
+    /**
+     * User-agent string of the client that clicked the link, or null when it is not known.
+     */
+    user_agent: string | null;
+};
+/**
+ * The recipient clicked a tracked link in the email. May fire more than once per recipient.
+ */
+type EventEmailClicked = {
+    /**
+     * Event type.
+     */
+    type: "email.clicked";
+    /**
+     * Time the click was recorded.
+     */
+    timestamp: string;
+    data: EventEmailClickedData;
+};
+/**
+ * Payload of the email.bounced event.
+ */
+type EventEmailBouncedData = EventEmailBase & {
+    bounce_type: EmailBounceType;
+    /**
+     * Numeric bounce classification for fine-grained deliverability triage, or null when the receiving server's response could not be classified. Lets you distinguish, for example, a DNS failure from a spam block when both would be `bounce_type: soft` or `bounce_type: block`.
+     *
+     */
+    bounce_class: number | null;
+    /**
+     * SMTP reply code returned by the receiving mail server, or null when none was provided.
+     */
+    bounce_code: string | null;
+    /**
+     * Human-readable reason the receiving mail server gave for the bounce, or null when none was provided.
+     */
+    bounce_description: string | null;
+    /**
+     * The IP address used to send this message, or null when it is not known.
+     */
+    sending_ip: string | null;
+};
+/**
+ * An outbound email permanently failed at the recipient's mail server. Fires once per recipient.
+ */
+type EventEmailBounced = {
+    /**
+     * Event type.
+     */
+    type: "email.bounced";
+    /**
+     * Time the bounce was recorded.
+     */
+    timestamp: string;
+    data: EventEmailBouncedData;
+};
+/**
+ * Payload of the email.accepted event.
+ */
+type EventEmailAcceptedData = EventEmailBase;
+/**
+ * Bird accepted the email send and is preparing to deliver. Fires once per requested recipient at acceptance time.
+ */
+type EventEmailAccepted = {
+    /**
+     * Event type.
+     */
+    type: "email.accepted";
+    /**
+     * Time Bird accepted the send.
+     */
+    timestamp: string;
+    data: EventEmailAcceptedData;
+};
+/**
+ * A sending domain completed DNS verification successfully. Payload schema not yet finalized.
+ */
+type EventDomainVerified = {
+    /**
+     * Event type.
+     */
+    type: "domain.verified";
+    /**
+     * When the event occurred.
+     */
+    timestamp: string;
+    /**
+     * Event payload. The fields for this event are not yet finalized.
+     */
+    data: {
+        [key: string]: never;
+    };
+};
+/**
+ * A sending domain failed DNS verification. Payload schema not yet finalized.
+ */
+type EventDomainFailed = {
+    /**
+     * Event type.
+     */
+    type: "domain.failed";
+    /**
+     * When the event occurred.
+     */
+    timestamp: string;
+    /**
+     * Event payload. The fields for this event are not yet finalized.
+     */
+    data: {
+        [key: string]: never;
+    };
+};
+/**
+ * Discriminated union of every webhook event the Bird platform emits.
+ * Each variant is the full delivery body: `type` names the event, `timestamp` is when the event occurred, and `data` carries the event-specific payload. The `type` property selects the variant — SDKs that consume this schema (openapi-typescript, oapi-codegen) generate a narrowed union keyed on `type`, so customer code can switch on the event id and access the variant-specific payload fields without casting.
+ * Delivery metadata (the event id and per-attempt signature headers) rides in HTTP headers per Standard Webhooks and is handled by the SDK's webhook verification helper, which returns one of these variants.
+ *
+ */
+type WebhookEvent = ({
+    type: "domain.failed";
+} & EventDomainFailed) | ({
+    type: "domain.verified";
+} & EventDomainVerified) | ({
+    type: "email.accepted";
+} & EventEmailAccepted) | ({
+    type: "email.bounced";
+} & EventEmailBounced) | ({
+    type: "email.clicked";
+} & EventEmailClicked) | ({
+    type: "email.complained";
+} & EventEmailComplained) | ({
+    type: "email.deferred";
+} & EventEmailDeferred) | ({
+    type: "email.delivered";
+} & EventEmailDelivered) | ({
+    type: "email.list_unsubscribed";
+} & EventEmailListUnsubscribed) | ({
+    type: "email.opened";
+} & EventEmailOpened) | ({
+    type: "email.out_of_band_bounce";
+} & EventEmailOutOfBandBounce) | ({
+    type: "email.processed";
+} & EventEmailProcessed) | ({
+    type: "email.received";
+} & EventEmailReceived) | ({
+    type: "email.rejected";
+} & EventEmailRejected) | ({
+    type: "email.unsubscribed";
+} & EventEmailUnsubscribed) | ({
+    type: "email_suppression.created";
+} & EventEmailSuppressionCreated);
+/**
+ * File attached to an email send. The attachment bytes are passed as base64-encoded `content` directly in the request body (required). The `path` field (provide a URL and Bird fetches the attachment for you) is a preview feature and currently unavailable. Requests are rejected with 422 if `content` is missing — `path` alone does not satisfy the schema. When `path` becomes generally available, the schema will be relaxed so that exactly one of `content` or `path` is required.
+ * Inline images for `<img src="cid:..."/>` references in the HTML body use the `content_id` field together with `content`.
+ * Total message size (body + inline images + all attachments) is capped at **20 MB on the wire (post-base64)**. Sends above this limit are rejected. As a rule of thumb, raw file content should stay under ~15 MB to leave headroom after base64 encoding.
+ * Recipient-side delivery reality: most consumer inboxes cap at 20–25 MB (Gmail 25 MB, Outlook desktop 20 MB, Exchange corporate often 10 MB). Sends close to Bird's 20 MB cap may be accepted by Bird but bounce at the recipient's mail server.
+ * Sends with attachments cannot use `POST /v1/emails/batch`; use the single-send endpoint instead. Certain executable / script content types are rejected at validation time.
+ *
+ */
+type EmailAttachment = {
+    /**
+     * Filename shown to the recipient. Required.
+     */
+    filename: string;
+    /**
+     * Base64-encoded attachment bytes. Required. Counts against the 20 MB per-send wire cap.
+     *
+     */
+    content: string;
+    /**
+     * Preview feature — provide a URL and Bird fetches the attachment for you. Currently unavailable. Use `content` instead. The schema currently requires `content`, so a request with only `path` is rejected with 422 for missing `content`; a request supplying both `content` and `path` is rejected with 422 `unsupported_feature` until this preview ships. When generally available: HTTPS-only, single redirect followed and re-validated, private IP ranges blocked, request timeout enforced, fetched content counts against the 20 MB per-send wire cap.
+     *
+     */
+    path?: string;
+    /**
+     * MIME type. Inferred from `filename` extension when omitted. Used to enforce the blocklist of disallowed executable / script types.
+     *
+     */
+    content_type?: string;
+    /**
+     * RFC 2392 Content-ID. When set, the attachment is rendered inline and can be referenced from the HTML body as `<img src="cid:{content_id}"/>`. When omitted, the attachment is rendered as a regular file attachment.
+     *
+     */
+    content_id?: string;
+};
+/**
+ * An email address with an optional display name.
+ */
+type EmailAddress = {
+    /**
+     * Email address.
+     */
+    email: string;
+    /**
+     * Display name shown alongside the address in mail clients.
+     */
+    name?: string;
+};
+/**
+ * A sender or recipient address. Accepts a plain email string (`jane@example.com`), an RFC 5322 mailbox string with an embedded display name (`Jane Doe <jane@example.com>`), or an object carrying the address and an optional display name. All forms can be mixed freely within one request; responses always return the object form.
+ *
+ */
+type EmailAddressInput = string | EmailAddress;
+type EmailMessageSendRequest = {
+    /**
+     * Sender address, as a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name. Must be from a verified domain in this workspace.
+     */
+    from: EmailAddressInput;
+    /**
+     * Primary recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name.
+     */
+    to: Array<EmailAddressInput>;
+    /**
+     * CC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name.
+     */
+    cc?: Array<EmailAddressInput>;
+    /**
+     * BCC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (`Jane <jane@example.com>`), or an object with an optional display name.
+     */
+    bcc?: Array<EmailAddressInput>;
+    /**
+     * Message subject line.
+     */
+    subject: string;
+    /**
+     * HTML body. At least one of html or text must be provided.
+     */
+    html?: string;
+    /**
+     * Plain-text body. At least one of html or text must be provided.
+     */
+    text?: string;
+    /**
+     * Reply-To addresses, each a plain email string, an RFC 5322 mailbox string, or an object with an optional display name. RFC 5322 allows multiple. Every recipient reply hits all listed addresses, so 1-2 is typical; the 25 cap exists to prevent runaway header sizes that some MTAs reject.
+     *
+     */
+    reply_to?: Array<EmailAddressInput>;
+    /**
+     * Custom email headers as key-value pairs.
+     */
+    headers?: {
+        [key: string]: string;
+    };
+    /**
+     * Structured `{name, value}` labels for **filtering and analytics**. Tags become first-class query dimensions: filter the list endpoint by tag name, slice analytics rollups by tag, and surface in webhook payloads. Cap: 20 tags per send. Use tags for low-cardinality dimensions (`category`, `experiment_variant`, `template_id`). For arbitrary structured context that you do not need as a filter dimension, use `metadata` instead.
+     *
+     */
+    tags?: Array<EmailTag>;
+    /**
+     * Arbitrary JSON object **stored, returned on API reads, and echoed in webhook payloads**. Path-queryable in analytics (e.g. filter on `metadata.order_id`) but not surfaced as a first-class dashboard filter dimension. Cap: 2 KB serialized. Use metadata for per-send context like internal IDs, foreign keys, and structured payloads you want round-tripped through events. For low-cardinality filterable labels, use `tags` instead.
+     *
+     */
+    metadata?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Whether to track open events for this message.
+     */
+    track_opens?: boolean;
+    /**
+     * Whether to track click events for this message.
+     */
+    track_clicks?: boolean;
+    /**
+     * ID of the IP pool to send from (`ipp_` prefix), or `ipp_shared` to route through the shared pool explicitly. Omit to use your organization's default pool. An unknown pool, or a pool with no dedicated IPs available to send from, is rejected with a `422`.
+     *
+     */
+    ip_pool?: string;
+    /**
+     * Content classification — independent of which endpoint you use. Controls suppression policy: `marketing` blocks on all suppression reasons (use for marketing content); `transactional` allows delivery through complaint and unsubscribe suppressions (use for receipts, password resets, and similar operational messages). Default: transactional.
+     *
+     */
+    category?: "marketing" | "transactional";
+    /**
+     * Preview feature — threaded replies. Currently unavailable; supplying this field returns `422 unsupported_feature`. When generally available, sets In-Reply-To and References headers automatically.
+     */
+    in_reply_to_message_id?: EmailId;
+    /**
+     * File attachments. Total message size (body + inline images + all attachments) capped at 20 MB post-base64. Raw file content should stay under ~15 MB to leave room after encoding. Sends with attachments cannot use `POST /v1/emails/batch`; use the single-send endpoint. See the EmailAttachment schema for the full field contract.
+     *
+     */
+    attachments?: Array<EmailAttachment>;
+    /**
+     * Preview feature — send-later scheduling. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+     */
+    scheduled_at?: string;
+    /**
+     * Preview feature — contact-targeted sends. Currently unavailable; supplying this field returns `422 unsupported_feature`.
+     */
+    contact_id?: string;
+    /**
+     * Preview feature — topic-gated sends. Currently unavailable; supplying this field returns `422 unsupported_feature`. When generally available, a non-empty `topic_id` gates delivery on the recipient's opt-in state for that topic — if the recipient is opt_out, the send is silently suppressed and an `email.suppressed` event fires with `reason: topic_opt_out`.
+     *
+     */
+    topic_id?: string;
+};
+/**
+ * Attachment metadata returned on API reads. The original content is not echoed back — only the metadata needed for display and audit. To fetch the raw attachment content (when storage is enabled), use `GET /v1/email/messages/{email_id}/attachments/{attachment_id}` — endpoint reserved for a future content-retention product.
+ *
+ */
+type EmailAttachmentRef = {
+    /**
+     * Attachment ID, stable per email send.
+     */
+    id?: string;
+    /**
+     * Filename as shown to the recipient.
+     */
+    filename: string;
+    /**
+     * Resolved MIME type at send time.
+     */
+    content_type?: string;
+    /**
+     * Decoded size in bytes.
+     */
+    size: number;
+    /**
+     * True when the attachment was sent inline via a `content_id` reference in the HTML body, false for regular file attachments.
+     *
+     */
+    inline?: boolean;
+    /**
+     * The Content-ID set at send time, when the attachment was inline.
+     */
+    content_id?: string | null;
+};
+type EmailMessage = {
+    /**
+     * Message ID.
+     */
+    readonly id: EmailId;
+    /**
+     * Sender address. `name` is present when a display name was provided on the send.
+     */
+    from: EmailAddress;
+    /**
+     * Primary recipients. Length is the recipient count; use the broadcasts endpoint for audience-targeted sends. Each entry's `name` is present when a display name was provided on the send.
+     */
+    to: Array<EmailAddress>;
+    /**
+     * CC recipients.
+     */
+    cc?: Array<EmailAddress>;
+    /**
+     * BCC recipients.
+     */
+    bcc?: Array<EmailAddress>;
+    /**
+     * Message subject line.
+     */
+    subject: string;
+    /**
+     * Content classification. Controls suppression policy — `marketing` blocks on all suppression reasons; `transactional` allows delivery through complaint and unsubscribe suppressions.
+     *
+     */
+    category: "marketing" | "transactional";
+    /**
+     * Reply-To addresses, if set on the send. Empty/null when no Reply-To was provided.
+     */
+    reply_to?: Array<EmailAddress> | null;
+    /**
+     * Aggregate delivery status derived from recipient states. `accepted` means Bird has the send and is preparing to deliver. `processed` means Bird has processed the message and queued it for delivery to the recipient's mail server.
+     *
+     */
+    readonly status: "accepted" | "processed" | "deferred" | "delivered" | "partial_failure" | "bounced" | "complained" | "rejected";
+    /**
+     * Number of recipients currently in the `accepted` state — Bird has the send and is preparing to deliver.
+     */
+    readonly accepted_count: number;
+    /**
+     * Number of recipients for whom Bird has processed the message and queued it for delivery.
+     */
+    readonly processed_count: number;
+    /**
+     * Number of recipients whose messages were accepted by the remote MTA.
+     */
+    readonly delivered_count: number;
+    /**
+     * Number of recipients that resulted in a permanent delivery failure.
+     */
+    readonly bounced_count: number;
+    /**
+     * Number of recipients that reported spam.
+     */
+    readonly complained_count: number;
+    /**
+     * Number of recipients in transient delivery deferral; the provider is retrying.
+     */
+    readonly deferred_count: number;
+    /**
+     * Number of recipients rejected before delivery. See the per-recipient `rejection_reason` field on `GET /v1/emails/{id}/recipients` for the specific cause (suppression match, transmission failure, generation failure, or policy refusal).
+     *
+     */
+    readonly rejected_count: number;
+    /**
+     * Time between Bird accepting the send and the message being processed for delivery, in milliseconds, for the fastest recipient. Null until the first recipient reaches `processed`.
+     *
+     */
+    readonly processing_latency_ms?: number | null;
+    /**
+     * Time between the message being processed and the receiving mail server accepting it, in milliseconds, for the fastest delivered recipient. Null until the first recipient is delivered.
+     *
+     */
+    readonly delivery_latency_ms?: number | null;
+    /**
+     * End-to-end accept → delivered time for the fastest delivered recipient, in milliseconds. Null until the first recipient is delivered.
+     *
+     */
+    readonly total_latency_ms?: number | null;
+    /**
+     * Total open events across all recipients.
+     */
+    readonly open_count: number;
+    /**
+     * Total click events across all recipients.
+     */
+    readonly click_count: number;
+    /**
+     * Structured `{name, value}` filter labels applied to this send. See EmailMessageSendRequest for the tags vs metadata distinction.
+     */
+    tags?: Array<EmailTag>;
+    /**
+     * Arbitrary JSON metadata stored on the message object and echoed in webhook payloads. See EmailMessageSendRequest for the tags vs metadata distinction.
+     */
+    metadata?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Attachment metadata for the send. Empty when no attachments were included. Raw content is not echoed; use the future content-retrieval endpoint when storage is enabled.
+     */
+    attachments?: Array<EmailAttachmentRef>;
+    /**
+     * Whether open tracking is enabled for this send.
+     */
+    track_opens: boolean;
+    /**
+     * Whether click tracking is enabled for this send.
+     */
+    track_clicks: boolean;
+    /**
+     * When the send request was accepted.
+     */
+    readonly created_at: string;
+    /**
+     * Thread this message belongs to. Null until threading is enabled.
+     */
+    readonly thread_id?: string | null;
+    /**
+     * The message this one is a reply to, if any.
+     */
+    readonly in_reply_to_message_id?: string | null;
+    /**
+     * When all recipients reached a terminal delivered state, or null if not yet fully delivered.
+     */
+    readonly delivered_at?: string | null;
+};
+type ListEmailMessagesData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * Maximum number of items to return per page.
+         */
+        limit?: number;
+        /**
+         * Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
+         */
+        starting_after?: string;
+        /**
+         * Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.
+         */
+        ending_before?: string;
+        /**
+         * Return only resources created strictly after this timestamp. RFC 3339 / ISO 8601 with timezone.
+         */
+        created_after?: string;
+        /**
+         * Return only resources created strictly before this timestamp. RFC 3339 / ISO 8601 with timezone.
+         */
+        created_before?: string;
+        /**
+         * Filter by aggregate delivery status.
+         */
+        status?: "accepted" | "processed" | "deferred" | "delivered" | "partial_failure" | "bounced" | "complained" | "rejected";
+        /**
+         * Filter by tag. Accepts `name` to match any send carrying that tag name, or `name:value` to match a specific tag pair (e.g. `category:welcome`). For filtering on arbitrary `metadata` fields, use the metadata path-filter parameters instead.
+         *
+         */
+        tag?: string;
+        /**
+         * Filter by category.
+         */
+        category?: "marketing" | "transactional";
+        /**
+         * Filter by recipient address. Exact match against any `to`/`cc`/`bcc` recipient on the message; normalised to lowercase before comparison.
+         *
+         */
+        to?: string;
+        /**
+         * Filter by sender address. Exact match against the message `from` field; normalised to lowercase before comparison.
+         *
+         */
+        from?: string;
+    };
+    url: "/v1/email/messages";
+};
+
+type AuthToken = string | undefined;
+interface Auth {
+    /**
+     * Which part of the request do we use to send the auth?
+     *
+     * @default 'header'
+     */
+    in?: "header" | "query" | "cookie";
+    /**
+     * Header or query parameter name.
+     *
+     * @default 'Authorization'
+     */
+    name?: string;
+    scheme?: "basic" | "bearer";
+    type: "apiKey" | "http";
+}
+
+interface SerializerOptions<T> {
+    /**
+     * @default true
+     */
+    explode: boolean;
+    style: T;
+}
+type ArrayStyle = "form" | "spaceDelimited" | "pipeDelimited";
+type ObjectStyle = "form" | "deepObject";
+
+type QuerySerializer = (query: Record<string, unknown>) => string;
+type BodySerializer = (body: unknown) => unknown;
+type QuerySerializerOptionsObject = {
+    allowReserved?: boolean;
+    array?: Partial<SerializerOptions<ArrayStyle>>;
+    object?: Partial<SerializerOptions<ObjectStyle>>;
+};
+type QuerySerializerOptions = QuerySerializerOptionsObject & {
+    /**
+     * Per-parameter serialization overrides. When provided, these settings
+     * override the global array/object settings for specific parameter names.
+     */
+    parameters?: Record<string, QuerySerializerOptionsObject>;
+};
+
+type HttpMethod = "connect" | "delete" | "get" | "head" | "options" | "patch" | "post" | "put" | "trace";
+type Client$1<RequestFn = never, Config = unknown, MethodFn = never, BuildUrlFn = never, SseFn = never> = {
+    /**
+     * Returns the final request URL.
+     */
+    buildUrl: BuildUrlFn;
+    getConfig: () => Config;
+    request: RequestFn;
+    setConfig: (config: Config) => Config;
+} & {
+    [K in HttpMethod]: MethodFn;
+} & ([SseFn] extends [never] ? {
+    sse?: never;
+} : {
+    sse: {
+        [K in HttpMethod]: SseFn;
+    };
+});
+interface Config$1 {
+    /**
+     * Auth token or a function returning auth token. The resolved value will be
+     * added to the request payload as defined by its `security` array.
+     */
+    auth?: ((auth: Auth) => Promise<AuthToken> | AuthToken) | AuthToken;
+    /**
+     * A function for serializing request body parameter. By default,
+     * {@link JSON.stringify()} will be used.
+     */
+    bodySerializer?: BodySerializer | null;
+    /**
+     * An object containing any HTTP headers that you want to pre-populate your
+     * `Headers` object with.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more}
+     */
+    headers?: RequestInit["headers"] | Record<string, string | number | boolean | (string | number | boolean)[] | null | undefined | unknown>;
+    /**
+     * The request method.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/fetch#method See more}
+     */
+    method?: Uppercase<HttpMethod>;
+    /**
+     * A function for serializing request query parameters. By default, arrays
+     * will be exploded in form style, objects will be exploded in deepObject
+     * style, and reserved characters are percent-encoded.
+     *
+     * This method will have no effect if the native `paramsSerializer()` Axios
+     * API function is used.
+     *
+     * {@link https://swagger.io/docs/specification/serialization/#query View examples}
+     */
+    querySerializer?: QuerySerializer | QuerySerializerOptions;
+    /**
+     * A function validating request data. This is useful if you want to ensure
+     * the request conforms to the desired shape, so it can be safely sent to
+     * the server.
+     */
+    requestValidator?: (data: unknown) => Promise<unknown>;
+    /**
+     * A function transforming response data before it's returned. This is useful
+     * for post-processing data, e.g., converting ISO strings into Date objects.
+     */
+    responseTransformer?: (data: unknown) => Promise<unknown>;
+    /**
+     * A function validating response data. This is useful if you want to ensure
+     * the response conforms to the desired shape, so it can be safely passed to
+     * the transformers and returned to the user.
+     */
+    responseValidator?: (data: unknown) => Promise<unknown>;
+}
+
+type ServerSentEventsOptions<TData = unknown> = Omit<RequestInit, "method"> & Pick<Config$1, "method" | "responseTransformer" | "responseValidator"> & {
+    /**
+     * Fetch API implementation. You can use this option to provide a custom
+     * fetch instance.
+     *
+     * @default globalThis.fetch
+     */
+    fetch?: typeof fetch;
+    /**
+     * Implementing clients can call request interceptors inside this hook.
+     */
+    onRequest?: (url: string, init: RequestInit) => Promise<Request>;
+    /**
+     * Callback invoked when a network or parsing error occurs during streaming.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @param error The error that occurred.
+     */
+    onSseError?: (error: unknown) => void;
+    /**
+     * Callback invoked when an event is streamed from the server.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @param event Event streamed from the server.
+     * @returns Nothing (void).
+     */
+    onSseEvent?: (event: StreamEvent<TData>) => void;
+    serializedBody?: RequestInit["body"];
+    /**
+     * Default retry delay in milliseconds.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @default 3000
+     */
+    sseDefaultRetryDelay?: number;
+    /**
+     * Maximum number of retry attempts before giving up.
+     */
+    sseMaxRetryAttempts?: number;
+    /**
+     * Maximum retry delay in milliseconds.
+     *
+     * Applies only when exponential backoff is used.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @default 30000
+     */
+    sseMaxRetryDelay?: number;
+    /**
+     * Optional sleep function for retry backoff.
+     *
+     * Defaults to using `setTimeout`.
+     */
+    sseSleepFn?: (ms: number) => Promise<void>;
+    url: string;
+};
+interface StreamEvent<TData = unknown> {
+    data: TData;
+    event?: string;
+    id?: string;
+    retry?: number;
+}
+type ServerSentEventsResult<TData = unknown, TReturn = void, TNext = unknown> = {
+    stream: AsyncGenerator<TData extends Record<string, unknown> ? TData[keyof TData] : TData, TReturn, TNext>;
+};
+
+type ErrInterceptor<Err, Res, Req, Options> = (error: Err, 
+/** response may be undefined due to a network error where no response object is produced */
+response: Res | undefined, 
+/** request may be undefined, because error may be from building the request object itself */
+request: Req | undefined, options: Options) => Err | Promise<Err>;
+type ReqInterceptor<Req, Options> = (request: Req, options: Options) => Req | Promise<Req>;
+type ResInterceptor<Res, Req, Options> = (response: Res, request: Req, options: Options) => Res | Promise<Res>;
+declare class Interceptors<Interceptor> {
+    fns: Array<Interceptor | null>;
+    clear(): void;
+    eject(id: number | Interceptor): void;
+    exists(id: number | Interceptor): boolean;
+    getInterceptorIndex(id: number | Interceptor): number;
+    update(id: number | Interceptor, fn: Interceptor): number | Interceptor | false;
+    use(fn: Interceptor): number;
+}
+interface Middleware<Req, Res, Err, Options> {
+    error: Interceptors<ErrInterceptor<Err, Res, Req, Options>>;
+    request: Interceptors<ReqInterceptor<Req, Options>>;
+    response: Interceptors<ResInterceptor<Res, Req, Options>>;
+}
+
+type ResponseStyle = "data" | "fields";
+interface Config<T extends ClientOptions = ClientOptions> extends Omit<RequestInit, "body" | "headers" | "method">, Config$1 {
+    /**
+     * Base URL for all requests made by this client.
+     */
+    baseUrl?: T["baseUrl"];
+    /**
+     * Fetch API implementation. You can use this option to provide a custom
+     * fetch instance.
+     *
+     * @default globalThis.fetch
+     */
+    fetch?: typeof fetch;
+    /**
+     * Please don't use the Fetch client for Next.js applications. The `next`
+     * options won't have any effect.
+     *
+     * Install {@link https://www.npmjs.com/package/@hey-api/client-next `@hey-api/client-next`} instead.
+     */
+    next?: never;
+    /**
+     * Return the response data parsed in a specified format. By default, `auto`
+     * will infer the appropriate method from the `Content-Type` response header.
+     * You can override this behavior with any of the {@link Body} methods.
+     * Select `stream` if you don't want to parse response data at all.
+     *
+     * @default 'auto'
+     */
+    parseAs?: "arrayBuffer" | "auto" | "blob" | "formData" | "json" | "stream" | "text";
+    /**
+     * Should we return only data or multiple fields (data, error, response, etc.)?
+     *
+     * @default 'fields'
+     */
+    responseStyle?: ResponseStyle;
+    /**
+     * Throw an error instead of returning it in the response?
+     *
+     * @default false
+     */
+    throwOnError?: T["throwOnError"];
+}
+interface RequestOptions<TData = unknown, TResponseStyle extends ResponseStyle = "fields", ThrowOnError extends boolean = boolean, Url extends string = string> extends Config<{
+    responseStyle: TResponseStyle;
+    throwOnError: ThrowOnError;
+}>, Pick<ServerSentEventsOptions<TData>, "onRequest" | "onSseError" | "onSseEvent" | "sseDefaultRetryDelay" | "sseMaxRetryAttempts" | "sseMaxRetryDelay"> {
+    /**
+     * Any body that you want to add to your request.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/fetch#body}
+     */
+    body?: unknown;
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    /**
+     * Security mechanism(s) to use for the request.
+     */
+    security?: ReadonlyArray<Auth>;
+    url: Url;
+}
+interface ResolvedRequestOptions<TResponseStyle extends ResponseStyle = "fields", ThrowOnError extends boolean = boolean, Url extends string = string> extends RequestOptions<unknown, TResponseStyle, ThrowOnError, Url> {
+    headers: Headers;
+    serializedBody?: string;
+}
+type RequestResult<TData = unknown, TError = unknown, ThrowOnError extends boolean = boolean, TResponseStyle extends ResponseStyle = "fields"> = ThrowOnError extends true ? Promise<TResponseStyle extends "data" ? TData extends Record<string, unknown> ? TData[keyof TData] : TData : {
+    data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
+    request: Request;
+    response: Response;
+}> : Promise<TResponseStyle extends "data" ? (TData extends Record<string, unknown> ? TData[keyof TData] : TData) | undefined : ({
+    data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
+    error: undefined;
+} | {
+    data: undefined;
+    error: TError extends Record<string, unknown> ? TError[keyof TError] : TError;
+}) & {
+    /** request may be undefined, because error may be from building the request object itself */
+    request?: Request;
+    /** response may be undefined, because error may be from building the request object itself or from a network error */
+    response?: Response;
+}>;
+interface ClientOptions {
+    baseUrl?: string;
+    responseStyle?: ResponseStyle;
+    throwOnError?: boolean;
+}
+type MethodFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = "fields">(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, "method">) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
+type SseFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = "fields">(options: Omit<RequestOptions<never, TResponseStyle, ThrowOnError>, "method">) => Promise<ServerSentEventsResult<TData, TError>>;
+type RequestFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = "fields">(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, "method"> & Pick<Required<RequestOptions<TData, TResponseStyle, ThrowOnError>>, "method">) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
+type BuildUrlFn = <TData extends {
+    body?: unknown;
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    url: string;
+}>(options: TData & Options<TData>) => string;
+type Client = Client$1<RequestFn, Config, MethodFn, BuildUrlFn, SseFn> & {
+    interceptors: Middleware<Request, Response, unknown, ResolvedRequestOptions>;
+};
+interface TDataShape {
+    body?: unknown;
+    headers?: unknown;
+    path?: unknown;
+    query?: unknown;
+    url: string;
+}
+type OmitKeys<T, K> = Pick<T, Exclude<keyof T, K>>;
+type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown, TResponseStyle extends ResponseStyle = "fields"> = OmitKeys<RequestOptions<TResponse, TResponseStyle, ThrowOnError>, "body" | "path" | "query" | "url"> & ([TData] extends [never] ? unknown : Omit<TData, "url">);
+
+/** Resolved per-attempt inputs handed to the hey-api SDK call. */
+interface CallContext {
+    signal: AbortSignal;
+    /** Merged headers: caller `headers` plus the resolved `Idempotency-Key`. */
+    headers: Record<string, string>;
+}
+declare abstract class Resource {
+    protected readonly core: BirdHTTPClient;
+    protected readonly client: Client;
+    constructor(core: BirdHTTPClient, client: Client);
+    /** Run a single typed call through the lifecycle. */
+    protected call<T>(method: string, options: RequestOptions$1 | undefined, invoke: (ctx: CallContext) => Promise<FetchOutcome<T>>): APIPromise<T>;
+    /** Run a cursor-paginated list through the lifecycle (each page retried independently). */
+    protected paginated<T>(method: string, options: RequestOptions$1 | undefined, invoke: (ctx: CallContext, cursor: string | undefined) => Promise<FetchOutcome<CursorPage<T>>>): PaginatedPromise<T>;
+}
+
+/** Body for `bird.email.send`. */
+type EmailSendParams = EmailMessageSendRequest;
+/** Filters and cursor params for `bird.email.list`. */
+type EmailListQuery = NonNullable<ListEmailMessagesData["query"]>;
+/**
+ * Channel-level defaults set at client construction. Field names mirror the
+ * send params (so they read as pre-filled fields). Any field set here becomes
+ * optional in `send` and is filled when omitted (per-send value wins).
+ */
+type EmailChannelDefaults = Partial<Pick<EmailSendParams, "from" | "reply_to" | "category" | "track_opens" | "track_clicks" | "headers" | "tags" | "metadata">>;
+type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/** Keys that carry a configured default — made optional in `send`. */
+type DefaultedKeys<D> = D extends object ? Extract<keyof D, keyof EmailSendParams> : never;
+/** `send` params with defaulted fields made optional. */
+type EmailSend<D> = PartialBy<EmailSendParams, DefaultedKeys<D>>;
+declare class EmailResource<D extends EmailChannelDefaults | undefined = undefined> extends Resource {
+    #private;
+    constructor(core: ConstructorParameters<typeof Resource>[0], client: ConstructorParameters<typeof Resource>[1], defaults?: D);
+    /**
+     * Send an email message. Resolves once the message is accepted for delivery
+     * (the API's 202). Throws on failure — a 422 (unverified sender, all
+     * recipients suppressed, validation) is a `BirdValidationError`. Fields set as
+     * channel defaults may be omitted (per-send value wins).
+     *
+     * @example Send a message
+     * // bird:snippet:start email.send
+     * const msg = await bird.email.send({
+     *   from: { email: "onboarding@messagebird.dev", name: "Bird" },
+     *   to: ["delivered@messagebird.dev"],
+     *   subject: "Hello from Bird",
+     *   html: "<p>My first Bird email.</p>",
+     * });
+     * console.log(msg.id, msg.status); // "em_…", "accepted"
+     * // bird:snippet:end email.send
+     *
+     * @example A richer send — cc/bcc, reply-to, tags, metadata, click-tracking off, and an idempotency key (safe to retry; the server dedupes)
+     * await bird.email.send(
+     *   {
+     *     from: "hello@acme.com",
+     *     to: ["a@example.com", "b@example.com"],
+     *     cc: ["manager@example.com"],
+     *     reply_to: ["support@acme.com"],
+     *     subject: "Your March invoice",
+     *     html: "<p>Attached.</p>",
+     *     tags: [{ name: "category", value: "billing" }],
+     *     metadata: { invoice_id: "inv_123" },
+     *     track_clicks: false,
+     *   },
+     *   { idempotencyKey: "invoice-march/cust_1" },
+     * );
+     *
+     * @example Branch on the typed error hierarchy
+     * // bird:snippet:start email.errors
+     * import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";
+     *
+     * try {
+     *   await bird.email.send({
+     *     from: "onboarding@messagebird.dev",
+     *     to: ["delivered@messagebird.dev"],
+     *     subject: "Hello from Bird",
+     *     html: "<p>My first Bird email.</p>",
+     *   });
+     * } catch (err) {
+     *   if (err instanceof BirdRateLimitError) console.log(`rate limited — retry in ${err.retryAfter}s`);
+     *   else if (err instanceof BirdValidationError) console.error(err.details);
+     *   else if (err instanceof BirdAPIError) console.error(err.code, err.requestId);
+     *   else throw err;
+     * }
+     * // bird:snippet:end email.errors
+     *
+     * @example Errors as values with `.safe()`
+     * // bird:snippet:start email.safe
+     * const { data, error } = await bird.email
+     *   .send({
+     *     from: "onboarding@messagebird.dev",
+     *     to: ["delivered@messagebird.dev"],
+     *     subject: "Hello from Bird",
+     *     html: "<p>My first Bird email.</p>",
+     *   })
+     *   .safe();
+     * if (error) console.error(error.message);
+     * else console.log(data.id);
+     * // bird:snippet:end email.safe
+     */
+    send(params: EmailSend<D>, options?: RequestOptions$1): APIPromise<EmailMessage>;
+    /**
+     * Fetch a message with aggregate delivery status.
+     *
+     * @example
+     * // bird:snippet:start email.get
+     * const msg = await bird.email.get("em_abc123");
+     * msg.status; // "accepted" | "processed" | "delivered" | "bounced" | …
+     * msg.delivered_count;
+     * msg.bounced_count;
+     * // bird:snippet:end email.get
+     */
+    get(messageId: string, options?: RequestOptions$1): APIPromise<EmailMessage>;
+    /**
+     * List messages, newest first. `await` resolves the first page; `for await`
+     * walks every message across all pages.
+     *
+     * @example Iterate every message, or take one page
+     * // bird:snippet:start email.list.paginate
+     * // bird:snippet:start email.list.iterate
+     * for await (const message of bird.email.list({ status: "bounced" })) {
+     *   console.log(message.id);
+     * }
+     * // bird:snippet:end email.list.iterate
+     * const page = await bird.email.list({ limit: 50 }); // page.data, page.next_cursor
+     * // bird:snippet:end email.list.paginate
+     */
+    list(query?: EmailListQuery, options?: RequestOptions$1): PaginatedPromise<EmailMessage>;
+}
+
+/** A verified webhook event — discriminated on `type` (ADR-0028 wire contract). */
+type BirdWebhookEvent = WebhookEvent;
+/** Inbound request headers, as a `Headers` object or a plain record. */
+type WebhookHeaders = Headers | Record<string, string>;
+/** Client-level webhooks config (`new BirdClient({ webhooks: { secret } })`). */
+interface WebhookOptions {
+    /** Signing secret used by `unwrap`; a per-call `secret` overrides it. */
+    secret?: string;
+}
+declare class WebhooksResource {
+    #private;
+    constructor(config?: WebhookOptions);
+    /**
+     * Verify a webhook delivery and return the typed event.
+     *
+     * **Pass the raw request body**, exactly as received — do NOT parse it first.
+     * The Standard Webhooks signature is computed over the raw bytes, so parsing
+     * and re-serializing before verifying is the classic webhook bug.
+     *
+     * The secret comes from `webhooks.secret` on the client; pass `{ secret }` to
+     * override per call. Throws {@link BirdWebhookVerificationError} on a bad
+     * signature, a stale timestamp, or missing/malformed headers. Unknown event
+     * types are returned as-is (handle them in a `default` case) so a newer server
+     * event can't break an older SDK.
+     *
+     * @example Verify and dispatch — pass the raw request body, never the parsed JSON
+     * // new BirdClient({ apiKey, webhooks: { secret } })
+     * try {
+     *   const event = bird.webhooks.unwrap(rawBody, req.headers);
+     *   switch (event.type) {
+     *     case "email.delivered":
+     *       markDelivered(event.email_id, event.recipient); // narrowed; fields are flat
+     *       break;
+     *     case "email.bounced":
+     *     case "email.complained":
+     *       suppress(event.recipient);
+     *       break;
+     *     default: // unknown future event types — an older SDK won't break on a new one
+     *   }
+     * } catch (err) {
+     *   if (err instanceof BirdWebhookVerificationError) {
+     *     // reject with 400 — bad signature, stale timestamp, or missing/malformed headers
+     *   } else throw err;
+     * }
+     */
+    unwrap(payload: string, headers: WebhookHeaders, options?: WebhookOptions): BirdWebhookEvent;
+}
+
+interface BirdClientOptions {
+    apiKey: string;
+    /** Explicit base URL; overrides region resolution. For local/self-hosted use. */
+    baseUrl?: string;
+    /** Region override (e.g. `"eu1"`); the API key prefix is used by default. */
+    region?: string;
+    /** Per-attempt timeout in ms. Default 60_000. */
+    timeout?: number;
+    /** Max retry attempts on retryable failures (429, 5xx, network). Default 2. */
+    maxRetries?: number;
+    /** Custom fetch — testing, proxying, edge-runtime adapters. Default global fetch. */
+    fetch?: typeof fetch;
+    /** Headers added to every request. SDK-internal headers win on conflict. */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Email channel defaults. Any field set here may be omitted in
+     * `bird.email.send` (the type enforces this); the per-send value wins.
+     */
+    email?: EmailChannelDefaults;
+    /** Webhooks config — `secret` is the default used by `bird.webhooks.unwrap`. */
+    webhooks?: WebhookOptions;
+}
+/** A raw request for the `bird.request` escape hatch. */
+interface BirdRequest {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /**
+     * Absolute path on the API host, e.g. `/v1/email/domains`; must start
+     * with a single `/`.
+     */
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    /** JSON request body. */
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+type EmailDefaultsOf<O> = O extends {
+    email: infer E extends EmailChannelDefaults;
+} ? E : undefined;
+/**
+ * The Bird API client. Construct it with an API key; the region is taken from
+ * the key's prefix (`bk_{region}_…`) — pass `baseUrl` or `region` to override.
+ *
+ * @example Construct and send
+ * const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
+ * const msg = await bird.email.send({
+ *   from: "hello@acme.com",
+ *   to: ["customer@example.com"],
+ *   subject: "Welcome aboard",
+ *   html: "<h1>Hi there 👋</h1>",
+ * });
+ * console.log(msg.id);
+ *
+ * @example Channel defaults — set common send fields once; a per-send value always wins
+ * const bird = new BirdClient({
+ *   apiKey: process.env.BIRD_API_KEY!,
+ *   email: { from: "hello@acme.com", category: "transactional" },
+ * });
+ * // `from` and `category` are filled from the defaults; both stay optional in `send`.
+ * await bird.email.send({ to: ["customer@example.com"], subject: "Hi", html: "<p>hi</p>" });
+ *
+ * @example All client options
+ * // bird:snippet:start client.options
+ * const bird = new BirdClient({
+ *   apiKey: process.env.BIRD_API_KEY!,
+ *   region: "eu1", // optional — override the region from the key prefix
+ *   baseUrl: "http://localhost:8080", // optional — overrides region entirely (local/self-hosted)
+ *   timeout: 60_000, // per-attempt timeout in ms (default 60_000)
+ *   maxRetries: 2, // retry budget for transient failures (default 2)
+ * });
+ * // bird:snippet:end client.options
+ */
+declare class BirdClient<const O extends BirdClientOptions = BirdClientOptions> {
+    #private;
+    protected readonly core: BirdHTTPClient;
+    /** The email channel — `bird.email.send(...)`, `.get(...)`, `.list(...)`. */
+    readonly email: EmailResource<EmailDefaultsOf<O>>;
+    /** Webhooks — `bird.webhooks.unwrap(payload, headers)` verifies an inbound delivery. */
+    readonly webhooks: WebhooksResource;
+    constructor(options: O);
+    /**
+     * Escape hatch for endpoints the typed resources don't cover. Runs the full
+     * lifecycle (auth, retries, idempotency, error mapping); you supply the
+     * response type. Prefer a typed resource method where one exists.
+     *
+     * @throws {TypeError} if `req.path` does not start with exactly one `/` or
+     *   resolves to a different origin than the configured Bird API base URL.
+     *
+     * @example Reach an endpoint outside the curated surface — you supply the response type
+     * type Suppressions = { data: Array<{ recipient: string }> };
+     * const suppressions = await bird.request<Suppressions>({ method: "GET", path: "/v1/email/suppressions" });
+     * console.log(suppressions.data.length);
+     */
+    request<T = unknown>(req: BirdRequest, options?: RequestOptions$1): APIPromise<T>;
+}
+
+/** Extracts the region code from a `bk_{region}_{token}` key, or undefined. */
+declare function regionFromApiKey(apiKey: string): string | undefined;
+declare function baseUrlForRegion(region: string): string;
+
+export { type APIPromise, BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, type BirdClientOptions, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, type BirdRequest, type BirdResponse, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, type BirdWebhookEvent, BirdWebhookVerificationError, type CursorPage, type EmailChannelDefaults, type EmailListQuery, type EmailMessage, type EmailSendParams, type ErrorDetail, type PaginatedPromise, type RequestOptions$1 as RequestOptions, type SafeResult, type WebhookHeaders, type WebhookOptions, baseUrlForRegion, regionFromApiKey };