omnisocials 0.5.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2dff156c383d34ece380b804eb9dc42fd00bd42782218bd99e7f840dfc4c197e
-  data.tar.gz: 8a7d23f25f08551a42e4b5ad30dc680f2b83045f72bb78c894a9ab13134df8e1
+  metadata.gz: 43d0cc71e753d98ddbaa8b1732f140ecfc3d578d02a8e8df81e248c6c9c75131
+  data.tar.gz: a66ae890324f9adc7b37b57add4e76ce1be1b110d4b15f751c611bcbfa6adf61
 SHA512:
-  metadata.gz: 3f3ca94edd9dbac14a91c91fc17c39b22efda2385dc36fd6fbc02b881c2f86a661e672a55665e97c47d4a8ee278ed6cb0e9bd961f4dcba495b936e6840316b88
-  data.tar.gz: 9f99feca0fef8165c5d80901cc60f4a3e8f681025e8c786e2e32938582e4194c9a98c8ba60ca54d1166e603bbc3c1f1e751dbdc580e42e9a3032bd650760511a
+  metadata.gz: 0b30af0ebca987fe7bebb4710d7648d2c0361e8709cdf716897d4f1f82808dc916159742dcae7c9c0512863e01f68435d642a9341e8254d9cc11511459b496ce
+  data.tar.gz: e50bd7f05fe6a2e516ff9ea31bb28307af242c4118ca1a30583008b88591e3b2d9c080fb50447137133f036e21d6fed8721b90bd380cfb670dc3870868ac7710

data/README.md

@@ -105,7 +105,7 @@ Note that `linkedin` targets a personal LinkedIn profile and `linkedin_page` tar
 
 ### Chained threads (X, Bluesky, Mastodon, Threads)
 
-Pass 2 to 25 `thread_parts` to publish a chained thread instead of a single tweet (each part is at most 280 characters). Bluesky, Mastodon and Threads support the same `thread_parts` shape (Threads: 2 to 25 parts, 500 characters per part, up to 10 media per part; parts after the first publish as replies to the previous part, and the Threads caption is taken from part 1):
+Pass 2 to 25 `thread_parts` to publish a chained thread instead of a single tweet (each part is at most 280 characters, 25,000 for X Premium/Premium+ accounts). Bluesky, Mastodon and Threads support the same `thread_parts` shape (Threads: 2 to 25 parts, 500 characters per part, up to 10 media per part; parts after the first publish as replies to the previous part, and the Threads caption is taken from part 1):
 
 ```ruby
 post = client.posts.create(
@@ -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"
@@ -392,13 +406,42 @@ end
 client.inbox.mark_read(conversation_id)
 client.inbox.reply(conversation_id, text: "Thanks for reaching out!")
 
-# Threads only: hide or unhide a reply someone left on one of your Threads posts.
+# Hide or unhide a comment someone left on one of your posts (Facebook,
+# Instagram, TikTok, YouTube, Threads). Delete removes it outright (Facebook,
+# Instagram, TikTok; YouTube: hide instead), replies under it included.
 message_id = messages["data"][0]["id"]
 client.inbox.hide(message_id)               # hide
 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. Only incoming top-level Threads replies can be hidden (nested replies cannot), and a hidden message keeps its place in the conversation with its `hidden` flag set. 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. 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")
+while item["data"]
+  message = item["data"]["message"]
+  puts "#{item["remaining"]} left. #{message["sender"]["username"]}: #{message["text"]}"
+
+  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
+```
 
 Replying to an X DM costs 2 prepaid credits, debited from the company balance before the send and automatically refunded if the send fails:
 
@@ -421,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(
@@ -464,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/client.rb

@@ -59,8 +59,8 @@ module OmniSocials
     ].freeze
 
     attr_reader :api_key, :base_url, :timeout, :max_retries,
-                :posts, :media, :folders, :hashtag_sets, :accounts, :analytics,
-                :audio, :locations, :inbox, :webhooks
+                :posts, :media, :folders, :hashtag_sets, :approval_workflows,
+                :accounts, :analytics, :audio, :locations, :inbox, :webhooks
 
     # api_key     - API key (omsk_live_* / omsk_test_*). Falls back to the
     #               OMNISOCIALS_API_KEY environment variable. Raises
@@ -89,6 +89,7 @@ module OmniSocials
       @media = Resources::Media.new(self)
       @folders = Resources::Folders.new(self)
       @hashtag_sets = Resources::HashtagSets.new(self)
+      @approval_workflows = Resources::ApprovalWorkflows.new(self)
       @accounts = Resources::Accounts.new(self)
       @analytics = Resources::Analytics.new(self)
       @audio = Resources::Audio.new(self)

data/lib/omnisocials/resources/approval_workflows.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Approval workflows resource: the workflows configured in the dashboard
+    # (Approvals). List them here and route a post through one at create time
+    # via approval_workflow_id on posts.create.
+    class ApprovalWorkflows
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /approval-workflows - the workflows this workspace can use
+      # (company-wide plus workspace-bound), with steps and named approvers.
+      def list
+        @client.request("GET", "/approval-workflows")
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/inbox.rb

@@ -24,24 +24,31 @@ module OmniSocials
       #
       # All filters are optional: platform ("instagram", "facebook",
       # "linkedin", "tiktok", "youtube", "x", "threads"), type ("dm", "comment",
-      # "mention"), unread (only conversations with unread messages), limit
-      # (1-100), and cursor (an opaque cursor from a previous response's
+      # "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, 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
       # "threads_comment_<rootPostId>") and "mention"
       # ("threads_mention_<postId>"); there are no Threads DMs. 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.
-      def list_conversations(platform: nil, type: nil, unread: nil, limit: nil, cursor: nil)
+      # needs a Threads connection with the reply permissions; connections made
+      # before those permissions existed must be reconnected once.
+      def list_conversations(platform: nil, type: nil, unread: nil, unanswered: nil, limit: nil, cursor: nil)
         @client.request(
           "GET", "/inbox/conversations",
           query: {
             "platform" => platform,
             "type" => type,
             "unread" => unread,
+            "unanswered" => unanswered,
             "limit" => limit,
             "cursor" => cursor
           }
@@ -73,10 +80,9 @@ module OmniSocials
       # text-only. Returns the created outgoing message.
       #
       # On a Threads conversation the reply publishes as a native Threads
-      # reply. Threads inbox is currently rolling out (disabled on production
-      # until Meta App Review) and needs a Threads connection with the reply
+      # reply. The Threads inbox needs a Threads connection with the reply
       # permission: a 401 with code "reauth_required" means the connection
-      # lacks that permission (reconnect Threads).
+      # lacks that permission (connected before it existed; reconnect Threads).
       #
       # Replying to an X DM costs 2 prepaid credits, debited from the
       # company balance before the send and automatically refunded if the
@@ -86,12 +92,35 @@ module OmniSocials
       # auto-suspended after the balance hit zero (top up and re-enable it
       # in the dashboard to resume; DMs that arrived while suspended are
       # not recovered).
-      def reply(conversation_id, text: nil, attachment_url: nil, attachment_type: nil)
+      #
+      # 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, message_id: nil, include_next: nil)
         body = Internal.drop_nil(
           {
             "text" => text,
             "attachment_url" => attachment_url,
-            "attachment_type" => attachment_type
+            "attachment_type" => attachment_type,
+            "message_id" => message_id,
+            "include_next" => include_next
           }
         )
         @client.request(
@@ -100,18 +129,37 @@ module OmniSocials
         )
       end
 
-      # POST /inbox/messages/{id}/hide - hide or unhide a reply someone left
-      # on one of the user's Threads posts, as the post owner (Threads only
-      # for now). Pass hide: false to unhide. Only incoming top-level replies
-      # can be hidden (Threads does not allow hiding nested replies); the
-      # message keeps its place in the conversation. Returns the updated
-      # message with its "hidden" flag flipped.
+      # POST /inbox/messages/{id}/hide - hide or unhide a comment someone
+      # left on one of the user's posts, on the platform, as the post owner.
+      # Facebook, Instagram, TikTok, YouTube and Threads comments (Threads:
+      # incoming top-level replies only; Threads does not allow hiding nested
+      # replies). Pass hide: false to unhide. On YouTube, hide sets the
+      # comment's moderation status to rejected, which removes it and its
+      # replies from public view; unhide publishes it again. Returns the
+      # updated message with its "hidden" flag flipped; the message keeps its
+      # place in the conversation, and a hidden comment no longer counts as
+      # unanswered. The account must have been connected with the moderation
+      # permission (Facebook pages_manage_engagement, Instagram
+      # instagram_business_manage_comments).
       #
-      # Errors: 400 "unsupported_platform" (not an incoming Threads reply, or
-      # Threads inbox not available yet), 400 "not_hideable" (nested reply or
-      # Threads refused), 401 "reauth_required" (connection lacks the reply
-      # permission; reconnect Threads), 404 "not_found" (message not in this
-      # workspace) or "account_not_connected" (no Threads account).
+      # Errors: 400 "unsupported_platform" (not an incoming comment on a
+      # supported platform), 400 "not_hideable" (Threads nested reply, or
+      # Threads refused), 401 "reauth_required" (the Threads reply permission
+      # or the TikTok comments authorization is missing or expired), 403
+      # "reconnect_required" (the account was connected without the
+      # comment-moderation permission; reconnect it in the dashboard), 404
+      # "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), 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",
@@ -119,6 +167,84 @@ module OmniSocials
         )
       end
 
+      # DELETE /inbox/messages/{id} - delete a comment someone left on one of
+      # the user's posts, on the platform and from the inbox. Facebook,
+      # Instagram and TikTok comments only: YouTube's API does not let a
+      # channel delete other people's comments, hide those instead (`hide`).
+      # Replies under the deleted comment go with it (the platforms cascade
+      # the delete and the inbox mirrors that); their inbox ids come back as
+      # "removed_reply_ids". A comment that is already gone on the platform
+      # is still removed from the inbox. This cannot be undone. Returns
+      # { "data" => { "id", "conversation_id", "removed_reply_ids" } }.
+      #
+      # Errors: 400 "unsupported_platform" (not an incoming Facebook,
+      # Instagram or TikTok comment), 401 "reauth_required" (the TikTok
+      # comments authorization expired), 403 "reconnect_required" (the
+      # account was connected without the comment-moderation permission;
+      # reconnect it in the dashboard), 404 "not_found" (message not in this
+      # workspace) or "account_not_connected", 502 "platform_error" (the
+      # platform rejected the call).
+      def delete_message(message_id)
+        @client.request("DELETE", "/inbox/messages/#{encode_id(message_id)}")
+      end
+
+      # GET /inbox/next - the next conversation that needs an answer: a work
+      # 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).
+      # Looks at the last 30 days of activity. Requires the inbox:read scope.
+      #
+      # Only unread items are served by default: marking a conversation read
+      # (`mark_read`) is how to skip one for good; pass include_read: true to
+      # 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"; 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", "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
+      # same response. Errors: 400 "validation_error" (unknown platform, type
+      # or order).
+      def next(platform: nil, type: nil, order: nil, include_read: nil, exclude: nil)
+        exclude = exclude.join(",") if exclude.is_a?(Array)
+        exclude = nil if exclude == ""
+        @client.request(
+          "GET", "/inbox/next",
+          query: {
+            "platform" => platform,
+            "type" => type,
+            "order" => order,
+            "include_read" => include_read,
+            "exclude" => exclude
+          }
+        )
+      end
+
       private
 
       # URL-encode a conversation or message id for use in a path segment.

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

@@ -46,6 +46,13 @@ module OmniSocials
       # POST /posts/create - create a post (draft, or scheduled when
       # scheduled_at is set).
       #
+      # approval_workflow_id (a workflow id from client.approval_workflows.list)
+      # routes the post through a saved approval workflow: it is created as
+      # in_approval (approval_status "pending") instead of scheduled, the
+      # approvers are notified, and it publishes at scheduled_at once the last
+      # step approves. Requires scheduled_at; not allowed with publish_now.
+      # Errors: 404 workflow_not_found, 400 validation_error.
+      #
       # hashtag_set (set name, case-insensitive) or hashtag_set_id applies a
       # saved hashtag set once at create time; tags already in a caption are
       # skipped; Instagram's 30-hashtag cap returns error code
@@ -88,7 +95,7 @@ module OmniSocials
                  instagram: nil, facebook: nil, linkedin: nil,
                  linkedin_page: nil, tiktok: nil, x: nil, bluesky: nil,
                  mastodon: nil, threads: nil, google_business: nil,
-                 linkedin_poll: nil)
+                 linkedin_poll: nil, approval_workflow_id: nil)
         body = create_body(
           content: content, channels: channels, scheduled_at: scheduled_at,
           media_ids: media_ids, media_urls: media_urls, type: type,
@@ -101,7 +108,8 @@ module OmniSocials
           youtube: youtube, instagram: instagram, facebook: facebook,
           linkedin: linkedin, linkedin_page: linkedin_page, tiktok: tiktok,
           x: x, bluesky: bluesky, mastodon: mastodon, threads: threads,
-          google_business: google_business, linkedin_poll: linkedin_poll
+          google_business: google_business, linkedin_poll: linkedin_poll,
+          approval_workflow_id: approval_workflow_id
         )
         @client.request("POST", "/posts/create", json: body)
       end
@@ -184,7 +192,7 @@ module OmniSocials
         @client.request("PATCH", "/posts/#{post_id}", json: body)
       end
 
-      # DELETE /posts/{id} - delete a post. Returns nil (204).
+      # DELETE /posts/{id} - remove a post from OmniSocials (the live post stays on the platform). Returns nil (204).
       def delete(post_id)
         @client.request("DELETE", "/posts/#{post_id}")
       end
@@ -230,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:,
@@ -239,7 +263,8 @@ module OmniSocials
                       hashtag_set_id:, hashtag_placement:, hashtag_platforms:,
                       pinterest:, youtube:, instagram:, facebook:, linkedin:,
                       linkedin_page:, tiktok:, x:, bluesky:, mastodon:,
-                      threads:, google_business:, linkedin_poll:)
+                      threads:, google_business:, linkedin_poll:,
+                      approval_workflow_id: nil)
         Internal.drop_nil(
           {
             "content" => content,
@@ -272,7 +297,8 @@ module OmniSocials
             "mastodon" => mastodon,
             "threads" => threads,
             "google_business" => google_business,
-            "linkedin_poll" => linkedin_poll
+            "linkedin_poll" => linkedin_poll,
+            "approval_workflow_id" => approval_workflow_id
           }
         )
       end

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.5.0"
+  VERSION = "0.8.0"
 end

data/lib/omnisocials.rb

@@ -20,6 +20,7 @@ require_relative "omnisocials/resources/posts"
 require_relative "omnisocials/resources/media"
 require_relative "omnisocials/resources/folders"
 require_relative "omnisocials/resources/hashtag_sets"
+require_relative "omnisocials/resources/approval_workflows"
 require_relative "omnisocials/resources/accounts"
 require_relative "omnisocials/resources/analytics"
 require_relative "omnisocials/resources/audio"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omnisocials
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.8.0
 platform: ruby
 authors:
 - OmniSocials
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-30 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,
@@ -27,6 +27,7 @@ files:
 - lib/omnisocials/internal.rb
 - lib/omnisocials/resources/accounts.rb
 - lib/omnisocials/resources/analytics.rb
+- lib/omnisocials/resources/approval_workflows.rb
 - lib/omnisocials/resources/audio.rb
 - lib/omnisocials/resources/folders.rb
 - lib/omnisocials/resources/hashtag_sets.rb