postproxy-sdk 1.9.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b20d20d7dc1f6a386e74894a57e470c70a1edc3e95bcd61c3b25f02b3e457cd
-  data.tar.gz: 6fd6807bcbbd09fae222ccd07eee0d66cbb420bc04e83fd49ab98c4340a4ed82
+  metadata.gz: 2852d366a306a698457955ea9e631fb4cd05fbc0f55949a772f0b872b19ce0af
+  data.tar.gz: 74845607657bcea29116fe1a3d509daea04f0afba3e0ded079068f03b17d3506
 SHA512:
-  metadata.gz: c5e18b59805d1aff449eb7e3b8227bd2290b85994ba8e14f38b1c945381facd37a1b77e218d9eaf3c3e8c3183eade0da5268eb86b79762ad1aa9606b015a8e6a
-  data.tar.gz: ec5a37899a8c3622212e5d7d2b43a540df1e7aff64f9ea99a17a3fd1b0ed1e332a44a7c568eef24882f70fba267fe18302581d9af999ed997651df368dca59cc
+  metadata.gz: 0650f24d42af376d663521ced5c78be0fe97dc99d117534a132479a02f8290a18404426d5791ea5f90f3ed786041ccb2d3a15486533b149e7ab0c94324839238
+  data.tar.gz: 39699c4a07a238f45fc1e12545dfc97b88d85299f03cd3eb1ba97380a1f7bfa79da004abd170c3da87aa707d486a7a103c298c0b34fb9371d9d0c4ada45e3014

data/README.md

@@ -264,7 +264,7 @@ PostProxy::WebhookSignature.verify(
 
 Subscribe to any of these events (or pass `["*"]` for all):
 
-`post.processed`, `post.imported`, `platform_post.published`, `platform_post.failed`, `platform_post.failed_waiting_for_retry`, `platform_post.insights`, `profile.connected`, `profile.disconnected`, `profile.stats`, `media.failed`, `comment.created`.
+`post.processed`, `post.imported`, `platform_post.published`, `platform_post.failed`, `platform_post.failed_waiting_for_retry`, `platform_post.insights`, `profile.connected`, `profile.disconnected`, `profile.stats`, `media.failed`, `comment.created`, `profile_comment.created`, `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.edited`, `message.deleted`, `message.failed_waiting_for_retry`, `message.failed`, `reaction.received`.
 
 `PostProxy::WebhookEvents.parse` validates the envelope and returns a typed `Event` — `event.data` is the right model for the event:
 
@@ -277,9 +277,20 @@ when "platform_post.published"
   puts "Published: #{event.data.platform_id}"
 when "comment.created"
   puts "#{event.data.author_username}: #{event.data.body}"
+when "message.received"
+  # MessageEventData — event.data.message is a full Message
+  puts "DM from #{event.data.message.chat_id}: #{event.data.message.body}"
+when "reaction.received"
+  # ReactionEventData
+  puts "#{event.data.action}: #{event.data.reaction} on #{event.data.message.id}"
+when "profile_comment.created"
+  # ProfileCommentCreatedData
+  puts "#{event.data.author_username}: #{event.data.body}"
 end
 ```
 
+The direct-message events (`message.*`) carry a `MessageEventData` (`data.message` is a full `Message`); `reaction.received` carries a `ReactionEventData`; `profile_comment.created` carries a `ProfileCommentCreatedData`.
+
 ## Comments
 
 ```ruby
@@ -315,6 +326,71 @@ client.comments.unhide("post-id", "comment-id", profile_id: "profile-id")
 # Like / unlike a comment
 client.comments.like("post-id", "comment-id", profile_id: "profile-id")
 client.comments.unlike("post-id", "comment-id", profile_id: "profile-id")
+
+# Synced comments may carry media attachments and author metadata
+comment = client.comments.get("post-id", "comment-id", profile_id: "profile-id")
+comment.attachments.each { |att| puts "#{att.type} #{att.url} (#{att.status})" }
+puts comment.metadata[:follower_count] if comment.metadata
+
+# Private reply to a comment's author (Instagram/Facebook) — returns a Message
+message = client.comments.private_reply("post-id", "comment-id", profile_id: "profile-id", text: "DM-ing you the details.")
+puts message.chat_id, message.status
+```
+
+## Direct Messages
+
+Read and send 1:1 messages on DM-capable profiles (Facebook Messenger, Instagram, Telegram, Bluesky). A conversation is a **Chat**; it holds **Messages**. Outbound sends are processed asynchronously (`status` starts as `pending`).
+
+```ruby
+# List chats for a profile (paginated, most recent first)
+chats = client.chats.list("profile-id", per_page: 20)
+chats.data.each { |chat| puts "#{chat.participant_username}: #{chat.last_message_at}" }
+
+# Find or create a chat with a participant (idempotent)
+chat = client.chats.create("profile-id", "igsid_8675309", participant_username: "jane_doe")
+
+# Get a single chat
+chat = client.chats.get(chat.id)
+
+# List messages in a chat (filter by direction/status)
+messages = client.messages.list(chat.id, direction: "inbound")
+messages.data.each do |msg|
+  puts "#{msg.direction}: #{msg.body}"
+  msg.attachments.each { |att| puts "  #{att.url}" }
+end
+
+# Send a text message (within the 24h window)
+sent = client.messages.send(chat.id, body: "Yes, we ship worldwide!")
+
+# Send outside the 24h window with a tag (Facebook/Instagram)
+client.messages.send(chat.id, body: "Following up.", tag: "HUMAN_AGENT")
+
+# Send media — by hosted URL or local file
+client.messages.send(chat.id, media: ["https://cdn.example.com/photo.png"])
+client.messages.send(chat.id, media_files: ["./photo.png"])
+
+# Telegram: reply threading + inline keyboard
+client.messages.send(
+  chat.id,
+  body: "Pick one:",
+  reply_markup: { inline_keyboard: [[{ text: "Track order", callback_data: "track:1" }]] }
+)
+
+# Get / edit (Telegram only) a message
+msg = client.messages.get(sent.id)
+client.messages.edit(sent.id, body: "Updated answer.")
+
+# React / unreact (Facebook & Instagram)
+client.messages.react(sent.id, reaction: "love", emoji: "❤️")
+client.messages.unreact(sent.id)
+
+# Archive / unarchive a chat (Bluesky only)
+client.chats.archive(chat.id)
+client.chats.unarchive(chat.id)
+
+# Private reply to a comment's author (Instagram/Facebook) — returns a Message
+message = client.comments.private_reply("post-id", "comment-id", profile_id: "profile-id", text: "DM-ing you the details.")
+puts message.chat_id, message.status
 ```
 
 ## Profile comments (Google Business reviews)

data/lib/postproxy/client.rb

@@ -8,6 +8,8 @@ require_relative "resources/webhooks"
 require_relative "resources/queues"
 require_relative "resources/comments"
 require_relative "resources/profile_comments"
+require_relative "resources/chats"
+require_relative "resources/messages"
 
 module PostProxy
   class Client
@@ -25,6 +27,8 @@ module PostProxy
       @queues = nil
       @comments = nil
       @profile_comments = nil
+      @chats = nil
+      @messages = nil
     end
 
     def posts
@@ -55,6 +59,14 @@ module PostProxy
       @profile_comments ||= Resources::ProfileComments.new(self)
     end
 
+    def chats
+      @chats ||= Resources::Chats.new(self)
+    end
+
+    def messages
+      @messages ||= Resources::Messages.new(self)
+    end
+
     def request(method, path, params: nil, json: nil, data: nil, files: nil, profile_group_id: nil)
       url = "/api#{path}"
 

data/lib/postproxy/constants.rb

@@ -32,6 +32,10 @@ module PostProxy
 
   TELEGRAM_PARSE_MODES = %w[HTML MarkdownV2].freeze
 
+  MESSAGE_DIRECTIONS = %w[inbound outbound].freeze
+
+  MESSAGE_STATUSES = %w[pending published failed_waiting_for_retry failed received].freeze
+
   WEBHOOK_EVENT_TYPES = %w[
     post.processed
     post.imported
@@ -44,5 +48,15 @@ module PostProxy
     profile.stats
     media.failed
     comment.created
+    profile_comment.created
+    message.received
+    message.sent
+    message.delivered
+    message.read
+    message.edited
+    message.deleted
+    message.failed_waiting_for_retry
+    message.failed
+    reaction.received
   ].freeze
 end

data/lib/postproxy/resources/chats.rb

@@ -0,0 +1,57 @@
+module PostProxy
+  module Resources
+    class Chats
+      def initialize(client)
+        @client = client
+      end
+
+      def list(profile_id, page: nil, per_page: nil, before: nil, after: nil, profile_group_id: nil)
+        params = {}
+        params[:page] = page if page
+        params[:per_page] = per_page if per_page
+        params[:before] = format_time(before) if before
+        params[:after] = format_time(after) if after
+
+        result = @client.request(:get, "/profiles/#{profile_id}/chats", params: params, profile_group_id: profile_group_id)
+        chats = (result[:data] || []).map { |c| Chat.new(**c) }
+        PaginatedResponse.new(
+          data: chats,
+          total: result[:total],
+          page: result[:page],
+          per_page: result[:per_page]
+        )
+      end
+
+      def create(profile_id, participant_external_id, participant_username: nil, participant_name: nil, profile_group_id: nil)
+        json_body = { participant_external_id: participant_external_id }
+        json_body[:participant_username] = participant_username if participant_username
+        json_body[:participant_name] = participant_name if participant_name
+
+        result = @client.request(:post, "/profiles/#{profile_id}/chats", json: json_body, profile_group_id: profile_group_id)
+        Chat.new(**result)
+      end
+
+      def get(chat_id, profile_group_id: nil)
+        result = @client.request(:get, "/chats/#{chat_id}", profile_group_id: profile_group_id)
+        Chat.new(**result)
+      end
+
+      def archive(chat_id, profile_group_id: nil)
+        result = @client.request(:post, "/chats/#{chat_id}/archive", profile_group_id: profile_group_id)
+        Chat.new(**result)
+      end
+
+      def unarchive(chat_id, profile_group_id: nil)
+        result = @client.request(:delete, "/chats/#{chat_id}/archive", profile_group_id: profile_group_id)
+        Chat.new(**result)
+      end
+
+      private
+
+      def format_time(value)
+        return value if value.is_a?(String)
+        value.iso8601
+      end
+    end
+  end
+end

data/lib/postproxy/resources/comments.rb

@@ -57,6 +57,14 @@ module PostProxy
         result = @client.request(:post, "/posts/#{post_id}/comments/#{comment_id}/unlike", params: { profile_id: profile_id })
         AcceptedResponse.new(**result)
       end
+
+      def private_reply(post_id, comment_id, profile_id:, text:)
+        result = @client.request(:post, "/posts/#{post_id}/comments/#{comment_id}/private_reply",
+          params: { profile_id: profile_id },
+          json: { text: text }
+        )
+        Message.new(**result)
+      end
     end
   end
 end

data/lib/postproxy/resources/messages.rb

@@ -0,0 +1,118 @@
+module PostProxy
+  module Resources
+    class Messages
+      def initialize(client)
+        @client = client
+      end
+
+      def list(chat_id, page: nil, per_page: nil, direction: nil, status: nil, profile_group_id: nil)
+        params = {}
+        params[:page] = page if page
+        params[:per_page] = per_page if per_page
+        params[:direction] = direction if direction
+        params[:status] = status if status
+
+        result = @client.request(:get, "/chats/#{chat_id}/messages", params: params, profile_group_id: profile_group_id)
+        messages = (result[:data] || []).map { |m| Message.new(**m) }
+        PaginatedResponse.new(
+          data: messages,
+          total: result[:total],
+          page: result[:page],
+          per_page: result[:per_page]
+        )
+      end
+
+      def send_message(chat_id, body: nil, media: nil, media_files: nil, tag: nil,
+                       reply_to_external_id: nil, reply_markup: nil, profile_group_id: nil)
+        has_files = media_files && !media_files.empty?
+
+        if has_files
+          form_data = {}
+          form_data["body"] = body if body
+          form_data["tag"] = tag if tag
+          form_data["reply_to_external_id"] = reply_to_external_id if reply_to_external_id
+
+          files = []
+          media&.each do |m|
+            files << ["media[]", nil, m, "text/plain"]
+          end
+          media_files.each do |path|
+            path = path.to_s
+            filename = File.basename(path)
+            content_type = mime_type_for(filename)
+            io = File.open(path, "rb")
+            files << ["media[]", filename, io, content_type]
+          end
+
+          result = @client.request(:post, "/chats/#{chat_id}/messages",
+            data: form_data,
+            files: files,
+            profile_group_id: profile_group_id
+          )
+        else
+          json_body = {}
+          json_body[:body] = body if body
+          json_body[:media] = media if media
+          json_body[:tag] = tag if tag
+          json_body[:reply_to_external_id] = reply_to_external_id if reply_to_external_id
+          json_body[:reply_markup] = reply_markup if reply_markup
+
+          result = @client.request(:post, "/chats/#{chat_id}/messages", json: json_body, profile_group_id: profile_group_id)
+        end
+
+        Message.new(**result)
+      end
+      alias_method :send, :send_message
+
+      def get(message_id, profile_group_id: nil)
+        result = @client.request(:get, "/messages/#{message_id}", profile_group_id: profile_group_id)
+        Message.new(**result)
+      end
+
+      def edit(message_id, body: nil, reply_markup: nil, profile_group_id: nil)
+        json_body = {}
+        json_body[:body] = body if body
+        json_body[:reply_markup] = reply_markup if reply_markup
+
+        result = @client.request(:patch, "/messages/#{message_id}", json: json_body, profile_group_id: profile_group_id)
+        Message.new(**result)
+      end
+
+      def react(message_id, reaction: nil, emoji: nil, profile_group_id: nil)
+        json_body = {}
+        json_body[:reaction] = reaction if reaction
+        json_body[:emoji] = emoji if emoji
+
+        result = @client.request(:post, "/messages/#{message_id}/react",
+          json: json_body.empty? ? nil : json_body,
+          profile_group_id: profile_group_id
+        )
+        Message.new(**result)
+      end
+
+      def unreact(message_id, profile_group_id: nil)
+        result = @client.request(:delete, "/messages/#{message_id}/unreact", profile_group_id: profile_group_id)
+        Message.new(**result)
+      end
+
+      private
+
+      def mime_type_for(filename)
+        case File.extname(filename).downcase
+        when ".jpg", ".jpeg" then "image/jpeg"
+        when ".png" then "image/png"
+        when ".gif" then "image/gif"
+        when ".webp" then "image/webp"
+        when ".mp4" then "video/mp4"
+        when ".mov" then "video/quicktime"
+        when ".avi" then "video/x-msvideo"
+        when ".webm" then "video/webm"
+        when ".mp3" then "audio/mpeg"
+        when ".ogg" then "audio/ogg"
+        when ".m4a" then "audio/mp4"
+        else "application/octet-stream"
+        end
+      end
+    end
+  end
+end

data/lib/postproxy/types.rb

@@ -307,25 +307,59 @@ module PostProxy
     end
   end
 
+  class Attachment < Model
+    attr_accessor :id, :type, :url, :status, :external_id
+
+    def initialize(**attrs)
+      @url = nil
+      @external_id = nil
+      super
+    end
+  end
+
+  class Reaction < Model
+    attr_accessor :sender_external_id, :emoji, :reaction, :at
+
+    def initialize(**attrs)
+      @emoji = nil
+      @reaction = nil
+      @at = nil
+      super
+      @at = parse_time(@at)
+    end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil?
+      value.is_a?(Time) ? value : Time.parse(value.to_s)
+    end
+  end
+
   class Comment < Model
     attr_accessor :id, :external_id, :body, :status, :author_username,
-                  :author_avatar_url, :author_external_id, :parent_external_id,
-                  :like_count, :is_hidden, :permalink, :platform_data,
-                  :posted_at, :created_at, :replies
+                  :author_avatar_url, :author_external_id, :metadata,
+                  :parent_external_id, :like_count, :is_hidden, :permalink,
+                  :platform_data, :attachments, :posted_at, :created_at, :replies
 
     def initialize(**attrs)
       @external_id = nil
       @author_avatar_url = nil
       @author_external_id = nil
+      @metadata = nil
       @parent_external_id = nil
       @like_count = 0
       @is_hidden = false
       @permalink = nil
       @platform_data = nil
+      @attachments = []
       @replies = []
       super
       @posted_at = parse_time(@posted_at)
       @created_at = parse_time(@created_at)
+      @attachments = (@attachments || []).map do |a|
+        a.is_a?(Attachment) ? a : Attachment.new(**a.transform_keys(&:to_sym))
+      end
       @replies = (@replies || []).map do |r|
         r.is_a?(Comment) ? r : Comment.new(**r.transform_keys(&:to_sym))
       end
@@ -339,6 +373,85 @@ module PostProxy
     end
   end
 
+  class Chat < Model
+    attr_accessor :id, :profile_id, :platform, :participant_external_id,
+                  :participant_username, :participant_name, :participant_avatar_url,
+                  :external_conversation_id, :last_inbound_at, :last_outbound_at,
+                  :last_message_at, :metadata, :archived, :created_at
+
+    def initialize(**attrs)
+      @participant_username = nil
+      @participant_name = nil
+      @participant_avatar_url = nil
+      @external_conversation_id = nil
+      @last_inbound_at = nil
+      @last_outbound_at = nil
+      @last_message_at = nil
+      @metadata = nil
+      @archived = nil
+      super
+      @last_inbound_at = parse_time(@last_inbound_at)
+      @last_outbound_at = parse_time(@last_outbound_at)
+      @last_message_at = parse_time(@last_message_at)
+      @created_at = parse_time(@created_at)
+    end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil?
+      value.is_a?(Time) ? value : Time.parse(value.to_s)
+    end
+  end
+
+  class Message < Model
+    attr_accessor :id, :chat_id, :external_id, :direction, :body, :status,
+                  :tag, :external_comment_id, :error_message, :platform_data,
+                  :external_posted_at, :external_delivered_at, :external_read_at,
+                  :external_edited_at, :reply_to_external_id, :reply_markup,
+                  :external_deleted_at, :reactions, :attachments,
+                  :is_unsupported, :created_at
+
+    def initialize(**attrs)
+      @external_id = nil
+      @body = nil
+      @tag = nil
+      @external_comment_id = nil
+      @error_message = nil
+      @platform_data = nil
+      @external_posted_at = nil
+      @external_delivered_at = nil
+      @external_read_at = nil
+      @external_edited_at = nil
+      @reply_to_external_id = nil
+      @reply_markup = nil
+      @external_deleted_at = nil
+      @reactions = []
+      @attachments = []
+      @is_unsupported = false
+      super
+      @external_posted_at = parse_time(@external_posted_at)
+      @external_delivered_at = parse_time(@external_delivered_at)
+      @external_read_at = parse_time(@external_read_at)
+      @external_edited_at = parse_time(@external_edited_at)
+      @external_deleted_at = parse_time(@external_deleted_at)
+      @created_at = parse_time(@created_at)
+      @reactions = (@reactions || []).map do |r|
+        r.is_a?(Reaction) ? r : Reaction.new(**r.transform_keys(&:to_sym))
+      end
+      @attachments = (@attachments || []).map do |a|
+        a.is_a?(Attachment) ? a : Attachment.new(**a.transform_keys(&:to_sym))
+      end
+    end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil?
+      value.is_a?(Time) ? value : Time.parse(value.to_s)
+    end
+  end
+
   class ProfileComment < Model
     attr_accessor :id, :external_id, :parent_external_id, :placement_id,
                   :body, :status, :author_username, :author_avatar_url,

data/lib/postproxy/version.rb

@@ -1,3 +1,3 @@
 module PostProxy
-  VERSION = "1.9.0"
+  VERSION = "1.10.0"
 end

data/lib/postproxy/webhook_events.rb

@@ -71,6 +71,35 @@ module PostProxy
                     :platform_data, :posted_at, :created_at
     end
 
+    class MessageEventData < Model
+      attr_accessor :message
+
+      def initialize(**attrs)
+        @message = nil
+        super
+        @message = Message.new(**@message.transform_keys(&:to_sym)) if @message.is_a?(Hash)
+      end
+    end
+
+    class ReactionEventData < Model
+      attr_accessor :message, :sender_external_id, :action, :reaction, :emoji, :occurred_at
+
+      def initialize(**attrs)
+        @message = nil
+        @reaction = nil
+        @emoji = nil
+        @occurred_at = nil
+        super
+        @message = Message.new(**@message.transform_keys(&:to_sym)) if @message.is_a?(Hash)
+      end
+    end
+
+    class ProfileCommentCreatedData < Model
+      attr_accessor :id, :profile_id, :platform, :placement_id, :external_id,
+                    :parent_external_id, :body, :status, :author_username,
+                    :author_avatar_url, :platform_data, :posted_at, :created_at
+    end
+
     DATA_CLASSES = {
       "post.processed" => PostProcessedData,
       "post.imported" => PostImportedData,
@@ -82,7 +111,17 @@ module PostProxy
       "profile.disconnected" => ProfileEventData,
       "profile.stats" => ProfileStatsData,
       "media.failed" => MediaFailedData,
-      "comment.created" => CommentCreatedData
+      "comment.created" => CommentCreatedData,
+      "profile_comment.created" => ProfileCommentCreatedData,
+      "message.received" => MessageEventData,
+      "message.sent" => MessageEventData,
+      "message.delivered" => MessageEventData,
+      "message.read" => MessageEventData,
+      "message.edited" => MessageEventData,
+      "message.deleted" => MessageEventData,
+      "message.failed_waiting_for_retry" => MessageEventData,
+      "message.failed" => MessageEventData,
+      "reaction.received" => ReactionEventData
     }.freeze
 
     # Parse a webhook body and return a typed Event. `data` is parsed into the

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: postproxy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.10.0
 platform: ruby
 authors:
 - PostProxy
@@ -78,7 +78,9 @@ files:
 - lib/postproxy/client.rb
 - lib/postproxy/constants.rb
 - lib/postproxy/errors.rb
+- lib/postproxy/resources/chats.rb
 - lib/postproxy/resources/comments.rb
+- lib/postproxy/resources/messages.rb
 - lib/postproxy/resources/posts.rb
 - lib/postproxy/resources/profile_comments.rb
 - lib/postproxy/resources/profile_groups.rb