ruby-whatsapp 0.4.0 → 0.6.1

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/subscribed_app/transport.rb

@@ -5,18 +5,19 @@ module Whatsapp
     # The one piece shared by {List}, {Subscribe}, and {Unsubscribe}: all three address
     # the same WABA-scoped edge, differing only in HTTP verb and body. Extended (not
     # included) since those classes are class-method-only.
+    #
+    # 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 `subscribed_apps` edge.
       # @raise [Error] if no WABA ID is configured.
       def edge_path(client)
-        if client.waba_id.nil? || client.waba_id.to_s.empty?
-          raise Error, "waba_id is required for subscribed apps; set it via Whatsapp.configure or Client.new(waba_id:)"
-        end
-
-        client.path_for(client.waba_id, "subscribed_apps")
+        scoped_path(client, :waba_id, "subscribed_apps", error_class: Error, purpose: "subscribed apps")
       end
     end
   end

data/lib/ruby/whatsapp/version.rb

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

data/lib/ruby/whatsapp/webhook/business_username_updates.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # A business phone number's username status changed — approved, reserved, or deleted.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+    class BusinessUsernameUpdates
+      # @!attribute [rw] display_phone_number
+      #   @return [String, nil]
+      attr_accessor :display_phone_number
+
+      # @!attribute [rw] username
+      #   @return [String, nil] Omitted when `status` is `"deleted"`.
+      attr_accessor :username
+
+      # @!attribute [rw] status
+      #   @return [String, nil] `"approved"`, `"reserved"`, or `"deleted"`.
+      attr_accessor :status
+
+      # @!attribute [r] raw
+      #   @return [Hash] The untouched `value` hash. A diagnostic escape hatch, not part
+      #     of the supported API: every attribute above is a flat top-level read, so a
+      #     single renamed key yields an all-`nil` object with no other signal. Reach for
+      #     it when a typed accessor is unexpectedly `nil`, log what you find, and treat
+      #     it as read-only: it is the object `JSON.parse` returned, not a copy.
+      attr_reader :raw
+
+      def initialize(display_phone_number: nil, status: nil, username: nil, raw: {})
+        @display_phone_number = display_phone_number
+        @username = username
+        @status = status
+        @raw = raw
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [BusinessUsernameUpdates]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            display_phone_number: data["display_phone_number"],
+            username: data["username"],
+            status: data["status"],
+            raw: data
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/change.rb

@@ -2,7 +2,7 @@
 
 module Whatsapp
   module Webhook
-    # A single `entry[].changes[]` item: `field` names which of Meta's ~19 documented
+    # A single `entry[].changes[]` item: `field` names which of Meta's 21 documented
     # webhook notification types this is, `value` is the deserialized payload for it.
     #
     # `FIELDS` is populated incrementally as each field's value class is implemented
@@ -17,6 +17,7 @@ module Whatsapp
         account_update: AccountUpdate,
         automatic_events: AutomaticEvents,
         business_capability_update: BusinessCapabilityUpdate,
+        business_username_updates: BusinessUsernameUpdates,
         history: History,
         message_template_components_update: MessageTemplateComponentsUpdate,
         message_template_quality_update: MessageTemplateQualityUpdate,
@@ -29,6 +30,7 @@ module Whatsapp
         smb_app_state_sync: SmbAppStateSync,
         smb_message_echoes: SmbMessageEchoes,
         template_category_update: TemplateCategoryUpdate,
+        user_id_update: UserIdUpdate,
         user_preferences: UserPreferences,
       }.freeze
 

data/lib/ruby/whatsapp/webhook/contact.rb

@@ -10,13 +10,33 @@ module Whatsapp
       #   @return [String, nil]
       attr_accessor :profile_name
 
+      # @!attribute [rw] username
+      #   @return [String, nil] Set only if the user has adopted a username. Read from
+      #     `profile.username`, where Meta's App Dashboard test payloads put it, falling
+      #     back to a flat top-level `username` — `user_id`/`parent_user_id` arrive flat
+      #     on this same hash and Meta publishes no reference schema for the contact
+      #     object, so both locations are read rather than betting on one.
+      attr_accessor :username
+
       # @!attribute [rw] wa_id
-      #   @return [String, nil]
+      #   @return [String, nil] Omitted once the user adopts a username, unless a
+      #     recent interaction or the contact book still allows sharing the phone number.
       attr_accessor :wa_id
 
-      def initialize(profile_name:, wa_id:)
+      # @!attribute [rw] user_id
+      #   @return [String, nil] The user's business-scoped user ID (BSUID).
+      attr_accessor :user_id
+
+      # @!attribute [rw] parent_user_id
+      #   @return [String, nil] The user's parent BSUID, present only when enrolled.
+      attr_accessor :parent_user_id
+
+      def initialize(profile_name: nil, username: nil, wa_id: nil, user_id: nil, parent_user_id: nil)
         @profile_name = profile_name
+        @username = username
         @wa_id = wa_id
+        @user_id = user_id
+        @parent_user_id = parent_user_id
       end
 
       class << self
@@ -27,7 +47,10 @@ module Whatsapp
 
           new(
             profile_name: data.dig("profile", "name"),
-            wa_id: data["wa_id"]
+            username: data.dig("profile", "username") || data["username"],
+            wa_id: data["wa_id"],
+            user_id: data["user_id"],
+            parent_user_id: data["parent_user_id"]
           )
         end
       end

data/lib/ruby/whatsapp/webhook/history/chunk.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class History
+      # A single `history[]` entry: one chunk of a chat-history sync, plus the counters
+      # that tell you how far through the sync it is.
+      class Chunk
+        # @!attribute [rw] phase
+        #   @return [Integer, nil] Which sync phase this chunk belongs to.
+        attr_accessor :phase
+
+        # @!attribute [rw] chunk_order
+        #   @return [Integer, nil] This chunk's position within its phase.
+        attr_accessor :chunk_order
+
+        # @!attribute [rw] progress
+        #   @return [Integer, nil] Percent complete, 0-100.
+        attr_accessor :progress
+
+        # @!attribute [rw] threads
+        #   @return [Array<Thread>]
+        attr_accessor :threads
+
+        def initialize(phase: nil, chunk_order: nil, progress: nil, threads: [])
+          @phase = phase
+          @chunk_order = chunk_order
+          @progress = progress
+          @threads = threads
+        end
+
+        class << self
+          # @param data [Hash, nil] A raw `history[]` entry.
+          # @return [Chunk]
+          def deserialize(data)
+            data ||= {}
+            metadata = data["metadata"] || {}
+
+            new(
+              phase: metadata["phase"],
+              chunk_order: metadata["chunk_order"],
+              progress: metadata["progress"],
+              threads: Array(data["threads"]).map { |thread_data| Thread.deserialize(thread_data) }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/history/thread.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class History
+      # One conversation within a history {Chunk}: who it is with, and the messages in it.
+      #
+      # Named for Meta's `threads[]` key. Nested under {History}, so it never shadows
+      # `::Thread` for anything outside this class.
+      class Thread
+        # @!attribute [rw] id
+        #   @return [String, nil] The thread's identifier — the user's phone number, omitted
+        #     if they had already adopted a username when the sync was requested and their
+        #     number was no longer shareable. Use {#context} to identify them instead.
+        attr_accessor :id
+
+        # @!attribute [rw] context
+        #   @return [Contact, nil] Who the thread is with (`wa_id`, `user_id`,
+        #     `parent_user_id`, `username`). Deserialized with the same
+        #     {Whatsapp::Webhook::Contact} as every other contact entry — its `username`
+        #     read already falls back to a flat key, which is where Meta puts it here, and
+        #     its `profile_name` is simply `nil` since a thread context carries no profile.
+        attr_accessor :context
+
+        # @!attribute [rw] messages
+        #   @return [Array<Message::Base>] The synced messages, dispatched by `type` like
+        #     any inbound message.
+        #
+        #     Each one also carries a `history_context.status` (its delivery state at sync
+        #     time), which is **not** modelled: it would put a history-only field on
+        #     `Message::Base`, the envelope shared by every inbound message type, where it
+        #     could never appear. Read it from {#raw} instead.
+        attr_accessor :messages
+
+        # @!attribute [r] raw
+        #   @return [Hash] The untouched thread hash, so the unmodelled per-message
+        #     `history_context` stays reachable. Read-only; not a copy.
+        attr_reader :raw
+
+        def initialize(id: nil, context: nil, messages: [], raw: {})
+          @id = id
+          @context = context
+          @messages = messages
+          @raw = raw
+        end
+
+        class << self
+          # @param data [Hash, nil] A raw `threads[]` entry.
+          # @return [Thread]
+          def deserialize(data)
+            data ||= {}
+
+            new(
+              id: data["id"],
+              context: data["context"] ? Contact.deserialize(data["context"]) : nil,
+              messages: Array(data["messages"]).map { |message_data| Message.deserialize(message_data) },
+              raw: data
+            )
+          end
+        end
+      end
+    end
+  end
+end