sports-odds-api 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ed23b744aefd6897f1ffe2c1b8b6ec7d2017a5c38f9f61407e9036a64c4b539c
+  data.tar.gz: 330d785ea83722954b4a1861bce87df552f61bf5640cd43d28a19b24ce39699b
+SHA512:
+  metadata.gz: a294de700247d92d72620d6ecd464313dc711d36bcccba1c848dbe1ce8a7da399559a4dcb59bfe3fcaf70982c6a86423af8d45ef3cb6bc0fbcf02bdedc20337b
+  data.tar.gz: b482d8805041a5b6d2efd02090c05f598b3b998619ba553502633be7406285304e8608f88f4c6d548b0b27d7c2a8c333639638d9faf8770757eb44fc21be5e2d

data/.ignore

@@ -0,0 +1,2 @@
+rbi/*
+sig/*

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.0.0 (2025-09-23)
+
+Full Changelog: [v0.0.1...v1.0.0](https://github.com/SportsGameOdds/sports-odds-api-ruby/compare/v0.0.1...v1.0.0)
+
+### Chores
+
+* configure new SDK language ([9c4b469](https://github.com/SportsGameOdds/sports-odds-api-ruby/commit/9c4b4699bebfe2c5b954d381bd7e9e80d0fac2ad))
+* update SDK settings ([cbf7543](https://github.com/SportsGameOdds/sports-odds-api-ruby/commit/cbf7543231a240400a972d7f4ef862387ffae409))

data/README.md

@@ -0,0 +1,186 @@
+# Sports Odds API - Live Sports Data & Sportsbook Betting Odds - Powered by SportsGameOdds Ruby Library
+
+Get live betting odds, spreads, and totals for NFL, NBA, MLB, and 50 additional sports and leagues. Production-ready Ruby SDK with connection pooling, 99.9% uptime, and sub-minute updates during live games. Perfect for developers building sportsbook platforms, odds comparison tools, positive EV models, and anything else that requires fast, accurate sports data.
+
+[![Gem Version](https://img.shields.io/gem/v/sports-odds-api.svg?label=rubygems%20(stable))](https://rubygems.org/gems/sports-odds-api)
+
+This library provides convenient access to the Sports Game Odds REST API from any Ruby 3.2.0+ application.
+
+The REST API documentation can be found on [sportsgameodds.com](https://sportsgameodds.com/docs/). The full API of this library can be found in [api.md](api.md).
+
+## Features
+
+**For developers building the next generation of sports stats and/or betting applications:**
+
+- 📈 **3k+ odds markets** including moneylines, spreads, over/unders, team props, player props & more
+- 🏈 **50+ leagues covered** including NFL, NBA, MLB, NHL, NCAAF, NCAAB, EPL, UCL, UFC, PGA, ATP & more
+- 📊 **80+ sportsbooks** with unified odds formats, alt lines & deeplinks
+- 📺 **Live scores & stats** coverage on all games, teams, and players
+- ⚡ **Sub-100ms response times** and sub-minute updates for fast data
+- 💎 **Comprehensive Ruby type support** with Yard, RBS, and RBI definitions
+- 💰 **Developer-friendly pricing** with a generous free tier
+- ⏱️ **5-minute setup** with copy-paste examples
+
+## Installation
+
+Add to your application's `Gemfile`:
+
+```ruby
+gem "sports-odds-api", "~> 1.0.0"
+```
+
+Or install manually:
+
+```sh
+gem install sports-odds-api
+```
+
+## Obtain an API Key
+
+Get a free API key from [sportsgameodds.com](https://sportsgameodds.com/pricing).
+
+Unlike enterprise-only solutions, the Sports Game Odds API offers a developer-friendly experience, transparent pricing, comprehensive documentation, and a generous free tier.
+
+## Usage
+
+The full API of this library can be found in [api.md](api.md).
+
+```ruby
+require "bundler/setup"
+require "sports_odds_api"
+
+client = SportsOddsAPI::Client.new(
+  api_key_param: ENV["SPORTS_ODDS_API_KEY_HEADER"] # This is the default and can be omitted
+)
+
+page = client.events.get
+event = page.data[0]
+
+puts(event.activity)
+```
+
+# Real-Time Event Streaming API
+
+This API endpoint is only available to **AllStar** and **custom plan** subscribers. It is not included with basic subscription tiers. [Contact support](mailto:api@sportsgameodds.com) to get access.
+
+This streaming API is currently in **beta**. API call patterns, response formats, and functionality may change. Fully managed streaming via SDK may be available in future releases.
+
+Our Streaming API provides real-time updates for Event objects through WebSocket connections. Instead of polling our REST endpoints, you can maintain a persistent connection to receive instant notifications when events change. This is ideal for applications that need immediate updates with minimal delay.
+
+We use [Pusher Protocol](https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/) for WebSocket communication. While you can connect using any WebSocket library, we recommend using the [pusher-client-ruby](https://github.com/pusher/pusher-client-ruby) gem.
+
+## How It Works
+
+The streaming process involves two steps:
+
+1. **Get Connection Details**: Make a request using `client.stream.events()` to receive:
+    - WebSocket authentication credentials
+    - WebSocket URL/channel info
+    - Initial snapshot of current data
+
+2. **Connect and Stream**: Use the provided details to connect via Pusher and receive real-time `eventID` notifications for changed events.
+
+Your API key will have limits on concurrent streams.
+
+## Available Feeds
+
+Subscribe to different feeds using the `feed` query parameter:
+
+| Feed              | Description                                                                 | Required Parameters |
+| ----------------- | --------------------------------------------------------------------------- | ------------------- |
+| `events:live`     | All events currently in progress (started but not finished)                | None                |
+| `events:upcoming` | Upcoming events with available odds for a specific league                  | `leagueID`          |
+| `events:byid`     | Updates for a single specific event                                         | `eventID`           |
+
+The number of supported feeds will increase over time. Please reach out if you have a use case which can't be covered by these feeds.
+
+## Quick Start Example
+
+Here's the minimal code to connect to live events:
+
+```ruby
+require "sports_odds_api"
+require "pusher-client"
+
+STREAM_FEED = "events:live" # ex: events:upcoming, events:byid, events:live
+API_KEY = "YOUR API KEY"
+
+client = SportsOddsAPI::Client.new(api_key_param: API_KEY)
+
+# Initialize a data structure where we'll save the event data
+events = {}
+
+# Call this endpoint to get initial data and connection parameters
+stream_info = client.stream.events(feed: STREAM_FEED)
+
+# Seed initial data
+stream_info.data.each { |event| events[event.eventID] = event }
+
+# Connect to WebSocket server
+pusher = PusherClient::Socket.new(stream_info.pusherKey, stream_info.pusherOptions)
+channel = pusher.subscribe(stream_info.channel)
+
+channel.bind("data") do |changed_events|
+  event_ids = changed_events.map { |ev| ev["eventID"] }.join(",")
+
+  client.events.get(eventIDs: event_ids).each do |event|
+    events[event.eventID] = event
+  end
+end
+
+trap("SIGINT") { pusher.disconnect }
+pusher.connect
+```
+
+## Pagination
+
+List methods in the Sports Game Odds API are paginated.
+
+This library provides auto-paginating iterators with each list response:
+
+```ruby
+page = client.events.get(limit: 30)
+
+page.auto_paging_each do |event|
+  puts(event.activity)
+end
+```
+
+Or, you can use `#next_page?` and `#next_page` for manual pagination.
+
+## Handling Errors
+
+When the library is unable to connect to the API, or if the API returns a non-success status code (4xx or 5xx), a subclass of `SportsOddsAPI::Errors::APIError` will be thrown.
+
+```ruby
+begin
+  page = client.events.get
+rescue SportsOddsAPI::Errors::APIError => e
+  puts(e.message)
+end
+```
+
+Error codes map to specific exception classes, such as `AuthenticationError`, `RateLimitError`, `NotFoundError`, etc.
+
+## Retries
+
+Certain errors are retried automatically with exponential backoff. Configure retries globally or per-request with the `max_retries` option.
+
+## Timeouts
+
+Requests time out after 60 seconds by default. Configure with `timeout` globally or per-request.
+
+## Advanced Usage
+
+- Access undocumented params via `extra_query`, `extra_body`, and `extra_headers`
+- Use `client.request` for undocumented endpoints
+- Threadsafe client with connection pooling
+- Sorbet integration via RBI & RBS definitions
+
+## Requirements
+
+- Ruby 3.2.0+
+
+## Contributing
+
+See [the contributing documentation](https://github.com/SportsGameOdds/sports-odds-api-ruby/tree/main/CONTRIBUTING.md).

data/SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Reporting Security Issues
+
+This SDK is generated by [Stainless Software Inc](http://stainless.com). Stainless takes security seriously, and encourages you to report any security vulnerability promptly so that appropriate action can be taken.
+
+To report a security issue, please contact the Stainless team at security@stainless.com.
+
+## Responsible Disclosure
+
+We appreciate the efforts of security researchers and individuals who help us maintain the security of
+SDKs we generate. If you believe you have found a security vulnerability, please adhere to responsible
+disclosure practices by allowing us a reasonable amount of time to investigate and address the issue
+before making any information public.
+
+## Reporting Non-SDK Related Security Issues
+
+If you encounter security issues that are not directly related to SDKs but pertain to the services
+or products provided by Sports Game Odds, please follow the respective company's security reporting guidelines.
+
+### Sports Game Odds Terms and Policies
+
+Please contact api@sportsgameodds.com for any questions or concerns regarding the security of our services.
+
+---
+
+Thank you for helping us keep the SDKs and systems they interact with secure.

data/lib/sports_odds_api/client.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module SportsOddsAPI
+  class Client < SportsOddsAPI::Internal::Transport::BaseClient
+    # Default max number of retries to attempt after a failed retryable request.
+    DEFAULT_MAX_RETRIES = 2
+
+    # Default per-request timeout.
+    DEFAULT_TIMEOUT_IN_SECONDS = 60.0
+
+    # Default initial retry delay in seconds.
+    # Overall delay is calculated using exponential backoff + jitter.
+    DEFAULT_INITIAL_RETRY_DELAY = 0.5
+
+    # Default max retry delay in seconds.
+    DEFAULT_MAX_RETRY_DELAY = 8.0
+
+    # API key via header
+    # @return [String, nil]
+    attr_reader :api_key_header
+
+    # API key via query param
+    # @return [String, nil]
+    attr_reader :api_key_param
+
+    # @return [SportsOddsAPI::Resources::Events]
+    attr_reader :events
+
+    # @return [SportsOddsAPI::Resources::Teams]
+    attr_reader :teams
+
+    # @return [SportsOddsAPI::Resources::Players]
+    attr_reader :players
+
+    # @return [SportsOddsAPI::Resources::Leagues]
+    attr_reader :leagues
+
+    # @return [SportsOddsAPI::Resources::Sports]
+    attr_reader :sports
+
+    # @return [SportsOddsAPI::Resources::Stats]
+    attr_reader :stats
+
+    # @return [SportsOddsAPI::Resources::Account]
+    attr_reader :account
+
+    # @return [SportsOddsAPI::Resources::Stream]
+    attr_reader :stream
+
+    # @api private
+    #
+    # @return [Hash{String=>String}]
+    private def auth_headers
+      {"x-api-key" => @api_key_header}
+    end
+
+    # @api private
+    #
+    # @return [Hash{String=>String}]
+    private def auth_query
+      {"apiKey" => @api_key_param}
+    end
+
+    # Creates and returns a new client for interacting with the API.
+    #
+    # @param api_key_header [String, nil] API key via header Defaults to `ENV["SPORTS_ODDS_API_KEY_HEADER"]`
+    #
+    # @param api_key_param [String, nil] API key via query param Defaults to `ENV["SPORTS_ODDS_API_KEY_HEADER"]`
+    #
+    # @param base_url [String, nil] Override the default base URL for the API, e.g.,
+    # `"https://api.example.com/v2/"`. Defaults to `ENV["SPORTS_GAME_ODDS_BASE_URL"]`
+    #
+    # @param max_retries [Integer] Max number of retries to attempt after a failed retryable request.
+    #
+    # @param timeout [Float]
+    #
+    # @param initial_retry_delay [Float]
+    #
+    # @param max_retry_delay [Float]
+    def initialize(
+      api_key_header: ENV["SPORTS_ODDS_API_KEY_HEADER"],
+      api_key_param: ENV["SPORTS_ODDS_API_KEY_HEADER"],
+      base_url: ENV["SPORTS_GAME_ODDS_BASE_URL"],
+      max_retries: self.class::DEFAULT_MAX_RETRIES,
+      timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
+      initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
+      max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY
+    )
+      base_url ||= "https://api.sportsgameodds.com/v2"
+
+      @api_key_header = api_key_header&.to_s
+      @api_key_param = api_key_param&.to_s
+
+      super(
+        base_url: base_url,
+        timeout: timeout,
+        max_retries: max_retries,
+        initial_retry_delay: initial_retry_delay,
+        max_retry_delay: max_retry_delay
+      )
+
+      @events = SportsOddsAPI::Resources::Events.new(client: self)
+      @teams = SportsOddsAPI::Resources::Teams.new(client: self)
+      @players = SportsOddsAPI::Resources::Players.new(client: self)
+      @leagues = SportsOddsAPI::Resources::Leagues.new(client: self)
+      @sports = SportsOddsAPI::Resources::Sports.new(client: self)
+      @stats = SportsOddsAPI::Resources::Stats.new(client: self)
+      @account = SportsOddsAPI::Resources::Account.new(client: self)
+      @stream = SportsOddsAPI::Resources::Stream.new(client: self)
+    end
+  end
+end

data/lib/sports_odds_api/errors.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module SportsOddsAPI
+  module Errors
+    class Error < StandardError
+      # @!attribute cause
+      #
+      #   @return [StandardError, nil]
+    end
+
+    class ConversionError < SportsOddsAPI::Errors::Error
+      # @return [StandardError, nil]
+      def cause = @cause.nil? ? super : @cause
+
+      # @api private
+      #
+      # @param on [Class<StandardError>]
+      # @param method [Symbol]
+      # @param target [Object]
+      # @param value [Object]
+      # @param cause [StandardError, nil]
+      def initialize(on:, method:, target:, value:, cause: nil)
+        cls = on.name.split("::").last
+
+        message = [
+          "Failed to parse #{cls}.#{method} from #{value.class} to #{target.inspect}.",
+          "To get the unparsed API response, use #{cls}[#{method.inspect}].",
+          cause && "Cause: #{cause.message}"
+        ].filter(&:itself).join(" ")
+
+        @cause = cause
+        super(message)
+      end
+    end
+
+    class APIError < SportsOddsAPI::Errors::Error
+      # @return [URI::Generic]
+      attr_accessor :url
+
+      # @return [Integer, nil]
+      attr_accessor :status
+
+      # @return [Hash{String=>String}, nil]
+      attr_accessor :headers
+
+      # @return [Object, nil]
+      attr_accessor :body
+
+      # @api private
+      #
+      # @param url [URI::Generic]
+      # @param status [Integer, nil]
+      # @param headers [Hash{String=>String}, nil]
+      # @param body [Object, nil]
+      # @param request [nil]
+      # @param response [nil]
+      # @param message [String, nil]
+      def initialize(url:, status: nil, headers: nil, body: nil, request: nil, response: nil, message: nil)
+        @url = url
+        @status = status
+        @headers = headers
+        @body = body
+        @request = request
+        @response = response
+        super(message)
+      end
+    end
+
+    class APIConnectionError < SportsOddsAPI::Errors::APIError
+      # @!attribute status
+      #
+      #   @return [nil]
+
+      # @!attribute body
+      #
+      #   @return [nil]
+
+      # @api private
+      #
+      # @param url [URI::Generic]
+      # @param status [nil]
+      # @param headers [Hash{String=>String}, nil]
+      # @param body [nil]
+      # @param request [nil]
+      # @param response [nil]
+      # @param message [String, nil]
+      def initialize(
+        url:,
+        status: nil,
+        headers: nil,
+        body: nil,
+        request: nil,
+        response: nil,
+        message: "Connection error."
+      )
+        super
+      end
+    end
+
+    class APITimeoutError < SportsOddsAPI::Errors::APIConnectionError
+      # @api private
+      #
+      # @param url [URI::Generic]
+      # @param status [nil]
+      # @param headers [Hash{String=>String}, nil]
+      # @param body [nil]
+      # @param request [nil]
+      # @param response [nil]
+      # @param message [String, nil]
+      def initialize(
+        url:,
+        status: nil,
+        headers: nil,
+        body: nil,
+        request: nil,
+        response: nil,
+        message: "Request timed out."
+      )
+        super
+      end
+    end
+
+    class APIStatusError < SportsOddsAPI::Errors::APIError
+      # @api private
+      #
+      # @param url [URI::Generic]
+      # @param status [Integer]
+      # @param headers [Hash{String=>String}, nil]
+      # @param body [Object, nil]
+      # @param request [nil]
+      # @param response [nil]
+      # @param message [String, nil]
+      #
+      # @return [self]
+      def self.for(url:, status:, headers:, body:, request:, response:, message: nil)
+        kwargs =
+          {
+            url: url,
+            status: status,
+            headers: headers,
+            body: body,
+            request: request,
+            response: response,
+            message: message
+          }
+
+        case status
+        in 400
+          SportsOddsAPI::Errors::BadRequestError.new(**kwargs)
+        in 401
+          SportsOddsAPI::Errors::AuthenticationError.new(**kwargs)
+        in 403
+          SportsOddsAPI::Errors::PermissionDeniedError.new(**kwargs)
+        in 404
+          SportsOddsAPI::Errors::NotFoundError.new(**kwargs)
+        in 409
+          SportsOddsAPI::Errors::ConflictError.new(**kwargs)
+        in 422
+          SportsOddsAPI::Errors::UnprocessableEntityError.new(**kwargs)
+        in 429
+          SportsOddsAPI::Errors::RateLimitError.new(**kwargs)
+        in (500..)
+          SportsOddsAPI::Errors::InternalServerError.new(**kwargs)
+        else
+          SportsOddsAPI::Errors::APIStatusError.new(**kwargs)
+        end
+      end
+
+      # @!parse
+      #   # @return [Integer]
+      #   attr_accessor :status
+
+      # @api private
+      #
+      # @param url [URI::Generic]
+      # @param status [Integer]
+      # @param headers [Hash{String=>String}, nil]
+      # @param body [Object, nil]
+      # @param request [nil]
+      # @param response [nil]
+      # @param message [String, nil]
+      def initialize(url:, status:, headers:, body:, request:, response:, message: nil)
+        message ||= {url: url.to_s, status: status, body: body}
+        super(
+          url: url,
+          status: status,
+          headers: headers,
+          body: body,
+          request: request,
+          response: response,
+          message: message&.to_s
+        )
+      end
+    end
+
+    class BadRequestError < SportsOddsAPI::Errors::APIStatusError
+      HTTP_STATUS = 400
+    end
+
+    class AuthenticationError < SportsOddsAPI::Errors::APIStatusError
+      HTTP_STATUS = 401
+    end
+
+    class PermissionDeniedError < SportsOddsAPI::Errors::APIStatusError
+      HTTP_STATUS = 403
+    end
+
+    class NotFoundError < SportsOddsAPI::Errors::APIStatusError
+      HTTP_STATUS = 404
+    end
+
+    class ConflictError < SportsOddsAPI::Errors::APIStatusError
+      HTTP_STATUS = 409
+    end
+
+    class UnprocessableEntityError < SportsOddsAPI::Errors::APIStatusError
+      HTTP_STATUS = 422
+    end
+
+    class RateLimitError < SportsOddsAPI::Errors::APIStatusError
+      HTTP_STATUS = 429
+    end
+
+    class InternalServerError < SportsOddsAPI::Errors::APIStatusError
+      HTTP_STATUS = (500..)
+    end
+  end
+end

data/lib/sports_odds_api/file_part.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module SportsOddsAPI
+  class FilePart
+    # @return [Pathname, StringIO, IO, String]
+    attr_reader :content
+
+    # @return [String, nil]
+    attr_reader :content_type
+
+    # @return [String, nil]
+    attr_reader :filename
+
+    # @api private
+    #
+    # @return [String]
+    private def read
+      case content
+      in Pathname
+        content.read(binmode: true)
+      in StringIO
+        content.string
+      in IO
+        content.read
+      in String
+        content
+      end
+    end
+
+    # @param a [Object]
+    #
+    # @return [String]
+    def to_json(*a) = read.to_json(*a)
+
+    # @param a [Object]
+    #
+    # @return [String]
+    def to_yaml(*a) = read.to_yaml(*a)
+
+    # @param content [Pathname, StringIO, IO, String]
+    # @param filename [String, nil]
+    # @param content_type [String, nil]
+    def initialize(content, filename: nil, content_type: nil)
+      @content = content
+      @filename =
+        case content
+        in Pathname
+          filename.nil? ? content.basename.to_path : ::File.basename(filename)
+        else
+          filename.nil? ? nil : ::File.basename(filename)
+        end
+      @content_type = content_type
+    end
+  end
+end