postproxy-sdk 1.7.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0aea2892ef3d3256dfd1cc9ce790da283df1d6edb83a2cfcaa76c0aa8a8194ae
-  data.tar.gz: a9f008666d47832963cc7119d0db1b53d53c7ddd3dc690fa13acebc05c72f5f6
+  metadata.gz: 7b20d20d7dc1f6a386e74894a57e470c70a1edc3e95bcd61c3b25f02b3e457cd
+  data.tar.gz: 6fd6807bcbbd09fae222ccd07eee0d66cbb420bc04e83fd49ab98c4340a4ed82
 SHA512:
-  metadata.gz: c9f6cf9ec0d398081c84c21c41824bd590fa9d57b7e8eea423512bcc899b82d3df93c4532edf307e2f949a0d72217e6677743b36434a4384e9b9d801030b4aa4
-  data.tar.gz: 325923dc017d840f212edac1941f2f2aa8d8821594f2418e40dee1e1b56a8f103627ab1f8cb9adb07f576afcc8fe5a6b431fcc408a50c4ac6887948bf80426d6
+  metadata.gz: c5e18b59805d1aff449eb7e3b8227bd2290b85994ba8e14f38b1c945381facd37a1b77e218d9eaf3c3e8c3183eade0da5268eb86b79762ad1aa9606b015a8e6a
+  data.tar.gz: ec5a37899a8c3622212e5d7d2b43a540df1e7aff64f9ea99a17a3fd1b0ed1e332a44a7c568eef24882f70fba267fe18302581d9af999ed997651df368dca59cc

data/README.md

@@ -260,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
@@ -297,6 +317,32 @@ client.comments.like("post-id", "comment-id", profile_id: "profile-id")
 client.comments.unlike("post-id", "comment-id", profile_id: "profile-id")
 ```
 
+## Profile comments (Google Business reviews)
+
+Profile-level comments expose Google Business reviews and replies. Reviews are user-generated — the SDK lets you list/get them and reply to or delete your own replies. Reviews sync twice daily.
+
+```ruby
+# List reviews for a profile (paginated)
+reviews = client.profile_comments.list("profile-id")
+reviews.data.each do |review|
+  rating = (review.platform_data || {})[:star_rating]
+  puts "#{review.author_username} #{rating}: #{review.body}"
+  review.replies.each { |r| puts "  reply: #{r.body}" }
+end
+
+# Filter by placement (location)
+reviews = client.profile_comments.list("profile-id", placement_id: "accounts/123/locations/456")
+
+# Get a single review
+review = client.profile_comments.get("profile-id", "review-id")
+
+# Reply to a review (parent_id is the review id)
+reply = client.profile_comments.create("profile-id", parent_id: "review-id", text: "Thanks for visiting!")
+
+# Delete your reply
+client.profile_comments.delete("profile-id", "reply-id")
+```
+
 ## Profiles
 
 ```ruby
@@ -311,6 +357,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
@@ -335,6 +394,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
@@ -364,7 +445,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(
@@ -374,6 +461,28 @@ post = client.posts.create(
 )
 ```
 
+Supported platforms: `facebook`, `instagram`, `tiktok`, `linkedin`, `youtube`, `twitter`, `threads`, `pinterest`, `bluesky`, `telegram`, `google_business`. Telegram requires a `chat_id` per post — list channels with `client.profiles.placements(profile_id)`.
+
+### Google Business
+
+Google Business posts use a `google_business` entry in `PlatformParams` (a plain hash; no typed struct). The `location_id` is the location resource path returned by `client.profiles.placements()`. Supported formats: `standard`, `event`, `offer`. CTA actions: `LEARN_MORE`, `BOOK`, `ORDER`, `SHOP`, `SIGN_UP`, `CALL`. Media is limited to one image (≤5 MB).
+
+```ruby
+client.posts.create(
+  "Now open weekends!",
+  ["gbp-profile-id"],
+  media: ["https://example.com/store.jpg"],
+  platforms: {
+    google_business: {
+      format: "standard",
+      location_id: "accounts/123/locations/456",
+      cta_action_type: "LEARN_MORE",
+      cta_url: "https://example.com"
+    }
+  }
+)
+```
+
 ## Error Handling
 
 ```ruby

data/lib/postproxy/client.rb

@@ -7,6 +7,7 @@ require_relative "resources/profile_groups"
 require_relative "resources/webhooks"
 require_relative "resources/queues"
 require_relative "resources/comments"
+require_relative "resources/profile_comments"
 
 module PostProxy
   class Client
@@ -23,6 +24,7 @@ module PostProxy
       @webhooks = nil
       @queues = nil
       @comments = nil
+      @profile_comments = nil
     end
 
     def posts
@@ -49,6 +51,10 @@ module PostProxy
       @comments ||= Resources::Comments.new(self)
     end
 
+    def profile_comments
+      @profile_comments ||= Resources::ProfileComments.new(self)
+    end
+
     def request(method, path, params: nil, json: nil, data: nil, files: nil, profile_group_id: nil)
       url = "/api#{path}"
 
@@ -99,11 +105,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 +123,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 google_business
   ].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/profile_comments.rb

@@ -0,0 +1,41 @@
+module PostProxy
+  module Resources
+    class ProfileComments
+      def initialize(client)
+        @client = client
+      end
+
+      def list(profile_id, placement_id: nil, page: nil, per_page: nil)
+        params = {}
+        params[:placement_id] = placement_id if placement_id
+        params[:page] = page if page
+        params[:per_page] = per_page if per_page
+
+        result = @client.request(:get, "/profiles/#{profile_id}/comments", params: params)
+        comments = (result[:data] || []).map { |c| ProfileComment.new(**c) }
+        PaginatedResponse.new(
+          data: comments,
+          total: result[:total],
+          page: result[:page],
+          per_page: result[:per_page]
+        )
+      end
+
+      def get(profile_id, comment_id)
+        result = @client.request(:get, "/profiles/#{profile_id}/comments/#{comment_id}")
+        ProfileComment.new(**result)
+      end
+
+      def create(profile_id, parent_id:, text:)
+        result = @client.request(:post, "/profiles/#{profile_id}/comments",
+                                 json: { parent_id: parent_id, text: text })
+        ProfileComment.new(**result)
+      end
+
+      def delete(profile_id, comment_id)
+        result = @client.request(:delete, "/profiles/#{profile_id}/comments/#{comment_id}")
+        AcceptedResponse.new(**result)
+      end
+    end
+  end
+end

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

@@ -98,14 +98,31 @@ module PostProxy
     end
   end
 
+  class MediaPlatformError < Model
+    attr_accessor :platform, :status, :error, :error_details
+
+    def initialize(**attrs)
+      @error = nil
+      @error_details = nil
+      super
+      @error_details = ErrorDetails.new(**@error_details.transform_keys(&:to_sym)) if @error_details.is_a?(Hash)
+    end
+  end
+
   class Media < Model
-    attr_accessor :id, :status, :error_message, :content_type, :source_url, :url
+    attr_accessor :id, :status, :error_message, :content_type, :source_url, :url, :platforms
 
     def initialize(**attrs)
       @error_message = nil
       @source_url = nil
       @url = nil
+      @platforms = nil
       super
+      if @platforms.is_a?(Array)
+        @platforms = @platforms.map do |p|
+          p.is_a?(MediaPlatformError) ? p : MediaPlatformError.new(**p.transform_keys(&:to_sym))
+        end
+      end
     end
   end
 
@@ -322,6 +339,33 @@ module PostProxy
     end
   end
 
+  class ProfileComment < Model
+    attr_accessor :id, :external_id, :parent_external_id, :placement_id,
+                  :body, :status, :author_username, :author_avatar_url,
+                  :platform_data, :posted_at, :created_at, :replies
+
+    def initialize(**attrs)
+      @parent_external_id = nil
+      @author_username = nil
+      @author_avatar_url = nil
+      @platform_data = nil
+      @replies = []
+      super
+      @posted_at = parse_time(@posted_at)
+      @created_at = parse_time(@created_at)
+      @replies = (@replies || []).map do |r|
+        r.is_a?(ProfileComment) ? r : ProfileComment.new(**r.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 AcceptedResponse < Model
     attr_accessor :accepted
   end
@@ -350,10 +394,60 @@ module PostProxy
     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
@@ -392,13 +486,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, :google_business
 
     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 google_business].each do |platform|
         value = send(platform)
         next if value.nil?
 

data/lib/postproxy/version.rb

@@ -1,3 +1,3 @@
 module PostProxy
-  VERSION = "1.7.0"
+  VERSION = "1.9.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.7.0
+  version: 1.9.0
 platform: ruby
 authors:
 - PostProxy
@@ -80,12 +80,14 @@ files:
 - lib/postproxy/errors.rb
 - lib/postproxy/resources/comments.rb
 - lib/postproxy/resources/posts.rb
+- lib/postproxy/resources/profile_comments.rb
 - lib/postproxy/resources/profile_groups.rb
 - lib/postproxy/resources/profiles.rb
 - lib/postproxy/resources/queues.rb
 - 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: