omnisocials 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43d0cc71e753d98ddbaa8b1732f140ecfc3d578d02a8e8df81e248c6c9c75131
-  data.tar.gz: a66ae890324f9adc7b37b57add4e76ce1be1b110d4b15f751c611bcbfa6adf61
+  metadata.gz: 26f8bcb600108496ff4cf072d383bf2dbb1082c573b14d2f0e7b8986284c1b1d
+  data.tar.gz: e42dc4799da58ada826fc37d34cab90c96d91b92afed5117f89dce73f01cdf2c
 SHA512:
-  metadata.gz: 0b30af0ebca987fe7bebb4710d7648d2c0361e8709cdf716897d4f1f82808dc916159742dcae7c9c0512863e01f68435d642a9341e8254d9cc11511459b496ce
-  data.tar.gz: e50bd7f05fe6a2e516ff9ea31bb28307af242c4118ca1a30583008b88591e3b2d9c080fb50447137133f036e21d6fed8721b90bd380cfb670dc3870868ac7710
+  metadata.gz: 92398e94cbc636eb8dfede06d8cb2dfc0d5a7239c39ef72e417b6f8de5e982ed8538c4f5d7f61c6bdb70cfc2e52a76a556d58d27bd6c5cf161c784d6a30b824f
+  data.tar.gz: 1a5e379ad7bafe61ba70912d724531670ac7245e44c5d45e4e4968bfb458f0b030ab9a03ec64001fa3ddd6b50021c4854df280af220b1c6413ce17b30ae30d3d

data/README.md

@@ -387,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`.

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/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,

data/lib/omnisocials/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OmniSocials
-  VERSION = "0.8.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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omnisocials
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - OmniSocials
@@ -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