@messagebird/sdk 0.6.0 → 0.7.0

package/dist/index.d.mts

@@ -503,8 +503,30 @@ type EventSmsAccepted = {
   timestamp: string;
   data: EventSmsAcceptedData;
 };
+type SuppressionId = string;
 /**
- * An email address was added to the workspace's suppression list (manually, via complaint, or via hard bounce). Payload schema not yet finalized.
+ * Payload of the email_suppression.created event.
+ */
+type EventEmailSuppressionCreatedData = {
+  /**
+   * The suppression entry that was created.
+   */
+  suppression_id: SuppressionId;
+  /**
+   * The recipient address that was added to the suppression list.
+   */
+  email: string;
+  /**
+   * Why the address was suppressed.
+   */
+  reason: "hard_bounce" | "complaint" | "unsubscribe" | "manual";
+  /**
+   * The workspace the suppression belongs to.
+   */
+  workspace_id: WorkspaceId;
+};
+/**
+ * An email address was added to the workspace's suppression list (manually, via complaint, or via hard bounce).
  */
 type EventEmailSuppressionCreated = {
   /**
@@ -515,12 +537,7 @@ type EventEmailSuppressionCreated = {
    * When the event occurred.
    */
   timestamp: string;
-  /**
-   * Event payload. The fields for this event are not yet finalized.
-   */
-  data: {
-    [key: string]: never;
-  };
+  data: EventEmailSuppressionCreatedData;
 };
 /**
  * Payload of the email_mailbox.thread_created event.
@@ -1237,7 +1254,25 @@ type EventEmailAccepted = {
   data: EventEmailAcceptedData;
 };
 /**
- * A sending domain completed DNS verification successfully. Payload schema not yet finalized.
+ * Payload of the domain.verified event.
+ */
+type EventDomainVerifiedData = {
+  /**
+   * The sending domain resource that verified.
+   */
+  domain_id: DomainId;
+  /**
+   * The sending domain hostname.
+   */
+  domain: string;
+  /**
+   * The workspace the domain is assigned to.
+   */
+  workspace_id: WorkspaceId;
+};
+type DomainId = string;
+/**
+ * A sending domain completed DNS verification successfully.
  */
 type EventDomainVerified = {
   /**
@@ -1248,15 +1283,31 @@ type EventDomainVerified = {
    * When the event occurred.
    */
   timestamp: string;
+  data: EventDomainVerifiedData;
+};
+/**
+ * Payload of the domain.failed event.
+ */
+type EventDomainFailedData = {
   /**
-   * Event payload. The fields for this event are not yet finalized.
+   * The sending domain resource whose verification failed.
    */
-  data: {
-    [key: string]: never;
-  };
+  domain_id: DomainId;
+  /**
+   * The sending domain hostname.
+   */
+  domain: string;
+  /**
+   * The workspace the domain is assigned to.
+   */
+  workspace_id: WorkspaceId;
+  /**
+   * Why verification failed, when a specific reason is available (for example, the DKIM record was not found at the expected selector).
+   */
+  failure_reason?: string | null;
 };
 /**
- * A sending domain failed DNS verification. Payload schema not yet finalized.
+ * A sending domain failed DNS verification.
  */
 type EventDomainFailed = {
   /**
@@ -1267,12 +1318,7 @@ type EventDomainFailed = {
    * When the event occurred.
    */
   timestamp: string;
-  /**
-   * Event payload. The fields for this event are not yet finalized.
-   */
-  data: {
-    [key: string]: never;
-  };
+  data: EventDomainFailedData;
 };
 /**
  * Discriminated union of every webhook event the Bird platform emits.
@@ -1511,6 +1557,18 @@ type SendWhatsAppMessageRequest = {
    *
    */
   template?: SendWhatsAppMessageTemplate;
+  /**
+   * Structured `{name, value}` labels for filtering. Tags become first-class query dimensions: filter the list endpoint by tag name. Maximum 20 tags per send. Use tags for low-cardinality dimensions (`category`, `experiment_variant`). For arbitrary structured context you do not need as a filter dimension, use `metadata` instead.
+   *
+   */
+  tags?: Array<Tag>;
+  /**
+   * Arbitrary JSON object stored on the message and returned on API reads. Maximum 2 KB serialized. Use metadata for per-send context like internal IDs and foreign keys. For low-cardinality filterable labels, use `tags` instead.
+   *
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
 };
 type WhatsAppMessageTemplateComponentParameter = {
   /**
@@ -1639,6 +1697,116 @@ type WhatsAppMessage = {
    * When the message was read by the recipient. Null until then.
    */
   readonly read_at?: string | null;
+  /**
+   * Structured `{name, value}` filter labels applied to this message.
+   */
+  tags?: Array<Tag>;
+  /**
+   * Arbitrary JSON metadata stored on the message.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
+};
+type VerificationCheckResult = {
+  /**
+   * Whether the submitted passcode verified this verification. true means the passcode was correct and the verification is now complete; false means it was not verified — see reason. A verification that has already reached a final state is no longer checkable and returns 404.
+   */
+  readonly success: boolean;
+  /**
+   * Why the check did not succeed, or null when success is true. incorrect_code means the passcode was wrong and attempts remain; expired means the time window elapsed; attempts_exhausted means too many incorrect attempts. Open enum — treat any unrecognized value as a future reason.
+   */
+  readonly reason?: string | null;
+  verification: Verification;
+  /**
+   * The number of check attempts left, or null once the verification is complete.
+   */
+  readonly attempts_remaining?: number | null;
+};
+/**
+ * The channel a passcode is delivered over. Open enum — new channels may be added over time, so treat any unrecognized value as a future channel rather than an error.
+ */
+type VerificationChannel = string;
+type VerificationChannelEntry = {
+  channel: VerificationChannel;
+};
+/**
+ * The recipient to verify. Provide an email_address, a phone_number, or both; at least one is required.
+ */
+type VerificationTo = {
+  /**
+   * The recipient's email address.
+   */
+  email_address?: string;
+  /**
+   * The recipient's phone number in E.164 format.
+   */
+  phone_number?: string;
+};
+type VerificationId = string;
+type Verification = {
+  readonly id: VerificationId;
+  /**
+   * The verification's current state: pending (awaiting a valid passcode), verified, failed (too many incorrect attempts), or expired (the time window elapsed before a correct passcode).
+   */
+  readonly status: "pending" | "verified" | "failed" | "expired" | "canceled" | "blocked";
+  /**
+   * Why the verification reached its final state, or null while pending or once verified. Open enum — treat any unrecognized value as a future reason.
+   */
+  readonly reason?: string | null;
+  readonly to: VerificationTo;
+  /**
+   * The ordered channels this verification uses to deliver the passcode. An email recipient is verified over email; a phone recipient is verified over SMS.
+   */
+  readonly channels: Array<VerificationChannelEntry>;
+  /**
+   * The channel the most recent passcode was sent on, or null before the first send. Open enum — new channels may be added over time, so treat any unrecognized value as a future channel rather than an error.
+   */
+  readonly last_channel?: string | null;
+  /**
+   * The key/value pairs attached when the verification was created.
+   */
+  readonly metadata?: {
+    [key: string]: unknown;
+  };
+  /**
+   * When the verification expires if no correct passcode is submitted.
+   */
+  readonly expires_at: string;
+  /**
+   * When the verification was completed, or null if it is not yet verified.
+   */
+  readonly verified_at?: string | null;
+} & Timestamps;
+type VerificationCheckRequest = {
+  to: VerificationTo;
+  /**
+   * The passcode the recipient received.
+   */
+  code: string;
+};
+type VerificationCreateRequest = {
+  to: VerificationTo;
+  options?: VerificationOptions;
+  /**
+   * Optional key/value pairs to attach to the verification, for example a correlation id. Returned on the verification.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
+};
+/**
+ * Per-request overrides applied to this verification only.
+ */
+type VerificationOptions = {
+  /**
+   * Passcode length for this verification, overriding the configured length.
+   */
+  code_length?: number;
+  /**
+   * Reorder or narrow the delivery channels for this request. List channel names in the order to try them; a channel you omit is not used for this request, and a channel not already enabled for the recipient is ignored. Omit the field to use the configured order.
+   */
+  channels?: Array<VerificationChannel>;
 };
 type SmsTemplateList = {
   /**
@@ -2306,7 +2474,7 @@ type EmailTemplateSend = unknown & {
    */
   id?: EmailTemplateId;
   /**
-   * The template to send, by its name handle (for example `welcome-email`).
+   * The template to send, by its name handle — a workspace template (for example `welcome-email`) or a built-in `system` template (for example `bird_welcome`).
    */
   name?: TemplateName;
   /**
@@ -2629,7 +2797,7 @@ type ListEmailMessagesData = {
      */
     status?: "scheduled" | "accepted" | "processed" | "deferred" | "delivered" | "partial_failure" | "bounced" | "complained" | "rejected" | "canceled";
     /**
-     * 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`). Repeat the parameter to AND-combine several tag filters.
+     * Filter by tag. Accepts `name` to match any message carrying that tag name, or `name:value` to match a specific tag pair (e.g. `category:welcome`). Repeat the parameter to AND-combine several tag filters.
      *
      */
     tag?: Array<string>;
@@ -2798,7 +2966,7 @@ type ListSmsMessagesData = {
      */
     from?: string;
     /**
-     * Filter by tag. Accepts `name` to match any message carrying that tag name, or `name:value` to match a specific tag pair. Repeat the parameter to AND-combine several tag filters.
+     * Filter by tag. Accepts `name` to match any message carrying that tag name, or `name:value` to match a specific tag pair (e.g. `category:welcome`). Repeat the parameter to AND-combine several tag filters.
      *
      */
     tag?: Array<string>;
@@ -2860,6 +3028,11 @@ type ListWhatsAppMessagesData = {
      * Filter by business-scoped user ID (Meta identifier).
      */
     bsuid?: string;
+    /**
+     * Filter by tag. Accepts `name` to match any message carrying that tag name, or `name:value` to match a specific tag pair (e.g. `category:welcome`). Repeat the parameter to AND-combine several tag filters.
+     *
+     */
+    tag?: Array<string>;
   };
   url: "/v1/whatsapp/messages";
 };
@@ -3734,6 +3907,46 @@ declare class WhatsappTemplatesResource extends Resource {
   list(options?: RequestOptions): APIPromise<WhatsAppTemplateList>;
 }
 //#endregion
+//#region src/resources/verify.d.ts
+/** Body for `bird.verify.verifications.create` — a recipient in `to`, plus optional `options`/`metadata`. */
+type VerificationCreateParams = VerificationCreateRequest;
+/** Body for `bird.verify.verifications.check` — the recipient in `to` and the submitted `code`. */
+type VerificationCheckParams = VerificationCheckRequest;
+declare class VerificationsResource extends Resource {
+  /**
+   * Start a verification and send a one-time passcode to the recipient in `to`
+   * (a `phone_number` over SMS, an `email_address` over email, or both). Calling
+   * again for the same recipient re-sends the code after the cooldown rather than
+   * starting a second verification. The passcode is never returned — submit the
+   * recipient's entry with `check`.
+   *
+   * @example Start over SMS
+   * const verification = await bird.verify.verifications.create({
+   *   to: { phone_number: "+15551234567" },
+   * });
+   * console.log(verification.id, verification.status);
+   */
+  create(params: VerificationCreateParams, options?: RequestOptions): APIPromise<Verification>;
+  /**
+   * Check a passcode the recipient submitted. Identify the verification by the same
+   * `to` recipient used to start it — no id needed. A wrong, expired, or already-used
+   * code resolves with `success: false` and a `reason`, not an error.
+   *
+   * @example
+   * const result = await bird.verify.verifications.check({
+   *   to: { phone_number: "+15551234567" },
+   *   code: "123456",
+   * });
+   * console.log(result.success);
+   */
+  check(params: VerificationCheckParams, options?: RequestOptions): APIPromise<VerificationCheckResult>;
+}
+/** The Verify product namespace — holds the `verifications` collection. */
+declare class VerifyResource {
+  readonly verifications: VerificationsResource;
+  constructor(...args: ConstructorParameters<typeof Resource>);
+}
+//#endregion
 //#region src/resources/webhooks.d.ts
 /** A verified webhook event — discriminated on `type` (ADR-0028 wire contract). */
 type BirdWebhookEvent = WebhookEvent;
@@ -3871,6 +4084,8 @@ declare class BirdClient<const O extends BirdClientOptions = BirdClientOptions>
   readonly whatsapp: WhatsappResource;
   /** WhatsApp templates — `bird.whatsappTemplates.list(...)`. */
   readonly whatsappTemplates: WhatsappTemplatesResource;
+  /** The Verify product — `bird.verify.verifications.create(...)`, `.check(...)`. */
+  readonly verify: VerifyResource;
   /** Contacts — `bird.contacts.create(...)`, `.list(...)`, `.get(...)`, `.batch(...)`, … */
   readonly contacts: ContactsResource;
   /** Audiences — `bird.audiences.create(...)`, `.list(...)`, `.addContacts(...)`, … */
@@ -3943,5 +4158,5 @@ declare const WebhookEventType: {
 /** A known webhook event type value. */
 type WebhookEventTypeValue = (typeof WebhookEventType)[keyof typeof WebhookEventType];
 //#endregion
-export { type APIPromise, type Audience, type AudienceAddContactsParams, type AudienceContactsQuery, type AudienceCreateParams, type AudienceListQuery, type AudienceMember, type AudienceRemoveContactsParams, type AudienceUpdateParams, 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 Contact, type ContactBatchParams, type ContactCreateParams, type ContactListQuery, type ContactProperty, type ContactPropertyCreateParams, type ContactPropertyListQuery, type ContactPropertyUpdateParams, type ContactUpdateParams, type ContactUpsertResult, type CursorPage, type EmailChannelDefaults, type EmailListQuery, type EmailMessage, type EmailSendBatchParams, type EmailSendBatchResult, type EmailSendParams, type ErrorDetail, type ErrorNextAction, type PaginatedPromise, type RequestOptions, type SafeResult, type SmsListQuery, type SmsMessage, type SmsSendBatchParams, type SmsSendBatchResult, type SmsSendParams, type SmsTemplate, type SmsTemplateList, type SmsTemplateListQuery, type UnmetGate, WebhookEventType, type WebhookEventTypeValue, type WebhookHeaders, type WebhookOptions, type WhatsAppEventList, type WhatsAppMessage, type WhatsAppTemplate, type WhatsAppTemplateList, type WhatsappListEventsQuery, type WhatsappListQuery, type WhatsappSendParams, baseUrlForRegion, regionFromApiKey };
+export { type APIPromise, type Audience, type AudienceAddContactsParams, type AudienceContactsQuery, type AudienceCreateParams, type AudienceListQuery, type AudienceMember, type AudienceRemoveContactsParams, type AudienceUpdateParams, 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 Contact, type ContactBatchParams, type ContactCreateParams, type ContactListQuery, type ContactProperty, type ContactPropertyCreateParams, type ContactPropertyListQuery, type ContactPropertyUpdateParams, type ContactUpdateParams, type ContactUpsertResult, type CursorPage, type EmailChannelDefaults, type EmailListQuery, type EmailMessage, type EmailSendBatchParams, type EmailSendBatchResult, type EmailSendParams, type ErrorDetail, type ErrorNextAction, type PaginatedPromise, type RequestOptions, type SafeResult, type SmsListQuery, type SmsMessage, type SmsSendBatchParams, type SmsSendBatchResult, type SmsSendParams, type SmsTemplate, type SmsTemplateList, type SmsTemplateListQuery, type UnmetGate, type Verification, type VerificationCheckParams, type VerificationCheckResult, type VerificationCreateParams, WebhookEventType, type WebhookEventTypeValue, type WebhookHeaders, type WebhookOptions, type WhatsAppEventList, type WhatsAppMessage, type WhatsAppTemplate, type WhatsAppTemplateList, type WhatsappListEventsQuery, type WhatsappListQuery, type WhatsappSendParams, baseUrlForRegion, regionFromApiKey };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1804,6 +1804,50 @@ const getSmsTemplate = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Create a verification
+*
+* Creates a verification for a recipient and sends them a one-time passcode. Provide a recipient in `to` — an email address (verified over email), a phone number (verified over SMS), or both. If a verification is already in progress for the same recipient, that one is reused and its passcode is re-sent once the resend cooldown has elapsed, rather than starting a second verification. The response includes the verification's current state; the passcode itself is never returned. Submit the passcode the recipient enters with the check endpoint.
+*
+*/
+const createVerification = (options) => (options.client ?? client).post({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/verify/verifications",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
+* Check a verification passcode
+*
+* Checks a passcode for a recipient and returns the outcome together with the verification's current state. Identify the verification by the same `to` recipient used to create it — you do not need to store a verification id. A wrong, expired, or already-used passcode is reported in the response body, with `success` set to `false` and a `reason` such as `incorrect_code` or `expired`, rather than as an HTTP error; only a missing verification, malformed input, or rate limiting return an error status.
+*
+*/
+const createVerificationCheck = (options) => (options.client ?? client).post({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/verify/verifications/check",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
 * List WhatsApp messages
 *
 * Returns a paginated list of WhatsApp messages in the workspace, newest first.
@@ -2693,6 +2737,58 @@ var WhatsappTemplatesResource = class extends Resource {
 	}
 };
 //#endregion
+//#region src/resources/verify.ts
+var VerificationsResource = class extends Resource {
+	/**
+	* Start a verification and send a one-time passcode to the recipient in `to`
+	* (a `phone_number` over SMS, an `email_address` over email, or both). Calling
+	* again for the same recipient re-sends the code after the cooldown rather than
+	* starting a second verification. The passcode is never returned — submit the
+	* recipient's entry with `check`.
+	*
+	* @example Start over SMS
+	* const verification = await bird.verify.verifications.create({
+	*   to: { phone_number: "+15551234567" },
+	* });
+	* console.log(verification.id, verification.status);
+	*/
+	create(params, options) {
+		return this.call("POST", options, ({ signal, headers }) => createVerification({
+			client: this.client,
+			body: params,
+			headers,
+			signal
+		}));
+	}
+	/**
+	* Check a passcode the recipient submitted. Identify the verification by the same
+	* `to` recipient used to start it — no id needed. A wrong, expired, or already-used
+	* code resolves with `success: false` and a `reason`, not an error.
+	*
+	* @example
+	* const result = await bird.verify.verifications.check({
+	*   to: { phone_number: "+15551234567" },
+	*   code: "123456",
+	* });
+	* console.log(result.success);
+	*/
+	check(params, options) {
+		return this.call("POST", options, ({ signal, headers }) => createVerificationCheck({
+			client: this.client,
+			body: params,
+			headers,
+			signal
+		}));
+	}
+};
+/** The Verify product namespace — holds the `verifications` collection. */
+var VerifyResource = class {
+	verifications;
+	constructor(...args) {
+		this.verifications = new VerificationsResource(...args);
+	}
+};
+//#endregion
 //#region src/resources/webhooks.ts
 var WebhooksResource = class {
 	#secret;
@@ -2817,6 +2913,8 @@ var BirdClient = class {
 	whatsapp;
 	/** WhatsApp templates — `bird.whatsappTemplates.list(...)`. */
 	whatsappTemplates;
+	/** The Verify product — `bird.verify.verifications.create(...)`, `.check(...)`. */
+	verify;
 	/** Contacts — `bird.contacts.create(...)`, `.list(...)`, `.get(...)`, `.batch(...)`, … */
 	contacts;
 	/** Audiences — `bird.audiences.create(...)`, `.list(...)`, `.addContacts(...)`, … */
@@ -2832,9 +2930,9 @@ var BirdClient = class {
 		this.#headers = {
 			...opts.defaultHeaders,
 			Authorization: `Bearer ${opts.apiKey}`,
-			"User-Agent": `bird-sdk-js/0.6.0`,
+			"User-Agent": `bird-sdk-js/0.7.0`,
 			"Bird-Surface": "sdk-js",
-			"Bird-Version": "0.6.0"
+			"Bird-Version": "0.7.0"
 		};
 		const caller = detectCaller();
 		if (caller) this.#headers["Bird-Caller"] = caller;
@@ -2852,6 +2950,7 @@ var BirdClient = class {
 		this.smsTemplates = new SmsTemplatesResource(this.core, this.#client);
 		this.whatsapp = new WhatsappResource(this.core, this.#client);
 		this.whatsappTemplates = new WhatsappTemplatesResource(this.core, this.#client);
+		this.verify = new VerifyResource(this.core, this.#client);
 		this.contacts = new ContactsResource(this.core, this.#client);
 		this.audiences = new AudiencesResource(this.core, this.#client);
 		this.contactProperties = new ContactPropertiesResource(this.core, this.#client);