omnisocials 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 712ed8026c6e6223f5d2bbcaaa0696cda2ed181ab8f4da6bd2b95fd2430bc84e
-  data.tar.gz: 2e1cf587a451e8f966800ddef4f74b1b8a0422e0df7fd7ffb078afdf5e1636eb
+  metadata.gz: 27468385685af2b1f49e6665393bb687f2dd9fc18cf7d06b98190c78c9b3c3fe
+  data.tar.gz: 24dafc551dc62fd9922aa9ce330ae138288a3ecd86dc768abcf35e2f5f466cae
 SHA512:
-  metadata.gz: f45800a5a3a36c56e37df9085ee31c95182cfaec1f1a30224a65a82d538884f66c40bbd677b48a47236dd92dcc41e81db6e869c066d10f4b360debb566eb1d80
-  data.tar.gz: 48569b613c4247848a3638727b65f8ba71ac1a9e1f1051c12843f02e738771536058290909d6623a97b5c1dc09d92eacf9c5c12c917196b5f7467917178e320e
+  metadata.gz: 43d61512382a55a5ef87c2e906f28f55153a15d3deed758262e6f919eeb934e5de86be8e700570ffc2bb9862a33e111e285085248ed0bbd7f3645046a3dcf6ce
+  data.tar.gz: 93c23762f52f0550bf38fcae55d850aafa24365966adad31d71b603c8c9fbee3c297be8cb31219d947fc2dd38d1d7b7b2252642460ae98d65a024060cb3d16ba

data/README.md

@@ -425,6 +425,37 @@ client.posts.create(
 )
 ```
 
+## Post tags
+
+Tags are your workspace's own labels for posts (a hook style, a format, a campaign), to filter posts and compare how each kind does. They never go to a platform. Uses the `posts:read` / `posts:write` scopes; the comparison uses `analytics:read`. A tag is `{ "id", "name", "color", "created_at" }`; names are unique in the workspace (case-insensitive, max 40 characters), at most 200 tags per workspace.
+
+```ruby
+tag = client.tags.create(name: "Question", color: "teal")  # color is optional
+client.tags.list
+client.tags.update(tag["data"]["id"], name: "Question hook")
+client.tags.delete(tag["data"]["id"])  # { "data" => { "tag" => ..., "posts_untagged" => 4 } }
+
+# Tag a post: ids or names, a new name becomes a tag (at most 20 per post)
+client.posts.create(content: "Would you post this?", channels: ["instagram"], tags: ["Question"])
+client.posts.update("1024", tags: ["Question", "Talking head"])  # replaces; tags: nil or [] removes all
+
+# Up to 500 posts at once, published ones included: add, remove or set (replace)
+result = client.tags.apply(post_ids: ["1024", "1025"], add: ["Question"], remove: ["Listicle"])
+puts result["data"]["updated"], result["data"]["not_found"].inspect
+
+# Filter by tag (an id or name, or an Array: posts with any of them)
+client.posts.list(tag: "Question")
+client.analytics.overview(period: "30d", tag: ["Question", "Talking head"])
+
+# How each tag did against your normal (default: the last 90 days)
+compare = client.analytics.tags(start_date: "2026-08-01", end_date: "2026-10-31")
+compare["data"]["tags"].each do |row|
+  puts "#{row["tag"]["name"]} #{row["vs_normal"]} #{row["enough_posts"]}"  # vs_normal 0.38 = 38% above
+end
+```
+
+`analytics.tags` returns `period`, `platform`, `min_posts`, `tags` (comparable tags first, best first; each with `posts`, `measured`, `median_impressions`, `engagement_rate` in percent, `vs_normal` as a fraction, `best_channel` and `enough_posts`), `untagged` (the same numbers for posts without a tag) and `normals` (median impressions per channel). `platform:` keeps one channel's numbers and `min_posts:` (default 5) sets how many measured posts a tag needs before `enough_posts` is true. Every post carries `tags` and `trial_reel` (`{ "strategy" => "MANUAL" | "SS_PERFORMANCE" }` for an Instagram Trial Reel, else `nil`), and so does every entry of `analytics.posts`. Errors: `404 tag_not_found`, `409 tag_exists` (the existing tag is in `e.body["error"]["tag"]`), `409 tag_limit_reached`, `400 invalid_tag_name`, `invalid_tag_color`, `invalid_tags`, `invalid_post_ids`, `too_many_posts`, `too_many_tags`.
+
 ## Accounts
 
 ```ruby

data/lib/omnisocials/client.rb

@@ -61,7 +61,7 @@ module OmniSocials
     attr_reader :api_key, :base_url, :timeout, :max_retries,
                 :posts, :media, :folders, :hashtag_sets, :approval_workflows,
                 :accounts, :analytics, :audio, :locations, :pinterest,
-                :automations, :inbox, :webhooks
+                :automations, :inbox, :webhooks, :tags
 
     # api_key     - API key (omsk_live_*). Falls back to the
     #               OMNISOCIALS_API_KEY environment variable. Raises
@@ -90,6 +90,7 @@ module OmniSocials
       @media = Resources::Media.new(self)
       @folders = Resources::Folders.new(self)
       @hashtag_sets = Resources::HashtagSets.new(self)
+      @tags = Resources::Tags.new(self)
       @approval_workflows = Resources::ApprovalWorkflows.new(self)
       @accounts = Resources::Accounts.new(self)
       @analytics = Resources::Analytics.new(self)

data/lib/omnisocials/resources/analytics.rb

@@ -15,7 +15,9 @@ module OmniSocials
 
       # GET /analytics/posts?ids=a,b,c - bulk metrics for up to 100 posts in
       # one request. `ids` is an Array of post ids (or an already-joined
-      # comma-separated String).
+      # comma-separated String). Each entry also carries "tags" (the post's
+      # tags) and "trial_reel" ({ "strategy" => "MANUAL" | "SS_PERFORMANCE" }
+      # for an Instagram Trial Reel, else nil).
       def posts(ids)
         @client.request(
           "GET", "/analytics/posts",
@@ -24,10 +26,17 @@ module OmniSocials
       end
 
       # GET /analytics/overview - workspace-wide analytics overview.
-      def overview(period: nil, start_date: nil, end_date: nil)
+      #
+      # tag (a tag id or name, or an Array of them: any of them) keeps the
+      # post numbers of the posts with that tag; account numbers stay those
+      # of the whole account. An unknown tag is a 404 tag_not_found.
+      def overview(period: nil, start_date: nil, end_date: nil, tag: nil)
         @client.request(
           "GET", "/analytics/overview",
-          query: { "period" => period, "start_date" => start_date, "end_date" => end_date }
+          query: {
+            "period" => period, "start_date" => start_date, "end_date" => end_date,
+            "tag" => Tags.tag_query(tag)
+          }
         )
       end
 
@@ -49,6 +58,28 @@ module OmniSocials
           query: { "platform" => platform, "timezone" => timezone }
         )
       end
+
+      # GET /analytics/tags - how each tag did against your normal, for the
+      # published posts in a period (default the last 90 days).
+      #
+      # Returns { "data" => { "period", "platform", "min_posts", "tags",
+      # "untagged", "normals" } }. Each entry of "tags" is { "tag", "posts",
+      # "measured", "median_impressions", "engagement_rate" (percent),
+      # "vs_normal" (fraction: 0.38 = 38% above your normal), "best_channel",
+      # "enough_posts" }, comparable tags first, best first; "untagged" has
+      # the same numbers for the posts without a tag, "normals" the median
+      # impressions per channel. platform keeps one channel's numbers;
+      # min_posts (1 to 50, default 5) is the measured posts a tag needs
+      # before "enough_posts" is true.
+      def tags(start_date: nil, end_date: nil, platform: nil, min_posts: nil)
+        @client.request(
+          "GET", "/analytics/tags",
+          query: {
+            "start_date" => start_date, "end_date" => end_date,
+            "platform" => platform, "min_posts" => min_posts
+          }
+        )
+      end
     end
   end
 end

data/lib/omnisocials/resources/posts.rb

@@ -21,10 +21,17 @@ module OmniSocials
       # GET /posts - list posts (status: draft, in_approval, scheduled, posting,
       # posted, failed, warning; in_approval = waiting for a reviewer in an
       # approval workflow).
-      def list(status: nil, limit: nil, offset: nil)
+      # tag (a tag id or name, or an Array of them) keeps the posts with any
+      # of those tags; an unknown tag is a 404 tag_not_found. Every post
+      # carries "tags" (its tags) and "trial_reel" ({ "strategy" =>
+      # "MANUAL" | "SS_PERFORMANCE" } for an Instagram Trial Reel, else nil).
+      def list(status: nil, limit: nil, offset: nil, tag: nil)
         @client.request(
           "GET", "/posts",
-          query: { "status" => status, "limit" => limit, "offset" => offset }
+          query: {
+            "status" => status, "limit" => limit, "offset" => offset,
+            "tag" => Tags.tag_query(tag)
+          }
         )
       end
 
@@ -169,6 +176,11 @@ module OmniSocials
       # nil, plus "platforms" and "automations", one { "id", "platform",
       # "status" } per channel); each starts listening once the post is
       # live on its channel.
+      #
+      # tags labels the post with the workspace's own tags (ids or names, at
+      # most 20; a name that does not exist yet becomes a new tag) to filter
+      # and compare posts in Analytics. Tags never go to a platform. Errors:
+      # 404 tag_not_found (an unknown id), 400 invalid_tags / too_many_tags.
       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,
@@ -180,7 +192,7 @@ module OmniSocials
                  mastodon: nil, threads: nil, google_business: nil,
                  telegram: nil, discord: nil, linkedin_poll: nil,
                  approval_workflow_id: nil, draft: nil, media_fit: nil,
-                 comment_dm_automation: nil)
+                 comment_dm_automation: nil, tags: nil)
         body = create_body(
           content: content, channels: channels, scheduled_at: scheduled_at,
           media_ids: media_ids, media_urls: media_urls, type: type,
@@ -196,7 +208,8 @@ module OmniSocials
           google_business: google_business, telegram: telegram,
           discord: discord, linkedin_poll: linkedin_poll,
           approval_workflow_id: approval_workflow_id, draft: draft,
-          media_fit: media_fit, comment_dm_automation: comment_dm_automation
+          media_fit: media_fit, comment_dm_automation: comment_dm_automation,
+          tags: tags
         )
         @client.request("POST", "/posts/create", json: body)
       end
@@ -204,8 +217,8 @@ module OmniSocials
       # POST /posts/create-and-publish - create and publish immediately.
       # See #create for the "warnings" array (X link posts, and the
       # "image_fit" entries steered by media_fit), the 402
-      # "x_credits_insufficient" credit gate on X link posts and
-      # comment_dm_automation.
+      # "x_credits_insufficient" credit gate on X link posts,
+      # comment_dm_automation and tags.
       def create_and_publish(content:, channels: nil, media_ids: nil,
                              media_urls: nil, type: nil, source: nil,
                              link_url: nil, link_title: nil, link_description: nil,
@@ -219,7 +232,7 @@ module OmniSocials
                              threads: nil, google_business: nil,
                              telegram: nil, discord: nil, linkedin_poll: nil,
                              media_fit: nil,
-                             comment_dm_automation: nil)
+                             comment_dm_automation: nil, tags: nil)
         body = create_body(
           content: content, channels: channels, scheduled_at: nil,
           media_ids: media_ids, media_urls: media_urls, type: type,
@@ -234,7 +247,8 @@ module OmniSocials
           x: x, bluesky: bluesky, mastodon: mastodon, threads: threads,
           google_business: google_business, telegram: telegram,
           discord: discord, linkedin_poll: linkedin_poll,
-          media_fit: media_fit, comment_dm_automation: comment_dm_automation
+          media_fit: media_fit, comment_dm_automation: comment_dm_automation,
+          tags: tags
         )
         @client.request("POST", "/posts/create-and-publish", json: body)
       end
@@ -275,6 +289,11 @@ module OmniSocials
       # discord merges into the stored Discord options: a key set to nil
       # removes that option (e.g. discord: { "poll" => nil }), an explicit
       # discord: nil removes every option, and leaving it out keeps them.
+      #
+      # tags (ids or names, a new name becomes a tag) replaces the post's
+      # tags; tags: nil or tags: [] removes them all, and leaving it out
+      # keeps them. An update with only tags works on every post, published
+      # and failed ones included.
       def update(post_id, content: nil, scheduled_at: nil, channels: nil,
                  media_ids: nil, media_urls: nil, type: nil, location_id: nil,
                  collaborators: nil, user_tags: nil, pinterest: nil,
@@ -283,7 +302,8 @@ module OmniSocials
                  mastodon: nil, threads: nil, google_business: nil,
                  telegram: nil, discord: OmniSocials::NOT_GIVEN,
                  linkedin_poll: nil, draft: nil, media_fit: nil,
-                 comment_dm_automation: OmniSocials::NOT_GIVEN)
+                 comment_dm_automation: OmniSocials::NOT_GIVEN,
+                 tags: OmniSocials::NOT_GIVEN)
         body = Internal.drop_nil(
           {
             "content" => content,
@@ -318,6 +338,8 @@ module OmniSocials
         body["comment_dm_automation"] = comment_dm_automation unless comment_dm_automation.is_a?(NotGiven)
         # Same for discord: an explicit nil removes every Discord option.
         body["discord"] = discord unless discord.is_a?(NotGiven)
+        # And for tags: an explicit nil (or []) removes every tag of the post.
+        body["tags"] = tags unless tags.is_a?(NotGiven)
         @client.request("PATCH", "/posts/#{post_id}", json: body)
       end
 
@@ -395,7 +417,7 @@ module OmniSocials
                       threads:, google_business:, linkedin_poll:,
                       telegram: nil, discord: nil, approval_workflow_id: nil,
                       draft: nil,
-                      media_fit: nil, comment_dm_automation: nil)
+                      media_fit: nil, comment_dm_automation: nil, tags: nil)
         Internal.drop_nil(
           {
             "content" => content,
@@ -434,7 +456,8 @@ module OmniSocials
             "approval_workflow_id" => approval_workflow_id,
             "draft" => draft,
             "media_fit" => media_fit,
-            "comment_dm_automation" => comment_dm_automation
+            "comment_dm_automation" => comment_dm_automation,
+            "tags" => tags
           }
         )
       end

data/lib/omnisocials/resources/tags.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Tags resource: the workspace's own labels for its posts (a hook style,
+    # a format), to filter and compare posts in Analytics. Tags never go to a
+    # platform.
+    #
+    # Set them on a post with tags: on posts.create / create_and_publish /
+    # update, in bulk with #apply, filter with tag: on posts.list and
+    # analytics.overview, and compare them with analytics.tags. A tag
+    # reference is a tag id (Integer or String) or a tag name
+    # (case-insensitive); in add / set (and tags: on posts) a name that does
+    # not exist yet becomes a new tag.
+    class Tags
+      # Serialize the tag filter: one id or name, or an Array joined with ",".
+      def self.tag_query(tag)
+        return nil if tag.nil?
+        return tag.map(&:to_s).join(",") if tag.is_a?(Array)
+
+        tag.to_s
+      end
+
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /tags - every tag of the workspace, by name. Each tag is
+      # { "id", "name", "color", "created_at" }. Scope posts:read.
+      def list
+        @client.request("GET", "/tags")
+      end
+
+      # POST /tags - create a tag. `name` is at most 40 characters and unique
+      # in the workspace (case-insensitive); `color` is one of blue, green,
+      # orange, red, purple, pink, teal, yellow, brown, gray (omit it to get
+      # the next colour). At most 200 tags per workspace.
+      #
+      # Errors: 409 tag_exists (the existing tag is in
+      # error.body["error"]["tag"]), 409 tag_limit_reached,
+      # 400 invalid_tag_name / invalid_tag_color.
+      def create(name:, color: nil)
+        @client.request(
+          "POST", "/tags",
+          json: Internal.drop_nil({ "name" => name, "color" => color })
+        )
+      end
+
+      # PATCH /tags/{id} - rename or recolour a tag. Only the keys you pass
+      # are sent; posts keep the tag. Errors: 404 tag_not_found,
+      # 409 tag_exists.
+      def update(tag_id, name: nil, color: nil)
+        body = Internal.drop_nil({ "name" => name, "color" => color })
+        @client.request("PATCH", "/tags/#{tag_id}", json: body)
+      end
+
+      # DELETE /tags/{id} - delete a tag and take it off every post (the
+      # posts stay). Returns { "data" => { "tag", "posts_untagged" } }.
+      def delete(tag_id)
+        @client.request("DELETE", "/tags/#{tag_id}")
+      end
+
+      # POST /tags/apply - add, remove or replace the tags of up to 500 posts
+      # at once, published ones included.
+      #
+      # add, remove and set take tag ids or names; a new name in add or set
+      # becomes a tag. set replaces a post's tags (set: [] removes them all),
+      # add and remove change only the tags you name. Returns
+      # { "data" => { "updated", "posts" => [{ "id", "tags" }], "not_found" } };
+      # not_found lists the post ids that are not posts of this workspace.
+      # Errors: 400 invalid_post_ids / too_many_posts / too_many_tags /
+      # invalid_tags, 404 tag_not_found.
+      def apply(post_ids:, add: nil, remove: nil, set: nil)
+        body = Internal.drop_nil(
+          {
+            "post_ids" => Array(post_ids).map(&:to_s),
+            "add" => add,
+            "remove" => remove,
+            "set" => set
+          }
+        )
+        @client.request("POST", "/tags/apply", json: body)
+      end
+    end
+  end
+end

data/lib/omnisocials/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OmniSocials
-  VERSION = "0.13.0"
+  VERSION = "0.14.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/tags"
 require_relative "omnisocials/resources/approval_workflows"
 require_relative "omnisocials/resources/accounts"
 require_relative "omnisocials/resources/analytics"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omnisocials
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - OmniSocials
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-27 00:00:00.000000000 Z
+date: 2026-11-02 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,
@@ -37,6 +37,7 @@ files:
 - lib/omnisocials/resources/media.rb
 - lib/omnisocials/resources/pinterest.rb
 - lib/omnisocials/resources/posts.rb
+- lib/omnisocials/resources/tags.rb
 - lib/omnisocials/resources/webhooks.rb
 - lib/omnisocials/version.rb
 - lib/omnisocials/webhooks.rb