postproxy-sdk 1.11.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c459486395f3eed2f4199f1946ed7a71c7b6b5de5ae270e46b088e779c772459
-  data.tar.gz: 38788f6fd45363f0c229af3cd7fd28a79a21511d1a7b8c4c417bb2d0c5c93f48
+  metadata.gz: 9fabdc6a06ca3cef409cf88533c925ff183e3e1c7089fd53aa541c09bff0aa6f
+  data.tar.gz: 7b4245a53e37aab93f006d408430676dbe3352a8815e5479de765946d941e20e
 SHA512:
-  metadata.gz: 8458cc1ca2c4bd873fe980d9b18db5d81b2871c3d027f914a0555ce686cbca1daba5400464f2a950ceb2ba3602657d6e2bf1daa5d5d23c891addbdc0c5b2c54b
-  data.tar.gz: 3b9fa99981232895852351741ebdaf2cf5675d585b298100bb29ae1fdca054f67b6e16d9e909ba1db6a15f2fda1b0b06a69f37f6443eceb2680af253e0ca27a3
+  metadata.gz: 97e32211fa2f54a2a28b506333108a484153083efcf9272bcf23fc821e27e6e2e88be7dd7d166acf6f9cd339a69a07afd1fb9b9f3c271a860b8ec9f5b41b7a9e
+  data.tar.gz: 3217e3f75dd540a6c13215dc5a5b7830d483ebd38f4cd30433162e7c732f69b214b06e3f73ccfbe5683f953a9c57133bf9dd1de4bdaf4ffe5dc3a631c15a132e

data/README.md

@@ -50,6 +50,36 @@ end
 client = PostProxy::Client.new("your-api-key", faraday_client: faraday)
 ```
 
+### Idempotency
+
+Every write method (`POST`/`PUT`/`PATCH`/`DELETE`) accepts an `idempotency_key:`, sent as
+the `Idempotency-Key` header. If the connection drops before you see the response, retry
+with the same key and you get the original response back instead of a second post:
+
+```ruby
+require "securerandom"
+
+key = SecureRandom.uuid
+post = client.posts.create("Hello", profiles: ["profile-id"], idempotency_key: key)
+
+# Retrying the same call with the same key replays the original response.
+```
+
+Generate a fresh key per logical operation — a UUID is ideal. Keys are scoped to your
+account and may be up to 255 characters. The SDK never generates keys or retries for you.
+
+| Situation | Result |
+|---|---|
+| First request with the key | Runs normally |
+| Retry after a success | Original status and body replayed |
+| Retry while the first is still running | `ConflictError` (409) — wait and retry |
+| Same key, different request body | `ValidationError` (422) |
+| Retry after an error response | Runs normally — errors are not replayed |
+
+Only successful (`2xx`) responses are stored, so a request that failed validation or hit a
+quota leaves the key free — fix the payload and retry with the same key. Stored responses
+are kept for **24 hours**. Requests without a key are unaffected.
+
 ## Posts
 
 ```ruby
@@ -306,6 +336,15 @@ end
 # List with pagination
 comments = client.comments.list("post-id", profile_id: "profile-id", page: 2, per_page: 10)
 
+# Filter by when PostProxy received the comment (created_at, not posted_at).
+# A bare date means that date's start of day. Applies to top-level comments —
+# one in range brings its full replies array with it.
+recent = client.comments.list("post-id",
+  profile_id: "profile-id",
+  from: "2026-03-25",
+  to: "2026-03-26T12:00:00Z"
+)
+
 # Get a single comment
 comment = client.comments.get("post-id", "comment-id", profile_id: "profile-id")
 
@@ -337,6 +376,38 @@ message = client.comments.private_reply("post-id", "comment-id", profile_id: "pr
 puts message.chat_id, message.status
 ```
 
+### Comments across posts
+
+`comments.list_all` returns comments spanning every post in the profile group in one
+request — the comments counterpart to `posts.stats`. Every filter is optional.
+
+**This list is flat.** Unlike the per-post list, replies are not nested: every comment,
+top-level or reply, is its own entry linked to its parent by `parent_external_id`, so
+`total` counts every comment and paging is exact.
+
+```ruby
+all = client.comments.list_all(
+  profiles: ["instagram", "prof-abc"],  # profile IDs or network names, mixed
+  post_ids: ["post-1", "post-2"],       # omit for every post in scope
+  from: "2026-03-25",
+  per_page: 50                          # max 100
+)
+
+all.data.each do |c|
+  # Each entry says where it came from, so you can act on it with the
+  # post-scoped methods above.
+  puts "#{c.platform} #{c.post_id} #{c.profile_id}: #{c.body}"
+  puts "  ↳ reply to #{c.parent_external_id}" if c.parent_external_id
+end
+
+# Reply to one of them
+first = all.data.first
+client.comments.create(first.post_id, "Thanks!", profile_id: first.profile_id, parent_id: first.id)
+```
+
+Unknown or out-of-scope IDs in `post_ids` and `profiles` are ignored rather than erroring.
+Results are ordered newest first by receipt time.
+
 ## 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`).
@@ -466,6 +537,81 @@ bsky = client.profiles.get_profile_stats("prof_bsky_001")
 puts bsky.data.records.last.stats[:followersCount]
 ```
 
+Every stats record (post stats and profile stats alike) carries `raw_stats` alongside the
+normalized `stats`, exposing each metric under its **original platform name**:
+
+```ruby
+stats = client.posts.stats(["post-id"])
+record = stats.data["post-id"].platforms.first.records.first
+
+puts record.stats[:impressions]          # normalized
+puts record.raw_stats[:views]            # Instagram's own name
+puts record.raw_stats[:impression_count] # Twitter/X's own name
+```
+
+LinkedIn post stats now normalize `likes`, `comments`, `shares`, and `clicks` alongside
+`impressions` — previously only `impressions` was normalized.
+
+### Post syncs & backfill
+
+PostProxy mirrors posts published natively on a platform into your account. Every one of
+those pulls is recorded as a **post sync**: the one fired when the profile connects, the
+recurring poll, and any backfill you start.
+
+```ruby
+# Start a backfill — walks the feed backwards from the newest post in batches
+# of 25 until it reaches `from` or the platform stops returning posts.
+sync = client.profiles.backfill_posts("prof-id", from: "2025-01-01")
+puts sync.id, sync.status # => "sync456def" "pending"
+
+# Poll it to completion — finished when status is "completed" or "failed"
+run = client.profiles.post_sync("prof-id", sync.id)
+puts "#{run.posts_imported} of #{run.posts_seen}, back to #{run.oldest_posted_at}"
+
+# List recent runs (kept for 30 days), newest first
+runs = client.profiles.post_syncs("prof-id",
+  trigger: "backfill",   # connect | scheduled | backfill
+  status: "completed",   # pending | running | completed | failed
+  per_page: 25
+)
+```
+
+| `PostSync` field | Description |
+|---|---|
+| `id` | Sync identifier |
+| `profile_id` | Profile this run belongs to |
+| `kind` | Always `posts` today |
+| `trigger` | `connect`, `scheduled`, or `backfill` |
+| `status` | `pending`, `running`, `completed`, or `failed` |
+| `started_at` / `completed_at` | `Time` or `nil` |
+| `posts_seen` | Posts the platform returned across the run |
+| `posts_imported` | Posts that were **new** and got created |
+| `backfill_from` | The date floor requested; `nil` for `connect`/`scheduled` |
+| `oldest_posted_at` | Publish date of the oldest post the run reached |
+| `error` | Platform error message when `status` is `"failed"` |
+| `created_at` | `Time` |
+
+**How far back a backfill reaches depends on the platform's API**, not on PostProxy: where
+history is pageable we follow it, otherwise the run ends early with whatever it got and
+still reports `status == "completed"`.
+
+Only one backfill runs per profile at a time — starting a second raises `ConflictError`
+carrying the running one's id:
+
+```ruby
+begin
+  client.profiles.backfill_posts("prof-id", from: "2025-01-01")
+rescue PostProxy::ConflictError => e
+  running_id = e.response[:profile_sync_id]
+  # Poll the run that's already going.
+end
+```
+
+Posts you already have are skipped, so overlapping backfills are safe. Imported posts
+behave exactly like ones the poll picks up (`source: "imported"`, `post.imported`
+webhook), but a backfill's follow-up work is queued at a lower priority so a deep run
+can't slow down publishing.
+
 ## Profile Groups
 
 ```ruby
@@ -560,6 +706,43 @@ 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)`.
 
+### Instagram user tags
+
+Tag public Instagram accounts in a post — feed post, reel, or story:
+
+```ruby
+client.posts.create(
+  "Shot on location",
+  profiles: ["ig-profile-id"],
+  media: [
+    "https://example.com/1.jpg",
+    "https://example.com/2.jpg",
+    "https://example.com/3.mp4"
+  ],
+  platforms: PostProxy::PlatformParams.new(
+    instagram: PostProxy::InstagramParams.new(
+      format: "post",
+      user_tags: [
+        { username: "natgeo", x: 0.5, y: 0.4 },               # slide 0
+        { username: "nasa", x: 0.2, y: 0.8, media_index: 1 },  # slide 1
+        { username: "spacex", media_index: 2 }                 # video — username only
+      ]
+    )
+  )
+)
+```
+
+- **Images require `x` and `y`** — floats `0.0`–`1.0` measured from the top-left corner.
+- **Reels and video slides** are tagged by username only; coordinates are ignored and dropped.
+- **Stories** accept coordinates but don't need them.
+- `media_index` picks the carousel slide (0-based, defaults to `0`, video slides included).
+- A leading `@` on a username is stripped for you.
+
+Coordinates outside `0.0`–`1.0`, a `media_index` past the last media item, or an image tag
+missing `x`/`y` are rejected with a `ValidationError` naming the offending entry. Accounts
+that are private or have tagging turned off are silently skipped by Instagram at publish
+time.
+
 ### 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).
@@ -589,6 +772,10 @@ rescue PostProxy::AuthenticationError => e
   puts "Auth failed: #{e.message}"       # 401
 rescue PostProxy::NotFoundError => e
   puts "Not found: #{e.message}"          # 404
+rescue PostProxy::ConflictError => e
+  puts "Conflict: #{e.message}"           # 409
+  puts e.response[:duplicate_post_id]     # on a duplicate post
+  puts e.response[:profile_sync_id]       # on a backfill already running
 rescue PostProxy::ValidationError => e
   puts "Invalid: #{e.message}"            # 422
 rescue PostProxy::BadRequestError => e
@@ -599,6 +786,15 @@ rescue PostProxy::Error => e
 end
 ```
 
+| Status | Error | Raised for |
+|---|---|---|
+| 400 | `BadRequestError` | Missing required parameters |
+| 401 | `AuthenticationError` | Invalid, missing, or insufficient API key permissions |
+| 404 | `NotFoundError` | Resource does not exist or is not accessible |
+| 409 | `ConflictError` | Duplicate submission, a backfill already running, or an in-flight `Idempotency-Key` |
+| 422 | `ValidationError` | Validation failed |
+| 429 | `Error` | Posting rate limit reached |
+
 ## License
 
 MIT

data/lib/postproxy/client.rb

@@ -67,7 +67,8 @@ module PostProxy
       @messages ||= Resources::Messages.new(self)
     end
 
-    def request(method, path, params: nil, json: nil, data: nil, files: nil, profile_group_id: nil)
+    def request(method, path, params: nil, json: nil, data: nil, files: nil, profile_group_id: nil,
+      idempotency_key: nil)
       url = "/api#{path}"
 
       query = {}
@@ -102,12 +103,14 @@ module PostProxy
                    end
                    conn.send(method, url) do |req|
                      req.params = query unless query.empty?
+                     req.headers["Idempotency-Key"] = idempotency_key if idempotency_key
                      req.body = payload
                    end
                  else
                    conn = json_connection
                    conn.send(method, url) do |req|
                      req.params = query unless query.empty?
+                     req.headers["Idempotency-Key"] = idempotency_key if idempotency_key
                      req.body = json.to_json if json
                    end
                  end
@@ -160,6 +163,13 @@ module PostProxy
           status_code: response.status,
           response: body
         )
+      when 409
+        body = parse_error_body(response)
+        raise ConflictError.new(
+          error_message(body),
+          status_code: response.status,
+          response: body
+        )
       when 422
         body = parse_error_body(response)
         raise ValidationError.new(

data/lib/postproxy/errors.rb

@@ -11,6 +11,12 @@ module PostProxy
 
   class AuthenticationError < Error; end
   class NotFoundError < Error; end
+
+  # 409. Raised for a duplicate submission (`response[:duplicate_post_id]`), a
+  # backfill that is already running (`response[:profile_sync_id]`), or a
+  # request whose Idempotency-Key is still in flight.
+  class ConflictError < Error; end
+
   class ValidationError < Error; end
   class BadRequestError < Error; end
 end

data/lib/postproxy/resources/chats.rb

@@ -22,12 +22,17 @@ module PostProxy
         )
       end
 
-      def create(profile_id, participant_external_id, participant_username: nil, participant_name: nil, profile_group_id: nil)
+      def create(profile_id, participant_external_id, participant_username: nil, participant_name: nil,
+        profile_group_id: nil, idempotency_key: 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)
+        result = @client.request(:post, "/profiles/#{profile_id}/chats",
+          json: json_body,
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
+        )
         Chat.new(**result)
       end
 
@@ -36,13 +41,19 @@ module PostProxy
         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)
+      def archive(chat_id, profile_group_id: nil, idempotency_key: nil)
+        result = @client.request(:post, "/chats/#{chat_id}/archive",
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
+        )
         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)
+      def unarchive(chat_id, profile_group_id: nil, idempotency_key: nil)
+        result = @client.request(:delete, "/chats/#{chat_id}/archive",
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
+        )
         Chat.new(**result)
       end
 

data/lib/postproxy/resources/comments.rb

@@ -5,10 +5,15 @@ module PostProxy
         @client = client
       end
 
-      def list(post_id, profile_id:, page: nil, per_page: nil)
+      # `from` and `to` filter on when PostProxy received the comment
+      # (`created_at`), not the platform's `posted_at`. They apply to top-level
+      # comments — one in range brings its full `replies` array with it.
+      def list(post_id, profile_id:, page: nil, per_page: nil, from: nil, to: nil)
         params = { profile_id: profile_id }
         params[:page] = page if page
         params[:per_page] = per_page if per_page
+        params[:from] = from if from
+        params[:to] = to if to
 
         result = @client.request(:get, "/posts/#{post_id}/comments", params: params)
         comments = (result[:data] || []).map { |c| Comment.new(**c) }
@@ -20,48 +25,95 @@ module PostProxy
         )
       end
 
+      # Comments across every post in the profile group. Flat: replies come
+      # back as their own entries linked by `parent_external_id`, so `total`
+      # counts every comment. `profiles` takes profile IDs or network names,
+      # mixed.
+      def list_all(post_ids: nil, profiles: nil, from: nil, to: nil, page: nil, per_page: nil,
+        profile_group_id: nil)
+        params = {}
+        params[:post_ids] = Array(post_ids).join(",") if post_ids
+        params[:profiles] = Array(profiles).join(",") if profiles
+        params[:from] = from if from
+        params[:to] = to if to
+        params[:page] = page if page
+        params[:per_page] = per_page if per_page
+
+        result = @client.request(:get, "/comments",
+          params: params.empty? ? nil : params,
+          profile_group_id: profile_group_id
+        )
+        comments = (result[:data] || []).map { |c| BulkComment.new(**c) }
+        PaginatedResponse.new(
+          data: comments,
+          total: result[:total],
+          page: result[:page],
+          per_page: result[:per_page]
+        )
+      end
+
       def get(post_id, comment_id, profile_id:)
         result = @client.request(:get, "/posts/#{post_id}/comments/#{comment_id}", params: { profile_id: profile_id })
         Comment.new(**result)
       end
 
-      def create(post_id, text, profile_id:, parent_id: nil)
+      def create(post_id, text, profile_id:, parent_id: nil, idempotency_key: nil)
         json_body = { text: text }
         json_body[:parent_id] = parent_id if parent_id
 
-        result = @client.request(:post, "/posts/#{post_id}/comments", params: { profile_id: profile_id }, json: json_body)
+        result = @client.request(:post, "/posts/#{post_id}/comments",
+          params: { profile_id: profile_id },
+          json: json_body,
+          idempotency_key: idempotency_key
+        )
         Comment.new(**result)
       end
 
-      def delete(post_id, comment_id, profile_id:)
-        result = @client.request(:delete, "/posts/#{post_id}/comments/#{comment_id}", params: { profile_id: profile_id })
+      def delete(post_id, comment_id, profile_id:, idempotency_key: nil)
+        result = @client.request(:delete, "/posts/#{post_id}/comments/#{comment_id}",
+          params: { profile_id: profile_id },
+          idempotency_key: idempotency_key
+        )
         AcceptedResponse.new(**result)
       end
 
-      def hide(post_id, comment_id, profile_id:)
-        result = @client.request(:post, "/posts/#{post_id}/comments/#{comment_id}/hide", params: { profile_id: profile_id })
+      def hide(post_id, comment_id, profile_id:, idempotency_key: nil)
+        result = @client.request(:post, "/posts/#{post_id}/comments/#{comment_id}/hide",
+          params: { profile_id: profile_id },
+          idempotency_key: idempotency_key
+        )
         AcceptedResponse.new(**result)
       end
 
-      def unhide(post_id, comment_id, profile_id:)
-        result = @client.request(:post, "/posts/#{post_id}/comments/#{comment_id}/unhide", params: { profile_id: profile_id })
+      def unhide(post_id, comment_id, profile_id:, idempotency_key: nil)
+        result = @client.request(:post, "/posts/#{post_id}/comments/#{comment_id}/unhide",
+          params: { profile_id: profile_id },
+          idempotency_key: idempotency_key
+        )
         AcceptedResponse.new(**result)
       end
 
-      def like(post_id, comment_id, profile_id:)
-        result = @client.request(:post, "/posts/#{post_id}/comments/#{comment_id}/like", params: { profile_id: profile_id })
+      def like(post_id, comment_id, profile_id:, idempotency_key: nil)
+        result = @client.request(:post, "/posts/#{post_id}/comments/#{comment_id}/like",
+          params: { profile_id: profile_id },
+          idempotency_key: idempotency_key
+        )
         AcceptedResponse.new(**result)
       end
 
-      def unlike(post_id, comment_id, profile_id:)
-        result = @client.request(:post, "/posts/#{post_id}/comments/#{comment_id}/unlike", params: { profile_id: profile_id })
+      def unlike(post_id, comment_id, profile_id:, idempotency_key: nil)
+        result = @client.request(:post, "/posts/#{post_id}/comments/#{comment_id}/unlike",
+          params: { profile_id: profile_id },
+          idempotency_key: idempotency_key
+        )
         AcceptedResponse.new(**result)
       end
 
-      def private_reply(post_id, comment_id, profile_id:, text:)
+      def private_reply(post_id, comment_id, profile_id:, text:, idempotency_key: nil)
         result = @client.request(:post, "/posts/#{post_id}/comments/#{comment_id}/private_reply",
           params: { profile_id: profile_id },
-          json: { text: text }
+          json: { text: text },
+          idempotency_key: idempotency_key
         )
         Message.new(**result)
       end

data/lib/postproxy/resources/messages.rb

@@ -23,7 +23,8 @@ module PostProxy
       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)
+                       reply_to_external_id: nil, reply_markup: nil, profile_group_id: nil,
+                       idempotency_key: nil)
         has_files = media_files && !media_files.empty?
 
         if has_files
@@ -47,7 +48,8 @@ module PostProxy
           result = @client.request(:post, "/chats/#{chat_id}/messages",
             data: form_data,
             files: files,
-            profile_group_id: profile_group_id
+            profile_group_id: profile_group_id,
+            idempotency_key: idempotency_key
           )
         else
           json_body = {}
@@ -57,7 +59,11 @@ module PostProxy
           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)
+          result = @client.request(:post, "/chats/#{chat_id}/messages",
+            json: json_body,
+            profile_group_id: profile_group_id,
+            idempotency_key: idempotency_key
+          )
         end
 
         Message.new(**result)
@@ -69,29 +75,37 @@ module PostProxy
         Message.new(**result)
       end
 
-      def edit(message_id, body: nil, reply_markup: nil, profile_group_id: nil)
+      def edit(message_id, body: nil, reply_markup: nil, profile_group_id: nil, idempotency_key: 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)
+        result = @client.request(:patch, "/messages/#{message_id}",
+          json: json_body,
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
+        )
         Message.new(**result)
       end
 
-      def react(message_id, reaction: nil, emoji: nil, profile_group_id: nil)
+      def react(message_id, reaction: nil, emoji: nil, profile_group_id: nil, idempotency_key: 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
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
         )
         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)
+      def unreact(message_id, profile_group_id: nil, idempotency_key: nil)
+        result = @client.request(:delete, "/messages/#{message_id}/unreact",
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
+        )
         Message.new(**result)
       end
 

data/lib/postproxy/resources/posts.rb

@@ -30,7 +30,7 @@ module PostProxy
 
       def create(body, profiles:, media: nil, media_files: nil, platforms: nil,
                  thread: nil, scheduled_at: nil, draft: nil, queue_id: nil,
-                 queue_priority: nil, profile_group_id: nil)
+                 queue_priority: nil, profile_group_id: nil, idempotency_key: nil)
         has_files = media_files && !media_files.empty?
         has_thread_files = thread&.any? { |t| t[:media_files]&.any? }
 
@@ -87,7 +87,8 @@ module PostProxy
           result = @client.request(:post, "/posts",
             data: form_data,
             files: files,
-            profile_group_id: profile_group_id
+            profile_group_id: profile_group_id,
+            idempotency_key: idempotency_key
           )
         else
           post_payload = { body: body }
@@ -101,7 +102,11 @@ module PostProxy
           json_body[:queue_id] = queue_id if queue_id
           json_body[:queue_priority] = queue_priority if queue_priority
 
-          result = @client.request(:post, "/posts", json: json_body, profile_group_id: profile_group_id)
+          result = @client.request(:post, "/posts",
+            json: json_body,
+            profile_group_id: profile_group_id,
+            idempotency_key: idempotency_key
+          )
         end
 
         Post.new(**result)
@@ -109,7 +114,7 @@ module PostProxy
 
       def update(id, body: nil, profiles: nil, media: nil, media_files: nil, platforms: nil,
                  thread: nil, scheduled_at: nil, draft: nil, queue_id: nil,
-                 queue_priority: nil, profile_group_id: nil)
+                 queue_priority: nil, profile_group_id: nil, idempotency_key: nil)
         has_files = media_files && !media_files.empty?
         has_thread_files = thread&.any? { |t| t[:media_files]&.any? }
 
@@ -167,7 +172,8 @@ module PostProxy
           result = @client.request(:patch, "/posts/#{id}",
             data: form_data,
             files: files,
-            profile_group_id: profile_group_id
+            profile_group_id: profile_group_id,
+            idempotency_key: idempotency_key
           )
         else
           json_body = {}
@@ -185,14 +191,21 @@ module PostProxy
           json_body[:queue_id] = queue_id if queue_id
           json_body[:queue_priority] = queue_priority if queue_priority
 
-          result = @client.request(:patch, "/posts/#{id}", json: json_body, profile_group_id: profile_group_id)
+          result = @client.request(:patch, "/posts/#{id}",
+            json: json_body,
+            profile_group_id: profile_group_id,
+            idempotency_key: idempotency_key
+          )
         end
 
         Post.new(**result)
       end
 
-      def publish_draft(id, profile_group_id: nil)
-        result = @client.request(:post, "/posts/#{id}/publish", profile_group_id: profile_group_id)
+      def publish_draft(id, profile_group_id: nil, idempotency_key: nil)
+        result = @client.request(:post, "/posts/#{id}/publish",
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
+        )
         Post.new(**result)
       end
 
@@ -209,24 +222,27 @@ module PostProxy
         StatsResponse.new(data: posts)
       end
 
-      def delete(id, delete_on_platform: nil, profile_group_id: nil)
+      def delete(id, delete_on_platform: nil, profile_group_id: nil, idempotency_key: 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
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
         )
         DeleteResponse.new(**result)
       end
 
-      def delete_on_platform(id, post_profile_id: nil, profile_id: nil, network: nil, profile_group_id: nil)
+      def delete_on_platform(id, post_profile_id: nil, profile_id: nil, network: nil, profile_group_id: nil,
+        idempotency_key: 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
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
         )
         DeleteOnPlatformResponse.new(**result)
       end

data/lib/postproxy/resources/profile_comments.rb

@@ -26,14 +26,16 @@ module PostProxy
         ProfileComment.new(**result)
       end
 
-      def create(profile_id, parent_id:, text:)
+      def create(profile_id, parent_id:, text:, idempotency_key: nil)
         result = @client.request(:post, "/profiles/#{profile_id}/comments",
-                                 json: { parent_id: parent_id, text: text })
+                                 json: { parent_id: parent_id, text: text },
+                                 idempotency_key: idempotency_key)
         ProfileComment.new(**result)
       end
 
-      def delete(profile_id, comment_id)
-        result = @client.request(:delete, "/profiles/#{profile_id}/comments/#{comment_id}")
+      def delete(profile_id, comment_id, idempotency_key: nil)
+        result = @client.request(:delete, "/profiles/#{profile_id}/comments/#{comment_id}",
+                                 idempotency_key: idempotency_key)
         AcceptedResponse.new(**result)
       end
     end

data/lib/postproxy/resources/profile_groups.rb

@@ -16,13 +16,16 @@ module PostProxy
         ProfileGroup.new(**result)
       end
 
-      def create(name)
-        result = @client.request(:post, "/profile_groups", json: { name: name })
+      def create(name, idempotency_key: nil)
+        result = @client.request(:post, "/profile_groups",
+          json: { name: name },
+          idempotency_key: idempotency_key
+        )
         ProfileGroup.new(**result)
       end
 
-      def delete(id)
-        result = @client.request(:delete, "/profile_groups/#{id}")
+      def delete(id, idempotency_key: nil)
+        result = @client.request(:delete, "/profile_groups/#{id}", idempotency_key: idempotency_key)
         DeleteResponse.new(**result)
       end
 

data/lib/postproxy/resources/profiles.rb

@@ -39,17 +39,64 @@ module PostProxy
       # Moves a placement (e.g. a Facebook Page or Telegram channel) to another
       # profile group. `placement_id` is the placement's external ID as
       # returned by #placements.
-      def assign_placement_to_group(id, placement_id:, target_profile_group_id:, profile_group_id: nil)
+      def assign_placement_to_group(id, placement_id:, target_profile_group_id:, profile_group_id: nil,
+        idempotency_key: nil)
         result = @client.request(:patch, "/profiles/#{id}/assign_placement_to_group",
           json: {
             placement_id: placement_id,
             target_profile_group_id: target_profile_group_id
           },
-          profile_group_id: profile_group_id
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
         )
         Placement.new(**result)
       end
 
+      # Imports older posts from the platform. Walks the profile's feed
+      # backwards from the newest post until it reaches `from` or the platform
+      # stops returning posts. Runs in the background — poll #post_sync with
+      # the returned id for progress. Only one backfill runs per profile;
+      # starting a second raises ConflictError carrying the running one's
+      # `profile_sync_id`.
+      def backfill_posts(id, from:, profile_group_id: nil, idempotency_key: nil)
+        result = @client.request(:post, "/profiles/#{id}/backfill_posts",
+          json: { from: from },
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
+        )
+        PostSync.new(**result)
+      end
+
+      # Lists post sync runs, newest first. Runs are kept for 30 days.
+      def post_syncs(id, trigger: nil, status: nil, page: nil, per_page: nil, profile_group_id: nil)
+        params = {}
+        params[:trigger] = trigger if trigger
+        params[:status] = status if status
+        params[:page] = page if page
+        params[:per_page] = per_page if per_page
+
+        result = @client.request(:get, "/profiles/#{id}/post_syncs",
+          params: params.empty? ? nil : params,
+          profile_group_id: profile_group_id
+        )
+        syncs = (result[:data] || []).map { |s| PostSync.new(**s) }
+        PaginatedResponse.new(
+          data: syncs,
+          total: result[:total],
+          page: result[:page],
+          per_page: result[:per_page]
+        )
+      end
+
+      # Fetches a single run. Poll this to follow a backfill to completion —
+      # the run is finished when `status` is "completed" or "failed".
+      def post_sync(id, post_sync_id, profile_group_id: nil)
+        result = @client.request(:get, "/profiles/#{id}/post_syncs/#{post_sync_id}",
+          profile_group_id: profile_group_id
+        )
+        PostSync.new(**result)
+      end
+
       # Lists DM ice breakers. Supported for Instagram profiles only.
       def ice_breakers(id, profile_group_id: nil)
         result = @client.request(:get, "/profiles/#{id}/ice_breakers", profile_group_id: profile_group_id)
@@ -57,22 +104,29 @@ module PostProxy
       end
 
       # Replaces the DM ice breakers for a profile (1-4 items).
-      def set_ice_breakers(id, ice_breakers, profile_group_id: nil)
+      def set_ice_breakers(id, ice_breakers, profile_group_id: nil, idempotency_key: nil)
         items = ice_breakers.map { |ib| ib.is_a?(IceBreaker) ? ib.to_h : ib }
         result = @client.request(:post, "/profiles/#{id}/ice_breakers",
           json: { ice_breakers: items },
-          profile_group_id: profile_group_id
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
         )
         SuccessResponse.new(**result)
       end
 
-      def delete_ice_breakers(id, profile_group_id: nil)
-        result = @client.request(:delete, "/profiles/#{id}/ice_breakers", profile_group_id: profile_group_id)
+      def delete_ice_breakers(id, profile_group_id: nil, idempotency_key: nil)
+        result = @client.request(:delete, "/profiles/#{id}/ice_breakers",
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
+        )
         SuccessResponse.new(**result)
       end
 
-      def delete(id, profile_group_id: nil)
-        result = @client.request(:delete, "/profiles/#{id}", profile_group_id: profile_group_id)
+      def delete(id, profile_group_id: nil, idempotency_key: nil)
+        result = @client.request(:delete, "/profiles/#{id}",
+          profile_group_id: profile_group_id,
+          idempotency_key: idempotency_key
+        )
         SuccessResponse.new(**result)
       end
     end

data/lib/postproxy/resources/queues.rb

@@ -21,7 +21,8 @@ module PostProxy
         NextSlotResponse.new(**result)
       end
 
-      def create(name, profile_group_id:, description: nil, timezone: nil, jitter: nil, timeslots: nil)
+      def create(name, profile_group_id:, description: nil, timezone: nil, jitter: nil, timeslots: nil,
+        idempotency_key: nil)
         post_queue = { name: name }
         post_queue[:description] = description if description
         post_queue[:timezone] = timezone if timezone
@@ -33,11 +34,12 @@ module PostProxy
           post_queue: post_queue,
         }
 
-        result = @client.request(:post, "/post_queues", json: json_body)
+        result = @client.request(:post, "/post_queues", json: json_body, idempotency_key: idempotency_key)
         Queue.new(**result)
       end
 
-      def update(id, name: nil, description: nil, timezone: nil, enabled: nil, jitter: nil, timeslots: nil)
+      def update(id, name: nil, description: nil, timezone: nil, enabled: nil, jitter: nil, timeslots: nil,
+        idempotency_key: nil)
         post_queue = {}
         post_queue[:name] = name unless name.nil?
         post_queue[:description] = description unless description.nil?
@@ -48,12 +50,12 @@ module PostProxy
 
         json_body = { post_queue: post_queue }
 
-        result = @client.request(:patch, "/post_queues/#{id}", json: json_body)
+        result = @client.request(:patch, "/post_queues/#{id}", json: json_body, idempotency_key: idempotency_key)
         Queue.new(**result)
       end
 
-      def delete(id)
-        result = @client.request(:delete, "/post_queues/#{id}")
+      def delete(id, idempotency_key: nil)
+        result = @client.request(:delete, "/post_queues/#{id}", idempotency_key: idempotency_key)
         DeleteResponse.new(**result)
       end
     end

data/lib/postproxy/resources/webhooks.rb

@@ -16,27 +16,27 @@ module PostProxy
         Webhook.new(**result)
       end
 
-      def create(url, events:, description: nil)
+      def create(url, events:, description: nil, idempotency_key: nil)
         json_body = { url: url, events: events }
         json_body[:description] = description if description
 
-        result = @client.request(:post, "/webhooks", json: json_body)
+        result = @client.request(:post, "/webhooks", json: json_body, idempotency_key: idempotency_key)
         Webhook.new(**result)
       end
 
-      def update(id, url: nil, events: nil, enabled: nil, description: nil)
+      def update(id, url: nil, events: nil, enabled: nil, description: nil, idempotency_key: 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)
+        result = @client.request(:patch, "/webhooks/#{id}", json: json_body, idempotency_key: idempotency_key)
         Webhook.new(**result)
       end
 
-      def delete(id)
-        result = @client.request(:delete, "/webhooks/#{id}")
+      def delete(id, idempotency_key: nil)
+        result = @client.request(:delete, "/webhooks/#{id}", idempotency_key: idempotency_key)
         DeleteResponse.new(**result)
       end
 

data/lib/postproxy/types.rb

@@ -261,10 +261,13 @@ module PostProxy
   end
 
   class StatsRecord < Model
-    attr_accessor :stats, :recorded_at
+    # `raw_stats` carries every metric under its original platform name, e.g.
+    # `views` for Instagram or `impression_count` for Twitter/X.
+    attr_accessor :stats, :raw_stats, :recorded_at
 
     def initialize(**attrs)
       @stats = {}
+      @raw_stats = {}
       @recorded_at = nil
       super
       @recorded_at = parse_time(@recorded_at)
@@ -505,6 +508,79 @@ module PostProxy
     attr_accessor :accepted
   end
 
+  # A comment from Comments#list_all. Flat: replies are their own entries
+  # linked to their parent by `parent_external_id` rather than nested under
+  # `replies`.
+  class BulkComment < Model
+    attr_accessor :post_id, :profile_id, :platform, :id, :external_id, :body,
+                  :status, :author_username, :author_avatar_url,
+                  :author_external_id, :metadata, :parent_external_id,
+                  :like_count, :is_hidden, :permalink, :platform_data,
+                  :attachments, :posted_at, :created_at
+
+    def initialize(**attrs)
+      @external_id = nil
+      @author_username = 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 = []
+      @posted_at = nil
+      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
+    end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil?
+      value.is_a?(Time) ? value : Time.parse(value.to_s)
+    end
+  end
+
+  # A record of one post pull for a profile — the sync fired when the profile
+  # connects, the recurring poll, or a backfill.
+  class PostSync < Model
+    attr_accessor :id, :profile_id, :kind, :trigger, :status, :started_at,
+                  :completed_at, :posts_seen, :posts_imported, :backfill_from,
+                  :oldest_posted_at, :error, :created_at
+
+    def initialize(**attrs)
+      @started_at = nil
+      @completed_at = nil
+      @posts_seen = 0
+      # Posts that were new and got created — lower than `posts_seen` whenever
+      # the run re-read posts you already have.
+      @posts_imported = 0
+      @backfill_from = nil
+      # Publish date of the oldest post the run reached.
+      @oldest_posted_at = nil
+      @error = nil
+      super
+      @started_at = parse_time(@started_at)
+      @completed_at = parse_time(@completed_at)
+      @backfill_from = parse_time(@backfill_from)
+      @oldest_posted_at = parse_time(@oldest_posted_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 DeleteResponse < Model
     attr_accessor :deleted
   end
@@ -589,9 +665,37 @@ module PostProxy
     attr_accessor :format, :title, :first_comment, :page_id
   end
 
+  # An Instagram account to tag in a post. Images require `x` and `y`; reels
+  # and video slides are tagged by username only — Instagram ignores
+  # coordinates there. `media_index` picks the carousel slide (0-based).
+  class InstagramUserTag < Model
+    attr_accessor :username, :x, :y, :media_index
+  end
+
   class InstagramParams < Model
     attr_accessor :format, :first_comment, :collaborators, :cover_url,
-                  :audio_name, :trial_strategy, :thumb_offset
+                  :audio_name, :trial_strategy, :thumb_offset, :user_tags
+
+    def initialize(**attrs)
+      @user_tags = nil
+      super
+      @user_tags = @user_tags&.map do |t|
+        t.is_a?(InstagramUserTag) ? t : InstagramUserTag.new(**t.transform_keys(&:to_sym))
+      end
+    end
+
+    # User tags must reach the wire as plain hashes, with unset coordinates
+    # dropped rather than sent as nulls.
+    def to_h
+      result = super
+      tags = result[:user_tags]
+      return result if tags.nil?
+
+      result[:user_tags] = tags.map do |t|
+        (t.is_a?(Model) ? t.to_h : t).reject { |_, v| v.nil? }
+      end
+      result
+    end
   end
 
   class TikTokParams < Model

data/lib/postproxy/version.rb

@@ -1,3 +1,3 @@
 module PostProxy
-  VERSION = "1.11.0"
+  VERSION = "1.12.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: postproxy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.12.0
 platform: ruby
 authors:
 - PostProxy