ruby-whatsapp 0.4.2 → 0.6.2

data/lib/ruby/whatsapp/messages/interactive/list_buttons/section.rb

@@ -14,21 +14,26 @@ module Whatsapp
           end
 
           # @!attribute [rw] title
-          #   @return [String]
+          #   @return [String, nil]
           attr_accessor :title
 
           # @!attribute [rw] rows
           #   @return [Array<Hash>]
           attr_accessor :rows
 
-          validates :title, presence: true, length: { maximum: Defaults::MAX_TITLE_LENGTH }
+          # Optional here: Meta requires a title only when the list has more than one
+          # section, which a lone Section cannot see — {ListButtons} enforces that rule.
+          validates :title, length: { maximum: Defaults::MAX_TITLE_LENGTH }, allow_nil: true
           validates :rows, presence: true, length: { minimum: Defaults::MIN_ROWS_LENGTH, maximum: Defaults::MAX_ROWS_LENGTH }
 
-          # @param title [String] The title of the section.
+          # A blank title (`""` or whitespace) is treated as absent, so it is omitted from
+          # the payload rather than sent as an empty heading.
           # @param rows [Array<Hash>] The rows in the section.
+          # @param title [String, nil] The title of the section. Required only when the list
+          #   has more than one section (enforced by {ListButtons}).
           #  @raise [ActiveModel::ValidationError] if validation fails.
-          def initialize(title:, rows:)
-            @title = title
+          def initialize(rows:, title: nil)
+            @title = title.presence
             @rows = rows
 
             validate!
@@ -47,7 +52,7 @@ module Whatsapp
             {
               title:,
               rows: serialized_rows,
-            }
+            }.compact
           end
 
         private

data/lib/ruby/whatsapp/messages/interactive/list_buttons.rb

@@ -23,6 +23,7 @@ module Whatsapp
         validates :button, presence: true, length: { maximum: Defaults::MAX_BUTTON_LENGTH }
         validates :sections, presence: true, length: { minimum: Defaults::MIN_SECTIONS_COUNT,
                                                        maximum: Defaults::MAX_SECTIONS_COUNT, }
+        validate :validate_section_titles
 
         # @param button [String] The text for the list button.
         # @param sections [Array<Hash>] The sections of the list button.
@@ -52,6 +53,17 @@ module Whatsapp
 
       private
 
+        # Meta requires `sections[].title` only once a list has more than one section, so
+        # {Section} leaves it optional and the rule lives here, where the count is known.
+        # A blank title counts as missing, matching {Section}, which omits it.
+        # @return [void]
+        def validate_section_titles
+          return if sections.blank? || sections.size <= 1
+          return if sections.all? { |section| section[:title].present? }
+
+          errors.add(:sections, "must each have a title when there is more than one section")
+        end
+
         # @return [Array<Hash>] Serialized sections.
         #   @raise [ActiveModel::ValidationError] if validation fails.
         def serialized_sections

data/lib/ruby/whatsapp/messages/interactive/request_contact_info.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Interactive
+      # Asks the recipient to share their phone number, which they hand over with one tap.
+      #
+      # The interactive-message counterpart to
+      # {Whatsapp::MessageTemplates::Button::RequestContactInfo}: use this inside the
+      # 24-hour service window, and the template button to open a conversation. Either way
+      # this is how you get a phone number back from someone who has adopted a username and
+      # reaches you only as a
+      # [BSUID](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids).
+      #
+      # The only action kind with nothing for the caller to supply — the whole payload is
+      # `{ name: "request_contact_info" }` — which is why {Interactive} marks it
+      # parameterless and stops requiring an `action:`. Compare
+      # {Whatsapp::Messages::LocationRequest}, whose action is the same shape.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+      class RequestContactInfo < Base
+        module Defaults
+          ACTION_NAME = "request_contact_info"
+        end
+
+        # @!attribute [rw] name
+        #   @return [String] Always {Defaults::ACTION_NAME}.
+        attr_accessor :name
+
+        validates :name, inclusion: { in: [Defaults::ACTION_NAME] }
+
+        # @param name [String] The action name. Defaulted, since Meta accepts exactly one
+        #   value; the keyword exists so a caller spelling out
+        #   `action: { name: "request_contact_info" }` — mirroring Meta's example payload —
+        #   still works.
+        #  @raise [ActiveModel::ValidationError] if `name` is anything else.
+        def initialize(name: Defaults::ACTION_NAME)
+          @name = name
+
+          validate!
+        end
+
+        class << self
+          # Takes a keyword splat rather than named parameters, because {Interactive} calls
+          # it as `serialize(**action)` with an empty hash for this kind.
+          # @return [Hash] Serialized representation of the request.
+          def serialize(**)
+            new(**).serialize
+          end
+        end
+
+        # @return [Hash] Serialized representation of the request — no `parameters` key,
+        #   unlike every other action kind, because there is nothing to parameterize.
+        def serialize
+          { name: }
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/messages/interactive.rb

@@ -19,6 +19,10 @@ module Whatsapp
         url_button: { klass: UrlButton, api_type: "cta_url" },
         media_carousel: { klass: MediaCarousel, api_type: "carousel" },
         product_carousel: { klass: ProductCarousel, api_type: "product_list" },
+        # The one kind whose registry key and wire value coincide — the registry exists
+        # because they usually differ, so this is not a copy-paste slip. `parameterless`
+        # marks the one kind with nothing for a caller to supply; see #validate_action.
+        request_contact_info: { klass: RequestContactInfo, api_type: "request_contact_info", parameterless: true },
       }.freeze
 
       # @!attribute [rw] type
@@ -43,16 +47,17 @@ module Whatsapp
 
       validates :type, presence: true, inclusion: { in: ACTION_TYPES.keys }
       validates :body, presence: true
-      validates :action, presence: true
+      validate :validate_action
 
       # @param type [Symbol, String] The action kind (see {ACTION_TYPES}).
       # @param body [String] The body text of the interactive message.
-      # @param action [Hash] The action content, forwarded to the action class.
+      # @param action [Hash] The action content, forwarded to the action class. Defaults to
+      #   empty, which only the parameterless `:request_contact_info` kind accepts.
       # @param header [Hash, nil] The header content (optional).
       # @param footer [Hash, nil] The footer content (optional).
-      # @param kwargs [Hash] Additional keyword arguments (e.g. :to).
+      # @param kwargs [Hash] Additional keyword arguments passed to {Base} (:to / :recipient).
       #  @raise [ActiveModel::ValidationError] if validation fails.
-      def initialize(type:, body:, action:, header: nil, footer: nil, **)
+      def initialize(type:, body:, action: {}, header: nil, footer: nil, **)
         super(**)
 
         @type = type.to_sym
@@ -87,6 +92,19 @@ module Whatsapp
         ACTION_TYPES.fetch(type)
       end
 
+      # An empty `action` is blank, so a plain presence validator would reject the one kind
+      # that legitimately has nothing to supply. Reads the registry with `[]` rather than
+      # the `fetch`-backed #action_config, so an unknown `type` falls through to the
+      # inclusion validator above instead of raising KeyError from inside a validator.
+      # @return [void]
+      def validate_action
+        config = ACTION_TYPES[type]
+        return if config.nil? || config[:parameterless]
+        return if action.present?
+
+        errors.add(:action, "can't be blank")
+      end
+
       # @return [Hash, nil] The serialized header information.
       def serialized_header
         return unless header

data/lib/ruby/whatsapp/messages/response/contacts.rb

@@ -5,18 +5,34 @@ module Whatsapp
     class Response
       class Contacts
         # @!attribute [rw] input
-        #   @return [String]
+        #   @return [String] Whatever you addressed the message to: the phone number, the
+        #     BSUID or parent BSUID, or a group ID.
         attr_accessor :input
 
         # @!attribute [rw] wa_id
-        #   @return [String]
+        #   @return [String, nil] The recipient's WhatsApp ID. Present only if the message
+        #     was sent to their phone number; omitted otherwise.
         attr_accessor :wa_id
 
+        # @!attribute [rw] user_id
+        #   @return [String, nil] The recipient's business-scoped user ID (BSUID), or parent
+        #     BSUID — Meta returns either in this one field, unlike the webhook classes,
+        #     which separate `user_id` from `parent_user_id`.
+        #
+        #     Omitted whenever the message went to a phone number, **including when both
+        #     `to` and `recipient` were supplied**, since Meta gives `to` precedence and
+        #     answers as though `recipient` had not been sent. A `nil` here therefore does
+        #     not mean the recipient has no BSUID.
+        attr_accessor :user_id
+
         # @param input [String] The input value of the contact.
-        # @param wa_id [String] The WhatsApp ID of the contact.
-        def initialize(input:, wa_id:)
+        # @param wa_id [String, nil] The WhatsApp ID of the contact, if it was addressed by
+        #   phone number.
+        # @param user_id [String, nil] The contact's BSUID, if it was addressed by one.
+        def initialize(input:, wa_id: nil, user_id: nil)
           @input = input
           @wa_id = wa_id
+          @user_id = user_id
         end
 
         class << self
@@ -26,7 +42,8 @@ module Whatsapp
           def deserialize(data)
             new(
               input: data["input"],
-              wa_id: data["wa_id"]
+              wa_id: data["wa_id"],
+              user_id: data["user_id"]
             )
           end
         end

data/lib/ruby/whatsapp/schedule/create.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Schedule
+    # Schedules an approved template to be sent to an audience at a set time.
+    #
+    # A validated instance rather than a bare class method (unlike {List}, which has
+    # nothing to check): Meta documents all six body fields as required, so a missing
+    # one fails here rather than costing a request. Nothing beyond that is checked —
+    # Meta publishes no length limits and no rule that `delivery_time` must be in the
+    # future.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/schedules-api
+    class Create
+      include ActiveModel::Validations
+      extend ResponseHandling
+      extend Transport
+
+      # @!attribute [rw] hsm_id
+      #   @return [String] The ID of the approved template to send.
+      attr_accessor :hsm_id
+
+      # @!attribute [rw] audience_id
+      #   @return [String] The ID of the audience to send it to.
+      attr_accessor :audience_id
+
+      # @!attribute [rw] waba_cs_id
+      #   @return [String] What Meta documents only as "WABA customer status ID (phone
+      #     number)"; whether that means a phone number ID or the number itself is
+      #     unverified, so it is passed through as given.
+      attr_accessor :waba_cs_id
+
+      # @!attribute [rw] name
+      #   @return [String] The schedule's name.
+      attr_accessor :name
+
+      # @!attribute [rw] description
+      #   @return [String] The schedule's description.
+      attr_accessor :description
+
+      # @!attribute [rw] delivery_time
+      #   @return [Integer] When to send, as a Unix timestamp.
+      attr_accessor :delivery_time
+
+      validates :hsm_id, :audience_id, :waba_cs_id, :name, :description, presence: true
+      validates :delivery_time, numericality: { only_integer: true }
+
+      # @param hsm_id [String] See {#hsm_id}.
+      # @param audience_id [String] See {#audience_id}.
+      # @param waba_cs_id [String] See {#waba_cs_id}.
+      # @param name [String] See {#name}.
+      # @param description [String] See {#description}.
+      # @param delivery_time [Integer] A Unix timestamp; pass `time.to_i` for a `Time`.
+      # @raise [ActiveModel::ValidationError] if a field is blank, or `delivery_time`
+      #   is not an integer.
+      def initialize(hsm_id:, audience_id:, waba_cs_id:, name:, description:, delivery_time:)
+        @hsm_id = hsm_id
+        @audience_id = audience_id
+        @waba_cs_id = waba_cs_id
+        @name = name
+        @description = description
+        @delivery_time = delivery_time
+
+        validate!
+      end
+
+      # @return [Hash] The schedule payload. Every field is documented required, so
+      #   none is ever compacted away.
+      def serialize
+        { hsm_id:, audience_id:, waba_cs_id:, name:, description:, delivery_time: }
+      end
+
+      class << self
+        # @example Send a template to an audience in one hour
+        #   Create.call(
+        #     hsm_id: "1234567890", audience_id: "2345678901", waba_cs_id: "3456789012",
+        #     name: "Black Friday", description: "Black Friday promo to VIP customers",
+        #     delivery_time: Time.now.to_i + 3600
+        #   ).id
+        # @param hsm_id [String] See {#initialize}.
+        # @param audience_id [String] See {#initialize}.
+        # @param waba_cs_id [String] See {#initialize}.
+        # @param name [String] See {#initialize}.
+        # @param description [String] See {#initialize}.
+        # @param delivery_time [Integer] See {#initialize}.
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @return [Response::Created]
+        # @raise [ActiveModel::ValidationError] if a field is blank, or `delivery_time`
+        #   is not an integer.
+        # @raise [Error] if no WABA ID is configured, or the request fails.
+        def call(hsm_id:, audience_id:, waba_cs_id:, name:, description:, delivery_time:, client: Client.new)
+          body = new(hsm_id:, audience_id:, waba_cs_id:, name:, description:, delivery_time:).serialize
+          response = client.connection.post(edge_path(client), json: body)
+
+          Response::Created.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "create schedule"))
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/schedule/list.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Schedule
+    # Lists a WABA's campaign schedules, one page at a time.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/schedules-api
+    class List
+      extend ResponseHandling
+      extend Transport
+
+      # The fields Meta documents for a schedule. Meta's default set is every one of
+      # these except `id`, so ask for it explicitly when you need it. Offered for
+      # convenience, not enforcement — {.call} does not validate `fields` against this
+      # list, so a field Meta adds later works without a gem release.
+      module Fields
+        ID = "id"
+        NAME = "name"
+        DESCRIPTION = "description"
+        DELIVERY_TIME = "delivery_time"
+        STATUS = "status"
+
+        ALL = [ID, NAME, DESCRIPTION, DELIVERY_TIME, STATUS].freeze
+      end
+
+      class << self
+        # @example Read every field, including the id the default set leaves out
+        #   List.call(fields: List::Fields::ALL)
+        # @example Fetch the next page
+        #   page = List.call(limit: 50)
+        #   List.call(limit: 50, after: page.next_cursor) if page.next_cursor
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @param fields [Array<String>, String, nil] Restrict each schedule to these
+        #   fields; see {Fields::ALL}. Omitted when nil, so Meta returns its defaults.
+        # @param limit [Integer, nil] Schedules per page; Meta accepts 1 to 100.
+        # @param after [String, nil] Cursor for the page after this one.
+        # @param before [String, nil] Cursor for the page before this one.
+        # @return [Response::Collection]
+        # @raise [Error] if no WABA ID is configured, or the request fails.
+        def call(client: Client.new, fields: nil, limit: nil, after: nil, before: nil)
+          params = { fields: fields && Array(fields).join(","), limit:, after:, before: }.compact
+          response = client.connection.get(edge_path(client), params:)
+
+          Response::Collection.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "list schedules"))
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/schedule/response/collection.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Schedule
+    module Response
+      # A page of campaign schedules: `{data, paging}`.
+      #
+      # Enumerable over its schedules, so `list.select(&:scheduled?)` reads naturally
+      # without reaching for `.data` first.
+      #
+      # `paging` reuses {Whatsapp::MessageTemplates::Response::Paging}: the Graph API
+      # cursor shape is identical, and only the cursors are kept, not the
+      # `previous`/`next` URLs. As there, paging is exposed rather than followed
+      # automatically; pass {#next_cursor} back as `after:` to fetch the next page.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/schedules-api
+      class Collection
+        include Enumerable
+
+        # @!attribute [rw] data
+        #   @return [Array<Node>]
+        attr_accessor :data
+
+        # @!attribute [rw] paging
+        #   @return [Whatsapp::MessageTemplates::Response::Paging, nil]
+        attr_accessor :paging
+
+        # @param data [Array<Node>]
+        # @param paging [Whatsapp::MessageTemplates::Response::Paging, nil]
+        def initialize(data: [], paging: nil)
+          @data = data
+          @paging = paging
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body.
+          # @return [Collection]
+          def deserialize(response)
+            response ||= {}
+
+            new(
+              data: Array(response["data"]).map { |node| Node.deserialize(node) },
+              paging: response["paging"] && MessageTemplates::Response::Paging.deserialize(response["paging"])
+            )
+          end
+        end
+
+        # @yieldparam schedule [Node]
+        # @return [Enumerator]
+        def each(&)
+          data.each(&)
+        end
+
+        # The cursor to pass as `after:` to fetch the next page.
+        # @return [String, nil]
+        def next_cursor
+          paging&.after
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/schedule/response/created.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Schedule
+    module Response
+      # The response to creating a campaign schedule: `{id}`.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/schedules-api
+      class Created
+        # @!attribute [rw] id
+        #   @return [String, nil] The new schedule's unique identifier.
+        attr_accessor :id
+
+        # @param id [String, nil]
+        def initialize(id: nil)
+          @id = id
+        end
+
+        class << self
+          # @param data [Hash, nil] The parsed response body.
+          # @return [Created]
+          def deserialize(data)
+            data ||= {}
+
+            new(id: data["id"])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/schedule/response/node.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Schedule
+    module Response
+      # One campaign schedule, as listed by {List}.
+      #
+      # Every attribute tolerates being absent: Meta returns only the fields asked for,
+      # and its default set omits `id`. `status` is kept as the raw string and never
+      # validated on the way in; compare it through the predicates or {Statuses}.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/schedules-api
+      class Node
+        # @!attribute [rw] id
+        #   @return [String, nil] The schedule's unique identifier.
+        attr_accessor :id
+
+        # @!attribute [rw] name
+        #   @return [String, nil] The schedule's name.
+        attr_accessor :name
+
+        # @!attribute [rw] description
+        #   @return [String, nil] The schedule's description.
+        attr_accessor :description
+
+        # @!attribute [rw] delivery_time
+        #   @return [Integer, nil] The scheduled delivery time, as a Unix timestamp.
+        attr_accessor :delivery_time
+
+        # @!attribute [rw] status
+        #   @return [String, nil] The raw status string Meta sent; {Statuses::ALL} lists the
+        #     documented values, and anything else is kept as-is.
+        attr_accessor :status
+
+        # @param id [String, nil]
+        # @param name [String, nil]
+        # @param description [String, nil]
+        # @param delivery_time [Integer, nil]
+        # @param status [String, nil]
+        def initialize(id: nil, name: nil, description: nil, delivery_time: nil, status: nil)
+          @id = id
+          @name = name
+          @description = description
+          @delivery_time = delivery_time
+          @status = status
+        end
+
+        class << self
+          # @param data [Hash, nil] One element of the `data` array.
+          # @return [Node]
+          def deserialize(data)
+            data ||= {}
+
+            new(
+              id: data["id"],
+              name: data["name"],
+              description: data["description"],
+              delivery_time: data["delivery_time"],
+              status: data["status"]
+            )
+          end
+        end
+
+        # @return [Boolean] Whether the schedule is still waiting for its delivery time.
+        def scheduled?
+          status == Statuses::SCHEDULED
+        end
+
+        # @return [Boolean] Whether the campaign is being sent right now.
+        def sending?
+          status == Statuses::SENDING
+        end
+
+        # @return [Boolean] Whether the campaign finished sending.
+        def completed?
+          status == Statuses::COMPLETED
+        end
+
+        # @return [Boolean] Whether the campaign failed.
+        def failed?
+          status == Statuses::FAILED
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/schedule/response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Schedule
+    # Deserializers for the responses of the `schedules` edge.
+    #
+    # Two response shapes, one per action, plus the element type of the list:
+    #
+    #   {Collection}   `{data, paging}`   List
+    #   {Created}      `{id}`             Create
+    #   {Node}         one element of `data`
+    #
+    # Every class follows the gem's `.deserialize(data)` convention and tolerates a nil
+    # or partial payload, so a field Meta stops sending cannot raise.
+    module Response
+    end
+  end
+end

data/lib/ruby/whatsapp/schedule/statuses.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Schedule
+    # The documented states of a campaign schedule.
+    #
+    # For comparison, not enforcement: {Response::Node#status} keeps whatever string
+    # Meta sends, so a status added later still round-trips.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/schedules-api
+    module Statuses
+      COMPLETED = "COMPLETED"
+      FAILED = "FAILED"
+      SCHEDULED = "SCHEDULED"
+      SENDING = "SENDING"
+
+      ALL = [COMPLETED, FAILED, SCHEDULED, SENDING].freeze
+    end
+  end
+end

data/lib/ruby/whatsapp/schedule/transport.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Schedule
+    # The one piece shared by {List} and {Create}: both address the same WABA-scoped
+    # edge, differing only in HTTP verb and body. Extended (not included) because
+    # {#edge_path} is used from class-level `.call` methods (as a private class method).
+    #
+    # The guard itself and its message live in {Whatsapp::PathBuilding}, shared with every
+    # other ID-scoped feature; what stays here is the edge this module addresses.
+    module Transport
+      include Whatsapp::PathBuilding
+
+    private
+
+      # @param client [Whatsapp::Client]
+      # @return [String] The versioned path to the `schedules` edge.
+      # @raise [Error] if no WABA ID is configured.
+      def edge_path(client)
+        scoped_path(client, :waba_id, "schedules", error_class: Error, purpose: "schedules")
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/schedule.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  # Lists and creates a WhatsApp Business Account's campaign schedules: an approved
+  # template sent to an audience at a set time.
+  #
+  # Schedules *send* templates that already exist; {Whatsapp::MessageTemplates} is what
+  # creates and manages the templates themselves. Addresses `waba_id`, not `phone_id`,
+  # like {Whatsapp::MessageTemplates} and {Whatsapp::SubscribedApp}.
+  # See `lib/ruby/whatsapp/schedule/CLAUDE.md` and `docs/schedule/README.md`.
+  # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/schedules-api
+  module Schedule
+    class Error < Whatsapp::Error; end
+  end
+end

data/lib/ruby/whatsapp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Whatsapp
-  VERSION = "0.4.2"
+  VERSION = "0.6.2"
 end