@zavudev/sdk 0.50.0 → 0.52.0

package/src/resources/invitations.ts

@@ -8,18 +8,21 @@ import { path } from '../internal/utils/path';
 
 export class Invitations extends APIResource {
   /**
-   * Create a partner invitation link for a client to connect WhatsApp. The client
-   * opens the returned `url` and connects. Set `connectionType` to choose how they
-   * connect:
+   * Create a partner invitation link for a client to connect a Meta channel. The
+   * client opens the returned `url` and authorizes with Meta; the resulting sender
+   * is created in your project when they finish, and the invitation transitions to
+   * `completed`.
    *
-   * - `whatsapp_waba` (default): the client completes Meta's embedded signup,
-   *   linking an official WhatsApp Business Account.
-   * - `whatsapp_alt`: the client links their number by scanning a QR code. Requires
-   *   the WhatsApp Alternative feature to be enabled for your team (otherwise
-   *   returns 400).
+   * `connectionType` picks the channel:
    *
-   * Either way, the resulting sender is created in your project when the client
-   * completes the flow, and the invitation transitions to `completed`.
+   * - `whatsapp_waba` (default): Meta's embedded signup links an official WhatsApp
+   *   Business Account.
+   * - `messenger`: the client picks a Facebook Page they administer; its Messenger
+   *   inbox (including Marketplace chats) is routed to Zavu.
+   *
+   * One invitation connects one channel — create one per channel to onboard a client
+   * on several. `phoneNumberId` and `allowedPhoneCountries` apply to `whatsapp_waba`
+   * only.
    *
    * @example
    * ```ts
@@ -99,8 +102,13 @@ export interface Invitation {
 
   /**
    * Current status of the partner invitation.
+   *
+   * `failed` means the client started the connection and it did not finish (they
+   * cancelled Meta's dialog, denied a permission, or abandoned the tab). A failed
+   * invitation is still usable: the same link can be retried, and it moves back to
+   * `in_progress` when the client tries again.
    */
-  status: 'pending' | 'in_progress' | 'completed' | 'expired' | 'cancelled';
+  status: 'pending' | 'in_progress' | 'completed' | 'expired' | 'cancelled' | 'failed';
 
   updatedAt: string;
 
@@ -118,13 +126,33 @@ export interface Invitation {
   completedAt?: string | null;
 
   /**
-   * How the client connects WhatsApp: `whatsapp_waba` (official Cloud API via
-   * embedded signup) or `whatsapp_alt` (QR-linked).
+   * The account the client linked, populated once the invitation is `completed`.
+   * Null before that. Use it to show the partner what was connected without fetching
+   * the sender.
+   */
+  connectedAccount?: Invitation.ConnectedAccount | null;
+
+  /**
+   * Which Meta channel the client connects: `whatsapp_waba` (official WhatsApp Cloud
+   * API via embedded signup) or `messenger` (a Facebook Page's Messenger inbox,
+   * including Marketplace chats).
+   */
+  connectionType?: 'whatsapp_waba' | 'messenger';
+
+  failedAt?: string | null;
+
+  /**
+   * Stable code for why the last attempt failed, present when `status` is `failed`.
+   * Values include `fb_cancelled` (client closed Meta's dialog), `fb_not_authorized`
+   * (permission denied), `signup_abandoned` (started but never finished),
+   * `meta_no_pages` (the client administers no Facebook Page), and `internal_error`.
+   * Treat unknown codes as a generic failure.
    */
-  connectionType?: 'whatsapp_waba' | 'whatsapp_alt';
+  failureReason?: string | null;
 
   /**
-   * ID of a pre-assigned Zavu phone number for WhatsApp registration.
+   * ID of a pre-assigned Zavu phone number for WhatsApp registration. Always null
+   * for `messenger` invitations.
    */
   phoneNumberId?: string | null;
 
@@ -138,6 +166,28 @@ export interface Invitation {
   viewedAt?: string | null;
 }
 
+export namespace Invitation {
+  /**
+   * The account the client linked, populated once the invitation is `completed`.
+   * Null before that. Use it to show the partner what was connected without fetching
+   * the sender.
+   */
+  export interface ConnectedAccount {
+    /**
+     * Provider-side identifier: the WhatsApp phone number ID, or the Facebook Page ID.
+     */
+    id: string;
+
+    channel: 'whatsapp' | 'messenger';
+
+    /**
+     * Display name of the connected account: the WhatsApp verified name, or the
+     * Facebook Page name.
+     */
+    name?: string | null;
+  }
+}
+
 export interface InvitationCreateResponse {
   invitation: Invitation;
 }
@@ -152,7 +202,8 @@ export interface InvitationCancelResponse {
 
 export interface InvitationCreateParams {
   /**
-   * ISO country codes for allowed phone numbers.
+   * ISO country codes for allowed phone numbers. Only valid when `connectionType` is
+   * `whatsapp_waba` — sending it with `messenger` returns 400.
    */
   allowedPhoneCountries?: Array<string>;
 
@@ -172,12 +223,21 @@ export interface InvitationCreateParams {
   clientPhone?: string;
 
   /**
-   * How the client connects WhatsApp. `whatsapp_waba` (default) runs Meta's embedded
-   * signup to link an official WhatsApp Business Account. `whatsapp_alt` links the
-   * number by scanning a QR code — available only to teams with the WhatsApp
-   * Alternative feature enabled.
+   * Which Meta channel the client connects, and how.
+   *
+   * - `whatsapp_waba` (default): Meta's embedded signup links an official WhatsApp
+   *   Business Account. Accepts `phoneNumberId` and `allowedPhoneCountries`.
+   * - `messenger`: the client authorizes with Facebook and picks a Facebook Page
+   *   they administer. The Page's Messenger inbox — including Marketplace chats — is
+   *   routed to Zavu. They must be an admin of at least one Page. A Page can only be
+   *   connected to one Zavu project at a time: if the client picks a Page that
+   *   another project already connected, the newer connection wins and the older one
+   *   is disconnected.
+   *
+   * One invitation connects one channel. To onboard a client on several channels,
+   * create one invitation per channel; each completes into its own sender.
    */
-  connectionType?: 'whatsapp_waba' | 'whatsapp_alt';
+  connectionType?: 'whatsapp_waba' | 'messenger';
 
   /**
    * Number of days until the invitation expires.
@@ -186,7 +246,9 @@ export interface InvitationCreateParams {
 
   /**
    * ID of a Zavu phone number to pre-assign for WhatsApp registration. If provided,
-   * the client will use this number instead of their own.
+   * the client will use this number instead of their own. Only valid when
+   * `connectionType` is `whatsapp_waba` — sending it with `messenger` returns 400,
+   * since a Facebook Page has no phone number.
    */
   phoneNumberId?: string;
 }
@@ -194,8 +256,13 @@ export interface InvitationCreateParams {
 export interface InvitationListParams extends CursorParams {
   /**
    * Current status of the partner invitation.
+   *
+   * `failed` means the client started the connection and it did not finish (they
+   * cancelled Meta's dialog, denied a permission, or abandoned the tab). A failed
+   * invitation is still usable: the same link can be retried, and it moves back to
+   * `in_progress` when the client tries again.
    */
-  status?: 'pending' | 'in_progress' | 'completed' | 'expired' | 'cancelled';
+  status?: 'pending' | 'in_progress' | 'completed' | 'expired' | 'cancelled' | 'failed';
 }
 
 export declare namespace Invitations {

package/src/resources/messages.ts

@@ -82,10 +82,30 @@ export class Messages extends APIResource {
    * - Window opens when the user messages you first
    * - Use template messages to initiate conversations outside the window
    *
-   * **Daily limits:**
+   * **Plan allowances and email billing:**
    *
-   * - Unverified accounts: 200 messages per channel per day
-   * - Complete KYC verification to increase limits to 10,000/day
+   * - WhatsApp, Telegram, Instagram and Messenger share an allowance of 2,000
+   *   messages per month on Free. Over it, sends return 429 with code
+   *   `a2p_limit_exceeded` and upgrade details; the counter resets on the 1st of
+   *   each month. Paid plans have no message caps
+   * - Email is billed from your prepaid balance in 1,000-message blocks: $0.40 per
+   *   1,000 transactional emails, $0.80 per 1,000 marketing (broadcast) emails. A
+   *   block is charged when your monthly count crosses each 1,000 boundary, and at
+   *   zero balance email sends return 402 with code `insufficient_balance`. Free
+   *   teams start with $2 of credit and additionally cap at 3,000 emails/month and
+   *   100/day. Teams on earlier plans keep their original email quotas instead
+   * - SMS and voice are billed per message from your balance on every plan
+   *
+   * **Email recipient pre-flight:** Email messages are validated automatically
+   * before dispatch. Sends that would be a guaranteed hard bounce are failed instead
+   * of sent, protecting your bounce rate: the message transitions to `failed`
+   * (visible via `GET /v1/messages/{messageId}` and the `message.failed` webhook)
+   * with `errorCode` set to `EMAIL_INVALID_RECIPIENT` (malformed address),
+   * `EMAIL_DOMAIN_NOT_FOUND` (recipient domain has no MX or A records), or
+   * `EMAIL_RECIPIENT_SUPPRESSED` (address is on your suppression list after a
+   * previous bounce or complaint). Advisory signals (role addresses, disposable
+   * domains) do not block sends — check them beforehand with
+   * `POST /v1/introspect/email`.
    *
    * @example
    * ```ts
@@ -140,17 +160,13 @@ export class Messages extends APIResource {
 export type MessagesCursor = Cursor<Message>;
 
 /**
- * Delivery channel. Use 'auto' for intelligent routing. `whatsapp_alt` is the
- * QR-linked WhatsApp channel and is only accepted for teams with the WhatsApp
- * Alternative feature enabled; the sender must have a connected whatsapp_alt
- * session.
+ * Delivery channel. Use 'auto' for intelligent routing.
  */
 export type Channel =
   | 'auto'
   | 'sms'
   | 'sms_oneway'
   | 'whatsapp'
-  | 'whatsapp_alt'
   | 'telegram'
   | 'email'
   | 'instagram'
@@ -161,10 +177,7 @@ export interface Message {
   id: string;
 
   /**
-   * Delivery channel. Use 'auto' for intelligent routing. `whatsapp_alt` is the
-   * QR-linked WhatsApp channel and is only accepted for teams with the WhatsApp
-   * Alternative feature enabled; the sender must have a connected whatsapp_alt
-   * session.
+   * Delivery channel. Use 'auto' for intelligent routing.
    */
   channel: Channel;
 
@@ -173,6 +186,20 @@ export interface Message {
   /**
    * Type of message. Non-text types are supported by WhatsApp and Telegram (varies
    * by type).
+   *
+   * `location_request` asks the recipient to share their location and is
+   * WhatsApp-only. It takes no `content` object — the prompt goes in `text` (max
+   * 1024 characters) and the button label is fixed by WhatsApp. The recipient's
+   * answer arrives as an inbound `location` message whose `content.replyToMessageId`
+   * is the ID of the request.
+   *
+   * `request_contact_info` asks the recipient to share their phone number and is
+   * WhatsApp-only. Like `location_request` it takes no `content` object — the prompt
+   * goes in `text` (max 1024 characters) and WhatsApp renders a fixed **Share
+   * Contact Info** button. The answer arrives as an inbound `contact` message. Use
+   * it to recover the phone number of a contact who adopted a WhatsApp username and
+   * is only known by their business-scoped user ID (BSUID); when they share it, Zavu
+   * automatically links the phone number to that contact.
    */
   messageType: MessageType;
 
@@ -185,6 +212,14 @@ export interface Message {
    */
   content?: MessageContent;
 
+  /**
+   * ID of the conversation (inbox thread) this message belongs to. Use it to build a
+   * direct dashboard link:
+   * `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`. Omitted only
+   * on legacy messages created before conversation threading.
+   */
+  conversationId?: string;
+
   /**
    * Zavu platform charge in USD for this message. Messaging is billed against your
    * plan's monthly limits plus usage-based overage.
@@ -449,6 +484,20 @@ export type MessageStatus =
 /**
  * Type of message. Non-text types are supported by WhatsApp and Telegram (varies
  * by type).
+ *
+ * `location_request` asks the recipient to share their location and is
+ * WhatsApp-only. It takes no `content` object — the prompt goes in `text` (max
+ * 1024 characters) and the button label is fixed by WhatsApp. The recipient's
+ * answer arrives as an inbound `location` message whose `content.replyToMessageId`
+ * is the ID of the request.
+ *
+ * `request_contact_info` asks the recipient to share their phone number and is
+ * WhatsApp-only. Like `location_request` it takes no `content` object — the prompt
+ * goes in `text` (max 1024 characters) and WhatsApp renders a fixed **Share
+ * Contact Info** button. The answer arrives as an inbound `contact` message. Use
+ * it to recover the phone number of a contact who adopted a WhatsApp username and
+ * is only known by their business-scoped user ID (BSUID); when they share it, Zavu
+ * automatically links the phone number to that contact.
  */
 export type MessageType =
   | 'text'
@@ -462,6 +511,8 @@ export type MessageType =
   | 'buttons'
   | 'list'
   | 'cta_url'
+  | 'request_contact_info'
+  | 'location_request'
   | 'reaction'
   | 'template';
 
@@ -499,13 +550,10 @@ export interface MessageReactParams {
 export interface MessageSendParams {
   /**
    * Body param: Recipient phone number in E.164 format, email address, WhatsApp
-   * business-scoped user ID (BSUID, e.g. `US.13491208655302741918`), WhatsApp group
-   * JID (`<id>@g.us`, e.g. `120363000000000000@g.us`), or numeric chat ID (for
-   * Telegram/Instagram/Messenger). A BSUID is routed to WhatsApp and sent via the
-   * `recipient` field; use it to message a contact who adopted a username and whose
-   * phone number is hidden. A group JID is only valid on the `whatsapp_alt` channel
-   * and supports text and media (image, video, audio, document, sticker, location,
-   * contact).
+   * business-scoped user ID (BSUID, e.g. `US.13491208655302741918`), or numeric chat
+   * ID (for Telegram/Instagram/Messenger). A BSUID is routed to WhatsApp and sent
+   * via the `recipient` field; use it to message a contact who adopted a username
+   * and whose phone number is hidden.
    */
   to: string;
 

package/src/resources/number-10dlc/brands.ts

@@ -115,7 +115,11 @@ export class Brands extends APIResource {
 
   /**
    * Submit a draft brand to The Campaign Registry (TCR) for vetting. The brand must
-   * be in draft status. A $35 registration fee is charged from your balance.
+   * be in draft status. TCR's one-time $4 brand registration fee is charged from
+   * your balance at submission (passed through at cost) and refunded if the carrier
+   * rejects the registration. A team that already paid this fee through the
+   * compliance flow is not charged again. Campaign registration is billed separately
+   * when a campaign is submitted.
    *
    * @example
    * ```ts

package/src/resources/number-10dlc/campaigns/campaigns.ts

@@ -117,7 +117,12 @@ export class Campaigns extends APIResource {
 
   /**
    * Submit a draft campaign for carrier review. The campaign must be in draft status
-   * and its brand must be verified.
+   * and its brand must be verified. TCR's one-time registration fee is charged from
+   * your balance at submission ($15 for standard use cases, $2 for LOW_VOLUME),
+   * passed through at cost and refunded if the carrier rejects it. Once approved,
+   * the campaign's monthly TCR fee ($10 standard, $2 LOW_VOLUME) is charged from
+   * your balance while the campaign is active — see registrationCostCents and
+   * monthlyFeeCents on the campaign object.
    *
    * @example
    * ```ts

package/src/resources/phone-numbers.ts

@@ -350,6 +350,12 @@ export interface PhoneNumberSearchAvailableParams {
    */
   countryCode: string;
 
+  /**
+   * Comma-separated capabilities the number must have: `sms`, `voice`, `mms`.
+   * Numbers missing any of them are dropped.
+   */
+  capabilities?: string;
+
   /**
    * Search for numbers containing this string.
    */