omnisocials 0.1.0

data/lib/omnisocials/errors.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  # Error hierarchy for the OmniSocials SDK.
+  #
+  #   OmniSocials::Error (base)
+  #     OmniSocials::APIError (has #status, #code, #message, #body)
+  #       OmniSocials::AuthenticationError (401)
+  #       OmniSocials::PermissionDeniedError (403)
+  #       OmniSocials::NotFoundError (404)
+  #       OmniSocials::ValidationError (400 / 422)
+  #       OmniSocials::RateLimitError (429, exposes #retry_after seconds when known)
+  #       OmniSocials::ServerError (>= 500)
+  #     OmniSocials::APIConnectionError (network failure / timeout)
+  #     OmniSocials::WebhookVerificationError
+
+  # Base class for every error raised by this SDK.
+  class Error < StandardError; end
+
+  # A non-2xx response from the OmniSocials API.
+  #
+  # Attributes:
+  #   status - HTTP status code (nil for client-side failures such as a
+  #            missing API key at construction time).
+  #   code   - machine-readable error code from the API body
+  #            ({"error" => {"code" => ..., "message" => ...}}) when present.
+  #   body   - the parsed response body (Hash) when the response was JSON,
+  #            otherwise the raw response text, or nil.
+  class APIError < Error
+    attr_reader :status, :code, :body
+
+    def initialize(message, status: nil, code: nil, body: nil)
+      super(message)
+      @status = status
+      @code = code
+      @body = body
+    end
+  end
+
+  # 401 - missing or invalid API key.
+  class AuthenticationError < APIError; end
+
+  # 403 - the API key lacks the required scope.
+  class PermissionDeniedError < APIError; end
+
+  # 404 - the requested resource does not exist.
+  class NotFoundError < APIError; end
+
+  # 400 / 422 - the request was malformed or failed validation.
+  class ValidationError < APIError; end
+
+  # 429 - rate limit exceeded (100 requests per minute).
+  #
+  # #retry_after is the number of seconds to wait before retrying, taken from
+  # the Retry-After header (or the body's retry_after field) when present.
+  class RateLimitError < APIError
+    attr_reader :retry_after
+
+    def initialize(message, status: 429, code: nil, body: nil, retry_after: nil)
+      super(message, status: status, code: code, body: body)
+      @retry_after = retry_after
+    end
+  end
+
+  # >= 500 - something went wrong on OmniSocials' side.
+  class ServerError < APIError; end
+
+  # The request never got a response (network failure or timeout).
+  class APIConnectionError < Error
+    def initialize(message = "Connection error.")
+      super
+    end
+  end
+
+  # Webhook signature verification failed.
+  class WebhookVerificationError < Error; end
+end

data/lib/omnisocials/internal.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+module OmniSocials
+  # Sentinel distinguishing "omitted" from an explicit nil.
+  #
+  # A few endpoints treat null as meaningful (for example
+  # media.update(folder_id: nil) moves a file to the root folder), so nil
+  # cannot double as "not provided" there. Use OmniSocials::NOT_GIVEN as the
+  # default for those parameters.
+  class NotGiven
+    def inspect
+      "NOT_GIVEN"
+    end
+    alias to_s inspect
+  end
+
+  NOT_GIVEN = NotGiven.new.freeze
+
+  # Internal helpers shared by the client core and the resource classes.
+  # Not part of the public API.
+  module Internal
+    MAX_BACKOFF_SECONDS = 8.0
+
+    class << self
+      # Drop nil and NOT_GIVEN values (top level only).
+      #
+      # Nested values are passed through untouched, so platform option hashes
+      # can still carry meaningful nils (e.g. x: { "thread_parts" => nil } on
+      # update clears an X thread).
+      def drop_nil(hash)
+        hash.reject { |_key, value| value.nil? || value.is_a?(NotGiven) }
+      end
+
+      # Join an array into a comma-separated string; pass strings through.
+      def join_list(value)
+        return nil if value.nil?
+        return value if value.is_a?(String)
+
+        value.map(&:to_s).join(",")
+      end
+
+      # Stringify query params, dropping nil/NOT_GIVEN values.
+      def serialize_query(params)
+        return nil if params.nil? || params.empty?
+
+        out = {}
+        params.each do |key, value|
+          next if value.nil? || value.is_a?(NotGiven)
+
+          out[key.to_s] =
+            case value
+            when true then "true"
+            when false then "false"
+            else value.to_s
+            end
+        end
+        out.empty? ? nil : out
+      end
+
+      # Parse a response body as JSON, falling back to the raw text.
+      def parse_body(raw)
+        return nil if raw.nil? || raw.empty?
+
+        begin
+          JSON.parse(raw)
+        rescue JSON::ParserError
+          raw
+        end
+      end
+
+      # Delay before retry number +attempt+ (0-based): 0.5s, 1s, 2s... + jitter.
+      #
+      # An explicit Retry-After from the server wins over the computed backoff.
+      def backoff_delay(attempt, retry_after)
+        return [retry_after, 60.0].min unless retry_after.nil?
+
+        delay = [0.5 * (2**attempt), MAX_BACKOFF_SECONDS].min
+        delay * (0.75 + rand * 0.5)
+      end
+
+      # Normalize the +file+ argument to [filename, binary_data].
+      #
+      # Accepts:
+      # - an IO / File / StringIO (anything responding to #read)
+      # - a file path (a String or Pathname)
+      # - raw bytes (a binary-encoded String, e.g. from File.binread)
+      #
+      # The content is read fully into memory so automatic retries can resend it.
+      def coerce_file(file, filename)
+        case file
+        when Pathname
+          path = file.to_s
+          return [filename || File.basename(path), File.binread(path)]
+        when String
+          # A binary-encoded String is treated as raw bytes; any other String
+          # is treated as a file path (mirrors the Python SDK where str = path).
+          return [filename || "upload", file] if file.encoding == Encoding::BINARY
+
+          return [filename || File.basename(file), File.binread(file)]
+        end
+
+        if file.respond_to?(:read)
+          data = file.read.to_s.b
+          inferred = file.respond_to?(:path) ? file.path : nil
+          resolved = filename
+          resolved ||= File.basename(inferred) if inferred.is_a?(String) && !inferred.empty?
+          return [resolved || "upload", data]
+        end
+
+        raise ArgumentError,
+              "file must be an IO, a file path (String or Pathname), or raw bytes " \
+              "(a binary-encoded String, e.g. from File.binread); got #{file.class}."
+      end
+
+      # Build a multipart/form-data body (single file part named "file" plus
+      # optional plain form fields), hand-rolled so the SDK stays dependency-free.
+      def multipart_body(boundary, fields, filename, data)
+        body = String.new(encoding: Encoding::BINARY)
+        fields.each do |name, value|
+          body << "--#{boundary}\r\n".b
+          body << "Content-Disposition: form-data; name=\"#{name}\"\r\n\r\n".b
+          body << value.to_s.b
+          body << "\r\n".b
+        end
+        safe_name = filename.to_s.gsub('"', "%22").gsub(/[\r\n]/, " ")
+        body << "--#{boundary}\r\n".b
+        body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{safe_name}\"\r\n".b
+        body << "Content-Type: application/octet-stream\r\n\r\n".b
+        body << data.to_s.b
+        body << "\r\n--#{boundary}--\r\n".b
+        body
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/accounts.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Accounts resource: connected social accounts for the API key's workspace.
+    class Accounts
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /accounts - list connected social accounts.
+      #
+      # The response also carries workspace_id and workspace_name for the
+      # workspace the API key belongs to.
+      def list
+        @client.request("GET", "/accounts")
+      end
+
+      # GET /accounts/{id} - fetch a single connected account.
+      def get(account_id)
+        @client.request("GET", "/accounts/#{account_id}")
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/analytics.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Analytics resource: post stats, account stats, overview, and best times.
+    class Analytics
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /analytics/posts/{id} - latest per-platform metrics for one post.
+      def post(post_id)
+        @client.request("GET", "/analytics/posts/#{post_id}")
+      end
+
+      # GET /analytics/posts?ids=a,b,c - bulk metrics for up to 100 posts in
+      # one request. `ids` is an Array of post ids (or an already-joined
+      # comma-separated String).
+      def posts(ids)
+        @client.request(
+          "GET", "/analytics/posts",
+          query: { "ids" => Internal.join_list(ids) }
+        )
+      end
+
+      # GET /analytics/overview - workspace-wide analytics overview.
+      def overview(period: nil, start_date: nil, end_date: nil)
+        @client.request(
+          "GET", "/analytics/overview",
+          query: { "period" => period, "start_date" => start_date, "end_date" => end_date }
+        )
+      end
+
+      # GET /analytics/accounts - account-level stats (followers etc.).
+      def accounts(platform: nil, date: nil)
+        @client.request(
+          "GET", "/analytics/accounts",
+          query: { "platform" => platform, "date" => date }
+        )
+      end
+
+      # GET /analytics/best-times - best times to post for a platform,
+      # derived from the workspace's own engagement history.
+      def best_times(platform:, timezone: nil)
+        @client.request(
+          "GET", "/analytics/best-times",
+          query: { "platform" => platform, "timezone" => timezone }
+        )
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/folders.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Folders resource: organize media library files into folders.
+    class Folders
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /folders - list media folders (with per-folder file counts).
+      def list
+        @client.request("GET", "/folders")
+      end
+
+      # POST /folders - create a folder (optionally nested under parent_id).
+      def create(name:, parent_id: nil)
+        body = Internal.drop_nil({ "name" => name, "parent_id" => parent_id })
+        @client.request("POST", "/folders", json: body)
+      end
+
+      # PATCH /folders/{id} - rename and/or move a folder.
+      #
+      # Pass parent_id: nil explicitly to move the folder to the top level;
+      # omit it to leave the parent unchanged.
+      def update(folder_id, name: nil, parent_id: OmniSocials::NOT_GIVEN)
+        body = Internal.drop_nil({ "name" => name })
+        body["parent_id"] = parent_id unless parent_id.is_a?(NotGiven)
+        @client.request("PATCH", "/folders/#{folder_id}", json: body)
+      end
+
+      # DELETE /folders/{id} - delete a folder. Returns nil (204).
+      #
+      # The folder's media is NOT deleted: files move to the root and
+      # subfolders move up to the deleted folder's parent.
+      def delete(folder_id)
+        @client.request("DELETE", "/folders/#{folder_id}")
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/locations.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Locations resource: Instagram place tagging (search + validate).
+    class Locations
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /locations/search?q= - search Facebook place pages usable as an
+      # Instagram location_id.
+      def search(q)
+        @client.request("GET", "/locations/search", query: { "q" => q })
+      end
+
+      # GET /locations/validate?id= - validate a location id before attaching
+      # it to a post.
+      def validate(id)
+        @client.request("GET", "/locations/validate", query: { "id" => id })
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/media.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Media resource: upload, list, check, rename/move, and delete library files.
+    class Media
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /media - list library files.
+      def list(limit: nil, offset: nil, search: nil, folder_id: nil)
+        @client.request(
+          "GET", "/media",
+          query: {
+            "limit" => limit,
+            "offset" => offset,
+            "search" => search,
+            "folder_id" => folder_id
+          }
+        )
+      end
+
+      # GET /media/{id} - fetch a single library file.
+      def get(media_id)
+        @client.request("GET", "/media/#{media_id}")
+      end
+
+      # POST /media/upload - multipart upload (max 100MB inline).
+      #
+      # `file` is an IO, a file path (String or Pathname), or raw bytes (a
+      # binary-encoded String, e.g. from File.binread).
+      #
+      # A PDF is split into image slides and the response carries `slides`
+      # plus a `media_ids` array instead of a single `data` item. For files
+      # over 100MB use upload_from_url (up to 1GB) or the create_upload_url
+      # presigned flow.
+      def upload(file:, filename: nil, name: nil, folder: nil, folder_id: nil)
+        upload_name, data = Internal.coerce_file(file, filename)
+        fields = Internal.drop_nil(
+          { "name" => name, "folder" => folder, "folder_id" => folder_id }
+        )
+        @client.request(
+          "POST", "/media/upload",
+          multipart: { fields: fields, filename: upload_name, data: data }
+        )
+      end
+
+      # POST /media/upload-from-url - server-side fetch, up to 1GB.
+      #
+      # Files over 100MB are streamed in the background: the response has
+      # data["status"] == "processing"; poll get() until it is "ready".
+      def upload_from_url(url:, filename: nil, name: nil, folder: nil, folder_id: nil)
+        body = Internal.drop_nil(
+          {
+            "url" => url,
+            "filename" => filename,
+            "name" => name,
+            "folder" => folder,
+            "folder_id" => folder_id
+          }
+        )
+        @client.request("POST", "/media/upload-from-url", json: body)
+      end
+
+      # POST /media/upload-from-base64 - upload base64-encoded data (without
+      # a data URI prefix).
+      def upload_from_base64(data:, mime_type:, filename: nil, name: nil,
+                             folder: nil, folder_id: nil)
+        body = Internal.drop_nil(
+          {
+            "data" => data,
+            "mime_type" => mime_type,
+            "filename" => filename,
+            "name" => name,
+            "folder" => folder,
+            "folder_id" => folder_id
+          }
+        )
+        @client.request("POST", "/media/upload-from-base64", json: body)
+      end
+
+      # POST /media/create-upload-url - mint a one-time presigned URL.
+      #
+      # Returns {"upload_url", "upload_token", "expires_in_seconds", ...}.
+      # POST the file to upload_url as multipart form data (field name "file")
+      # with NO auth headers; the token in the URL authenticates the single
+      # upload and expires after 10 minutes.
+      def create_upload_url
+        @client.request("POST", "/media/create-upload-url")
+      end
+
+      # POST /media/check - preflight platform compatibility.
+      #
+      # Provide one of: a public `url`, an existing `media_id`, or
+      # `size_bytes` + `mime`.
+      def check(url: nil, media_id: nil, size_bytes: nil, mime: nil)
+        body = Internal.drop_nil(
+          {
+            "url" => url,
+            "media_id" => media_id,
+            "size_bytes" => size_bytes,
+            "mime" => mime
+          }
+        )
+        @client.request("POST", "/media/check", json: body)
+      end
+
+      # PATCH /media/{id} - rename and/or move a file.
+      #
+      # Pass folder_id: nil explicitly to move the file to the root
+      # ("All media"); omit it to leave the folder unchanged.
+      def update(media_id, name: nil, folder_id: OmniSocials::NOT_GIVEN)
+        body = Internal.drop_nil({ "name" => name })
+        body["folder_id"] = folder_id unless folder_id.is_a?(NotGiven)
+        @client.request("PATCH", "/media/#{media_id}", json: body)
+      end
+
+      # DELETE /media/{id} - delete a file. Returns nil (204).
+      #
+      # Fails with 409 media_in_use if the file is attached to a scheduled or
+      # publishing post.
+      def delete(media_id)
+        @client.request("DELETE", "/media/#{media_id}")
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/posts.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Posts resource: create, schedule, publish, update, and list posts.
+    #
+    # `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.
+    class Posts
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /posts - list posts (status: draft, scheduled, posted, failed).
+      def list(status: nil, limit: nil, offset: nil)
+        @client.request(
+          "GET", "/posts",
+          query: { "status" => status, "limit" => limit, "offset" => offset }
+        )
+      end
+
+      # GET /posts/{id} - fetch a single post.
+      def get(post_id)
+        @client.request("GET", "/posts/#{post_id}")
+      end
+
+      # GET /posts/recent-platform - recent posts fetched live from the
+      # connected platform APIs (including content published outside
+      # OmniSocials). Requires the analytics:read scope.
+      def recent_platform(limit: nil, platforms: nil)
+        @client.request(
+          "GET", "/posts/recent-platform",
+          query: { "limit" => limit, "platforms" => Internal.join_list(platforms) }
+        )
+      end
+
+      # POST /posts/create - create a post (draft, or scheduled when
+      # scheduled_at is set).
+      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)
+        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
+        )
+        @client.request("POST", "/posts/create", json: body)
+      end
+
+      # POST /posts/create-and-publish - create and publish immediately.
+      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,
+                             google_business: nil)
+        body = create_body(
+          content: content, channels: channels, scheduled_at: nil,
+          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
+        )
+        @client.request("POST", "/posts/create-and-publish", json: body)
+      end
+
+      # PATCH /posts/{id} - update a draft or scheduled post.
+      #
+      # Only top-level nils are dropped from the body, so passing e.g.
+      # 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.
+      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)
+        body = Internal.drop_nil(
+          {
+            "content" => content,
+            "scheduled_at" => scheduled_at,
+            "channels" => channels,
+            "media_ids" => media_ids,
+            "media_urls" => media_urls,
+            "type" => type,
+            "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
+          }
+        )
+        @client.request("PATCH", "/posts/#{post_id}", json: body)
+      end
+
+      # DELETE /posts/{id} - delete a post. Returns nil (204).
+      def delete(post_id)
+        @client.request("DELETE", "/posts/#{post_id}")
+      end
+
+      # POST /posts/{id}/publish - publish a draft or scheduled post now.
+      def publish(post_id)
+        @client.request("POST", "/posts/#{post_id}/publish")
+      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:)
+        Internal.drop_nil(
+          {
+            "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
+          }
+        )
+      end
+    end
+  end
+end