socialstats-ruby-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9913c6eb0102ad42654410100eb2a33fe967ee4d99d0e831b9d34e34b7a02c95
+  data.tar.gz: 6585f4e2b0bae1eee06e6e8a6aba82124efb9f10495f92a00fc8635f2055f707
+SHA512:
+  metadata.gz: ca3e3dc6d29ac228a25383015048592efed8a66591e864670cd967f4e16ab340c639552b4c39c53b9250199ec6ff4b9ba401de8f470fcd4368d8a5b33adf869c
+  data.tar.gz: df8cf7c971eec6f6225d6ae5a4dd896a9256e7ace3fef6e75654f7cee6a5aba8b186157758421f916e04f7c9dbbb31fe550ea1d514797b17b02ee9fc4cd910f2

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.1.0] - 2026-06-25
+
+### Added
+
+- Initial standalone Ruby SDK repo for Socialstats Enterprise API (`/enterprise/v1`)
+- Resource coverage:
+  - `info`
+  - `creators`
+  - `posts`
+- Shared HTTP client with:
+  - `apikey` header auth
+  - JSON response decoding
+  - retry/backoff on transport errors and retryable status codes
+- Structured exception types for API and transport failures
+- Route coverage audit doc mapping Rails routes to SDK methods

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Songstats
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,136 @@
+# Socialstats Ruby SDK
+
+Official Ruby client for the **Socialstats Enterprise API**.
+
+RubyGems: https://rubygems.org/gems/socialstats-ruby-sdk  
+API Documentation: https://docs.socialstats.com  
+API Key Access: Please contact api@socialstats.com
+
+---
+
+## Requirements
+
+- Ruby >= 3.2
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+    gem "socialstats-ruby-sdk"
+
+Then install:
+
+    bundle install
+
+Or install directly via RubyGems:
+
+    gem install socialstats-ruby-sdk
+
+---
+
+## Quick Start
+
+    require "socialstats_sdk"
+
+    client = SocialstatsSDK::Client.new(
+      api_key: ENV["SOCIALSTATS_API_KEY"]
+    )
+
+    # API status
+    status = client.info.status
+
+    # Creator information
+    creator = client.creators.info(
+      socialstats_creator_id: "d3rvjgk2"
+    )
+
+    # Creator statistics
+    creator_stats = client.creators.stats(
+      socialstats_creator_id: "d3rvjgk2",
+      source: "instagram"
+    )
+
+    # Post statistics
+    post_stats = client.posts.stats(
+      socialstats_creator_id: "d3rvjgk2",
+      source_id: "tiktok",
+      post_id: "7654234001833610518"
+    )
+
+---
+
+## Authentication
+
+All requests include your API key in the `apikey` header.
+
+You can generate an API key in your Socialstats Enterprise dashboard.
+
+We recommend storing your key securely in environment variables:
+
+    export SOCIALSTATS_API_KEY=your_key_here
+
+---
+
+## Available Resource Clients
+
+- `client.info`
+- `client.creators`
+- `client.posts`
+
+Info endpoints:
+- `client.info.sources` -> `/sources`
+- `client.info.status` -> `/status`
+- `client.info.definitions` -> `/definitions`
+
+Creator endpoints:
+- `client.creators.info(...)` -> `/creators/info`
+- `client.creators.stats(...)` -> `/creators/stats`
+- `client.creators.historic_stats(...)` -> `/creators/historic_stats`
+- `client.creators.audience(...)` -> `/creators/audience`
+- `client.creators.audience_details(country_code: ..., ...)` -> `/creators/audience/details`
+- `client.creators.activities(...)` -> `/creators/activities`
+- `client.creators.content(...)` -> `/creators/content`
+- `client.creators.top_posts(...)` -> `/creators/top_posts`
+- `client.creators.search(q: ..., ...)` -> `/creators/search`
+- `client.creators.add_link_request(link: ..., ...)` -> `/creators/link_request`
+- `client.creators.remove_link_request(link: ..., ...)` -> `/creators/link_request`
+
+Post endpoints:
+- `client.posts.stats(...)` -> `/posts/stats`
+- `client.posts.historic_stats(...)` -> `/posts/historic_stats`
+
+---
+
+## Error Handling
+
+    begin
+      client.creators.info(socialstats_creator_id: "invalid")
+    rescue SocialstatsSDK::SocialstatsAPIError => e
+      puts "API error: #{e.message}"
+    rescue SocialstatsSDK::SocialstatsTransportError => e
+      puts "Transport error: #{e.message}"
+    end
+
+---
+
+## Development
+
+To work on the SDK locally:
+
+    git clone https://github.com/songstats/socialstats-ruby-sdk.git
+    cd socialstats-ruby-sdk
+    bundle install
+
+---
+
+## Versioning
+
+This SDK follows Semantic Versioning (SemVer).
+
+---
+
+## License
+
+MIT

data/docs/enterprise_routes_audit.md

@@ -0,0 +1,43 @@
+# Enterprise Routes Audit (Socialstats Rails -> Ruby SDK)
+
+Audited against:
+
+- `/Users/Oskar/1001tl/config/routes.rb`
+- `/Users/Oskar/1001tl/app/controllers/enterprise/v1/creators_controller.rb`
+- `/Users/Oskar/1001tl/app/controllers/enterprise/v1/info_controller.rb`
+- `/Users/Oskar/1001tl/app/controllers/enterprise/v1/enterprise_base_controller.rb`
+- `/Users/Oskar/1001tl/docs/socialstats_openapi.yaml`
+
+Authentication observed in Rails: `apikey` request header.
+
+## `/enterprise/v1/info`
+
+| HTTP | Route           | SDK Method                 |
+| ---- | --------------- | -------------------------- |
+| GET  | `/sources`      | `client.info.sources`      |
+| GET  | `/status`       | `client.info.status`       |
+| GET  | `/uptime_check` | `client.info.uptime_check` |
+| GET  | `/definitions`  | `client.info.definitions`  |
+
+## `/enterprise/v1/creators`
+
+| HTTP   | Route               | SDK Method                                                 |
+| ------ | ------------------- | ---------------------------------------------------------- |
+| GET    | `/info`             | `client.creators.info(...)`                                |
+| GET    | `/stats`            | `client.creators.stats(...)`                               |
+| GET    | `/historic_stats`   | `client.creators.historic_stats(...)`                      |
+| GET    | `/audience`         | `client.creators.audience(...)`                            |
+| GET    | `/audience/details` | `client.creators.audience_details(country_code: ..., ...)` |
+| GET    | `/activities`       | `client.creators.activities(...)`                          |
+| GET    | `/content`          | `client.creators.content(...)`                             |
+| GET    | `/top_posts`        | `client.creators.top_posts(...)`                           |
+| GET    | `/search`           | `client.creators.search(q: ..., ...)`                      |
+| POST   | `/link_request`     | `client.creators.add_link_request(link: ..., ...)`         |
+| DELETE | `/link_request`     | `client.creators.remove_link_request(link: ..., ...)`      |
+
+## `/enterprise/v1/posts`
+
+| HTTP | Route             | SDK Method                         |
+| ---- | ----------------- | ---------------------------------- |
+| GET  | `/stats`          | `client.posts.stats(...)`          |
+| GET  | `/historic_stats` | `client.posts.historic_stats(...)` |

data/lib/socialstats_sdk/client.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SocialstatsSDK
+  class Client
+    attr_reader :info, :creators, :posts
+
+    def initialize(api_key:, base_url: HTTPClient::DEFAULT_BASE_URL, timeout: HTTPClient::DEFAULT_TIMEOUT_SECONDS,
+      max_retries: 2, http_adapter: nil, user_agent: nil)
+      @http = HTTPClient.new(
+        api_key: api_key,
+        base_url: base_url,
+        timeout: timeout,
+        max_retries: max_retries,
+        adapter: http_adapter,
+        user_agent: user_agent
+      )
+
+      @info = Resources::Info.new(@http)
+      @creators = Resources::Creators.new(@http)
+      @posts = Resources::Posts.new(@http)
+    end
+
+    def close
+      @http.close
+    end
+  end
+end

data/lib/socialstats_sdk/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SocialstatsSDK
+  class SocialstatsError < StandardError; end
+
+  class SocialstatsTransportError < SocialstatsError; end
+
+  class SocialstatsAPIError < SocialstatsError
+    attr_reader :status_code, :payload
+
+    def initialize(message:, status_code:, payload: nil)
+      @error_message = message
+      super(@error_message)
+      @status_code = status_code
+      @payload = payload
+    end
+
+    def to_s
+      "Socialstats API error (#{status_code}): #{@error_message}"
+    end
+  end
+end

data/lib/socialstats_sdk/http_client.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module SocialstatsSDK
+  HTTPResponse = Struct.new(:status, :body, :headers, keyword_init: true)
+
+  class NetHTTPAdapter
+    METHOD_MAP = {
+      get: Net::HTTP::Get,
+      post: Net::HTTP::Post,
+      delete: Net::HTTP::Delete
+    }.freeze
+
+    def request(method:, base_url:, path:, headers:, params:, json:, timeout:)
+      uri = URI.join("#{base_url.chomp('/')}/", path.delete_prefix('/'))
+      query = URI.encode_www_form(params || {})
+      uri.query = [uri.query, query].compact.reject(&:empty?).join("&") unless query.empty?
+
+      request_class = METHOD_MAP.fetch(method.to_sym) { raise ArgumentError, "Unsupported HTTP method: #{method}" }
+      request = request_class.new(uri)
+      headers.each { |key, value| request[key] = value unless value.nil? }
+
+      if json
+        request["content-type"] ||= "application/json"
+        request.body = JSON.generate(json)
+      end
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+
+      response = http.request(request)
+      HTTPResponse.new(status: response.code.to_i, body: response.body.to_s, headers: response.to_hash)
+    end
+  end
+
+  class HTTPClient
+    DEFAULT_BASE_URL = "https://api.socialstats.com"
+    DEFAULT_TIMEOUT_SECONDS = 30
+    RETRYABLE_STATUS_CODES = [429, 500, 502, 503, 504].freeze
+    RETRYABLE_EXCEPTIONS = [
+      EOFError,
+      IOError,
+      SocketError,
+      Timeout::Error,
+      Errno::ECONNRESET,
+      Errno::ECONNREFUSED,
+      Errno::ETIMEDOUT,
+      Net::OpenTimeout,
+      Net::ReadTimeout
+    ].freeze
+
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT_SECONDS, max_retries: 2, adapter: nil,
+      user_agent: nil)
+      raise ArgumentError, "api_key is required" if api_key.to_s.empty?
+      raise ArgumentError, "max_retries must be >= 0" if max_retries.to_i.negative?
+
+      @api_key = api_key
+      @base_url = base_url
+      @timeout = timeout
+      @max_retries = max_retries.to_i
+      @adapter = adapter || NetHTTPAdapter.new
+      @user_agent = user_agent || "socialstats-ruby-sdk/#{VERSION}"
+    end
+
+    def close
+      @adapter.close if @adapter.respond_to?(:close)
+    end
+
+    def request(method, path, params: nil, json: nil)
+      endpoint = "/enterprise/v1/#{path.to_s.delete_prefix('/')}"
+      attempts = 0
+
+      loop do
+        begin
+          response = @adapter.request(
+            method: method.to_sym,
+            base_url: @base_url,
+            path: endpoint,
+            headers: request_headers,
+            params: params,
+            json: json,
+            timeout: @timeout
+          )
+        rescue *RETRYABLE_EXCEPTIONS => e
+          if attempts < @max_retries
+            sleep(backoff_seconds(attempts))
+            attempts += 1
+            next
+          end
+          raise SocialstatsTransportError, e.message
+        end
+
+        if RETRYABLE_STATUS_CODES.include?(response.status) && attempts < @max_retries
+          sleep(backoff_seconds(attempts))
+          attempts += 1
+          next
+        end
+
+        return decode_response(response.body) if response.status.between?(200, 299)
+
+        raise build_api_error(response)
+      end
+    end
+
+    private
+
+    def request_headers
+      {
+        "apikey" => @api_key,
+        "accept" => "application/json",
+        "user-agent" => @user_agent
+      }
+    end
+
+    def backoff_seconds(attempt)
+      0.2 * (2**attempt)
+    end
+
+    def decode_response(body)
+      return nil if body.nil? || body.strip.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      { "raw" => body }
+    end
+
+    def build_api_error(response)
+      payload = decode_response(response.body)
+      message = "HTTP #{response.status}"
+
+      if payload.is_a?(Hash)
+        message = payload["message"] || payload["error"] || message
+      end
+
+      SocialstatsAPIError.new(message: message, status_code: response.status, payload: payload)
+    end
+  end
+end

data/lib/socialstats_sdk/resources/base.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SocialstatsSDK
+  module Resources
+    class Base
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      private
+
+      def get(path, params: nil)
+        @http.request(:get, path, params: normalize_params(params))
+      end
+
+      def post(path, params: nil, json: nil)
+        @http.request(:post, path, params: normalize_params(params), json: normalize_params(json))
+      end
+
+      def delete(path, params: nil)
+        @http.request(:delete, path, params: normalize_params(params))
+      end
+
+      def normalize_params(params)
+        return nil if params.blank?
+
+        normalized = {}
+        params.each do |key, value|
+          next if value.nil?
+
+          normalized[key] = case value
+          when true then "true"
+          when false then "false"
+          when Array then value.map(&:to_s).join(",")
+          else value
+          end
+        end
+
+        normalized.empty? ? nil : normalized
+      end
+
+      def require_any_identifier!(params, identifier_keys)
+        has_identifier = identifier_keys.any? do |key|
+          value = params[key]
+          !value.nil? && value != ""
+        end
+        return if has_identifier
+
+        raise ArgumentError, "One identifier is required. Supported keys: #{identifier_keys.join(', ')}"
+      end
+    end
+  end
+end

data/lib/socialstats_sdk/resources/creators.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module SocialstatsSDK
+  module Resources
+    class Creators < Base
+      IDENTIFIER_KEYS = %i[socialstats_creator_id].freeze
+
+      def info(**params)
+        get("creators/info", params: with_identifier(params))
+      end
+
+      def stats(**params)
+        get("creators/stats", params: with_identifier(params))
+      end
+
+      def historic_stats(**params)
+        get("creators/historic_stats", params: with_identifier(params))
+      end
+
+      def audience(**params)
+        get("creators/audience", params: with_identifier(params))
+      end
+
+      def audience_details(country_code:, **params)
+        raise ArgumentError, "country_code is required" if country_code.to_s.empty?
+
+        query = with_identifier(params)
+        query[:country_code] = country_code
+        get("creators/audience/details", params: query)
+      end
+
+      def activities(**params)
+        get("creators/activities", params: with_identifier(params))
+      end
+
+      def content(**params)
+        get("creators/content", params: with_identifier(params))
+      end
+
+      def top_posts(**params)
+        get("creators/top_posts", params: with_identifier(params))
+      end
+
+      def search(q:, **params)
+        raise ArgumentError, "q is required" if q.to_s.empty?
+
+        get("creators/search", params: params.merge(q: q))
+      end
+
+      def add_link_request(link:, **params)
+        raise ArgumentError, "link is required" if link.to_s.empty?
+
+        query = with_identifier(params)
+        query[:link] = link
+        post("creators/link_request", params: query)
+      end
+
+      def remove_link_request(link:, **params)
+        raise ArgumentError, "link is required" if link.to_s.empty?
+
+        query = with_identifier(params)
+        query[:link] = link
+        delete("creators/link_request", params: query)
+      end
+
+      private
+
+      def with_identifier(params)
+        query = params.dup
+        require_any_identifier!(query, IDENTIFIER_KEYS)
+        query
+      end
+    end
+  end
+end

data/lib/socialstats_sdk/resources/info.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SocialstatsSDK
+  module Resources
+    class Info < Base
+      def sources
+        get("sources")
+      end
+
+      def status
+        get("status")
+      end
+
+      def uptime_check
+        get("uptime_check")
+      end
+
+      def definitions
+        get("definitions")
+      end
+    end
+  end
+end

data/lib/socialstats_sdk/resources/posts.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module SocialstatsSDK
+  module Resources
+    class Posts < Base
+      CREATOR_IDENTIFIER_KEYS = %i[socialstats_creator_id].freeze
+      POST_IDENTIFIER_KEYS = %i[post_id id_unique external_id].freeze
+
+      def stats(source_id:, **params)
+        get("posts/stats", params: with_post_identifier(params.merge(source_id: source_id)))
+      end
+
+      def historic_stats(source_id:, **params)
+        get("posts/historic_stats", params: with_post_identifier(params.merge(source_id: source_id)))
+      end
+
+      private
+
+      def with_post_identifier(params)
+        query = params.dup
+        raise ArgumentError, "source_id is required" if query[:source_id].to_s.empty?
+
+        require_any_identifier!(query, CREATOR_IDENTIFIER_KEYS)
+        require_any_identifier!(query, POST_IDENTIFIER_KEYS)
+        query
+      end
+    end
+  end
+end

data/lib/socialstats_sdk/resources.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "resources/base"
+require_relative "resources/info"
+require_relative "resources/creators"
+require_relative "resources/posts"

data/lib/socialstats_sdk/version.rb

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

data/lib/socialstats_sdk.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "socialstats_sdk/version"
+require_relative "socialstats_sdk/errors"
+require "active_support/core_ext/object/blank"
+require_relative "socialstats_sdk/http_client"
+require_relative "socialstats_sdk/resources"
+require_relative "socialstats_sdk/client"

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: socialstats-ruby-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Songstats
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: Typed Ruby client for Socialstats Enterprise API resources.
+email:
+- api@socialstats.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/enterprise_routes_audit.md
+- lib/socialstats_sdk.rb
+- lib/socialstats_sdk/client.rb
+- lib/socialstats_sdk/errors.rb
+- lib/socialstats_sdk/http_client.rb
+- lib/socialstats_sdk/resources.rb
+- lib/socialstats_sdk/resources/base.rb
+- lib/socialstats_sdk/resources/creators.rb
+- lib/socialstats_sdk/resources/info.rb
+- lib/socialstats_sdk/resources/posts.rb
+- lib/socialstats_sdk/version.rb
+homepage: https://socialstats.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://socialstats.com
+  source_code_uri: https://github.com/songstats/socialstats-ruby-sdk
+  bug_tracker_uri: https://github.com/songstats/socialstats-ruby-sdk/issues
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.17
+signing_key:
+specification_version: 4
+summary: Ruby SDK for the Socialstats Enterprise API.
+test_files: []