tmdb_client 1.0.0

data/lib/tmdb/config.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module TMDb
+  # Settings for a client. Held on a plain object rather than in a class
+  # variable, so a process can run more than one (a different language, a
+  # different key) without them treading on each other.
+  #
+  # Not to be confused with TMDb::Configuration, which is the `/configuration`
+  # endpoint.
+  class Config
+    DEFAULT_BASE_URL = 'https://api.themoviedb.org/3'
+    DEFAULT_TIMEOUT = 10
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_RETRIES = 2
+    DEFAULT_RETRY_INTERVAL = 0.5
+    # TMDb sends Retry-After on a 429, and the retry middleware honours it.
+    # Waiting on it is right; waiting on it for minutes inside a web request is
+    # not, so a wait longer than this gives up instead of sleeping.
+    DEFAULT_MAX_RETRY_INTERVAL = 10
+    RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+
+    # A v3 API key, sent as a query parameter.
+    attr_accessor :api_key
+    # A v4 read access token, sent as a bearer header. Takes precedence over
+    # api_key when both are set.
+    attr_accessor :access_token
+    attr_accessor :language, :region, :base_url, :timeout, :open_timeout,
+                  :retries, :retry_interval, :max_retry_interval, :adapter, :logger, :user_agent
+
+    def initialize
+      @base_url = DEFAULT_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @retries = DEFAULT_RETRIES
+      @retry_interval = DEFAULT_RETRY_INTERVAL
+      @max_retry_interval = DEFAULT_MAX_RETRY_INTERVAL
+      @adapter = Faraday.default_adapter
+      @user_agent = "tmdb_client/#{TMDb::VERSION} (+https://github.com/cineol-gems/tmdb-client)"
+    end
+
+    def bearer_auth?
+      !access_token.nil? && !access_token.to_s.empty?
+    end
+
+    def credentials?
+      bearer_auth? || !api_key.to_s.empty?
+    end
+
+    # The query parameters every request starts from. A per-call filter of the
+    # same name overrides these, which is how `language: 'en'` works on one call
+    # while the client stays configured for Spanish.
+    def default_params
+      params = { language: language, region: region }
+      params[:api_key] = api_key unless bearer_auth?
+
+      params.compact
+    end
+
+    def headers
+      base = { 'Accept' => 'application/json', 'User-Agent' => user_agent }
+      base['Authorization'] = "Bearer #{access_token}" if bearer_auth?
+
+      base
+    end
+
+    def initialize_copy(other)
+      super
+      @adapter = other.adapter.dup if other.adapter.is_a?(::Array)
+    end
+  end
+end

data/lib/tmdb/configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TMDb
+  # The `/configuration` endpoints -- image base URLs, the country and language
+  # lists, the job list. Not to be confused with TMDb::Config, which is this
+  # gem's own settings.
+  class Configuration < Resource
+    def get(filters = {})
+      object('/configuration', filters)
+    end
+    alias detail get
+
+    def countries(filters = {})
+      objects(fetch('/configuration/countries', filters))
+    end
+
+    def languages(filters = {})
+      objects(fetch('/configuration/languages', filters))
+    end
+
+    def jobs(filters = {})
+      objects(fetch('/configuration/jobs', filters))
+    end
+
+    def timezones(filters = {})
+      objects(fetch('/configuration/timezones', filters))
+    end
+
+    # An Array of locale strings, not objects.
+    def primary_translations(filters = {})
+      fetch('/configuration/primary_translations', filters)
+    end
+
+    expose_class_methods
+  end
+end

data/lib/tmdb/credit.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module TMDb
+  class Credit < Resource
+    def detail(id, filters = {})
+      object("/credit/#{id}", filters)
+    end
+
+    expose_class_methods
+  end
+end

data/lib/tmdb/discover.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module TMDb
+  class Discover < Resource
+    def movie(filters = {})
+      page('/discover/movie', filters)
+    end
+
+    def tv(filters = {})
+      page('/discover/tv', filters)
+    end
+
+    expose_class_methods
+  end
+end

data/lib/tmdb/errors.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module TMDb
+  # Base class for everything this gem raises.
+  #
+  # `rescue TMDb::Error` catches every failure, transport ones included: no
+  # Faraday, socket or JSON exception is ever allowed to escape the client, so
+  # callers never have to know what the client is built on.
+  #
+  # Where the old `themoviedb-api` gem collapsed every failure into one class
+  # carrying only a message string, an error here knows its HTTP `status`,
+  # TMDb's own numeric `code`, and the parsed `body` -- so a missing id can be
+  # told from a bad key without matching on prose.
+  class Error < StandardError
+    attr_reader :status, :code, :body, :retry_after
+
+    def initialize(message = nil, status: nil, code: nil, body: nil, retry_after: nil)
+      @status = status
+      @code = code
+      @body = body
+      @retry_after = retry_after
+
+      super(message || 'TMDb request failed')
+    end
+
+    # Maps an HTTP status onto the class raised for it. Unknown 4xx and 5xx
+    # statuses still land under ClientError/ServerError rather than the bare
+    # base, so `rescue TMDb::ServerError` keeps meaning "their side".
+    def self.class_for(status)
+      STATUS_ERRORS.fetch(status) do
+        if status.to_i >= 500 then ServerError
+        elsif status.to_i >= 400 then ClientError
+        else Error
+        end
+      end
+    end
+  end
+
+  # The gem was asked to make a request it has no credentials for. Raised
+  # before any HTTP happens, so a forgotten `TMDb.configure` reads as a
+  # configuration mistake rather than as a 401 from TMDb.
+  class ConfigurationError < Error; end
+
+  # TMDb answered, but with a failing status.
+  class HTTPError < Error; end
+
+  # 4xx -- we asked wrongly.
+  class ClientError < HTTPError; end
+  class BadRequest < ClientError; end
+  class Unauthorized < ClientError; end
+  class Forbidden < ClientError; end
+  class NotFound < ClientError; end
+  class MethodNotAllowed < ClientError; end
+  class NotAcceptable < ClientError; end
+  class UnprocessableEntity < ClientError; end
+
+  # 429. `retry_after` carries the header TMDb sent, in seconds, when it sent one.
+  class RateLimited < ClientError; end
+
+  # 5xx -- their side.
+  class ServerError < HTTPError; end
+  class ServiceUnavailable < ServerError; end
+
+  # We never reached TMDb, or could not read what came back.
+  class ConnectionError < Error; end
+  class TimeoutError < ConnectionError; end
+  class ParsingError < Error; end
+
+  Error::STATUS_ERRORS = {
+    400 => BadRequest,
+    401 => Unauthorized,
+    403 => Forbidden,
+    404 => NotFound,
+    405 => MethodNotAllowed,
+    406 => NotAcceptable,
+    422 => UnprocessableEntity,
+    429 => RateLimited,
+    500 => ServerError,
+    502 => ServiceUnavailable,
+    503 => ServiceUnavailable,
+    504 => ServiceUnavailable
+  }.freeze
+end

data/lib/tmdb/find.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module TMDb
+  # Looks a title up by an id from somewhere else -- IMDb, TVDB, Wikidata:
+  #
+  #   TMDb::Find.movie('tt0137523', external_source: 'imdb_id')
+  #
+  # Each method returns a bare Array of the matches for that media type, which
+  # is nearly always empty or one long.
+  class Find < Resource
+    def movie(external_id, filters = {})
+      list("/find/#{external_id}", :movie_results, filters)
+    end
+
+    def people(external_id, filters = {})
+      list("/find/#{external_id}", :person_results, filters)
+    end
+    alias person people
+
+    def tv_series(external_id, filters = {})
+      list("/find/#{external_id}", :tv_results, filters)
+    end
+    # themoviedb-api spelled it `tv_serie`. Kept so a migration is a rename.
+    alias tv_serie tv_series
+
+    # themoviedb-api read `tv_episode_results` here and `tv_season_results` in
+    # tv_episode -- the two were swapped. These read the right keys.
+    def tv_season(external_id, filters = {})
+      list("/find/#{external_id}", :tv_season_results, filters)
+    end
+
+    def tv_episode(external_id, filters = {})
+      list("/find/#{external_id}", :tv_episode_results, filters)
+    end
+
+    # Every bucket from a single request, where asking for a film and then a
+    # series costs two.
+    def all(external_id, filters = {})
+      object("/find/#{external_id}", filters)
+    end
+
+    expose_class_methods
+  end
+end

data/lib/tmdb/genre.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TMDb
+  class Genre < Resource
+    def movie_list(filters = {})
+      list('/genre/movie/list', :genres, filters)
+    end
+
+    def tv_list(filters = {})
+      list('/genre/tv/list', :genres, filters)
+    end
+
+    # Deprecated by TMDb; TMDb::Discover.movie(with_genres: id) is the
+    # supported way to ask this. Kept for parity with themoviedb-api.
+    def movies(genre_id, filters = {})
+      page("/genre/#{genre_id}/movies", filters)
+    end
+
+    expose_class_methods
+  end
+end

data/lib/tmdb/job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TMDb
+  # Deprecated by TMDb in favour of TMDb::Configuration.jobs. Kept for parity
+  # with themoviedb-api.
+  class Job < Resource
+    def list(filters = {})
+      objects(fetch('/job/list', filters)[:jobs])
+    end
+
+    expose_class_methods
+  end
+end

data/lib/tmdb/keyword.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module TMDb
+  class Keyword < Resource
+    def detail(id, filters = {})
+      object("/keyword/#{id}", filters)
+    end
+
+    def movies(id, filters = {})
+      page("/keyword/#{id}/movies", filters)
+    end
+
+    expose_class_methods
+  end
+end

data/lib/tmdb/movie.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module TMDb
+  class Movie < Resource
+    def detail(id, filters = {})
+      object("/movie/#{id}", filters)
+    end
+
+    def alternative_titles(id, filters = {})
+      list("/movie/#{id}/alternative_titles", :titles, filters)
+    end
+
+    def credits(id, filters = {})
+      object("/movie/#{id}/credits", filters)
+    end
+
+    def cast(id, filters = {})
+      list("/movie/#{id}/credits", :cast, filters)
+    end
+
+    def crew(id, filters = {})
+      list("/movie/#{id}/credits", :crew, filters)
+    end
+
+    def director(id, filters = {})
+      crew(id, filters).select { |member| member[:job] == 'Director' }
+    end
+
+    def external_ids(id, filters = {})
+      object("/movie/#{id}/external_ids", filters)
+    end
+
+    def images(id, filters = {})
+      object("/movie/#{id}/images", filters)
+    end
+
+    def backdrops(id, filters = {})
+      list("/movie/#{id}/images", :backdrops, filters)
+    end
+
+    def posters(id, filters = {})
+      list("/movie/#{id}/images", :posters, filters)
+    end
+
+    def logos(id, filters = {})
+      list("/movie/#{id}/images", :logos, filters)
+    end
+
+    def videos(id, filters = {})
+      list("/movie/#{id}/videos", :results, filters)
+    end
+
+    def keywords(id, filters = {})
+      list("/movie/#{id}/keywords", :keywords, filters)
+    end
+
+    def watch_providers(id, filters = {})
+      object("/movie/#{id}/watch/providers", filters)
+    end
+
+    def release_dates(id, filters = {})
+      list("/movie/#{id}/release_dates", :results, filters)
+    end
+
+    # Deprecated by TMDb in favour of `release_dates`; kept for parity with
+    # themoviedb-api, which only had this one.
+    def releases(id, filters = {})
+      list("/movie/#{id}/releases", :countries, filters)
+    end
+
+    def translations(id, filters = {})
+      list("/movie/#{id}/translations", :translations, filters)
+    end
+
+    def changes(id, filters = {})
+      list("/movie/#{id}/changes", :changes, filters)
+    end
+
+    def similar(id, filters = {})
+      page("/movie/#{id}/similar", filters)
+    end
+
+    def recommendations(id, filters = {})
+      page("/movie/#{id}/recommendations", filters)
+    end
+
+    def reviews(id, filters = {})
+      page("/movie/#{id}/reviews", filters)
+    end
+
+    def lists(id, filters = {})
+      page("/movie/#{id}/lists", filters)
+    end
+
+    def latest(filters = {})
+      object('/movie/latest', filters)
+    end
+
+    def upcoming(filters = {})
+      page('/movie/upcoming', filters)
+    end
+
+    def now_playing(filters = {})
+      page('/movie/now_playing', filters)
+    end
+
+    def popular(filters = {})
+      page('/movie/popular', filters)
+    end
+
+    def top_rated(filters = {})
+      page('/movie/top_rated', filters)
+    end
+
+    expose_class_methods
+  end
+end

data/lib/tmdb/network.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module TMDb
+  class Network < Resource
+    def detail(id, filters = {})
+      object("/network/#{id}", filters)
+    end
+
+    def alternative_names(id, filters = {})
+      list("/network/#{id}/alternative_names", :results, filters)
+    end
+
+    def images(id, filters = {})
+      object("/network/#{id}/images", filters)
+    end
+
+    expose_class_methods
+  end
+end

data/lib/tmdb/object.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module TMDb
+  # An immutable, hash-backed view over one TMDb JSON object.
+  #
+  # TMDb's payloads are wide, deeply nested, and change shape between endpoints
+  # and `append_to_response` combinations, so this gem does not try to declare a
+  # field list per resource -- it wraps whatever came back and lets you read it
+  # three ways, whichever suits the call site:
+  #
+  #   movie.title            # => "Fight Club"
+  #   movie[:title]          # => "Fight Club"
+  #   movie['title']         # => "Fight Club"
+  #
+  # Nested objects and arrays are wrapped recursively, so `movie.credits.cast`
+  # is an Array of TMDb::Object. A key TMDb did not send reads as `nil` rather
+  # than raising: half of TMDb's fields are conditional (a credit has no
+  # `imdb_id`, a film in production has no `release_date`), and forcing every
+  # caller to guard each read would be worse than the typo it would catch.
+  #
+  # This replaces the old gem's OpenStruct subclass. Unlike OpenStruct it is
+  # frozen, allocates no singleton class per instance, and cannot be mutated
+  # into disagreeing with the response it came from.
+  class Object
+    # Ruby calls these implicitly to convert an object. Answering `nil` to them
+    # would make Ruby raise a confusing TypeError deep inside a splat or an
+    # interpolation, so they must miss loudly instead.
+    COERCION_METHODS = %i[to_ary to_a to_hash to_str to_int to_io to_proc coerce].freeze
+
+    attr_reader :attributes
+
+    def initialize(attributes = {})
+      @attributes = self.class.normalize(attributes)
+
+      freeze
+    end
+
+    class << self
+      # Symbolizes keys one level deep and wraps the values. JSON keys arrive as
+      # strings, hand-built test doubles as symbols; both end up identical.
+      def normalize(attributes)
+        case attributes
+        when Object then attributes.attributes
+        when nil then {}.freeze
+        when ::Hash
+          attributes.each_with_object({}) { |(key, value), memo| memo[key.to_sym] = wrap(value) }.freeze
+        else
+          raise ArgumentError, "TMDb::Object expects a Hash, got #{attributes.class}"
+        end
+      end
+
+      # Anything already wrapped, and every scalar, falls through untouched.
+      def wrap(value)
+        case value
+        when ::Hash then new(value)
+        when ::Array then value.map { |element| wrap(element) }.freeze
+        else value
+        end
+      end
+    end
+
+    def [](key)
+      @attributes[key.to_sym]
+    end
+
+    def fetch(key, *default, &)
+      @attributes.fetch(key.to_sym, *default, &)
+    end
+
+    def dig(key, *rest)
+      value = self[key]
+
+      rest.empty? ? value : value&.dig(*rest)
+    end
+
+    def key?(key)
+      @attributes.key?(key.to_sym)
+    end
+    alias has_key? key?
+    alias member? key?
+
+    def keys
+      @attributes.keys
+    end
+
+    def each_pair(&block)
+      return enum_for(:each_pair) unless block
+
+      @attributes.each_pair(&block)
+      self
+    end
+
+    # A plain, deeply-unwrapped Hash with symbol keys -- the inverse of `new`.
+    def to_h
+      @attributes.transform_values { |value| self.class.unwrap(value) }
+    end
+
+    def self.unwrap(value)
+      case value
+      when Object then value.to_h
+      when ::Array then value.map { |element| unwrap(element) }
+      else value
+      end
+    end
+
+    def ==(other)
+      other.is_a?(Object) && attributes == other.attributes
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, @attributes].hash
+    end
+
+    def inspect
+      "#<TMDb::Object #{@attributes.map { |key, value| "#{key}=#{value.inspect}" }.join(' ')}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def method_missing(name, *args)
+      return super unless args.empty?
+      return super if COERCION_METHODS.include?(name)
+      return super if name.end_with?('=', '?', '!')
+
+      @attributes[name]
+    end
+
+    # Deliberately narrower than `method_missing`: only keys actually present
+    # answer true. Ruby's implicit conversion checks (`to_ary` and friends) and
+    # any `respond_to?`-based duck typing therefore get an honest answer, while
+    # a plain read of an absent key still returns nil.
+    def respond_to_missing?(name, include_private = false)
+      @attributes.key?(name) || super
+    end
+  end
+end