zavudev 0.19.0 → 0.20.0

data/rbi/zavudev/models/invitation.rbi

@@ -20,6 +20,11 @@ module Zavudev
       attr_accessor :expires_at
 
       # 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.
       sig { returns(Zavudev::Invitation::Status::TaggedSymbol) }
       attr_accessor :status
 
@@ -42,8 +47,23 @@ module Zavudev
       sig { returns(T.nilable(Time)) }
       attr_accessor :completed_at
 
-      # How the client connects WhatsApp: `whatsapp_waba` (official Cloud API via
-      # embedded signup).
+      # 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.
+      sig { returns(T.nilable(Zavudev::Invitation::ConnectedAccount)) }
+      attr_reader :connected_account
+
+      sig do
+        params(
+          connected_account:
+            T.nilable(Zavudev::Invitation::ConnectedAccount::OrHash)
+        ).void
+      end
+      attr_writer :connected_account
+
+      # 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).
       sig do
         returns(T.nilable(Zavudev::Invitation::ConnectionType::TaggedSymbol))
       end
@@ -56,7 +76,19 @@ module Zavudev
       end
       attr_writer :connection_type
 
-      # ID of a pre-assigned Zavu phone number for WhatsApp registration.
+      sig { returns(T.nilable(Time)) }
+      attr_accessor :failed_at
+
+      # 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.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :failure_reason
+
+      # ID of a pre-assigned Zavu phone number for WhatsApp registration. Always null
+      # for `messenger` invitations.
       sig { returns(T.nilable(String)) }
       attr_accessor :phone_number_id
 
@@ -83,7 +115,11 @@ module Zavudev
           client_name: T.nilable(String),
           client_phone: T.nilable(String),
           completed_at: T.nilable(Time),
+          connected_account:
+            T.nilable(Zavudev::Invitation::ConnectedAccount::OrHash),
           connection_type: Zavudev::Invitation::ConnectionType::OrSymbol,
+          failed_at: T.nilable(Time),
+          failure_reason: T.nilable(String),
           phone_number_id: T.nilable(String),
           sender_id: T.nilable(String),
           started_at: T.nilable(Time),
@@ -97,6 +133,11 @@ module Zavudev
         created_at:,
         expires_at:,
         # 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:,
         updated_at:,
         # Full URL to share with the client.
@@ -105,10 +146,23 @@ module Zavudev
         client_name: nil,
         client_phone: nil,
         completed_at: nil,
-        # How the client connects WhatsApp: `whatsapp_waba` (official Cloud API via
-        # embedded signup).
+        # 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.
+        connected_account: nil,
+        # 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).
         connection_type: nil,
-        # ID of a pre-assigned Zavu phone number for WhatsApp registration.
+        failed_at: nil,
+        # 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.
+        failure_reason: nil,
+        # ID of a pre-assigned Zavu phone number for WhatsApp registration. Always null
+        # for `messenger` invitations.
         phone_number_id: nil,
         # ID of the sender created when invitation is completed.
         sender_id: nil,
@@ -131,7 +185,10 @@ module Zavudev
             client_name: T.nilable(String),
             client_phone: T.nilable(String),
             completed_at: T.nilable(Time),
+            connected_account: T.nilable(Zavudev::Invitation::ConnectedAccount),
             connection_type: Zavudev::Invitation::ConnectionType::TaggedSymbol,
+            failed_at: T.nilable(Time),
+            failure_reason: T.nilable(String),
             phone_number_id: T.nilable(String),
             sender_id: T.nilable(String),
             started_at: T.nilable(Time),
@@ -143,6 +200,11 @@ module Zavudev
       end
 
       # 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.
       module Status
         extend Zavudev::Internal::Type::Enum
 
@@ -156,6 +218,7 @@ module Zavudev
         COMPLETED = T.let(:completed, Zavudev::Invitation::Status::TaggedSymbol)
         EXPIRED = T.let(:expired, Zavudev::Invitation::Status::TaggedSymbol)
         CANCELLED = T.let(:cancelled, Zavudev::Invitation::Status::TaggedSymbol)
+        FAILED = T.let(:failed, Zavudev::Invitation::Status::TaggedSymbol)
 
         sig do
           override.returns(T::Array[Zavudev::Invitation::Status::TaggedSymbol])
@@ -164,8 +227,97 @@ module Zavudev
         end
       end
 
-      # How the client connects WhatsApp: `whatsapp_waba` (official Cloud API via
-      # embedded signup).
+      class ConnectedAccount < Zavudev::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Zavudev::Invitation::ConnectedAccount,
+              Zavudev::Internal::AnyHash
+            )
+          end
+
+        # Provider-side identifier: the WhatsApp phone number ID, or the Facebook Page ID.
+        sig { returns(String) }
+        attr_accessor :id
+
+        sig do
+          returns(Zavudev::Invitation::ConnectedAccount::Channel::TaggedSymbol)
+        end
+        attr_accessor :channel
+
+        # Display name of the connected account: the WhatsApp verified name, or the
+        # Facebook Page name.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :name
+
+        # 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.
+        sig do
+          params(
+            id: String,
+            channel: Zavudev::Invitation::ConnectedAccount::Channel::OrSymbol,
+            name: T.nilable(String)
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # Provider-side identifier: the WhatsApp phone number ID, or the Facebook Page ID.
+          id:,
+          channel:,
+          # Display name of the connected account: the WhatsApp verified name, or the
+          # Facebook Page name.
+          name: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              id: String,
+              channel:
+                Zavudev::Invitation::ConnectedAccount::Channel::TaggedSymbol,
+              name: T.nilable(String)
+            }
+          )
+        end
+        def to_hash
+        end
+
+        module Channel
+          extend Zavudev::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(Symbol, Zavudev::Invitation::ConnectedAccount::Channel)
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          WHATSAPP =
+            T.let(
+              :whatsapp,
+              Zavudev::Invitation::ConnectedAccount::Channel::TaggedSymbol
+            )
+          MESSENGER =
+            T.let(
+              :messenger,
+              Zavudev::Invitation::ConnectedAccount::Channel::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Zavudev::Invitation::ConnectedAccount::Channel::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+
+      # 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).
       module ConnectionType
         extend Zavudev::Internal::Type::Enum
 
@@ -178,6 +330,8 @@ module Zavudev
             :whatsapp_waba,
             Zavudev::Invitation::ConnectionType::TaggedSymbol
           )
+        MESSENGER =
+          T.let(:messenger, Zavudev::Invitation::ConnectionType::TaggedSymbol)
 
         sig do
           override.returns(

data/rbi/zavudev/models/invitation_create_params.rbi

@@ -11,7 +11,8 @@ module Zavudev
           T.any(Zavudev::InvitationCreateParams, Zavudev::Internal::AnyHash)
         end
 
-      # 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.
       sig { returns(T.nilable(T::Array[String])) }
       attr_reader :allowed_phone_countries
 
@@ -39,8 +40,19 @@ module Zavudev
       sig { params(client_phone: String).void }
       attr_writer :client_phone
 
-      # How the client connects WhatsApp. `whatsapp_waba` (default) runs Meta's embedded
-      # signup to link an official WhatsApp Business Account.
+      # 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.
       sig do
         returns(
           T.nilable(Zavudev::InvitationCreateParams::ConnectionType::OrSymbol)
@@ -64,7 +76,9 @@ module Zavudev
       attr_writer :expires_in_days
 
       # 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.
       sig { returns(T.nilable(String)) }
       attr_reader :phone_number_id
 
@@ -85,7 +99,8 @@ module Zavudev
         ).returns(T.attached_class)
       end
       def self.new(
-        # 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.
         allowed_phone_countries: nil,
         # Email of the client being invited.
         client_email: nil,
@@ -93,13 +108,26 @@ module Zavudev
         client_name: nil,
         # Phone number of the client in E.164 format.
         client_phone: nil,
-        # How the client connects WhatsApp. `whatsapp_waba` (default) runs Meta's embedded
-        # signup to link an official WhatsApp Business Account.
+        # 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.
         connection_type: nil,
         # Number of days until the invitation expires.
         expires_in_days: nil,
         # 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.
         phone_number_id: nil,
         request_options: {}
       )
@@ -123,8 +151,19 @@ module Zavudev
       def to_hash
       end
 
-      # How the client connects WhatsApp. `whatsapp_waba` (default) runs Meta's embedded
-      # signup to link an official WhatsApp Business Account.
+      # 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.
       module ConnectionType
         extend Zavudev::Internal::Type::Enum
 
@@ -139,6 +178,11 @@ module Zavudev
             :whatsapp_waba,
             Zavudev::InvitationCreateParams::ConnectionType::TaggedSymbol
           )
+        MESSENGER =
+          T.let(
+            :messenger,
+            Zavudev::InvitationCreateParams::ConnectionType::TaggedSymbol
+          )
 
         sig do
           override.returns(

data/rbi/zavudev/models/invitation_list_params.rbi

@@ -24,6 +24,11 @@ module Zavudev
       attr_writer :limit
 
       # 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.
       sig do
         returns(T.nilable(Zavudev::InvitationListParams::Status::OrSymbol))
       end
@@ -46,6 +51,11 @@ module Zavudev
         cursor: nil,
         limit: nil,
         # 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: nil,
         request_options: {}
       )
@@ -65,6 +75,11 @@ module Zavudev
       end
 
       # 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.
       module Status
         extend Zavudev::Internal::Type::Enum
 
@@ -85,6 +100,8 @@ module Zavudev
           T.let(:expired, Zavudev::InvitationListParams::Status::TaggedSymbol)
         CANCELLED =
           T.let(:cancelled, Zavudev::InvitationListParams::Status::TaggedSymbol)
+        FAILED =
+          T.let(:failed, Zavudev::InvitationListParams::Status::TaggedSymbol)
 
         sig do
           override.returns(

data/rbi/zavudev/models/message.rbi

@@ -18,6 +18,20 @@ module Zavudev
 
       # 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.
       sig { returns(Zavudev::MessageType::TaggedSymbol) }
       attr_accessor :message_type
 
@@ -131,6 +145,20 @@ module Zavudev
         created_at:,
         # 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.
         message_type:,
         status:,
         to:,

data/rbi/zavudev/models/message_type.rbi

@@ -4,6 +4,20 @@ module Zavudev
   module Models
     # 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.
     module MessageType
       extend Zavudev::Internal::Type::Enum
 
@@ -21,6 +35,10 @@ module Zavudev
       BUTTONS = T.let(:buttons, Zavudev::MessageType::TaggedSymbol)
       LIST = T.let(:list, Zavudev::MessageType::TaggedSymbol)
       CTA_URL = T.let(:cta_url, Zavudev::MessageType::TaggedSymbol)
+      REQUEST_CONTACT_INFO =
+        T.let(:request_contact_info, Zavudev::MessageType::TaggedSymbol)
+      LOCATION_REQUEST =
+        T.let(:location_request, Zavudev::MessageType::TaggedSymbol)
       REACTION = T.let(:reaction, Zavudev::MessageType::TaggedSymbol)
       TEMPLATE = T.let(:template, Zavudev::MessageType::TaggedSymbol)
 

data/rbi/zavudev/models/phone_number_pricing.rbi

@@ -8,7 +8,9 @@ module Zavudev
           T.any(Zavudev::PhoneNumberPricing, Zavudev::Internal::AnyHash)
         end
 
-      # Whether this number qualifies for the free first US number offer.
+      # Whether this number qualifies as the plan-included US number on paid plans. The
+      # benefit is one per account: it is never offered again once claimed, not even
+      # after the number is released.
       sig { returns(T.nilable(T::Boolean)) }
       attr_reader :is_free_eligible
 
@@ -37,7 +39,9 @@ module Zavudev
         ).returns(T.attached_class)
       end
       def self.new(
-        # Whether this number qualifies for the free first US number offer.
+        # Whether this number qualifies as the plan-included US number on paid plans. The
+        # benefit is one per account: it is never offered again once claimed, not even
+        # after the number is released.
         is_free_eligible: nil,
         # Monthly price in USD.
         monthly_price: nil,

data/rbi/zavudev/models/phone_number_search_available_params.rbi

@@ -18,6 +18,14 @@ module Zavudev
       sig { returns(String) }
       attr_accessor :country_code
 
+      # Comma-separated capabilities the number must have: `sms`, `voice`, `mms`.
+      # Numbers missing any of them are dropped.
+      sig { returns(T.nilable(String)) }
+      attr_reader :capabilities
+
+      sig { params(capabilities: String).void }
+      attr_writer :capabilities
+
       # Search for numbers containing this string.
       sig { returns(T.nilable(String)) }
       attr_reader :contains
@@ -42,6 +50,7 @@ module Zavudev
       sig do
         params(
           country_code: String,
+          capabilities: String,
           contains: String,
           limit: Integer,
           type: Zavudev::PhoneNumberType::OrSymbol,
@@ -51,6 +60,9 @@ module Zavudev
       def self.new(
         # Two-letter ISO country code.
         country_code:,
+        # Comma-separated capabilities the number must have: `sms`, `voice`, `mms`.
+        # Numbers missing any of them are dropped.
+        capabilities: nil,
         # Search for numbers containing this string.
         contains: nil,
         # Maximum number of results to return.
@@ -65,6 +77,7 @@ module Zavudev
         override.returns(
           {
             country_code: String,
+            capabilities: String,
             contains: String,
             limit: Integer,
             type: Zavudev::PhoneNumberType::OrSymbol,

data/rbi/zavudev/models/sender.rbi

@@ -16,6 +16,16 @@ module Zavudev
       sig { returns(String) }
       attr_accessor :phone_number
 
+      # Channels this sender can actually send on right now, computed from its
+      # configuration. Empty means the sender cannot send or receive anything yet: a
+      # phoneNumber alone does not enable SMS or voice. Check this rather than inferring
+      # capability from phoneNumber or emailAddress.
+      sig { returns(T.nilable(T::Array[String])) }
+      attr_reader :channels
+
+      sig { params(channels: T::Array[String]).void }
+      attr_writer :channels
+
       sig { returns(T.nilable(Time)) }
       attr_reader :created_at
 
@@ -78,6 +88,7 @@ module Zavudev
           id: String,
           name: String,
           phone_number: String,
+          channels: T::Array[String],
           created_at: Time,
           email_address: String,
           email_catch_all_enabled: T::Boolean,
@@ -93,6 +104,11 @@ module Zavudev
         name:,
         # Phone number in E.164 format.
         phone_number:,
+        # Channels this sender can actually send on right now, computed from its
+        # configuration. Empty means the sender cannot send or receive anything yet: a
+        # phoneNumber alone does not enable SMS or voice. Check this rather than inferring
+        # capability from phoneNumber or emailAddress.
+        channels: nil,
         created_at: nil,
         # From-address for the email channel, if configured.
         email_address: nil,
@@ -119,6 +135,7 @@ module Zavudev
             id: String,
             name: String,
             phone_number: String,
+            channels: T::Array[String],
             created_at: Time,
             email_address: String,
             email_catch_all_enabled: T::Boolean,