omnisocials 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8be79cfb8525cbb823f24a4a34d6cb3d51b193d864db80cc190bc0a7db45a18
-  data.tar.gz: ed95b24b6e722f29e9c7e94e9d4506c69dece3579f9e609966fa999d5d1893bf
+  metadata.gz: 2dff156c383d34ece380b804eb9dc42fd00bd42782218bd99e7f840dfc4c197e
+  data.tar.gz: 8a7d23f25f08551a42e4b5ad30dc680f2b83045f72bb78c894a9ab13134df8e1
 SHA512:
-  metadata.gz: 2138c0350aea5e6c3059bf5d71bc9cd050441ac11b8846d01d55f9c6bd88c83488cd4e47b5c17ba8e298f98c01d75e53dcf1e54845a89a2c92553f4e896a9386
-  data.tar.gz: 10177239235e7dcd623615ed273c4171b81c2819de790bdc636ff495a1dd3b177cc18011b4cf9ac67a1162358d711d927d38a07c7a00ed9d672a0fe551dc524d
+  metadata.gz: 3f3ca94edd9dbac14a91c91fc17c39b22efda2385dc36fd6fbc02b881c2f86a661e672a55665e97c47d4a8ee278ed6cb0e9bd961f4dcba495b936e6840316b88
+  data.tar.gz: 9f99feca0fef8165c5d80901cc60f4a3e8f681025e8c786e2e32938582e4194c9a98c8ba60ca54d1166e603bbc3c1f1e751dbdc580e42e9a3032bd650760511a

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). 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,14 @@ 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.
+message_id = messages["data"][0]["id"]
+client.inbox.hide(message_id)               # hide
+client.inbox.hide(message_id, hide: false)  # unhide
 ```
 
-`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. 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"`).
 
 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/resources/inbox.rb

@@ -23,10 +23,18 @@ 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
+      # "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
       # 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)
         @client.request(
           "GET", "/inbox/conversations",
@@ -58,9 +66,17 @@ 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. Threads inbox is currently rolling out (disabled on production
+      # until Meta App Review) and needs a Threads connection with the reply
+      # permission: a 401 with code "reauth_required" means the connection
+      # lacks that permission (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,7 +86,7 @@ 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)
+      def reply(conversation_id, text: nil, attachment_url: nil, attachment_type: nil)
         body = Internal.drop_nil(
           {
             "text" => text,
@@ -84,11 +100,31 @@ 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.
+      #
+      # 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).
+      def hide(message_id, hide: true)
+        @client.request(
+          "POST", "/inbox/messages/#{encode_id(message_id)}/hide",
+          json: { "hide" => hide }
+        )
+      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
@@ -67,6 +67,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 +87,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)
         body = create_body(
           content: content, channels: channels, scheduled_at: scheduled_at,
           media_ids: media_ids, media_urls: media_urls, type: type,
@@ -87,7 +100,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", json: body)
@@ -106,7 +119,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 +132,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 +142,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 +153,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 +176,7 @@ module OmniSocials
             "x" => x,
             "bluesky" => bluesky,
             "mastodon" => mastodon,
+            "threads" => threads,
             "google_business" => google_business,
             "linkedin_poll" => linkedin_poll
           }
@@ -190,6 +207,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 +239,7 @@ 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:)
         Internal.drop_nil(
           {
             "content" => content,
@@ -230,6 +270,7 @@ module OmniSocials
             "x" => x,
             "bluesky" => bluesky,
             "mastodon" => mastodon,
+            "threads" => threads,
             "google_business" => google_business,
             "linkedin_poll" => linkedin_poll
           }

data/lib/omnisocials/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omnisocials
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - OmniSocials
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-22 00:00:00.000000000 Z
+date: 2026-08-30 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,