omnisocials 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d8e63bac3e6cf2774234d627061b6ef9d2f2555329374da55bc37b2dc912593
-  data.tar.gz: 1f432caac9857e978a539b9382aeb11390a5e02637c97725a84f5b7146f14206
+  metadata.gz: cfdc77673c3c6885b9098af3daf33b7393329ed3b6501fd04d28e813585d97b0
+  data.tar.gz: 9753cf8ccae71e85a0414fa137d1b201f678c8a7a018edacb2a74df4353dc822
 SHA512:
-  metadata.gz: '079b0f69fe85f2317bae07bf58246d49a150d6a5afaed56aac9c4dc3111dfc6713ac250c12591f6f8428923e91003333377b004a6f64fe8eb786660b9fb75eca'
-  data.tar.gz: 5cced0edb928d0b5600a94ca7a28a8c3a809bfc58eee18ef89683c665f04327aee7d215c7982af068144165718e87468b237e698b7d36a273013cb6503df206e
+  metadata.gz: 7d8390a9fb03fb151002f79d55706c43b29506d604fe84a9c4707cbe233166ebaab7ad4d2a552e1db14de26a8eed0e8244879daf148f2f83bf3a83d5fe7d8449
+  data.tar.gz: 0376b9f5a46d25a6cfc9ca718f46ffd45d2cbe1deecdd9430f1bc2ac2b7a45e1299b5b93d54e8dcf3cf98f17f32b379c56eaed9fffb1699aa203493d27d5a4b3

data/README.md

@@ -65,6 +65,24 @@ post = client.posts.create_and_publish(
 )
 ```
 
+### Per-media alt text
+
+Every `media_urls` / `media_ids` entry accepts either a plain String or a Hash with an `alt` accessibility description (max 1500 chars). Alt text is delivered to Mastodon (media description), Bluesky (embed alt), X (photos and GIFs), Pinterest (pin alt text), Instagram (images), and LinkedIn (images). Strings and Hashes can be mixed, and the same shape works in per-platform Hashes and `thread_parts` media.
+
+```ruby
+post = client.posts.create(
+  content: "Sunrise over the harbor",
+  channels: ["mastodon", "bluesky"],
+  scheduled_at: "2026-08-01T09:00:00Z",
+  media_urls: [
+    {
+      "url" => "https://example.com/harbor.jpg",
+      "alt" => "A small sailboat crossing a calm harbor at sunrise, sky in deep orange"
+    }
+  ]
+)
+```
+
 ### Post to specific platforms with platform options
 
 `content` can be a per-platform Hash (with `default` as the fallback), and each platform has its own options Hash:
@@ -107,6 +125,24 @@ post = client.posts.create(
 
 On update, passing `x: { "thread_parts" => nil }` clears the thread and reverts the post to single-tweet mode. Only top-level `nil` values are dropped from request bodies, so nested `nil` values like this one are sent as JSON `null`.
 
+### X link posts use credits
+
+X bills API posts whose text contains a URL at a premium, and OmniSocials passes that fee through as prepaid credits (20 credits per URL-containing tweet; threads billed per part with a link). When a create targets X and the text contains a URL, the response Hash includes a top-level `"warnings"` array (a sibling of `"data"`):
+
+```ruby
+res = client.posts.create(
+  content: "Read the full story: https://example.com/post",
+  channels: ["x"]
+)
+(res["warnings"] || []).each do |warning|
+  if warning["code"] == "x_url_post_credits"
+    puts "#{warning["credits_required"]} credits (balance: #{warning["credits_balance"]})"
+  end
+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.
+
 ### Other post operations
 
 ```ruby
@@ -114,13 +150,18 @@ posts = client.posts.list(status: "scheduled", limit: 50, offset: 0)
 post = client.posts.get("123")
 client.posts.update("123", scheduled_at: "2026-08-02T10:00:00Z")
 client.posts.publish("123")           # publish a draft or scheduled post now
+client.posts.retry("123")             # retry only the failed platforms of a failed/warning post
 client.posts.delete("123")            # returns nil (204)
 
 # Recent posts fetched live from the connected platforms (including content
-# published outside OmniSocials). Requires the analytics:read scope.
+# published outside OmniSocials). Requires the analytics:read scope. Video
+# records include duration_seconds (whole seconds; TikTok and YouTube today,
+# null for images and platforms that don't expose it).
 recent = client.posts.recent_platform(limit: 10, platforms: ["instagram", "tiktok"])
 ```
 
+`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.
+
 ## Media
 
 ### Upload from a URL (recommended, up to 1GB)
@@ -190,6 +231,36 @@ client.folders.update(sub["data"]["id"], parent_id: nil)  # move to top level
 client.folders.delete(folder["data"]["id"])  # files move to root, subfolders move up
 ```
 
+## Hashtag Sets
+
+Save reusable hashtag groups and apply them to posts at create time. Uses the `posts:read` / `posts:write` scopes.
+
+```ruby
+set = client.hashtag_sets.create(
+  name: "Launch",
+  hashtags: ["saas", "buildinpublic", "startup"]  # or one string: "#saas #buildinpublic #startup"
+)
+puts set["data"]["preview"]  # "#saas #buildinpublic #startup"
+
+client.hashtag_sets.list
+client.hashtag_sets.get(set["data"]["id"])
+client.hashtag_sets.update(set["data"]["id"], hashtags: ["saas", "founder"])  # replaces the full list
+client.hashtag_sets.delete(set["data"]["id"])  # returns nil (204)
+```
+
+Apply a set when creating a post with `hashtag_set` (the set name, case-insensitive) or `hashtag_set_id`. The set is applied once at create time and tags already in the caption are skipped. `hashtag_placement` is `"caption_append"` (default) or `"first_comment"`, and `hashtag_platforms` restricts the hashtags to a subset of the post's channels. Instagram's 30-hashtag cap returns error code `hashtag_limit_exceeded`.
+
+```ruby
+client.posts.create(
+  content: "Launch day!",
+  channels: ["instagram", "x"],
+  scheduled_at: "2026-08-01T09:00:00Z",
+  hashtag_set: "Launch",
+  hashtag_placement: "first_comment",
+  hashtag_platforms: ["instagram"]
+)
+```
+
 ## Accounts
 
 ```ruby

data/lib/omnisocials/client.rb

@@ -59,8 +59,8 @@ module OmniSocials
     ].freeze
 
     attr_reader :api_key, :base_url, :timeout, :max_retries,
-                :posts, :media, :folders, :accounts, :analytics, :locations,
-                :webhooks
+                :posts, :media, :folders, :hashtag_sets, :accounts, :analytics,
+                :audio, :locations, :inbox, :webhooks
 
     # api_key     - API key (omsk_live_* / omsk_test_*). Falls back to the
     #               OMNISOCIALS_API_KEY environment variable. Raises
@@ -88,9 +88,12 @@ module OmniSocials
       @posts = Resources::Posts.new(self)
       @media = Resources::Media.new(self)
       @folders = Resources::Folders.new(self)
+      @hashtag_sets = Resources::HashtagSets.new(self)
       @accounts = Resources::Accounts.new(self)
       @analytics = Resources::Analytics.new(self)
+      @audio = Resources::Audio.new(self)
       @locations = Resources::Locations.new(self)
+      @inbox = Resources::Inbox.new(self)
       @webhooks = Resources::Webhooks.new(self)
     end
 

data/lib/omnisocials/resources/audio.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Audio resource: Instagram Reels audio (Meta's licensed catalog).
+    class Audio
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /audio/search?q=&type= - search Meta's licensed audio catalog for
+      # Instagram Reels. Omit query for trending audio; type is "music"
+      # (default) or "original_sound". Use a result's audio_id as
+      # instagram.audio_id on a reel post (with optional
+      # instagram.audio_volume / instagram.video_volume, integers 0-100).
+      # preview_url is a temporary URL (~1.5 days); never persist it.
+      def search(query: nil, type: nil)
+        @client.request("GET", "/audio/search", query: { "q" => query, "type" => type })
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/hashtag_sets.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Hashtag sets resource: saved, reusable hashtag groups applied to posts
+    # at create time (via hashtag_set / hashtag_set_id on posts.create).
+    class HashtagSets
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /hashtag-sets - list the workspace's saved hashtag sets.
+      def list
+        @client.request("GET", "/hashtag-sets")
+      end
+
+      # GET /hashtag-sets/{id} - fetch a single hashtag set.
+      def get(hashtag_set_id)
+        @client.request("GET", "/hashtag-sets/#{hashtag_set_id}")
+      end
+
+      # POST /hashtag-sets - create a hashtag set.
+      #
+      # `hashtags` is an Array of tags, or a single String of tags. Apply the
+      # set on posts.create via hashtag_set (name, case-insensitive) or
+      # hashtag_set_id.
+      def create(name:, hashtags:)
+        @client.request(
+          "POST", "/hashtag-sets",
+          json: { "name" => name, "hashtags" => hashtags }
+        )
+      end
+
+      # PATCH /hashtag-sets/{id} - rename and/or replace the tags.
+      #
+      # `hashtags` replaces the FULL list.
+      def update(hashtag_set_id, name: nil, hashtags: nil)
+        body = Internal.drop_nil({ "name" => name, "hashtags" => hashtags })
+        @client.request("PATCH", "/hashtag-sets/#{hashtag_set_id}", json: body)
+      end
+
+      # DELETE /hashtag-sets/{id} - delete a hashtag set. Returns nil (204).
+      def delete(hashtag_set_id)
+        @client.request("DELETE", "/hashtag-sets/#{hashtag_set_id}")
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/inbox.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module OmniSocials
+  module Resources
+    # Inbox resource: social inbox conversations (DMs, comments, mentions)
+    # across connected platforms, plus reading and replying to them.
+    #
+    # The list endpoints use CURSOR pagination (unlike the offset pagination
+    # elsewhere): each response carries pagination["next_cursor"],
+    # pagination["has_more"], and pagination["limit"]. Page on by passing the
+    # previous response's next_cursor as `cursor` while has_more is true.
+    #
+    # 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").
+    class Inbox
+      def initialize(client)
+        @client = client
+      end
+
+      # 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"]).
+      def list_conversations(platform: nil, type: nil, unread: nil, limit: nil, cursor: nil)
+        @client.request(
+          "GET", "/inbox/conversations",
+          query: {
+            "platform" => platform,
+            "type" => type,
+            "unread" => unread,
+            "limit" => limit,
+            "cursor" => cursor
+          }
+        )
+      end
+
+      # GET /inbox/conversations/{id}/messages - full message thread for one
+      # conversation, newest first. Cursor-paginated via `limit` / `cursor`.
+      def get_messages(conversation_id, limit: nil, cursor: nil)
+        @client.request(
+          "GET", "/inbox/conversations/#{encode_id(conversation_id)}/messages",
+          query: { "limit" => limit, "cursor" => cursor }
+        )
+      end
+
+      # POST /inbox/conversations/{id}/read - mark every message in the
+      # conversation as read. Returns the count of messages newly marked read.
+      def mark_read(conversation_id)
+        @client.request("POST", "/inbox/conversations/#{encode_id(conversation_id)}/read")
+      end
+
+      # POST /inbox/conversations/{id}/reply - send a reply into the
+      # conversation (a DM message, or a reply to the comment/mention).
+      #
+      # `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.
+      def reply(conversation_id, text:, attachment_url: nil, attachment_type: nil)
+        body = Internal.drop_nil(
+          {
+            "text" => text,
+            "attachment_url" => attachment_url,
+            "attachment_type" => attachment_type
+          }
+        )
+        @client.request(
+          "POST", "/inbox/conversations/#{encode_id(conversation_id)}/reply",
+          json: body
+        )
+      end
+
+      private
+
+      # URL-encode a conversation id for use in a path segment. LinkedIn ids
+      # contain ":" and "()", so they must be escaped; spaces become %20
+      # (a path segment treats "+" literally, unlike a query string).
+      def encode_id(conversation_id)
+        CGI.escape(conversation_id.to_s).gsub("+", "%20")
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/posts.rb

@@ -6,6 +6,13 @@ module OmniSocials
     #
     # `content` is a plain String, or a per-platform Hash with a "default" key.
     # `media_ids` / `media_urls` are a flat Array, or a per-platform Hash.
+    # Each entry is a plain String, or a Hash with an "alt" accessibility
+    # description (max 1500 chars): `{ "url" => "https://...", "alt" => "..." }`
+    # for media_urls, `{ "id" => "...", "alt" => "..." }` for media_ids. Alt
+    # text is delivered to Mastodon (media description), Bluesky (embed alt),
+    # X (photos/GIFs), Pinterest (pin alt text), Instagram (images), and
+    # LinkedIn (images); the same entry shape works inside x/bluesky/mastodon
+    # `thread_parts` media.
     class Posts
       def initialize(client)
         @client = client
@@ -36,36 +43,58 @@ module OmniSocials
 
       # POST /posts/create - create a post (draft, or scheduled when
       # scheduled_at is set).
+      #
+      # hashtag_set (set name, case-insensitive) or hashtag_set_id applies a
+      # saved hashtag set once at create time; tags already in a caption are
+      # skipped; Instagram's 30-hashtag cap returns error code
+      # hashtag_limit_exceeded. hashtag_placement is "caption_append"
+      # (default) or "first_comment"; hashtag_platforms restricts the tags to
+      # a subset of channels.
+      #
+      # When the post targets X and its text (or any thread part) contains a
+      # URL, the response includes a top-level "warnings" array (sibling of
+      # "data") with a "x_url_post_credits" entry carrying credits_required
+      # 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.
       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,
                  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)
+                 hashtag_set: nil, hashtag_set_id: nil, hashtag_placement: nil,
+                 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)
         body = create_body(
           content: content, channels: channels, scheduled_at: scheduled_at,
           media_ids: media_ids, media_urls: media_urls, type: type,
           source: source, link_url: link_url, link_title: link_title,
           link_description: link_description, link_thumbnail_url: link_thumbnail_url,
           location_id: location_id, collaborators: collaborators,
-          user_tags: user_tags, pinterest: pinterest, youtube: youtube,
-          instagram: instagram, facebook: facebook, linkedin: linkedin,
-          linkedin_page: linkedin_page, tiktok: tiktok, x: x, bluesky: bluesky,
-          mastodon: mastodon, google_business: google_business
+          user_tags: user_tags, hashtag_set: hashtag_set,
+          hashtag_set_id: hashtag_set_id, hashtag_placement: hashtag_placement,
+          hashtag_platforms: hashtag_platforms, pinterest: pinterest,
+          youtube: youtube, instagram: instagram, facebook: facebook,
+          linkedin: linkedin, linkedin_page: linkedin_page, tiktok: tiktok,
+          x: x, bluesky: bluesky, mastodon: mastodon,
+          google_business: google_business
         )
         @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.
       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,
                              link_thumbnail_url: 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,
+                             collaborators: nil, user_tags: nil,
+                             hashtag_set: nil, hashtag_set_id: nil,
+                             hashtag_placement: nil, 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)
         body = create_body(
           content: content, channels: channels, scheduled_at: nil,
@@ -73,10 +102,13 @@ module OmniSocials
           source: source, link_url: link_url, link_title: link_title,
           link_description: link_description, link_thumbnail_url: link_thumbnail_url,
           location_id: location_id, collaborators: collaborators,
-          user_tags: user_tags, pinterest: pinterest, youtube: youtube,
-          instagram: instagram, facebook: facebook, linkedin: linkedin,
-          linkedin_page: linkedin_page, tiktok: tiktok, x: x, bluesky: bluesky,
-          mastodon: mastodon, google_business: google_business
+          user_tags: user_tags, hashtag_set: hashtag_set,
+          hashtag_set_id: hashtag_set_id, hashtag_placement: hashtag_placement,
+          hashtag_platforms: hashtag_platforms, pinterest: pinterest,
+          youtube: youtube, instagram: instagram, facebook: facebook,
+          linkedin: linkedin, linkedin_page: linkedin_page, tiktok: tiktok,
+          x: x, bluesky: bluesky, mastodon: mastodon,
+          google_business: google_business
         )
         @client.request("POST", "/posts/create-and-publish", json: body)
       end
@@ -130,14 +162,27 @@ module OmniSocials
         @client.request("POST", "/posts/#{post_id}/publish")
       end
 
+      # POST /posts/{id}/retry - retry the failed platforms of a "failed" or
+      # "warning" (partially failed) post, on the same post.
+      #
+      # Only the platforms that failed are re-published; platforms that
+      # already succeeded are never posted again. Asynchronous: a 200 means
+      # the retry is queued - poll `get` for the outcome. Max 3 retries per
+      # platform.
+      def retry(post_id)
+        @client.request("POST", "/posts/#{post_id}/retry")
+      end
+
       private
 
       def create_body(content:, channels:, scheduled_at:, media_ids:,
                       media_urls:, type:, source:, link_url:, link_title:,
                       link_description:, link_thumbnail_url:, location_id:,
-                      collaborators:, user_tags:, pinterest:, youtube:,
-                      instagram:, facebook:, linkedin:, linkedin_page:,
-                      tiktok:, x:, bluesky:, mastodon:, google_business:)
+                      collaborators:, user_tags:, hashtag_set:,
+                      hashtag_set_id:, hashtag_placement:, hashtag_platforms:,
+                      pinterest:, youtube:, instagram:, facebook:, linkedin:,
+                      linkedin_page:, tiktok:, x:, bluesky:, mastodon:,
+                      google_business:)
         Internal.drop_nil(
           {
             "content" => content,
@@ -154,6 +199,10 @@ module OmniSocials
             "location_id" => location_id,
             "collaborators" => collaborators,
             "user_tags" => user_tags,
+            "hashtag_set" => hashtag_set,
+            "hashtag_set_id" => hashtag_set_id,
+            "hashtag_placement" => hashtag_placement,
+            "hashtag_platforms" => hashtag_platforms,
             "pinterest" => pinterest,
             "youtube" => youtube,
             "instagram" => instagram,

data/lib/omnisocials/version.rb

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

data/lib/omnisocials.rb

@@ -19,9 +19,12 @@ require_relative "omnisocials/webhooks"
 require_relative "omnisocials/resources/posts"
 require_relative "omnisocials/resources/media"
 require_relative "omnisocials/resources/folders"
+require_relative "omnisocials/resources/hashtag_sets"
 require_relative "omnisocials/resources/accounts"
 require_relative "omnisocials/resources/analytics"
+require_relative "omnisocials/resources/audio"
 require_relative "omnisocials/resources/locations"
+require_relative "omnisocials/resources/inbox"
 require_relative "omnisocials/resources/webhooks"
 require_relative "omnisocials/client"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omnisocials
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - OmniSocials
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-15 00:00:00.000000000 Z
+date: 2026-08-09 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,
@@ -27,7 +27,10 @@ files:
 - lib/omnisocials/internal.rb
 - lib/omnisocials/resources/accounts.rb
 - lib/omnisocials/resources/analytics.rb
+- lib/omnisocials/resources/audio.rb
 - lib/omnisocials/resources/folders.rb
+- lib/omnisocials/resources/hashtag_sets.rb
+- lib/omnisocials/resources/inbox.rb
 - lib/omnisocials/resources/locations.rb
 - lib/omnisocials/resources/media.rb
 - lib/omnisocials/resources/posts.rb