omnisocials 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d8e63bac3e6cf2774234d627061b6ef9d2f2555329374da55bc37b2dc912593
+  data.tar.gz: 1f432caac9857e978a539b9382aeb11390a5e02637c97725a84f5b7146f14206
+SHA512:
+  metadata.gz: '079b0f69fe85f2317bae07bf58246d49a150d6a5afaed56aac9c4dc3111dfc6713ac250c12591f6f8428923e91003333377b004a6f64fe8eb786660b9fb75eca'
+  data.tar.gz: 5cced0edb928d0b5600a94ca7a28a8c3a809bfc58eee18ef89683c665f04327aee7d215c7982af068144165718e87468b237e698b7d36a273013cb6503df206e

data/README.md

@@ -0,0 +1,373 @@
+# OmniSocials Ruby SDK
+
+The official Ruby client for the [OmniSocials](https://omnisocials.com) Public API. Schedule and publish posts, upload media, and read analytics across Instagram, Facebook, LinkedIn, YouTube, TikTok, X, Pinterest, Bluesky, Threads, Mastodon, and Google Business.
+
+Full API reference: [https://docs.omnisocials.com](https://docs.omnisocials.com)
+
+## Install
+
+```bash
+gem install omnisocials
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "omnisocials"
+```
+
+Requires Ruby 3.0+. Zero runtime dependencies: built entirely on the Ruby standard library (Net::HTTP, OpenSSL, JSON).
+
+## Quickstart
+
+```ruby
+require "omnisocials"
+
+client = OmniSocials::Client.new  # reads OMNISOCIALS_API_KEY from the environment
+post = client.posts.create(content: "Hello from Ruby", channels: ["instagram", "linkedin"])
+puts post["data"]["id"]
+```
+
+## Authentication
+
+Create an API key in the OmniSocials app under **Settings -> API Keys**. Keys look like `omsk_live_...` (or `omsk_test_...` for test keys) and are bound to one workspace.
+
+Pass the key explicitly or set the `OMNISOCIALS_API_KEY` environment variable:
+
+```ruby
+require "omnisocials"
+
+client = OmniSocials::Client.new(api_key: "omsk_live_...")
+# or: export OMNISOCIALS_API_KEY=omsk_live_... and just OmniSocials::Client.new
+```
+
+The client opens a fresh connection per request, so there is nothing to close. All responses are plain Hashes (parsed JSON, string keys), returned exactly as the API sends them.
+
+## Posts
+
+### Schedule a post
+
+```ruby
+post = client.posts.create(
+  content: "Big announcement coming Friday",
+  channels: ["instagram", "facebook", "linkedin"],
+  scheduled_at: "2026-08-01T09:00:00Z",
+  media_urls: ["https://example.com/teaser.jpg"]
+)
+```
+
+Omit `scheduled_at` to create a draft, or use `create_and_publish` to publish immediately:
+
+```ruby
+post = client.posts.create_and_publish(
+  content: "We are live!",
+  channels: ["x", "bluesky"]
+)
+```
+
+### 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:
+
+```ruby
+post = client.posts.create(
+  content: {
+    "default" => "New feature: best times to post",
+    "linkedin" => "We just shipped best times to post. Here is how it works."
+  },
+  channels: ["linkedin", "instagram", "youtube"],
+  media_urls: ["https://example.com/demo.mp4"],
+  scheduled_at: "2026-08-01T09:00:00Z",
+  instagram: { "share_to_feed" => true },
+  youtube: { "title" => "Best times to post, explained", "privacy_status" => "public" }
+)
+```
+
+Note that `linkedin` targets a personal LinkedIn profile and `linkedin_page` targets a LinkedIn company page. Both can be connected to the same workspace and posted to independently.
+
+### X thread example
+
+Pass 2 to 25 `thread_parts` to publish a chained thread instead of a single tweet (each part is at most 280 characters). Bluesky and Mastodon support the same `thread_parts` shape:
+
+```ruby
+post = client.posts.create(
+  content: "How we cut our API response times by 80%",  # fallback text
+  channels: ["x"],
+  scheduled_at: "2026-08-01T15:00:00Z",
+  x: {
+    "thread_parts" => [
+      { "text" => "How we cut our API response times by 80%. A thread:" },
+      { "text" => "1/ We started by profiling every endpoint under real load." },
+      { "text" => "2/ The biggest win: batching analytics reads into one query." },
+      { "text" => "3/ Full write-up on the blog. Thanks for reading!" }
+    ]
+  }
+)
+```
+
+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`.
+
+### Other post operations
+
+```ruby
+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.delete("123")            # returns nil (204)
+
+# Recent posts fetched live from the connected platforms (including content
+# published outside OmniSocials). Requires the analytics:read scope.
+recent = client.posts.recent_platform(limit: 10, platforms: ["instagram", "tiktok"])
+```
+
+## Media
+
+### Upload from a URL (recommended, up to 1GB)
+
+```ruby
+media = client.media.upload_from_url(
+  url: "https://example.com/promo.mp4",
+  name: "promo-august",
+  folder: "Campaigns"
+)
+media_id = media["data"]["id"]
+```
+
+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.
+
+### Upload a local file (multipart, max 100MB)
+
+```ruby
+media = client.media.upload(file: "/path/to/image.jpg", name: "hero-shot")
+```
+
+`file` accepts a file path (String or Pathname), an IO (`File.open("...", "rb")`, StringIO), or raw bytes as a binary-encoded String (e.g. from `File.binread`).
+
+Uploading a PDF splits it into image slides (max 20 pages) and returns `slides` plus a `media_ids` array. Pass all of `media_ids`, in order, to `posts.create` to publish the deck as a carousel (a native swipeable document on LinkedIn, an image carousel elsewhere).
+
+Every upload response also includes a `compatibility` block listing any connected platforms that would reject the file.
+
+### Other media operations
+
+```ruby
+files = client.media.list(search: "promo", folder_id: "42")
+item = client.media.get("1001")
+client.media.update("1001", name: "renamed", folder_id: "42")
+client.media.update("1001", folder_id: nil)   # move to the root ("All media")
+client.media.delete("1001")
+
+# Base64 upload (handy when you have bytes but no URL)
+client.media.upload_from_base64(data: b64_string, mime_type: "image/png")
+
+# Preflight compatibility BEFORE uploading
+result = client.media.check(url: "https://example.com/huge.mp4")
+puts result["summary"] unless result["compatible"]
+```
+
+Note the difference between omitting `folder_id` (leave the folder unchanged) and passing `folder_id: nil` (move the file to the root). The same applies to `parent_id` on `folders.update`.
+
+### Large file uploads with a presigned URL
+
+`create_upload_url` mints a one-time upload URL so any environment (a CI job, a sandbox, a script without the SDK) can upload a file without auth headers:
+
+```ruby
+grant = client.media.create_upload_url
+# grant contains: upload_url, upload_token, expires_in_seconds (600),
+# method ("POST"), content_type ("multipart/form-data")
+```
+
+POST the file to `grant["upload_url"]` as multipart form data (field name `file`) with no auth headers. The token is single-use and expires after 10 minutes. The response JSON contains the created media item with its `id` (or a `media_ids` array for a PDF).
+
+## Folders
+
+```ruby
+folders = client.folders.list
+folder = client.folders.create(name: "Campaigns")
+sub = client.folders.create(name: "August", parent_id: folder["data"]["id"])
+client.folders.update(sub["data"]["id"], name: "August 2026")
+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
+```
+
+## Accounts
+
+```ruby
+accounts = client.accounts.list
+accounts["data"].each do |account|
+  puts "#{account["platform"]}: #{account["username"]}"
+end
+
+account = client.accounts.get("instagram")
+```
+
+## Analytics
+
+```ruby
+# One post
+stats = client.analytics.post("123")
+
+# Up to 100 posts in one request (avoids rate limit trouble when syncing)
+bulk = client.analytics.posts(["123", "124", "125"])
+
+# Workspace overview
+overview = client.analytics.overview(period: "30d")
+
+# Account-level stats (followers etc.)
+accounts = client.analytics.accounts(platform: "instagram")
+```
+
+### Best times to post
+
+```ruby
+best = client.analytics.best_times(platform: "instagram", timezone: "Europe/Amsterdam")
+best["data"]["best_times"].each { |slot| puts slot }
+```
+
+## Locations (Instagram place tagging)
+
+```ruby
+results = client.locations.search("Blue Bottle Coffee Oakland")
+location_id = results["data"][0]["id"]
+client.locations.validate(location_id)
+
+client.posts.create(
+  content: "Great coffee here",
+  channels: ["instagram"],
+  media_urls: ["https://example.com/latte.jpg"],
+  location_id: location_id
+)
+```
+
+## Webhooks
+
+Subscribe to `post.scheduled`, `post.published`, and `post.failed` events:
+
+```ruby
+webhook = client.webhooks.create(
+  url: "https://example.com/hooks/omnisocials",
+  events: ["post.published", "post.failed"]
+)
+secret = webhook["data"]["secret"]  # only shown once, store it
+
+client.webhooks.list
+client.webhooks.get(webhook["data"]["id"])
+client.webhooks.update(webhook["data"]["id"], is_active: false)
+client.webhooks.rotate_secret(webhook["data"]["id"])  # new secret, shown once
+client.webhooks.delete(webhook["data"]["id"])
+```
+
+### Verifying webhook signatures (Rails example)
+
+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):
+
+```ruby
+class OmnisocialsWebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    payload = request.body.read  # raw body, exactly as received
+    signature = request.headers["X-OmniSocials-Signature"]
+
+    begin
+      event = OmniSocials::Webhooks.verify(
+        payload: payload,
+        signature: signature,
+        secret: ENV.fetch("OMNISOCIALS_WEBHOOK_SECRET"),
+        tolerance: 300
+      )
+    rescue OmniSocials::WebhookVerificationError
+      return head :bad_request
+    end
+
+    if event["type"] == "post.published"
+      event["data"]["targets"].each do |target|
+        Rails.logger.info "#{target["platform"]} #{target["status"]} #{target["native_post_id"]}"
+      end
+    end
+
+    head :ok
+  end
+end
+```
+
+### Verifying webhook signatures (plain Rack)
+
+```ruby
+# config.ru
+require "omnisocials"
+
+app = lambda do |env|
+  request = Rack::Request.new(env)
+  payload = request.body.read
+  signature = env["HTTP_X_OMNISOCIALS_SIGNATURE"]
+
+  begin
+    event = OmniSocials::Webhooks.verify(
+      payload: payload,
+      signature: signature,
+      secret: ENV.fetch("OMNISOCIALS_WEBHOOK_SECRET")
+    )
+  rescue OmniSocials::WebhookVerificationError
+    next [400, { "content-type" => "application/json" }, ['{"error":"invalid signature"}']]
+  end
+
+  # handle event["type"] ...
+  [200, { "content-type" => "application/json" }, ['{"ok":true}']]
+end
+
+run app
+```
+
+`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.
+
+## Error handling
+
+Non-2xx responses raise typed exceptions with `status`, `code`, `message`, and the parsed `body`:
+
+```ruby
+begin
+  client.posts.get("does-not-exist")
+rescue OmniSocials::NotFoundError => e
+  puts "Gone: #{e.code} #{e.message}"
+rescue OmniSocials::RateLimitError => e
+  puts "Slow down, retry in #{e.retry_after}s"
+rescue OmniSocials::ValidationError => e
+  puts "Bad request: #{e.body}"
+rescue OmniSocials::AuthenticationError
+  puts "Check your API key"
+rescue OmniSocials::APIConnectionError
+  puts "Network problem"
+rescue OmniSocials::APIError => e
+  puts "API error: #{e.status} #{e.message}"
+end
+```
+
+The full hierarchy: `OmniSocials::Error` is the base; `OmniSocials::APIError` covers all HTTP errors with subclasses `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ValidationError` (400/422), `RateLimitError` (429, with `#retry_after`), and `ServerError` (5xx); `APIConnectionError` covers network failures; `WebhookVerificationError` covers signature failures.
+
+## Rate limits
+
+The API allows **100 requests per minute** per API key. Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. On 429 the SDK automatically waits for the `Retry-After` value and retries. When syncing analytics for many posts, prefer the bulk `client.analytics.posts([...])` endpoint (100 posts per request) over per-post calls.
+
+## Retries and timeouts
+
+The SDK automatically retries on 429, 5xx, and connection errors with exponential backoff (0.5s, 1s, 2s, with jitter), honoring the `Retry-After` header when present. Other 4xx errors are never retried. Defaults: 2 retries, 30 second timeout. Both are configurable:
+
+```ruby
+client = OmniSocials::Client.new(
+  api_key: "omsk_live_...",
+  timeout: 60,        # seconds
+  max_retries: 5,     # retries after the first attempt
+  base_url: "https://api.omnisocials.com/v1"  # override for testing
+)
+```
+
+## More
+
+- Full API reference and guides: [https://docs.omnisocials.com](https://docs.omnisocials.com)
+- MCP server for AI agents: `npx -y @omnisocials/mcp-server`
+- Agent skills CLI: `npx skills add OmniSocials/omnisocials-agent-skills`
+
+## License
+
+MIT

data/lib/omnisocials/client.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "time"
+require "uri"
+
+module OmniSocials
+  # Synchronous client for the OmniSocials Public API.
+  #
+  #   require "omnisocials"
+  #
+  #   client = OmniSocials::Client.new  # reads OMNISOCIALS_API_KEY from env
+  #   # or: OmniSocials::Client.new(api_key: "omsk_live_...", base_url: ...,
+  #   #                             timeout: ..., max_retries: ...)
+  #
+  #   post = client.posts.create(
+  #     content: "Hello from the SDK",
+  #     channels: ["instagram", "linkedin"],
+  #     scheduled_at: "2026-08-01T09:00:00Z"
+  #   )
+  #
+  # Zero runtime dependencies: built on Net::HTTP, OpenSSL, and JSON from the
+  # Ruby standard library. A fresh connection is opened per request, so there
+  # is nothing to close.
+  class Client
+    DEFAULT_BASE_URL = "https://api.omnisocials.com/v1"
+    DEFAULT_TIMEOUT = 30.0
+    DEFAULT_MAX_RETRIES = 2
+    USER_AGENT = "omnisocials-ruby/#{VERSION}"
+
+    # Statuses that are retried automatically (alongside connection errors).
+    RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+
+    METHOD_CLASSES = {
+      "GET" => Net::HTTP::Get,
+      "POST" => Net::HTTP::Post,
+      "PATCH" => Net::HTTP::Patch,
+      "DELETE" => Net::HTTP::Delete
+    }.freeze
+
+    CONNECTION_ERRORS = [
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::EHOSTUNREACH,
+      Errno::ENETUNREACH,
+      Errno::EPIPE,
+      Errno::ETIMEDOUT,
+      SocketError,
+      EOFError,
+      IOError,
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      Net::WriteTimeout,
+      OpenSSL::SSL::SSLError,
+      Timeout::Error
+    ].freeze
+
+    attr_reader :api_key, :base_url, :timeout, :max_retries,
+                :posts, :media, :folders, :accounts, :analytics, :locations,
+                :webhooks
+
+    # api_key     - API key (omsk_live_* / omsk_test_*). Falls back to the
+    #               OMNISOCIALS_API_KEY environment variable. Raises
+    #               OmniSocials::AuthenticationError when neither is set.
+    # base_url    - API base URL (default https://api.omnisocials.com/v1).
+    # timeout     - per-request timeout in seconds (default 30).
+    # max_retries - automatic retries after the first attempt (default 2),
+    #               applied on 429, 5xx, and connection errors.
+    def initialize(api_key: nil, base_url: nil, timeout: DEFAULT_TIMEOUT,
+                   max_retries: DEFAULT_MAX_RETRIES)
+      key = api_key.nil? || api_key.to_s.empty? ? ENV["OMNISOCIALS_API_KEY"] : api_key
+      if key.nil? || key.to_s.empty?
+        raise AuthenticationError.new(
+          "No API key provided. Pass api_key: ... to OmniSocials::Client.new " \
+          "or set the OMNISOCIALS_API_KEY environment variable. Create a key " \
+          "in the OmniSocials app under Settings -> API Keys.",
+          status: nil
+        )
+      end
+      @api_key = key
+      @base_url = (base_url || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+      @timeout = Float(timeout)
+      @max_retries = [max_retries.to_i, 0].max
+
+      @posts = Resources::Posts.new(self)
+      @media = Resources::Media.new(self)
+      @folders = Resources::Folders.new(self)
+      @accounts = Resources::Accounts.new(self)
+      @analytics = Resources::Analytics.new(self)
+      @locations = Resources::Locations.new(self)
+      @webhooks = Resources::Webhooks.new(self)
+    end
+
+    # GET /health - API health check (no scopes required).
+    def health
+      request("GET", "/health")
+    end
+
+    # Perform an HTTP request against the API with automatic retries.
+    #
+    # Returns the parsed response body (Hash/Array) as-is, the raw text for
+    # non-JSON responses, or nil for 204. Raises an OmniSocials::APIError
+    # subclass on non-2xx and OmniSocials::APIConnectionError when no
+    # response was ever received.
+    def request(method, path, query: nil, json: nil, multipart: nil)
+      uri = build_uri(path, query)
+      last_error = nil
+
+      (max_retries + 1).times do |attempt|
+        begin
+          response = perform(method, uri, json: json, multipart: multipart)
+        rescue *CONNECTION_ERRORS => e
+          last_error = e
+          break if attempt >= max_retries
+
+          sleep(Internal.backoff_delay(attempt, nil))
+          next
+        end
+
+        should_retry, retry_after = retry_info(response)
+        if should_retry && attempt < max_retries
+          sleep(Internal.backoff_delay(attempt, retry_after))
+          next
+        end
+        return handle_response(response)
+      end
+
+      raise APIConnectionError,
+            "Connection error while requesting #{method} #{uri}: " \
+            "#{last_error.class}: #{last_error.message}"
+    end
+
+    private
+
+    def build_uri(path, query)
+      uri = URI.parse("#{base_url}#{path}")
+      pairs = Internal.serialize_query(query)
+      uri.query = URI.encode_www_form(pairs) if pairs
+      uri
+    end
+
+    def perform(method, uri, json:, multipart:)
+      request_class = METHOD_CLASSES.fetch(method) do
+        raise ArgumentError, "Unsupported HTTP method: #{method}"
+      end
+      req = request_class.new(uri)
+      req["Authorization"] = "Bearer #{api_key}"
+      req["User-Agent"] = USER_AGENT
+      req["Accept"] = "application/json"
+
+      if json
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(json)
+      elsif multipart
+        boundary = "----OmniSocialsRuby#{SecureRandom.hex(16)}"
+        req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+        req.body = Internal.multipart_body(
+          boundary, multipart[:fields] || {}, multipart[:filename], multipart[:data]
+        )
+      end
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout
+      http.start { |conn| conn.request(req) }
+    end
+
+    def retry_info(response)
+      status = response.code.to_i
+      if RETRY_STATUSES.include?(status) || status >= 500
+        [true, parse_retry_after(response, Internal.parse_body(response.body))]
+      else
+        [false, nil]
+      end
+    end
+
+    def handle_response(response)
+      status = response.code.to_i
+      return nil if status == 204
+      return Internal.parse_body(response.body) if status >= 200 && status < 300
+
+      raise error_from_response(response)
+    end
+
+    def error_from_response(response)
+      body = Internal.parse_body(response.body)
+      status = response.code.to_i
+
+      code = nil
+      message = "Request failed with status #{status}."
+      if body.is_a?(Hash)
+        error = body["error"]
+        if error.is_a?(Hash)
+          code = error["code"] if error["code"].is_a?(String)
+          message = error["message"] if error["message"].is_a?(String)
+        elsif body["message"].is_a?(String)
+          message = body["message"]
+        end
+      end
+
+      case status
+      when 401
+        AuthenticationError.new(message, status: status, code: code, body: body)
+      when 403
+        PermissionDeniedError.new(message, status: status, code: code, body: body)
+      when 404
+        NotFoundError.new(message, status: status, code: code, body: body)
+      when 400, 422
+        ValidationError.new(message, status: status, code: code, body: body)
+      when 429
+        RateLimitError.new(
+          message,
+          status: status, code: code, body: body,
+          retry_after: parse_retry_after(response, body)
+        )
+      else
+        if status >= 500
+          ServerError.new(message, status: status, code: code, body: body)
+        else
+          APIError.new(message, status: status, code: code, body: body)
+        end
+      end
+    end
+
+    def parse_retry_after(response, body)
+      header = response["retry-after"]
+      if header
+        stripped = header.strip
+        return [stripped.to_f, 0.0].max if stripped.match?(/\A-?\d+(\.\d+)?\z/)
+
+        begin
+          return [Time.httpdate(stripped) - Time.now, 0.0].max
+        rescue ArgumentError
+          # Not an HTTP-date either; fall through to the body.
+        end
+      end
+      if body.is_a?(Hash) && body["retry_after"].is_a?(Numeric)
+        return [body["retry_after"].to_f, 0.0].max
+      end
+
+      nil
+    end
+  end
+end