@messagebird/sdk 0.1.1 → 0.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 The official TypeScript SDK for the [Bird](https://bird.com) API — fully typed, edge-ready, ESM.
 
+📚 **Documentation:** https://bird.com/docs/sdks/typescript
+
 ## Requirements
 
 - **Node.js 20.3+** or a modern edge runtime (Cloudflare Workers, Vercel Edge, Deno). The SDK uses only web-standard APIs (`fetch`, `AbortSignal`, Web Crypto) and ships no Node built-ins.
@@ -17,19 +19,21 @@ pnpm add @messagebird/sdk
 
 ## Quickstart
 
+<!-- bird:snippet quickstart-email -->
+
 ```ts
 import { BirdClient } from "@messagebird/sdk";
 
 const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
 
-const email = await bird.email.send({
-  from: "hello@acme.com",
-  to: ["customer@example.com"],
-  subject: "Welcome aboard",
-  html: "<h1>Hi there</h1>",
+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(email.id);
+console.log(msg.id, msg.status);
 ```
 
 The region is inferred from the API key prefix (`bk_{region}_…`). For a local or self-hosted server, pass `baseUrl` (which overrides region resolution).
@@ -80,14 +84,22 @@ switch (event.type) {
 
 Methods **throw** on failure with a typed error hierarchy you narrow with `instanceof`:
 
+<!-- bird:snippet email.errors -->
+
 ```ts
-import { BirdRateLimitError, BirdValidationError } from "@messagebird/sdk";
+import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";
 
 try {
-  await bird.email.send({ from, to, subject, html });
+  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>",
+  });
 } catch (err) {
-  if (err instanceof BirdRateLimitError) await sleep(err.retryAfter);
+  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;
 }
 ```
@@ -96,10 +108,19 @@ Every API error carries `statusCode`, `requestId`, and `type`. The core retries
 
 Prefer to branch on a value instead of catching? Use `.safe()`:
 
+<!-- bird:snippet email.safe -->
+
 ```ts
-const { data, error } = await bird.email.send({ from, to, subject, html }).safe();
-if (error) return; // data is null; error is a BirdError
-data.id; // narrowed
+const { data, error } = 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>",
+  })
+  .safe();
+if (error) console.error(error.message);
+else console.log(data.id);
 ```
 
 And `.withResponse()` exposes transport metadata (status, headers, request id) on success:

package/dist/index.d.ts

@@ -236,6 +236,240 @@ interface PaginatedPromise<T> extends Promise<CursorPage<T>>, AsyncIterable<T> {
     safe(): Promise<SafeResult<CursorPage<T>>>;
 }
 
+/**
+ * Payload of the sms.undelivered event.
+ */
+type EventSmsUndeliveredData = EventSmsBase & {
+    /**
+     * Why the message was not delivered.
+     */
+    error: SmsError;
+};
+/**
+ * Bird-stable failure reason. `invalid_destination` — the number is not assigned, ported out, or malformed. `unreachable` — handset off or out of coverage. `blocked_by_carrier` — the carrier filtered the message. `blocked_by_recipient` — the recipient device blocked the sender. `landline_unreachable` — the destination is a landline that does not accept SMS. `content_rejected` — the carrier rejected the content. `sender_unregistered` — the sender is not registered for the destination. `recipient_opted_out` — the recipient is on a suppression list. `provider_unavailable` — an upstream failure after retries. `unknown` — an unmapped failure.
+ *
+ */
+type SmsErrorCode = "invalid_destination" | "unreachable" | "blocked_by_carrier" | "blocked_by_recipient" | "landline_unreachable" | "content_rejected" | "sender_unregistered" | "recipient_opted_out" | "provider_unavailable" | "unknown";
+/**
+ * Failure detail for a message that could not be delivered or was rejected. Null when there is no failure.
+ */
+type SmsError = {
+    code: SmsErrorCode;
+    /**
+     * Human-readable explanation of the failure.
+     */
+    description: string;
+    /**
+     * Raw carrier-supplied error code, when available, for low-level debugging.
+     */
+    carrier_error_code?: string | null;
+    /**
+     * When the failure occurred.
+     */
+    occurred_at: string;
+} | null;
+/**
+ * Structured key/value tag attached to an SMS message. Surfaces in list filters, the event log, and webhook payloads. Use tags for low-cardinality filtering dimensions (category, experiment 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 SMSMessageSendRequest for the array maximum.
+ *
+ */
+type SmsTag = {
+    /**
+     * 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;
+};
+type WorkspaceId = string;
+type SmsMessageId = string;
+/**
+ * Identity fields shared by every SMS lifecycle event payload.
+ */
+type EventSmsBase = {
+    /**
+     * ID of the SMS message.
+     */
+    sms_id: SmsMessageId;
+    /**
+     * ID of the workspace.
+     */
+    workspace_id: WorkspaceId;
+    /**
+     * Recipient phone number in E.164 format.
+     */
+    to: string;
+    /**
+     * Sender the message was sent from — an E.164 number, an alphanumeric sender ID, or a short code.
+     */
+    from: string;
+    /**
+     * Tags provided on the send request, echoed on every event for the message so you can route and correlate without an extra lookup. Null when the message carried no tags.
+     *
+     */
+    tags: Array<SmsTag> | null;
+    /**
+     * The metadata object provided on the send request, echoed on every event for the message so you can correlate events with your own records. Null when the message carried no metadata.
+     *
+     */
+    metadata: {
+        [key: string]: unknown;
+    } | null;
+};
+/**
+ * The carrier reported a non-permanent failure to deliver the message.
+ */
+type EventSmsUndelivered = {
+    /**
+     * Event type.
+     */
+    type: "sms.undelivered";
+    /**
+     * Time the non-delivery was recorded.
+     */
+    timestamp: string;
+    data: EventSmsUndeliveredData;
+};
+/**
+ * Payload of the sms.sent event.
+ */
+type EventSmsSentData = EventSmsBase & {
+    /**
+     * Carrier that handled the message, or null when not known.
+     */
+    carrier: string | null;
+    /**
+     * Mobile country code and mobile network code of the carrier, or null when not known.
+     */
+    mcc_mnc: string | null;
+};
+/**
+ * Bird handed the message to the carrier for delivery.
+ */
+type EventSmsSent = {
+    /**
+     * Event type.
+     */
+    type: "sms.sent";
+    /**
+     * Time the message was handed to the carrier.
+     */
+    timestamp: string;
+    data: EventSmsSentData;
+};
+/**
+ * Payload of the sms.rejected event.
+ */
+type EventSmsRejectedData = EventSmsBase & {
+    /**
+     * Why the message was rejected before reaching the carrier.
+     */
+    error: SmsError;
+};
+/**
+ * Bird rejected the message before sending it to the carrier (invalid destination, suppression, or a content/policy guard).
+ */
+type EventSmsRejected = {
+    /**
+     * Event type.
+     */
+    type: "sms.rejected";
+    /**
+     * Time the rejection was recorded.
+     */
+    timestamp: string;
+    data: EventSmsRejectedData;
+};
+/**
+ * Payload of the sms.failed event.
+ */
+type EventSmsFailedData = EventSmsBase & {
+    /**
+     * Why the message terminally failed.
+     */
+    error: SmsError;
+};
+/**
+ * The message terminally failed and will not be delivered.
+ */
+type EventSmsFailed = {
+    /**
+     * Event type.
+     */
+    type: "sms.failed";
+    /**
+     * Time the failure was recorded.
+     */
+    timestamp: string;
+    data: EventSmsFailedData;
+};
+/**
+ * Payload of the sms.expired event.
+ */
+type EventSmsExpiredData = EventSmsBase;
+/**
+ * The message's validity period elapsed before it could be delivered.
+ */
+type EventSmsExpired = {
+    /**
+     * Event type.
+     */
+    type: "sms.expired";
+    /**
+     * Time the message expired.
+     */
+    timestamp: string;
+    data: EventSmsExpiredData;
+};
+/**
+ * Payload of the sms.delivered event.
+ */
+type EventSmsDeliveredData = EventSmsBase & {
+    /**
+     * Carrier that delivered the message, or null when not known.
+     */
+    carrier: string | null;
+    /**
+     * Mobile country code and mobile network code of the carrier, or null when not known.
+     */
+    mcc_mnc: string | null;
+};
+/**
+ * The carrier confirmed delivery of the message to the recipient handset.
+ */
+type EventSmsDelivered = {
+    /**
+     * Event type.
+     */
+    type: "sms.delivered";
+    /**
+     * Time the carrier confirmed delivery.
+     */
+    timestamp: string;
+    data: EventSmsDeliveredData;
+};
+/**
+ * Payload of the sms.accepted event.
+ */
+type EventSmsAcceptedData = EventSmsBase;
+/**
+ * Bird accepted the SMS send request and queued it for processing.
+ */
+type EventSmsAccepted = {
+    /**
+     * Event type.
+     */
+    type: "sms.accepted";
+    /**
+     * Time Bird accepted the request.
+     */
+    timestamp: string;
+    data: EventSmsAcceptedData;
+};
 /**
  * An email address was added to the workspace's suppression list (manually, via complaint, or via hard bounce). Payload schema not yet finalized.
  */
@@ -280,7 +514,6 @@ type EmailTag = {
  * Envelope position of a recipient on an outbound email event.
  */
 type RecipientRole = "to" | "cc" | "bcc";
-type WorkspaceId = string;
 type RecipientId = string;
 type EmailId = string;
 /**
@@ -360,14 +593,15 @@ type EventEmailRejected = {
     timestamp: string;
     data: EventEmailRejectedData;
 };
+type InboundEmailMessageId = string;
 /**
  * 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.
+     * ID of the received email. Use it with GET /v1/email/inbound-messages/{id} to fetch the body, raw content, and attachments.
      */
-    inbound_message_id: string;
+    inbound_message_id: InboundEmailMessageId;
     /**
      * ID of the workspace.
      */
@@ -381,12 +615,36 @@ type EventEmailReceivedData = {
      */
     from: string;
     /**
-     * Subject line as received.
+     * Recipient addresses the message was sent to.
      */
-    subject: string;
+    to: Array<string>;
+    /**
+     * Subject line as received, or null when the message had no subject.
+     */
+    subject: string | null;
+    /**
+     * In-Reply-To header — the Message-ID this message replies to, or null when it is not a reply.
+     */
+    in_reply_to?: string | null;
+    /**
+     * Whether SPF passed for the sender, or null when the result did not carry an SPF verdict.
+     */
+    spf_pass?: boolean | null;
+    /**
+     * Whether DKIM passed for the sender, or null when the result did not carry a DKIM verdict.
+     */
+    dkim_pass?: boolean | null;
+    /**
+     * Whether DMARC passed for the sender, or null when the result did not carry a DMARC verdict.
+     */
+    dmarc_pass?: boolean | null;
+    /**
+     * Spam score for the message. Always null at present; reserved for a future content-scoring capability.
+     */
+    spam_score?: number | null;
 };
 /**
- * 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.
+ * Bird received and parsed an inbound email. The payload carries the message's identifiers, sender and recipients, subject, threading reference, and authentication results — enough to route and triage without a fetch. Fetch the body, full headers, and attachments with GET /v1/email/inbound-messages/{id}.
  */
 type EventEmailReceived = {
     /**
@@ -740,13 +998,52 @@ type WebhookEvent = ({
     type: "email.unsubscribed";
 } & EventEmailUnsubscribed) | ({
     type: "email_suppression.created";
-} & EventEmailSuppressionCreated);
+} & EventEmailSuppressionCreated) | ({
+    type: "sms.accepted";
+} & EventSmsAccepted) | ({
+    type: "sms.delivered";
+} & EventSmsDelivered) | ({
+    type: "sms.expired";
+} & EventSmsExpired) | ({
+    type: "sms.failed";
+} & EventSmsFailed) | ({
+    type: "sms.rejected";
+} & EventSmsRejected) | ({
+    type: "sms.sent";
+} & EventSmsSent) | ({
+    type: "sms.undelivered";
+} & EventSmsUndelivered);
+type EmailMessageBatchResponse = {
+    /**
+     * One entry per message in the batch, in submission order.
+     */
+    data: Array<EmailMessageBatchItem>;
+};
+type EmailMessageBatchItem = {
+    /**
+     * Message ID assigned to this batch item.
+     */
+    readonly id: EmailId;
+    /**
+     * Initial status of this message in the batch.
+     */
+    readonly status: "accepted";
+    /**
+     * Resolved category for this batch item.
+     */
+    category: "marketing" | "transactional";
+};
+/**
+ * Batch of email message send requests. All items are validated before any are queued. Attachments are allowed on individual messages. Each message must stay within the 20 MB estimated generated message-size cap. The serialized JSON request body for the batch has a hard 20 MB cap.
+ *
+ */
+type EmailMessageBatchRequest = Array<EmailMessageSendRequest>;
 /**
  * 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.
+ * Bird enforces a **20 MB estimated generated message size** cap. The estimate is the HTML and text body plus all attachments and inline images measured after base64 encoding. This is not a raw file-size cap. As a rule of thumb, keep total raw attachment content at or below **15 MB** so the generated message has enough room after encoding and MIME wrapping.
+ * Recipient-side delivery reality: downstream limits vary by product and tenant/server policy. Gmail personal and Outlook.com document 25 MB attachment limits. Exchange Online defaults to 35 MB send / 36 MB receive, but admins can configure limits; on-prem Exchange Server organizational defaults are 10 MB. Sends close to Bird's 20 MB generated-message cap may be accepted by Bird but bounce at the recipient's mail server.
+ * Batch sends can include attachments on individual message objects. Each message still has the 20 MB estimated generated-size cap, and the serialized JSON request body for the whole batch has a hard 20 MB cap. Certain executable / script content types are rejected at validation time.
  *
  */
 type EmailAttachment = {
@@ -755,12 +1052,12 @@ type EmailAttachment = {
      */
     filename: string;
     /**
-     * Base64-encoded attachment bytes. Required. Counts against the 20 MB per-send wire cap.
+     * Base64-encoded attachment bytes. Required. Counts toward the 20 MB estimated generated message-size cap after encoding and MIME wrapping.
      *
      */
     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.
+     * 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 toward the 20 MB estimated generated message-size cap after encoding and MIME wrapping.
      *
      */
     path?: string;
@@ -857,7 +1154,7 @@ type EmailMessageSendRequest = {
      * 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;
+    ip_pool_id?: 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.
      *
@@ -868,7 +1165,7 @@ type EmailMessageSendRequest = {
      */
     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.
+     * File attachments. Bird rejects sends whose estimated generated message size exceeds 20 MB. The estimate is the HTML and text body plus all attachments and inline images measured after base64 encoding. Keep total raw attachment content at or below 15 MB for reliable headroom. In batch sends, this per-message cap still applies and the serialized JSON request body for the whole batch has a hard 20 MB cap. See the EmailAttachment schema for the full field contract.
      *
      */
     attachments?: Array<EmailAttachment>;
@@ -886,15 +1183,16 @@ type EmailMessageSendRequest = {
      */
     topic_id?: string;
 };
+type EmailAttachmentId = 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.
+ * Attachment metadata returned on API reads. The original content is not echoed back inline — only the metadata needed for display and audit. To download the raw attachment bytes (while content storage is enabled and within the retention window), use `GET /v1/email/messages/{message_id}/attachments/{attachment_id}`, which returns the file with its own content type and a Content-Disposition filename.
  *
  */
 type EmailAttachmentRef = {
     /**
      * Attachment ID, stable per email send.
      */
-    id?: string;
+    readonly id?: EmailAttachmentId;
     /**
      * Filename as shown to the recipient.
      */
@@ -981,7 +1279,7 @@ type EmailMessage = {
      */
     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).
+     * Number of recipients rejected before delivery. See the per-recipient `rejection_reason` field on `GET /v1/email/messages/{message_id}/recipients` for the specific cause (suppression match, transmission failure, generation failure, or policy refusal).
      *
      */
     readonly rejected_count: number;
@@ -1041,7 +1339,7 @@ type EmailMessage = {
     /**
      * The message this one is a reply to, if any.
      */
-    readonly in_reply_to_message_id?: string | null;
+    readonly in_reply_to_message_id?: EmailId | null;
     /**
      * When all recipients reached a terminal delivered state, or null if not yet fully delivered.
      */
@@ -1430,6 +1728,10 @@ declare abstract class Resource {
 
 /** Body for `bird.email.send`. */
 type EmailSendParams = EmailMessageSendRequest;
+/** Body for `bird.email.sendBatch` — an array of send params, validated as a unit. */
+type EmailSendBatchParams = EmailMessageBatchRequest;
+/** Result of `bird.email.sendBatch` — one accepted item per submitted message. */
+type EmailSendBatchResult = EmailMessageBatchResponse;
 /** Filters and cursor params for `bird.email.list`. */
 type EmailListQuery = NonNullable<ListEmailMessagesData["query"]>;
 /**
@@ -1485,7 +1787,7 @@ declare class EmailResource<D extends EmailChannelDefaults | undefined = undefin
      *
      * try {
      *   await bird.email.send({
-     *     from: "onboarding@messagebird.dev",
+     *     from: { email: "onboarding@messagebird.dev", name: "Bird" },
      *     to: ["delivered@messagebird.dev"],
      *     subject: "Hello from Bird",
      *     html: "<p>My first Bird email.</p>",
@@ -1502,7 +1804,7 @@ declare class EmailResource<D extends EmailChannelDefaults | undefined = undefin
      * // bird:snippet:start email.safe
      * const { data, error } = await bird.email
      *   .send({
-     *     from: "onboarding@messagebird.dev",
+     *     from: { email: "onboarding@messagebird.dev", name: "Bird" },
      *     to: ["delivered@messagebird.dev"],
      *     subject: "Hello from Bird",
      *     html: "<p>My first Bird email.</p>",
@@ -1513,6 +1815,34 @@ declare class EmailResource<D extends EmailChannelDefaults | undefined = undefin
      * // bird:snippet:end email.safe
      */
     send(params: EmailSend<D>, options?: RequestOptions$1): APIPromise<EmailMessage>;
+    /**
+     * Send a batch of up to 100 independent email messages in one request. The
+     * batch is validated as a unit — if any item fails validation (unverified
+     * sender, all recipients suppressed, field-level errors) the whole batch is
+     * rejected with a `BirdValidationError` and nothing is queued. Resolves with
+     * one accepted item per submitted message, in submission order, once the batch
+     * is accepted (the API's 202). Channel defaults are applied per item.
+     *
+     * @example Send a batch of messages
+     * // bird:snippet:start email.sendBatch
+     * const batch = await bird.email.sendBatch([
+     *   {
+     *     from: { email: "onboarding@messagebird.dev", name: "Bird" },
+     *     to: ["alice@example.com"],
+     *     subject: "Your receipt",
+     *     html: "<p>Thanks, Alice.</p>",
+     *   },
+     *   {
+     *     from: { email: "onboarding@messagebird.dev", name: "Bird" },
+     *     to: ["bob@example.com"],
+     *     subject: "Your receipt",
+     *     html: "<p>Thanks, Bob.</p>",
+     *   },
+     * ]);
+     * for (const item of batch.data) console.log(item.id, item.status);
+     * // bird:snippet:end email.sendBatch
+     */
+    sendBatch(params: EmailSendBatchParams, options?: RequestOptions$1): APIPromise<EmailSendBatchResult>;
     /**
      * Fetch a message with aggregate delivery status.
      *
@@ -1567,6 +1897,13 @@ declare class WebhooksResource {
      * types are returned as-is (handle them in a `default` case) so a newer server
      * event can't break an older SDK.
      *
+     * @example One call verifies the signature and returns the typed event
+     * // bird:snippet:start webhook.unwrap
+     * // Pass the RAW request body; set the secret via new BirdClient({ webhooks: { secret } }).
+     * const event = bird.webhooks.unwrap(rawBody, headers);
+     * console.log(event.type); // discriminated union — narrow on event.type
+     * // bird:snippet:end webhook.unwrap
+     *
      * @example Verify and dispatch — pass the raw request body, never the parsed JSON
      * // new BirdClient({ apiKey, webhooks: { secret } })
      * try {
@@ -1689,4 +2026,37 @@ declare class BirdClient<const O extends BirdClientOptions = BirdClientOptions>
 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 };
+/**
+ * Webhook event types known at this SDK version. The wire value is an open
+ * string: a value added by a newer server is returned by `unwrap` unchanged,
+ * so switch on these with a `default` branch.
+ */
+declare const WebhookEventType: {
+    readonly DomainFailed: "domain.failed";
+    readonly DomainVerified: "domain.verified";
+    readonly EmailAccepted: "email.accepted";
+    readonly EmailBounced: "email.bounced";
+    readonly EmailClicked: "email.clicked";
+    readonly EmailComplained: "email.complained";
+    readonly EmailDeferred: "email.deferred";
+    readonly EmailDelivered: "email.delivered";
+    readonly EmailListUnsubscribed: "email.list_unsubscribed";
+    readonly EmailOpened: "email.opened";
+    readonly EmailOutOfBandBounce: "email.out_of_band_bounce";
+    readonly EmailProcessed: "email.processed";
+    readonly EmailReceived: "email.received";
+    readonly EmailRejected: "email.rejected";
+    readonly EmailSuppressionCreated: "email_suppression.created";
+    readonly EmailUnsubscribed: "email.unsubscribed";
+    readonly SmsAccepted: "sms.accepted";
+    readonly SmsDelivered: "sms.delivered";
+    readonly SmsExpired: "sms.expired";
+    readonly SmsFailed: "sms.failed";
+    readonly SmsRejected: "sms.rejected";
+    readonly SmsSent: "sms.sent";
+    readonly SmsUndelivered: "sms.undelivered";
+};
+/** A known webhook event type value. */
+type WebhookEventTypeValue = (typeof WebhookEventType)[keyof typeof WebhookEventType];
+
+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 EmailSendBatchParams, type EmailSendBatchResult, type EmailSendParams, type ErrorDetail, type PaginatedPromise, type RequestOptions$1 as RequestOptions, type SafeResult, WebhookEventType, type WebhookEventTypeValue, type WebhookHeaders, type WebhookOptions, baseUrlForRegion, regionFromApiKey };