Merge 81219e3 into c87a0d7

.travis.yml

@@ -7,3 +7,6 @@ cache: bundler
 rvm:
   - 2.4.1
   - 2.6.5
+env:
+  global:
+    - RUN_ALL_TESTS=true

CHANGELOG.rdoc

@@ -1,10 +1,17 @@
 = CHANGELOG
 
-== Unreleased (0.14.1)
+== Unreleased (0.15.0)
 
+* *DEPRECATION* When creating an `OEmbed::Provider` instance, specifying the format via positional argument is now deprecated. Please use a named argument instead: `OEmbed::Provider.new(@endpoint_url, format: :json)`
+* *DEPRECATION* Do not use the `new` method for `Instagram`, `FacebookPost`, or `FacebookVideo` providers to set your access token. Instead either use the `OEMBED_FACEBOOK_TOKEN` environment variable or call `Instagram.access_token = @your_token`.
+* Fix Issue #77: Built-in Instagram & Facebook providers are now instances again.
+* Add support for `OEmbed::Provider` instances with `required_query_params` (like access tokens), where the provider will fail to answer until it is fully configured.
+* Support focused rspec tests for local development (e.g. "fcontext" or "fit")
+* Fix a few typos in documentation & tests; Pull #76 (Inge Jørgensen)
 
 == 0.14.0 - 5 November 2020
 
+* *BREAKING* Built-in providers for Instagram & Facebook are now classes, not instances, and therefore can't manually be registered via `OEmbed::Providers.register(OEmbed::Providers::Instagram)`; See Issue #77
 * Add support for Facebook/Instagram access tokens; Pull #75 (Inge Jørgensen)
 
 == 0.13.1 - 25 May 2020

lib/oembed.rb

@@ -8,6 +8,7 @@
 require 'oembed/provider'
 require 'oembed/provider_discovery'
 require 'oembed/providers'
+require 'oembed/providers/builtin_providers'
 require 'oembed/response'
 require 'oembed/response/photo'
 require 'oembed/response/video'

lib/oembed/provider.rb

@@ -36,24 +36,46 @@ class Provider
     # In actual requests to this Provider, this string will be replaced with a String
     # representing the request format (e.g. "json").
     #
-    # If give, the format should be the name of the default format for all request
+    # The `format:` option should be the name of the default format for all request
     # to this Provider (e.g. 'json'). Defaults to OEmbed::Formatter.default
     #
+    # # @deprecated *Note*: The `positional_format` is deprecated. Please used the named argument instead.
+    #
+    # The `required_query_params:` option should be a Hash
+    # representing query params that will be appended to the endpoint on each request
+    # and the optional name of an environment variable (i.e. ENV) whose value will be used
+    #
     # For example:
     #   # If requests should be sent to:
     #   # "http://my.service.com/oembed?format=#{OEmbed::Formatter.default}"
     #   @provider = OEmbed::Provider.new("http://my.service.com/oembed")
     #
     #   # If requests should be sent to:
     #   # "http://my.service.com/oembed.xml"
-    #   @xml_provider = OEmbed::Provider.new("http://my.service.com/oembed.{format}", :xml)
-    def initialize(endpoint, format = OEmbed::Formatter.default)
+    #   @xml_provider = OEmbed::Provider.new("http://my.service.com/oembed.{format}", format: :xml)
+    #
+    #   # If the endpoint requires an `access_token` be specified:
+    #   @provider_with_auth = OEmbed::Provider.new("http://my.service.com/oembed", required_query_params: { access_token: 'MY_SERVICE_ACCESS_TOKEN' })
+    #   # You can optionally override the value from `ENV['MY_SERVICE_ACCESS_TOKEN']`
+    #   @provider_with_auth.access_token = @my_access_token
+    def initialize(endpoint, positional_format = OEmbed::Formatter.default, format: nil, required_query_params: {})
       endpoint_uri = URI.parse(endpoint.gsub(/[\{\}]/,'')) rescue nil
       raise ArgumentError, "The given endpoint isn't a valid http(s) URI: #{endpoint.to_s}" unless endpoint_uri.is_a?(URI::HTTP)
 
+      @required_query_params = {}
+      required_query_params.each do |param, default_env_var|
+        param = param.to_sym
+        @required_query_params[param] = default_env_var ? ENV[default_env_var] : nil
+
+        # Define a getter and a setter for each required_query_param
+        define_singleton_method("#{param}") { @required_query_params[param] } unless respond_to?("#{param}")
+        define_singleton_method("#{param}=") { |val| set_required_query_params(param, val) } unless respond_to?("#{param}=")
+      end
+      required_query_params_set?(reset_cache: true)
+
       @endpoint = endpoint
       @urls = []
-      @format = format
+      @format = format || positional_format
     end
 
     # Adds the given url scheme to this Provider instance.
@@ -75,6 +97,28 @@ def <<(url)
       @urls << url
     end
 
+    # Given the name of a required_query_param and a value
+    # store that value internally, so that it can be sent along
+    # with requests to this provider's endpoint.
+    # Raises an ArgumentError if the given param is not listed with required_query_params
+    # during instantiation.
+    def set_required_query_params(param, val)
+      raise ArgumentError.new("This provider does NOT have a required_query_param named #{param.inspect}") unless @required_query_params.has_key?(param)
+
+      @required_query_params[param] = val.nil? ? nil : ::CGI.escape(val.to_s)
+
+      required_query_params_set?(reset_cache: true)
+
+      @required_query_params[param]
+    end
+
+    # Returns true if all of this provider's required_query_params have a value
+    def required_query_params_set?(reset_cache: false)
+      return @all_required_query_params_set unless reset_cache || @all_required_query_params_set.nil?
+
+      @all_required_query_params_set = !@required_query_params.values.include?(nil)
+    end
+
     # Send a request to the Provider endpoint to get information about the
     # given url and return the appropriate OEmbed::Response.
     #
@@ -92,18 +136,22 @@ def get(url, query = {})
 
     # Determine whether the given url is supported by this Provider by matching
     # against the Provider's URL schemes.
+    # It will always return false of a provider has required_query_params that are not set.
     def include?(url)
+      return false unless required_query_params_set?
       @urls.empty? || !!@urls.detect{ |u| u =~ url }
     end
 
     # @deprecated *Note*: This method will be made private in the future.
     def build(url, query = {})
       raise OEmbed::NotFound, url unless include?(url)
 
-      query = query.merge({:url => ::CGI.escape(url)})
       query.delete(:timeout)
       query.delete(:max_redirects)
 
+      query = query.merge(@required_query_params)
+      query = query.merge({:url => ::CGI.escape(url)})
+
       # TODO: move this code exclusively into the get method, once build is private.
       this_format = (query[:format] ||= @format.to_s).to_s