internetdata 2.2.0 → 2.3.0

data/lib/internetdata/models/token_response.rb

@@ -0,0 +1,258 @@
+=begin
+#InternetData API
+
+#The InternetData API: download the databases your organization is licensed for, and manage the account behind them.  See https://docs.internetdata.io for guides and https://github.com/internetdata for the official client libraries. 
+
+The version of the OpenAPI document: 2026.09.21
+Contact: support@internetdata.io
+Generated by: https://openapi-generator.tech
+Generator version: 7.25.0
+
+=end
+
+require 'date'
+require 'time'
+
+module InternetData
+  class TokenResponse < ApiModelBase
+    attr_accessor :access_token
+
+    # Always `Bearer`.
+    attr_accessor :token_type
+
+    # Seconds until the access token expires.
+    attr_accessor :expires_in
+
+    # Always returned. A refresh consumes the token it presents, so keep this one.
+    attr_accessor :refresh_token
+
+    # What was actually granted, which may be narrower than what was asked for.
+    attr_accessor :scope
+
+    # Not part of OAuth. The ID of the API key the person picked when they approved, returned by every grant while this authorization may still read that key back. Absent when no key was picked, or when the person's role no longer allows reading keys back. 
+    attr_accessor :apikey_id
+
+    # Not part of OAuth. The API key itself, so a device ends up holding an ordinary key. Returned by the device code and authorization code grants only, never by a refresh, and only alongside `mslm:apikey_id`. Absent when that key's secret cannot be read back, which is the case for a key created before keys could be shown again in the console; a rotated key can be. 
+    attr_accessor :apikey
+
+    # Attribute mapping from ruby-style variable name to JSON key.
+    def self.attribute_map
+      {
+        :'access_token' => :'access_token',
+        :'token_type' => :'token_type',
+        :'expires_in' => :'expires_in',
+        :'refresh_token' => :'refresh_token',
+        :'scope' => :'scope',
+        :'apikey_id' => :'mslm:apikey_id',
+        :'apikey' => :'mslm:apikey'
+      }
+    end
+
+    # Returns attribute mapping this model knows about
+    def self.acceptable_attribute_map
+      attribute_map
+    end
+
+    # Returns all the JSON keys this model knows about
+    def self.acceptable_attributes
+      acceptable_attribute_map.values
+    end
+
+    # Attribute type mapping.
+    def self.openapi_types
+      {
+        :'access_token' => :'String',
+        :'token_type' => :'String',
+        :'expires_in' => :'Integer',
+        :'refresh_token' => :'String',
+        :'scope' => :'String',
+        :'apikey_id' => :'String',
+        :'apikey' => :'String'
+      }
+    end
+
+    # List of attributes with nullable: true
+    def self.openapi_nullable
+      Set.new([
+      ])
+    end
+
+    # Initializes the object
+    # @param [Hash] attributes Model attributes in the form of hash
+    def initialize(attributes = {})
+      if (!attributes.is_a?(Hash))
+        fail ArgumentError, "The input argument (attributes) must be a hash in `InternetData::TokenResponse` initialize method"
+      end
+
+      # check to see if the attribute exists and convert string to symbol for hash key
+      acceptable_attribute_map = self.class.acceptable_attribute_map
+      attributes = attributes.each_with_object({}) { |(k, v), h|
+        if (!acceptable_attribute_map.key?(k.to_sym))
+          fail ArgumentError, "`#{k}` is not a valid attribute in `InternetData::TokenResponse`. Please check the name to make sure it's valid. List of attributes: " + acceptable_attribute_map.keys.inspect
+        end
+        h[k.to_sym] = v
+      }
+
+      if attributes.key?(:'access_token')
+        self.access_token = attributes[:'access_token']
+      else
+        self.access_token = nil
+      end
+
+      if attributes.key?(:'token_type')
+        self.token_type = attributes[:'token_type']
+      else
+        self.token_type = nil
+      end
+
+      if attributes.key?(:'expires_in')
+        self.expires_in = attributes[:'expires_in']
+      else
+        self.expires_in = nil
+      end
+
+      if attributes.key?(:'refresh_token')
+        self.refresh_token = attributes[:'refresh_token']
+      end
+
+      if attributes.key?(:'scope')
+        self.scope = attributes[:'scope']
+      end
+
+      if attributes.key?(:'apikey_id')
+        self.apikey_id = attributes[:'apikey_id']
+      end
+
+      if attributes.key?(:'apikey')
+        self.apikey = attributes[:'apikey']
+      end
+    end
+
+    # Show invalid properties with the reasons. Usually used together with valid?
+    # @return Array for valid properties with the reasons
+    def list_invalid_properties
+      warn '[DEPRECATED] the `list_invalid_properties` method is obsolete'
+      invalid_properties = Array.new
+      if @access_token.nil?
+        invalid_properties.push('invalid value for "access_token", access_token cannot be nil.')
+      end
+
+      if @token_type.nil?
+        invalid_properties.push('invalid value for "token_type", token_type cannot be nil.')
+      end
+
+      if @expires_in.nil?
+        invalid_properties.push('invalid value for "expires_in", expires_in cannot be nil.')
+      end
+
+      invalid_properties
+    end
+
+    # Check to see if the all the properties in the model are valid
+    # @return true if the model is valid
+    def valid?
+      warn '[DEPRECATED] the `valid?` method is obsolete'
+      return false if @access_token.nil?
+      return false if @token_type.nil?
+      return false if @expires_in.nil?
+      true
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] access_token Value to be assigned
+    def access_token=(access_token)
+      if access_token.nil?
+        fail ArgumentError, 'access_token cannot be nil'
+      end
+
+      @access_token = access_token
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] token_type Value to be assigned
+    def token_type=(token_type)
+      if token_type.nil?
+        fail ArgumentError, 'token_type cannot be nil'
+      end
+
+      @token_type = token_type
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] expires_in Value to be assigned
+    def expires_in=(expires_in)
+      if expires_in.nil?
+        fail ArgumentError, 'expires_in cannot be nil'
+      end
+
+      @expires_in = expires_in
+    end
+
+    # Checks equality by comparing each attribute.
+    # @param [Object] Object to be compared
+    def ==(o)
+      return true if self.equal?(o)
+      self.class == o.class &&
+          access_token == o.access_token &&
+          token_type == o.token_type &&
+          expires_in == o.expires_in &&
+          refresh_token == o.refresh_token &&
+          scope == o.scope &&
+          apikey_id == o.apikey_id &&
+          apikey == o.apikey
+    end
+
+    # @see the `==` method
+    # @param [Object] Object to be compared
+    def eql?(o)
+      self == o
+    end
+
+    # Calculates hash code according to all attributes.
+    # @return [Integer] Hash code
+    def hash
+      [access_token, token_type, expires_in, refresh_token, scope, apikey_id, apikey].hash
+    end
+
+    # Builds the object from hash
+    # @param [Hash] attributes Model attributes in the form of hash
+    # @return [Object] Returns the model itself
+    def self.build_from_hash(attributes)
+      return nil unless attributes.is_a?(Hash)
+      attributes = attributes.transform_keys(&:to_sym)
+      transformed_hash = {}
+      openapi_types.each_pair do |key, type|
+        if attributes.key?(attribute_map[key]) && attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = nil
+        elsif type =~ /\AArray<(.*)>/i
+          # check to ensure the input is an array given that the attribute
+          # is documented as an array but the input is not
+          if attributes[attribute_map[key]].is_a?(Array)
+            transformed_hash["#{key}"] = attributes[attribute_map[key]].map { |v| _deserialize($1, v) }
+          end
+        elsif !attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = _deserialize(type, attributes[attribute_map[key]])
+        end
+      end
+      new(transformed_hash)
+    end
+
+    # Returns the object in the form of hash
+    # @return [Hash] Returns the object in the form of hash
+    def to_hash
+      hash = {}
+      self.class.attribute_map.each_pair do |attr, param|
+        value = self.send(attr)
+        if value.nil?
+          is_nullable = self.class.openapi_nullable.include?(attr)
+          next if !is_nullable || (is_nullable && !instance_variable_defined?(:"@#{attr}"))
+        end
+
+        hash[param] = _to_hash(value)
+      end
+      hash
+    end
+
+  end
+
+end

data/lib/internetdata/oauth_api.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module InternetData
+  # Signing a person in with OAuth, reached as `client.oauth`.
+  #
+  # A program on the person's own machine starts a device sign-in, shows them a
+  # code to approve in their browser, and waits for the tokens, which can carry
+  # one of their API keys so nobody pastes a key by hand. Only a registered
+  # client ID works; they are issued on request from support@internetdata.io.
+  #
+  # No request made here carries the API key this client was built with, and a
+  # client built without one works exactly the same. Every method takes
+  # `timeout:`, seconds per attempt, for that call alone.
+  class OauthApi
+    METADATA_PATH = '/.well-known/oauth-authorization-server'
+    DEVICE_AUTHORIZATION_PATH = '/oauth/device_authorization'
+    TOKEN_PATH = '/oauth/token'
+    REVOKE_PATH = '/oauth/revoke'
+    DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code'
+
+    # The members a 2xx must carry for its type to mean anything.
+    REQUIRED = {
+      OauthMetadata => %i[issuer authorization_endpoint token_endpoint],
+      DeviceAuthorization => %i[device_code user_code verification_uri expires_in interval],
+      TokenResponse => %i[access_token token_type expires_in],
+    }.freeze
+
+    def initialize(transport, retries:)
+      @transport = transport
+      @retries = retries
+      # The poll's wait and its monotonic clock, which a test replaces together.
+      @wait = ->(seconds) { sleep(seconds) }
+      @now = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+    end
+
+    # The authorization server's discovery document.
+    #
+    # @return [OauthMetadata]
+    def metadata(timeout: nil)
+      Retries.with_retries(@retries) do
+        decode(OauthMetadata, @transport.oauth_request(:GET, METADATA_PATH, timeout: timeout).run)
+      end
+    end
+
+    # Start a device sign-in: show the person `user_code` and `verification_uri`,
+    # then {#poll_device_token}.
+    #
+    # @param scope [String, nil] space-delimited, sent as given; the server grants
+    #   what this client may ask for and silently drops the rest.
+    # @param resource [String, nil] the API the tokens are for.
+    # @return [DeviceAuthorization]
+    def device_authorization(client_id, scope: nil, resource: nil, timeout: nil)
+      form = { 'client_id' => client_id, 'scope' => scope, 'resource' => resource }.compact
+      Retries.with_retries(@retries) do
+        request = @transport.oauth_request(:POST, DEVICE_AUTHORIZATION_PATH, form: form, timeout: timeout)
+        decode(DeviceAuthorization, request.run)
+      end
+    end
+
+    # Exchange a device code for tokens, once. Until the person approves this
+    # raises {OauthRequestError} coded `authorization_pending`;
+    # {#poll_device_token} is the loop that waits for them.
+    #
+    # Never retried: the server spends the code when it answers, so a retry after
+    # a lost success could only fail and lose the tokens.
+    #
+    # @return [TokenResponse] with `apikey_id` and `apikey` when the person picked a key.
+    def exchange_device_code(client_id, device_code, timeout: nil)
+      form = { 'grant_type' => DEVICE_CODE_GRANT, 'device_code' => device_code, 'client_id' => client_id }
+      exchange(form, timeout)
+    end
+
+    # Exchange a refresh token for a new pair. The token presented is spent, so
+    # keep the `refresh_token` this returns. Never retried, for the same reason as
+    # {#exchange_device_code}.
+    #
+    # @return [TokenResponse] which may name the key in `apikey_id`, but never carries `apikey`.
+    def exchange_refresh_token(client_id, refresh_token, timeout: nil)
+      form = { 'grant_type' => 'refresh_token', 'refresh_token' => refresh_token, 'client_id' => client_id }
+      exchange(form, timeout)
+    end
+
+    # Revoke an access or refresh token. A refresh token ends the whole grant and
+    # every token it issued, which is how a machine signs out.
+    #
+    # @return [nil]
+    def revoke(client_id, token, timeout: nil)
+      form = { 'token' => token, 'client_id' => client_id }
+      Retries.with_retries(@retries) do
+        request = @transport.oauth_request(:POST, REVOKE_PATH, form: form, timeout: timeout)
+        Transport.oauth_success!(request.run)
+      end
+      nil
+    end
+
+    # Wait for the person to approve a device sign-in, and return its tokens.
+    #
+    # Waits `device.interval` seconds before EVERY exchange, the first included,
+    # and five seconds longer for good each time the server answers `slow_down`.
+    # Raises {OauthAccessDeniedError} when the person refuses and
+    # {OauthExpiredTokenError} when the code expires, including locally, with no
+    # status, once `device.expires_in` seconds have passed since this call. Any
+    # other failure, a timeout or an outage included, ends the wait unchanged;
+    # calling again with the same device is safe until the code expires.
+    #
+    # There is no way to cancel it from outside: it blocks until one of those
+    # outcomes, so run it where blocking is acceptable.
+    #
+    # @param timeout [Numeric, nil] bounds each exchange, never the whole wait.
+    # @return [TokenResponse]
+    def poll_device_token(client_id, device, timeout: nil)
+      interval = device.interval >= 1 ? device.interval : 5
+      deadline = @now.call + device.expires_in
+      loop do
+        @wait.call(interval)
+        raise OauthExpiredTokenError, 'expired_token' if @now.call >= deadline
+
+        begin
+          return exchange_device_code(client_id, device.device_code, timeout: timeout)
+        rescue OauthRequestError => e
+          case e.error_code
+          when 'slow_down' then interval += 5
+          when 'authorization_pending' then next
+          else raise
+          end
+        end
+      end
+    end
+
+    private
+
+    def exchange(form, timeout)
+      decode(TokenResponse, @transport.oauth_request(:POST, TOKEN_PATH, form: form, timeout: timeout).run)
+    end
+
+    # Only the members the type declares are read, each checked against the type
+    # the spec gives it, so an absent member stays nil and an empty `scope` stays
+    # an empty string. A 2xx that is not the type is the server's fault.
+    def decode(type, response)
+      body = Transport.oauth_object(response)
+      type.attribute_map.each do |member, wire|
+        value = body[wire.to_s]
+        if value.nil?
+          next unless REQUIRED.fetch(type).include?(member)
+
+          raise Error.new(:server_error, "the answer carried no #{wire}", status: response.code)
+        end
+        next if typed?(type.openapi_types.fetch(member), value)
+
+        raise Error.new(:server_error, "the answer's #{wire} is not a #{type.openapi_types[member]}",
+                        status: response.code)
+      end
+      type.build_from_hash(body)
+    end
+
+    def typed?(type, value)
+      case type
+      when :String then value.is_a?(String)
+      when :Integer then value.is_a?(Integer)
+      when :Boolean then [true, false].include?(value)
+      when :'Array<String>' then value.is_a?(Array) && value.all?(String)
+      else raise ArgumentError, "no check for a member typed #{type}"
+      end
+    end
+  end
+end

data/lib/internetdata/transport.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'uri'
 
 module InternetData
@@ -87,5 +88,67 @@ module InternetData
       options[:cainfo] = @config.ssl_ca_cert if @config.ssl_ca_cert
       Typhoeus::Request.new(url, options)
     end
+
+    # A request to the authorization server, which carries NO credential whatever
+    # this client was built with: these endpoints have no use for the API key, and
+    # on the token endpoint an `Authorization` header reads as client
+    # authentication, which a public client does not have.
+    #
+    # The form is encoded here rather than by curl, so a `+` in a value leaves as
+    # `%2B` and never arrives as a space.
+    def oauth_request(http_method, path, form: nil, timeout: nil)
+      headers = { 'Accept' => 'application/json' }
+      headers['Content-Type'] = 'application/x-www-form-urlencoded' unless form.nil?
+      request = build_request(http_method, path, header_params: headers, auth_names: [], timeout: timeout)
+      request.options[:body] = URI.encode_www_form(form) unless form.nil?
+      request
+    end
+
+    # The JSON object a 2xx OAuth answer carries. A refusal the authorization
+    # server words as an RFC 6749 error raises that; anything else that is not a
+    # 2xx raises the ordinary error its status maps to.
+    def self.oauth_object(response)
+      oauth_success!(response)
+      parse_object(response)
+    end
+
+    def self.oauth_success!(response)
+      raise Error.from_transport(response) if transport_failure?(response)
+      return if response.success?
+
+      raise oauth_refusal(response) || Error.from_status(response.code, response.headers, response.body)
+    end
+
+    # Only a 4xx whose body is a JSON object with a STRING `error` is the
+    # authorization server's own refusal. A 5xx is an outage whatever its body
+    # says, and a gateway's page names no OAuth code at all.
+    def self.oauth_refusal(response)
+      return nil unless (400..499).cover?(response.code)
+
+      body = JSON.parse(response.body.to_s)
+      return nil unless body.is_a?(Hash) && body['error'].is_a?(String)
+
+      description = body['error_description'].is_a?(String) ? body['error_description'] : nil
+      OauthRequestError.for_code(body['error'], description, status: response.code, headers: response.headers)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def self.transport_failure?(response)
+      response.timed_out? || response.code.to_i.zero?
+    end
+
+    def self.parse_object(response)
+      body = JSON.parse(response.body.to_s)
+      return body if body.is_a?(Hash)
+
+      raise Error.new(:server_error, 'the API answered with something other than an object',
+                      status: response.code)
+    rescue JSON::ParserError => e
+      raise Error.new(:server_error, "could not parse the response body: #{e.message}",
+                      status: response.code)
+    end
+
+    private_class_method :transport_failure?, :parse_object, :oauth_refusal
   end
 end

data/lib/internetdata/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module InternetData
-  VERSION = '2.2.0'
+  VERSION = '2.3.0'
 end

data/lib/internetdata.rb

@@ -16,6 +16,7 @@ require 'internetdata/errors'
 require 'internetdata/retries'
 require 'internetdata/transport'
 require 'internetdata/database_api'
+require 'internetdata/oauth_api'
 require 'internetdata/client'
 
 # The official Ruby client library for the InternetData API.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: internetdata
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Mslm Dev
@@ -50,10 +50,14 @@ files:
 - lib/internetdata/models/database_metadata_column.rb
 - lib/internetdata/models/database_version.rb
 - lib/internetdata/models/db_checksums.rb
+- lib/internetdata/models/device_authorization.rb
 - lib/internetdata/models/download.rb
 - lib/internetdata/models/download_list.rb
 - lib/internetdata/models/error_envelope.rb
+- lib/internetdata/models/oauth_metadata.rb
 - lib/internetdata/models/standing.rb
+- lib/internetdata/models/token_response.rb
+- lib/internetdata/oauth_api.rb
 - lib/internetdata/retries.rb
 - lib/internetdata/transport.rb
 - lib/internetdata/version.rb