postproxy-sdk 1.6.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e62e2ba2b3d951aed31a2d60d74a7ee4a46672b03131676f28d81f6dc5cade69
-  data.tar.gz: 83bf66f3dae825b04195d1ec9e809849352f4c290dbf2d1458879a1838688e93
+  metadata.gz: 1d2f9ae8cbbc2ca3cd324b5dc522226c9d7a77cd93430abb309b31efc210a293
+  data.tar.gz: 26c58e5f9b7ea1af4eccb3935ef8c71bf202bf5bff93898d0b30a5450114bb1a
 SHA512:
-  metadata.gz: 2b38044c1990d12a5d937b261df5b01e80d3cec44caaebd0eeb4eb9038859bb2428c35c6f557421ba8a5cc494347e4e08de7963d98d8ff1ad552960cbcd02dae
-  data.tar.gz: 5f3393e61377f4de158148d7c4de2982df376410cc377bdd356d478729bf129a86b5659ea0abc412a4809a55a343dde7b59e4e8ee11ff6957630f7475957286d
+  metadata.gz: 906800719560c2e37351c958fa72449d1411b351c1cad4deb0d312e9b6fcaa3af3be3dcb504eeef045a3d24737815afb4e7f772edae4687e102e2f9d4bd605cc
+  data.tar.gz: b6ee51b608b91a9d31ed2891b7bba87df996006be1795504f540e275dd54c8ff3b7ef7e5f1994a7aa495a02f67ec8f3921e9017baadb3e1e8d3c5550d6959b06

data/README.md

@@ -105,6 +105,18 @@ post.thread.each { |child| puts "#{child.id}: #{child.body}" }
 
 # Delete a post
 client.posts.delete("post-id")
+
+# Delete a post and also remove it from social platforms
+client.posts.delete("post-id", delete_on_platform: true)
+
+# Delete from platforms only (keeps DB record). Defaults to all platforms.
+client.posts.delete_on_platform("post-id")
+# Target a single network
+client.posts.delete_on_platform("post-id", network: "twitter")
+# Target a specific profile
+client.posts.delete_on_platform("post-id", profile_id: "prof-abc")
+# Target a specific post profile (covers entire thread for that profile)
+client.posts.delete_on_platform("post-id", post_profile_id: "pp-abc")
 ```
 
 ## Post Stats
@@ -248,6 +260,26 @@ PostProxy::WebhookSignature.verify(
 )
 ```
 
+### Event types and typed payloads
+
+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`.
+
+`PostProxy::WebhookEvents.parse` validates the envelope and returns a typed `Event` — `event.data` is the right model for the event:
+
+```ruby
+event = PostProxy::WebhookEvents.parse(request.body.read)
+case event.type
+when "profile.stats"
+  puts "#{event.data.profile_id}: #{event.data.stats}"
+when "platform_post.published"
+  puts "Published: #{event.data.platform_id}"
+when "comment.created"
+  puts "#{event.data.author_username}: #{event.data.body}"
+end
+```
+
 ## Comments
 
 ```ruby
@@ -299,6 +331,19 @@ placements = client.profiles.placements("prof-id").data
 
 # Delete a profile
 client.profiles.delete("prof-id")
+
+# Profile stats timeseries — placement_id required for facebook, linkedin, telegram
+stats = client.profiles.get_profile_stats("prof_li_001",
+  placement_id: "108520199",
+  from: "2026-04-01T00:00:00Z"
+)
+stats.data.records.each do |r|
+  puts "#{r.recorded_at}: #{r.stats[:followerCount]}"
+end
+
+# Bluesky — no placements
+bsky = client.profiles.get_profile_stats("prof_bsky_001")
+puts bsky.data.records.last.stats[:followersCount]
 ```
 
 ## Profile Groups
@@ -323,6 +368,28 @@ connection = client.profile_groups.initialize_connection(
   redirect_url: "https://myapp.com/callback"
 )
 # Redirect user to connection.url
+
+# BlueSky — app password (synchronous, no OAuth)
+bsky = client.profile_groups.connect_bluesky("pg-id",
+  identifier: "yourname.bsky.social",
+  app_password: "xxxx-xxxx-xxxx-xxxx"
+)
+puts bsky.profile.id
+
+# Telegram — bring-your-own-bot. Channels populate asynchronously; poll
+# placements until non-empty.
+tg = client.profile_groups.connect_telegram("pg-id",
+  bot_token: "123456789:ABCdef-GhIJklMnOpQrStUvWxYz"
+)
+puts tg.next_step
+
+placements = []
+loop do
+  placements = client.profiles.placements(tg.profile.id).data
+  break unless placements.empty?
+  sleep 3
+end
+puts "Channels: #{placements.map { |p| [p.id, p.name] }}"
 ```
 
 ## Platform Parameters
@@ -352,7 +419,13 @@ platforms = PostProxy::PlatformParams.new(
     board_id: "board-123"
   ),
   threads: PostProxy::ThreadsParams.new(format: "post"),
-  twitter: PostProxy::TwitterParams.new(format: "post")
+  twitter: PostProxy::TwitterParams.new(format: "post"),
+  bluesky: PostProxy::BlueskyParams.new(format: "post"),
+  telegram: PostProxy::TelegramParams.new(
+    chat_id: "-1001234567890",
+    parse_mode: "HTML",
+    disable_link_preview: true
+  )
 )
 
 post = client.posts.create(
@@ -362,6 +435,8 @@ post = client.posts.create(
 )
 ```
 
+Supported platforms: `facebook`, `instagram`, `tiktok`, `linkedin`, `youtube`, `twitter`, `threads`, `pinterest`, `bluesky`, `telegram`. Telegram requires a `chat_id` per post — list channels with `client.profiles.placements(profile_id)`.
+
 ## Error Handling
 
 ```ruby

data/lib/postproxy/client.rb

@@ -99,11 +99,16 @@ module PostProxy
 
     private
 
+    def user_agent
+      @user_agent ||= "postproxy-ruby/#{PostProxy::VERSION} (ruby/#{RUBY_VERSION})"
+    end
+
     def json_connection
       @faraday_client || Faraday.new(url: @base_url) do |f|
         f.request :url_encoded
         f.headers["Authorization"] = "Bearer #{@api_key}"
         f.headers["Content-Type"] = "application/json"
+        f.headers["User-Agent"] = user_agent
         f.adapter Faraday.default_adapter
       end
     end
@@ -112,6 +117,7 @@ module PostProxy
       @faraday_client || Faraday.new(url: @base_url) do |f|
         f.request :multipart
         f.headers["Authorization"] = "Bearer #{@api_key}"
+        f.headers["User-Agent"] = user_agent
         f.adapter Faraday.default_adapter
       end
     end

data/lib/postproxy/constants.rb

@@ -2,7 +2,7 @@ module PostProxy
   DEFAULT_BASE_URL = "https://api.postproxy.dev"
 
   PLATFORMS = %w[
-    facebook instagram tiktok linkedin youtube twitter threads pinterest
+    facebook instagram tiktok linkedin youtube twitter threads pinterest bluesky telegram
   ].freeze
 
   PROFILE_STATUSES = %w[active expired inactive].freeze
@@ -21,10 +21,28 @@ module PostProxy
   PINTEREST_FORMATS = %w[pin].freeze
   THREADS_FORMATS = %w[post].freeze
   TWITTER_FORMATS = %w[post].freeze
+  BLUESKY_FORMATS = %w[post].freeze
+  TELEGRAM_FORMATS = %w[post].freeze
 
   TIKTOK_PRIVACIES = %w[
     PUBLIC_TO_EVERYONE MUTUAL_FOLLOW_FRIENDS FOLLOWER_OF_CREATOR SELF_ONLY
   ].freeze
 
   YOUTUBE_PRIVACIES = %w[public unlisted private].freeze
+
+  TELEGRAM_PARSE_MODES = %w[HTML MarkdownV2].freeze
+
+  WEBHOOK_EVENT_TYPES = %w[
+    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
+  ].freeze
 end

data/lib/postproxy/resources/posts.rb

@@ -38,6 +38,8 @@ module PostProxy
           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?
+          form_data["queue_id"] = queue_id if queue_id
+          form_data["queue_priority"] = queue_priority if queue_priority
 
           files = []
 
@@ -116,6 +118,8 @@ module PostProxy
           form_data["post[body]"] = body if body
           form_data["post[scheduled_at]"] = format_time(scheduled_at) if scheduled_at
           form_data["post[draft]"] = draft.to_s if !draft.nil?
+          form_data["queue_id"] = queue_id if queue_id
+          form_data["queue_priority"] = queue_priority if queue_priority
 
           files = []
 
@@ -205,11 +209,28 @@ module PostProxy
         StatsResponse.new(data: posts)
       end
 
-      def delete(id, profile_group_id: nil)
-        result = @client.request(:delete, "/posts/#{id}", profile_group_id: profile_group_id)
+      def delete(id, delete_on_platform: nil, profile_group_id: nil)
+        params = {}
+        params[:delete_on_platform] = delete_on_platform unless delete_on_platform.nil?
+        result = @client.request(:delete, "/posts/#{id}",
+          params: params.empty? ? nil : params,
+          profile_group_id: profile_group_id
+        )
         DeleteResponse.new(**result)
       end
 
+      def delete_on_platform(id, post_profile_id: nil, profile_id: nil, network: nil, profile_group_id: nil)
+        json_body = {}
+        json_body[:post_profile_id] = post_profile_id if post_profile_id
+        json_body[:profile_id] = profile_id if profile_id
+        json_body[:network] = network if network
+        result = @client.request(:post, "/posts/#{id}/delete_on_platform",
+          json: json_body.empty? ? nil : json_body,
+          profile_group_id: profile_group_id
+        )
+        DeleteOnPlatformResponse.new(**result)
+      end
+
       private
 
       def format_time(value)

data/lib/postproxy/resources/profile_groups.rb

@@ -26,11 +26,28 @@ module PostProxy
         DeleteResponse.new(**result)
       end
 
-      def initialize_connection(id, platform:, redirect_url:)
+      # OAuth flow. BlueSky and Telegram use their dedicated helpers below.
+      def initialize_connection(id, platform:, redirect_url: nil)
+        body = { platform: platform }
+        body[:redirect_url] = redirect_url if redirect_url
+        result = @client.request(:post, "/profile_groups/#{id}/initialize_connection", json: body)
+        ConnectionResponse.new(**result)
+      end
+
+      def connect_bluesky(id, identifier:, app_password:)
         result = @client.request(:post, "/profile_groups/#{id}/initialize_connection",
-          json: { platform: platform, redirect_url: redirect_url }
+          json: { platform: "bluesky", identifier: identifier, app_password: app_password }
         )
-        ConnectionResponse.new(**result)
+        BlueskyConnectionResponse.new(**result)
+      end
+
+      # After this call, poll `client.profiles.placements(profile.id)` until non-empty —
+      # the bot must be added as administrator to a channel in Telegram first.
+      def connect_telegram(id, bot_token:)
+        result = @client.request(:post, "/profile_groups/#{id}/initialize_connection",
+          json: { platform: "telegram", bot_token: bot_token }
+        )
+        TelegramConnectionResponse.new(**result)
       end
     end
   end

data/lib/postproxy/resources/profiles.rb

@@ -22,6 +22,20 @@ module PostProxy
         ListResponse.new(data: items)
       end
 
+      # `placement_id` is required for facebook, linkedin, and telegram profiles.
+      def get_profile_stats(id, placement_id: nil, from: nil, to: nil, profile_group_id: nil)
+        params = {}
+        params[:placement_id] = placement_id if placement_id
+        params[:from] = from if from
+        params[:to] = to if to
+
+        result = @client.request(:get, "/profiles/#{id}/stats",
+          params: params.empty? ? nil : params,
+          profile_group_id: profile_group_id
+        )
+        ProfileStatsResponse.new(data: result[:data])
+      end
+
       def delete(id, profile_group_id: nil)
         result = @client.request(:delete, "/profiles/#{id}", profile_group_id: profile_group_id)
         SuccessResponse.new(**result)

data/lib/postproxy/types.rb

@@ -63,17 +63,31 @@ module PostProxy
     end
   end
 
+  class ErrorDetails < Model
+    attr_accessor :platform_error_code, :platform_error_subcode, :platform_error_message, :postproxy_note
+
+    def initialize(**attrs)
+      @platform_error_code = nil
+      @platform_error_subcode = nil
+      @platform_error_message = nil
+      @postproxy_note = nil
+      super
+    end
+  end
+
   class PlatformResult < Model
-    attr_accessor :platform, :status, :params, :error, :attempted_at, :insights
+    attr_accessor :platform, :status, :params, :error, :error_details, :attempted_at, :insights
 
     def initialize(**attrs)
       @params = nil
       @error = nil
+      @error_details = nil
       @attempted_at = nil
       @insights = nil
       super
       @attempted_at = parse_time(@attempted_at)
       @insights = Insights.new(**@insights) if @insights.is_a?(Hash)
+      @error_details = ErrorDetails.new(**@error_details.transform_keys(&:to_sym)) if @error_details.is_a?(Hash)
     end
 
     private
@@ -316,14 +330,80 @@ module PostProxy
     attr_accessor :deleted
   end
 
+  class DeletingPlatform < Model
+    attr_accessor :post_profile_id, :platform
+  end
+
+  class DeleteOnPlatformResponse < Model
+    attr_accessor :success, :deleting
+
+    def initialize(**attrs)
+      @deleting = []
+      super
+      @deleting = (@deleting || []).map do |entry|
+        entry.is_a?(DeletingPlatform) ? entry : DeletingPlatform.new(**entry)
+      end
+    end
+  end
+
   class SuccessResponse < Model
     attr_accessor :success
   end
 
+  # OAuth-style connection response (facebook, instagram, twitter, etc.).
   class ConnectionResponse < Model
     attr_accessor :url, :success
   end
 
+  # Alias for clarity at call sites; same shape as ConnectionResponse.
+  OAuthConnectionResponse = ConnectionResponse
+
+  class SyncProfile < Model
+    attr_accessor :id, :network, :name, :external_username
+  end
+
+  class BlueskyConnectionResponse < Model
+    attr_accessor :success, :profile
+
+    def initialize(**attrs)
+      @profile = nil
+      super
+      @profile = SyncProfile.new(**@profile.transform_keys(&:to_sym)) if @profile.is_a?(Hash)
+    end
+  end
+
+  class TelegramConnectionResponse < Model
+    attr_accessor :success, :profile, :next_step
+
+    def initialize(**attrs)
+      @profile = nil
+      @next_step = nil
+      super
+      @profile = SyncProfile.new(**@profile.transform_keys(&:to_sym)) if @profile.is_a?(Hash)
+    end
+  end
+
+  class ProfileStats < Model
+    attr_accessor :profile_id, :platform, :placement_id, :records
+
+    def initialize(**attrs)
+      @placement_id = nil
+      @records = []
+      super
+      @records = (@records || []).map do |r|
+        r.is_a?(StatsRecord) ? r : StatsRecord.new(**r.transform_keys(&:to_sym))
+      end
+    end
+  end
+
+  class ProfileStatsResponse
+    attr_reader :data
+
+    def initialize(data:)
+      @data = data.is_a?(ProfileStats) ? data : ProfileStats.new(**data.transform_keys(&:to_sym))
+    end
+  end
+
   # Platform-specific parameter structs
 
   class FacebookParams < Model
@@ -346,7 +426,8 @@ module PostProxy
   end
 
   class YouTubeParams < Model
-    attr_accessor :format, :title, :privacy_status, :cover_url, :made_for_kids
+    attr_accessor :format, :title, :privacy_status, :cover_url, :made_for_kids,
+                  :tags, :category_id, :contains_synthetic_media
   end
 
   class PinterestParams < Model
@@ -361,13 +442,21 @@ module PostProxy
     attr_accessor :format
   end
 
+  class BlueskyParams < Model
+    attr_accessor :format
+  end
+
+  class TelegramParams < Model
+    attr_accessor :format, :chat_id, :parse_mode, :disable_link_preview, :disable_notification
+  end
+
   class PlatformParams < Model
     attr_accessor :facebook, :instagram, :tiktok, :linkedin, :youtube,
-                  :pinterest, :threads, :twitter
+                  :pinterest, :threads, :twitter, :bluesky, :telegram
 
     def to_h
       result = {}
-      %i[facebook instagram tiktok linkedin youtube pinterest threads twitter].each do |platform|
+      %i[facebook instagram tiktok linkedin youtube pinterest threads twitter bluesky telegram].each do |platform|
         value = send(platform)
         next if value.nil?
 

data/lib/postproxy/version.rb

@@ -1,3 +1,3 @@
 module PostProxy
-  VERSION = "1.6.0"
+  VERSION = "1.8.0"
 end

data/lib/postproxy/webhook_events.rb

@@ -0,0 +1,113 @@
+require "json"
+
+module PostProxy
+  class WebhookParseError < StandardError; end
+
+  module WebhookEvents
+    class Event < Model
+      attr_accessor :id, :type, :created_at, :data
+    end
+
+    class PostProcessedPlatform < Model
+      attr_accessor :id, :platform, :name
+    end
+
+    class PostProcessedData < Model
+      attr_accessor :id, :body, :status, :scheduled_at, :created_at, :platforms
+
+      def initialize(**attrs)
+        @platforms = []
+        super
+        @platforms = (@platforms || []).map do |p|
+          p.is_a?(PostProcessedPlatform) ? p : PostProcessedPlatform.new(**p.transform_keys(&:to_sym))
+        end
+      end
+    end
+
+    class ImportedProfile < Model
+      attr_accessor :id, :name, :platform
+    end
+
+    class PostImportedData < Model
+      attr_accessor :id, :body, :source, :posted_at, :created_at,
+                    :platform, :profile, :platform_post_id, :public_id
+
+      def initialize(**attrs)
+        @profile = nil
+        super
+        @profile = ImportedProfile.new(**@profile.transform_keys(&:to_sym)) if @profile.is_a?(Hash)
+      end
+    end
+
+    class PlatformPostData < Model
+      attr_accessor :id, :post_id, :platform, :profile_id, :profile_name,
+                    :status, :error, :error_details, :platform_id, :insights
+
+      def initialize(**attrs)
+        @error_details = nil
+        @insights = nil
+        super
+        @error_details = ErrorDetails.new(**@error_details.transform_keys(&:to_sym)) if @error_details.is_a?(Hash)
+      end
+    end
+
+    class ProfileEventData < Model
+      attr_accessor :id, :name, :platform, :profile_group_id, :status, :uid, :username
+    end
+
+    class ProfileStatsData < Model
+      attr_accessor :profile_id, :platform, :placement_id, :stats, :recorded_at
+    end
+
+    class MediaFailedData < Model
+      attr_accessor :id, :post_id, :content_type, :status, :error_message
+    end
+
+    class CommentCreatedData < Model
+      attr_accessor :id, :post_id, :platform_post_id, :platform, :external_id,
+                    :parent_external_id, :body, :status, :author_external_id,
+                    :author_name, :author_username, :author_avatar_url,
+                    :like_count, :reply_count, :is_hidden, :permalink,
+                    :platform_data, :posted_at, :created_at
+    end
+
+    DATA_CLASSES = {
+      "post.processed" => PostProcessedData,
+      "post.imported" => PostImportedData,
+      "platform_post.published" => PlatformPostData,
+      "platform_post.failed" => PlatformPostData,
+      "platform_post.failed_waiting_for_retry" => PlatformPostData,
+      "platform_post.insights" => PlatformPostData,
+      "profile.connected" => ProfileEventData,
+      "profile.disconnected" => ProfileEventData,
+      "profile.stats" => ProfileStatsData,
+      "media.failed" => MediaFailedData,
+      "comment.created" => CommentCreatedData
+    }.freeze
+
+    # Parse a webhook body and return a typed Event. `data` is parsed into the
+    # appropriate model based on `type`. Raises WebhookParseError on bad input.
+    def self.parse(body)
+      parsed =
+        case body
+        when String then JSON.parse(body, symbolize_names: true)
+        when Hash then body.transform_keys(&:to_sym)
+        else raise WebhookParseError, "Webhook body must be a String or Hash"
+        end
+    rescue JSON::ParserError => e
+      raise WebhookParseError, "Invalid JSON: #{e.message}"
+    else
+      type = parsed[:type].to_s
+      raise WebhookParseError, "Unknown webhook event type: #{type.inspect}" unless DATA_CLASSES.key?(type)
+
+      data_class = DATA_CLASSES[type]
+      data_hash = (parsed[:data] || {}).transform_keys(&:to_sym)
+      Event.new(
+        id: parsed[:id],
+        type: type,
+        created_at: parsed[:created_at],
+        data: data_class.new(**data_hash)
+      )
+    end
+  end
+end

data/lib/postproxy.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: postproxy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.8.0
 platform: ruby
 authors:
 - PostProxy
@@ -86,6 +86,7 @@ files:
 - lib/postproxy/resources/webhooks.rb
 - lib/postproxy/types.rb
 - lib/postproxy/version.rb
+- lib/postproxy/webhook_events.rb
 - lib/postproxy/webhook_signature.rb
 homepage: https://postproxy.dev
 licenses: