omnisocials 0.6.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b3fed727cadc18b6ea190937598241ea06e5ac3451f5a01e47e993f641f5332
-  data.tar.gz: 6adeeba6ddc69911b79c4b620ddc418e0dd372d6e76e3a417bd285ae54b44e9d
+  metadata.gz: 26f8bcb600108496ff4cf072d383bf2dbb1082c573b14d2f0e7b8986284c1b1d
+  data.tar.gz: e42dc4799da58ada826fc37d34cab90c96d91b92afed5117f89dce73f01cdf2c
 SHA512:
-  metadata.gz: ad4c11a0f91aa25cd0dfab676f0a28b5973d139a82137c0d753de697a453d710bd9f59f6c212596230fe727e37d20e117635d7b23d06f2f6aeeefce3d66b5ffa
-  data.tar.gz: 1b53388871737de150a7d71387472915b3e1bfcc7c8e245f45e5c3d87ea4ef2ee9d8047855876d33e1028c0b24272accfe663ef482e83bbdc4e60a72fe9268af
+  metadata.gz: 92398e94cbc636eb8dfede06d8cb2dfc0d5a7239c39ef72e417b6f8de5e982ed8538c4f5d7f61c6bdb70cfc2e52a76a556d58d27bd6c5cf161c784d6a30b824f
+  data.tar.gz: 1a5e379ad7bafe61ba70912d724531670ac7245e44c5d45e4e4968bfb458f0b030ab9a03ec64001fa3ddd6b50021c4854df280af220b1c6413ce17b30ae30d3d

data/README.md

@@ -208,6 +208,20 @@ client.posts.reject("123", comment: "Wrong CTA link, please fix.") # reject and
 
 Only works on a post with `approval_status: "pending"` (`status: "in_approval"`). Both act on behalf of the user who owns the API key, who must be a listed approver for the workflow's CURRENT step — steps approve in order, so being an approver on a later step is not enough yet (raises a 403 `OmniSocials::PermissionDeniedError`). Approving the last step finalizes the post (`scheduled` or `posting`); rejecting stops the whole workflow immediately, not just the current step.
 
+### Read the approval review
+
+```ruby
+review = client.posts.get_approval("123")["data"]
+if review["status"] == "rejected" && review["rejection"]
+  puts "Rejected by #{review["rejection"]["by"]["name"]}: #{review["rejection"]["reason"]}"
+end
+review["steps"].each do |step|
+  puts "#{step["order"]} #{step["name"]} #{step["status"]}"
+end
+```
+
+`get_approval` returns the review of a post that went through an approval workflow: `status` (`none`, `pending`, `approved`, `rejected`), the `workflow`, who requested it and when, `current_step` (the step the post waits on, `nil` when the review ended), every step with its approvers and their decisions, the `rejection` (`by`, `reason`, `at`, `step`; `nil` when nobody rejected) and the `comments` thread, oldest first. A post without an approval workflow returns `status: "none"` with empty `steps` and `comments`. Read-only; needs the `posts:read` scope.
+
 ## Media
 
 ### Upload from a URL (recommended, up to 1GB)
@@ -231,7 +245,7 @@ media = client.media.upload(file: "/path/to/image.jpg", name: "hero-shot")
 
 `file` accepts a file path (String or Pathname), an IO (`File.open("...", "rb")`, StringIO), or raw bytes as a binary-encoded String (e.g. from `File.binread`).
 
-Uploading a PDF splits it into image slides (max 20 pages) and returns `slides` plus a `media_ids` array. Pass all of `media_ids`, in order, to `posts.create` to publish the deck as a carousel (a native swipeable document on LinkedIn, an image carousel elsewhere).
+Uploading a PDF splits it into image slides (max 20 pages) and returns `slides` plus a `media_ids` array. Pass all of `media_ids`, in order, to `posts.create` to publish the deck as a carousel (on LinkedIn a native swipeable document made from the original PDF file, which is kept so text and links stay intact; an image carousel elsewhere). To keep the PDF as ONE library item instead of one item per page, pass `pdf_mode` = `"document"`: the response then has a single `data` item of type `document` (its page images in `pdf.pages`) and `media_ids` holds that one id, which expands into every page at post time.
 
 Every upload response also includes a `compatibility` block listing any connected platforms that would reject the file.
 
@@ -373,6 +387,32 @@ client.posts.create(
 
 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.
 
+## Pinterest product tags
+
+Tag products on a Pin so people can shop the items in the image. `client.pinterest.list_products` returns the product Pins of the connected Pinterest account; pass their `pin_id` values (max 24) as `"product_tags"` in the `pinterest` options of the post. Only product Pins of your own account can be tagged; products of other merchants cannot. The tags are added right after the Pin is published. A product that Pinterest refuses never fails the post: the outcome is on the post as `pinterest["product_tags_result"]` (`requested`, `tagged`, `skipped`, `error`).
+
+```ruby
+result = client.pinterest.list_products
+
+if result["error"]
+  # HTTP 200 without "products": pinterest_not_connected,
+  # pinterest_catalog_access_required or platform_error
+  warn "#{result["error"]["code"]}: #{result["error"]["message"]}"
+else
+  product_tags = result["products"].first(3).map { |product| product["pin_id"] }
+
+  client.posts.create(
+    content: "Our summer picks",
+    channels: ["pinterest"],
+    media_urls: ["https://example.com/summer-look.jpg"],
+    scheduled_at: "2026-08-01T09:00:00Z",
+    pinterest: { "board_id" => "1234567890", "title" => "Summer picks", "product_tags" => product_tags }
+  )
+end
+```
+
+Without `source:` the list reads the Pinterest catalog (with `price`, `currency`, `availability` and `item_id`) when the connection has catalog access, else the account's own Pins. Catalog access is given one time in the OmniSocials composer: Pinterest options, Add products, Connect catalog. `source: "pins"` scans up to 250 Pins per call, so `"products"` can be empty while `"bookmark"` is set; call again with `bookmark: result["bookmark"]`. To check one Pin id or Pin link before you post, call `client.pinterest.validate_product("813744226420795884")`. On `posts.update` the `pinterest` hash replaces the stored one, so leave `"product_tags"` out to remove the tags.
+
 ## 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`.
@@ -383,7 +423,7 @@ conversations["data"].each do |conversation|
   puts "#{conversation["platform"]}: #{conversation["preview"]}"
 end
 
-conversation_id = conversations["data"][0]["id"]
+conversation_id = conversations["data"][0]["conversation_id"]
 messages = client.inbox.get_messages(conversation_id)
 messages["data"].each do |message|
   puts "#{message["direction"]}: #{message["text"]}"  # direction is "incoming" or "outgoing"
@@ -401,9 +441,9 @@ client.inbox.hide(message_id, hide: false)  # unhide
 client.inbox.delete_message(message_id)
 ```
 
-`platform` accepts `"instagram"`, `"facebook"`, `"linkedin"`, `"tiktok"`, `"youtube"`, `"x"`, or `"threads"`; `type` accepts `"dm"`, `"comment"`, or `"mention"`. Threads conversations are comments (replies people leave on your Threads posts) and mentions; there are no Threads DMs. Comments can be hidden on Facebook, Instagram, TikTok, YouTube, and Threads (Threads: incoming top-level replies only), and a hidden message keeps its place in the conversation with its `hidden` flag set; `hidden` is `true`/`false` on comments and `nil` on DMs. A comment/mention's `post` carries `url` (public link when the platform provides one) and `media_type` (the platform's own label) next to `id`, `caption`, and `thumbnail`. Threads inbox is currently rolling out; until Meta approves the permissions it is disabled on production and calls return a clear error, and it needs a Threads connection with the reply permission (a 401 `reauth_required` means reconnect Threads). TikTok and YouTube replies are comments only; TikTok replies are capped at 150 characters. Conversation ids are URL-encoded for you, so pass them exactly as returned - LinkedIn ids contain `":"` and `"()"` (e.g. `"linkedin_comment_urn:li:activity:123"`).
+`platform` accepts `"instagram"`, `"facebook"`, `"linkedin"`, `"tiktok"`, `"youtube"`, `"x"`, or `"threads"`; `type` accepts `"dm"`, `"comment"`, or `"mention"`. Threads conversations are comments (replies people leave on your Threads posts) and mentions; there are no Threads DMs. Comments can be hidden on Facebook, Instagram, TikTok, YouTube, and Threads (Threads: incoming top-level replies only), and a hidden message keeps its place in the conversation with its `hidden` flag set; `hidden` is `true`/`false` on comments and `nil` on DMs. A comment/mention's `post` carries `url` (public link when the platform provides one) and `media_type` (the platform's own label) next to `id`, `caption`, and `thumbnail`. The Threads inbox needs a Threads connection with the reply permission (a 401 `reauth_required` means reconnect Threads; an account connected before 2026-09-14 needs this once). TikTok and YouTube replies are comments only; TikTok replies are capped at 150 characters. Conversation ids are URL-encoded for you, so pass them exactly as returned - LinkedIn ids contain `":"` and `"()"` (e.g. `"linkedin_comment_urn:li:activity:123"`).
 
-`next` hands out the next conversation that still needs a reply (the customer's latest DM with no reply after it, or an unreplied comment/mention that is not hidden), with the whole thread and the post it belongs to, so a reply can be drafted from one call. Replies typed in the native apps count as answers. Only unread items are served by default, so `mark_read` is the durable way to skip one; `exclude` skips conversation ids for the current session only. Pass `include_next: true` to `reply` to get the following item in the same response. `list_conversations(unanswered: true)` gives the same set as a plain list.
+`next` hands out the next conversation that still needs a reply (the customer's latest DM with no reply after it, or an unreplied comment/mention that is not hidden), with the whole thread and the post it belongs to, so a reply can be drafted from one call. DMs that can still be answered come first, then Instagram/Facebook DMs whose 24-hour window has closed (`reply_window["open"]` is `false`: answer those from the native app or mark them read), then comments and mentions, oldest first. Replies typed in the native apps count as answers. Only unread items are served by default, so `mark_read` is the durable way to skip one; `exclude` skips conversation ids for the current session only. Always pass `message_id: message["id"]` to `reply` on comment threads: every comment on a post shares one conversation, and without it the reply goes under the newest comment on the post. Pass `include_next: true` to `reply` to get the following item in the same response. `list_conversations(unanswered: true)` gives the same set as a plain list.
 
 ```ruby
 item = client.inbox.next(platform: "instagram")
@@ -411,7 +451,20 @@ while item["data"]
   message = item["data"]["message"]
   puts "#{item["remaining"]} left. #{message["sender"]["username"]}: #{message["text"]}"
 
-  reply = client.inbox.reply(message["conversation_id"], text: "Thanks! DM sent.", include_next: true)
+  unless item["data"]["reply_window"]["open"]
+    # An Instagram/Facebook DM past Meta's 24-hour window: reply would raise
+    # 422 outside_messaging_window. Answer it in the app, or skip it.
+    client.inbox.mark_read(message["conversation_id"])
+    item = client.inbox.next(platform: "instagram")
+    next
+  end
+
+  reply = client.inbox.reply(
+    message["conversation_id"],
+    text: "Thanks! DM sent.",
+    message_id: message["id"], # the comment being answered, not the newest one
+    include_next: true
+  )
   item = { "data" => reply["next"], "remaining" => reply["remaining"] || 0 }
 end
 ```
@@ -437,7 +490,7 @@ end
 
 ## Webhooks
 
-Subscribe to `post.scheduled`, `post.published`, and `post.failed` events:
+Subscribe to `post.scheduled`, `post.published`, `post.failed`, `post.approved`, and `post.rejected` events. `post.approved` fires when the last step of a post's approval workflow is approved, `post.rejected` when an approver rejects the post (it will not publish). These two carry `data["approval"]` with `status`, `decided_by` (the approver's user id) and `reason` (`nil` on `post.approved`), and an empty `data["targets"]`.
 
 ```ruby
 webhook = client.webhooks.create(
@@ -480,6 +533,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

@@ -60,7 +60,8 @@ module OmniSocials
 
     attr_reader :api_key, :base_url, :timeout, :max_retries,
                 :posts, :media, :folders, :hashtag_sets, :approval_workflows,
-                :accounts, :analytics, :audio, :locations, :inbox, :webhooks
+                :accounts, :analytics, :audio, :locations, :pinterest, :inbox,
+                :webhooks
 
     # api_key     - API key (omsk_live_* / omsk_test_*). Falls back to the
     #               OMNISOCIALS_API_KEY environment variable. Raises
@@ -94,6 +95,7 @@ module OmniSocials
       @analytics = Resources::Analytics.new(self)
       @audio = Resources::Audio.new(self)
       @locations = Resources::Locations.new(self)
+      @pinterest = Resources::Pinterest.new(self)
       @inbox = Resources::Inbox.new(self)
       @webhooks = Resources::Webhooks.new(self)
     end

data/lib/omnisocials/resources/inbox.rb

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

data/lib/omnisocials/resources/media.rb

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

data/lib/omnisocials/resources/pinterest.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Pinterest resource: product Pins for product tagging (list + validate).
+    class Pinterest
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /pinterest/products - list the product Pins of the connected
+      # Pinterest account. Pass a result's pin_id in
+      # pinterest: { "product_tags" => [...] } on post create/update to tag
+      # the product on the Pin (max 24 per Pin). Pinterest only accepts a
+      # product Pin that is public, belongs to the same account and links to
+      # a website that account claimed; products of other merchants cannot
+      # be tagged.
+      #
+      # source is "catalog" or "pins". "catalog" reads the Pinterest catalog
+      # (with price, currency, availability, item_id) and needs catalog
+      # access, which is given one time in the OmniSocials composer
+      # (Pinterest options, Add products, Connect catalog); product_group_id
+      # and page_size (1..100, default 25) apply to this source only. "pins"
+      # reads the account's own Pins and works on every connection; one call
+      # scans up to 250 Pins, so "products" can be empty while "bookmark" is
+      # set (call again with bookmark:). When source is left out the API
+      # uses "catalog" when the connection has catalog access, else "pins".
+      #
+      # Response (not the usual "data" envelope):
+      # { "products" => [{ pin_id, title, description, link, image_url,
+      # price, currency, availability, item_id }], "bookmark", "source",
+      # "catalog_access" } plus "product_groups" and "product_group_id" for
+      # the catalog source, or { "error" => { "code", "message" } } without
+      # "products" when the list could not be read, both with HTTP 200. code
+      # is one of "pinterest_not_connected",
+      # "pinterest_catalog_access_required" or "platform_error". A bad source
+      # or product_group_id raises a 400 with the standard error envelope.
+      def list_products(source: nil, product_group_id: nil, bookmark: nil,
+                        page_size: nil)
+        @client.request(
+          "GET", "/pinterest/products",
+          query: {
+            "source" => source,
+            "product_group_id" => product_group_id,
+            "bookmark" => bookmark,
+            "page_size" => page_size
+          }
+        )
+      end
+
+      # GET /pinterest/products/validate?id= - check whether a Pin can be
+      # used in pinterest product_tags before creating the post. id is a Pin
+      # id or a Pin link (https://www.pinterest.com/pin/<id>/). Response:
+      # { "valid", "pin_id", ... }; "unverified" => true means the check
+      # could not run and the publish step is the final check.
+      def validate_product(id)
+        @client.request("GET", "/pinterest/products/validate", query: { "id" => id })
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/posts.rb

@@ -86,6 +86,16 @@ module OmniSocials
       # 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).
+      #
+      # Pinterest posts can tag products: pass
+      # pinterest: { "board_id" => "...", "product_tags" => [...] } with up
+      # to 24 product Pins of the connected Pinterest account, each as a Pin
+      # id String (see pinterest.list_products) or a Pin link. Products of
+      # other merchants cannot be tagged. The tags are added right after the
+      # Pin is published; a product Pinterest refuses never fails the post,
+      # and the Post's "pinterest" block then carries "product_tags_result"
+      # (requested, tagged, skipped, error). More than 24 entries or an
+      # invalid entry raises a 400 validation_error.
       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,
@@ -154,6 +164,9 @@ module OmniSocials
       # and threads thread parts, and to a Threads location tag:
       # threads: { "location_id" => nil } (or "location" => nil) clears it.
       #
+      # pinterest replaces the stored Pinterest options wholesale, so leave
+      # "product_tags" out (or send []) to remove the product tags.
+      #
       # See #create for the 402 "x_credits_insufficient" credit gate that
       # can also refuse an update to a scheduled X link post.
       def update(post_id, content: nil, scheduled_at: nil, channels: nil,
@@ -238,6 +251,22 @@ module OmniSocials
         @client.request("POST", "/posts/#{post_id}/reject", json: body)
       end
 
+      # GET /posts/{id}/approval - the approval review of a post: every step
+      # with its approvers and their decisions, the rejection with its
+      # reason, and the comment thread. Use it when approval_status is
+      # "rejected" to learn who rejected the post and why, or while it is
+      # "pending" to see who the post waits for.
+      #
+      # `data` carries post_id, status ("none", "pending", "approved",
+      # "rejected"), workflow, requested_by, requested_at, current_step,
+      # steps, rejection and comments (oldest first). A post without an
+      # approval workflow returns status "none" with the object fields nil
+      # and empty steps and comments. Read-only; requires the posts:read
+      # scope.
+      def get_approval(post_id)
+        @client.request("GET", "/posts/#{post_id}/approval")
+      end
+
       private
 
       def create_body(content:, channels:, scheduled_at:, media_ids:,

data/lib/omnisocials/resources/webhooks.rb

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

data/lib/omnisocials/version.rb

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

data/lib/omnisocials.rb

@@ -25,6 +25,7 @@ require_relative "omnisocials/resources/accounts"
 require_relative "omnisocials/resources/analytics"
 require_relative "omnisocials/resources/audio"
 require_relative "omnisocials/resources/locations"
+require_relative "omnisocials/resources/pinterest"
 require_relative "omnisocials/resources/inbox"
 require_relative "omnisocials/resources/webhooks"
 require_relative "omnisocials/client"

metadata

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