omnisocials 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8be79cfb8525cbb823f24a4a34d6cb3d51b193d864db80cc190bc0a7db45a18
-  data.tar.gz: ed95b24b6e722f29e9c7e94e9d4506c69dece3579f9e609966fa999d5d1893bf
+  metadata.gz: 4b3fed727cadc18b6ea190937598241ea06e5ac3451f5a01e47e993f641f5332
+  data.tar.gz: 6adeeba6ddc69911b79c4b620ddc418e0dd372d6e76e3a417bd285ae54b44e9d
 SHA512:
-  metadata.gz: 2138c0350aea5e6c3059bf5d71bc9cd050441ac11b8846d01d55f9c6bd88c83488cd4e47b5c17ba8e298f98c01d75e53dcf1e54845a89a2c92553f4e896a9386
-  data.tar.gz: 10177239235e7dcd623615ed273c4171b81c2819de790bdc636ff495a1dd3b177cc18011b4cf9ac67a1162358d711d927d38a07c7a00ed9d672a0fe551dc524d
+  metadata.gz: ad4c11a0f91aa25cd0dfab676f0a28b5973d139a82137c0d753de697a453d710bd9f59f6c212596230fe727e37d20e117635d7b23d06f2f6aeeefce3d66b5ffa
+  data.tar.gz: 1b53388871737de150a7d71387472915b3e1bfcc7c8e245f45e5c3d87ea4ef2ee9d8047855876d33e1028c0b24272accfe663ef482e83bbdc4e60a72fe9268af

data/README.md

@@ -103,9 +103,9 @@ post = client.posts.create(
 
 Note that `linkedin` targets a personal LinkedIn profile and `linkedin_page` targets a LinkedIn company page. Both can be connected to the same workspace and posted to independently.
 
-### X thread example
+### 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 and Mastodon support the same `thread_parts` shape:
+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(
@@ -123,7 +123,24 @@ post = client.posts.create(
 )
 ```
 
-On update, passing `x: { "thread_parts" => nil }` clears the thread and reverts the post to single-tweet mode. Only top-level `nil` values are dropped from request bodies, so nested `nil` values like this one are sent as JSON `null`.
+```ruby
+# Meta Threads chain with a carousel on the first part
+post = client.posts.create(
+  content: "Behind the scenes of our summer shoot",
+  channels: ["threads"],
+  threads: {
+    "thread_parts" => [
+      { "text" => "Behind the scenes of our summer shoot. A few highlights:", "media_urls" => ["https://example.com/shoot-1.jpg", "https://example.com/shoot-2.jpg"] },
+      { "text" => "Day one: scouting locations at sunrise." },
+      { "text" => "Day two: the full crew, 14 hours, zero regrets." }
+    ]
+  }
+)
+```
+
+On update, passing `x: { "thread_parts" => nil }` clears the thread and reverts the post to single-tweet mode (same for `bluesky`, `mastodon` and `threads`). Only top-level `nil` values are dropped from request bodies, so nested `nil` values like this one are sent as JSON `null`.
+
+Threads posts can also carry a location tag: pass `threads: { "location_id" => "..." }` with an id from `client.locations.search(platform: "threads")` (see Locations below). On a multi-post thread the tag is applied to part 1, and on update `threads: { "location_id" => nil }` clears it. Threads location tagging is currently rolling out; until Meta approves the permissions it is disabled on production and calls return a clear error.
 
 ### X link posts use credits
 
@@ -182,6 +199,15 @@ recent = client.posts.recent_platform(limit: 10, platforms: ["instagram", "tikto
 
 `retry` re-publishes only the platforms that failed, on the same post; platforms that already succeeded are never posted again. It is asynchronous: a 200 means the retry is queued, so poll `get` for the outcome. Max 3 retries per platform.
 
+### Approve or reject a post
+
+```ruby
+client.posts.approve("123")                                    # approve the current approval-workflow step
+client.posts.reject("123", comment: "Wrong CTA link, please fix.") # reject and stop the workflow (comment optional)
+```
+
+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.
+
 ## Media
 
 ### Upload from a URL (recommended, up to 1GB)
@@ -315,7 +341,7 @@ best = client.analytics.best_times(platform: "instagram", timezone: "Europe/Amst
 best["data"]["best_times"].each { |slot| puts slot }
 ```
 
-## Locations (Instagram place tagging)
+## Locations (Instagram and Threads place tagging)
 
 ```ruby
 results = client.locations.search("Blue Bottle Coffee Oakland")
@@ -330,6 +356,23 @@ client.posts.create(
 )
 ```
 
+Threads uses its own location ids (a Facebook Place ID is not a Threads location id). Pass `platform: "threads"` and search by keyword, or by `latitude` plus `longitude` instead of `q`; use a result's `id` as `threads.location_id` on a post:
+
+```ruby
+results = client.locations.search("Blue Bottle Coffee Oakland", platform: "threads")
+# or around a point instead of a keyword:
+results = client.locations.search(platform: "threads", latitude: 37.8044, longitude: -122.2712)
+threads_location_id = results["locations"][0]["id"]
+
+client.posts.create(
+  content: "Great coffee here",
+  channels: ["threads"],
+  threads: { "location_id" => threads_location_id }
+)
+```
+
+The Threads response is `{ "locations" => [...] }` (each with nullable `name`, `address`, `city`, `country`, `latitude`, `longitude`) or `{ "error" => { "code", "message" } }` with `code` one of `not_available`, `threads_not_connected`, `threads_reauth_required` (reconnect Threads), or `platform_error`. Threads location tagging is currently rolling out; until Meta approves the permissions it is disabled on production and calls return a clear error.
+
 ## Inbox
 
 Read and reply to social inbox conversations (DMs, comments, mentions) across connected platforms. Requires an API key with the opt-in `inbox:read` / `inbox:write` scopes. The list endpoints are cursor-paginated (unlike the offset pagination used elsewhere): page while `pagination["has_more"]` is true by passing the previous response's `pagination["next_cursor"]` as `cursor`.
@@ -348,9 +391,30 @@ end
 
 client.inbox.mark_read(conversation_id)
 client.inbox.reply(conversation_id, text: "Thanks for reaching out!")
+
+# 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"`, or `"x"`; `type` accepts `"dm"`, `"comment"`, or `"mention"`. TikTok replies are comments only and 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`. 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"`).
+
+`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.
+
+```ruby
+item = client.inbox.next(platform: "instagram")
+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)
+  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:
 

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

@@ -23,17 +23,30 @@ module OmniSocials
       # GET /inbox/conversations - list conversations, newest activity first.
       #
       # All filters are optional: platform ("instagram", "facebook",
-      # "linkedin", "tiktok", "x"), type ("dm", "comment", "mention"),
-      # unread (only conversations with unread messages), limit (1-100), and
-      # cursor (an opaque cursor from a previous response's
-      # pagination["next_cursor"]).
-      def list_conversations(platform: nil, type: nil, unread: nil, limit: nil, cursor: nil)
+      # "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"]).
+      #
+      # 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
+      # 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
           }
@@ -58,9 +71,16 @@ module OmniSocials
       # POST /inbox/conversations/{id}/reply - send a reply into the
       # conversation (a DM message, or a reply to the comment/mention).
       #
-      # `text` is required. Optionally attach a single media asset by public
-      # URL with `attachment_url` plus `attachment_type` ("image", "video",
-      # "audio", or "file"). Returns the created outgoing message.
+      # On Facebook and Instagram DMs, optionally attach a single media asset
+      # by public URL with `attachment_url` plus `attachment_type` ("image",
+      # "video", "audio", or "file"); `text` is optional when `attachment_url`
+      # is set (an attachment-only reply is allowed). Other platforms are
+      # text-only. Returns the created outgoing message.
+      #
+      # On a Threads conversation the reply publishes as a native Threads
+      # reply. The Threads inbox needs a Threads connection with the reply
+      # permission: a 401 with code "reauth_required" means the connection
+      # 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
@@ -70,12 +90,19 @@ 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:, attachment_url: nil, attachment_type: nil)
+      #
+      # 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)
         body = Internal.drop_nil(
           {
             "text" => text,
             "attachment_url" => attachment_url,
-            "attachment_type" => attachment_type
+            "attachment_type" => attachment_type,
+            "include_next" => include_next
           }
         )
         @client.request(
@@ -84,11 +111,113 @@ module OmniSocials
         )
       end
 
+      # 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 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). Threads inbox is currently rolling
+      # out; until Meta approves the permissions it is disabled on production
+      # and Threads calls return a clear error.
+      def hide(message_id, hide: true)
+        @client.request(
+          "POST", "/inbox/messages/#{encode_id(message_id)}/hide",
+          json: { "hide" => hide }
+        )
+      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 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
+      # comment/mention that has not been replied to and is not hidden.
+      # 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". 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
+      # 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 id for use in a path segment. LinkedIn ids
-      # contain ":" and "()", so they must be escaped; spaces become %20
-      # (a path segment treats "+" literally, unlike a query string).
+      # URL-encode a conversation or message id for use in a path segment.
+      # LinkedIn conversation ids contain ":" and "()", so they must be
+      # escaped; spaces become %20 (a path segment treats "+" literally,
+      # unlike a query string).
       def encode_id(conversation_id)
         CGI.escape(conversation_id.to_s).gsub("+", "%20")
       end

data/lib/omnisocials/resources/locations.rb

@@ -2,16 +2,48 @@
 
 module OmniSocials
   module Resources
-    # Locations resource: Instagram place tagging (search + validate).
+    # Locations resource: Instagram and Threads place tagging (search +
+    # validate).
     class Locations
       def initialize(client)
         @client = client
       end
 
-      # GET /locations/search?q= - search Facebook place pages usable as an
-      # Instagram location_id.
-      def search(q)
-        @client.request("GET", "/locations/search", query: { "q" => q })
+      # GET /locations/search - search locations for place tagging.
+      #
+      # platform is "instagram" (default) or "threads". The two sources use
+      # DIFFERENT ids: a Facebook Place ID is not a Threads location id.
+      #
+      # Instagram: pass q to search Facebook place pages usable as an
+      # Instagram location_id. Response: { "data" => [...] } plus optional
+      # "error" (a plain string on the degraded path) and "needsPermission".
+      #
+      # Threads: pass q, OR latitude (-90..90) plus longitude (-180..180) to
+      # search around a point instead of q. Response:
+      # { "locations" => [{ id, name, address, city, country, latitude,
+      # longitude }] } (all fields but id nullable), or
+      # { "error" => { "code", "message" } } where code is one of
+      # "not_available" (Threads location tagging not enabled in this
+      # environment yet), "threads_not_connected", "threads_reauth_required"
+      # (the connection lacks the threads_location_tagging permission;
+      # reconnect Threads), or "platform_error". Validation problems (neither
+      # q nor lat+lng, q under 2 chars, coordinates out of range) raise a 400
+      # with the standard error envelope. Pass a result's id as
+      # threads.location_id on post create/update.
+      #
+      # Threads location tagging is currently rolling out: until Meta
+      # approves the permissions it is disabled on production and calls
+      # return a clear error.
+      def search(q = nil, platform: nil, latitude: nil, longitude: nil)
+        @client.request(
+          "GET", "/locations/search",
+          query: {
+            "q" => q,
+            "platform" => platform,
+            "latitude" => latitude,
+            "longitude" => longitude
+          }
+        )
       end
 
       # GET /locations/validate?id= - validate a location id before attaching

data/lib/omnisocials/resources/posts.rb

@@ -11,8 +11,8 @@ module OmniSocials
     # for media_urls, `{ "id" => "...", "alt" => "..." }` for media_ids. Alt
     # text is delivered to Mastodon (media description), Bluesky (embed alt),
     # X (photos/GIFs), Pinterest (pin alt text), Instagram (images), and
-    # LinkedIn (images); the same entry shape works inside x/bluesky/mastodon
-    # `thread_parts` media.
+    # LinkedIn (images); the same entry shape works inside
+    # x/bluesky/mastodon/threads `thread_parts` media.
     class Posts
       def initialize(client)
         @client = client
@@ -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
@@ -67,6 +74,18 @@ module OmniSocials
       # company's total reserved credits past its balance. Drafts are never
       # gated, and posts scheduled to publish before 2026-08-14 are never
       # gated either.
+      #
+      # Threads posts can carry a location tag: pass
+      # threads: { "location_id" => "..." } (an id from locations.search with
+      # platform: "threads"), or threads: { "location" => { "id" => "...",
+      # "name" => "..." } } to store display fields along with the id
+      # (location_id wins when both are given). On a multi-post thread
+      # (thread_parts) the tag is applied to part 1, and the Post's "threads"
+      # block echoes a "location" object when set. Threads location tagging
+      # is currently rolling out: until Meta approves the permissions it is
+      # disabled on production and create/update/publish return a 400 (also a
+      # 400 validation_error asking you to reconnect Threads when the
+      # connection lacks the threads_location_tagging permission).
       def create(content:, channels: nil, scheduled_at: nil, media_ids: nil,
                  media_urls: nil, type: nil, source: nil, link_url: nil,
                  link_title: nil, link_description: nil, link_thumbnail_url: nil,
@@ -75,7 +94,8 @@ module OmniSocials
                  hashtag_platforms: nil, pinterest: nil, youtube: nil,
                  instagram: nil, facebook: nil, linkedin: nil,
                  linkedin_page: nil, tiktok: nil, x: nil, bluesky: nil,
-                 mastodon: nil, google_business: nil, linkedin_poll: nil)
+                 mastodon: nil, threads: nil, google_business: 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,
@@ -87,8 +107,9 @@ module OmniSocials
           hashtag_platforms: hashtag_platforms, pinterest: pinterest,
           youtube: youtube, instagram: instagram, facebook: facebook,
           linkedin: linkedin, linkedin_page: linkedin_page, tiktok: tiktok,
-          x: x, bluesky: bluesky, mastodon: mastodon,
-          google_business: google_business, linkedin_poll: linkedin_poll
+          x: x, bluesky: bluesky, mastodon: mastodon, threads: threads,
+          google_business: google_business, linkedin_poll: linkedin_poll,
+          approval_workflow_id: approval_workflow_id
         )
         @client.request("POST", "/posts/create", json: body)
       end
@@ -106,7 +127,8 @@ module OmniSocials
                              pinterest: nil, youtube: nil, instagram: nil,
                              facebook: nil, linkedin: nil, linkedin_page: nil,
                              tiktok: nil, x: nil, bluesky: nil, mastodon: nil,
-                             google_business: nil, linkedin_poll: nil)
+                             threads: nil, google_business: nil,
+                             linkedin_poll: nil)
         body = create_body(
           content: content, channels: channels, scheduled_at: nil,
           media_ids: media_ids, media_urls: media_urls, type: type,
@@ -118,7 +140,7 @@ module OmniSocials
           hashtag_platforms: hashtag_platforms, pinterest: pinterest,
           youtube: youtube, instagram: instagram, facebook: facebook,
           linkedin: linkedin, linkedin_page: linkedin_page, tiktok: tiktok,
-          x: x, bluesky: bluesky, mastodon: mastodon,
+          x: x, bluesky: bluesky, mastodon: mastodon, threads: threads,
           google_business: google_business, linkedin_poll: linkedin_poll
         )
         @client.request("POST", "/posts/create-and-publish", json: body)
@@ -128,8 +150,9 @@ module OmniSocials
       #
       # Only top-level nils are dropped from the body, so passing e.g.
       # x: { "thread_parts" => nil } still clears an X thread (reverts the
-      # post to single-tweet mode). The same applies to bluesky and mastodon
-      # thread parts.
+      # post to single-tweet mode). The same applies to bluesky, mastodon
+      # and threads thread parts, and to a Threads location tag:
+      # threads: { "location_id" => nil } (or "location" => nil) clears it.
       #
       # See #create for the 402 "x_credits_insufficient" credit gate that
       # can also refuse an update to a scheduled X link post.
@@ -138,7 +161,8 @@ module OmniSocials
                  collaborators: nil, user_tags: nil, pinterest: nil,
                  youtube: nil, instagram: nil, facebook: nil, linkedin: nil,
                  linkedin_page: nil, tiktok: nil, x: nil, bluesky: nil,
-                 mastodon: nil, google_business: nil, linkedin_poll: nil)
+                 mastodon: nil, threads: nil, google_business: nil,
+                 linkedin_poll: nil)
         body = Internal.drop_nil(
           {
             "content" => content,
@@ -160,6 +184,7 @@ module OmniSocials
             "x" => x,
             "bluesky" => bluesky,
             "mastodon" => mastodon,
+            "threads" => threads,
             "google_business" => google_business,
             "linkedin_poll" => linkedin_poll
           }
@@ -167,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
@@ -190,6 +215,29 @@ module OmniSocials
         @client.request("POST", "/posts/#{post_id}/retry")
       end
 
+      # POST /posts/{id}/approve - approve the current step of a post's
+      # approval workflow, on behalf of the user who owns this API key. That
+      # user must be a listed approver for the workflow's CURRENT step -
+      # steps approve in order, so an approver on a later step gets a 403
+      # "forbidden" error until earlier steps clear. Only works on a post
+      # with approval_status "pending". If this is the last step, the post
+      # finalizes immediately ("scheduled" or "posting"); otherwise it stays
+      # "in_approval" and the next step's approvers are notified.
+      def approve(post_id)
+        @client.request("POST", "/posts/#{post_id}/approve")
+      end
+
+      # POST /posts/{id}/reject - reject a post's approval workflow, on
+      # behalf of the user who owns this API key. Same approver requirement
+      # as #approve. Unlike approval, a rejection stops the WHOLE workflow
+      # immediately (not just the current step) - the post's status becomes
+      # "rejected". `comment` is optional and, when given, is shown to the
+      # requester and other approvers in the post's review thread.
+      def reject(post_id, comment: nil)
+        body = comment ? { comment: comment } : nil
+        @client.request("POST", "/posts/#{post_id}/reject", json: body)
+      end
+
       private
 
       def create_body(content:, channels:, scheduled_at:, media_ids:,
@@ -199,7 +247,8 @@ module OmniSocials
                       hashtag_set_id:, hashtag_placement:, hashtag_platforms:,
                       pinterest:, youtube:, instagram:, facebook:, linkedin:,
                       linkedin_page:, tiktok:, x:, bluesky:, mastodon:,
-                      google_business:, linkedin_poll:)
+                      threads:, google_business:, linkedin_poll:,
+                      approval_workflow_id: nil)
         Internal.drop_nil(
           {
             "content" => content,
@@ -230,8 +279,10 @@ module OmniSocials
             "x" => x,
             "bluesky" => bluesky,
             "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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OmniSocials
-  VERSION = "0.4.0"
+  VERSION = "0.6.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.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - OmniSocials
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-22 00:00:00.000000000 Z
+date: 2026-09-17 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