omnisocials 0.17.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 +4 -4
- data/README.md +33 -2
- data/lib/omnisocials/client.rb +2 -1
- data/lib/omnisocials/resources/accounts.rb +30 -0
- data/lib/omnisocials/resources/analytics.rb +21 -0
- data/lib/omnisocials/resources/credits.rb +31 -0
- data/lib/omnisocials/resources/webhooks.rb +7 -2
- data/lib/omnisocials/version.rb +1 -1
- data/lib/omnisocials.rb +1 -0
- metadata +2 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 396d389f359f705ffd24283768276b53efdc6f1f8f4a9d4448b38788b3f23d1d
|
|
4
|
+
data.tar.gz: 45c406d73dd22a7af20c8ec5d02e7f330da72ef9dbe482f9ca5717644439fb02
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
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(
|
data/lib/omnisocials/client.rb
CHANGED
|
@@ -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
|
|
@@ -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
|
|
@@ -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
|
|
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
|
data/lib/omnisocials/version.rb
CHANGED
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,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: omnisocials
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.18.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- OmniSocials
|
|
@@ -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
|