omnisocials 0.17.0 → 0.19.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: ed162913bd0b1df20523b08aa142a02796d6582043bcd83e240beeb8c66f63fe
4
- data.tar.gz: 849d9a1b4cfcc90de8e49c62084c2bb24e25c89890fac04f0b643504bb9052a9
3
+ metadata.gz: 490b6b315f549b047f79a7bdd796c702b9323536f1628bb08a74588f0179d197
4
+ data.tar.gz: ff14b37094ab09bb02e6e86a7fc6785709bb8c815c17cfcce8b6c1eaf83ba548
5
5
  SHA512:
6
- metadata.gz: 6b3c178ef5fe80eb82627dee0fb49820b774b19f5fcfc2c806c7e6c427d186d4f50f809ed313a428f4025d1e57097fab653f6a55a0d5ec1380baac17db7c2788
7
- data.tar.gz: 51133e2698b555d04f47a4d3aa9df28e2407484f3705a6758688d97fda76276a7a1d54d39702437c1f87e13e082ce342e55588fc4e2cab07ffe21cfa6fbe4358
6
+ metadata.gz: e1c426ffcac5d703c4e8d9da2ee717644852fd66704b599e7f200c81f9a300d32e897256d28abdc9138c982db2f7b0be417382186959999b97c21bb857540616
7
+ data.tar.gz: 6af60e23be607ead1188f7f4caa3764cf671ab27f4a59ef5d2bf30500f55ca5179c41a8b114b8c5a3f20ae7cda670178b45e0039483374b214700afda6d1ed55
data/README.md CHANGED
@@ -84,7 +84,7 @@ client.posts.update(proposal["data"]["id"], draft: false)
84
84
 
85
85
  ### Comment-to-DM automations
86
86
 
87
- Answer a keyword in an Instagram comment with a DM, once per person, with an optional public reply under the comment. Pass `comment_dm_automation:` on `create` (Instagram must be in `channels`) and the automation is bound to that post; it starts listening once the post is live. Needs the opt-in `automations:write` scope on the key. `client.automations` manages the automations themselves (`list`, `get`, `create`, `update`, `delete`) and reads their activity (`list_events`, `automations:read`). On `update`, `comment_dm_automation:` as a Hash replaces the post's automation and an explicit `nil` removes it. Instagram rules: one private reply per comment, within 7 days; OmniSocials caps sends at 180 DMs an hour per account.
87
+ Answer a keyword in an Instagram comment with a DM, once per person, with an optional public reply under the comment. Pass `comment_dm_automation:` on `create` (Instagram must be in `channels`) and the automation is bound to that post; it starts listening once the post is live. Needs the opt-in `automations:write` scope on the key. `client.automations` manages the automations themselves (`list`, `get`, `create`, `update`, `delete`) and reads their activity (`list_events`, `automations:read`). On `update`, `comment_dm_automation:` as a Hash replaces the post's automation and an explicit `nil` removes it. Instagram rules: one private reply per comment, within 7 days; OmniSocials caps sends at 700 DMs an hour per account, and an answer over the cap waits in a queue for up to a day.
88
88
 
89
89
  ```ruby
90
90
  post = client.posts.create(
@@ -129,6 +129,23 @@ client.automations.update(
129
129
  )
130
130
  ```
131
131
 
132
+ A follow-up (`"follow_up"` in the actions, Instagram and Facebook) sends one more DM `delay_hours` (1 to 23, default 23) after the answer went out, with an optional link `button`. Meta allows an automatic message only within 24 hours after the person's last DM, button tap or quick reply; the comment and the private reply do not open that window. So on an Instagram comment with Follow first off the first DM becomes a tap step, a short text with one button (`tap`, default "Tap the button and I'll send you the link 👇" / "Send me the link"), and the tap sends the DM text. Until the tap the event is `waiting` with `event["follow_gate"]["mode"]` `"tap"`; people who never tap get no link and no follow-up. With Follow first on, its own tap is the tap; DM and story reply triggers need none. A Facebook comment answer has no button, so only people who answer the DM in Messenger get the follow-up. At send time it is skipped when the automation is off, the person said stop, your team answered by hand or the window closed: `event["follow_up"]` carries `state`, `due_at`, `sent_at` and `reason` / `reason_label`, and `stats["follow_ups_sent"]` / `stats["follow_ups_skipped"]` count them. `nil`, `false` or `{ "enabled" => false }` turns it off and keeps the texts; on `update` it merges (`"button" => nil` removes the button). `"enabled" => true` on an X automation is a `400 follow_up_not_supported`.
133
+
134
+ ```ruby
135
+ client.automations.update(
136
+ automation_id,
137
+ actions: {
138
+ "dm" => { "text" => "Here is the guide: https://example.com/guide" },
139
+ "follow_up" => {
140
+ "enabled" => true,
141
+ "text" => "Did the guide help? Book a free call if you want a hand.",
142
+ "delay_hours" => 23,
143
+ "button" => { "title" => "Book a call", "url" => "https://example.com/call" }
144
+ }
145
+ }
146
+ )
147
+ ```
148
+
132
149
  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.
133
150
 
134
151
  On X, pass `platform: "x"` with `trigger: { "kinds" => ["dm"], "keywords" => ["guide"] }`: the X account answers a keyword in a DM, once per person, and every answer ends with "Reply STOP to stop automatic messages." An active X automation needs X DMs on for the workspace (`409 x_dms_off`; `status: "paused"` always saves). An answer over the send cap waits in a queue (`queued`) for up to an hour.
@@ -278,7 +295,7 @@ res = client.posts.create(
278
295
  end
279
296
  ```
280
297
 
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.
298
+ 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
299
 
283
300
  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
301
 
@@ -507,6 +524,8 @@ account = client.accounts.get("instagram")
507
524
 
508
525
  `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
526
 
527
+ 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).
528
+
510
529
  ## Analytics
511
530
 
512
531
  ```ruby
@@ -532,6 +551,35 @@ best = client.analytics.best_times(platform: "instagram", timezone: "Europe/Amst
532
551
  best["recommendations"].each { |slot| puts "#{slot["day"]} #{slot["time"]} #{slot["score"]}" }
533
552
  ```
534
553
 
554
+ ### X statistics use credits
555
+
556
+ 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`:
557
+
558
+ - `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`.
559
+ - `followers`: how often the follower count is read. `daily`, `weekly` or `off`.
560
+ - `source` (`account` or `default`), `billing` (`credits`), `state` (`active`, `paused`, `off`) and `paused_reason` (`insufficient_credits` or null).
561
+
562
+ 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.
563
+
564
+ ```ruby
565
+ # How often an X account is checked (opt-in scope accounts:write, billing rights)
566
+ account = client.accounts.update(
567
+ "1234_x",
568
+ x_statistics: { posts: "light", followers: "daily" } # one key or both
569
+ )
570
+ puts account["data"]["x_statistics"]["state"]
571
+
572
+ # "Update now": read one post's X numbers now (scope analytics:read)
573
+ fresh = client.analytics.refresh_post(9123)
574
+ puts fresh["data"]["credits_used"]
575
+
576
+ # The balance and what X statistics cost (opt-in scope credits:read, billing rights)
577
+ credits = client.credits.get["data"]
578
+ puts credits["balance"], credits["x_statistics"]["total_credits_month"]
579
+ ```
580
+
581
+ `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.
582
+
535
583
  ## Locations (Instagram and Threads place tagging)
536
584
 
537
585
  ```ruby
@@ -740,7 +788,7 @@ interests = client.ads.targeting.search(ad_account_id: meta["id"], type: "intere
740
788
 
741
789
  ## Webhooks
742
790
 
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`).
791
+ 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
792
 
745
793
  ```ruby
746
794
  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)
@@ -17,9 +17,39 @@ 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
25
  @client.request("GET", "/accounts/#{Internal.path_segment(account_id)}")
22
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
+ )
52
+ end
23
53
  end
24
54
  end
25
55
  end
@@ -13,6 +13,27 @@ module OmniSocials
13
13
  @client.request("GET", "/analytics/posts/#{Internal.path_segment(post_id)}")
14
14
  end
15
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
+ )
35
+ end
36
+
16
37
  # GET /analytics/posts?ids=a,b,c - bulk metrics for up to 100 posts in
17
38
  # one request. `ids` is an Array of post ids (or an already-joined
18
39
  # comma-separated String). Each entry also carries "tags" (the post's
@@ -69,9 +69,10 @@ module OmniSocials
69
69
  # "2026-12-31T00:00:00Z" } (both optional). `status` is "active"
70
70
  # (default) or "paused". Meta rules, the same on Instagram and
71
71
  # Facebook: one private reply per comment, within 7 days; OmniSocials
72
- # caps sends at 180 DMs an hour per account and platform, and on X at
72
+ # caps sends at 700 DMs an hour per account and platform, and on X at
73
73
  # 15 per 15 minutes and 450 a day; an answer over a cap waits in a
74
- # queue ("queued") for up to an hour.
74
+ # queue ("queued") for up to about a day on Instagram and Facebook
75
+ # (an hour on X).
75
76
  #
76
77
  # Follow first (Instagram only): actions "follow_gate" => { "enabled"
77
78
  # => true, "first_message" => { "text", "button" }, "not_following" =>
@@ -86,8 +87,34 @@ module OmniSocials
86
87
  # the default. nil or false turns it off. The response carries the
87
88
  # gate with its texts (nil on Facebook and X) and stats "followed".
88
89
  #
90
+ # Follow-up (Instagram and Facebook): actions "follow_up" => {
91
+ # "enabled" => true, "text" => "...", "delay_hours" => 23, "button" =>
92
+ # { "title", "url" }, "tap" => { "text", "button" } } sends one more DM
93
+ # delay_hours (1 to 23, default 23) after the answer (the "dm" text)
94
+ # went out. "text" is required when it is on (max 1000 characters,
95
+ # 640 with a "button"); "button" is an optional link button ("title"
96
+ # 1 to 20 characters, "url" an https:// or http:// address of up to
97
+ # 2000). Meta allows an automatic message only within 24 hours after
98
+ # the person's last DM, button tap or quick reply; the comment and the
99
+ # private reply do not open that window. So on an Instagram comment
100
+ # with Follow first off the first DM becomes a tap step, a short text
101
+ # with one button ("tap", Instagram only, "text" max 640 and "button"
102
+ # max 20 characters; default "Tap the button and I'll send you the
103
+ # link 👇" / "Send me the link"): the tap sends the link, and until
104
+ # then the event is "waiting" with follow_gate "mode" "tap". People
105
+ # who never tap get no link and no follow-up. With Follow first on,
106
+ # its own tap is the tap; DM and story reply triggers need none. A
107
+ # Facebook comment answer has no button: only people who answer the
108
+ # DM in Messenger get the follow-up. nil, false or { "enabled" =>
109
+ # false } turns it off and keeps the texts. The response carries
110
+ # actions "follow_up" ({ "enabled", "text", "delay_hours", "button" =>
111
+ # {...} | nil, "tap" => {...} | nil }, "tap" filled in on Instagram
112
+ # and nil on Facebook; the whole follow-up is nil on X) and stats
113
+ # "follow_ups_sent" / "follow_ups_skipped".
114
+ #
89
115
  # Requires the automations:write scope (opt-in on the API key).
90
116
  # Errors: 400 validation_error, 400 follow_gate_instagram_only, 400
117
+ # follow_up_not_supported (a follow-up switched on on X), 400
91
118
  # post_not_instagram, 400 post_not_facebook, 400 post_required, 404 post_not_found, 404
92
119
  # instagram_media_not_found, 404 facebook_post_not_found, 409
93
120
  # instagram_not_connected, 409 instagram_needs_reauth, 409
@@ -114,15 +141,18 @@ module OmniSocials
114
141
  # "public_reply" => { "enabled" => false } or { "variations" => [] }
115
142
  # turns the public reply off; "follow_gate" => { "enabled" => false }
116
143
  # 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
144
+ # switch, and "follow_gate" => nil turns it off; "follow_up" merges
145
+ # the same way ("tap" key by key, "button" => nil removes the button,
146
+ # nil, false or { "enabled" => false } turns it off and keeps the
147
+ # texts); limits: { "max_sends" => nil } removes that limit. status: "paused" pauses and "active" resumes; another
119
148
  # post_id / instagram_media_id / facebook_post_id moves the automation
120
149
  # to that post. The platform cannot change: a platform other than the
121
150
  # automation's is a 400 platform_immutable. status: "active" on an X
122
151
  # automation needs X DMs on for the workspace (409 x_dms_off). A
123
152
  # "completed" automation starts again when its limits or trigger
124
153
  # change. Requires the
125
- # automations:write scope. 400 no_fields when nothing is passed.
154
+ # automations:write scope. 400 no_fields when nothing is passed; 400
155
+ # follow_up_not_supported for a follow-up switched on on X.
126
156
  def update(automation_id, name: nil, post_id: nil, instagram_media_id: nil,
127
157
  trigger: nil, actions: nil, limits: nil, status: nil,
128
158
  platform: nil, facebook_post_id: nil)
@@ -143,9 +173,10 @@ module OmniSocials
143
173
  # GET /automations/{id}/events - the automation's activity: one event
144
174
  # per person it answered, skipped or failed on. outcome filters on
145
175
  # "sent", "skipped", "failed", "pending", "queued" (waits for a free
146
- # slot under the send cap, out within the hour), "opted_out" (the
176
+ # slot under the send cap, out as soon as there is room), "opted_out" (the
147
177
  # person replied STOP on X) or "waiting" (Follow first: asked to
148
- # follow, the link goes out after the follow); limit is 1..100
178
+ # follow, the link goes out after the follow; or the tap step of a
179
+ # follow-up: the link goes out after the tap); limit is 1..100
149
180
  # (default 25), offset skips. Requires the automations:read scope.
150
181
  #
151
182
  # The response is not the plain list envelope: { "data" => [...],
@@ -161,7 +192,19 @@ module OmniSocials
161
192
  # @handle), trigger_id, trigger_text, message (the DM sent),
162
193
  # public_reply, platform_message_id, follow_gate (Follow first:
163
194
  # { "state" => "waiting" | "done", "asked_at", "taps", "followed",
164
- # "checked", "after_ask" }, else nil), created_at and sent_at.
195
+ # "checked", "after_ask", "mode" }, else nil; "mode" is "follow", or
196
+ # "tap" for the tap step of a follow-up, which checks no follow:
197
+ # "checked" stays false and "followed" is nil after the tap),
198
+ # follow_up (the follow-up of this answer: { "state" => "scheduled" |
199
+ # "sending" | "sent" | "skipped" | "failed", "due_at", "sent_at",
200
+ # "reason", "reason_label", "platform_message_id" }, else nil;
201
+ # "reason" only on skipped and failed: "automation_off",
202
+ # "follow_up_off", "plan_inactive", "opted_out", "team_answered",
203
+ # "window_closed" (the person's last tap or message is older than 24
204
+ # hours minus 15 minutes) or "cannot_message" for a skip, the
205
+ # platform's error text or "interrupted" (a send that died midway,
206
+ # never sent again) for a failure; "reason_label" = the skip in plain
207
+ # words, or the error text), created_at and sent_at.
165
208
  def list_events(automation_id, outcome: nil, limit: nil, offset: nil)
166
209
  @client.request(
167
210
  "GET", "/automations/#{Internal.path_segment(automation_id)}/events",
@@ -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
@@ -173,7 +173,8 @@ module OmniSocials
173
173
  # [...] } }, "limits" => { "max_sends" => 500 }, "platforms" =>
174
174
  # ["instagram", "facebook"] } (see automations.create for the
175
175
  # fields, also the actions "follow_gate", Follow first, which applies
176
- # to the Instagram automation only). "platforms" makes one automation
176
+ # to the Instagram automation only, and "follow_up", the follow-up,
177
+ # which applies to both). "platforms" makes one automation
177
178
  # per listed channel; each
178
179
  # must be a channel of the post. Without it: Instagram when the post
179
180
  # goes there, else Facebook. Needs the automations:write scope on the
@@ -299,7 +300,8 @@ module OmniSocials
299
300
  # comment_dm_automation (same shape as on #create) as a Hash replaces
300
301
  # the post's comment-to-DM automations (a channel no longer in
301
302
  # "platforms" loses its automation), an explicit nil removes them all,
302
- # and leaving it out keeps them. Needs the automations:write scope.
303
+ # and leaving it out keeps them. An "actions" without "follow_up"
304
+ # keeps the stored follow-up. Needs the automations:write scope.
303
305
  #
304
306
  # discord merges into the stored Discord options: a key set to nil
305
307
  # removes that option (e.g. discord: { "poll" => nil }), an explicit
@@ -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
@@ -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
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module OmniSocials
4
- VERSION = "0.17.0"
4
+ VERSION = "0.19.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.17.0
4
+ version: 0.19.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-08 00:00:00.000000000 Z
11
+ date: 2026-11-19 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