omnisocials 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b3fed727cadc18b6ea190937598241ea06e5ac3451f5a01e47e993f641f5332
-  data.tar.gz: 6adeeba6ddc69911b79c4b620ddc418e0dd372d6e76e3a417bd285ae54b44e9d
+  metadata.gz: 43d0cc71e753d98ddbaa8b1732f140ecfc3d578d02a8e8df81e248c6c9c75131
+  data.tar.gz: a66ae890324f9adc7b37b57add4e76ce1be1b110d4b15f751c611bcbfa6adf61
 SHA512:
-  metadata.gz: ad4c11a0f91aa25cd0dfab676f0a28b5973d139a82137c0d753de697a453d710bd9f59f6c212596230fe727e37d20e117635d7b23d06f2f6aeeefce3d66b5ffa
-  data.tar.gz: 1b53388871737de150a7d71387472915b3e1bfcc7c8e245f45e5c3d87ea4ef2ee9d8047855876d33e1028c0b24272accfe663ef482e83bbdc4e60a72fe9268af
+  metadata.gz: 0b30af0ebca987fe7bebb4710d7648d2c0361e8709cdf716897d4f1f82808dc916159742dcae7c9c0512863e01f68435d642a9341e8254d9cc11511459b496ce
+  data.tar.gz: e50bd7f05fe6a2e516ff9ea31bb28307af242c4118ca1a30583008b88591e3b2d9c080fb50447137133f036e21d6fed8721b90bd380cfb670dc3870868ac7710

data/README.md

@@ -208,6 +208,20 @@ client.posts.reject("123", comment: "Wrong CTA link, please fix.") # reject and
 
 Only works on a post with `approval_status: "pending"` (`status: "in_approval"`). Both act on behalf of the user who owns the API key, who must be a listed approver for the workflow's CURRENT step — steps approve in order, so being an approver on a later step is not enough yet (raises a 403 `OmniSocials::PermissionDeniedError`). Approving the last step finalizes the post (`scheduled` or `posting`); rejecting stops the whole workflow immediately, not just the current step.
 
+### Read the approval review
+
+```ruby
+review = client.posts.get_approval("123")["data"]
+if review["status"] == "rejected" && review["rejection"]
+  puts "Rejected by #{review["rejection"]["by"]["name"]}: #{review["rejection"]["reason"]}"
+end
+review["steps"].each do |step|
+  puts "#{step["order"]} #{step["name"]} #{step["status"]}"
+end
+```
+
+`get_approval` returns the review of a post that went through an approval workflow: `status` (`none`, `pending`, `approved`, `rejected`), the `workflow`, who requested it and when, `current_step` (the step the post waits on, `nil` when the review ended), every step with its approvers and their decisions, the `rejection` (`by`, `reason`, `at`, `step`; `nil` when nobody rejected) and the `comments` thread, oldest first. A post without an approval workflow returns `status: "none"` with empty `steps` and `comments`. Read-only; needs the `posts:read` scope.
+
 ## Media
 
 ### Upload from a URL (recommended, up to 1GB)
@@ -231,7 +245,7 @@ media = client.media.upload(file: "/path/to/image.jpg", name: "hero-shot")
 
 `file` accepts a file path (String or Pathname), an IO (`File.open("...", "rb")`, StringIO), or raw bytes as a binary-encoded String (e.g. from `File.binread`).
 
-Uploading a PDF splits it into image slides (max 20 pages) and returns `slides` plus a `media_ids` array. Pass all of `media_ids`, in order, to `posts.create` to publish the deck as a carousel (a native swipeable document on LinkedIn, an image carousel elsewhere).
+Uploading a PDF splits it into image slides (max 20 pages) and returns `slides` plus a `media_ids` array. Pass all of `media_ids`, in order, to `posts.create` to publish the deck as a carousel (on LinkedIn a native swipeable document made from the original PDF file, which is kept so text and links stay intact; an image carousel elsewhere). To keep the PDF as ONE library item instead of one item per page, pass `pdf_mode` = `"document"`: the response then has a single `data` item of type `document` (its page images in `pdf.pages`) and `media_ids` holds that one id, which expands into every page at post time.
 
 Every upload response also includes a `compatibility` block listing any connected platforms that would reject the file.
 
@@ -383,7 +397,7 @@ conversations["data"].each do |conversation|
   puts "#{conversation["platform"]}: #{conversation["preview"]}"
 end
 
-conversation_id = conversations["data"][0]["id"]
+conversation_id = conversations["data"][0]["conversation_id"]
 messages = client.inbox.get_messages(conversation_id)
 messages["data"].each do |message|
   puts "#{message["direction"]}: #{message["text"]}"  # direction is "incoming" or "outgoing"
@@ -401,9 +415,9 @@ client.inbox.hide(message_id, hide: false)  # unhide
 client.inbox.delete_message(message_id)
 ```
 
-`platform` accepts `"instagram"`, `"facebook"`, `"linkedin"`, `"tiktok"`, `"youtube"`, `"x"`, or `"threads"`; `type` accepts `"dm"`, `"comment"`, or `"mention"`. Threads conversations are comments (replies people leave on your Threads posts) and mentions; there are no Threads DMs. Comments can be hidden on Facebook, Instagram, TikTok, YouTube, and Threads (Threads: incoming top-level replies only), and a hidden message keeps its place in the conversation with its `hidden` flag set; `hidden` is `true`/`false` on comments and `nil` on DMs. A comment/mention's `post` carries `url` (public link when the platform provides one) and `media_type` (the platform's own label) next to `id`, `caption`, and `thumbnail`. Threads inbox is currently rolling out; until Meta approves the permissions it is disabled on production and calls return a clear error, and it needs a Threads connection with the reply permission (a 401 `reauth_required` means reconnect Threads). TikTok and YouTube replies are comments only; TikTok replies are capped at 150 characters. Conversation ids are URL-encoded for you, so pass them exactly as returned - LinkedIn ids contain `":"` and `"()"` (e.g. `"linkedin_comment_urn:li:activity:123"`).
+`platform` accepts `"instagram"`, `"facebook"`, `"linkedin"`, `"tiktok"`, `"youtube"`, `"x"`, or `"threads"`; `type` accepts `"dm"`, `"comment"`, or `"mention"`. Threads conversations are comments (replies people leave on your Threads posts) and mentions; there are no Threads DMs. Comments can be hidden on Facebook, Instagram, TikTok, YouTube, and Threads (Threads: incoming top-level replies only), and a hidden message keeps its place in the conversation with its `hidden` flag set; `hidden` is `true`/`false` on comments and `nil` on DMs. A comment/mention's `post` carries `url` (public link when the platform provides one) and `media_type` (the platform's own label) next to `id`, `caption`, and `thumbnail`. The Threads inbox needs a Threads connection with the reply permission (a 401 `reauth_required` means reconnect Threads; an account connected before 2026-09-14 needs this once). TikTok and YouTube replies are comments only; TikTok replies are capped at 150 characters. Conversation ids are URL-encoded for you, so pass them exactly as returned - LinkedIn ids contain `":"` and `"()"` (e.g. `"linkedin_comment_urn:li:activity:123"`).
 
-`next` hands out the next conversation that still needs a reply (the customer's latest DM with no reply after it, or an unreplied comment/mention that is not hidden), with the whole thread and the post it belongs to, so a reply can be drafted from one call. Replies typed in the native apps count as answers. Only unread items are served by default, so `mark_read` is the durable way to skip one; `exclude` skips conversation ids for the current session only. Pass `include_next: true` to `reply` to get the following item in the same response. `list_conversations(unanswered: true)` gives the same set as a plain list.
+`next` hands out the next conversation that still needs a reply (the customer's latest DM with no reply after it, or an unreplied comment/mention that is not hidden), with the whole thread and the post it belongs to, so a reply can be drafted from one call. DMs that can still be answered come first, then Instagram/Facebook DMs whose 24-hour window has closed (`reply_window["open"]` is `false`: answer those from the native app or mark them read), then comments and mentions, oldest first. Replies typed in the native apps count as answers. Only unread items are served by default, so `mark_read` is the durable way to skip one; `exclude` skips conversation ids for the current session only. Always pass `message_id: message["id"]` to `reply` on comment threads: every comment on a post shares one conversation, and without it the reply goes under the newest comment on the post. Pass `include_next: true` to `reply` to get the following item in the same response. `list_conversations(unanswered: true)` gives the same set as a plain list.
 
 ```ruby
 item = client.inbox.next(platform: "instagram")
@@ -411,7 +425,20 @@ while item["data"]
   message = item["data"]["message"]
   puts "#{item["remaining"]} left. #{message["sender"]["username"]}: #{message["text"]}"
 
-  reply = client.inbox.reply(message["conversation_id"], text: "Thanks! DM sent.", include_next: true)
+  unless item["data"]["reply_window"]["open"]
+    # An Instagram/Facebook DM past Meta's 24-hour window: reply would raise
+    # 422 outside_messaging_window. Answer it in the app, or skip it.
+    client.inbox.mark_read(message["conversation_id"])
+    item = client.inbox.next(platform: "instagram")
+    next
+  end
+
+  reply = client.inbox.reply(
+    message["conversation_id"],
+    text: "Thanks! DM sent.",
+    message_id: message["id"], # the comment being answered, not the newest one
+    include_next: true
+  )
   item = { "data" => reply["next"], "remaining" => reply["remaining"] || 0 }
 end
 ```
@@ -437,7 +464,7 @@ end
 
 ## Webhooks
 
-Subscribe to `post.scheduled`, `post.published`, and `post.failed` events:
+Subscribe to `post.scheduled`, `post.published`, `post.failed`, `post.approved`, and `post.rejected` events. `post.approved` fires when the last step of a post's approval workflow is approved, `post.rejected` when an approver rejects the post (it will not publish). These two carry `data["approval"]` with `status`, `decided_by` (the approver's user id) and `reason` (`nil` on `post.approved`), and an empty `data["targets"]`.
 
 ```ruby
 webhook = client.webhooks.create(
@@ -480,6 +507,8 @@ class OmnisocialsWebhooksController < ApplicationController
       event["data"]["targets"].each do |target|
         Rails.logger.info "#{target["platform"]} #{target["status"]} #{target["native_post_id"]}"
       end
+    elsif event["type"] == "post.rejected"
+      Rails.logger.info "Rejected: #{event["data"]["post_id"]} #{event["data"]["approval"]["reason"]}"
     end
 
     head :ok

data/lib/omnisocials/resources/inbox.rb

@@ -26,12 +26,14 @@ module OmniSocials
       # "linkedin", "tiktok", "youtube", "x", "threads"), type ("dm", "comment",
       # "mention"), unread (only conversations with unread messages),
       # unanswered (only conversations that still need an answer: the
-      # customer's latest DM has no reply after it, for Instagram/Facebook DMs
-      # within the 24-hour messaging window only, or a comment/mention that
-      # has not been replied to and is not hidden; replies typed in the native
-      # apps count as answers, and read state is ignored, so use `next` for a
-      # work queue), limit (1-100), and cursor (an opaque cursor from a
-      # previous response's pagination["next_cursor"]).
+      # customer's latest DM has no reply after it, Instagram/Facebook DMs
+      # past Meta's 24-hour messaging window included (they cannot be answered
+      # through the API, but the customer is still waiting), or a
+      # comment/mention that has not been replied to and is not hidden;
+      # replies typed in the native apps count as answers, and read state is
+      # ignored, so use `next` for a work queue), limit (1-100), and cursor
+      # (an opaque cursor from a previous response's
+      # pagination["next_cursor"]).
       #
       # Threads conversations are type "comment" (replies people leave on the
       # user's Threads posts; conversation ids look like
@@ -91,17 +93,33 @@ module OmniSocials
       # in the dashboard to resume; DMs that arrived while suspended are
       # not recovered).
       #
+      # On comment and mention threads, pass message_id: (the "id" of the
+      # comment being answered: message["id"] from `next`, or a message "id"
+      # from `get_messages`). Every comment on a post shares one
+      # conversation, so without it the reply is posted under the newest
+      # comment on the post, which may be a different person than the one you
+      # drafted for. Ignored for DMs. 404 "not_found" when it is not an
+      # incoming message of this conversation.
+      #
+      # Instagram and Facebook DMs can only be answered within 24 hours of
+      # the customer's last message (Meta policy). That is checked before the
+      # send: a closed window raises 422 "outside_messaging_window" and
+      # nothing is sent (`next` reports the same in "reply_window"). Answer
+      # such a DM from the Instagram or Facebook app (mirrored into the
+      # inbox) or mark the conversation read; do not retry.
+      #
       # Pass include_next: true to also get "next" (the next conversation
       # that needs an answer, the same object `next` returns under "data",
       # using its default queue order and filters; nil when nothing is
       # waiting) and "remaining" in the response. Saves the extra call when
       # working through the inbox.
-      def reply(conversation_id, text: nil, attachment_url: nil, attachment_type: nil, include_next: nil)
+      def reply(conversation_id, text: nil, attachment_url: nil, attachment_type: nil, message_id: nil, include_next: nil)
         body = Internal.drop_nil(
           {
             "text" => text,
             "attachment_url" => attachment_url,
             "attachment_type" => attachment_type,
+            "message_id" => message_id,
             "include_next" => include_next
           }
         )
@@ -133,9 +151,15 @@ module OmniSocials
       # "not_found" (message not in this workspace) or
       # "account_not_connected", 429 "quota_exceeded" (YouTube's daily API
       # quota is used up; retry after midnight Pacific), 502 "platform_error"
-      # (the platform rejected the call). Threads inbox is currently rolling
-      # out; until Meta approves the permissions it is disabled on production
-      # and Threads calls return a clear error.
+      # (the platform rejected the call), 502 "hide_not_applied" (Instagram
+      # accepted the call but, read back, still reports the comment in its
+      # old state; this happens with comments Instagram shows under "Comments
+      # from Facebook" on a reel that is also shared to Facebook, which live
+      # on Facebook where Instagram's hide does not reach them; the inbox row
+      # is left unchanged, so hide it in the Instagram or Facebook app and do
+      # not retry). A Threads account connected before 2026-09-14 needs a
+      # one-time reconnect; until then a Threads hide answers 401
+      # "reauth_required".
       def hide(message_id, hide: true)
         @client.request(
           "POST", "/inbox/messages/#{encode_id(message_id)}/hide",
@@ -165,13 +189,17 @@ module OmniSocials
       end
 
       # GET /inbox/next - the next conversation that needs an answer: a work
-      # queue for answering the inbox. Returns the oldest (by default) item
-      # that still needs a reply, together with its conversation so far and
-      # the post it belongs to, so a reply can be drafted from one call. An
-      # item needs an answer when it is the customer's latest DM with no
-      # reply after it (Instagram/Facebook DMs within the 24-hour messaging
-      # window only, since Meta refuses replies outside it), or a
+      # queue for answering the inbox. Returns one item that still needs a
+      # reply, together with its conversation so far and the post it belongs
+      # to, so a reply can be drafted from one call. An item needs an answer
+      # when it is the customer's latest DM with no reply after it, or a
       # comment/mention that has not been replied to and is not hidden.
+      # Order: DMs that can still be answered come first (Instagram/Facebook
+      # DMs inside Meta's 24-hour window, the one whose window closes soonest
+      # first, and X DMs), then Instagram/Facebook DMs whose window has
+      # closed (served with "reply_window"["open"] false: answer them from
+      # the native app or mark them read), then comments and mentions, oldest
+      # first by default.
       # Replies typed in the native apps count as answers (they are mirrored
       # into the inbox), so a thread a colleague answered on their phone is
       # not served again. Instagram mentions are skipped (no reply path).
@@ -182,16 +210,21 @@ module OmniSocials
       # include read-but-unanswered items. exclude is a session-local skip:
       # conversation ids (an Array, or a comma-separated String) to leave out
       # of this call, up to 100. order is "oldest" (default: the item that
-      # has waited longest first) or "newest". platform and type ("dm",
-      # "comment", "mention") narrow the queue.
+      # has waited longest first) or "newest"; it reverses the order within
+      # each group. platform and type ("dm", "comment", "mention") narrow the
+      # queue.
       #
       # Returns { "data" => ..., "remaining" => Integer }. "data" is
-      # { "conversation", "message", "messages" }, or nil when nothing is
-      # waiting. "message" is the unanswered incoming item itself (the
-      # customer's latest DM, or the specific comment): its "id" is what
-      # `hide` and `delete_message` take, its "conversation_id" is what
-      # `reply` takes. "messages" is the conversation so far, oldest first
-      # (the most recent 50 messages for long DM threads). "remaining" is the
+      # { "conversation", "message", "messages", "reply_window" }, or nil
+      # when nothing is waiting. "message" is the unanswered incoming item
+      # itself (the customer's latest DM, or the specific comment): its "id"
+      # is what `hide` and `delete_message` take and the message_id: to pass
+      # to `reply` on comment threads, its "conversation_id" is what `reply`
+      # takes. "messages" is the conversation so far, oldest first (the most
+      # recent 50 messages for long DM threads). "reply_window" is
+      # { "open" => Boolean, "closes_at" => String|nil }: "open" is false
+      # only for an Instagram/Facebook DM past its 24-hour window, which
+      # `reply` refuses with 422 "outside_messaging_window". "remaining" is the
       # number of unanswered items still waiting after this one (capped at
       # 500), 0 when "data" is nil. To chain the queue, pass
       # include_next: true to `reply` and it returns the next item in the

data/lib/omnisocials/resources/media.rb

@@ -32,13 +32,15 @@ module OmniSocials
       # binary-encoded String, e.g. from File.binread).
       #
       # A PDF is split into image slides and the response carries `slides`
-      # plus a `media_ids` array instead of a single `data` item. For files
+      # plus a `media_ids` array instead of a single `data` item; pass
+      # pdf_mode: "document" to keep it as ONE item of type "document" whose
+      # single id in media_ids expands into every page. For files
       # over 100MB use upload_from_url (up to 1GB) or the create_upload_url
       # presigned flow.
-      def upload(file:, filename: nil, name: nil, folder: nil, folder_id: nil)
+      def upload(file:, filename: nil, name: nil, folder: nil, folder_id: nil, pdf_mode: nil)
         upload_name, data = Internal.coerce_file(file, filename)
         fields = Internal.drop_nil(
-          { "name" => name, "folder" => folder, "folder_id" => folder_id }
+          { "name" => name, "folder" => folder, "folder_id" => folder_id, "pdf_mode" => pdf_mode }
         )
         @client.request(
           "POST", "/media/upload",
@@ -50,14 +52,15 @@ module OmniSocials
       #
       # Files over 100MB are streamed in the background: the response has
       # data["status"] == "processing"; poll get() until it is "ready".
-      def upload_from_url(url:, filename: nil, name: nil, folder: nil, folder_id: nil)
+      def upload_from_url(url:, filename: nil, name: nil, folder: nil, folder_id: nil, pdf_mode: nil)
         body = Internal.drop_nil(
           {
             "url" => url,
             "filename" => filename,
             "name" => name,
             "folder" => folder,
-            "folder_id" => folder_id
+            "folder_id" => folder_id,
+            "pdf_mode" => pdf_mode
           }
         )
         @client.request("POST", "/media/upload-from-url", json: body)
@@ -66,7 +69,7 @@ module OmniSocials
       # POST /media/upload-from-base64 - upload base64-encoded data (without
       # a data URI prefix).
       def upload_from_base64(data:, mime_type:, filename: nil, name: nil,
-                             folder: nil, folder_id: nil)
+                             folder: nil, folder_id: nil, pdf_mode: nil)
         body = Internal.drop_nil(
           {
             "data" => data,
@@ -74,7 +77,8 @@ module OmniSocials
             "filename" => filename,
             "name" => name,
             "folder" => folder,
-            "folder_id" => folder_id
+            "folder_id" => folder_id,
+            "pdf_mode" => pdf_mode
           }
         )
         @client.request("POST", "/media/upload-from-base64", json: body)

data/lib/omnisocials/resources/posts.rb

@@ -238,6 +238,22 @@ module OmniSocials
         @client.request("POST", "/posts/#{post_id}/reject", json: body)
       end
 
+      # GET /posts/{id}/approval - the approval review of a post: every step
+      # with its approvers and their decisions, the rejection with its
+      # reason, and the comment thread. Use it when approval_status is
+      # "rejected" to learn who rejected the post and why, or while it is
+      # "pending" to see who the post waits for.
+      #
+      # `data` carries post_id, status ("none", "pending", "approved",
+      # "rejected"), workflow, requested_by, requested_at, current_step,
+      # steps, rejection and comments (oldest first). A post without an
+      # approval workflow returns status "none" with the object fields nil
+      # and empty steps and comments. Read-only; requires the posts:read
+      # scope.
+      def get_approval(post_id)
+        @client.request("GET", "/posts/#{post_id}/approval")
+      end
+
       private
 
       def create_body(content:, channels:, scheduled_at:, media_ids:,

data/lib/omnisocials/resources/webhooks.rb

@@ -3,7 +3,7 @@
 module OmniSocials
   module Resources
     # Webhooks resource: manage event subscriptions (post.scheduled,
-    # post.published, post.failed).
+    # post.published, post.failed, post.approved, post.rejected).
     #
     # For verifying incoming deliveries, see OmniSocials::Webhooks.verify.
     class Webhooks
@@ -24,8 +24,9 @@ module OmniSocials
       # POST /webhooks - create a webhook subscription.
       #
       # `url` must be HTTPS. `events` is a non-empty subset of
-      # post.scheduled, post.published, post.failed. The signing `secret` is
-      # only returned once, in this response - store it.
+      # post.scheduled, post.published, post.failed, post.approved,
+      # post.rejected. The signing `secret` is only returned once, in this
+      # response - store it.
       def create(url:, events:)
         @client.request(
           "POST", "/webhooks",

data/lib/omnisocials/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OmniSocials
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omnisocials
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - OmniSocials
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-17 00:00:00.000000000 Z
+date: 2026-10-05 00:00:00.000000000 Z
 dependencies: []
 description: Schedule and publish social media posts, upload media, and read analytics
   across Instagram, Facebook, LinkedIn, YouTube, TikTok, X, Pinterest, Bluesky, Threads,