omnisocials 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfdc77673c3c6885b9098af3daf33b7393329ed3b6501fd04d28e813585d97b0
-  data.tar.gz: 9753cf8ccae71e85a0414fa137d1b201f678c8a7a018edacb2a74df4353dc822
+  metadata.gz: 0200cd0b7aa77ce95c037b0f5fd93a9e80b7bfdc589194b53c80084bb560b165
+  data.tar.gz: 37e48405dd0871201467442b940d2bc1dabd8057deddd81f903e25250bdb5cbc
 SHA512:
-  metadata.gz: 7d8390a9fb03fb151002f79d55706c43b29506d604fe84a9c4707cbe233166ebaab7ad4d2a552e1db14de26a8eed0e8244879daf148f2f83bf3a83d5fe7d8449
-  data.tar.gz: 0376b9f5a46d25a6cfc9ca718f46ffd45d2cbe1deecdd9430f1bc2ac2b7a45e1299b5b93d54e8dcf3cf98f17f32b379c56eaed9fffb1699aa203493d27d5a4b3
+  metadata.gz: 886f262e3a7eb8c2164f75845e8c67c3e5d86c2869974ffb290b69d8ebeb29b4f29cba11130d1722152236c3b865d9651194709fef35a24bc15b9eba4fe798a9
+  data.tar.gz: '078aba4be97a9fbcceef92fc3587059ea6e7cef7d760da25949bbc5eff37cc1ea3ff4fb59d47b8b5ec2ad12b532b5e7f4dace15572df90b8a42cffb57e8e75e2'

data/README.md

@@ -143,6 +143,26 @@ end
 
 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.
 
+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:
+
+```ruby
+begin
+  client.posts.create(
+    content: "Read the full story: https://example.com/post",
+    channels: ["x"],
+    scheduled_at: "2026-08-20T09:00:00Z"
+  )
+rescue OmniSocials::APIError => e
+  if e.code == "x_credits_insufficient"
+    puts "Not enough reserved credits: #{e.body["error"]["details"]}"
+  else
+    raise
+  end
+end
+```
+
+Drafts are never gated, and posts scheduled to publish before 2026-08-14 are never gated either.
+
 ### Other post operations
 
 ```ruby
@@ -310,6 +330,47 @@ client.posts.create(
 )
 ```
 
+## Inbox
+
+Read and reply to social inbox conversations (DMs, comments, mentions) across connected platforms. Requires an API key with the opt-in `inbox:read` / `inbox:write` scopes. The list endpoints are cursor-paginated (unlike the offset pagination used elsewhere): page while `pagination["has_more"]` is true by passing the previous response's `pagination["next_cursor"]` as `cursor`.
+
+```ruby
+conversations = client.inbox.list_conversations(platform: "instagram", unread: true, limit: 20)
+conversations["data"].each do |conversation|
+  puts "#{conversation["platform"]}: #{conversation["preview"]}"
+end
+
+conversation_id = conversations["data"][0]["id"]
+messages = client.inbox.get_messages(conversation_id)
+messages["data"].each do |message|
+  puts "#{message["direction"]}: #{message["text"]}"  # direction is "incoming" or "outgoing"
+end
+
+client.inbox.mark_read(conversation_id)
+client.inbox.reply(conversation_id, text: "Thanks for reaching out!")
+```
+
+`platform` accepts `"instagram"`, `"facebook"`, `"linkedin"`, `"tiktok"`, or `"x"`; `type` accepts `"dm"`, `"comment"`, or `"mention"`. TikTok replies are comments only and capped at 150 characters. Conversation ids are URL-encoded for you, so pass them exactly as returned - LinkedIn ids contain `":"` and `"()"` (e.g. `"linkedin_comment_urn:li:activity:123"`).
+
+Replying to an X DM costs 2 prepaid credits, debited from the company balance before the send and automatically refunded if the send fails:
+
+```ruby
+begin
+  client.inbox.reply(conversation_id, text: "On it, thanks!")
+rescue OmniSocials::APIError => e
+  case e.code
+  when "insufficient_credits"
+    puts "Not enough credits to send this reply (need 2)."
+  when "x_inbox_suspended"
+    puts "X inbox is suspended - top up and re-enable it in the dashboard."
+  else
+    raise
+  end
+end
+```
+
+`x_inbox_suspended` fires once a workspace's X inbox has auto-suspended after its credit balance hit zero; topping up and re-enabling it in the dashboard resumes delivery, but DMs that arrived while suspended are not recovered.
+
 ## Webhooks
 
 Subscribe to `post.scheduled`, `post.published`, and `post.failed` events:

data/lib/omnisocials/resources/inbox.rb

@@ -23,9 +23,10 @@ module OmniSocials
       # GET /inbox/conversations - list conversations, newest activity first.
       #
       # All filters are optional: platform ("instagram", "facebook",
-      # "linkedin"), type ("dm", "comment", "mention"), unread (only
-      # conversations with unread messages), limit (1-100), and cursor (an
-      # opaque cursor from a previous response's pagination["next_cursor"]).
+      # "linkedin", "tiktok", "x"), type ("dm", "comment", "mention"),
+      # unread (only conversations with unread messages), limit (1-100), and
+      # cursor (an opaque cursor from a previous response's
+      # pagination["next_cursor"]).
       def list_conversations(platform: nil, type: nil, unread: nil, limit: nil, cursor: nil)
         @client.request(
           "GET", "/inbox/conversations",
@@ -59,7 +60,16 @@ module OmniSocials
       #
       # `text` is required. Optionally attach a single media asset by public
       # URL with `attachment_url` plus `attachment_type` ("image", "video",
-      # "audio", or "file"). Returns the created outbound message.
+      # "audio", or "file"). Returns the created outgoing message.
+      #
+      # Replying to an X DM costs 2 prepaid credits, debited from the
+      # company balance before the send and automatically refunded if the
+      # send fails. Two 402 error codes are specific to this call:
+      # "insufficient_credits" when the balance can't cover the 2 credits,
+      # and "x_inbox_suspended" when the workspace's X inbox was
+      # auto-suspended after the balance hit zero (top up and re-enable it
+      # in the dashboard to resume; DMs that arrived while suspended are
+      # not recovered).
       def reply(conversation_id, text:, attachment_url: nil, attachment_type: nil)
         body = Internal.drop_nil(
           {

data/lib/omnisocials/resources/posts.rb

@@ -57,6 +57,14 @@ module OmniSocials
       # and credits_balance: X's link-post fee is passed through as prepaid
       # credits, debited at publish time (from 2026-08-14). Credits are
       # managed in the dashboard, not the API.
+      #
+      # Separately, from 2026-08-14 this call (and #update / #publish) can
+      # refuse an X link post up front with a 402 and error code
+      # "x_credits_insufficient" (details: credits_required, credits_balance,
+      # credits_reserved) when reserving this post's cost would push the
+      # company's total reserved credits past its balance. Drafts are never
+      # gated, and posts scheduled to publish before 2026-08-14 are never
+      # gated either.
       def create(content:, channels: nil, scheduled_at: nil, media_ids: nil,
                  media_urls: nil, type: nil, source: nil, link_url: nil,
                  link_title: nil, link_description: nil, link_thumbnail_url: nil,
@@ -65,7 +73,7 @@ module OmniSocials
                  hashtag_platforms: nil, pinterest: nil, youtube: nil,
                  instagram: nil, facebook: nil, linkedin: nil,
                  linkedin_page: nil, tiktok: nil, x: nil, bluesky: nil,
-                 mastodon: nil, google_business: nil)
+                 mastodon: nil, google_business: nil, linkedin_poll: nil)
         body = create_body(
           content: content, channels: channels, scheduled_at: scheduled_at,
           media_ids: media_ids, media_urls: media_urls, type: type,
@@ -78,13 +86,14 @@ module OmniSocials
           youtube: youtube, instagram: instagram, facebook: facebook,
           linkedin: linkedin, linkedin_page: linkedin_page, tiktok: tiktok,
           x: x, bluesky: bluesky, mastodon: mastodon,
-          google_business: google_business
+          google_business: google_business, linkedin_poll: linkedin_poll
         )
         @client.request("POST", "/posts/create", json: body)
       end
 
       # POST /posts/create-and-publish - create and publish immediately.
-      # See #create for the "warnings" array on X link posts.
+      # See #create for the "warnings" array and the 402
+      # "x_credits_insufficient" credit gate on X link posts.
       def create_and_publish(content:, channels: nil, media_ids: nil,
                              media_urls: nil, type: nil, source: nil,
                              link_url: nil, link_title: nil, link_description: nil,
@@ -95,7 +104,7 @@ module OmniSocials
                              pinterest: nil, youtube: nil, instagram: nil,
                              facebook: nil, linkedin: nil, linkedin_page: nil,
                              tiktok: nil, x: nil, bluesky: nil, mastodon: nil,
-                             google_business: nil)
+                             google_business: nil, linkedin_poll: nil)
         body = create_body(
           content: content, channels: channels, scheduled_at: nil,
           media_ids: media_ids, media_urls: media_urls, type: type,
@@ -108,7 +117,7 @@ module OmniSocials
           youtube: youtube, instagram: instagram, facebook: facebook,
           linkedin: linkedin, linkedin_page: linkedin_page, tiktok: tiktok,
           x: x, bluesky: bluesky, mastodon: mastodon,
-          google_business: google_business
+          google_business: google_business, linkedin_poll: linkedin_poll
         )
         @client.request("POST", "/posts/create-and-publish", json: body)
       end
@@ -119,12 +128,15 @@ module OmniSocials
       # x: { "thread_parts" => nil } still clears an X thread (reverts the
       # post to single-tweet mode). The same applies to bluesky and mastodon
       # thread parts.
+      #
+      # See #create for the 402 "x_credits_insufficient" credit gate that
+      # can also refuse an update to a scheduled X link post.
       def update(post_id, content: nil, scheduled_at: nil, channels: nil,
                  media_ids: nil, media_urls: nil, type: nil, location_id: nil,
                  collaborators: nil, user_tags: nil, pinterest: nil,
                  youtube: nil, instagram: nil, facebook: nil, linkedin: nil,
                  linkedin_page: nil, tiktok: nil, x: nil, bluesky: nil,
-                 mastodon: nil, google_business: nil)
+                 mastodon: nil, google_business: nil, linkedin_poll: nil)
         body = Internal.drop_nil(
           {
             "content" => content,
@@ -146,7 +158,8 @@ module OmniSocials
             "x" => x,
             "bluesky" => bluesky,
             "mastodon" => mastodon,
-            "google_business" => google_business
+            "google_business" => google_business,
+            "linkedin_poll" => linkedin_poll
           }
         )
         @client.request("PATCH", "/posts/#{post_id}", json: body)
@@ -158,6 +171,8 @@ module OmniSocials
       end
 
       # POST /posts/{id}/publish - publish a draft or scheduled post now.
+      # See #create for the 402 "x_credits_insufficient" credit gate that
+      # can also refuse publishing a scheduled X link post.
       def publish(post_id)
         @client.request("POST", "/posts/#{post_id}/publish")
       end
@@ -182,7 +197,7 @@ module OmniSocials
                       hashtag_set_id:, hashtag_placement:, hashtag_platforms:,
                       pinterest:, youtube:, instagram:, facebook:, linkedin:,
                       linkedin_page:, tiktok:, x:, bluesky:, mastodon:,
-                      google_business:)
+                      google_business:, linkedin_poll:)
         Internal.drop_nil(
           {
             "content" => content,
@@ -213,7 +228,8 @@ module OmniSocials
             "x" => x,
             "bluesky" => bluesky,
             "mastodon" => mastodon,
-            "google_business" => google_business
+            "google_business" => google_business,
+            "linkedin_poll" => linkedin_poll
           }
         )
       end

data/lib/omnisocials/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OmniSocials
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omnisocials
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - OmniSocials
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
+date: 2026-08-20 00:00:00.000000000 Z
 dependencies: []
 description: Schedule and publish social media posts, upload media, and read analytics
   across Instagram, Facebook, LinkedIn, YouTube, TikTok, X, Pinterest, Bluesky, Threads,