zavudev 0.19.0 → 0.21.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

@@ -16,8 +16,27 @@ module Zavudev
       sig { returns(Time) }
       attr_accessor :created_at
 
+      # Who sent the message. Needed to render a thread: `status` cannot tell the two
+      # apart, because an inbound message is also stored as `delivered`.
+      sig { returns(Zavudev::Message::Direction::TaggedSymbol) }
+      attr_accessor :direction
+
       # 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
 
@@ -106,6 +125,7 @@ module Zavudev
           id: String,
           channel: Zavudev::Channel::OrSymbol,
           created_at: Time,
+          direction: Zavudev::Message::Direction::OrSymbol,
           message_type: Zavudev::MessageType::OrSymbol,
           status: Zavudev::MessageStatus::OrSymbol,
           to: String,
@@ -129,8 +149,25 @@ module Zavudev
         # Delivery channel. Use 'auto' for intelligent routing.
         channel:,
         created_at:,
+        # Who sent the message. Needed to render a thread: `status` cannot tell the two
+        # apart, because an inbound message is also stored as `delivered`.
+        direction:,
         # 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:,
@@ -167,6 +204,7 @@ module Zavudev
             id: String,
             channel: Zavudev::Channel::TaggedSymbol,
             created_at: Time,
+            direction: Zavudev::Message::Direction::TaggedSymbol,
             message_type: Zavudev::MessageType::TaggedSymbol,
             status: Zavudev::MessageStatus::TaggedSymbol,
             to: String,
@@ -188,6 +226,25 @@ module Zavudev
       end
       def to_hash
       end
+
+      # Who sent the message. Needed to render a thread: `status` cannot tell the two
+      # apart, because an inbound message is also stored as `delivered`.
+      module Direction
+        extend Zavudev::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias { T.all(Symbol, Zavudev::Message::Direction) }
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        INBOUND = T.let(:inbound, Zavudev::Message::Direction::TaggedSymbol)
+        OUTBOUND = T.let(:outbound, Zavudev::Message::Direction::TaggedSymbol)
+
+        sig do
+          override.returns(T::Array[Zavudev::Message::Direction::TaggedSymbol])
+        end
+        def self.values
+        end
+      end
     end
   end
 end