omnisocials 0.13.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 712ed8026c6e6223f5d2bbcaaa0696cda2ed181ab8f4da6bd2b95fd2430bc84e
4
- data.tar.gz: 2e1cf587a451e8f966800ddef4f74b1b8a0422e0df7fd7ffb078afdf5e1636eb
3
+ metadata.gz: 8c00d8899c0d1c024d739775a25508750dfada8a2be74eb4ecdc2b855b39cafe
4
+ data.tar.gz: cad371c9a76055c3331232856d48192f638e1fa382482c018b9b78ff0dc47017
5
5
  SHA512:
6
- metadata.gz: f45800a5a3a36c56e37df9085ee31c95182cfaec1f1a30224a65a82d538884f66c40bbd677b48a47236dd92dcc41e81db6e869c066d10f4b360debb566eb1d80
7
- data.tar.gz: 48569b613c4247848a3638727b65f8ba71ac1a9e1f1051c12843f02e738771536058290909d6623a97b5c1dc09d92eacf9c5c12c917196b5f7467917178e320e
6
+ metadata.gz: 93ae9f8f0a567e517c3c45408eaf22f9663d2e9354526d37b05be404ce5805021c70852cedef9a081d4cd27c824ef88e8a9966c8a2c6d9d11b077b29c2e98d2f
7
+ data.tar.gz: 4bfa021ebf8d846b0e705ebd0fdcd95343b0b508c433f9f5e2a86c843f5e8c413044599b176203f0b7c46090204ad537cadf57b758ee23707063bb298c5aba72
data/README.md CHANGED
@@ -111,7 +111,23 @@ events["data"].each do |event|
111
111
  end
112
112
  ```
113
113
 
114
- The events response is `{ "data", "counts", "pagination" }`, not the plain list: `counts` is the number of events per outcome (`sent`, `skipped`, `failed`, `pending`, `queued`, `opted_out`). An automation can also listen on a post published outside OmniSocials (`client.automations.create(instagram_media_id: ..., actions: ...)`), on the next post the workspace publishes (`trigger: { "scope" => "next_post" }`) or on every post (`"scope" => "any"`), and on DMs and story replies (`trigger: { "kinds" => ["dm", "story_reply"], ... }`).
114
+ The events response is `{ "data", "counts", "pagination" }`, not the plain list: `counts` is the number of events per outcome (`sent`, `skipped`, `failed`, `pending`, `queued`, `opted_out`, `waiting`). An automation can also listen on a post published outside OmniSocials (`client.automations.create(instagram_media_id: ..., actions: ...)`), on the next post the workspace publishes (`trigger: { "scope" => "next_post" }`) or on every post (`"scope" => "any"`), and on DMs and story replies (`trigger: { "kinds" => ["dm", "story_reply"], ... }`).
115
+
116
+ Follow first (`"follow_gate"` in the actions, Instagram only) sends the link only to people who follow the account. On a comment the private reply is a first message with one button; a tap makes OmniSocials ask Instagram whether the person follows. A follower gets the DM text, anyone else gets the `not_following` message with its button, and every later tap checks again. A DM or a story reply is checked at once. When Instagram gives no answer the link goes out anyway. Texts hold 640 characters and buttons 20; leave them out for the defaults. A person who has not followed yet is an event with outcome `waiting` and `event["follow_gate"]` (`state`, `taps`, `followed`, `checked`, `after_ask`); `stats["followed"]` counts the people who followed after the ask. `"enabled" => true` on a Facebook or X automation is a `400 follow_gate_instagram_only`.
117
+
118
+ ```ruby
119
+ client.automations.update(
120
+ automation_id,
121
+ actions: {
122
+ "dm" => { "text" => "Here is the guide: https://example.com/guide" },
123
+ "follow_gate" => {
124
+ "enabled" => true,
125
+ "first_message" => { "text" => "Tap the button and I'll send you the link 👇", "button" => "Send me the link" },
126
+ "not_following" => { "text" => "Almost there! Follow @yourbrand first, then tap the button again.", "button" => "I follow now" }
127
+ }
128
+ }
129
+ )
130
+ ```
115
131
 
116
132
  A Facebook Page works the same way, and the DM lands in Messenger: pass `platform: "facebook"` to `client.automations.create`, or `facebook_post_id: ...` for a Page post published outside OmniSocials. On a post, `comment_dm_automation: { "platforms" => ["instagram", "facebook"], ... }` makes one automation per channel with the same keywords and DM. Facebook has no story replies.
117
133
 
@@ -425,6 +441,37 @@ client.posts.create(
425
441
  )
426
442
  ```
427
443
 
444
+ ## Post tags
445
+
446
+ 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.
447
+
448
+ ```ruby
449
+ tag = client.tags.create(name: "Question", color: "teal") # color is optional
450
+ client.tags.list
451
+ client.tags.update(tag["data"]["id"], name: "Question hook")
452
+ client.tags.delete(tag["data"]["id"]) # { "data" => { "tag" => ..., "posts_untagged" => 4 } }
453
+
454
+ # Tag a post: ids or names, a new name becomes a tag (at most 20 per post)
455
+ client.posts.create(content: "Would you post this?", channels: ["instagram"], tags: ["Question"])
456
+ client.posts.update("1024", tags: ["Question", "Talking head"]) # replaces; tags: nil or [] removes all
457
+
458
+ # Up to 500 posts at once, published ones included: add, remove or set (replace)
459
+ result = client.tags.apply(post_ids: ["1024", "1025"], add: ["Question"], remove: ["Listicle"])
460
+ puts result["data"]["updated"], result["data"]["not_found"].inspect
461
+
462
+ # Filter by tag (an id or name, or an Array: posts with any of them)
463
+ client.posts.list(tag: "Question")
464
+ client.analytics.overview(period: "30d", tag: ["Question", "Talking head"])
465
+
466
+ # How each tag did against your normal (default: the last 90 days)
467
+ compare = client.analytics.tags(start_date: "2026-08-01", end_date: "2026-10-31")
468
+ compare["data"]["tags"].each do |row|
469
+ puts "#{row["tag"]["name"]} #{row["vs_normal"]} #{row["enough_posts"]}" # vs_normal 0.38 = 38% above
470
+ end
471
+ ```
472
+
473
+ `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`.
474
+
428
475
  ## Accounts
429
476
 
430
477
  ```ruby
@@ -544,6 +591,7 @@ client.inbox.reply(conversation_id, text: "Thanks for reaching out!")
544
591
  message_id = messages["data"][0]["id"]
545
592
  client.inbox.hide(message_id) # hide
546
593
  client.inbox.hide(message_id, hide: false) # unhide
594
+ # Delete a comment, or one of your own replies (Facebook, Instagram, TikTok).
547
595
  client.inbox.delete_message(message_id)
548
596
 
549
597
  # Like a comment as the Page or account (Facebook, LinkedIn Page, TikTok).
@@ -600,9 +648,68 @@ end
600
648
 
601
649
  `x_inbox_suspended` fires once a workspace's X inbox has auto-suspended after its credit balance hit zero; topping up and re-enabling it in the dashboard resumes delivery, but DMs that arrived while suspended are not recovered.
602
650
 
651
+ ## Ads
652
+
653
+ Boost a published post or create a new ad on Meta, Pinterest, TikTok, LinkedIn, X and Google. Ads spend real money, so every call that starts or raises spend asks for the amount again: `ads.activate`, `ads.activate_multi`, `ads.drafts.launch` and a budget raise through `ads.update`. Show the person the amount first and pass it only after they agree. These calls (and `ads.resume`) are not retried after a 5xx or a timeout, because the first attempt may have started the ad: read the campaign or the draft to see what happened.
654
+
655
+ The `ads:read` and `ads:write` scopes are opt-in: create the API key with **Ads** switched on (Settings, API). A key without them gets `403 insufficient_scope`. Ad accounts are connected and picked in the OmniSocials dashboard. Budgets are in major units (10 = 10 EUR) in the ad account's currency. Ad account and campaign ids come back as strings (`"51"`); the methods take an id as a string or a number.
656
+
657
+ ### Create an ad (draft, then launch)
658
+
659
+ ```ruby
660
+ caps = client.ads.capabilities
661
+ p caps["data"]["create_networks"], caps["data"]["network_states"]
662
+
663
+ draft = client.ads.drafts.create(
664
+ name: "Autumn sale",
665
+ objective: "traffic",
666
+ platforms: %w[meta linkedin],
667
+ budget: { "amount" => 10, "currency" => "EUR" },
668
+ schedule: { "duration_days" => 7 },
669
+ targeting: { "countries" => %w[NL BE], "automatic_audience" => true },
670
+ ads: [
671
+ {
672
+ "media" => [{ "url" => "https://example.com/sale.jpg", "type" => "image", "width" => 1080, "height" => 1350 }],
673
+ "primary_text" => "30% off everything this week",
674
+ "headline" => "Autumn sale",
675
+ "cta" => "shop_now",
676
+ "link" => "https://example.com/sale"
677
+ }
678
+ ]
679
+ )["data"]
680
+
681
+ # A draft spends nothing. Hand draft["review_url"] to the person, or start it
682
+ # after they confirmed 10 EUR a day per network:
683
+ launch = client.ads.drafts.launch(draft["group_id"], confirm_budget_amount: 10)["data"]
684
+ launch["results"].each do |result|
685
+ puts "#{result["platform"]}: #{result["ok"] ? "started" : result["error"]}"
686
+ end
687
+ ```
688
+
689
+ A draft needs no ad account; `client.ads.drafts.attach_account(group_id, platform: "meta", ad_account_id: "51")` sets one, and `campaigns[].readiness` says what still stops a network. `client.ads.drafts.update(group_id, ...)` replaces the whole draft (HTTP PUT), so send every field again. On Meta an ad can carry a second upright 9:16 file for Stories and Reels: `"placement_media" => { "stories_reels" => { "url" => ..., "type" => ... } }`.
690
+
691
+ ### Boost a post
692
+
693
+ ```ruby
694
+ accounts = client.ads.list_accounts["data"]
695
+ meta = accounts.find { |account| account["platform"] == "meta" && account["is_selected"] }
696
+
697
+ boost = client.ads.boost(
698
+ post_id: 12_345,
699
+ ad_account_id: meta["id"],
700
+ budget: { "type" => "daily", "amount" => 5, "currency" => meta.dig("account_info", "currency") || "EUR" },
701
+ targeting: { "countries" => ["NL"] }
702
+ )["data"]
703
+
704
+ # The boost is a draft. Start it only after the person confirmed 5 a day:
705
+ client.ads.activate(boost["id"], 5)
706
+ ```
707
+
708
+ `client.ads.boost_multi` makes one draft boost per ad account (up to 10, the same budget each). `client.ads.suggestions` lists posts that do better than your median, `client.ads.overview` the totals, and `client.ads.list`, `get`, `pause`, `resume` and `delete` manage campaigns. Keyword ideas through the connected Google Ads account: `client.ads.research_keywords(keywords: ["running shoes"], country: "NL")` and `client.ads.keyword_metrics(keywords: [...])`.
709
+
603
710
  ## Webhooks
604
711
 
605
- 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"]`.
712
+ 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"]`. `ad.status_changed` fires when an ad campaign changes status (for example `pending_review` to `active` or `rejected`); its `data` is the campaign, not a post: `campaign_id`, `workspace_id`, `name`, `platform`, `campaign_type`, `status`, `previous_status`, `external_campaign_id` and `budget`.
606
713
 
607
714
  ```ruby
608
715
  webhook = client.webhooks.create(
@@ -684,6 +791,39 @@ run app
684
791
 
685
792
  `OmniSocials::Webhooks.verify` uses a constant-time comparison, rejects timestamps older than `tolerance` seconds (default 300) to block replays, and returns the parsed event Hash on success. Respond with any 2xx within 10 seconds to acknowledge; deliveries are retried up to 3 times.
686
793
 
794
+ ## Limits and feature requests
795
+
796
+ `client.limits.list` lists what OmniSocials cannot do, why (`says`) and what to do instead (`instead`): platform rules, features not built yet, features that work in the OmniSocials app only. Read it before you tell a person that something is not possible. When the person still wants a `requestable` entry, send a feature request with its `limit_id`. The request is stored for the person who owns the key; they see it in OmniSocials (Settings, Request a feature) and get an email when its status changes. Works with every key, no scope needed.
797
+
798
+ ```ruby
799
+ limits = client.limits.list(platform: "telegram") # area: "posts" | "inbox" | ...
800
+ limits["data"].each do |limit|
801
+ puts [limit["id"], limit["says"], limit["instead"], limit["requestable"]].inspect
802
+ end
803
+
804
+ begin
805
+ result = client.feature_requests.create(
806
+ summary: "Post our daily update to the Announcements topic of our Telegram group, not to the whole group.",
807
+ platform: "telegram",
808
+ limit_id: "telegram.forum_topics"
809
+ )
810
+ # "created" (new), "voted" (added a vote to your organisation's open request)
811
+ # or "already_requested" (you asked before; data is that request)
812
+ puts result["outcome"], result["data"]["id"], result["data"]["status"]
813
+ rescue OmniSocials::APIError => e
814
+ raise unless e.code == "not_requestable"
815
+
816
+ # A platform rule or a choice of OmniSocials: nothing was stored.
817
+ limit = e.body["error"]["limit"]
818
+ puts limit["says"], limit["instead"]
819
+ end
820
+
821
+ mine = client.feature_requests.list # newest first, at most 50
822
+ one = client.feature_requests.get(mine["data"].first["id"]) # status, team_answer, team_replies
823
+ ```
824
+
825
+ A limit is `{ "id", "kind", "kind_label", "area", "platforms", "title", "says", "instead", "requestable" }`; `kind` is `platform`, `by_design`, `not_built`, `beta`, `dashboard_only` or `needs_setup`, and `requestable` is false for `platform` and `by_design`. `limits.list` also returns `kinds` (a label per kind). A request carries `status` (`open`, `in_progress`, `completed`, `declined`), `votes_count`, `team_answer` and `team_replies`. `summary:` is 10 to 1000 characters (what the person wants to do and why), `title:` at most 120 (made from the summary when left out); `area:` is one of posts, media, inbox, analytics, automations, accounts, ads, team, other. Errors: `400 invalid_summary` / `invalid_title` / `invalid_platform` / `invalid_area` / `unknown_limit`, `409 not_requestable` (the entry is in `e.body["error"]["limit"]`), `429 too_many_requests` (10 an hour per person), and `400 invalid_id` / `404 not_found` on `get`.
826
+
687
827
  ## Error handling
688
828
 
689
829
  Non-2xx responses raise typed exceptions with `status`, `code`, `message`, and the parsed `body`:
@@ -714,7 +854,7 @@ The API allows **100 requests per minute** per API key. Every response includes
714
854
 
715
855
  ## Retries and timeouts
716
856
 
717
- The SDK automatically retries on 429, 5xx, and connection errors with exponential backoff (0.5s, 1s, 2s, with jitter), honoring the `Retry-After` header when present. Other 4xx errors are never retried. Defaults: 2 retries, 30 second timeout. Both are configurable:
857
+ The SDK automatically retries on 429, 5xx, and connection errors with exponential backoff (0.5s, 1s, 2s, with jitter), honoring the `Retry-After` header when present. Other 4xx errors are never retried. The ads calls that start or raise spend retry a 429 only (see [Ads](#ads)). Defaults: 2 retries, 30 second timeout. Both are configurable:
718
858
 
719
859
  ```ruby
720
860
  client = OmniSocials::Client.new(
@@ -38,6 +38,7 @@ module OmniSocials
38
38
  "GET" => Net::HTTP::Get,
39
39
  "POST" => Net::HTTP::Post,
40
40
  "PATCH" => Net::HTTP::Patch,
41
+ "PUT" => Net::HTTP::Put,
41
42
  "DELETE" => Net::HTTP::Delete
42
43
  }.freeze
43
44
 
@@ -61,7 +62,8 @@ module OmniSocials
61
62
  attr_reader :api_key, :base_url, :timeout, :max_retries,
62
63
  :posts, :media, :folders, :hashtag_sets, :approval_workflows,
63
64
  :accounts, :analytics, :audio, :locations, :pinterest,
64
- :automations, :inbox, :webhooks
65
+ :automations, :ads, :inbox, :webhooks, :tags,
66
+ :limits, :feature_requests
65
67
 
66
68
  # api_key - API key (omsk_live_*). Falls back to the
67
69
  # OMNISOCIALS_API_KEY environment variable. Raises
@@ -90,6 +92,7 @@ module OmniSocials
90
92
  @media = Resources::Media.new(self)
91
93
  @folders = Resources::Folders.new(self)
92
94
  @hashtag_sets = Resources::HashtagSets.new(self)
95
+ @tags = Resources::Tags.new(self)
93
96
  @approval_workflows = Resources::ApprovalWorkflows.new(self)
94
97
  @accounts = Resources::Accounts.new(self)
95
98
  @analytics = Resources::Analytics.new(self)
@@ -97,8 +100,11 @@ module OmniSocials
97
100
  @locations = Resources::Locations.new(self)
98
101
  @pinterest = Resources::Pinterest.new(self)
99
102
  @automations = Resources::Automations.new(self)
103
+ @ads = Resources::Ads.new(self)
100
104
  @inbox = Resources::Inbox.new(self)
101
105
  @webhooks = Resources::Webhooks.new(self)
106
+ @limits = Resources::Limits.new(self)
107
+ @feature_requests = Resources::FeatureRequests.new(self)
102
108
  end
103
109
 
104
110
  # GET /health - API health check (no scopes required).
@@ -112,7 +118,11 @@ module OmniSocials
112
118
  # non-JSON responses, or nil for 204. Raises an OmniSocials::APIError
113
119
  # subclass on non-2xx and OmniSocials::APIConnectionError when no
114
120
  # response was ever received.
115
- def request(method, path, query: nil, json: nil, multipart: nil)
121
+ #
122
+ # retry_on: :rate_limit retries only a 429. A call that can start ad
123
+ # spend uses it: after a 5xx, a timeout or a lost connection the first
124
+ # attempt may have gone through, so it is never sent again.
125
+ def request(method, path, query: nil, json: nil, multipart: nil, retry_on: nil)
116
126
  uri = build_uri(path, query)
117
127
  last_error = nil
118
128
 
@@ -121,13 +131,14 @@ module OmniSocials
121
131
  response = perform(method, uri, json: json, multipart: multipart)
122
132
  rescue *CONNECTION_ERRORS => e
123
133
  last_error = e
124
- break if attempt >= max_retries
134
+ # Not sent again when the call may have started ad spend.
135
+ break if retry_on == :rate_limit || attempt >= max_retries
125
136
 
126
137
  sleep(Internal.backoff_delay(attempt, nil))
127
138
  next
128
139
  end
129
140
 
130
- should_retry, retry_after = retry_info(response)
141
+ should_retry, retry_after = retry_info(response, retry_on)
131
142
  if should_retry && attempt < max_retries
132
143
  sleep(Internal.backoff_delay(attempt, retry_after))
133
144
  next
@@ -177,9 +188,10 @@ module OmniSocials
177
188
  http.start { |conn| conn.request(req) }
178
189
  end
179
190
 
180
- def retry_info(response)
191
+ def retry_info(response, retry_on)
181
192
  status = response.code.to_i
182
- if RETRY_STATUSES.include?(status) || status >= 500
193
+ server_error = RETRY_STATUSES.include?(status) || status >= 500
194
+ if status == 429 || (server_error && retry_on != :rate_limit)
183
195
  [true, parse_retry_after(response, Internal.parse_body(response.body))]
184
196
  else
185
197
  [false, nil]
@@ -1,5 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require "cgi"
3
4
  require "json"
4
5
  require "pathname"
5
6
 
@@ -34,6 +35,12 @@ module OmniSocials
34
35
  hash.reject { |_key, value| value.nil? || value.is_a?(NotGiven) }
35
36
  end
36
37
 
38
+ # URL-encode an id for use as one path segment. Spaces become %20 (a
39
+ # path segment treats "+" literally, unlike a query string).
40
+ def path_segment(value)
41
+ CGI.escape(value.to_s).gsub("+", "%20")
42
+ end
43
+
37
44
  # Join an array into a comma-separated string; pass strings through.
38
45
  def join_list(value)
39
46
  return nil if value.nil?
@@ -0,0 +1,356 @@
1
+ # frozen_string_literal: true
2
+
3
+ module OmniSocials
4
+ module Resources
5
+ # Ads resource: boosts, campaigns and "Create an ad" drafts on Meta,
6
+ # Pinterest, TikTok, LinkedIn, X and Google.
7
+ #
8
+ # Ads spend real money once a campaign starts. Boosts, campaigns and
9
+ # drafts are created as drafts (no spend); activate, activate_multi,
10
+ # drafts.launch, resume and a budget raise through update start or raise
11
+ # spend, and each needs the amount again as a confirmation. These calls
12
+ # are never retried after a 5xx, a timeout or a lost connection (only a
13
+ # 429), because the first attempt may have started the ad. Budgets are in
14
+ # major currency units (10 = 10 EUR) in the ad account's currency. Ad
15
+ # accounts are connected and picked in the OmniSocials dashboard. The
16
+ # scopes ads:read and ads:write are opt-in on the API key (the Ads
17
+ # switch).
18
+ class Ads
19
+ # "Create an ad" drafts (an OmniSocials::Resources::AdDrafts).
20
+ attr_reader :drafts
21
+
22
+ def initialize(client)
23
+ @client = client
24
+ @drafts = AdDrafts.new(client)
25
+ end
26
+
27
+ # GET /ads/accounts - the connected ad accounts, as { "data" => [...],
28
+ # "platforms_available" => [...] }. Accounts are connected and picked in
29
+ # the dashboard; only is_selected accounts can run campaigns. Requires
30
+ # ads:read (opt-in on the API key).
31
+ def list_accounts
32
+ @client.request("GET", "/ads/accounts")
33
+ end
34
+
35
+ # GET /ads/capabilities - what each network accepts for a new ad
36
+ # (goals, media, text limits, buttons, minimum daily budget),
37
+ # create_networks and network_states ("live", "preview" or
38
+ # "coming_soon"). Requires ads:read.
39
+ def capabilities
40
+ @client.request("GET", "/ads/capabilities")
41
+ end
42
+
43
+ # GET /ads/campaigns - list campaigns and boosts, optionally by status,
44
+ # platform or campaign_type ("campaign" or "boost"); limit is 1..100
45
+ # (default 25). Requires ads:read.
46
+ def list(status: nil, platform: nil, campaign_type: nil, limit: nil, offset: nil)
47
+ @client.request(
48
+ "GET", "/ads/campaigns",
49
+ query: {
50
+ "status" => status, "platform" => platform, "campaign_type" => campaign_type,
51
+ "limit" => limit, "offset" => offset
52
+ }
53
+ )
54
+ end
55
+
56
+ # GET /ads/campaigns/{id} - one campaign with its latest numbers.
57
+ # Requires ads:read.
58
+ def get(campaign_id)
59
+ @client.request("GET", "/ads/campaigns/#{Internal.path_segment(campaign_id)}")
60
+ end
61
+
62
+ # POST /ads/boost - boost a published post. Creates a DRAFT boost: no
63
+ # spend until activate. budget is { "type" => "daily", "amount" => 5,
64
+ # "currency" => "EUR" } in the ad account's currency. TikTok needs
65
+ # creative "spark_auth_code", Google needs "headlines", "descriptions"
66
+ # and "logo_url". Requires ads:write.
67
+ def boost(post_id:, ad_account_id:, budget:, objective: nil, targeting: nil,
68
+ schedule: nil, creative: nil, name: nil)
69
+ body = Internal.drop_nil(
70
+ {
71
+ "post_id" => post_id, "ad_account_id" => ad_account_id, "budget" => budget,
72
+ "objective" => objective, "targeting" => targeting, "schedule" => schedule,
73
+ "creative" => creative, "name" => name
74
+ }
75
+ )
76
+ @client.request("POST", "/ads/boost", json: body)
77
+ end
78
+
79
+ # POST /ads/boost-multi - one DRAFT boost per ad account (up to 10),
80
+ # each with the same budget, so the total is amount x accounts. Answers
81
+ # { "results" => [...] }; one failed account never stops the others.
82
+ # Requires ads:write.
83
+ def boost_multi(post_id:, ad_account_ids:, budget:, objective: nil, targeting: nil,
84
+ schedule: nil, creative: nil, name: nil)
85
+ body = Internal.drop_nil(
86
+ {
87
+ "post_id" => post_id, "ad_account_ids" => ad_account_ids.to_a, "budget" => budget,
88
+ "objective" => objective, "targeting" => targeting, "schedule" => schedule,
89
+ "creative" => creative, "name" => name
90
+ }
91
+ )
92
+ @client.request("POST", "/ads/boost-multi", json: body)
93
+ end
94
+
95
+ # POST /ads/campaigns - a DRAFT campaign without ads. It cannot start
96
+ # (campaign_has_no_ads): use ads.drafts.create for a new ad. Requires
97
+ # ads:write.
98
+ def create(ad_account_id:, name:, budget:, objective: nil, targeting: nil, schedule: nil)
99
+ body = Internal.drop_nil(
100
+ {
101
+ "ad_account_id" => ad_account_id,
102
+ "name" => name,
103
+ "budget" => budget,
104
+ "objective" => objective,
105
+ "targeting" => targeting,
106
+ "schedule" => schedule
107
+ }
108
+ )
109
+ @client.request("POST", "/ads/campaigns", json: body)
110
+ end
111
+
112
+ # PATCH /ads/campaigns/{id} - change the name, budget, targeting or
113
+ # schedule.
114
+ #
115
+ # A higher budget on a running campaign RAISES REAL AD SPEND: show the
116
+ # person the new amount and get their yes first, then pass it again as
117
+ # confirm_budget_amount. Not retried after a 5xx, a timeout or a lost
118
+ # connection: read the campaign with get to see what happened. Requires
119
+ # ads:write.
120
+ def update(campaign_id, name: nil, budget: nil, confirm_budget_amount: nil,
121
+ targeting: nil, schedule: nil)
122
+ body = Internal.drop_nil(
123
+ {
124
+ "name" => name,
125
+ "budget" => budget,
126
+ "confirm_budget_amount" => confirm_budget_amount,
127
+ "targeting" => targeting,
128
+ "schedule" => schedule
129
+ }
130
+ )
131
+ @client.request(
132
+ "PATCH", "/ads/campaigns/#{Internal.path_segment(campaign_id)}",
133
+ json: body, retry_on: :rate_limit
134
+ )
135
+ end
136
+
137
+ # POST /ads/campaigns/{id}/activate - START REAL AD SPEND.
138
+ #
139
+ # Show the person the budget (amount, currency, daily or lifetime) and
140
+ # get their yes first; confirm_budget_amount must equal the campaign's
141
+ # budget amount. A campaign of a draft group answers 409
142
+ # use_draft_launch: use ads.drafts.launch. Not retried after a 5xx, a
143
+ # timeout or a lost connection: read the campaign with get to see what
144
+ # happened. Requires ads:write.
145
+ def activate(campaign_id, confirm_budget_amount)
146
+ @client.request(
147
+ "POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/activate",
148
+ json: { "confirm_budget_amount" => confirm_budget_amount }, retry_on: :rate_limit
149
+ )
150
+ end
151
+
152
+ # POST /ads/campaigns/activate-multi - START REAL AD SPEND on up to 10
153
+ # campaigns.
154
+ #
155
+ # Every campaign's budget must equal confirm_budget_amount; show the
156
+ # person the total (amount x campaigns) and get their yes first.
157
+ # Answers { "results" => [...] }. Not retried after a 5xx, a timeout or
158
+ # a lost connection: read the campaigns with get to see what happened.
159
+ # Requires ads:write.
160
+ def activate_multi(campaign_ids, confirm_budget_amount)
161
+ @client.request(
162
+ "POST", "/ads/campaigns/activate-multi",
163
+ json: {
164
+ "campaign_ids" => campaign_ids.to_a,
165
+ "confirm_budget_amount" => confirm_budget_amount
166
+ },
167
+ retry_on: :rate_limit
168
+ )
169
+ end
170
+
171
+ # POST /ads/campaigns/{id}/pause - pause a campaign (also while in
172
+ # review). Requires ads:write.
173
+ def pause(campaign_id)
174
+ @client.request("POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/pause")
175
+ end
176
+
177
+ # POST /ads/campaigns/{id}/resume - resume a paused campaign: it STARTS
178
+ # REAL AD SPEND again. Show the person the budget and get their yes
179
+ # first. Not retried after a 5xx, a timeout or a lost connection: read
180
+ # the campaign with get to see what happened. Requires ads:write.
181
+ def resume(campaign_id)
182
+ @client.request(
183
+ "POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/resume",
184
+ retry_on: :rate_limit
185
+ )
186
+ end
187
+
188
+ # DELETE /ads/campaigns/{id} - delete a campaign on the network too. A
189
+ # campaign that spent is archived: its spend stays in the totals.
190
+ # Requires ads:write.
191
+ def delete(campaign_id)
192
+ @client.request("DELETE", "/ads/campaigns/#{Internal.path_segment(campaign_id)}")
193
+ end
194
+
195
+ # GET /ads/overview - accounts, campaigns per status and total spend.
196
+ # Requires ads:read.
197
+ def overview
198
+ @client.request("GET", "/ads/overview")
199
+ end
200
+
201
+ # GET /ads/suggestions - organic posts that do better than the
202
+ # workspace median: boost candidates. Read-only. Requires ads:read.
203
+ def suggestions
204
+ @client.request("GET", "/ads/suggestions")
205
+ end
206
+
207
+ # POST /ads/research/keywords - keyword ideas from seed keywords (up to
208
+ # 20), a url or both, through the connected Google Ads account. country
209
+ # defaults to "US", language to "en", limit is 1..500 (default 100);
210
+ # ad_account_id only when the workspace has more than one Google Ads
211
+ # account. Read-only and free. Requires ads:read.
212
+ def research_keywords(keywords: nil, url: nil, country: nil, language: nil, limit: nil,
213
+ ad_account_id: nil)
214
+ body = Internal.drop_nil(
215
+ {
216
+ "keywords" => keywords&.to_a,
217
+ "url" => url,
218
+ "country" => country,
219
+ "language" => language,
220
+ "limit" => limit,
221
+ "ad_account_id" => ad_account_id
222
+ }
223
+ )
224
+ @client.request("POST", "/ads/research/keywords", json: body)
225
+ end
226
+
227
+ # POST /ads/research/keywords/metrics - search numbers for an exact
228
+ # keyword list. Read-only. Requires ads:read.
229
+ def keyword_metrics(keywords:, country: nil, language: nil, ad_account_id: nil)
230
+ body = Internal.drop_nil(
231
+ {
232
+ "keywords" => keywords.to_a,
233
+ "country" => country,
234
+ "language" => language,
235
+ "ad_account_id" => ad_account_id
236
+ }
237
+ )
238
+ @client.request("POST", "/ads/research/keywords/metrics", json: body)
239
+ end
240
+ end
241
+
242
+ # "Create an ad" drafts: one campaign per network in platforms, each with
243
+ # the same ads. A draft never spends; launch starts it.
244
+ class AdDrafts
245
+ def initialize(client)
246
+ @client = client
247
+ end
248
+
249
+ # GET /ads/drafts/defaults - suggested countries (where the Instagram
250
+ # followers are), the currency and the workspace's ad account per
251
+ # network. Requires ads:read.
252
+ def defaults
253
+ @client.request("GET", "/ads/drafts/defaults")
254
+ end
255
+
256
+ # POST /ads/drafts - save a new ad as a draft group. It needs no ad
257
+ # account and spends nothing.
258
+ #
259
+ # objective is "traffic", "engagement", "awareness" or "video_views".
260
+ # platforms lists network keys ("meta", "pinterest", "tiktok",
261
+ # "linkedin", "x", "google") or { "platform" => ..., "budget_amount" =>
262
+ # ..., "ad_account_id" => ... } per network. budget is the daily amount
263
+ # per network, { "amount" => 10, "currency" => "EUR" }. schedule is
264
+ # { "duration_days" => 7 } (nil runs until it is stopped). targeting
265
+ # needs "countries"; "automatic_audience" => true lets the network find
266
+ # the audience. Each of ads has "media", "primary_text", "link" and
267
+ # optionally "headline", "description", "cta", "primary_text_b" (an A/B
268
+ # test) and, on Meta, "placement_media" => { "stories_reels" => {...} }
269
+ # (an upright 9:16 file for Stories and Reels).
270
+ #
271
+ # Read ads.capabilities first for what each network accepts. The answer
272
+ # carries review_url (the builder in the dashboard) and per network
273
+ # readiness. Requires ads:write.
274
+ def create(objective:, platforms:, budget:, targeting:, ads:, name: nil, schedule: nil)
275
+ body = draft_body(
276
+ objective: objective, platforms: platforms, budget: budget,
277
+ targeting: targeting, ads: ads, name: name, schedule: schedule
278
+ )
279
+ @client.request("POST", "/ads/drafts", json: body)
280
+ end
281
+
282
+ # GET /ads/drafts/{group_id} - one draft group. Requires ads:read.
283
+ def get(group_id)
284
+ @client.request("GET", "/ads/drafts/#{Internal.path_segment(group_id)}")
285
+ end
286
+
287
+ # PUT /ads/drafts/{group_id} - replace the draft with the full body
288
+ # (the same fields as create). Networks that already started are left
289
+ # alone (campaigns[].editable). Requires ads:write.
290
+ def update(group_id, objective:, platforms:, budget:, targeting:, ads:, name: nil,
291
+ schedule: nil)
292
+ body = draft_body(
293
+ objective: objective, platforms: platforms, budget: budget,
294
+ targeting: targeting, ads: ads, name: name, schedule: schedule
295
+ )
296
+ @client.request("PUT", "/ads/drafts/#{Internal.path_segment(group_id)}", json: body)
297
+ end
298
+
299
+ # DELETE /ads/drafts/{group_id} - delete a draft group that never
300
+ # started. Requires ads:write.
301
+ def delete(group_id)
302
+ @client.request("DELETE", "/ads/drafts/#{Internal.path_segment(group_id)}")
303
+ end
304
+
305
+ # POST /ads/drafts/{group_id}/account - set the ad account of one
306
+ # network in the draft (from ads.list_accounts, same network). Requires
307
+ # ads:write.
308
+ def attach_account(group_id, platform:, ad_account_id:)
309
+ @client.request(
310
+ "POST", "/ads/drafts/#{Internal.path_segment(group_id)}/account",
311
+ json: { "platform" => platform, "ad_account_id" => ad_account_id }
312
+ )
313
+ end
314
+
315
+ # POST /ads/drafts/{group_id}/launch - START REAL AD SPEND for every
316
+ # network of the draft that never started.
317
+ #
318
+ # Show the person the daily amount per network and get their yes first,
319
+ # then pass it as confirm_budget_amount (or per campaign id as
320
+ # confirm_budget_amounts). A wrong or missing amount answers 400
321
+ # budget_confirmation_required and writes nothing. The answer is
322
+ # { "data" => { "group" => ..., "results" => [...] } } with a result per
323
+ # network; one failed network never stops the others. Not retried after
324
+ # a 5xx, a timeout or a lost connection: read the draft with get to see
325
+ # what started. Requires ads:write.
326
+ def launch(group_id, confirm_budget_amount: nil, confirm_budget_amounts: nil)
327
+ body = Internal.drop_nil(
328
+ {
329
+ "confirm_budget_amount" => confirm_budget_amount,
330
+ "confirm_budget_amounts" => confirm_budget_amounts
331
+ }
332
+ )
333
+ @client.request(
334
+ "POST", "/ads/drafts/#{Internal.path_segment(group_id)}/launch",
335
+ json: body, retry_on: :rate_limit
336
+ )
337
+ end
338
+
339
+ private
340
+
341
+ def draft_body(objective:, platforms:, budget:, targeting:, ads:, name:, schedule:)
342
+ Internal.drop_nil(
343
+ {
344
+ "name" => name,
345
+ "objective" => objective,
346
+ "platforms" => platforms.to_a,
347
+ "budget" => budget,
348
+ "schedule" => schedule,
349
+ "targeting" => targeting,
350
+ "ads" => ads.to_a
351
+ }
352
+ )
353
+ end
354
+ end
355
+ end
356
+ end
@@ -15,7 +15,9 @@ module OmniSocials
15
15
 
16
16
  # GET /analytics/posts?ids=a,b,c - bulk metrics for up to 100 posts in
17
17
  # one request. `ids` is an Array of post ids (or an already-joined
18
- # comma-separated String).
18
+ # comma-separated String). Each entry also carries "tags" (the post's
19
+ # tags) and "trial_reel" ({ "strategy" => "MANUAL" | "SS_PERFORMANCE" }
20
+ # for an Instagram Trial Reel, else nil).
19
21
  def posts(ids)
20
22
  @client.request(
21
23
  "GET", "/analytics/posts",
@@ -24,10 +26,17 @@ module OmniSocials
24
26
  end
25
27
 
26
28
  # GET /analytics/overview - workspace-wide analytics overview.
27
- def overview(period: nil, start_date: nil, end_date: nil)
29
+ #
30
+ # tag (a tag id or name, or an Array of them: any of them) keeps the
31
+ # post numbers of the posts with that tag; account numbers stay those
32
+ # of the whole account. An unknown tag is a 404 tag_not_found.
33
+ def overview(period: nil, start_date: nil, end_date: nil, tag: nil)
28
34
  @client.request(
29
35
  "GET", "/analytics/overview",
30
- query: { "period" => period, "start_date" => start_date, "end_date" => end_date }
36
+ query: {
37
+ "period" => period, "start_date" => start_date, "end_date" => end_date,
38
+ "tag" => Tags.tag_query(tag)
39
+ }
31
40
  )
32
41
  end
33
42
 
@@ -49,6 +58,28 @@ module OmniSocials
49
58
  query: { "platform" => platform, "timezone" => timezone }
50
59
  )
51
60
  end
61
+
62
+ # GET /analytics/tags - how each tag did against your normal, for the
63
+ # published posts in a period (default the last 90 days).
64
+ #
65
+ # Returns { "data" => { "period", "platform", "min_posts", "tags",
66
+ # "untagged", "normals" } }. Each entry of "tags" is { "tag", "posts",
67
+ # "measured", "median_impressions", "engagement_rate" (percent),
68
+ # "vs_normal" (fraction: 0.38 = 38% above your normal), "best_channel",
69
+ # "enough_posts" }, comparable tags first, best first; "untagged" has
70
+ # the same numbers for the posts without a tag, "normals" the median
71
+ # impressions per channel. platform keeps one channel's numbers;
72
+ # min_posts (1 to 50, default 5) is the measured posts a tag needs
73
+ # before "enough_posts" is true.
74
+ def tags(start_date: nil, end_date: nil, platform: nil, min_posts: nil)
75
+ @client.request(
76
+ "GET", "/analytics/tags",
77
+ query: {
78
+ "start_date" => start_date, "end_date" => end_date,
79
+ "platform" => platform, "min_posts" => min_posts
80
+ }
81
+ )
82
+ end
52
83
  end
53
84
  end
54
85
  end
@@ -73,9 +73,22 @@ module OmniSocials
73
73
  # 15 per 15 minutes and 450 a day; an answer over a cap waits in a
74
74
  # queue ("queued") for up to an hour.
75
75
  #
76
+ # Follow first (Instagram only): actions "follow_gate" => { "enabled"
77
+ # => true, "first_message" => { "text", "button" }, "not_following" =>
78
+ # { "text", "button" } } sends the link (the "dm" text) only to people
79
+ # who follow the account. A comment gets the first message as the
80
+ # private reply, with one button; a tap makes OmniSocials ask
81
+ # Instagram whether the person follows. A follower gets the link,
82
+ # anyone else gets the not_following message with its button, and
83
+ # every later tap checks again. A DM or a story reply is checked at
84
+ # once. When Instagram gives no answer the link goes out anyway.
85
+ # Texts hold 640 characters, buttons 20; a text or button left out is
86
+ # the default. nil or false turns it off. The response carries the
87
+ # gate with its texts (nil on Facebook and X) and stats "followed".
88
+ #
76
89
  # Requires the automations:write scope (opt-in on the API key).
77
- # Errors: 400 validation_error, 400 post_not_instagram, 400
78
- # post_not_facebook, 400 post_required, 404 post_not_found, 404
90
+ # Errors: 400 validation_error, 400 follow_gate_instagram_only, 400
91
+ # post_not_instagram, 400 post_not_facebook, 400 post_required, 404 post_not_found, 404
79
92
  # instagram_media_not_found, 404 facebook_post_not_found, 409
80
93
  # instagram_not_connected, 409 instagram_needs_reauth, 409
81
94
  # facebook_not_connected, 409 facebook_needs_reauth, 409
@@ -99,8 +112,10 @@ module OmniSocials
99
112
  # kinds, the scope and the match; a new actions "dm" "text" keeps the
100
113
  # public reply; limits: { "stop_at" => ... } keeps max_sends.
101
114
  # "public_reply" => { "enabled" => false } or { "variations" => [] }
102
- # turns the public reply off; limits: { "max_sends" => nil } removes
103
- # that limit. status: "paused" pauses and "active" resumes; another
115
+ # turns the public reply off; "follow_gate" => { "enabled" => false }
116
+ # turns Follow first off and keeps its texts, new texts keep the
117
+ # switch, and "follow_gate" => nil turns it off; limits: {
118
+ # "max_sends" => nil } removes that limit. status: "paused" pauses and "active" resumes; another
104
119
  # post_id / instagram_media_id / facebook_post_id moves the automation
105
120
  # to that post. The platform cannot change: a platform other than the
106
121
  # automation's is a 400 platform_immutable. status: "active" on an X
@@ -128,9 +143,10 @@ module OmniSocials
128
143
  # GET /automations/{id}/events - the automation's activity: one event
129
144
  # per person it answered, skipped or failed on. outcome filters on
130
145
  # "sent", "skipped", "failed", "pending", "queued" (waits for a free
131
- # slot under the send cap, out within the hour) or "opted_out" (the
132
- # person replied STOP on X); limit is 1..100 (default 25), offset
133
- # skips. Requires the automations:read scope.
146
+ # slot under the send cap, out within the hour), "opted_out" (the
147
+ # person replied STOP on X) or "waiting" (Follow first: asked to
148
+ # follow, the link goes out after the follow); limit is 1..100
149
+ # (default 25), offset skips. Requires the automations:read scope.
134
150
  #
135
151
  # The response is not the plain list envelope: { "data" => [...],
136
152
  # "counts" => { "sent" => 12, "skipped" => 3 }, "pagination" => {...} },
@@ -138,10 +154,12 @@ module OmniSocials
138
154
  # events is left out). Each event carries kind ("comment", "dm",
139
155
  # "story_reply"), outcome, reason / reason_label (X adds the skip
140
156
  # reasons "dms_closed", "no_credits", "opted_out" and
141
- # "automation_off"), person (id,
157
+ # "automation_off"; Follow first adds "already_waiting"), person (id,
142
158
  # username; on Facebook the person's name, since Facebook has no
143
159
  # @handle), trigger_id, trigger_text, message (the DM sent),
144
- # public_reply, platform_message_id, created_at and sent_at.
160
+ # public_reply, platform_message_id, follow_gate (Follow first:
161
+ # { "state" => "waiting" | "done", "asked_at", "taps", "followed",
162
+ # "checked", "after_ask" }, else nil), created_at and sent_at.
145
163
  def list_events(automation_id, outcome: nil, limit: nil, offset: nil)
146
164
  @client.request(
147
165
  "GET", "/automations/#{automation_id}/events",
@@ -0,0 +1,61 @@
1
+ # frozen_string_literal: true
2
+
3
+ module OmniSocials
4
+ module Resources
5
+ # Feature requests resource: requests to the OmniSocials team, for the
6
+ # person who owns the key (their name and email are stored with it so
7
+ # the team can answer). The person sees them in OmniSocials (Settings,
8
+ # Request a feature) and gets an email when the status changes. No scope
9
+ # needed.
10
+ #
11
+ # A request is { "id", "title", "summary", "status" (open, in_progress,
12
+ # completed, declined), "team_answer", "team_replies" => [{ "message",
13
+ # "created_at" }], "votes_count", "limit_id", "platform", "area",
14
+ # "source", "created_at", "updated_at", "completed_at" }.
15
+ class FeatureRequests
16
+ def initialize(client)
17
+ @client = client
18
+ end
19
+
20
+ # POST /feature-requests - send a request. Send it only when the
21
+ # person asked for it.
22
+ #
23
+ # summary: (10 to 1000 characters) says what the person wants to do
24
+ # and why; title: (at most 120) is made from it when left out.
25
+ # limit_id: is the "id" of the limits.list entry the request is about.
26
+ # Returns { "outcome", "data" }: "outcome" is "created" (a new
27
+ # request), "voted" (a vote added to the organisation's open request
28
+ # for the same gap) or "already_requested" (this person already has an
29
+ # open request for it; "data" is that request).
30
+ #
31
+ # Errors: 400 invalid_summary / invalid_title / invalid_platform /
32
+ # invalid_area / unknown_limit; 409 not_requestable (a platform rule or
33
+ # a choice of OmniSocials: the entry is in error.body["error"]["limit"],
34
+ # nothing was stored); 429 too_many_requests (10 an hour per person).
35
+ def create(summary:, title: nil, platform: nil, area: nil, limit_id: nil)
36
+ body = Internal.drop_nil(
37
+ {
38
+ "summary" => summary,
39
+ "title" => title,
40
+ "platform" => platform,
41
+ "area" => area,
42
+ "limit_id" => limit_id
43
+ }
44
+ )
45
+ @client.request("POST", "/feature-requests", json: body)
46
+ end
47
+
48
+ # GET /feature-requests - the person's own requests, newest first, at
49
+ # most 50: { "data" => [FeatureRequest] }.
50
+ def list
51
+ @client.request("GET", "/feature-requests")
52
+ end
53
+
54
+ # GET /feature-requests/{id} - one request with its status and the
55
+ # team's replies. Errors: 400 invalid_id, 404 not_found.
56
+ def get(request_id)
57
+ @client.request("GET", "/feature-requests/#{request_id}")
58
+ end
59
+ end
60
+ end
61
+ end
@@ -193,8 +193,9 @@ module OmniSocials
193
193
  )
194
194
  end
195
195
 
196
- # DELETE /inbox/messages/{id} - delete a comment someone left on one of
197
- # the user's posts, on the platform and from the inbox. Facebook,
196
+ # DELETE /inbox/messages/{id} - delete a comment on one of the user's
197
+ # posts, on the platform and from the inbox: a comment someone left, or
198
+ # one of the user's own replies (direction "outgoing"). Facebook,
198
199
  # Instagram and TikTok comments only: YouTube's API does not let a
199
200
  # channel delete other people's comments, hide those instead (`hide`).
200
201
  # Replies under the deleted comment go with it (the platforms cascade
@@ -0,0 +1,36 @@
1
+ # frozen_string_literal: true
2
+
3
+ module OmniSocials
4
+ module Resources
5
+ # Limits resource: what OmniSocials cannot do, why, and what to do
6
+ # instead (platform rules, features not built yet, features that work in
7
+ # the OmniSocials app only).
8
+ #
9
+ # Read it before you tell a person that something is not possible, so
10
+ # you can give the reason ("says") and the way around it ("instead").
11
+ # When the person still wants a "requestable" entry, send it with
12
+ # feature_requests.create(summary: ..., limit_id: ...). No scope needed:
13
+ # every key may call it.
14
+ class Limits
15
+ def initialize(client)
16
+ @client = client
17
+ end
18
+
19
+ # GET /limits - the things OmniSocials cannot do.
20
+ #
21
+ # platform: keeps the entries for one platform (entries for every
22
+ # channel stay in); area: is one of posts, media, inbox, analytics,
23
+ # automations, accounts, ads, team, other. Returns
24
+ # { "data" => [Limit], "kinds" => { kind => label } }; a limit is
25
+ # { "id", "kind", "kind_label", "area", "platforms", "title", "says",
26
+ # "instead", "requestable" }. "kind" is platform, by_design, not_built,
27
+ # beta, dashboard_only or needs_setup; "requestable" is false for
28
+ # platform and by_design.
29
+ #
30
+ # Errors: 400 invalid_platform / invalid_area.
31
+ def list(platform: nil, area: nil)
32
+ @client.request("GET", "/limits", query: { "platform" => platform, "area" => area })
33
+ end
34
+ end
35
+ end
36
+ end
@@ -21,10 +21,23 @@ module OmniSocials
21
21
  # GET /posts - list posts (status: draft, in_approval, scheduled, posting,
22
22
  # posted, failed, warning; in_approval = waiting for a reviewer in an
23
23
  # approval workflow).
24
- def list(status: nil, limit: nil, offset: nil)
24
+ # start_date / end_date keep posts whose schedule_at falls in the
25
+ # period, both inclusive: "YYYY-MM-DD" (a UTC day), "YYYY-MM" (a month)
26
+ # or an ISO 8601 datetime. With a range the posts come in calendar order
27
+ # (earliest first).
28
+ # tag (a tag id or name, or an Array of them) keeps the posts with any
29
+ # of those tags; an unknown tag is a 404 tag_not_found. Every post
30
+ # carries "tags" (its tags) and "trial_reel" ({ "strategy" =>
31
+ # "MANUAL" | "SS_PERFORMANCE" } for an Instagram Trial Reel, else nil).
32
+ def list(status: nil, limit: nil, offset: nil, start_date: nil, end_date: nil,
33
+ tag: nil)
25
34
  @client.request(
26
35
  "GET", "/posts",
27
- query: { "status" => status, "limit" => limit, "offset" => offset }
36
+ query: {
37
+ "status" => status, "limit" => limit, "offset" => offset,
38
+ "start_date" => start_date, "end_date" => end_date,
39
+ "tag" => Tags.tag_query(tag)
40
+ }
28
41
  )
29
42
  end
30
43
 
@@ -159,7 +172,9 @@ module OmniSocials
159
172
  # "..." }, "public_reply" => { "enabled" => true, "variations" =>
160
173
  # [...] } }, "limits" => { "max_sends" => 500 }, "platforms" =>
161
174
  # ["instagram", "facebook"] } (see automations.create for the
162
- # fields). "platforms" makes one automation per listed channel; each
175
+ # fields, also the actions "follow_gate", Follow first, which applies
176
+ # to the Instagram automation only). "platforms" makes one automation
177
+ # per listed channel; each
163
178
  # must be a channel of the post. Without it: Instagram when the post
164
179
  # goes there, else Facebook. Needs the automations:write scope on the
165
180
  # key (403 insufficient_scope, checked before anything else); a bad
@@ -169,6 +184,11 @@ module OmniSocials
169
184
  # nil, plus "platforms" and "automations", one { "id", "platform",
170
185
  # "status" } per channel); each starts listening once the post is
171
186
  # live on its channel.
187
+ #
188
+ # tags labels the post with the workspace's own tags (ids or names, at
189
+ # most 20; a name that does not exist yet becomes a new tag) to filter
190
+ # and compare posts in Analytics. Tags never go to a platform. Errors:
191
+ # 404 tag_not_found (an unknown id), 400 invalid_tags / too_many_tags.
172
192
  def create(content:, channels: nil, scheduled_at: nil, media_ids: nil,
173
193
  media_urls: nil, type: nil, source: nil, link_url: nil,
174
194
  link_title: nil, link_description: nil, link_thumbnail_url: nil,
@@ -180,7 +200,7 @@ module OmniSocials
180
200
  mastodon: nil, threads: nil, google_business: nil,
181
201
  telegram: nil, discord: nil, linkedin_poll: nil,
182
202
  approval_workflow_id: nil, draft: nil, media_fit: nil,
183
- comment_dm_automation: nil)
203
+ comment_dm_automation: nil, tags: nil)
184
204
  body = create_body(
185
205
  content: content, channels: channels, scheduled_at: scheduled_at,
186
206
  media_ids: media_ids, media_urls: media_urls, type: type,
@@ -196,7 +216,8 @@ module OmniSocials
196
216
  google_business: google_business, telegram: telegram,
197
217
  discord: discord, linkedin_poll: linkedin_poll,
198
218
  approval_workflow_id: approval_workflow_id, draft: draft,
199
- media_fit: media_fit, comment_dm_automation: comment_dm_automation
219
+ media_fit: media_fit, comment_dm_automation: comment_dm_automation,
220
+ tags: tags
200
221
  )
201
222
  @client.request("POST", "/posts/create", json: body)
202
223
  end
@@ -204,8 +225,8 @@ module OmniSocials
204
225
  # POST /posts/create-and-publish - create and publish immediately.
205
226
  # See #create for the "warnings" array (X link posts, and the
206
227
  # "image_fit" entries steered by media_fit), the 402
207
- # "x_credits_insufficient" credit gate on X link posts and
208
- # comment_dm_automation.
228
+ # "x_credits_insufficient" credit gate on X link posts,
229
+ # comment_dm_automation and tags.
209
230
  def create_and_publish(content:, channels: nil, media_ids: nil,
210
231
  media_urls: nil, type: nil, source: nil,
211
232
  link_url: nil, link_title: nil, link_description: nil,
@@ -219,7 +240,7 @@ module OmniSocials
219
240
  threads: nil, google_business: nil,
220
241
  telegram: nil, discord: nil, linkedin_poll: nil,
221
242
  media_fit: nil,
222
- comment_dm_automation: nil)
243
+ comment_dm_automation: nil, tags: nil)
223
244
  body = create_body(
224
245
  content: content, channels: channels, scheduled_at: nil,
225
246
  media_ids: media_ids, media_urls: media_urls, type: type,
@@ -234,7 +255,8 @@ module OmniSocials
234
255
  x: x, bluesky: bluesky, mastodon: mastodon, threads: threads,
235
256
  google_business: google_business, telegram: telegram,
236
257
  discord: discord, linkedin_poll: linkedin_poll,
237
- media_fit: media_fit, comment_dm_automation: comment_dm_automation
258
+ media_fit: media_fit, comment_dm_automation: comment_dm_automation,
259
+ tags: tags
238
260
  )
239
261
  @client.request("POST", "/posts/create-and-publish", json: body)
240
262
  end
@@ -275,6 +297,11 @@ module OmniSocials
275
297
  # discord merges into the stored Discord options: a key set to nil
276
298
  # removes that option (e.g. discord: { "poll" => nil }), an explicit
277
299
  # discord: nil removes every option, and leaving it out keeps them.
300
+ #
301
+ # tags (ids or names, a new name becomes a tag) replaces the post's
302
+ # tags; tags: nil or tags: [] removes them all, and leaving it out
303
+ # keeps them. An update with only tags works on every post, published
304
+ # and failed ones included.
278
305
  def update(post_id, content: nil, scheduled_at: nil, channels: nil,
279
306
  media_ids: nil, media_urls: nil, type: nil, location_id: nil,
280
307
  collaborators: nil, user_tags: nil, pinterest: nil,
@@ -283,7 +310,8 @@ module OmniSocials
283
310
  mastodon: nil, threads: nil, google_business: nil,
284
311
  telegram: nil, discord: OmniSocials::NOT_GIVEN,
285
312
  linkedin_poll: nil, draft: nil, media_fit: nil,
286
- comment_dm_automation: OmniSocials::NOT_GIVEN)
313
+ comment_dm_automation: OmniSocials::NOT_GIVEN,
314
+ tags: OmniSocials::NOT_GIVEN)
287
315
  body = Internal.drop_nil(
288
316
  {
289
317
  "content" => content,
@@ -318,6 +346,8 @@ module OmniSocials
318
346
  body["comment_dm_automation"] = comment_dm_automation unless comment_dm_automation.is_a?(NotGiven)
319
347
  # Same for discord: an explicit nil removes every Discord option.
320
348
  body["discord"] = discord unless discord.is_a?(NotGiven)
349
+ # And for tags: an explicit nil (or []) removes every tag of the post.
350
+ body["tags"] = tags unless tags.is_a?(NotGiven)
321
351
  @client.request("PATCH", "/posts/#{post_id}", json: body)
322
352
  end
323
353
 
@@ -395,7 +425,7 @@ module OmniSocials
395
425
  threads:, google_business:, linkedin_poll:,
396
426
  telegram: nil, discord: nil, approval_workflow_id: nil,
397
427
  draft: nil,
398
- media_fit: nil, comment_dm_automation: nil)
428
+ media_fit: nil, comment_dm_automation: nil, tags: nil)
399
429
  Internal.drop_nil(
400
430
  {
401
431
  "content" => content,
@@ -434,7 +464,8 @@ module OmniSocials
434
464
  "approval_workflow_id" => approval_workflow_id,
435
465
  "draft" => draft,
436
466
  "media_fit" => media_fit,
437
- "comment_dm_automation" => comment_dm_automation
467
+ "comment_dm_automation" => comment_dm_automation,
468
+ "tags" => tags
438
469
  }
439
470
  )
440
471
  end
@@ -0,0 +1,86 @@
1
+ # frozen_string_literal: true
2
+
3
+ module OmniSocials
4
+ module Resources
5
+ # Tags resource: the workspace's own labels for its posts (a hook style,
6
+ # a format), to filter and compare posts in Analytics. Tags never go to a
7
+ # platform.
8
+ #
9
+ # Set them on a post with tags: on posts.create / create_and_publish /
10
+ # update, in bulk with #apply, filter with tag: on posts.list and
11
+ # analytics.overview, and compare them with analytics.tags. A tag
12
+ # reference is a tag id (Integer or String) or a tag name
13
+ # (case-insensitive); in add / set (and tags: on posts) a name that does
14
+ # not exist yet becomes a new tag.
15
+ class Tags
16
+ # Serialize the tag filter: one id or name, or an Array joined with ",".
17
+ def self.tag_query(tag)
18
+ return nil if tag.nil?
19
+ return tag.map(&:to_s).join(",") if tag.is_a?(Array)
20
+
21
+ tag.to_s
22
+ end
23
+
24
+ def initialize(client)
25
+ @client = client
26
+ end
27
+
28
+ # GET /tags - every tag of the workspace, by name. Each tag is
29
+ # { "id", "name", "color", "created_at" }. Scope posts:read.
30
+ def list
31
+ @client.request("GET", "/tags")
32
+ end
33
+
34
+ # POST /tags - create a tag. `name` is at most 40 characters and unique
35
+ # in the workspace (case-insensitive); `color` is one of blue, green,
36
+ # orange, red, purple, pink, teal, yellow, brown, gray (omit it to get
37
+ # the next colour). At most 200 tags per workspace.
38
+ #
39
+ # Errors: 409 tag_exists (the existing tag is in
40
+ # error.body["error"]["tag"]), 409 tag_limit_reached,
41
+ # 400 invalid_tag_name / invalid_tag_color.
42
+ def create(name:, color: nil)
43
+ @client.request(
44
+ "POST", "/tags",
45
+ json: Internal.drop_nil({ "name" => name, "color" => color })
46
+ )
47
+ end
48
+
49
+ # PATCH /tags/{id} - rename or recolour a tag. Only the keys you pass
50
+ # are sent; posts keep the tag. Errors: 404 tag_not_found,
51
+ # 409 tag_exists.
52
+ def update(tag_id, name: nil, color: nil)
53
+ body = Internal.drop_nil({ "name" => name, "color" => color })
54
+ @client.request("PATCH", "/tags/#{tag_id}", json: body)
55
+ end
56
+
57
+ # DELETE /tags/{id} - delete a tag and take it off every post (the
58
+ # posts stay). Returns { "data" => { "tag", "posts_untagged" } }.
59
+ def delete(tag_id)
60
+ @client.request("DELETE", "/tags/#{tag_id}")
61
+ end
62
+
63
+ # POST /tags/apply - add, remove or replace the tags of up to 500 posts
64
+ # at once, published ones included.
65
+ #
66
+ # add, remove and set take tag ids or names; a new name in add or set
67
+ # becomes a tag. set replaces a post's tags (set: [] removes them all),
68
+ # add and remove change only the tags you name. Returns
69
+ # { "data" => { "updated", "posts" => [{ "id", "tags" }], "not_found" } };
70
+ # not_found lists the post ids that are not posts of this workspace.
71
+ # Errors: 400 invalid_post_ids / too_many_posts / too_many_tags /
72
+ # invalid_tags, 404 tag_not_found.
73
+ def apply(post_ids:, add: nil, remove: nil, set: nil)
74
+ body = Internal.drop_nil(
75
+ {
76
+ "post_ids" => Array(post_ids).map(&:to_s),
77
+ "add" => add,
78
+ "remove" => remove,
79
+ "set" => set
80
+ }
81
+ )
82
+ @client.request("POST", "/tags/apply", json: body)
83
+ end
84
+ end
85
+ end
86
+ end
@@ -3,7 +3,8 @@
3
3
  module OmniSocials
4
4
  module Resources
5
5
  # Webhooks resource: manage event subscriptions (post.scheduled,
6
- # post.published, post.failed, post.approved, post.rejected).
6
+ # post.published, post.failed, post.approved, post.rejected, and
7
+ # ad.status_changed for ad campaigns).
7
8
  #
8
9
  # For verifying incoming deliveries, see OmniSocials::Webhooks.verify.
9
10
  class Webhooks
@@ -25,8 +26,11 @@ module OmniSocials
25
26
  #
26
27
  # `url` must be HTTPS. `events` is a non-empty subset of
27
28
  # post.scheduled, post.published, post.failed, post.approved,
28
- # post.rejected. The signing `secret` is only returned once, in this
29
- # response - store it.
29
+ # post.rejected and ad.status_changed. The `data` of an
30
+ # ad.status_changed delivery is the campaign, not a post: campaign_id,
31
+ # workspace_id, name, platform, campaign_type, status, previous_status,
32
+ # external_campaign_id and budget. The signing `secret` is only
33
+ # returned once, in this response - store it.
30
34
  def create(url:, events:)
31
35
  @client.request(
32
36
  "POST", "/webhooks",
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module OmniSocials
4
- VERSION = "0.13.0"
4
+ VERSION = "0.15.0"
5
5
  end
data/lib/omnisocials.rb CHANGED
@@ -20,6 +20,7 @@ require_relative "omnisocials/resources/posts"
20
20
  require_relative "omnisocials/resources/media"
21
21
  require_relative "omnisocials/resources/folders"
22
22
  require_relative "omnisocials/resources/hashtag_sets"
23
+ require_relative "omnisocials/resources/tags"
23
24
  require_relative "omnisocials/resources/approval_workflows"
24
25
  require_relative "omnisocials/resources/accounts"
25
26
  require_relative "omnisocials/resources/analytics"
@@ -27,8 +28,11 @@ require_relative "omnisocials/resources/audio"
27
28
  require_relative "omnisocials/resources/locations"
28
29
  require_relative "omnisocials/resources/pinterest"
29
30
  require_relative "omnisocials/resources/automations"
31
+ require_relative "omnisocials/resources/ads"
30
32
  require_relative "omnisocials/resources/inbox"
31
33
  require_relative "omnisocials/resources/webhooks"
34
+ require_relative "omnisocials/resources/limits"
35
+ require_relative "omnisocials/resources/feature_requests"
32
36
  require_relative "omnisocials/client"
33
37
 
34
38
  module OmniSocials
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: omnisocials
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.13.0
4
+ version: 0.15.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - OmniSocials
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-10-27 00:00:00.000000000 Z
11
+ date: 2026-11-05 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description: Schedule and publish social media posts, upload media, and read analytics
14
14
  across Instagram, Facebook, LinkedIn, YouTube, TikTok, X, Pinterest, Bluesky, Threads,
@@ -26,17 +26,21 @@ files:
26
26
  - lib/omnisocials/errors.rb
27
27
  - lib/omnisocials/internal.rb
28
28
  - lib/omnisocials/resources/accounts.rb
29
+ - lib/omnisocials/resources/ads.rb
29
30
  - lib/omnisocials/resources/analytics.rb
30
31
  - lib/omnisocials/resources/approval_workflows.rb
31
32
  - lib/omnisocials/resources/audio.rb
32
33
  - lib/omnisocials/resources/automations.rb
34
+ - lib/omnisocials/resources/feature_requests.rb
33
35
  - lib/omnisocials/resources/folders.rb
34
36
  - lib/omnisocials/resources/hashtag_sets.rb
35
37
  - lib/omnisocials/resources/inbox.rb
38
+ - lib/omnisocials/resources/limits.rb
36
39
  - lib/omnisocials/resources/locations.rb
37
40
  - lib/omnisocials/resources/media.rb
38
41
  - lib/omnisocials/resources/pinterest.rb
39
42
  - lib/omnisocials/resources/posts.rb
43
+ - lib/omnisocials/resources/tags.rb
40
44
  - lib/omnisocials/resources/webhooks.rb
41
45
  - lib/omnisocials/version.rb
42
46
  - lib/omnisocials/webhooks.rb