podcast_api 1.1.5 → 3.0.0

data/lib/api_methods.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+# Generated by listennotes/devtools/api-sdks/sync.py ruby. Do not edit.
+
+module PodcastApi
+  module ApiMethods
+    def search(**kwargs)
+      request_api('GET', '/search',
+                  ['q', 'sort_by_date', 'type', 'offset', 'len_min', 'len_max', 'episode_count_min', 'episode_count_max', 'update_freq_min', 'update_freq_max', 'genre_ids', 'published_before', 'published_after', 'only_in', 'language', 'region', 'ocid', 'ncid', 'safe_mode', 'unique_podcasts', 'interviews_only', 'sponsored_only', 'page_size'], kwargs)
+    end
+
+    def typeahead(**kwargs)
+      request_api('GET', '/typeahead',
+                  ['q', 'show_podcasts', 'show_genres', 'safe_mode'], kwargs)
+    end
+
+    def search_episode_titles(**kwargs)
+      request_api('GET', '/search_episode_titles',
+                  ['q', 'podcast_id', 'podcast_id_type'], kwargs)
+    end
+
+    def spellcheck(**kwargs)
+      request_api('GET', '/spellcheck',
+                  ['q'], kwargs)
+    end
+
+    def fetch_related_searches(**kwargs)
+      request_api('GET', '/related_searches',
+                  ['q'], kwargs)
+    end
+
+    def fetch_trending_searches(**kwargs)
+      request_api('GET', '/trending_searches',
+                  [], kwargs)
+    end
+
+    def fetch_best_podcasts(**kwargs)
+      request_api('GET', '/best_podcasts',
+                  ['genre_id', 'page', 'region', 'publisher_region', 'language', 'sort', 'safe_mode'], kwargs)
+    end
+
+    def fetch_podcast_by_id(**kwargs)
+      request_api('GET', '/podcasts/{id}',
+                  ['next_episode_pub_date', 'sort'], kwargs)
+    end
+
+    def delete_podcast(**kwargs)
+      request_api('DELETE', '/podcasts/{id}',
+                  ['reason'], kwargs)
+    end
+
+    def fetch_episode_by_id(**kwargs)
+      request_api('GET', '/episodes/{id}',
+                  ['show_transcript'], kwargs)
+    end
+
+    def batch_fetch_episodes(**kwargs)
+      request_api('POST', '/episodes',
+                  [], kwargs)
+    end
+
+    def batch_fetch_podcasts(**kwargs)
+      request_api('POST', '/podcasts',
+                  [], kwargs)
+    end
+
+    def fetch_curated_podcasts_list_by_id(**kwargs)
+      request_api('GET', '/curated_podcasts/{id}',
+                  [], kwargs)
+    end
+
+    def fetch_podcast_genres(**kwargs)
+      request_api('GET', '/genres',
+                  ['top_level_only'], kwargs)
+    end
+
+    def fetch_podcast_regions(**kwargs)
+      request_api('GET', '/regions',
+                  [], kwargs)
+    end
+
+    def fetch_podcast_languages(**kwargs)
+      request_api('GET', '/languages',
+                  [], kwargs)
+    end
+
+    def just_listen(**kwargs)
+      request_api('GET', '/just_listen',
+                  [], kwargs)
+    end
+
+    def fetch_curated_podcasts_lists(**kwargs)
+      request_api('GET', '/curated_podcasts',
+                  ['page'], kwargs)
+    end
+
+    def fetch_recommendations_for_podcast(**kwargs)
+      request_api('GET', '/podcasts/{id}/recommendations',
+                  ['safe_mode'], kwargs)
+    end
+
+    def fetch_recommendations_for_episode(**kwargs)
+      request_api('GET', '/episodes/{id}/recommendations',
+                  ['safe_mode'], kwargs)
+    end
+
+    def submit_podcast(**kwargs)
+      request_api('POST', '/podcasts/submit',
+                  [], kwargs)
+    end
+
+    def fetch_playlist_by_id(**kwargs)
+      request_api('GET', '/playlists/{id}',
+                  ['type', 'last_timestamp_ms', 'sort'], kwargs)
+    end
+
+    def fetch_my_playlists(**kwargs)
+      request_api('GET', '/playlists',
+                  ['sort', 'page'], kwargs)
+    end
+
+    def fetch_audience_for_podcast(**kwargs)
+      request_api('GET', '/podcasts/{id}/audience',
+                  [], kwargs)
+    end
+
+    def fetch_podcasts_by_domain(**kwargs)
+      request_api('GET', '/podcasts/domains/{domain_name}',
+                  ['page'], kwargs)
+    end
+
+    def create_playlist(**kwargs)
+      request_api('POST', '/playlists',
+                  [], kwargs)
+    end
+
+    def update_playlist(**kwargs)
+      request_api('PUT', '/playlists/{id}',
+                  [], kwargs)
+    end
+
+    def add_playlist_item(**kwargs)
+      request_api('POST', '/playlists/{id}/items',
+                  [], kwargs)
+    end
+
+    def delete_playlist_item(**kwargs)
+      request_api('DELETE', '/playlists/{id}/items/{item_id}',
+                  [], kwargs)
+    end
+
+    def update_playlist_item_notes(**kwargs)
+      request_api('PUT', '/playlists/{id}/items/{item_id}',
+                  [], kwargs)
+    end
+
+  end
+end

data/lib/errors.rb

@@ -1,23 +1,19 @@
 # frozen_string_literal: true
 
 module PodcastApi
-    # PodcastApiError is the base error from which all other more specific PodcastApi
-    # errors derive.
-    class PodcastApiError < StandardError
-    end
-  
-    class AuthenticationError < PodcastApiError
-    end
-  
-    class APIConnectionError < PodcastApiError
-    end
-  
-    class InvalidRequestError < PodcastApiError
-    end
-  
-    class RateLimitError < PodcastApiError
+  class PodcastApiError < StandardError
+    attr_reader :response
+
+    def initialize(message = nil, response: nil)
+      @response = response
+      super(message)
     end
-  
-    class NotFoundError < PodcastApiError
-    end           
+  end
+
+  class AuthenticationError < PodcastApiError; end
+  class APIConnectionError < PodcastApiError; end
+  class InvalidRequestError < PodcastApiError; end
+  class PermissionDeniedError < PodcastApiError; end
+  class RateLimitError < PodcastApiError; end
+  class NotFoundError < PodcastApiError; end
 end

data/lib/podcast_api.rb

@@ -1,165 +1,85 @@
 # frozen_string_literal: true
 
 require 'httparty'
-
-# Version
-require 'version'
-require 'errors'
+require 'json'
+require 'uri'
+require_relative 'version'
+require_relative 'errors'
+require_relative 'api_methods'
 
 module PodcastApi
+  class Client
+    include HTTParty
+    include ApiMethods
+
+    BASE_URL_PROD = 'https://listen-api.listennotes.com/api/v2'
+    BASE_URL_TEST = 'https://listen-api-test.listennotes.com/api/v2'
+    attr_reader :base_url
+
+    def initialize(api_key: nil, user_agent: nil, timeout: 30)
+      unless (timeout.is_a?(Integer) || timeout.is_a?(Float)) && timeout.finite? && timeout.positive?
+        raise ArgumentError, 'timeout must be a positive, finite number of seconds'
+      end
+      @base_url = (api_key.nil? || api_key.empty?) ? BASE_URL_TEST : BASE_URL_PROD
+      @headers = {
+        'X-ListenAPI-Key' => api_key.to_s.dup.freeze,
+        'User-Agent' => (user_agent || "podcast-api-ruby #{VERSION}").dup.freeze
+      }.freeze
+      @timeout = timeout
+    end
 
-    class Client
-        include HTTParty
-
-        @@BASE_URL_PROD = 'https://listen-api.listennotes.com/api/v2'
-        @@BASE_URL_TEST = 'https://listen-api-test.listennotes.com/api/v2'
-
-        attr_reader :base_url
-
-        def initialize(api_key: nil, user_agent: nil)
-            @api_key = api_key
-            @base_url = api_key ? @@BASE_URL_PROD : @@BASE_URL_TEST
-            @headers = {
-                'X-ListenAPI-Key' => @api_key ? @api_key : '',
-                'User-Agent' => user_agent ? user_agent : "podcasts-api-ruby #{VERSION}"
-            }
-        end    
-
-        protected
-        def get_response(response:)
-            if response.code == 200
-                return response
-            elsif response.code == 400
-                raise InvalidRequestError.new 'something wrong on your end (client side errors), e.g., missing required parameters'
-            elsif response.code == 401
-                raise AuthenticationError.new 'wrong api key or your account is suspended'
-            elsif response.code == 404
-                raise NotFoundError.new 'endpoint not exist, or podcast / episode not exist'
-            elsif response.code == 429
-                raise RateLimitError.new 'for FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit - https://www.listennotes.com/api/faq/#faq17'
-            else
-                raise PodcastApiError.new 'something wrong on our end (unexpected server errors)'
-            end
-        end
-
-        def send_http_request(http_method, *args)
-            begin
-                response = HTTParty.public_send(http_method, *args)
-            rescue SocketError
-                raise APIConnectionError.new 'Failed to connect to Listen API servers'
-            else
-                return get_response(response: response)
-            end
-        end
-
-        public
-        def search(**kwargs)
-            return send_http_request('get', "#{@base_url}/search", {query: kwargs, headers: @headers})
-        end
-
-        def typeahead(**kwargs)
-            return send_http_request('get', "#{@base_url}/typeahead", {query: kwargs, headers: @headers})
-        end
-        
-        def spellcheck(**kwargs)
-            return send_http_request('get', "#{@base_url}/spellcheck", {query: kwargs, headers: @headers})
-        end
-        
-        def fetch_related_searches(**kwargs)
-            return send_http_request('get', "#{@base_url}/related_searches", {query: kwargs, headers: @headers})
-        end
-        
-        def fetch_trending_searches(**kwargs)
-            return send_http_request('get', "#{@base_url}/trending_searches", {query: kwargs, headers: @headers})
-        end
-
-        def fetch_best_podcasts(**kwargs)
-            return send_http_request('get', "#{@base_url}/best_podcasts", {query: kwargs, headers: @headers})
-        end
-        
-        def fetch_podcast_by_id(**kwargs)
-            id = kwargs.delete(:id)
-            return send_http_request('get', "#{@base_url}/podcasts/#{id}", {query: kwargs, headers: @headers})
-        end        
-
-        def fetch_episode_by_id(**kwargs)
-            id = kwargs.delete(:id)
-            return send_http_request('get', "#{@base_url}/episodes/#{id}", {query: kwargs, headers: @headers})
-        end        
-
-        def batch_fetch_podcasts(**kwargs)
-            @headers['Content-Type'] = 'application/x-www-form-urlencoded'            
-            return send_http_request('post', "#{@base_url}/podcasts", {body: kwargs, headers: @headers})
-        end         
-
-        def batch_fetch_episodes(**kwargs)
-            @headers['Content-Type'] = 'application/x-www-form-urlencoded'            
-            return send_http_request('post', "#{@base_url}/episodes", {body: kwargs, headers: @headers})
-        end              
-
-        def fetch_curated_podcasts_list_by_id(**kwargs)
-            id = kwargs.delete(:id)            
-            return send_http_request('get', "#{@base_url}/curated_podcasts/#{id}", {query: kwargs, headers: @headers})
-        end      
-        
-        def fetch_curated_podcasts_lists(**kwargs)
-            return send_http_request('get', "#{@base_url}/curated_podcasts", {query: kwargs, headers: @headers})
-        end              
-        
-        def fetch_podcast_genres(**kwargs)
-            return send_http_request('get', "#{@base_url}/genres", {query: kwargs, headers: @headers})
-        end         
-        
-        def fetch_podcast_regions(**kwargs)
-            return send_http_request('get', "#{@base_url}/regions", {query: kwargs, headers: @headers})
-        end                   
-
-        def fetch_podcast_languages(**kwargs)
-            return send_http_request('get', "#{@base_url}/languages", {query: kwargs, headers: @headers})
-        end            
-
-        def just_listen(**kwargs)
-            return send_http_request('get', "#{@base_url}/just_listen", {query: kwargs, headers: @headers})
-        end           
+    protected
 
-        def fetch_recommendations_for_podcast(**kwargs)
-            id = kwargs.delete(:id)            
-            return send_http_request('get', "#{@base_url}/podcasts/#{id}/recommendations", {query: kwargs, headers: @headers})
-        end           
-        
-        def fetch_recommendations_for_episode(**kwargs)
-            id = kwargs.delete(:id)            
-            return send_http_request('get', "#{@base_url}/episodes/#{id}/recommendations", {query: kwargs, headers: @headers})
-        end     
-        
-        def fetch_playlist_by_id(**kwargs)
-            id = kwargs.delete(:id)            
-            return send_http_request('get', "#{@base_url}/playlists/#{id}", {query: kwargs, headers: @headers})
-        end     
-        
-        def fetch_my_playlists(**kwargs)
-            return send_http_request('get', "#{@base_url}/playlists", {query: kwargs, headers: @headers})
-        end  
-        
-        def submit_podcast(**kwargs)
-            @headers['Content-Type'] = 'application/x-www-form-urlencoded'            
-            return send_http_request('post', "#{@base_url}/podcasts/submit", {body: kwargs, headers: @headers})
-        end       
-        
-        def delete_podcast(**kwargs)
-            id = kwargs.delete(:id)            
-            return send_http_request('delete', "#{@base_url}/podcasts/#{id}", {query: kwargs, headers: @headers})
+    def request_api(method, path, query_names, kwargs)
+      params = kwargs.transform_keys(&:to_s)
+      path = path.gsub(/\{([^}]+)\}/) do
+        name = Regexp.last_match(1)
+        value = params.delete(name)
+        if value.nil? || value.to_s.empty?
+          raise InvalidRequestError, "Missing required path parameter: #{name}"
         end
+        URI.encode_www_form_component(value.to_s).gsub('+', '%20')
+      end
+      params.reject! { |_, value| value.nil? }
+      query, body = params.partition { |name, _| %w[GET DELETE].include?(method) || query_names.include?(name) }.map(&:to_h)
+      options = {
+        headers: @headers.dup, query: query, timeout: @timeout,
+        # Net::HTTP otherwise retries some write methods on broken connections.
+        follow_redirects: false, max_retries: 0
+      }
+      if %w[POST PUT].include?(method)
+        options[:headers]['Content-Type'] = 'application/x-www-form-urlencoded'
+        options[:body] = URI.encode_www_form(body)
+      end
+      send_http_request(method.downcase, "#{@base_url}#{path}", options)
+    end
 
-        def fetch_audience_for_podcast(**kwargs)
-            id = kwargs.delete(:id)            
-            return send_http_request('get', "#{@base_url}/podcasts/#{id}/audience", {query: kwargs, headers: @headers})
-        end
-        
-        def fetch_podcasts_by_domain(**kwargs)
-            domain_name = kwargs.delete(:domain_name)            
-            return send_http_request('get', "#{@base_url}/podcasts/domains/#{domain_name}", {query: kwargs, headers: @headers})
-        end        
+    def send_http_request(http_method, *args)
+      response = HTTParty.public_send(http_method, *args)
+      get_response(response: response)
+    rescue SocketError, SystemCallError, Timeout::Error, IOError, EOFError, OpenSSL::SSL::SSLError => error
+      raise APIConnectionError, "Failed to connect to Listen API servers (#{error.class})"
     end
 
+    def get_response(response:)
+      return response if (200..299).cover?(response.code)
+
+      error_class = {
+        400 => InvalidRequestError,
+        401 => AuthenticationError,
+        403 => PermissionDeniedError,
+        404 => NotFoundError,
+        429 => RateLimitError
+      }.fetch(response.code, PodcastApiError)
+      message = "Listen API returned HTTP #{response.code}"
+      begin
+        payload = JSON.parse(response.body.to_s)
+        detail = payload['error'] || payload['message'] if payload.is_a?(Hash)
+        message += ": #{detail}" if detail.is_a?(String) && !detail.empty?
+      rescue JSON::ParserError
+        # Preserve a useful status message for HTML, empty, or malformed bodies.
+      end
+      raise error_class.new(message, response: response)
+    end
+  end
 end

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PodcastApi
-  VERSION = "1.1.5"
-end
+  VERSION = '3.0.0'
+end

metadata

@@ -1,29 +1,34 @@
 --- !ruby/object:Gem::Specification
 name: podcast_api
 version: !ruby/object:Gem::Version
-  version: 1.1.5
+  version: 3.0.0
 platform: ruby
 authors:
 - Listen Notes, Inc.
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-18 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.20.0
+        version: 0.24.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.25'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.24.1
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 0.20.0
+        version: '0.25'
 description: Listen Notes is the best podcast search engine and api.  This is the
   official Ruby Gem for the Listen Notes Podcast API. See https://www.PodcastAPI.com/
   for details.
@@ -32,30 +37,23 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- Gemfile
-- Gemfile.lock
 - LICENSE
 - README.md
-- RakeFile
-- examples/Gemfile
-- examples/Gemfile.lock
-- examples/sample.rb
+- lib/api-contract.json
+- lib/api_methods.rb
 - lib/errors.rb
 - lib/podcast_api.rb
 - lib/version.rb
-- podcast_api.gemspec
-- rakefile.rb
 homepage: https://www.PodcastAPI.com/
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/ListenNotes/podcast-api-ruby/issues
   changelog_uri: https://github.com/ListenNotes/podcast-api-ruby/releases
-  documentation_uri: https://www.listennotes.com/podcast-api/docs/
+  documentation_uri: https://www.listennotes.com/api/docs/
   github_repo: https://github.com/ListenNotes/podcast-api-ruby
   homepage_uri: https://www.PodcastAPI.com/
   source_code_uri: https://github.com/ListenNotes/podcast-api-ruby
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -63,15 +61,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Ruby bindings for the Listen Notes Podcast API
 test_files: []

data/Gemfile

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-gemspec
-
-group :development do
-  gem "mocha"
-  gem "rake"
-  gem "test-unit"
-  gem "bundler"
-end

data/Gemfile.lock

@@ -1,34 +0,0 @@
-PATH
-  remote: .
-  specs:
-    podcast_api (1.1.5)
-      httparty (~> 0.20.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    httparty (0.20.0)
-      mime-types (~> 3.0)
-      multi_xml (>= 0.5.2)
-    mime-types (3.4.1)
-      mime-types-data (~> 3.2015)
-    mime-types-data (3.2023.0218.1)
-    mocha (1.12.0)
-    multi_xml (0.6.0)
-    power_assert (2.0.0)
-    rake (13.0.3)
-    test-unit (3.4.1)
-      power_assert
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  bundler
-  mocha
-  podcast_api!
-  rake
-  test-unit
-
-BUNDLED WITH
-   1.17.2

data/RakeFile

@@ -1,9 +0,0 @@
-require 'rake/testtask'
-
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'test'
-  test.test_files = FileList['tests/*_test.rb']
-end
-
-desc 'Run Tests'
-task :default => :test

data/examples/Gemfile

@@ -1,3 +0,0 @@
-source 'https://rubygems.org'
-
-gem "podcast_api", path: "../"

data/examples/Gemfile.lock

@@ -1,25 +0,0 @@
-PATH
-  remote: ..
-  specs:
-    podcast_api (1.1.5)
-      httparty (~> 0.20.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    httparty (0.20.0)
-      mime-types (~> 3.0)
-      multi_xml (>= 0.5.2)
-    mime-types (3.4.1)
-      mime-types-data (~> 3.2015)
-    mime-types-data (3.2023.0218.1)
-    multi_xml (0.6.0)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  podcast_api!
-
-BUNDLED WITH
-   1.17.2