omnisocials 0.16.0 → 0.18.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: 7ea0275865830c8eb34ba9ae4f21fdf9ee1eef376185a7fcdaf379170d185668
4
- data.tar.gz: 4b136937c0214a7f703ad46e00cb719a61ee89a071ec58d6df640cb6aa7f88c8
3
+ metadata.gz: 396d389f359f705ffd24283768276b53efdc6f1f8f4a9d4448b38788b3f23d1d
4
+ data.tar.gz: 45c406d73dd22a7af20c8ec5d02e7f330da72ef9dbe482f9ca5717644439fb02
5
5
  SHA512:
6
- metadata.gz: 5f2d22fe54e670da7eb3c4451beae5472ac00e7c030ba9f280b2eb379f2b05c48f5e9e0d33420a9645f669d4811953796b66acc46bb8b4a2e8c2aa55d84878ab
7
- data.tar.gz: fed3adc29d81f96febcd4e2e70974ef1a6a6a76e361f22cf3230daa36c4710fdbbe95236edfcc3fcb5610285d499c7a4308f6e4febc0d876a3c3b01502729396
6
+ metadata.gz: 28ede0cfff7007e3ad31e395f3547a2c3f04a31592f4fb4308e7be388bd5466113a9b18260897817c38bfc11f6dc16180cdaeefa57c41c74c0d304f10f1c4897
7
+ data.tar.gz: 07be6b2cf99c29d8b2b9f6654615774ba28a31bc3b0e6121b962f6ca93e70aa8133c3d5cc3d6eaf77d28d73190bb422119ff5b679e052cf23fec13d54081dac2
data/README.md CHANGED
@@ -278,7 +278,7 @@ res = client.posts.create(
278
278
  end
279
279
  ```
280
280
 
281
- From `enforce_from` (2026-08-14) the balance is checked at publish time, but credits are only deducted after the post successfully publishes (a failed publish is never charged). If the balance can't cover it, only the X target fails (other platforms publish normally); top up in the dashboard under Settings -> Organisation -> Billing -> Credits, then call `posts.retry`. Posts without links, analytics, and media on X stay free. There is no API endpoint for credits — they are managed in the dashboard.
281
+ From `enforce_from` (2026-08-14) the balance is checked at publish time, but credits are only deducted after the post successfully publishes (a failed publish is never charged). If the balance can't cover it, only the X target fails (other platforms publish normally); top up in the dashboard under Settings -> Organisation -> Billing -> Credits, then call `posts.retry`. Posts without links and media on X stay free. X statistics use credits too, at X's price (see [X statistics use credits](#x-statistics-use-credits)). `client.credits.get` reads the balance; top-ups are made in the dashboard.
282
282
 
283
283
  Separately, from 2026-08-14 `posts.create` / `posts.update` / `posts.publish` on X can refuse the request itself, up front, with a `402` and error code `x_credits_insufficient` (`error.details` carries `credits_required`, `credits_balance`, and `credits_reserved`) when reserving this post's cost would push the company's total reserved credits past its balance:
284
284
 
@@ -507,6 +507,8 @@ account = client.accounts.get("instagram")
507
507
 
508
508
  `status` is `active` or `needs_reconnect` (the token was revoked or expired; Bluesky also when its sign-in could not be renewed). Posts to a `needs_reconnect` account fail until it is reconnected in the OmniSocials app. OmniSocials Connect customer workspaces can also show `pick_pending` (Facebook, Connect customers only: no Page chosen yet).
509
509
 
510
+ An X account also carries `x_statistics` (`posts`, `followers`, `post_schedule`, `source`, `billing`, `state`, `paused_reason`): how often OmniSocials reads its X statistics and who pays. `client.accounts.update(account_id, x_statistics: {...})` changes it; see [X statistics use credits](#x-statistics-use-credits).
511
+
510
512
  ## Analytics
511
513
 
512
514
  ```ruby
@@ -532,6 +534,35 @@ best = client.analytics.best_times(platform: "instagram", timezone: "Europe/Amst
532
534
  best["recommendations"].each { |slot| puts "#{slot["day"]} #{slot["time"]} #{slot["score"]}" }
533
535
  ```
534
536
 
537
+ ### X statistics use credits
538
+
539
+ X bills every statistics read, and OmniSocials passes X's price on as credits: half a credit per post check (plus half a credit when the tweet has a video or GIF; each part of a thread counts) and 1 credit per follower count. Every X account carries `x_statistics`:
540
+
541
+ - `posts`: how often each post is checked. `full` (5 checks: about 5 hours, day 1, 3 and 7, and day 30 for posts with 100+ views), `light` (2 checks: about 5 hours and day 7) or `off`.
542
+ - `followers`: how often the follower count is read. `daily`, `weekly` or `off`.
543
+ - `source` (`account` or `default`), `billing` (`credits`), `state` (`active`, `paused`, `off`) and `paused_reason` (`insufficient_credits` or null).
544
+
545
+ When the balance reaches 0 the reads pause (`state` `paused`) and start again by themselves after a top-up; the webhook events `x_statistics.paused` and `x_statistics.resumed` say so. `x_statistics.charging` in the answer of `client.credits.get` says whether reads are charged yet and from when.
546
+
547
+ ```ruby
548
+ # How often an X account is checked (opt-in scope accounts:write, billing rights)
549
+ account = client.accounts.update(
550
+ "1234_x",
551
+ x_statistics: { posts: "light", followers: "daily" } # one key or both
552
+ )
553
+ puts account["data"]["x_statistics"]["state"]
554
+
555
+ # "Update now": read one post's X numbers now (scope analytics:read)
556
+ fresh = client.analytics.refresh_post(9123)
557
+ puts fresh["data"]["credits_used"]
558
+
559
+ # The balance and what X statistics cost (opt-in scope credits:read, billing rights)
560
+ credits = client.credits.get["data"]
561
+ puts credits["balance"], credits["x_statistics"]["total_credits_month"]
562
+ ```
563
+
564
+ `analytics.refresh_post` costs nothing when the post was already read that day (UTC) and works at most 5 times a post and 100 times an organisation a day. Errors: `402 insufficient_credits`, `409 refresh_not_available` (no published X tweet), `429 refresh_limit`, `502 refresh_failed` (nothing charged). Because it can cost credits, the SDK retries it only after a 429, never after a 5xx or a timeout. `accounts.update` needs the opt-in scope `accounts:write` and billing rights (manage_billing) for the key's creator, sends only the keys you give, and answers `400 validation_error`, `invalid_value` or `not_supported` (not an X account) and `403 insufficient_permission` (no billing rights for the key's creator). `credits.get` needs the opt-in scope `credits:read` and billing rights.
565
+
535
566
  ## Locations (Instagram and Threads place tagging)
536
567
 
537
568
  ```ruby
@@ -740,7 +771,7 @@ interests = client.ads.targeting.search(ad_account_id: meta["id"], type: "intere
740
771
 
741
772
  ## Webhooks
742
773
 
743
- 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`. The other ads events are `ad.created`, `ad.updated`, `ad.review`, `ad.delivery_issue`, `campaign.created`, `campaign.updated`, `campaign.budget`, `lead.received`, `ads.sync_failed`, `ads.sync_recovered`, `ads.initial_sync_completed` and `ad_rule.triggered`. Subscribing to `ad.status_changed` or any other Ads event (`ad.*`, `campaign.*`, `lead.*`, `ads.*`, `ad_rule.*`) needs the `ads:read` scope on the key and `access_ads` for its person (`403 insufficient_scope` / `insufficient_permission`).
774
+ 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`. The other ads events are `ad.created`, `ad.updated`, `ad.review`, `ad.delivery_issue`, `campaign.created`, `campaign.updated`, `campaign.budget`, `lead.received`, `ads.sync_failed`, `ads.sync_recovered`, `ads.initial_sync_completed` and `ad_rule.triggered`. Subscribing to `ad.status_changed` or any other Ads event (`ad.*`, `campaign.*`, `lead.*`, `ads.*`, `ad_rule.*`) needs the `ads:read` scope on the key and `access_ads` for its person (`403 insufficient_scope` / `insufficient_permission`). `x_statistics.paused` and `x_statistics.resumed` fire when the organisation's X statistics stop at 0 credits or start again after a top-up, one delivery per workspace with X; `data` is `{ workspace_id, account_id, reason }` (`reason` is `insufficient_credits` or `credits_added`).
744
775
 
745
776
  ```ruby
746
777
  webhook = client.webhooks.create(
@@ -61,7 +61,7 @@ module OmniSocials
61
61
 
62
62
  attr_reader :api_key, :base_url, :timeout, :max_retries,
63
63
  :posts, :media, :folders, :hashtag_sets, :approval_workflows,
64
- :accounts, :analytics, :audio, :locations, :pinterest,
64
+ :accounts, :analytics, :credits, :audio, :locations, :pinterest,
65
65
  :automations, :ads, :inbox, :webhooks, :tags,
66
66
  :limits, :feature_requests
67
67
 
@@ -96,6 +96,7 @@ module OmniSocials
96
96
  @approval_workflows = Resources::ApprovalWorkflows.new(self)
97
97
  @accounts = Resources::Accounts.new(self)
98
98
  @analytics = Resources::Analytics.new(self)
99
+ @credits = Resources::Credits.new(self)
99
100
  @audio = Resources::Audio.new(self)
100
101
  @locations = Resources::Locations.new(self)
101
102
  @pinterest = Resources::Pinterest.new(self)
@@ -154,7 +155,9 @@ module OmniSocials
154
155
  private
155
156
 
156
157
  def build_uri(path, query)
157
- uri = URI.parse("#{base_url}#{path}")
158
+ # Every id in path was encoded with Internal.path_segment; this refuses
159
+ # an id of "", "." or ".." before the request is sent.
160
+ uri = URI.parse("#{base_url}#{Internal.check_path(path)}")
158
161
  pairs = Internal.serialize_query(query)
159
162
  uri.query = URI.encode_www_form(pairs) if pairs
160
163
  uri
@@ -35,12 +35,31 @@ module OmniSocials
35
35
  hash.reject { |_key, value| value.nil? || value.is_a?(NotGiven) }
36
36
  end
37
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).
38
+ # URL-encode a caller-supplied id as exactly one path segment. "/", "?",
39
+ # "#" and "%" are encoded too, so an id cannot add a segment, start a
40
+ # query or a fragment, or carry an escape of its own (an id such as
41
+ # "../webhooks/wh_1/rotate-secret#" would otherwise move the call to
42
+ # another endpoint of the same API key). Spaces become %20 (a path
43
+ # segment treats "+" literally, unlike a query string). Every id that
44
+ # goes into a request path goes through this method.
40
45
  def path_segment(value)
41
46
  CGI.escape(value.to_s).gsub("+", "%20")
42
47
  end
43
48
 
49
+ # Refuse a request path with an empty, "." or ".." segment.
50
+ # path_segment leaves "." and ".." as they are, and URL normalization
51
+ # drops such a segment or climbs one level, so an id of ".." would reach
52
+ # another endpoint; an empty id would reach the list route. Raises
53
+ # ArgumentError before anything is sent.
54
+ def check_path(path)
55
+ segments = path.to_s.split("?", 2).first.to_s.split("/", -1).drop(1)
56
+ if segments.any? { |segment| segment.empty? || segment == "." || segment == ".." }
57
+ raise ArgumentError, "Invalid request path #{path.inspect}: an id cannot be empty, \".\" or \"..\"."
58
+ end
59
+
60
+ path
61
+ end
62
+
44
63
  # Join an array into a comma-separated string; pass strings through.
45
64
  def join_list(value)
46
65
  return nil if value.nil?
@@ -17,8 +17,38 @@ module OmniSocials
17
17
  end
18
18
 
19
19
  # GET /accounts/{id} - fetch a single connected account.
20
+ #
21
+ # An X account also carries "x_statistics": posts, followers,
22
+ # post_schedule, source, billing, state and paused_reason (nil when it
23
+ # could not be read).
20
24
  def get(account_id)
21
- @client.request("GET", "/accounts/#{account_id}")
25
+ @client.request("GET", "/accounts/#{Internal.path_segment(account_id)}")
26
+ end
27
+
28
+ # PATCH /accounts/{id} - change how often the X statistics of an X
29
+ # account are read.
30
+ #
31
+ # `x_statistics` is a Hash with one key or more of posts, followers and
32
+ # post_schedule; only the keys you give are sent. posts is "full" (5
33
+ # checks), "light" (2 checks) or "off"; followers is "daily", "weekly"
34
+ # or "off". X bills every read and OmniSocials passes X's price on as
35
+ # credits (half a credit per post check, plus half for a video or GIF,
36
+ # 1 credit per follower count). Needs the opt-in scope accounts:write
37
+ # and billing rights (manage_billing) for the key's creator.
38
+ # OmniSocials Connect keys (the partner's own X app pays) also take
39
+ # posts: "custom" with post_schedule ({ at: ["1h", "1d"],
40
+ # then_every: "7d", until: "90d" }), followers "hourly" / "6h", and
41
+ # x_statistics: nil, which is sent as null: follow the customer's
42
+ # setting again.
43
+ #
44
+ # Returns { "data" => account } with the new "x_statistics". Errors:
45
+ # 400 validation_error / schedule_invalid / not_supported (not an X
46
+ # account), 403 forbidden, 404 not_found.
47
+ def update(account_id, x_statistics:)
48
+ @client.request(
49
+ "PATCH", "/accounts/#{Internal.path_segment(account_id)}",
50
+ json: { "x_statistics" => x_statistics.nil? ? nil : x_statistics.to_h }
51
+ )
22
52
  end
23
53
  end
24
54
  end
@@ -10,7 +10,28 @@ module OmniSocials
10
10
 
11
11
  # GET /analytics/posts/{id} - latest per-platform metrics for one post.
12
12
  def post(post_id)
13
- @client.request("GET", "/analytics/posts/#{post_id}")
13
+ @client.request("GET", "/analytics/posts/#{Internal.path_segment(post_id)}")
14
+ end
15
+
16
+ # POST /analytics/posts/{id}/refresh - "Update now": read the X numbers
17
+ # of one published post now, outside its check schedule.
18
+ #
19
+ # X bills every read, so it costs half a credit per tweet (each part
20
+ # of a thread counts, plus half a credit for a video or GIF), and
21
+ # nothing when the post was already read today (UTC). OmniSocials
22
+ # Connect accounts pay on the partner's own X app. At most 5 reads of
23
+ # a post a UTC day. Needs analytics:read. Returns { "data" =>
24
+ # { "post_id", "tweets" => [{ "id", "metrics", "read_at" }],
25
+ # "credits_used", "read_at" } }. Because it can cost credits it is
26
+ # retried only after a 429, never after a 5xx, a timeout or a lost
27
+ # connection. Errors: 402 insufficient_credits, 404 not_found, 409
28
+ # refresh_not_available (no published X tweet), 429 refresh_limit,
29
+ # 502 refresh_failed (nothing charged).
30
+ def refresh_post(post_id)
31
+ @client.request(
32
+ "POST", "/analytics/posts/#{Internal.path_segment(post_id)}/refresh",
33
+ retry_on: :rate_limit
34
+ )
14
35
  end
15
36
 
16
37
  # GET /analytics/posts?ids=a,b,c - bulk metrics for up to 100 posts in
@@ -35,7 +35,7 @@ module OmniSocials
35
35
  # GET /automations/{id} - fetch a single automation. Requires the
36
36
  # automations:read scope (opt-in on the API key).
37
37
  def get(automation_id)
38
- @client.request("GET", "/automations/#{automation_id}")
38
+ @client.request("GET", "/automations/#{Internal.path_segment(automation_id)}")
39
39
  end
40
40
 
41
41
  # POST /automations - create a comment-to-DM automation.
@@ -131,13 +131,13 @@ module OmniSocials
131
131
  trigger: trigger, actions: actions, limits: limits, status: status,
132
132
  platform: platform, facebook_post_id: facebook_post_id
133
133
  )
134
- @client.request("PATCH", "/automations/#{automation_id}", json: body)
134
+ @client.request("PATCH", "/automations/#{Internal.path_segment(automation_id)}", json: body)
135
135
  end
136
136
 
137
137
  # DELETE /automations/{id} - delete an automation. Returns nil (204).
138
138
  # Requires the automations:write scope.
139
139
  def delete(automation_id)
140
- @client.request("DELETE", "/automations/#{automation_id}")
140
+ @client.request("DELETE", "/automations/#{Internal.path_segment(automation_id)}")
141
141
  end
142
142
 
143
143
  # GET /automations/{id}/events - the automation's activity: one event
@@ -154,7 +154,9 @@ module OmniSocials
154
154
  # events is left out). Each event carries kind ("comment", "dm",
155
155
  # "story_reply"), outcome, reason / reason_label (X adds the skip
156
156
  # reasons "dms_closed", "no_credits", "opted_out" and
157
- # "automation_off"; Follow first adds "already_waiting"), person (id,
157
+ # "automation_off"; Follow first adds "already_waiting";
158
+ # "plan_inactive" = the organisation had no active plan or trial, so
159
+ # nothing was sent), person (id,
158
160
  # username; on Facebook the person's name, since Facebook has no
159
161
  # @handle), trigger_id, trigger_text, message (the DM sent),
160
162
  # public_reply, platform_message_id, follow_gate (Follow first:
@@ -162,7 +164,7 @@ module OmniSocials
162
164
  # "checked", "after_ask" }, else nil), created_at and sent_at.
163
165
  def list_events(automation_id, outcome: nil, limit: nil, offset: nil)
164
166
  @client.request(
165
- "GET", "/automations/#{automation_id}/events",
167
+ "GET", "/automations/#{Internal.path_segment(automation_id)}/events",
166
168
  query: { "outcome" => outcome, "limit" => limit, "offset" => offset }
167
169
  )
168
170
  end
@@ -0,0 +1,31 @@
1
+ # frozen_string_literal: true
2
+
3
+ module OmniSocials
4
+ module Resources
5
+ # Credits resource: the organisation's credit balance and what X
6
+ # statistics cost. Top-ups are made in the OmniSocials app (Settings ->
7
+ # Organisation -> Billing -> Credits).
8
+ class Credits
9
+ def initialize(client)
10
+ @client = client
11
+ end
12
+
13
+ # GET /credits - the balance and the X statistics overview.
14
+ #
15
+ # Returns { "data" => { "balance", "auto_refill" => { "enabled" },
16
+ # "this_month" => { reason => credits }, "x_statistics" => { "state",
17
+ # "paused_at", "charging" => { "active", "from" }, "prices" =>
18
+ # { "post_read", "media_read", "follower_read" },
19
+ # "total_credits_month", "this_month" => { "post_reads",
20
+ # "media_reads", "follower_reads", "refreshes", "credits" },
21
+ # "accounts" => [{ "account_id", "workspace_id", "handle", "posts",
22
+ # "followers", "tweets_30d", "credits_month" }] } } }. 1 credit = EUR
23
+ # 0.01. Needs the opt-in scope credits:read and billing rights
24
+ # (manage_billing) for the key's creator; OmniSocials Connect keys get
25
+ # 403 not_available_for_connect.
26
+ def get
27
+ @client.request("GET", "/credits")
28
+ end
29
+ end
30
+ end
31
+ end
@@ -54,7 +54,7 @@ module OmniSocials
54
54
  # GET /feature-requests/{id} - one request with its status and the
55
55
  # team's replies. Errors: 400 invalid_id, 404 not_found.
56
56
  def get(request_id)
57
- @client.request("GET", "/feature-requests/#{request_id}")
57
+ @client.request("GET", "/feature-requests/#{Internal.path_segment(request_id)}")
58
58
  end
59
59
  end
60
60
  end
@@ -26,7 +26,7 @@ module OmniSocials
26
26
  def update(folder_id, name: nil, parent_id: OmniSocials::NOT_GIVEN)
27
27
  body = Internal.drop_nil({ "name" => name })
28
28
  body["parent_id"] = parent_id unless parent_id.is_a?(NotGiven)
29
- @client.request("PATCH", "/folders/#{folder_id}", json: body)
29
+ @client.request("PATCH", "/folders/#{Internal.path_segment(folder_id)}", json: body)
30
30
  end
31
31
 
32
32
  # DELETE /folders/{id} - delete a folder. Returns nil (204).
@@ -34,7 +34,7 @@ module OmniSocials
34
34
  # The folder's media is NOT deleted: files move to the root and
35
35
  # subfolders move up to the deleted folder's parent.
36
36
  def delete(folder_id)
37
- @client.request("DELETE", "/folders/#{folder_id}")
37
+ @client.request("DELETE", "/folders/#{Internal.path_segment(folder_id)}")
38
38
  end
39
39
  end
40
40
  end
@@ -16,7 +16,7 @@ module OmniSocials
16
16
 
17
17
  # GET /hashtag-sets/{id} - fetch a single hashtag set.
18
18
  def get(hashtag_set_id)
19
- @client.request("GET", "/hashtag-sets/#{hashtag_set_id}")
19
+ @client.request("GET", "/hashtag-sets/#{Internal.path_segment(hashtag_set_id)}")
20
20
  end
21
21
 
22
22
  # POST /hashtag-sets - create a hashtag set.
@@ -36,12 +36,12 @@ module OmniSocials
36
36
  # `hashtags` replaces the FULL list.
37
37
  def update(hashtag_set_id, name: nil, hashtags: nil)
38
38
  body = Internal.drop_nil({ "name" => name, "hashtags" => hashtags })
39
- @client.request("PATCH", "/hashtag-sets/#{hashtag_set_id}", json: body)
39
+ @client.request("PATCH", "/hashtag-sets/#{Internal.path_segment(hashtag_set_id)}", json: body)
40
40
  end
41
41
 
42
42
  # DELETE /hashtag-sets/{id} - delete a hashtag set. Returns nil (204).
43
43
  def delete(hashtag_set_id)
44
- @client.request("DELETE", "/hashtag-sets/#{hashtag_set_id}")
44
+ @client.request("DELETE", "/hashtag-sets/#{Internal.path_segment(hashtag_set_id)}")
45
45
  end
46
46
  end
47
47
  end
@@ -279,7 +279,7 @@ module OmniSocials
279
279
  # escaped; spaces become %20 (a path segment treats "+" literally,
280
280
  # unlike a query string).
281
281
  def encode_id(conversation_id)
282
- CGI.escape(conversation_id.to_s).gsub("+", "%20")
282
+ Internal.path_segment(conversation_id)
283
283
  end
284
284
  end
285
285
  end
@@ -24,7 +24,7 @@ module OmniSocials
24
24
 
25
25
  # GET /media/{id} - fetch a single library file.
26
26
  def get(media_id)
27
- @client.request("GET", "/media/#{media_id}")
27
+ @client.request("GET", "/media/#{Internal.path_segment(media_id)}")
28
28
  end
29
29
 
30
30
  # POST /media/upload - multipart upload (max 100MB inline).
@@ -130,7 +130,7 @@ module OmniSocials
130
130
  def update(media_id, name: nil, folder_id: OmniSocials::NOT_GIVEN)
131
131
  body = Internal.drop_nil({ "name" => name })
132
132
  body["folder_id"] = folder_id unless folder_id.is_a?(NotGiven)
133
- @client.request("PATCH", "/media/#{media_id}", json: body)
133
+ @client.request("PATCH", "/media/#{Internal.path_segment(media_id)}", json: body)
134
134
  end
135
135
 
136
136
  # DELETE /media/{id} - delete a file. Returns nil (204).
@@ -138,7 +138,7 @@ module OmniSocials
138
138
  # Fails with 409 media_in_use if the file is attached to a scheduled or
139
139
  # publishing post.
140
140
  def delete(media_id)
141
- @client.request("DELETE", "/media/#{media_id}")
141
+ @client.request("DELETE", "/media/#{Internal.path_segment(media_id)}")
142
142
  end
143
143
  end
144
144
  end
@@ -43,7 +43,7 @@ module OmniSocials
43
43
 
44
44
  # GET /posts/{id} - fetch a single post.
45
45
  def get(post_id)
46
- @client.request("GET", "/posts/#{post_id}")
46
+ @client.request("GET", "/posts/#{Internal.path_segment(post_id)}")
47
47
  end
48
48
 
49
49
  # GET /posts/recent-platform - recent posts fetched live from the
@@ -364,7 +364,7 @@ module OmniSocials
364
364
  body["discord"] = discord unless discord.is_a?(NotGiven)
365
365
  # And for tags: an explicit nil (or []) removes every tag of the post.
366
366
  body["tags"] = tags unless tags.is_a?(NotGiven)
367
- @client.request("PATCH", "/posts/#{post_id}", json: body)
367
+ @client.request("PATCH", "/posts/#{Internal.path_segment(post_id)}", json: body)
368
368
  end
369
369
 
370
370
  # DELETE /posts/{id} - remove a post from OmniSocials (the live post
@@ -373,7 +373,7 @@ module OmniSocials
373
373
  # channels, the answer is 409 "post_publishing" and nothing is deleted:
374
374
  # poll #get until "published", "warning" or "failed", then delete it.
375
375
  def delete(post_id)
376
- @client.request("DELETE", "/posts/#{post_id}")
376
+ @client.request("DELETE", "/posts/#{Internal.path_segment(post_id)}")
377
377
  end
378
378
 
379
379
  # POST /posts/{id}/publish - publish a draft or scheduled post now.
@@ -383,7 +383,7 @@ module OmniSocials
383
383
  # "rejected") answers 409 "review_required": it publishes only after a
384
384
  # new review (create it again with approval_workflow_id).
385
385
  def publish(post_id)
386
- @client.request("POST", "/posts/#{post_id}/publish")
386
+ @client.request("POST", "/posts/#{Internal.path_segment(post_id)}/publish")
387
387
  end
388
388
 
389
389
  # POST /posts/{id}/retry - retry the failed platforms of a "failed" or
@@ -397,7 +397,7 @@ module OmniSocials
397
397
  # nothing is queued: poll `get` and retry once the post is "failed" or
398
398
  # "warning" again.
399
399
  def retry(post_id)
400
- @client.request("POST", "/posts/#{post_id}/retry")
400
+ @client.request("POST", "/posts/#{Internal.path_segment(post_id)}/retry")
401
401
  end
402
402
 
403
403
  # POST /posts/{id}/approve - approve the current step of a post's
@@ -419,7 +419,7 @@ module OmniSocials
419
419
  # current, so a retry after a timeout can approve the next step too.
420
420
  def approve(post_id, step_order: nil)
421
421
  body = step_order.nil? ? nil : { "step_order" => step_order }
422
- @client.request("POST", "/posts/#{post_id}/approve", json: body)
422
+ @client.request("POST", "/posts/#{Internal.path_segment(post_id)}/approve", json: body)
423
423
  end
424
424
 
425
425
  # POST /posts/{id}/reject - reject a post's approval workflow, on
@@ -435,7 +435,7 @@ module OmniSocials
435
435
  body = {}
436
436
  body["comment"] = comment if comment
437
437
  body["step_order"] = step_order unless step_order.nil?
438
- @client.request("POST", "/posts/#{post_id}/reject", json: body.empty? ? nil : body)
438
+ @client.request("POST", "/posts/#{Internal.path_segment(post_id)}/reject", json: body.empty? ? nil : body)
439
439
  end
440
440
 
441
441
  # GET /posts/{id}/approval - the approval review of a post: every step
@@ -451,7 +451,7 @@ module OmniSocials
451
451
  # and empty steps and comments. Read-only; requires the posts:read
452
452
  # scope.
453
453
  def get_approval(post_id)
454
- @client.request("GET", "/posts/#{post_id}/approval")
454
+ @client.request("GET", "/posts/#{Internal.path_segment(post_id)}/approval")
455
455
  end
456
456
 
457
457
  private
@@ -51,13 +51,13 @@ module OmniSocials
51
51
  # 409 tag_exists.
52
52
  def update(tag_id, name: nil, color: nil)
53
53
  body = Internal.drop_nil({ "name" => name, "color" => color })
54
- @client.request("PATCH", "/tags/#{tag_id}", json: body)
54
+ @client.request("PATCH", "/tags/#{Internal.path_segment(tag_id)}", json: body)
55
55
  end
56
56
 
57
57
  # DELETE /tags/{id} - delete a tag and take it off every post (the
58
58
  # posts stay). Returns { "data" => { "tag", "posts_untagged" } }.
59
59
  def delete(tag_id)
60
- @client.request("DELETE", "/tags/#{tag_id}")
60
+ @client.request("DELETE", "/tags/#{Internal.path_segment(tag_id)}")
61
61
  end
62
62
 
63
63
  # POST /tags/apply - add, remove or replace the tags of up to 500 posts
@@ -7,7 +7,8 @@ module OmniSocials
7
7
  # ad.status_changed, ad.created, ad.updated, ad.review,
8
8
  # ad.delivery_issue, campaign.created, campaign.updated,
9
9
  # campaign.budget, lead.received, ads.sync_failed, ads.sync_recovered,
10
- # ads.initial_sync_completed and ad_rule.triggered).
10
+ # ads.initial_sync_completed and ad_rule.triggered, and for X
11
+ # statistics x_statistics.paused and x_statistics.resumed).
11
12
  #
12
13
  # For verifying incoming deliveries, see OmniSocials::Webhooks.verify.
13
14
  class Webhooks
@@ -31,7 +32,7 @@ module OmniSocials
31
32
  # GET /webhooks/{id} - fetch a webhook of the key's workspace, or an
32
33
  # organisation-wide webhook of its organisation ("workspace_id" nil).
33
34
  def get(webhook_id)
34
- @client.request("GET", "/webhooks/#{webhook_id}")
35
+ @client.request("GET", "/webhooks/#{Internal.path_segment(webhook_id)}")
35
36
  end
36
37
 
37
38
  # POST /webhooks - create a webhook subscription.
@@ -42,7 +43,11 @@ module OmniSocials
42
43
  # ad.updated, ad.review, ad.delivery_issue, campaign.created,
43
44
  # campaign.updated, campaign.budget, lead.received, ads.sync_failed,
44
45
  # ads.sync_recovered, ads.initial_sync_completed and
45
- # ad_rule.triggered. The `data` of an ad.status_changed delivery is
46
+ # ad_rule.triggered, and x_statistics.paused / x_statistics.resumed
47
+ # (the organisation's X statistics stopped at 0 credits or started
48
+ # again after a top-up, one delivery per workspace with X; `data` is
49
+ # { workspace_id, account_id, reason }, reason insufficient_credits or
50
+ # credits_added). The `data` of an ad.status_changed delivery is
46
51
  # the campaign, not a post: campaign_id, workspace_id, name, platform,
47
52
  # campaign_type, status, previous_status, external_campaign_id and
48
53
  # budget; the other ads events carry the campaign (plus "details") or
@@ -63,7 +68,12 @@ module OmniSocials
63
68
  # Works on organisation-wide webhooks too. is_active: true switches on
64
69
  # a webhook that was switched off (also an automatic switch-off);
65
70
  # setting url, events or switching it on makes the key's creator the
66
- # person behind the webhook.
71
+ # person behind the webhook. Setting url on an organisation-wide
72
+ # webhook (even its current one) moves it to the key's workspace: from
73
+ # then on it gets only that workspace's events, and the answer shows
74
+ # the new workspace_id. When the webhook has Ads events after the
75
+ # change, setting url or events or switching it on needs ads:read and
76
+ # access_ads (403 otherwise, nothing changed).
67
77
  def update(webhook_id, url: nil, events: nil, is_active: nil)
68
78
  body = Internal.drop_nil(
69
79
  {
@@ -72,13 +82,13 @@ module OmniSocials
72
82
  "is_active" => is_active
73
83
  }
74
84
  )
75
- @client.request("PATCH", "/webhooks/#{webhook_id}", json: body)
85
+ @client.request("PATCH", "/webhooks/#{Internal.path_segment(webhook_id)}", json: body)
76
86
  end
77
87
 
78
88
  # DELETE /webhooks/{id} - delete a webhook of the key's workspace or
79
89
  # an organisation-wide webhook of its organisation. Returns nil (204).
80
90
  def delete(webhook_id)
81
- @client.request("DELETE", "/webhooks/#{webhook_id}")
91
+ @client.request("DELETE", "/webhooks/#{Internal.path_segment(webhook_id)}")
82
92
  end
83
93
 
84
94
  # POST /webhooks/{id}/rotate-secret - rotate the signing secret.
@@ -93,7 +103,7 @@ module OmniSocials
93
103
  # replaces the previous secret with the one just rotated out. Works on
94
104
  # organisation-wide webhooks too.
95
105
  def rotate_secret(webhook_id)
96
- @client.request("POST", "/webhooks/#{webhook_id}/rotate-secret")
106
+ @client.request("POST", "/webhooks/#{Internal.path_segment(webhook_id)}/rotate-secret")
97
107
  end
98
108
  end
99
109
  end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module OmniSocials
4
- VERSION = "0.16.0"
4
+ VERSION = "0.18.0"
5
5
  end
data/lib/omnisocials.rb CHANGED
@@ -24,6 +24,7 @@ require_relative "omnisocials/resources/tags"
24
24
  require_relative "omnisocials/resources/approval_workflows"
25
25
  require_relative "omnisocials/resources/accounts"
26
26
  require_relative "omnisocials/resources/analytics"
27
+ require_relative "omnisocials/resources/credits"
27
28
  require_relative "omnisocials/resources/audio"
28
29
  require_relative "omnisocials/resources/locations"
29
30
  require_relative "omnisocials/resources/pinterest"
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.16.0
4
+ version: 0.18.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-11-07 00:00:00.000000000 Z
11
+ date: 2026-11-08 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,
@@ -31,6 +31,7 @@ files:
31
31
  - lib/omnisocials/resources/approval_workflows.rb
32
32
  - lib/omnisocials/resources/audio.rb
33
33
  - lib/omnisocials/resources/automations.rb
34
+ - lib/omnisocials/resources/credits.rb
34
35
  - lib/omnisocials/resources/feature_requests.rb
35
36
  - lib/omnisocials/resources/folders.rb
36
37
  - lib/omnisocials/resources/hashtag_sets.rb