blueticks 1.1.2 → 2.0.0

data/lib/blueticks/types/audiences.rb

@@ -4,26 +4,32 @@ require_relative "base"
 
 module Blueticks
   module Types
-    class Contact < Base
+    # A contact stored inside an audience (ContactResponse). `variables` is a
+    # free-form hash of merge-field values.
+    class AudienceContact < Base
       field :id, :string
       field :to, :string
-      field :variables, %i[hash_of string]
-      field :added_at, :string
+      field :variables, :hash
+      field :added_at, :string, wire_name: "addedAt"
     end
 
+    # An audience (AudienceResponse).
     class Audience < Base
       field :id, :string
       field :name, :string
-      field :contact_count, :integer
-      field :created_at, :string
-      field :contacts, [:array, Contact], optional: true
-      field :page, :integer, optional: true
-      field :has_more, :boolean, optional: true
+      field :contact_count, :integer, wire_name: "contactCount"
+      field :created_at, :string, wire_name: "createdAt"
     end
 
+    # Result of appending contacts to an audience (POST .../contacts).
     class AppendContactsResult < Base
       field :added, :integer
-      field :contact_count, :integer
+      field :contact_count, :integer, wire_name: "contactCount"
+    end
+
+    # Result of removing a contact from an audience (DELETE .../contacts/{id}).
+    class ContactRemoval < Base
+      field :id, :string
     end
   end
 end

data/lib/blueticks/types/campaigns.rb

@@ -8,21 +8,22 @@ module Blueticks
       pending running paused complete_sent complete_delivered aborted
     ].freeze
 
+    # A campaign (CampaignResponse). Note the id is carried on `cmp_id`
+    # (wire `cmpId`), matching the backend document shape.
     class Campaign < Base
-      field :id, :string
+      field :cmp_id, :string, wire_name: "cmpId"
       field :name, :string
-      field :audience_id, :string
+      field :audience_id, :string, wire_name: "audienceId"
       field :status, [:enum, CAMPAIGN_STATUSES]
-      field :total_count, :integer
-      field :sent_count, :integer
-      field :delivered_count, :integer
-      field :read_count, :integer
-      field :failed_count, :integer
-      field :from, :string, nullable: true
-      field :created_at, :string
-      field :started_at, :string, nullable: true
-      field :completed_at, :string, nullable: true
-      field :aborted_at, :string, nullable: true
+      field :total_count, :integer, wire_name: "totalCount"
+      field :sent_count, :integer, wire_name: "sentCount"
+      field :delivered_count, :integer, wire_name: "deliveredCount"
+      field :read_count, :integer, wire_name: "readCount"
+      field :failed_count, :integer, wire_name: "failedCount"
+      field :created_at, :string, wire_name: "createdAt"
+      field :started_at, :string, nullable: true, wire_name: "startedAt"
+      field :completed_at, :string, nullable: true, wire_name: "completedAt"
+      field :aborted_at, :string, nullable: true, wire_name: "abortedAt"
     end
   end
 end

data/lib/blueticks/types/chats.rb

@@ -4,88 +4,29 @@ require_relative "base"
 
 module Blueticks
   module Types
-    MESSAGE_TYPES = %w[
-      chat image video document audio ptt sticker gif ptv
-      poll_creation location vcard revoked
-    ].freeze
-
-    MEDIA_UNAVAILABLE_REASONS = %w[expired fetching awaiting_sender error no_media].freeze
+    CHAT_TYPES = %w[contact group newsletter].freeze
 
+    # A chat row (Chat) returned by chats.list / chats.retrieve.
     class Chat < Base
-      field :id, :string
+      field :chat_id, :string, wire_name: "chatId"
       field :name, :string, nullable: true
-      field :is_group, :boolean
-      field :last_message_at, :string, nullable: true
-      field :unread_count, :integer, nullable: true
-    end
-
+      field :chat_type, [:enum, CHAT_TYPES], wire_name: "chatType"
+      field :pinned, :boolean, optional: true
+      field :archived, :boolean, optional: true
+      field :last_message_at, :string, nullable: true, wire_name: "lastMessageAt"
+      field :unread_count, :integer, nullable: true, wire_name: "unreadCount"
+      field :marked_unread, :boolean, wire_name: "markedUnread"
+      field :last_message_text, :string, nullable: true, optional: true, wire_name: "lastMessageText"
+      field :last_message_from_me, :boolean, nullable: true, optional: true, wire_name: "lastMessageFromMe"
+    end
+
+    # A participant of a group/community chat (Participant) as returned by
+    # chats.list_participants.
     class Participant < Base
-      field :chat_id, :string
-      field :is_admin, :boolean
-      field :is_super_admin, :boolean, nullable: true
-    end
-
-    class ChatMessage < Base
-      field :key, :string
-      field :chat_id, :string
-      field :from, :string
-      field :timestamp, :string, nullable: true
-      field :text, :string, nullable: true
-      field :type, :string
-      field :from_me, :boolean
-      field :ack, :integer, nullable: true
-      field :media_url, :string, nullable: true
-      field :caption, :string, nullable: true
-      field :filename, :string, nullable: true
-    end
-
-    class ChatMedia < Base
-      field :url, :string, nullable: true
-      field :mimetype, :string, nullable: true
-      field :filename, :string, nullable: true
-      field :data_base64, :string, nullable: true
-      field :original_quality, :boolean, nullable: true
-      field :media_unavailable, [:enum, MEDIA_UNAVAILABLE_REASONS], nullable: true
-    end
-
-    # Generic `{ "ok": true }` response envelope returned by acknowledged side-effects.
-    class OkResponse < Base
-      field :ok, :boolean
-    end
-
-    # `{ "chat_id": "..." }` envelope returned by /v1/chats/{chat_id}/open.
-    class ChatRef < Base
-      field :chat_id, :string
-    end
-
-    # `{ "ack": int|null }` envelope returned by .../messages/{key}/ack.
-    class MessageAck < Base
-      field :ack, :integer, nullable: true
-    end
-
-    # Response from POST /v1/chats/{chat_id}/messages/load_older.
-    class LoadOlderMessagesResponse < Base
-      field :total_messages, :integer, nullable: true
-      field :added, :integer, nullable: true
-      field :can_load_more, :boolean
-    end
-
-    # Response from GET /v1/chats/{chat_id}/messages/{key}/media_url.
-    class MediaUrlResponse < Base
-      field :url, :string, nullable: true
-    end
-
-    # Single entry in the BatchMessageAcksResponse `data` array.
-    # `{ "key": "<message key>", "ack": <int|null> }`.
-    class BatchMessageAckEntry < Base
-      field :key, :string
-      field :ack, :integer, nullable: true
-    end
-
-    # Response from POST /v1/chats/message_acks.
-    # `{ "data": [BatchMessageAckEntry, ...] }`.
-    class BatchMessageAcksResponse < Base
-      field :data, [:array, BatchMessageAckEntry]
+      field :chat_id, :string, wire_name: "chatId"
+      field :name, :string, nullable: true, optional: true
+      field :is_admin, :boolean, wire_name: "isAdmin"
+      field :is_super_admin, :boolean, optional: true, wire_name: "isSuperAdmin"
     end
   end
 end

data/lib/blueticks/types/contacts.rb

@@ -4,14 +4,13 @@ require_relative "base"
 
 module Blueticks
   module Types
+    # A WhatsApp contact known to the connected engine (contacts.list item).
+    # Per the spec, only `chatId` is required; `name` and `isBusiness` are
+    # optional and absent from real engine responses.
     class WhatsAppContact < Base
-      field :chat_id, :string
-      field :name, :string, nullable: true
-      field :is_business, :boolean
-    end
-
-    class ProfilePicture < Base
-      field :url, :string, nullable: true
+      field :chat_id, :string, wire_name: "chatId"
+      field :name, :string, optional: true, nullable: true
+      field :is_business, :boolean, optional: true, nullable: true, wire_name: "isBusiness"
     end
   end
 end

data/lib/blueticks/types/engines.rb

@@ -4,17 +4,18 @@ require_relative "base"
 
 module Blueticks
   module Types
-    class EngineStatus < Base
+    ENGINE_TYPES = %w[gateway regular].freeze
+
+    # A single engine session connected to the workspace (engines.list item).
+    # `type` is "gateway" (a remote server-side engine / Blueticks 24/7 gateway
+    # or baileys pod) or "regular" (the user's own WhatsApp Web extension).
+    class Engine < Base
+      field :id, :string
+      field :type, [:enum, ENGINE_TYPES]
       field :connected, :boolean
       field :state, :string, nullable: true
       field :stream, :string, nullable: true
-      field :has_synced, :boolean, nullable: true
-    end
-
-    class WhatsAppMe < Base
-      field :phone, :string, nullable: true
-      field :name, :string, nullable: true
-      field :platform, :string, nullable: true
+      field :has_synced, :boolean, nullable: true, wire_name: "hasSynced"
     end
   end
 end

data/lib/blueticks/types/groups.rb

@@ -4,24 +4,40 @@ require_relative "base"
 
 module Blueticks
   module Types
+    # A member of a group (GroupParticipant).
     class GroupParticipant < Base
-      field :chat_id, :string
-      field :is_admin, :boolean
-      field :is_super_admin, :boolean
+      field :chat_id, :string, wire_name: "chatId"
+      field :is_admin, :boolean, wire_name: "isAdmin"
+      field :is_super_admin, :boolean, wire_name: "isSuperAdmin"
       field :name, :string, nullable: true
     end
 
+    # Full group metadata (Group) returned by group create/get/update and the
+    # membership-mutating endpoints.
     class Group < Base
       field :id, :string
       field :name, :string, nullable: true
       field :description, :string, nullable: true
       field :owner, :string, nullable: true
-      field :created_at, :string, nullable: true
-      field :last_message_at, :string, nullable: true
-      field :participant_count, :integer, nullable: true
+      field :created_at, :string, nullable: true, wire_name: "createdAt"
+      field :last_message_at, :string, nullable: true, wire_name: "lastMessageAt"
+      field :participant_count, :integer, nullable: true, wire_name: "participantCount"
       field :announce, :boolean, nullable: true
       field :restrict, :boolean, nullable: true
       field :participants, [:array, GroupParticipant], nullable: true
     end
+
+    # A group row in the groups.list / contacts.common_groups page
+    # (GroupListItem) — a slimmer projection without announce/participants.
+    class GroupListItem < Base
+      field :id, :string
+      field :name, :string, nullable: true
+      field :description, :string, nullable: true
+      field :owner, :string, nullable: true
+      field :created_at, :string, nullable: true, wire_name: "createdAt"
+      field :last_message_at, :string, nullable: true, wire_name: "lastMessageAt"
+      field :participant_count, :integer, nullable: true, wire_name: "participantCount"
+      field :restrict, :boolean, nullable: true
+    end
   end
 end

data/lib/blueticks/types/messages.rb

@@ -4,22 +4,135 @@ require_relative "base"
 
 module Blueticks
   module Types
-    MESSAGE_STATUSES = %w[scheduled queued sending delivered read failed].freeze
+    MESSAGE_KINDS = %w[text media poll].freeze
+    MESSAGE_MEDIA_KINDS = %w[image video audio document sticker voice gif].freeze
+    MEDIA_UNAVAILABLE_REASONS = %w[expired fetching awaiting_sender error no_media].freeze
+    MESSAGE_STATUSES = %w[
+      pending before-wa-send bt-sent sending sent sent_pending_ack confirmed
+      delivered received read played cancelled error failed expired
+    ].freeze
 
+    # WhatsApp wire message key (PublicWaMessageKey). `serialized` maps the
+    # wire's `_serialized` compact form.
+    class WaMessageKey < Base
+      field :from_me, :boolean, wire_name: "fromMe"
+      field :remote, :string, optional: true
+      field :id, :string, optional: true
+      field :serialized, :string, optional: true, wire_name: "_serialized"
+      field :participant, :string, optional: true
+    end
+
+    # Link preview attached to a queued/scheduled message (MessageResponse).
+    # Fields are always present but may be null.
+    class LinkPreview < Base
+      field :title, :string, nullable: true
+      field :description, :string, nullable: true
+      field :canonical_url, :string, nullable: true, wire_name: "canonicalUrl"
+      field :thumbnail, :string, nullable: true
+    end
+
+    # Link preview attached to a store message (PublicMessage). Fields are all
+    # optional here.
+    class PublicLinkPreview < Base
+      field :title, :string, optional: true
+      field :description, :string, optional: true
+      field :canonical_url, :string, optional: true, wire_name: "canonicalUrl"
+      field :thumbnail, :string, optional: true
+    end
+
+    # The message a store message replies to (PublicQuotedMessage).
+    class QuotedMessage < Base
+      field :wa_message_key, WaMessageKey, wire_name: "waMessageKey"
+      field :text, :string, optional: true
+      field :type, :string, optional: true
+      field :author, :string, optional: true
+    end
+
+    # A message read from the WhatsApp store (PublicMessage) — the shape
+    # returned by messages.list and messages.retrieve.
+    class PublicMessage < Base
+      field :wa_message_key, WaMessageKey, wire_name: "waMessageKey"
+      field :chat_id, :string, wire_name: "chatId"
+      field :from, :string
+      field :author, :string, optional: true
+      field :sender_name, :string, optional: true, wire_name: "senderName"
+      field :timestamp, :string, optional: true
+      field :text, :string, optional: true
+      field :type, :string
+      field :from_me, :boolean, wire_name: "fromMe"
+      field :ack, :integer, optional: true
+      field :media_url, :string, optional: true, wire_name: "mediaUrl"
+      field :filename, :string, optional: true
+      field :link_preview, PublicLinkPreview, optional: true, wire_name: "linkPreview"
+      field :quoted_message, QuotedMessage, optional: true, wire_name: "quotedMessage"
+    end
+
+    # Media payload for a message (Media) returned by messages.get_media.
+    class Media < Base
+      field :url, :string, optional: true
+      field :mimetype, :string, optional: true
+      field :filename, :string, optional: true
+      field :data_base64, :string, optional: true, wire_name: "dataBase64"
+      field :original_quality, :boolean, optional: true, wire_name: "originalQuality"
+      field :media_unavailable, [:enum, MEDIA_UNAVAILABLE_REASONS], optional: true, wire_name: "mediaUnavailable"
+    end
+
+    # Delivery acknowledgement (MessageAck). ack: -1=error, 0=pending,
+    # 1=server, 2=device, 3=read, 4=played.
+    class MessageAck < Base
+      field :ack, :integer, nullable: true
+    end
+
+    # A single entry in the messages.batch_acks page (BatchMessageAckEntry).
+    class BatchAckEntry < Base
+      field :key, :string
+      field :ack, :integer, nullable: true
+      field :found, :boolean
+    end
+
+    # A pinned message summary (PinnedMessage) in the messages.pinned page.
+    class PinnedMessage < Base
+      field :key, :string
+      field :chat_id, :string, wire_name: "chatId"
+      field :text, :string, nullable: true
+    end
+
+    # Result of a load-older request (LoadOlderResult).
+    class LoadOlderResult < Base
+      field :total_messages, :integer, nullable: true, wire_name: "totalMessages"
+      field :added, :integer, nullable: true
+      field :can_load_more, :boolean, wire_name: "canLoadMore"
+      field :history_unavailable, :boolean, wire_name: "historyUnavailable"
+      field :error, :string, nullable: true
+    end
+
+    # A sent/queued outbound message record — the shape returned by
+    # messages.create (direct send). The spec's send response marks only
+    # `to`, `type`, `status`, `createdAt` required; `waMessageKey` is optional
+    # (absent until the message has a wire key). The scheduled/queued variant is
+    # modelled separately by Types::ScheduledMessage.
     class Message < Base
-      field :id, :string
+      field :id, :string, optional: true
+      field :wa_message_key, WaMessageKey, optional: true, nullable: true, wire_name: "waMessageKey"
       field :to, :string
-      field :from, :string, nullable: true
+      field :type, [:enum, MESSAGE_KINDS]
       field :text, :string, nullable: true
-      field :media_url, :string, nullable: true
+      field :media_url, :string, nullable: true, wire_name: "mediaUrl"
+      field :media_kind, [:enum, MESSAGE_MEDIA_KINDS], nullable: true, wire_name: "mediaKind"
+      field :poll_question, :string, nullable: true, wire_name: "pollQuestion"
+      field :poll_options, %i[array string], nullable: true, wire_name: "pollOptions"
+      field :poll_allow_multiple, :boolean, nullable: true, wire_name: "pollAllowMultiple"
       field :status, [:enum, MESSAGE_STATUSES]
-      field :send_at, :string, nullable: true
-      field :created_at, :string
-      field :sent_at, :string, nullable: true
-      field :delivered_at, :string, nullable: true
-      field :read_at, :string, nullable: true
-      field :failed_at, :string, nullable: true
-      field :failure_reason, :string, nullable: true
+      field :send_at, :string, nullable: true, wire_name: "sendAt"
+      field :created_at, :string, wire_name: "createdAt"
+      field :confirmed_at, :string, nullable: true, wire_name: "confirmedAt"
+      field :received_at, :string, nullable: true, wire_name: "receivedAt"
+      field :read_at, :string, nullable: true, wire_name: "readAt"
+      field :played_at, :string, nullable: true, wire_name: "playedAt"
+      field :failed_at, :string, nullable: true, wire_name: "failedAt"
+      field :failure_reason, :string, nullable: true, wire_name: "failureReason"
+      field :secret, :string, nullable: true
+      field :link_preview, LinkPreview, optional: true, wire_name: "linkPreview"
     end
   end
 end

data/lib/blueticks/types/newsletter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Blueticks
+  module Types
+    NEWSLETTER_VERIFICATIONS = %w[VERIFIED UNVERIFIED].freeze
+
+    # A WhatsApp newsletter (channel) as returned by create/get
+    # (NewsletterResponse). The JID is carried on `newsletter_id`.
+    class Newsletter < Base
+      field :newsletter_id, :string, wire_name: "newsletterId"
+      field :name, :string
+      field :description, :string, nullable: true
+      field :created_at, :string, nullable: true, wire_name: "createdAt"
+      field :subscribers, :integer, nullable: true
+      field :invite, :string, nullable: true
+      field :verification, [:enum, NEWSLETTER_VERIFICATIONS], nullable: true
+    end
+
+    # A newsletter row in the newsletters.list page (NewsletterListItem). Here
+    # the JID is carried on `chat_id`.
+    class NewsletterListItem < Base
+      field :chat_id, :string, wire_name: "chatId"
+      field :name, :string
+      field :description, :string, nullable: true
+      field :created_at, :string, nullable: true, wire_name: "createdAt"
+      field :subscribers, :integer, nullable: true
+      field :invite, :string, nullable: true
+      field :verification, [:enum, NEWSLETTER_VERIFICATIONS], nullable: true
+    end
+  end
+end

data/lib/blueticks/types/ok_result.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Blueticks
+  module Types
+    # Generic `{ "ok": true }` acknowledgement returned by side-effecting
+    # endpoints (chat archive/mark-read, message pin/unpin/react).
+    class OkResult < Base
+      field :ok, [:enum, [true]]
+    end
+  end
+end

data/lib/blueticks/types/paginated.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../errors"
+
+module Blueticks
+  module Types
+    # Offset-paginated list envelope. Every v1 list endpoint returns this shape
+    # inside the success/data wrapper: `{ data: [...], limit, skip, total }`.
+    #
+    # Iterate `data` for the current page; advance by passing `skip: skip + limit`
+    # (or any offset) back on the next list call. `total` is the full match count
+    # across all pages. `has_more` is populated only by endpoints that echo a
+    # `hasMore` flag (e.g. messages.list); nil elsewhere.
+    class PaginatedPage
+      attr_reader :data, :limit, :skip, :total, :has_more
+
+      def initialize(data:, limit:, skip:, total:, has_more: nil)
+        @data = data
+        @limit = limit
+        @skip = skip
+        @total = total
+        @has_more = has_more
+      end
+
+      # Build a PaginatedPage from a raw list envelope, decoding each item via
+      # item_type.from_hash. Reads `data`/`limit`/`skip`/`total` (and optional
+      # `hasMore`) off the envelope; ignores the `success` flag.
+      def self.from_hash(raw, item_type:)
+        unless raw.is_a?(Hash)
+          raise Errors::ValidationError.new(message: "Expected Hash for PaginatedPage, got #{raw.class}")
+        end
+        unless raw["data"].is_a?(Array)
+          raise Errors::ValidationError.new(message: "Field 'data' must be array in PaginatedPage")
+        end
+
+        limit = require_integer(raw, "limit")
+        skip = require_integer(raw, "skip")
+        total = require_integer(raw, "total")
+
+        has_more = raw["hasMore"]
+        unless has_more.nil? || [true, false].include?(has_more)
+          raise Errors::ValidationError.new(message: "Field 'hasMore' must be boolean or absent in PaginatedPage")
+        end
+
+        decoded = raw["data"].each_with_index.map do |item, i|
+          item_type.from_hash(item, context: "PaginatedPage.data[#{i}]")
+        end
+
+        new(data: decoded, limit: limit, skip: skip, total: total, has_more: has_more)
+      end
+
+      def self.require_integer(raw, key)
+        value = raw[key]
+        unless value.is_a?(Integer) && !value.is_a?(TrueClass) && !value.is_a?(FalseClass)
+          raise Errors::ValidationError.new(message: "Field '#{key}' must be integer in PaginatedPage")
+        end
+
+        value
+      end
+
+      def to_h
+        {
+          data: data.map { |d| d.respond_to?(:to_h) ? d.to_h : d },
+          limit: limit, skip: skip, total: total, has_more: has_more
+        }
+      end
+    end
+  end
+end

data/lib/blueticks/types/ping.rb

@@ -4,11 +4,19 @@ require_relative "base"
 
 module Blueticks
   module Types
+    # A connected WhatsApp engine as summarized on the ping response.
+    class PingConnection < Base
+      field :id, :string
+      field :type, [:enum, %w[gateway regular]]
+      field :connected, [:enum, [true]]
+    end
+
     # Response from GET /v1/ping.
     class Ping < Base
-      field :account_id, :string
-      field :key_prefix, :string
-      field :scopes, %i[array string]
+      field :api, [:enum, %w[ok]]
+      field :account_id, :string, wire_name: "accountId"
+      field :whatsapp_connections, [:array, PingConnection], wire_name: "whatsappConnections"
+      field :message, :string, optional: true
     end
   end
 end

data/lib/blueticks/types/scheduled_messages.rb

@@ -1,23 +1,37 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative "messages"
 
 module Blueticks
   module Types
+    # A queued / scheduled outbound message record — the shape returned by
+    # every scheduled_messages.* endpoint. This is a DISTINCT inline schema in
+    # the spec (not MessageResponse): only `to`, `type`, `status`, `createdAt`
+    # are required. In particular `waMessageKey` is optional and ABSENT on a
+    # record that has not dispatched yet, so it must never be decoded through a
+    # type that requires it (see Types::Message, used only by messages.create).
     class ScheduledMessage < Base
-      field :id, :string
-      field :to, :string, nullable: true
-      field :text, :string, nullable: true
-      field :media_url, :string, nullable: true
-      field :media_caption, :string, nullable: true
-      field :media_filename, :string, nullable: true
-      field :media_mime_type, :string, nullable: true
-      field :send_at, :string, nullable: true
-      field :status, :string, nullable: true
-      field :is_recurring, :boolean
-      field :recurrence_rule, :string, nullable: true
-      field :created_at, :string, nullable: true
-      field :updated_at, :string, nullable: true
+      field :id, :string, optional: true
+      field :wa_message_key, WaMessageKey, optional: true, nullable: true, wire_name: "waMessageKey"
+      field :to, :string
+      field :type, [:enum, MESSAGE_KINDS]
+      field :text, :string, optional: true, nullable: true
+      field :media_url, :string, optional: true, nullable: true, wire_name: "mediaUrl"
+      field :media_kind, [:enum, MESSAGE_MEDIA_KINDS], optional: true, nullable: true, wire_name: "mediaKind"
+      field :poll_question, :string, optional: true, nullable: true, wire_name: "pollQuestion"
+      field :poll_options, %i[array string], optional: true, nullable: true, wire_name: "pollOptions"
+      field :poll_allow_multiple, :boolean, optional: true, nullable: true, wire_name: "pollAllowMultiple"
+      field :status, [:enum, MESSAGE_STATUSES]
+      field :send_at, :string, optional: true, nullable: true, wire_name: "sendAt"
+      field :created_at, :string, wire_name: "createdAt"
+      field :confirmed_at, :string, optional: true, nullable: true, wire_name: "confirmedAt"
+      field :received_at, :string, optional: true, nullable: true, wire_name: "receivedAt"
+      field :read_at, :string, optional: true, nullable: true, wire_name: "readAt"
+      field :played_at, :string, optional: true, nullable: true, wire_name: "playedAt"
+      field :failed_at, :string, optional: true, nullable: true, wire_name: "failedAt"
+      field :failure_reason, :string, optional: true, nullable: true, wire_name: "failureReason"
+      field :secret, :string, optional: true, nullable: true
+      field :link_preview, LinkPreview, optional: true, wire_name: "linkPreview"
     end
   end
 end

data/lib/blueticks/types/suno.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Blueticks
+  module Types
+    SONG_CLIP_STATUSES = %w[submitted queued running streaming complete error].freeze
+
+    # Suno credit / plan usage (AccountUsageResponse) from GET /v1/suno/account.
+    class SunoAccount < Base
+      field :credits_left, :number, wire_name: "creditsLeft"
+      field :monthly_limit, :number, nullable: true, wire_name: "monthlyLimit"
+      field :monthly_usage, :number, nullable: true, wire_name: "monthlyUsage"
+      field :plan, :string, nullable: true
+    end
+
+    # A generated song clip (SongClip / GetSongResponse).
+    class SongClip < Base
+      field :id, :string
+      field :status, [:enum, SONG_CLIP_STATUSES]
+      field :audio_url, :string, nullable: true, wire_name: "audioUrl"
+      field :image_url, :string, nullable: true, wire_name: "imageUrl"
+      field :title, :string, nullable: true
+      field :duration_sec, :number, nullable: true, wire_name: "durationSec"
+      field :model, :string, nullable: true
+      field :error_type, :string, nullable: true, optional: true, wire_name: "errorType"
+      field :error_message, :string, nullable: true, optional: true, wire_name: "errorMessage"
+    end
+
+    # Result of submitting a song generation job (GenerateSongResponse).
+    class GenerateSongResult < Base
+      field :job_id, :string, wire_name: "jobId"
+      field :clips, [:array, SongClip]
+    end
+
+    # Result of registering a reference-audio upload (CreateUploadResponse).
+    class CreateUploadResult < Base
+      field :upload_id, :string, wire_name: "uploadId"
+      field :status, :string
+    end
+  end
+end