@messagebird/sdk 0.38.2 → 0.40.0

package/dist/index.d.mts

@@ -1497,24 +1497,26 @@ type AudienceContactsRemoveRequest = {
  */
 type MessageDirection = "outbound" | "inbound";
 /**
- * Content classification. Tells Bird and carriers why you're sending; per-country compliance rules (opt-out policy, quiet hours) key on it as they roll out.
+ * Content classification: why you are sending. Carriers see it, and where a destination country requires the sender to be registered, that registration is approved for a category: a send outside what it covers returns a `422` `SenderCategoryNotPermitted`. A registration approved for `marketing` covers all four values; one approved for `transactional`, `authentication`, or `service` covers those three and not `marketing`. Use `authentication` for a one-time passcode and `marketing` for a promotion; otherwise pick the value matching the message's purpose.
  */
 type SmsMessageCategory = "transactional" | "marketing" | "authentication" | "service";
 type SmsMessageId = string;
 /**
  * Delivery status:
  *
- * - `scheduled`: Queued for a future send time.
  * - `accepted`: Accepted and awaiting carrier handoff.
  * - `sent`: Handed to the carrier and awaiting a delivery receipt.
  * - `delivered`: Confirmed as delivered.
- * - `undelivered`: Temporarily unreachable.
- * - `failed`: Permanently failed.
+ * - `undelivered`: The carrier reported delivery as failed for a reason that may clear later, such as a handset out of coverage or a carrier at capacity. Final all the same: the message is not retried, so reaching the recipient means sending again.
+ * - `failed`: The carrier reported delivery as failed for a reason that will not clear, such as an unassigned number, a recipient who has opted out, or content the carrier refused.
  * - `rejected`: Refused before carrier handoff.
- * - `canceled`: Canceled before a scheduled send.
  * - `expired`: Reached its validity limit without a final receipt.
  * - `received`: Received as an inbound message.
  *
+ * `scheduled` and `canceled` are declared ahead of the send-later scheduling
+ * feature that produces them, so their arrival is not a breaking change. No
+ * message carries either status today.
+ *
  */
 type SmsMessageStatus = "scheduled" | "accepted" | "sent" | "delivered" | "undelivered" | "failed" | "rejected" | "canceled" | "expired" | "received";
 /**
@@ -1600,7 +1602,7 @@ type SmsErrorCode = "invalid_destination" | "unreachable" | "blocked_by_carrier"
 type SmsError = {
   code: SmsErrorCode;
   /**
-   * Human-readable explanation of the failure.
+   * The failure in words, from whatever refused the message: the carrier's own reason text on a delivery receipt, or ours on a message stopped before a carrier saw it. Free-form, so branch on `code` and show this to a human.
    */
   description: string;
   /**
@@ -1661,12 +1663,12 @@ type SmsMessage = {
     [key: string]: unknown;
   };
   /**
-   * Settings Bird applied to this message, with any option you omitted filled in with the default that was in force when you sent it. Absent on inbound messages, and on outbound messages sent before Bird began recording these settings.
+   * The settings applied to this message, with any option you omitted filled in with the default in force when you sent it. Absent on inbound messages, and on any outbound message for which no settings were recorded.
    *
    */
   readonly options?: SmsMessageEffectiveOptions;
   /**
-   * How long, in seconds, Bird keeps trying to deliver before the message transitions to `expired`.
+   * Preview feature: how long, in seconds, the carrier may keep attempting delivery before the message is marked `expired`. Not returned yet.
    */
   readonly validity_period?: number;
   /**
@@ -1765,12 +1767,12 @@ type SmsMessageSendRequest = unknown & {
    */
   text?: string;
   /**
-   * Content classification. Tells Bird and carriers why you're sending; per-country compliance rules (opt-out policy, quiet hours) key on it as they roll out. Required on a free-text send; omit it on a template send, where the category is derived from the template.
+   * Content classification: why you are sending. Required on a free-text send; omit it on a template send, where the category is derived from the template. Where the destination country requires the sender to be registered, a category outside what that registration covers returns a `422` `SenderCategoryNotPermitted`.
    *
    */
   category?: SmsMessageCategory;
   /**
-   * Preview feature: how long, in seconds (60-172800), Bird keeps trying to deliver before the message transitions to `expired`. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`.
+   * Preview feature: how long, in seconds (60-172800), the carrier may keep attempting delivery before the message is marked `expired`. Currently unavailable; supplying this field returns `422 SMSUnsupportedFeature`.
    *
    */
   validity_period?: number;
@@ -1996,7 +1998,7 @@ type SmsTemplateVersionId = string;
  */
 type SmsTemplate = {
   /**
-   * Unique identifier for the template.
+   * The template's generated identifier. Accepted anywhere a template is referenced: the `{template_ref}` path segment, and `template.id` on a send. The `slug` works in the same places and is more readable.
    */
   readonly id: SmsTemplateId;
   /**
@@ -3846,6 +3848,128 @@ type WhatsAppLocation = {
    */
   url?: string;
 };
+/**
+ * The contact's name, in the parts their device supplied. Every part is optional: WhatsApp sends what the card holds and omits the rest.
+ *
+ */
+type WhatsAppContactName = {
+  /**
+   * The whole name as the contact's device renders it.
+   */
+  formatted_name?: string;
+  first_name?: string;
+  middle_name?: string;
+  last_name?: string;
+  prefix?: string;
+  suffix?: string;
+};
+/**
+ * Where the contact works, as their card records it.
+ */
+type WhatsAppContactOrg = {
+  company?: string;
+  department?: string;
+  title?: string;
+};
+/**
+ * One phone number on a shared contact card.
+ */
+type WhatsAppContactPhone = {
+  /**
+   * The number as the card holds it, normalized to E.164 where we can parse it. A card is whatever the contact's device stored, so a number that no country's numbering plan accepts, an extension among them, is passed through exactly as it arrived rather than dropped. Parse defensively: most values are E.164 and none is guaranteed to be.
+   *
+   */
+  phone_number?: string;
+  /**
+   * The label the contact's device attached, for example `CELL`, `Home` or `iPhone`. Free text passed through verbatim: WhatsApp declares no vocabulary here and does not normalize the casing, so neither do we.
+   *
+   */
+  type?: string;
+};
+/**
+ * One email address on a shared contact card.
+ */
+type WhatsAppContactEmail = {
+  email?: string;
+  /**
+   * The label the contact's device attached, for example `Personal` or `Work`. Free text passed through verbatim.
+   *
+   */
+  type?: string;
+};
+/**
+ * One website on a shared contact card.
+ */
+type WhatsAppContactUrl = {
+  /**
+   * The address as the card holds it, which is often bare rather than a full URL, so it is passed through as text rather than validated.
+   *
+   */
+  url?: string;
+  /**
+   * The label the contact's device attached, for example `Company`. Free text passed through verbatim.
+   *
+   */
+  type?: string;
+};
+/**
+ * One postal address on a shared contact card.
+ */
+type WhatsAppContactAddress = {
+  street?: string;
+  city?: string;
+  state?: string;
+  zip?: string;
+  country?: string;
+  /**
+   * The country as the card holds it, left exactly as WhatsApp sent it: it describes a postal address rather than a routing destination.
+   *
+   */
+  country_code?: string;
+  /**
+   * The label the contact's device attached, for example `Home`. Free text passed through verbatim.
+   *
+   */
+  type?: string;
+};
+/**
+ * A contact card the contact shared, either by tapping a button that asked for their number or by sending a card from their address book. Inbound only.
+ * Nothing here is required. WhatsApp sends the parts the card holds and omits the rest, and a card that arrives with only an `origin` is still meaningful, so an empty card reads back empty rather than being dropped.
+ *
+ */
+type WhatsAppContactCard = {
+  /**
+   * Why the card arrived. `contact_request` means the contact tapped a button this workspace sent asking for their number, which is the only signal that the message answers that ask; `other` means they shared a card in the chat. Open enum: treat an unrecognized value as a way of sharing added since.
+   *
+   */
+  origin?: string;
+  /**
+   * The contact's card in vCard format. WhatsApp sends it on a card shared in the chat and omits it on a button tap, which carries the number alone.
+   *
+   */
+  vcard?: string;
+  /**
+   * The contact's name, when the card carries one.
+   */
+  name?: WhatsAppContactName;
+  /**
+   * Where the contact works, when the card carries it.
+   */
+  org?: WhatsAppContactOrg;
+  /**
+   * The contact's birthday, which WhatsApp sends as `YYYY-MM-DD`. Passed through as text rather than typed as a date: the value comes off the contact's own device unvalidated, and a card we could not parse would otherwise have to lose the field or fail the whole read.
+   *
+   */
+  birthday?: string;
+  /**
+   * The numbers on the card. A button tap carries the contact's own number here, which is the point of asking.
+   *
+   */
+  phone_numbers?: Array<WhatsAppContactPhone>;
+  emails?: Array<WhatsAppContactEmail>;
+  urls?: Array<WhatsAppContactUrl>;
+  addresses?: Array<WhatsAppContactAddress>;
+};
 /**
  * A message whose content we do not model, named so it is visible in the message log rather than arriving empty. Inbound only.
  *
@@ -3941,6 +4065,11 @@ type WhatsAppMessage = {
    * Location the message carried.
    */
   readonly location?: WhatsAppLocation;
+  /**
+   * Contact cards the contact shared, either by tapping a button that asked for their number or by sending a card from their address book. Inbound only: sending a contact card is not supported.
+   *
+   */
+  readonly contact_cards?: Array<WhatsAppContactCard>;
   /**
    * Set when the contact sent content we do not model, naming the WhatsApp content type so the message is not silently empty. Inbound only.
    *
@@ -8126,6 +8255,11 @@ type EventWhatsAppReceivedData = EventWhatsAppBase & {
    * Location the contact sent.
    */
   location?: WhatsAppLocation;
+  /**
+   * Contact cards the contact shared, either by tapping a button that asked for their number or by sending a card from their address book.
+   *
+   */
+  contact_cards?: Array<WhatsAppContactCard>;
   /**
    * Set when the contact sent content the API does not model, naming the WhatsApp content type.
    *
@@ -9147,7 +9281,7 @@ type ListSmsMessagesData = {
      */
     direction?: MessageDirection;
     /**
-     * Keep only messages whose current `status` matches; repeat the parameter to match any of several. One of `scheduled`, `accepted`, `sent`, `delivered`, `undelivered`, `failed`, `rejected`, `canceled`, `expired`, or `received`.
+     * Keep only messages whose current `status` matches; repeat the parameter to match any of several. One of `scheduled`, `accepted`, `sent`, `delivered`, `undelivered`, `failed`, `rejected`, `canceled`, `expired`, or `received`. `scheduled` and `canceled` are accepted but match nothing until send-later scheduling ships.
      *
      */
     status?: Array<string>;
@@ -13172,7 +13306,7 @@ type VerifyVerificationsCheckParams = NonNullable<CreateVerificationCheckData["b
 type VerifyVerificationsNextChannelParams = NonNullable<CreateVerificationNextChannelData["body"]>;
 declare class VerifyVerificationsResource extends Resource {
   /**
-   * Start a verification and send a one-time passcode to the email address, phone number, or both in `to`. Delivery uses one planned channel at a time and fails over when necessary. Calling again for the same recipient reuses the verification in progress and sends after the resend cooldown. The passcode is never returned; submit the recipient's code with `verify.verifications.check`. SMS, WhatsApp, and Telegram delivery draw on the workspace's balance.
+   * Start a verification and send a one-time passcode to the email address, phone number, or both in `to`. Delivery uses one planned channel at a time and fails over when necessary. Calling again for the same recipient reuses the verification in progress and sends after the resend cooldown; each send past the cooldown spends one of the recipient's hourly send slots, so repeated resends can hit the cap and return 429. The passcode is never returned; submit the recipient's code with `verify.verifications.check`. SMS, WhatsApp, and Telegram delivery draw on the workspace's balance.
    *
    * @example Start a verification over SMS
    * const verification = await bird.verify.verifications.create({
@@ -13182,7 +13316,7 @@ declare class VerifyVerificationsResource extends Resource {
    */
   create(params: VerifyVerificationsCreateParams, options?: RequestOptions): APIPromise<Verification>;
   /**
-   * Check a passcode a recipient submitted. Identify the verification by the same `to` recipient used to start it; no verification ID is needed. A wrong or expired code returns HTTP 200 with `success: false` and a `reason` (for example `incorrect_code` or `expired`). A verification that has already reached a final state is no longer checkable and returns 404, as does a missing verification; malformed input or rate limiting is also an error status.
+   * Check a passcode a recipient submitted. Identify the verification by the same `to` recipient used to start it; no verification ID is needed. A wrong or expired code returns HTTP 200 with `success: false` and a `reason` (for example `incorrect_code` or `expired`). A verification that has already reached a final state is no longer checkable and returns 404 `E13000`, as does a missing verification, so a 404 does not tell you the recipient failed: treat an earlier `success: true` as the outcome rather than re-checking. Malformed input or rate limiting is also an error status.
    *
    * @example Check a submitted passcode
    * const result = await bird.verify.verifications.check({

package/dist/index.mjs

@@ -2819,7 +2819,7 @@ const createEmailLookup = (options) => (options.client ?? client).post({
 *
 * Creates a verification and sends the recipient a one-time passcode. Provide an email address, a phone number, or both in `to`. The service sends over one channel at a time and moves to the next planned channel if delivery fails.
 *
-* Calling this again for the same recipient reuses the verification in progress. During the resend cooldown, it returns the current state without sending. After the cooldown, it sends a fresh passcode.
+* Calling this again for the same recipient reuses the verification in progress. During the resend cooldown, it returns the current state without sending, so nothing is charged and no send budget is spent. After the cooldown, it sends a fresh passcode, and that send draws on the recipient's hourly send cap exactly as a new verification does, so repeated resends can exhaust the cap and return `429` for the rest of that rolling hour. [Abuse guardrails](/docs/guides/verify/sending-verifications#abuse-guardrails) gives the figures.
 *
 * The `200` response contains the current state, never the passcode. Submit the recipient's passcode with [Check a verification](/docs/api/reference/create-verification-check) before `expires_at`. An invalid recipient returns `422`; exceeding the send rate limit returns `429`.
 *
@@ -2847,10 +2847,14 @@ const createVerification = (options) => (options.client ?? client).post({
 *
 * A wrong or expired passcode returns `200 OK` with `success: false` and a `reason` such as `incorrect_code` or `expired`. `success: true` means the verification is complete. Each verification reports its final outcome once and cannot be checked again.
 *
-* An error status is returned only when the check cannot be evaluated. A `404`
-* means no verification matches the recipient or the matching one already
-* reached its final state. A `422` indicates an invalid recipient. A `429`
-* means passcodes for a recipient are being checked too quickly.
+* An error status is returned only when the check cannot be evaluated. A `404
+* E13000` means no active verification matched the recipient: either none
+* exists for it, or the most recent one is already resolved as verified,
+* expired, or out of attempts. One code covers all of those, so a `404` is not
+* evidence the recipient failed to verify. Treat your own record of an earlier
+* `success: true` as the outcome, and create a new verification only if the
+* recipient still needs to verify. A `422` indicates an invalid recipient. A
+* `429` means passcodes for a recipient are being checked too quickly.
 *
 */
 const createVerificationCheck = (options) => (options.client ?? client).post({
@@ -2874,9 +2878,9 @@ const createVerificationCheck = (options) => (options.client ?? client).post({
 *
 * Advances an in-progress verification to the next channel in its plan and sends a fresh passcode there. Identify the verification by the same `to` recipient used to create it; no verification ID is required.
 *
-* The send bypasses the resend cooldown, and passcodes sent earlier remain valid. The response sets `last_channel` to the most recent completed send. Concurrent requests each advance the plan by at most one channel and return committed state.
+* The send bypasses the resend cooldown and does not draw on the recipient's hourly send cap; what bounds it is the channel plan, since each call advances by at most one channel. Passcodes sent earlier remain valid. The response sets `last_channel` to the most recent completed send. Concurrent requests each advance the plan by at most one channel and return committed state.
 *
-* A missing in-progress verification returns `404`. A plan with no further channel returns `422 NoNextChannel`; create the verification again to resend on the current channel. If every remaining channel fails, the operation returns `422 NoAvailableChannel`. Requests that exceed the send rate limit return `429`.
+* A recipient with no in-progress verification returns `404 E13000`, whether none was ever created or the most recent one is already resolved. A recipient who has already verified is in that set, so a `404` here is not evidence they still need verifying, and creating another verification would send a passcode they no longer need. A plan with no further channel returns `422 NoNextChannel`; create the verification again to resend on the current channel. If every remaining channel fails, the operation returns `422 NoAvailableChannel`. Requests that exceed the send rate limit return `429`.
 *
 */
 const createVerificationNextChannel = (options) => (options.client ?? client).post({
@@ -6465,7 +6469,7 @@ var VoiceResource = class extends Resource {
 //#region src/resources/verifyVerifications.gen.ts
 var VerifyVerificationsResource = class extends Resource {
 	/**
-	* Start a verification and send a one-time passcode to the email address, phone number, or both in `to`. Delivery uses one planned channel at a time and fails over when necessary. Calling again for the same recipient reuses the verification in progress and sends after the resend cooldown. The passcode is never returned; submit the recipient's code with `verify.verifications.check`. SMS, WhatsApp, and Telegram delivery draw on the workspace's balance.
+	* Start a verification and send a one-time passcode to the email address, phone number, or both in `to`. Delivery uses one planned channel at a time and fails over when necessary. Calling again for the same recipient reuses the verification in progress and sends after the resend cooldown; each send past the cooldown spends one of the recipient's hourly send slots, so repeated resends can hit the cap and return 429. The passcode is never returned; submit the recipient's code with `verify.verifications.check`. SMS, WhatsApp, and Telegram delivery draw on the workspace's balance.
 	*
 	* @example Start a verification over SMS
 	* const verification = await bird.verify.verifications.create({
@@ -6482,7 +6486,7 @@ var VerifyVerificationsResource = class extends Resource {
 		}));
 	}
 	/**
-	* Check a passcode a recipient submitted. Identify the verification by the same `to` recipient used to start it; no verification ID is needed. A wrong or expired code returns HTTP 200 with `success: false` and a `reason` (for example `incorrect_code` or `expired`). A verification that has already reached a final state is no longer checkable and returns 404, as does a missing verification; malformed input or rate limiting is also an error status.
+	* Check a passcode a recipient submitted. Identify the verification by the same `to` recipient used to start it; no verification ID is needed. A wrong or expired code returns HTTP 200 with `success: false` and a `reason` (for example `incorrect_code` or `expired`). A verification that has already reached a final state is no longer checkable and returns 404 `E13000`, as does a missing verification, so a 404 does not tell you the recipient failed: treat an earlier `success: true` as the outcome rather than re-checking. Malformed input or rate limiting is also an error status.
 	*
 	* @example Check a submitted passcode
 	* const result = await bird.verify.verifications.check({
@@ -7378,9 +7382,9 @@ var BirdClient = class {
 		this.#headers = {
 			...opts.defaultHeaders,
 			Authorization: `Bearer ${opts.apiKey}`,
-			"User-Agent": `bird-sdk-js/0.38.2`,
+			"User-Agent": `bird-sdk-js/0.40.0`,
 			"Bird-Surface": "sdk-js",
-			"Bird-Version": "0.38.2"
+			"Bird-Version": "0.40.0"
 		};
 		const caller = detectCaller();
 		if (caller) this.#headers["Bird-Caller"] = caller;