songstats-ruby-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e9cfa8f372c183dcde82286fa023415c8fb16b62c7f78652eef43d1128adaca
+  data.tar.gz: 995c45f1acab79d840ce4a899577ba4a964284f3ceb5ce72b75bb221e120e22e
+SHA512:
+  metadata.gz: bbf2f0293a3b15963723911ee7679c464d4eb96bdd71468ccfd4e3fb3508021b297aa219252f90fcbf24381b2d2892ec2f423ad3bb4f0d3546342debac10dfeb
+  data.tar.gz: e66e21ea1532cd8e0cc8fe6f350af45cd506df7a267a6c79a1a158338727805beeef8a83a0308dabad043d9185f707b232f8649468319d560be645c401f0a0f3

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.1.0] - 2026-02-19
+
+### Added
+- Initial standalone Ruby SDK repo for Songstats Enterprise API (`/enterprise/v1`)
+- Full resource coverage:
+  - `info`
+  - `tracks`
+  - `artists`
+  - `collaborators`
+  - `labels`
+  - `charts`
+  - `stations`
+- 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
+- Test suite covering route mapping, header auth, validation, and error handling
+- GitHub Actions CI workflow (`bundle exec rake test`)
+- GitHub Actions release workflow for tag-based gem publishing (`v*`)

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,55 @@
+# Songstats Ruby SDK
+
+Official Ruby Client SDK for the Songstats Enterprise API.
+
+## API Documentation
+
+https://docs.songstats.com
+
+## Install
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+For local usage in another project:
+
+```ruby
+gem "songstats-ruby-sdk", path: "/path/to/songstats-ruby-sdk"
+```
+
+## Quick Start
+
+```ruby
+require "songstats_sdk"
+
+client = SongstatsSDK::Client.new(api_key: "YOUR_API_KEY")
+
+status = client.info.status
+track = client.tracks.info(songstats_track_id: "abcd1234")
+artist_stats = client.artists.stats(songstats_artist_id: "abcd1234", source: "spotify")
+```
+
+## Authentication
+
+The SDK sends your key in the `apikey` header, matching Songstats enterprise auth.
+
+## Included Resource Clients
+
+- `client.info`
+- `client.tracks`
+- `client.artists`
+- `client.collaborators`
+- `client.labels`
+- `client.charts`
+- `client.stations`
+
+## Error Handling
+
+- `SongstatsSDK::SongstatsAPIError`: non-2xx HTTP response
+- `SongstatsSDK::SongstatsTransportError`: transport/connectivity failure
+
+## Route Coverage Audit
+
+See `docs/enterprise_routes_audit.md` for the Rails route to SDK method mapping.

data/docs/enterprise_routes_audit.md

@@ -0,0 +1,118 @@
+# Enterprise Routes Audit (Songstats Rails -> Ruby SDK)
+
+Audited against:
+- `/Users/Oskar/1001tl/config/routes.rb`
+- `/Users/Oskar/1001tl/app/controllers/enterprise/v1/*.rb`
+- `/Users/Oskar/1001tl/app/helpers/enterprise_helper.rb`
+
+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/tracks`
+
+| HTTP | Route | SDK Method |
+|---|---|---|
+| GET | `/info` | `client.tracks.info(...)` |
+| GET | `/stats` | `client.tracks.stats(...)` |
+| GET | `/historic_stats` | `client.tracks.historic_stats(...)` |
+| GET | `/search` | `client.tracks.search(q: ..., ...)` |
+| GET | `/activities` | `client.tracks.activities(...)` |
+| GET | `/comments` | `client.tracks.comments(...)` |
+| GET | `/songshare` | `client.tracks.songshare(...)` |
+| GET | `/locations` | `client.tracks.locations(...)` |
+| POST | `/link_request` | `client.tracks.add_link_request(link: ..., ...)` |
+| DELETE | `/link_request` | `client.tracks.remove_link_request(link: ..., ...)` |
+| POST | `/add_to_member_relevant_list` | `client.tracks.add_to_member_relevant_list(...)` |
+| DELETE | `/remove_from_member_relevant_list` | `client.tracks.remove_from_member_relevant_list(...)` |
+
+## `/enterprise/v1/charts`
+
+| HTTP | Route | SDK Method |
+|---|---|---|
+| GET | `/tracks` | `client.charts.tracks(country_code: ..., ...)` |
+
+## `/enterprise/v1/stations`
+
+| HTTP | Route | SDK Method |
+|---|---|---|
+| POST | `/station_request` | `client.stations.station_request(...)` |
+
+## `/enterprise/v1/artists`
+
+| HTTP | Route | SDK Method |
+|---|---|---|
+| GET | `/info` | `client.artists.info(...)` |
+| GET | `/stats` | `client.artists.stats(...)` |
+| GET | `/historic_stats` | `client.artists.historic_stats(...)` |
+| GET | `/audience` | `client.artists.audience(...)` |
+| GET | `/audience/details` | `client.artists.audience_details(country_code: ..., ...)` |
+| GET | `/catalog` | `client.artists.catalog(...)` |
+| GET | `/search` | `client.artists.search(q: ..., ...)` |
+| GET | `/activities` | `client.artists.activities(...)` |
+| GET | `/songshare` | `client.artists.songshare(...)` |
+| GET | `/top_tracks` | `client.artists.top_tracks(...)` |
+| GET | `/top_playlists` | `client.artists.top_playlists(...)` |
+| GET | `/top_curators` | `client.artists.top_curators(...)` |
+| GET | `/top_commentors` | `client.artists.top_commentors(...)` |
+| POST | `/link_request` | `client.artists.add_link_request(link: ..., ...)` |
+| DELETE | `/link_request` | `client.artists.remove_link_request(link: ..., ...)` |
+| POST | `/track_request` | `client.artists.add_track_request(...)` |
+| DELETE | `/track_request` | `client.artists.remove_track_request(...)` |
+| POST | `/add_to_member_relevant_list` | `client.artists.add_to_member_relevant_list(...)` |
+| DELETE | `/remove_from_member_relevant_list` | `client.artists.remove_from_member_relevant_list(...)` |
+
+## `/enterprise/v1/collaborators`
+
+| HTTP | Route | SDK Method |
+|---|---|---|
+| GET | `/info` | `client.collaborators.info(...)` |
+| GET | `/stats` | `client.collaborators.stats(...)` |
+| GET | `/historic_stats` | `client.collaborators.historic_stats(...)` |
+| GET | `/audience` | `client.collaborators.audience(...)` |
+| GET | `/audience/details` | `client.collaborators.audience_details(country_code: ..., ...)` |
+| GET | `/catalog` | `client.collaborators.catalog(...)` |
+| GET | `/search` | `client.collaborators.search(q: ..., ...)` |
+| GET | `/activities` | `client.collaborators.activities(...)` |
+| GET | `/songshare` | `client.collaborators.songshare(...)` |
+| GET | `/top_tracks` | `client.collaborators.top_tracks(...)` |
+| GET | `/top_playlists` | `client.collaborators.top_playlists(...)` |
+| GET | `/top_curators` | `client.collaborators.top_curators(...)` |
+| GET | `/top_commentors` | `client.collaborators.top_commentors(...)` |
+| POST | `/link_request` | `client.collaborators.add_link_request(link: ..., ...)` |
+| DELETE | `/link_request` | `client.collaborators.remove_link_request(link: ..., ...)` |
+| POST | `/track_request` | `client.collaborators.add_track_request(...)` |
+| DELETE | `/track_request` | `client.collaborators.remove_track_request(...)` |
+| POST | `/add_to_member_relevant_list` | `client.collaborators.add_to_member_relevant_list(...)` |
+| DELETE | `/remove_from_member_relevant_list` | `client.collaborators.remove_from_member_relevant_list(...)` |
+
+## `/enterprise/v1/labels`
+
+| HTTP | Route | SDK Method |
+|---|---|---|
+| GET | `/info` | `client.labels.info(...)` |
+| GET | `/stats` | `client.labels.stats(...)` |
+| GET | `/historic_stats` | `client.labels.historic_stats(...)` |
+| GET | `/audience` | `client.labels.audience(...)` |
+| GET | `/audience/details` | `client.labels.audience_details(country_code: ..., ...)` |
+| GET | `/catalog` | `client.labels.catalog(...)` |
+| GET | `/search` | `client.labels.search(q: ..., ...)` |
+| GET | `/activities` | `client.labels.activities(...)` |
+| GET | `/songshare` | `client.labels.songshare(...)` |
+| GET | `/top_tracks` | `client.labels.top_tracks(...)` |
+| GET | `/top_playlists` | `client.labels.top_playlists(...)` |
+| GET | `/top_curators` | `client.labels.top_curators(...)` |
+| GET | `/top_commentors` | `client.labels.top_commentors(...)` |
+| POST | `/link_request` | `client.labels.add_link_request(link: ..., ...)` |
+| DELETE | `/link_request` | `client.labels.remove_link_request(link: ..., ...)` |
+| POST | `/track_request` | `client.labels.add_track_request(...)` |
+| DELETE | `/track_request` | `client.labels.remove_track_request(...)` |
+| POST | `/add_to_member_relevant_list` | `client.labels.add_to_member_relevant_list(...)` |
+| DELETE | `/remove_from_member_relevant_list` | `client.labels.remove_from_member_relevant_list(...)` |

data/lib/songstats_sdk/client.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SongstatsSDK
+  class Client
+    attr_reader :info, :tracks, :artists, :collaborators, :labels, :charts, :stations
+
+    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)
+      @tracks = Resources::Tracks.new(@http)
+      @artists = Resources::Artists.new(@http)
+      @collaborators = Resources::Collaborators.new(@http)
+      @labels = Resources::Labels.new(@http)
+      @charts = Resources::Charts.new(@http)
+      @stations = Resources::Stations.new(@http)
+    end
+
+    def close
+      @http.close
+    end
+  end
+end

data/lib/songstats_sdk/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SongstatsSDK
+  class SongstatsError < StandardError; end
+
+  class SongstatsTransportError < SongstatsError; end
+
+  class SongstatsAPIError < SongstatsError
+    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
+      "Songstats API error (#{status_code}): #{@error_message}"
+    end
+  end
+end

data/lib/songstats_sdk/http_client.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module SongstatsSDK
+  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.sub(%r{\A/}, ""))
+      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://data.songstats.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 || "songstats-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.sub(%r{\A/}, "")}"
+      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 SongstatsTransportError, 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
+
+      SongstatsAPIError.new(message: message, status_code: response.status, payload: payload)
+    end
+  end
+end

data/lib/songstats_sdk/resources/base.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SongstatsSDK
+  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.nil? || params.empty?
+
+        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/songstats_sdk/resources/charts.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SongstatsSDK
+  module Resources
+    class Charts < Base
+      def tracks(country_code:, source: nil, **params)
+        raise ArgumentError, "country_code is required" if country_code.to_s.empty?
+
+        query = { country_code: country_code, source: source }.merge(params)
+        get("charts/tracks", params: query)
+      end
+    end
+  end
+end

data/lib/songstats_sdk/resources/entities.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module SongstatsSDK
+  module Resources
+    class Entity < Base
+      def initialize(http_client, resource:, identifier_keys:)
+        super(http_client)
+        @resource = resource
+        @identifier_keys = identifier_keys
+      end
+
+      def info(**params)
+        get("#{@resource}/info", params: with_identifier(params))
+      end
+
+      def stats(**params)
+        get("#{@resource}/stats", params: with_identifier(params))
+      end
+
+      def historic_stats(**params)
+        get("#{@resource}/historic_stats", params: with_identifier(params))
+      end
+
+      def audience(**params)
+        get("#{@resource}/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("#{@resource}/audience/details", params: query)
+      end
+
+      def catalog(**params)
+        get("#{@resource}/catalog", params: with_identifier(params))
+      end
+
+      def search(q:, **params)
+        raise ArgumentError, "q is required" if q.to_s.empty?
+
+        get("#{@resource}/search", params: params.merge(q: q))
+      end
+
+      def activities(**params)
+        get("#{@resource}/activities", params: with_identifier(params))
+      end
+
+      def songshare(**params)
+        get("#{@resource}/songshare", params: with_identifier(params))
+      end
+
+      def top_tracks(**params)
+        get("#{@resource}/top_tracks", params: with_identifier(params))
+      end
+
+      def top_playlists(**params)
+        get("#{@resource}/top_playlists", params: with_identifier(params))
+      end
+
+      def top_curators(**params)
+        get("#{@resource}/top_curators", params: with_identifier(params))
+      end
+
+      def top_commentors(**params)
+        get("#{@resource}/top_commentors", params: with_identifier(params))
+      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("#{@resource}/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("#{@resource}/link_request", params: query)
+      end
+
+      def add_track_request(link: nil, spotify_track_id: nil, isrc: nil, **params)
+        if [link, spotify_track_id, isrc].all? { |value| value.to_s.empty? }
+          raise ArgumentError, "One of link, spotify_track_id, or isrc is required"
+        end
+
+        query = with_identifier(params)
+        query[:link] = link
+        query[:spotify_track_id] = spotify_track_id
+        query[:isrc] = isrc
+        post("#{@resource}/track_request", params: query)
+      end
+
+      def remove_track_request(songstats_track_id: nil, spotify_track_id: nil, **params)
+        if [songstats_track_id, spotify_track_id].all? { |value| value.to_s.empty? }
+          raise ArgumentError, "songstats_track_id or spotify_track_id is required"
+        end
+
+        query = with_identifier(params)
+        query[:songstats_track_id] = songstats_track_id
+        query[:spotify_track_id] = spotify_track_id
+        delete("#{@resource}/track_request", params: query)
+      end
+
+      def add_to_member_relevant_list(**params)
+        post("#{@resource}/add_to_member_relevant_list", params: with_identifier(params))
+      end
+
+      def remove_from_member_relevant_list(**params)
+        delete("#{@resource}/remove_from_member_relevant_list", params: with_identifier(params))
+      end
+
+      private
+
+      def with_identifier(params)
+        query = params.dup
+        require_any_identifier!(query, @identifier_keys)
+        query
+      end
+    end
+
+    class Artists < Entity
+      def initialize(http_client)
+        super(
+          http_client,
+          resource: "artists",
+          identifier_keys: %i[songstats_artist_id spotify_artist_id apple_music_artist_id]
+        )
+      end
+    end
+
+    class Collaborators < Entity
+      def initialize(http_client)
+        super(
+          http_client,
+          resource: "collaborators",
+          identifier_keys: %i[songstats_collaborator_id spotify_artist_id apple_music_artist_id tidal_artist_id]
+        )
+      end
+    end
+
+    class Labels < Entity
+      def initialize(http_client)
+        super(
+          http_client,
+          resource: "labels",
+          identifier_keys: %i[songstats_label_id beatport_label_id]
+        )
+      end
+    end
+  end
+end

data/lib/songstats_sdk/resources/info.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SongstatsSDK
+  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/songstats_sdk/resources/stations.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module SongstatsSDK
+  module Resources
+    class Stations < Base
+      def station_request(radio_type:, name:, country_code:, website:, stream_url: nil, city_name: nil, frequency: nil,
+        contact: nil, comment: nil, **extra)
+        raise ArgumentError, "radio_type is required" if radio_type.to_s.empty?
+        raise ArgumentError, "name is required" if name.to_s.empty?
+        raise ArgumentError, "country_code is required" if country_code.to_s.empty?
+        raise ArgumentError, "website is required" if website.to_s.empty?
+
+        payload = {
+          radio_type: radio_type,
+          name: name,
+          country_code: country_code,
+          website: website,
+          stream_url: stream_url,
+          city_name: city_name,
+          frequency: frequency,
+          contact: contact,
+          comment: comment
+        }.merge(extra)
+
+        post("stations/station_request", json: payload)
+      end
+    end
+  end
+end

data/lib/songstats_sdk/resources/tracks.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module SongstatsSDK
+  module Resources
+    class Tracks < Base
+      IDENTIFIER_KEYS = %i[songstats_track_id spotify_track_id apple_music_track_id isrc].freeze
+
+      def info(**params)
+        get("tracks/info", params: with_identifier(params))
+      end
+
+      def stats(**params)
+        get("tracks/stats", params: with_identifier(params))
+      end
+
+      def historic_stats(**params)
+        get("tracks/historic_stats", params: with_identifier(params))
+      end
+
+      def activities(**params)
+        get("tracks/activities", params: with_identifier(params))
+      end
+
+      def comments(**params)
+        get("tracks/comments", params: with_identifier(params))
+      end
+
+      def songshare(**params)
+        get("tracks/songshare", params: with_identifier(params))
+      end
+
+      def locations(**params)
+        get("tracks/locations", params: with_identifier(params))
+      end
+
+      def search(q:, **params)
+        raise ArgumentError, "q is required" if q.to_s.empty?
+
+        get("tracks/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("tracks/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("tracks/link_request", params: query)
+      end
+
+      def add_to_member_relevant_list(**params)
+        post("tracks/add_to_member_relevant_list", params: with_identifier(params))
+      end
+
+      def remove_from_member_relevant_list(**params)
+        delete("tracks/remove_from_member_relevant_list", params: with_identifier(params))
+      end
+
+      private
+
+      def with_identifier(params)
+        query = params.dup
+        require_any_identifier!(query, IDENTIFIER_KEYS)
+        query
+      end
+    end
+  end
+end

data/lib/songstats_sdk/resources.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "resources/base"
+require_relative "resources/info"
+require_relative "resources/tracks"
+require_relative "resources/entities"
+require_relative "resources/charts"
+require_relative "resources/stations"

data/lib/songstats_sdk/version.rb

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

data/lib/songstats_sdk.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "songstats_sdk/version"
+require_relative "songstats_sdk/errors"
+require_relative "songstats_sdk/http_client"
+require_relative "songstats_sdk/resources"
+require_relative "songstats_sdk/client"

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: songstats-ruby-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Songstats
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-19 00:00:00.000000000 Z
+dependencies: []
+description: Typed Ruby client covering all /enterprise/v1 Songstats API routes.
+email:
+- api@songstats.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/enterprise_routes_audit.md
+- lib/songstats_sdk.rb
+- lib/songstats_sdk/client.rb
+- lib/songstats_sdk/errors.rb
+- lib/songstats_sdk/http_client.rb
+- lib/songstats_sdk/resources.rb
+- lib/songstats_sdk/resources/base.rb
+- lib/songstats_sdk/resources/charts.rb
+- lib/songstats_sdk/resources/entities.rb
+- lib/songstats_sdk/resources/info.rb
+- lib/songstats_sdk/resources/stations.rb
+- lib/songstats_sdk/resources/tracks.rb
+- lib/songstats_sdk/version.rb
+homepage: https://songstats.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://songstats.com
+  source_code_uri: https://github.com/songstats/songstats-ruby-sdk
+  bug_tracker_uri: https://github.com/songstats/songstats-ruby-sdk/issues
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.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 Songstats Enterprise API.
+test_files: []