omnisocials 0.15.0 → 0.16.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: 8c00d8899c0d1c024d739775a25508750dfada8a2be74eb4ecdc2b855b39cafe
4
- data.tar.gz: cad371c9a76055c3331232856d48192f638e1fa382482c018b9b78ff0dc47017
3
+ metadata.gz: 7ea0275865830c8eb34ba9ae4f21fdf9ee1eef376185a7fcdaf379170d185668
4
+ data.tar.gz: 4b136937c0214a7f703ad46e00cb719a61ee89a071ec58d6df640cb6aa7f88c8
5
5
  SHA512:
6
- metadata.gz: 93ae9f8f0a567e517c3c45408eaf22f9663d2e9354526d37b05be404ce5805021c70852cedef9a081d4cd27c824ef88e8a9966c8a2c6d9d11b077b29c2e98d2f
7
- data.tar.gz: 4bfa021ebf8d846b0e705ebd0fdcd95343b0b508c433f9f5e2a86c843f5e8c413044599b176203f0b7c46090204ad537cadf57b758ee23707063bb298c5aba72
6
+ metadata.gz: 5f2d22fe54e670da7eb3c4451beae5472ac00e7c030ba9f280b2eb379f2b05c48f5e9e0d33420a9645f669d4811953796b66acc46bb8b4a2e8c2aa55d84878ab
7
+ data.tar.gz: fed3adc29d81f96febcd4e2e70974ef1a6a6a76e361f22cf3230daa36c4710fdbbe95236edfcc3fcb5610285d499c7a4308f6e4febc0d876a3c3b01502729396
data/README.md CHANGED
@@ -319,14 +319,35 @@ recent = client.posts.recent_platform(limit: 10, platforms: ["instagram", "tikto
319
319
 
320
320
  `retry` re-publishes only the platforms that failed, on the same post; platforms that already succeeded are never posted again. It is asynchronous: a 200 means the retry is queued, so poll `get` for the outcome. Max 3 retries per platform.
321
321
 
322
+ These calls answer `409` and change nothing when the post is not in a state for them:
323
+
324
+ - `post_publishing`: `update` or `delete` while the post is publishing (status `posting`) or a retry publishes one of its channels. Poll `get` until the status is `published`, `warning` or `failed`. An `update` with only `tags` still works.
325
+ - `review_required`: changes were requested on the post (`approval_status` `rejected`), so `publish`, or an `update` that would schedule it, is refused. It needs a new review: create it again with `approval_workflow_id`. Saving it as a draft works.
326
+ - `retry_in_progress`: `retry` while another retry of the post runs.
327
+ - `media_processing`: a media id in `create`, `create_and_publish` or `update` is still processing. Wait until `client.media.get(id)` says `ready`, then send the same request again. A file whose processing failed answers `400 invalid_media`: upload it again.
328
+
322
329
  ### Approve or reject a post
323
330
 
324
331
  ```ruby
325
- client.posts.approve("123") # approve the current approval-workflow step
326
- client.posts.reject("123", comment: "Wrong CTA link, please fix.") # reject and stop the workflow (comment optional)
332
+ # Read the step you review first, then name it on the decision.
333
+ review = client.posts.get_approval("123")["data"]
334
+ step = review["current_step"]
335
+
336
+ begin
337
+ client.posts.approve("123", step_order: step) # approve the step you reviewed
338
+ # or: reject and stop the workflow (comment optional)
339
+ # client.posts.reject("123", comment: "Wrong CTA link, please fix.", step_order: step)
340
+ rescue OmniSocials::APIError => e
341
+ raise unless e.code == "step_changed"
342
+
343
+ # Somebody decided since you read it: nothing was decided. Read the approval again.
344
+ puts "The review is on step #{e.body["error"]["current_step_order"]}"
345
+ end
327
346
  ```
328
347
 
329
- Only works on a post with `approval_status: "pending"` (`status: "in_approval"`). Both act on behalf of the user who owns the API key, who must be a listed approver for the workflow's CURRENT step — steps approve in order, so being an approver on a later step is not enough yet (raises a 403 `OmniSocials::PermissionDeniedError`). Approving the last step finalizes the post (`scheduled` or `posting`); rejecting stops the whole workflow immediately, not just the current step.
348
+ Only works on a post with `approval_status: "pending"` (`status: "in_approval"`). Both act on behalf of the user who owns the API key, who must be a listed approver for the workflow's CURRENT step. Steps approve in order, so being an approver on a later step is not enough yet (raises a 403 `OmniSocials::PermissionDeniedError`). Approving the last step finalizes the post (`scheduled` or `posting`); rejecting stops the whole workflow immediately, not just the current step.
349
+
350
+ `step_order:` is optional: the `current_step` of `get_approval`. When the review is on another step now (somebody decided since you read it, or a retried call already went through), nothing is decided and the call raises a 409 `OmniSocials::APIError` with code `step_changed` and `error.current_step_order`, the step the review is on now. Without `step_order:` the call acts on whatever step is current, so a retry after a timeout could approve the next step too.
330
351
 
331
352
  ### Read the approval review
332
353
 
@@ -355,7 +376,7 @@ media = client.media.upload_from_url(
355
376
  media_id = media["data"]["id"]
356
377
  ```
357
378
 
358
- Files over 100MB are processed in the background: the response has `media["data"]["status"] == "processing"`; poll `client.media.get(media_id)` until it is `"ready"` before attaching it to a post.
379
+ Files over 100MB are processed in the background: the response has `media["data"]["status"] == "processing"`; poll `client.media.get(media_id)` until it is `"ready"` before attaching it to a post. When such a file cannot be queued, the call answers `503 processing_unavailable`: send the same request again in a minute.
359
380
 
360
381
  ### Upload a local file (multipart, max 100MB)
361
382
 
@@ -477,12 +498,15 @@ end
477
498
  ```ruby
478
499
  accounts = client.accounts.list
479
500
  accounts["data"].each do |account|
480
- puts "#{account["platform"]}: #{account["username"]}"
501
+ puts "#{account["platform"]}: #{account["username"]} (#{account["status"]})"
502
+ puts " needs a reconnect: #{account["reauth_reason"]}" if account["needs_reconnect"]
481
503
  end
482
504
 
483
505
  account = client.accounts.get("instagram")
484
506
  ```
485
507
 
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
+
486
510
  ## Analytics
487
511
 
488
512
  ```ruby
@@ -650,11 +674,11 @@ end
650
674
 
651
675
  ## Ads
652
676
 
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.
677
+ Boost a published post or create a new ad on Meta, Pinterest, TikTok, LinkedIn, X and Google. Boosts and new ads are drafts: your code writes the draft, and the person who pays sees the amount and starts the ad in OmniSocials from the draft's `review_url`. A key starts and raises spend itself only with the opt-in **Start ads** switch (scope `ads:spend`). Without it `ads.activate`, `ads.activate_multi`, `ads.resume`, `ads.drafts.launch`, a budget raise or any change of a campaign that reached the network through `ads.update`, and the parity calls that switch something on or raise a budget answer `403 start_in_app`, and the error message names the page where the person does it. Google (`api_draft_only` of `ads.capabilities`) always stops at the draft, also with `ads:spend`. `ads.pause` and `ads.delete` stay open, except on the networks in `api_stop_in_app` (Google), where a campaign that reached the network also answers `403 start_in_app`. Only a paused campaign resumes (`409 not_paused`). The calls that start or raise spend repeat the amount (`confirm_budget_amount`) and are not retried after a 5xx or a timeout, only after a 429, because the first attempt may have started the ad: read the campaign or the draft to see what happened.
654
678
 
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.
679
+ The `ads:read` and `ads:write` scopes are opt-in: create the API key with **Ads** switched on (Settings, API). `ads:spend` is the **Start ads** switch under it, offered only to a person with `manage_ads`. A key without a scope it needs 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: a draft whose `budget["currency"]` differs from the attached ad account's currency answers `400 currency_mismatch`. Ads errors may carry `param`, the field at fault: read it from `e.body["error"]["param"]` on the raised `OmniSocials::APIError` (here `"budget.currency"`). Ad account and campaign ids come back as strings (`"51"`); the methods take an id as a string or a number.
656
680
 
657
- ### Create an ad (draft, then launch)
681
+ ### Create an ad (a draft the person starts)
658
682
 
659
683
  ```ruby
660
684
  caps = client.ads.capabilities
@@ -678,14 +702,12 @@ draft = client.ads.drafts.create(
678
702
  ]
679
703
  )["data"]
680
704
 
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
705
+ # A draft spends nothing. The person checks it and starts it in OmniSocials:
706
+ puts "Check and start the ad here: #{draft["review_url"]}"
687
707
  ```
688
708
 
709
+ With a key that has `ads:spend`, `client.ads.drafts.launch(draft["group_id"], confirm_budget_amount: 10)` starts the draft after the person agreed to the amount; Google is skipped with code `start_in_app`. Without `ads:spend` the call answers `403 start_in_app`.
710
+
689
711
  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
712
 
691
713
  ### Boost a post
@@ -701,15 +723,24 @@ boost = client.ads.boost(
701
723
  targeting: { "countries" => ["NL"] }
702
724
  )["data"]
703
725
 
704
- # The boost is a draft. Start it only after the person confirmed 5 a day:
705
- client.ads.activate(boost["id"], 5)
726
+ # The boost is a draft: the person starts it in OmniSocials.
727
+ puts boost["status"] # "draft"
706
728
  ```
707
729
 
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: [...])`.
730
+ `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 (`totals["spend"]` is `nil` when the campaigns use more than one currency: read `totals_by_currency`, one row per currency), and `client.ads.list`, `get`, `pause` 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: [...])`.
731
+
732
+ ### More of the Ads API
733
+
734
+ Sub-resources cover the rest of the Ads API: `objects` (the tree of an ad account, also campaigns made outside OmniSocials, and their import), `campaign_ads`, `comments`, `targeting`, `audiences`, `lead_forms`, `leads`, `conversions`, `insights`, `reports`, `rules`, `results`, `media`, `previews`, `partnership`, `accounts` (health, finance, settings, people), `reach_frequency`, `studies`, `budget_schedules` and `google`, plus `ads.bulk_status` and `ads.duplicate`. A network without a feature answers `400 not_supported_on_network`; `ads.capabilities` lists `features` and `targeting_types` per network. Every call that switches something on or raises spend needs a key with `ads:spend` (without it, and on Google always, `403 start_in_app`; a rule that switches on or raises a budget: `403 rule_raises_spend`): `objects.update`, `objects.set_status` (switching on), `objects.duplicate`, `bulk_status` (resuming), `campaign_ads.add`, `campaign_ads.set_status` (switching on), `rules.create`, `rules.update`, `rules.undo`, `accounts.update_settings` (a spend cap), `reach_frequency.reserve`, `studies.create` and `budget_schedules.create`. The ones that raise spend take the person's own amount and are not retried after a 5xx or a timeout. Pausing, deleting and archiving stay open, except on Google; a rule that notifies, pauses or lowers a budget works with `ads:write` and never acts on Google.
735
+
736
+ ```ruby
737
+ interests = client.ads.targeting.search(ad_account_id: meta["id"], type: "interest", q: "running")["data"]["items"]
738
+ # Use the ids in targeting["networks"]["meta"]["include"]["interest"] of a draft.
739
+ ```
709
740
 
710
741
  ## Webhooks
711
742
 
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`.
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`).
713
744
 
714
745
  ```ruby
715
746
  webhook = client.webhooks.create(
@@ -721,10 +752,12 @@ secret = webhook["data"]["secret"] # only shown once, store it
721
752
  client.webhooks.list
722
753
  client.webhooks.get(webhook["data"]["id"])
723
754
  client.webhooks.update(webhook["data"]["id"], is_active: false)
724
- client.webhooks.rotate_secret(webhook["data"]["id"]) # new secret, shown once
755
+ client.webhooks.rotate_secret(webhook["data"]["id"]) # new secret, shown once; the old one signs for 24 hours more
725
756
  client.webhooks.delete(webhook["data"]["id"])
726
757
  ```
727
758
 
759
+ Every webhook carries `workspace_id`. `list` and `get` also return the organisation-wide webhooks of the key's organisation (`workspace_id` `nil`, made in the OmniSocials dashboard; they receive the events of every workspace), and `update`, `delete` and `rotate_secret` work on them too. Webhooks you create through the API belong to the key's workspace. When the person behind a webhook loses access to the organisation or workspace, OmniSocials switches the webhook off: `is_active` is `false` and `last_failure["error"]` says why. `update(id, is_active: true)` switches it on again.
760
+
728
761
  ### Verifying webhook signatures (Rails example)
729
762
 
730
763
  Every delivery is signed with HMAC-SHA256. The `X-OmniSocials-Signature` header has the form `t=<unix>,v1=<hex>`, signed over `"{timestamp}.{raw_body}"`. Use `OmniSocials::Webhooks.verify` with the raw request body (do not parse it first):
@@ -791,6 +824,31 @@ run app
791
824
 
792
825
  `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.
793
826
 
827
+ ### Rotate the secret without missing deliveries
828
+
829
+ For 24 hours after `rotate_secret`, every delivery carries two headers: `X-OmniSocials-Signature`, signed with the new secret, and `X-OmniSocials-Signature-Previous`, signed with the old secret (same format, same timestamp and body). Verify the first with the new secret and, when that fails, the second with the old one:
830
+
831
+ ```ruby
832
+ def verify_delivery(payload, headers)
833
+ OmniSocials::Webhooks.verify(
834
+ payload: payload,
835
+ signature: headers["X-OmniSocials-Signature"],
836
+ secret: ENV.fetch("OMNISOCIALS_WEBHOOK_SECRET") # the new secret
837
+ )
838
+ rescue OmniSocials::WebhookVerificationError
839
+ previous = headers["X-OmniSocials-Signature-Previous"]
840
+ raise if previous.nil?
841
+
842
+ OmniSocials::Webhooks.verify(
843
+ payload: payload,
844
+ signature: previous,
845
+ secret: ENV.fetch("OMNISOCIALS_WEBHOOK_SECRET_OLD") # the old secret
846
+ )
847
+ end
848
+ ```
849
+
850
+ Rotating again within the 24 hours replaces the previous secret with the one you just rotated out.
851
+
794
852
  ## Limits and feature requests
795
853
 
796
854
  `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.