postproxy-sdk 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 822ce030b347645daad188e55da76ab9a3494b0f7f01d0b6a78a02b4c9e933d6
-  data.tar.gz: 33dc5d8cf8e97817b9f6f69d8f57dd4dfd207ff1b8add0ba58661cddfd88f64f
+  metadata.gz: 665c9b0d7745b0da8ae0bd7864047997816bfa532725ee338588b94f1e6e9724
+  data.tar.gz: d9ebae2aa90d310886561d4ec4b2da268a2dcd6d341b59343c1661c3429b656c
 SHA512:
-  metadata.gz: 8460f568b415ec00973fa57d9065a85a141fe16aafb430765054ae51ca0ee16c514a55c02f59c54b7983def183c9131c07c65a5db448976f05d9db2139243915
-  data.tar.gz: 64c079b04bbd82dde18a2c612000ad42f8525351326714243c923dfde21bba6e51125006169a36675301b2fde2857f94c54e74cab08ae406345bf1dd8a26e711
+  metadata.gz: 32384b1c8ca96c498094d59530fd2617a542a911342ef969c93243f31da53afeb06a5d9de458413bfd0ef584c09c53a207743d0a217d49fb1dc097972e2e697e
+  data.tar.gz: 15c9e8c42a588f99fe9ef0eb93536c7206f3a90b16d75cd1648bb1497ec5fb3b9e00fae71de3abad3b2a4c2ca442c88aea54ba129b58f6d4dc283d8c9a07de0d

data/README.md

@@ -92,10 +92,111 @@ post = client.posts.create(
   scheduled_at: (Time.now + 3600).iso8601
 )
 
+# Create a thread post
+post = client.posts.create(
+  "Thread starts here",
+  profiles: ["prof-1"],
+  thread: [
+    { body: "Second post in the thread" },
+    { body: "Third with media", media: ["https://example.com/img.jpg"] },
+  ]
+)
+post.thread.each { |child| puts "#{child.id}: #{child.body}" }
+
 # Delete a post
 client.posts.delete("post-id")
 ```
 
+## Post Stats
+
+Retrieve stats snapshots for posts over time. Supports filtering by profiles/networks and timespan.
+
+```ruby
+# Get stats for one or more posts
+stats = client.posts.stats(["post-id-1", "post-id-2"])
+stats.data.each do |post_id, post_stats|
+  post_stats.platforms.each do |platform|
+    puts "#{post_id} on #{platform.platform} (#{platform.profile_id}):"
+    platform.records.each do |record|
+      puts "  #{record.recorded_at}: #{record.stats}"
+    end
+  end
+end
+
+# Filter by profiles or networks
+stats = client.posts.stats(["post-id"], profiles: ["instagram", "twitter"])
+
+# Filter by profile hashids
+stats = client.posts.stats(["post-id"], profiles: ["prof-abc", "prof-def"])
+
+# Filter by time range
+stats = client.posts.stats(
+  ["post-id"],
+  from: "2026-02-01T00:00:00Z",
+  to: "2026-02-24T00:00:00Z"
+)
+
+# Using Time objects
+stats = client.posts.stats(
+  ["post-id"],
+  from: Time.now - 86400 * 7,
+  to: Time.now
+)
+```
+
+Stats vary by platform:
+
+| Platform | Fields |
+|----------|--------|
+| Instagram | `impressions`, `likes`, `comments`, `saved`, `profile_visits`, `follows` |
+| Facebook | `impressions`, `clicks`, `likes` |
+| Threads | `impressions`, `likes`, `replies`, `reposts`, `quotes`, `shares` |
+| Twitter | `impressions`, `likes`, `retweets`, `comments`, `quotes`, `saved` |
+| YouTube | `impressions`, `likes`, `comments`, `saved` |
+| LinkedIn | `impressions` |
+| TikTok | `impressions`, `likes`, `comments`, `shares` |
+| Pinterest | `impressions`, `likes`, `comments`, `saved`, `outbound_clicks` |
+
+## Webhooks
+
+```ruby
+# List webhooks
+webhooks = client.webhooks.list.data
+
+# Get a webhook
+webhook = client.webhooks.get("wh-id")
+
+# Create a webhook
+webhook = client.webhooks.create(
+  "https://example.com/webhook",
+  events: ["post.published", "post.failed"],
+  description: "My webhook"
+)
+puts webhook.id, webhook.secret
+
+# Update a webhook
+webhook = client.webhooks.update("wh-id", events: ["post.published"], enabled: false)
+
+# Delete a webhook
+client.webhooks.delete("wh-id")
+
+# List deliveries
+deliveries = client.webhooks.deliveries("wh-id", page: 1, per_page: 10)
+deliveries.data.each { |d| puts "#{d.event_type}: #{d.success}" }
+```
+
+### Signature verification
+
+Verify incoming webhook signatures using HMAC-SHA256:
+
+```ruby
+PostProxy::WebhookSignature.verify(
+  payload: request.body.read,
+  signature_header: request.headers["X-PostProxy-Signature"],
+  secret: "whsec_..."
+)
+```
+
 ## Profiles
 
 ```ruby

data/lib/postproxy/client.rb

@@ -4,6 +4,7 @@ require "json"
 require_relative "resources/posts"
 require_relative "resources/profiles"
 require_relative "resources/profile_groups"
+require_relative "resources/webhooks"
 
 module PostProxy
   class Client
@@ -17,6 +18,7 @@ module PostProxy
       @posts = nil
       @profiles = nil
       @profile_groups = nil
+      @webhooks = nil
     end
 
     def posts
@@ -31,6 +33,10 @@ module PostProxy
       @profile_groups ||= Resources::ProfileGroups.new(self)
     end
 
+    def webhooks
+      @webhooks ||= Resources::Webhooks.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

@@ -7,7 +7,9 @@ module PostProxy
 
   PROFILE_STATUSES = %w[active expired inactive].freeze
 
-  POST_STATUSES = %w[pending draft processing processed scheduled].freeze
+  POST_STATUSES = %w[pending draft processing processed scheduled media_processing_failed].freeze
+
+  MEDIA_STATUSES = %w[pending processed failed].freeze
 
   PLATFORM_POST_STATUSES = %w[pending processing published failed deleted].freeze
 

data/lib/postproxy/resources/posts.rb

@@ -29,8 +29,11 @@ module PostProxy
       end
 
       def create(body, profiles:, media: nil, media_files: nil, platforms: nil,
-                 scheduled_at: nil, draft: nil, profile_group_id: nil)
-        if media_files && !media_files.empty?
+                 thread: nil, scheduled_at: nil, draft: nil, profile_group_id: nil)
+        has_files = media_files && !media_files.empty?
+        has_thread_files = thread&.any? { |t| t[:media_files]&.any? }
+
+        if has_files || has_thread_files
           form_data = { "post[body]" => body }
           form_data["post[scheduled_at]"] = format_time(scheduled_at) if scheduled_at
           form_data["post[draft]"] = draft.to_s if !draft.nil?
@@ -54,7 +57,7 @@ module PostProxy
             end
           end
 
-          media_files.each do |path|
+          media_files&.each do |path|
             path = path.to_s
             filename = File.basename(path)
             content_type = mime_type_for(filename)
@@ -62,6 +65,22 @@ module PostProxy
             files << ["media[]", filename, io, content_type]
           end
 
+          thread&.each_with_index do |t, i|
+            form_data["thread[#{i}][body]"] = t[:body] if t[:body]
+
+            t[:media]&.each do |m|
+              files << ["thread[#{i}][media][]", nil, m, "text/plain"]
+            end
+
+            t[: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 << ["thread[#{i}][media][]", filename, io, content_type]
+            end
+          end
+
           result = @client.request(:post, "/posts",
             data: form_data,
             files: files,
@@ -75,6 +94,7 @@ module PostProxy
           json_body = { post: post_payload, profiles: profiles }
           json_body[:platforms] = platforms.is_a?(PlatformParams) ? platforms.to_h : platforms if platforms
           json_body[:media] = media if media
+          json_body[:thread] = thread if thread
 
           result = @client.request(:post, "/posts", json: json_body, profile_group_id: profile_group_id)
         end
@@ -87,6 +107,19 @@ module PostProxy
         Post.new(**result)
       end
 
+      def stats(post_ids, profiles: nil, from: nil, to: nil)
+        params = { post_ids: post_ids.is_a?(Array) ? post_ids.join(",") : post_ids }
+        params[:profiles] = profiles.is_a?(Array) ? profiles.join(",") : profiles if profiles
+        params[:from] = format_time(from) if from
+        params[:to] = format_time(to) if to
+
+        result = @client.request(:get, "/posts/stats", params: params)
+        posts = (result[:data] || {}).each_with_object({}) do |(post_id, post_data), hash|
+          hash[post_id.to_s] = PostStats.new(**post_data.transform_keys(&:to_sym))
+        end
+        StatsResponse.new(data: posts)
+      end
+
       def delete(id, profile_group_id: nil)
         result = @client.request(:delete, "/posts/#{id}", profile_group_id: profile_group_id)
         DeleteResponse.new(**result)

data/lib/postproxy/resources/webhooks.rb

@@ -0,0 +1,59 @@
+module PostProxy
+  module Resources
+    class Webhooks
+      def initialize(client)
+        @client = client
+      end
+
+      def list
+        result = @client.request(:get, "/webhooks")
+        webhooks = (result[:data] || []).map { |w| Webhook.new(**w) }
+        ListResponse.new(data: webhooks)
+      end
+
+      def get(id)
+        result = @client.request(:get, "/webhooks/#{id}")
+        Webhook.new(**result)
+      end
+
+      def create(url, events:, description: nil)
+        json_body = { url: url, events: events }
+        json_body[:description] = description if description
+
+        result = @client.request(:post, "/webhooks", json: json_body)
+        Webhook.new(**result)
+      end
+
+      def update(id, url: nil, events: nil, enabled: nil, description: nil)
+        json_body = {}
+        json_body[:url] = url unless url.nil?
+        json_body[:events] = events unless events.nil?
+        json_body[:enabled] = enabled unless enabled.nil?
+        json_body[:description] = description unless description.nil?
+
+        result = @client.request(:patch, "/webhooks/#{id}", json: json_body)
+        Webhook.new(**result)
+      end
+
+      def delete(id)
+        result = @client.request(:delete, "/webhooks/#{id}")
+        DeleteResponse.new(**result)
+      end
+
+      def deliveries(id, page: nil, per_page: nil)
+        params = {}
+        params[:page] = page if page
+        params[:per_page] = per_page if per_page
+
+        result = @client.request(:get, "/webhooks/#{id}/deliveries", params: params)
+        deliveries = (result[:data] || []).map { |d| WebhookDelivery.new(**d) }
+        PaginatedResponse.new(
+          data: deliveries,
+          total: result[:total],
+          page: result[:page],
+          per_page: result[:per_page]
+        )
+      end
+    end
+  end
+end

data/lib/postproxy/types.rb

@@ -84,18 +84,89 @@ module PostProxy
     end
   end
 
+  class Media < Model
+    attr_accessor :id, :status, :error_message, :content_type, :source_url, :url
+
+    def initialize(**attrs)
+      @error_message = nil
+      @source_url = nil
+      @url = nil
+      super
+    end
+  end
+
+  class ThreadChild < Model
+    attr_accessor :id, :body, :media
+
+    def initialize(**attrs)
+      @media = []
+      super
+      @media = (@media || []).map do |m|
+        m.is_a?(Media) ? m : Media.new(**m.transform_keys(&:to_sym))
+      end
+    end
+  end
+
   class Post < Model
-    attr_accessor :id, :body, :status, :scheduled_at, :created_at, :platforms
+    attr_accessor :id, :body, :status, :scheduled_at, :created_at, :media, :platforms, :thread
 
     def initialize(**attrs)
       @scheduled_at = nil
+      @media = []
       @platforms = []
+      @thread = []
       super
       @scheduled_at = parse_time(@scheduled_at)
       @created_at = parse_time(@created_at)
+      @media = (@media || []).map do |m|
+        m.is_a?(Media) ? m : Media.new(**m.transform_keys(&:to_sym))
+      end
       @platforms = (@platforms || []).map do |p|
         p.is_a?(PlatformResult) ? p : PlatformResult.new(**p.transform_keys(&:to_sym))
       end
+      @thread = (@thread || []).map do |t|
+        t.is_a?(ThreadChild) ? t : ThreadChild.new(**t.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 Webhook < Model
+    attr_accessor :id, :url, :events, :enabled, :description, :secret,
+                  :created_at, :updated_at
+
+    def initialize(**attrs)
+      @events = []
+      @description = nil
+      @secret = nil
+      super
+      @created_at = parse_time(@created_at)
+      @updated_at = parse_time(@updated_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 WebhookDelivery < Model
+    attr_accessor :id, :event_id, :event_type, :response_status,
+                  :attempt_number, :success, :attempted_at, :created_at
+
+    def initialize(**attrs)
+      @response_status = nil
+      super
+      @attempted_at = parse_time(@attempted_at)
+      @created_at = parse_time(@created_at)
     end
 
     private
@@ -110,6 +181,56 @@ module PostProxy
     attr_accessor :id, :name
   end
 
+  class StatsRecord < Model
+    attr_accessor :stats, :recorded_at
+
+    def initialize(**attrs)
+      @stats = {}
+      @recorded_at = nil
+      super
+      @recorded_at = parse_time(@recorded_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 PlatformStats < Model
+    attr_accessor :profile_id, :platform, :records
+
+    def initialize(**attrs)
+      @records = []
+      super
+      @records = (@records || []).map do |r|
+        r.is_a?(StatsRecord) ? r : StatsRecord.new(**r.transform_keys(&:to_sym))
+      end
+    end
+  end
+
+  class PostStats < Model
+    attr_accessor :platforms
+
+    def initialize(**attrs)
+      @platforms = []
+      super
+      @platforms = (@platforms || []).map do |p|
+        p.is_a?(PlatformStats) ? p : PlatformStats.new(**p.transform_keys(&:to_sym))
+      end
+    end
+  end
+
+  class StatsResponse
+    attr_reader :data
+
+    def initialize(data:)
+      @data = data
+    end
+  end
+
   class ListResponse
     attr_reader :data
 
@@ -163,7 +284,7 @@ module PostProxy
   end
 
   class YouTubeParams < Model
-    attr_accessor :format, :title, :privacy_status, :cover_url
+    attr_accessor :format, :title, :privacy_status, :cover_url, :made_for_kids
   end
 
   class PinterestParams < Model

data/lib/postproxy/version.rb

@@ -1,3 +1,3 @@
 module PostProxy
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

data/lib/postproxy/webhook_signature.rb

@@ -0,0 +1,28 @@
+require "openssl"
+
+module PostProxy
+  module WebhookSignature
+    def self.verify(payload, signature_header, secret)
+      parts = signature_header.split(",").map { |p| p.split("=", 2) }.to_h
+      timestamp = parts["t"]
+      expected = parts["v1"]
+
+      return false if timestamp.nil? || expected.nil?
+
+      signed_payload = "#{timestamp}.#{payload}"
+      computed = OpenSSL::HMAC.hexdigest("SHA256", secret, signed_payload)
+
+      secure_compare(computed, expected)
+    end
+
+    private_class_method def self.secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      l = a.unpack("C*")
+      r = b.unpack("C*")
+      result = 0
+      l.zip(r) { |x, y| result |= x ^ y }
+      result.zero?
+    end
+  end
+end

data/lib/postproxy.rb

@@ -3,6 +3,7 @@ require_relative "postproxy/constants"
 require_relative "postproxy/errors"
 require_relative "postproxy/types"
 require_relative "postproxy/client"
+require_relative "postproxy/webhook_signature"
 
 module PostProxy
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: postproxy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - PostProxy
@@ -81,8 +81,10 @@ files:
 - lib/postproxy/resources/posts.rb
 - lib/postproxy/resources/profile_groups.rb
 - lib/postproxy/resources/profiles.rb
+- lib/postproxy/resources/webhooks.rb
 - lib/postproxy/types.rb
 - lib/postproxy/version.rb
+- lib/postproxy/webhook_signature.rb
 homepage: https://postproxy.dev
 licenses:
 - MIT