blueticks 1.1.2 → 2.1.1

data/lib/blueticks/resources/contacts.rb

@@ -2,25 +2,32 @@
 
 require_relative "../base_resource"
 require_relative "../types/contacts"
-require_relative "../types/page"
+require_relative "../types/groups"
+require_relative "../types/paginated"
 
 module Blueticks
   module Resources
     class ContactsResource < BaseResource
-      # Search the user's WhatsApp contacts. Cursor-paginated.
-      def list(query: nil, limit: nil, cursor: nil)
+      # List contacts.
+      #
+      # List WhatsApp contacts known to the connected engine. Offset-paginated.
+      def list(search_token: nil, include_archive: nil, skip: nil, limit: nil)
         params = {}
-        params["query"] = query unless query.nil?
+        params["searchToken"] = search_token unless search_token.nil?
+        params["includeArchive"] = include_archive unless include_archive.nil?
+        params["skip"] = skip unless skip.nil?
         params["limit"] = limit unless limit.nil?
-        params["cursor"] = cursor unless cursor.nil?
-        data = client.request("GET", "/v1/contacts", params: params.empty? ? nil : params)
-        Types::Page.from_hash(data, item_type: Types::WhatsAppContact)
+        env = client.request("GET", "/v1/contacts", params: params.empty? ? nil : params)
+        Types::PaginatedPage.from_hash(env, item_type: Types::WhatsAppContact)
       end
 
-      # Retrieve the CDN URL for a contact's profile picture.
-      def get_profile_picture(chat_id)
-        data = client.request("GET", "/v1/contacts/#{chat_id}/profile_picture")
-        Types::ProfilePicture.from_hash(data)
+      # List groups in common.
+      #
+      # List the groups the authenticated user shares with the given contact.
+      # Offset-paginated (GroupListItem rows).
+      def common_groups(contact_id)
+        env = client.request("GET", "/v1/contacts/#{contact_id}/common_groups")
+        Types::PaginatedPage.from_hash(env, item_type: Types::GroupListItem)
       end
     end
   end

data/lib/blueticks/resources/engines.rb

@@ -1,31 +1,24 @@
 # frozen_string_literal: true
 
 require_relative "../base_resource"
+require_relative "../errors"
 require_relative "../types/engines"
 
 module Blueticks
   module Resources
     class EnginesResource < BaseResource
-      # Current connection status of the user's WhatsApp engine.
-      def status
-        data = client.request("GET", "/v1/engines")
-        Types::EngineStatus.from_hash(data)
-      end
-
-      # Authenticated WhatsApp account profile (phone, pushname, platform).
-      def me
-        data = client.request("GET", "/v1/engines/me")
-        Types::WhatsAppMe.from_hash(data)
-      end
-
-      # Force the engine to log out of WhatsApp Web.
-      def logout
-        client.request("POST", "/v1/engines/logout")
-      end
+      # List engines.
+      #
+      # List the WhatsApp engines connected to the workspace. Returns an Array of
+      # Engine (empty when no engine is paired) — this endpoint is not paginated.
+      def list
+        env = client.request("GET", "/v1/engines")
+        data = env.is_a?(Hash) ? env["data"] : nil
+        unless data.is_a?(Array)
+          raise Errors::ValidationError.new(message: "Expected array `data` in engines.list response")
+        end
 
-      # Force the engine's WhatsApp Web tab to reload.
-      def reload
-        client.request("POST", "/v1/engines/reload")
+        data.map { |item| Types::Engine.from_hash(item) }
       end
     end
   end

data/lib/blueticks/resources/groups.rb

@@ -2,64 +2,105 @@
 
 require_relative "../base_resource"
 require_relative "../types/groups"
+require_relative "../types/paginated"
 
 module Blueticks
   module Resources
     class GroupsResource < BaseResource
+      # List groups.
+      #
+      # List the groups the connected WhatsApp engine sees. Offset-paginated
+      # (GroupListItem rows), with an optional case-insensitive name search via
+      # `search_token`.
+      def list(search_token: nil, include_archive: nil, skip: nil, limit: nil)
+        params = {}
+        params["searchToken"] = search_token unless search_token.nil?
+        params["includeArchive"] = include_archive unless include_archive.nil?
+        params["skip"] = skip unless skip.nil?
+        params["limit"] = limit unless limit.nil?
+        env = client.request("GET", "/v1/groups", params: params.empty? ? nil : params)
+        Types::PaginatedPage.from_hash(env, item_type: Types::GroupListItem)
+      end
+
       # Create a new group with an initial participant list.
       def create(name:, participants:)
-        data = client.request("POST", "/v1/groups",
-                              body: { "name" => name, "participants" => participants })
-        Types::Group.from_hash(data)
+        env = client.request("POST", "/v1/groups",
+                             body: { "name" => name, "participants" => participants })
+        Types::Group.from_hash(env && env["data"])
       end
 
-      # Retrieve group metadata by JID.
-      def get(group_id)
-        data = client.request("GET", "/v1/groups/#{group_id}")
-        Types::Group.from_hash(data)
+      # Retrieve group metadata by id. Pass `include: "participants"` to embed
+      # the participant list.
+      def retrieve(group_id, include: nil)
+        params = include.nil? ? nil : { "include" => include }
+        env = client.request("GET", "/v1/groups/#{group_id}", params: params)
+        Types::Group.from_hash(env && env["data"])
       end
 
-      # Rename the group and/or update admin-only settings.
+      # Rename the group and/or update admin-only settings. `settings` is a hash
+      # using the API's wire keys (announce, restrict, editInfoAdminsOnly,
+      # description).
       def update(group_id, name: nil, settings: nil)
         body = {}
         body["name"] = name unless name.nil?
         body["settings"] = settings unless settings.nil?
-        data = client.request("PATCH", "/v1/groups/#{group_id}", body: body)
-        Types::Group.from_hash(data)
+        env = client.request("PATCH", "/v1/groups/#{group_id}", body: body)
+        Types::Group.from_hash(env && env["data"])
       end
 
-      # Add a participant to the group by chat_id (JID) or +E.164 phone.
-      def add_member(group_id, chat_id:)
-        data = client.request("POST", "/v1/groups/#{group_id}/members",
-                              body: { "chat_id" => chat_id })
-        Types::Group.from_hash(data)
+      # Add members to the group by chat id (JID / +E.164) and/or a list of
+      # participants.
+      def add_members(group_id, chat_id: nil, participants: nil)
+        body = {}
+        body["chatId"] = chat_id unless chat_id.nil?
+        body["participants"] = participants unless participants.nil?
+        env = client.request("POST", "/v1/groups/#{group_id}/members", body: body)
+        Types::Group.from_hash(env && env["data"])
       end
 
       # Remove a participant from the group.
       def remove_member(group_id, chat_id)
-        data = client.request("DELETE", "/v1/groups/#{group_id}/members/#{chat_id}")
-        Types::Group.from_hash(data)
+        env = client.request("DELETE", "/v1/groups/#{group_id}/members/#{chat_id}")
+        Types::Group.from_hash(env && env["data"])
       end
 
       # Grant admin privileges to a group member.
       def promote_admin(group_id, chat_id)
-        data = client.request("POST", "/v1/groups/#{group_id}/members/#{chat_id}/admin")
-        Types::Group.from_hash(data)
+        env = client.request("POST", "/v1/groups/#{group_id}/members/#{chat_id}/admin")
+        Types::Group.from_hash(env && env["data"])
       end
 
       # Revoke admin privileges from a group member.
       def demote_admin(group_id, chat_id)
-        data = client.request("DELETE", "/v1/groups/#{group_id}/members/#{chat_id}/admin")
-        Types::Group.from_hash(data)
+        env = client.request("DELETE", "/v1/groups/#{group_id}/members/#{chat_id}/admin")
+        Types::Group.from_hash(env && env["data"])
+      end
+
+      # Replace the group picture. `file_data_url` is a base64 data URL, or pass
+      # a hosted `url`.
+      def set_picture(group_id, file_data_url: nil, url: nil, file_name: nil, file_mime_type: nil)
+        body = {}
+        body["fileDataUrl"] = file_data_url unless file_data_url.nil?
+        body["url"] = url unless url.nil?
+        body["fileName"] = file_name unless file_name.nil?
+        body["fileMimeType"] = file_mime_type unless file_mime_type.nil?
+        env = client.request("PUT", "/v1/groups/#{group_id}/picture", body: body)
+        Types::Group.from_hash(env && env["data"])
+      end
+
+      # Get the current group picture as a short-lived WhatsApp CDN `url`, or
+      # `url: nil` when the group has none. Requires `groups:read`.
+      def get_picture(group_id)
+        env = client.request("GET", "/v1/groups/#{group_id}/picture")
+        Types::GroupPicture.from_hash(env && env["data"])
       end
 
-      # Replace the group picture. `file_data_url` is a base64 data URL (PNG/JPEG, <=20 MiB).
-      def set_picture(group_id, file_data_url:, file_name: nil, file_mime_type: nil)
-        body = { "file_data_url" => file_data_url }
-        body["file_name"] = file_name unless file_name.nil?
-        body["file_mime_type"] = file_mime_type unless file_mime_type.nil?
-        data = client.request("PUT", "/v1/groups/#{group_id}/picture", body: body)
-        Types::Group.from_hash(data)
+      # Remove the group picture. Gateway (Baileys) engine only: a
+      # Chrome-extension-only account gets 501 `unsupported_command`. Requires
+      # `groups:write`.
+      def remove_picture(group_id)
+        env = client.request("DELETE", "/v1/groups/#{group_id}/picture")
+        Types::GroupPictureRemoved.from_hash(env && env["data"])
       end
 
       # Leave the group as the authenticated identity. Idempotent (204).

data/lib/blueticks/resources/identity.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../base_resource"
+require_relative "../types/identity"
+
+module Blueticks
+  module Resources
+    class IdentityResource < BaseResource
+      # Resolve an identity.
+      #
+      # Maps a WhatsApp JID (phone, `@lid` or group) to its canonical form and
+      # aliases. Requires the `contacts:read` scope.
+      def retrieve(id)
+        env = client.request("GET", "/v1/identity/#{id}")
+        Types::Identity.from_hash(env && env["data"])
+      end
+
+      # Resolve identities (batch).
+      #
+      # Resolves many JIDs in one call. Requires the `contacts:read` scope.
+      def resolve_batch(ids:)
+        env = client.request("POST", "/v1/identity/resolve", body: { "ids" => ids })
+        Types::IdentityBatch.from_hash(env && env["data"])
+      end
+    end
+  end
+end

data/lib/blueticks/resources/latest_chats.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "../base_resource"
+require_relative "../types/latest_chats"
+
+module Blueticks
+  module Resources
+    class LatestChatsResource < BaseResource
+      # Get latest chats & messages.
+      #
+      # Returns the most recent chats, each with its latest messages, in one
+      # call. Requires the `chats:read` scope.
+      def retrieve(number_of_chats: nil, number_of_messages: nil)
+        params = {}
+        params["numberOfChats"] = number_of_chats unless number_of_chats.nil?
+        params["numberOfMessages"] = number_of_messages unless number_of_messages.nil?
+        env = client.request("GET", "/v1/latest-chats", params: params.empty? ? nil : params)
+        Types::LatestChats.from_hash(env && env["data"])
+      end
+    end
+  end
+end

data/lib/blueticks/resources/messages.rb

@@ -2,46 +2,142 @@
 
 require_relative "../base_resource"
 require_relative "../types/messages"
-require_relative "../types/page"
+require_relative "../types/ok_result"
+require_relative "../types/paginated"
 
 module Blueticks
   module Resources
     class MessagesResource < BaseResource
-      # Send a message immediately, or schedule one for later with `send_at:`.
-      #
-      # @param to [String] WhatsApp chat-id or phone number
-      # @param text [String, nil] Plain-text message body
-      # @param media_url [String, nil] Public URL to media to attach
-      # @param media_caption [String, nil] Caption for media
-      # @param send_at [String, nil] ISO 8601 timestamp to schedule
-      # @param from [String, nil] Multi-number engine identifier
-      # @param idempotency_key [String, nil] Optional idempotency key
-      # @return [Blueticks::Types::Message]
-      def send(to:, text: nil, media_url: nil, media_caption: nil, send_at: nil,
-               from: nil, idempotency_key: nil)
-        body = { "to" => to }
-        body["text"] = text unless text.nil?
-        body["media_url"] = media_url unless media_url.nil?
-        body["media_caption"] = media_caption unless media_caption.nil?
-        body["send_at"] = send_at unless send_at.nil?
-        body["from"] = from unless from.nil?
-        data = client.request("POST", "/v1/messages", body: body, idempotency_key: idempotency_key)
-        Types::Message.from_hash(data)
+      # Query messages from the WhatsApp store, newest first. Offset-paginated
+      # (PublicMessage rows). `message_types` is an Array of wire message types
+      # (e.g. `%w[chat image]`). `query_any` is an Array of keywords matched with OR
+      # semantics; `mime`, `filename_contains`, `has_media` and `sender` narrow the
+      # result further.
+      def list(chat_id: nil, search_token: nil, order: nil, since: nil, until_: nil,
+               message_types: nil, load_from_phone_if_needed: nil,
+               include_media_content: nil, skip: nil, limit: nil,
+               query_any: nil, mime: nil, filename_contains: nil, has_media: nil, sender: nil)
+        params = {}
+        params["chatId"] = chat_id unless chat_id.nil?
+        params["searchToken"] = search_token unless search_token.nil?
+        params["order"] = order unless order.nil?
+        params["since"] = since unless since.nil?
+        params["until"] = until_ unless until_.nil?
+        params["messageTypes"] = message_types.join(",") if message_types && !message_types.empty?
+        params["loadFromPhoneIfNeeded"] = load_from_phone_if_needed unless load_from_phone_if_needed.nil?
+        params["includeMediaContent"] = include_media_content unless include_media_content.nil?
+        params["skip"] = skip unless skip.nil?
+        params["limit"] = limit unless limit.nil?
+        params["queryAny"] = query_any unless query_any.nil? || query_any.empty?
+        params["mime"] = mime unless mime.nil?
+        params["filenameContains"] = filename_contains unless filename_contains.nil?
+        params["hasMedia"] = has_media unless has_media.nil?
+        params["sender"] = sender unless sender.nil?
+        env = client.request("GET", "/v1/messages", params: params.empty? ? nil : params)
+        Types::PaginatedPage.from_hash(env, item_type: Types::PublicMessage)
+      end
+
+      # Retrieve a single store message by its serialized wire key. Pass
+      # `chat_id` to scope the lookup.
+      def retrieve(wa_message_key, chat_id: nil)
+        params = chat_id.nil? ? nil : { "chatId" => chat_id }
+        env = client.request("GET", "/v1/messages/#{wa_message_key}", params: params)
+        Types::PublicMessage.from_hash(env && env["data"])
       end
 
-      # Retrieve a single message by id.
-      def get(message_id)
-        data = client.request("GET", "/v1/messages/#{message_id}")
-        Types::Message.from_hash(data)
+      # Get delivery acknowledgement for a single message.
+      def get_ack(wa_message_key, chat_id: nil)
+        params = chat_id.nil? ? nil : { "chatId" => chat_id }
+        env = client.request("GET", "/v1/messages/ack/#{wa_message_key}", params: params)
+        Types::MessageAck.from_hash(env && env["data"])
       end
 
-      # List messages sent through the API, newest first. Cursor-paginated.
-      def list(limit: nil, cursor: nil)
+      # Batch get delivery status for up to 200 sent messages. Offset-paginated
+      # (BatchAckEntry rows).
+      def batch_acks(message_keys:, chat_id: nil)
+        body = { "messageKeys" => message_keys }
+        body["chatId"] = chat_id unless chat_id.nil?
+        env = client.request("POST", "/v1/messages/acks", body: body)
+        Types::PaginatedPage.from_hash(env, item_type: Types::BatchAckEntry)
+      end
+
+      # Ask the engine to pull older history from the connected phone.
+      #
+      # `pages` (1-10, default 1) is how many older pages to pull in one call;
+      # `until_date` (ISO 8601 string or epoch seconds/ms) stops paging once the
+      # oldest loaded message is at/before that date.
+      def load_older(chat_id, pages: nil, until_date: nil)
+        body = {}
+        body["pages"] = pages unless pages.nil?
+        body["until_date"] = until_date unless until_date.nil?
+        env = client.request("POST", "/v1/messages/load_older/#{chat_id}", body: body.empty? ? nil : body)
+        Types::LoadOlderResult.from_hash(env && env["data"])
+      end
+
+      # Fetch media (URL and/or base64 bytes) for a message.
+      def get_media(wa_message_key, chat_id: nil, max_attempts: nil)
         params = {}
-        params["limit"] = limit unless limit.nil?
-        params["cursor"] = cursor unless cursor.nil?
-        data = client.request("GET", "/v1/messages", params: params.empty? ? nil : params)
-        Types::Page.from_hash(data, item_type: Types::Message)
+        params["chatId"] = chat_id unless chat_id.nil?
+        params["maxAttempts"] = max_attempts unless max_attempts.nil?
+        env = client.request("GET", "/v1/messages/media/#{wa_message_key}",
+                             params: params.empty? ? nil : params)
+        Types::Media.from_hash(env && env["data"])
+      end
+
+      # Pin a message. Optional `duration` (seconds) sets the pin TTL.
+      def pin(wa_message_key, chat_id: nil, duration: nil)
+        params = chat_id.nil? ? nil : { "chatId" => chat_id }
+        body = {}
+        body["duration"] = duration unless duration.nil?
+        env = client.request("POST", "/v1/messages/pin/#{wa_message_key}", params: params, body: body)
+        Types::OkResult.from_hash(env && env["data"])
+      end
+
+      # Unpin a message.
+      def unpin(wa_message_key, chat_id: nil)
+        params = chat_id.nil? ? nil : { "chatId" => chat_id }
+        env = client.request("POST", "/v1/messages/unpin/#{wa_message_key}", params: params)
+        Types::OkResult.from_hash(env && env["data"])
+      end
+
+      # List the pinned messages in a chat. Offset-paginated (PinnedMessage rows).
+      def pinned(chat_id)
+        env = client.request("GET", "/v1/messages/pinned/#{chat_id}")
+        Types::PaginatedPage.from_hash(env, item_type: Types::PinnedMessage)
+      end
+
+      # React to a message. Pass an empty `emoji` string to remove a reaction.
+      def react(wa_message_key, emoji:, chat_id: nil)
+        params = chat_id.nil? ? nil : { "chatId" => chat_id }
+        env = client.request("POST", "/v1/messages/reactions/#{wa_message_key}",
+                             params: params, body: { "emoji" => emoji })
+        Types::OkResult.from_hash(env && env["data"])
+      end
+
+      # Send a message immediately to a chat (direct dispatch — no queue row is
+      # persisted for the wait; the response carries the WhatsApp wire key). The
+      # body is a discriminated union keyed on `type` (`text`, `media`, `poll`).
+      def create(chat_id, type:, text: nil, media_url: nil, media_base64: nil,
+                 media_kind: nil, media_filename: nil, poll_question: nil,
+                 poll_options: nil, poll_allow_multiple: nil, reply_to: nil,
+                 secret: nil, with_typing: nil, typing_seconds: nil, idempotency_key: nil,
+                 mentions: nil)
+        body = { "type" => type }
+        body["text"] = text unless text.nil?
+        body["mediaUrl"] = media_url unless media_url.nil?
+        body["mediaBase64"] = media_base64 unless media_base64.nil?
+        body["mediaKind"] = media_kind unless media_kind.nil?
+        body["mediaFilename"] = media_filename unless media_filename.nil?
+        body["pollQuestion"] = poll_question unless poll_question.nil?
+        body["pollOptions"] = poll_options unless poll_options.nil?
+        body["pollAllowMultiple"] = poll_allow_multiple unless poll_allow_multiple.nil?
+        body["replyTo"] = reply_to unless reply_to.nil?
+        body["secret"] = secret unless secret.nil?
+        body["withTyping"] = with_typing unless with_typing.nil?
+        body["typingSeconds"] = typing_seconds unless typing_seconds.nil?
+        body["mentions"] = mentions unless mentions.nil?
+        env = client.request("POST", "/v1/messages/#{chat_id}", body: body, idempotency_key: idempotency_key)
+        Types::Message.from_hash(env && env["data"])
       end
     end
   end

data/lib/blueticks/resources/newsletters.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "../base_resource"
+require_relative "../types/newsletter"
+require_relative "../types/paginated"
+
+module Blueticks
+  module Resources
+    class NewslettersResource < BaseResource
+      # List newsletters.
+      #
+      # List newsletters visible to the connected WhatsApp engine. Offset-paginated
+      # (NewsletterListItem rows). Requires `newsletters:read` scope.
+      def list(search_token: nil, include_archive: nil, skip: nil, limit: nil)
+        params = {}
+        params["searchToken"] = search_token unless search_token.nil?
+        params["includeArchive"] = include_archive unless include_archive.nil?
+        params["skip"] = skip unless skip.nil?
+        params["limit"] = limit unless limit.nil?
+        env = client.request("GET", "/v1/newsletters", params: params.empty? ? nil : params)
+        Types::PaginatedPage.from_hash(env, item_type: Types::NewsletterListItem)
+      end
+
+      # Create newsletter.
+      #
+      # Create a new WhatsApp newsletter (channel). Requires `messages:write` scope.
+      def create(name:, description: nil)
+        body = { "name" => name }
+        body["description"] = description unless description.nil?
+        env = client.request("POST", "/v1/newsletters", body: body)
+        Types::Newsletter.from_hash(env && env["data"])
+      end
+
+      # Get newsletter.
+      #
+      # Retrieve a newsletter by its JID. Requires `newsletters:read` scope.
+      def retrieve(newsletter_id)
+        env = client.request("GET", "/v1/newsletters/#{newsletter_id}")
+        Types::Newsletter.from_hash(env && env["data"])
+      end
+    end
+  end
+end

data/lib/blueticks/resources/ping.rb

@@ -6,10 +6,13 @@ require_relative "../types/ping"
 module Blueticks
   module Resources
     class PingResource < BaseResource
-      # Health check. Returns basic info about the authenticated API key.
+      # Ping.
+      #
+      # Probe the API: returns `api: "ok"`, the account id, and the currently
+      # connected WhatsApp engines. Useful as a connection/liveness test.
       def retrieve
-        data = client.request("GET", "/v1/ping")
-        Types::Ping.from_hash(data)
+        env = client.request("GET", "/v1/ping")
+        Types::Ping.from_hash(env && env["data"])
       end
     end
   end

data/lib/blueticks/resources/realtime.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "../base_resource"
+require_relative "../types/realtime"
+
+module Blueticks
+  module Resources
+    class RealtimeResource < BaseResource
+      # Get MQTT credentials for receiving messages in real time.
+      #
+      # Returns short-lived broker credentials and the topic to subscribe to.
+      # Requires the `chats:read` scope.
+      def create_token
+        env = client.request("POST", "/v1/realtime/token")
+        Types::RealtimeToken.from_hash(env && env["data"])
+      end
+    end
+  end
+end