blueticks 1.1.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19df800ede192ab6e262f3faeff874072d9c880466ad6d17cd5de461cdbf0b07
-  data.tar.gz: 25804da58032e239b22ef1027365fb05f12dd778633a542d52b41910eab3bffb
+  metadata.gz: 62b2a3ae7e59ee684634e2e2e26883fa47db18da62aa74eda711efd088d4e868
+  data.tar.gz: 392f498378faa47fa4be6f73fbefad15a5642ab16718ec2fdd9787a8aa5951a4
 SHA512:
-  metadata.gz: a2a0ab6b4d585f6a93a51a0a13d55dda3e87d2499c32ae932c36a29448ce09e2a886e97c9d8c4b8ba6457ae63aa9de15d79d5a8e8530eaee2451ce02a9d1bd97
-  data.tar.gz: 05c7bcd1cc42f0604961fe157234a3dc1604304f93e276b57425504aea42453eaeb2f3e9da3c6b6f01350d1d7a33134d76cd8247c98f1c59928d45aea03becbc
+  metadata.gz: e3a873bb77d76820cf1946483f11eabf2c53169c3930f1578fbbaa86679193e6428071aed414d4d9c41f5f99beb3dfd7bac411e9db84ebcad3e66b364e5f9def
+  data.tar.gz: 681cf759086355b74cdba8fec69cf515b62705b7a8a0039916c25a267dc34928d2f24c2a62dc948e3c04ea909c45f618cb0803677cc3efe0a56a2568447576d4

data/CHANGELOG.md

@@ -4,6 +4,47 @@ All notable changes to the Blueticks Ruby SDK are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.2.0 — 2026-05-22
+
+OpenAPI parity pass. The SDK now matches `backend/openapi.json`
+operation-for-operation; an engineless drift check
+(`.github/workflows/sdk-spec-drift.yml`) gates future regressions. The
+`/v1/*` surface is pre-release — none of these changes affect production
+callers yet.
+
+### Changed
+
+- `messages.send` now takes the discriminated body shape matching the
+  backend's strict `anyOf` (BE#50):
+  ```ruby
+  client.messages.send(to: '+1...', type: 'text', text: 'hi')
+  client.messages.send(to: '+1...', type: 'media', media: { url: '...', kind: 'image' })
+  client.messages.send(to: '+1...', type: 'poll',  poll: { question: '...', options: [...] })
+  ```
+- Single-item GETs now use `.retrieve(id)` instead of `.get(id)` where the
+  spec uses GET-by-id. Also `engines.status` → `engines.retrieve`.
+- `newsletters.create` returns the typed `Blueticks::Types::Newsletter` (8
+  fields) instead of a raw Hash.
+
+### Added
+
+- `newsletters.list(limit:, cursor:)` — `GET /v1/newsletters` (cursor-paginated → `Page<Newsletter>`)
+- `newsletters.retrieve(id)` — `GET /v1/newsletters/{id}`
+- `ping.retrieve` — typed `Ping` (`account_id`, `key_prefix`, `scopes`). The
+  `ping` resource had been deleted in a prior interim regen; restored here.
+- `Message` now exposes `key`, `type`, `media_kind`, `poll_question`, `link_preview`
+
+### Removed
+
+- `engines.me`, `engines.logout`, `engines.reload`
+- `contacts.get_profile_picture`
+- `utils.validate_phone`, `utils.link_preview` (the `utils` resource was emptied)
+
+### Fixed
+
+- `groups.list` was documented at `dev.blueticks.co` but absent from the
+  SDK for ~9 days — now present.
+
 ## 1.0.0 — 2026-04-30
 
 Initial release.

data/lib/blueticks/client.rb

@@ -2,13 +2,26 @@
 
 require_relative "errors"
 require_relative "transport"
+require_relative "resources/account"
+require_relative "resources/audiences"
+require_relative "resources/campaigns"
+require_relative "resources/chats"
+require_relative "resources/contacts"
+require_relative "resources/engines"
+require_relative "resources/groups"
+require_relative "resources/messages"
+require_relative "resources/newsletters"
+require_relative "resources/ping"
 require_relative "resources/scheduled_messages"
+require_relative "resources/suno"
+require_relative "resources/utils"
+require_relative "resources/webhooks"
 
 module Blueticks
   # Top-level entry point. Construct one and access resources via accessor methods:
   #
   #   client = Blueticks::Client.new(api_key: "bt_live_...")
-  #   client.messages.send(to: "12025550100", text: "Hello!")
+  #   client.scheduled_messages.create(type: "text", to: "12025550100", text: "Hello!")
   #
   # Configuration order of precedence:
   #   1. Explicit keyword args.
@@ -47,10 +60,6 @@ module Blueticks
       @ping ||= Resources::PingResource.new(self)
     end
 
-    def messages
-      @messages ||= Resources::MessagesResource.new(self)
-    end
-
     def scheduled_messages
       @scheduled_messages ||= Resources::ScheduledMessagesResource.new(self)
     end
@@ -83,6 +92,19 @@ module Blueticks
       @contacts ||= Resources::ContactsResource.new(self)
     end
 
+    def newsletters
+      @newsletters ||= Resources::NewslettersResource.new(self)
+    end
+
+    def messages
+      @messages ||= Resources::MessagesResource.new(self)
+    end
+
+    def suno
+      @suno ||= Resources::SunoResource.new(self)
+    end
+
+    # Kept for backward compatibility. No spec-backed operations exposed.
     def utils
       @utils ||= Resources::UtilsResource.new(self)
     end

data/lib/blueticks/resources/account.rb

@@ -10,8 +10,8 @@ module Blueticks
       #
       # Returns the account associated with the API key used for this request.
       def retrieve
-        data = client.request("GET", "/v1/account")
-        Types::Account.from_hash(data)
+        env = client.request("GET", "/v1/account")
+        Types::Account.from_hash(env && env["data"])
       end
     end
   end

data/lib/blueticks/resources/audiences.rb

@@ -3,67 +3,75 @@
 require_relative "../base_resource"
 require_relative "../types/audiences"
 require_relative "../types/deleted_resource"
-require_relative "../types/page"
+require_relative "../types/paginated"
 
 module Blueticks
   module Resources
     class AudiencesResource < BaseResource
+      # Create an audience, optionally seeding it with contacts.
+      # `contacts` is an Array of `{ "to" => ..., "variables" => {...} }` hashes.
       def create(name:, contacts: nil)
         body = { "name" => name }
         body["contacts"] = contacts unless contacts.nil?
-        data = client.request("POST", "/v1/audiences", body: body)
-        Types::Audience.from_hash(data)
+        env = client.request("POST", "/v1/audiences", body: body)
+        Types::Audience.from_hash(env && env["data"])
       end
 
-      # List audiences, newest first. Cursor-paginated.
-      def list(limit: nil, cursor: nil)
+      # List audiences, newest first. Offset-paginated.
+      def list(order: nil, skip: nil, limit: nil)
         params = {}
+        params["order"] = order unless order.nil?
+        params["skip"] = skip unless skip.nil?
         params["limit"] = limit unless limit.nil?
-        params["cursor"] = cursor unless cursor.nil?
-        data = client.request("GET", "/v1/audiences", params: params.empty? ? nil : params)
-        Types::Page.from_hash(data, item_type: Types::Audience)
+        env = client.request("GET", "/v1/audiences", params: params.empty? ? nil : params)
+        Types::PaginatedPage.from_hash(env, item_type: Types::Audience)
       end
 
-      def get(audience_id, page: nil)
-        params = page.nil? ? nil : { "page" => page }
-        data = client.request("GET", "/v1/audiences/#{audience_id}", params: params)
-        Types::Audience.from_hash(data)
+      # Retrieve an audience by id.
+      def retrieve(audience_id)
+        env = client.request("GET", "/v1/audiences/#{audience_id}")
+        Types::Audience.from_hash(env && env["data"])
       end
 
+      # Rename an audience.
       def update(audience_id, name:)
-        data = client.request("PATCH", "/v1/audiences/#{audience_id}", body: { "name" => name })
-        Types::Audience.from_hash(data)
+        env = client.request("PATCH", "/v1/audiences/#{audience_id}", body: { "name" => name })
+        Types::Audience.from_hash(env && env["data"])
       end
 
+      # Delete an audience.
       def delete(audience_id)
-        data = client.request("DELETE", "/v1/audiences/#{audience_id}")
-        Types::DeletedResource.from_hash(data)
+        env = client.request("DELETE", "/v1/audiences/#{audience_id}")
+        Types::DeletedResource.from_hash(env && env["data"])
       end
 
+      # Append contacts to an audience.
       def append_contacts(audience_id, contacts:)
-        data = client.request(
+        env = client.request(
           "POST",
           "/v1/audiences/#{audience_id}/contacts",
           body: { "contacts" => contacts }
         )
-        Types::AppendContactsResult.from_hash(data)
+        Types::AppendContactsResult.from_hash(env && env["data"])
       end
 
+      # Update a single contact's recipient and/or merge-field variables.
       def update_contact(audience_id, contact_id, to: nil, variables: nil)
         body = {}
         body["to"] = to unless to.nil?
         body["variables"] = variables unless variables.nil?
-        data = client.request(
+        env = client.request(
           "PATCH",
           "/v1/audiences/#{audience_id}/contacts/#{contact_id}",
           body: body
         )
-        Types::Contact.from_hash(data)
+        Types::AudienceContact.from_hash(env && env["data"])
       end
 
+      # Remove a contact from an audience.
       def delete_contact(audience_id, contact_id)
-        client.request("DELETE", "/v1/audiences/#{audience_id}/contacts/#{contact_id}")
-        nil
+        env = client.request("DELETE", "/v1/audiences/#{audience_id}/contacts/#{contact_id}")
+        Types::ContactRemoval.from_hash(env && env["data"])
       end
     end
   end

data/lib/blueticks/resources/campaigns.rb

@@ -2,50 +2,55 @@
 
 require_relative "../base_resource"
 require_relative "../types/campaigns"
-require_relative "../types/page"
+require_relative "../types/paginated"
 
 module Blueticks
   module Resources
     class CampaignsResource < BaseResource
+      # Create a campaign against an audience.
       def create(name:, audience_id:, text: nil, media_url: nil, media_caption: nil,
-                 from: nil, on_missing_variable: nil)
-        body = { "name" => name, "audience_id" => audience_id }
+                 on_missing_variable: nil)
+        body = { "name" => name, "audienceId" => audience_id }
         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["from"] = from unless from.nil?
-        body["on_missing_variable"] = on_missing_variable unless on_missing_variable.nil?
-        data = client.request("POST", "/v1/campaigns", body: body)
-        Types::Campaign.from_hash(data)
+        body["mediaUrl"] = media_url unless media_url.nil?
+        body["mediaCaption"] = media_caption unless media_caption.nil?
+        body["onMissingVariable"] = on_missing_variable unless on_missing_variable.nil?
+        env = client.request("POST", "/v1/campaigns", body: body)
+        Types::Campaign.from_hash(env && env["data"])
       end
 
-      # List campaigns, newest first. Cursor-paginated.
-      def list(limit: nil, cursor: nil)
+      # List campaigns, newest first. Offset-paginated.
+      def list(order: nil, skip: nil, limit: nil)
         params = {}
+        params["order"] = order unless order.nil?
+        params["skip"] = skip unless skip.nil?
         params["limit"] = limit unless limit.nil?
-        params["cursor"] = cursor unless cursor.nil?
-        data = client.request("GET", "/v1/campaigns", params: params.empty? ? nil : params)
-        Types::Page.from_hash(data, item_type: Types::Campaign)
+        env = client.request("GET", "/v1/campaigns", params: params.empty? ? nil : params)
+        Types::PaginatedPage.from_hash(env, item_type: Types::Campaign)
       end
 
-      def get(campaign_id)
-        data = client.request("GET", "/v1/campaigns/#{campaign_id}")
-        Types::Campaign.from_hash(data)
+      # Retrieve a campaign by id.
+      def retrieve(campaign_id)
+        env = client.request("GET", "/v1/campaigns/#{campaign_id}")
+        Types::Campaign.from_hash(env && env["data"])
       end
 
+      # Pause a running campaign.
       def pause(campaign_id)
-        data = client.request("POST", "/v1/campaigns/#{campaign_id}/pause")
-        Types::Campaign.from_hash(data)
+        env = client.request("POST", "/v1/campaigns/#{campaign_id}/pause")
+        Types::Campaign.from_hash(env && env["data"])
       end
 
+      # Resume a paused campaign.
       def resume(campaign_id)
-        data = client.request("POST", "/v1/campaigns/#{campaign_id}/resume")
-        Types::Campaign.from_hash(data)
+        env = client.request("POST", "/v1/campaigns/#{campaign_id}/resume")
+        Types::Campaign.from_hash(env && env["data"])
       end
 
+      # Cancel a campaign.
       def cancel(campaign_id)
-        data = client.request("POST", "/v1/campaigns/#{campaign_id}/cancel")
-        Types::Campaign.from_hash(data)
+        env = client.request("POST", "/v1/campaigns/#{campaign_id}/cancel")
+        Types::Campaign.from_hash(env && env["data"])
       end
     end
   end

data/lib/blueticks/resources/chats.rb

@@ -2,111 +2,62 @@
 
 require_relative "../base_resource"
 require_relative "../types/chats"
-require_relative "../types/page"
+require_relative "../types/ok_result"
+require_relative "../types/paginated"
 
 module Blueticks
   module Resources
     class ChatsResource < BaseResource
-      # List/search chats, newest first. Cursor-paginated.
-      def list(query: nil, limit: nil, cursor: nil)
+      # List/search chats, newest first. Offset-paginated.
+      def list(search_token: nil, filter: nil, include_last_message: nil,
+               include_extended_info: nil, include_without_name: nil,
+               include_archive: nil, skip: nil, limit: nil)
         params = {}
-        params["query"] = query unless query.nil?
+        params["searchToken"] = search_token unless search_token.nil?
+        params["filter"] = filter unless filter.nil?
+        params["includeLastMessage"] = include_last_message unless include_last_message.nil?
+        params["includeExtendedInfo"] = include_extended_info unless include_extended_info.nil?
+        params["includeWithoutName"] = include_without_name unless include_without_name.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/chats", params: params.empty? ? nil : params)
-        Types::Page.from_hash(data, item_type: Types::Chat)
+        env = client.request("GET", "/v1/chats", params: params.empty? ? nil : params)
+        Types::PaginatedPage.from_hash(env, item_type: Types::Chat)
       end
 
       # Retrieve a chat by its JID.
-      def get(chat_id)
-        data = client.request("GET", "/v1/chats/#{chat_id}")
-        Types::Chat.from_hash(data)
+      def retrieve(chat_id)
+        env = client.request("GET", "/v1/chats/#{chat_id}")
+        Types::Chat.from_hash(env && env["data"])
       end
 
-      # List participants in a group chat. Cursor-paginated.
-      def list_participants(chat_id, limit: nil, cursor: nil)
+      # List participants in a group/community chat. Offset-paginated.
+      def list_participants(chat_id, search_token: nil, skip: nil, limit: nil)
         params = {}
+        params["searchToken"] = search_token unless search_token.nil?
+        params["skip"] = skip unless skip.nil?
         params["limit"] = limit unless limit.nil?
-        params["cursor"] = cursor unless cursor.nil?
-        data = client.request("GET", "/v1/chats/#{chat_id}/participants",
-                              params: params.empty? ? nil : params)
-        Types::Page.from_hash(data, item_type: Types::Participant)
+        env = client.request("GET", "/v1/chats/#{chat_id}/participants",
+                             params: params.empty? ? nil : params)
+        Types::PaginatedPage.from_hash(env, item_type: Types::Participant)
       end
 
-      # Mark a chat as read (sends read receipts if enabled).
-      def mark_read(chat_id)
-        data = client.request("POST", "/v1/chats/#{chat_id}/mark_read")
-        Types::OkResponse.from_hash(data)
-      end
-
-      # Open a chat on the engine (useful for UI-assisted workflows).
-      def open(chat_id)
-        data = client.request("POST", "/v1/chats/#{chat_id}/open")
-        Types::ChatRef.from_hash(data)
-      end
-
-      # List messages in a chat. `mode` is "latest" or "history".
-      def list_messages(chat_id, mode: "latest", query: nil, since: nil, until_: nil,
-                        message_types: nil, limit: nil, cursor: nil)
-        params = { "mode" => mode }
-        params["query"] = query unless query.nil?
-        params["since"] = since unless since.nil?
-        params["until"] = until_ unless until_.nil?
-        params["message_types"] = message_types.join(",") if message_types && !message_types.empty?
-        params["limit"] = limit unless limit.nil?
-        params["cursor"] = cursor unless cursor.nil?
-        data = client.request("GET", "/v1/chats/#{chat_id}/messages", params: params)
-        Types::Page.from_hash(data, item_type: Types::ChatMessage)
+      # Archive a chat.
+      def archive(chat_id)
+        env = client.request("POST", "/v1/chats/#{chat_id}/archive")
+        Types::OkResult.from_hash(env && env["data"])
       end
 
-      # Retrieve a single message in a chat by its key.
-      def get_message(chat_id, key)
-        data = client.request("GET", "/v1/chats/#{chat_id}/messages/#{key}")
-        Types::ChatMessage.from_hash(data)
+      # Unarchive a chat.
+      def unarchive(chat_id)
+        env = client.request("POST", "/v1/chats/#{chat_id}/unarchive")
+        Types::OkResult.from_hash(env && env["data"])
       end
 
-      # Get message delivery status (ack value: -1=error, 0=pending, 1=server, 2=device, 3=read, 4=played).
-      def get_message_ack(chat_id, key)
-        data = client.request("GET", "/v1/chats/#{chat_id}/messages/#{key}/ack")
-        Types::MessageAck.from_hash(data)
-      end
-
-      # React to a message. Pass an empty `emoji` string to remove a reaction.
-      def react(chat_id, key, emoji:)
-        data = client.request(
-          "POST",
-          "/v1/chats/#{chat_id}/messages/#{key}/reactions",
-          body: { "emoji" => emoji }
-        )
-        Types::OkResponse.from_hash(data)
-      end
-
-      # Ask the engine to pull older history from the connected phone.
-      def load_older_messages(chat_id)
-        data = client.request("POST", "/v1/chats/#{chat_id}/messages/load_older")
-        Types::LoadOlderMessagesResponse.from_hash(data)
-      end
-
-      # Get a hosted URL for the message media without inlining bytes.
-      def get_media_url(chat_id, key)
-        data = client.request("GET", "/v1/chats/#{chat_id}/messages/#{key}/media_url")
-        Types::MediaUrlResponse.from_hash(data)
-      end
-
-      # Fetch full media bytes (base64) for a message.
-      def get_media(chat_id, key)
-        data = client.request("GET", "/v1/chats/#{chat_id}/messages/#{key}/media")
-        Types::ChatMedia.from_hash(data)
-      end
-
-      # Batch get delivery status for up to 200 sent messages.
-      def batch_message_acks(message_keys:)
-        data = client.request(
-          "POST",
-          "/v1/chats/message_acks",
-          body: { "message_keys" => message_keys }
-        )
-        Types::BatchMessageAcksResponse.from_hash(data)
+      # Mark a chat as read (sends read receipts if enabled).
+      def mark_read(chat_id)
+        env = client.request("POST", "/v1/chats/#{chat_id}/mark_read")
+        Types::OkResult.from_hash(env && env["data"])
       end
     end
   end

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