didit-sdk 1.0.0

data/lib/didit/model.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+require "time"
+
+module Didit
+  # Base class of every response type.
+  #
+  # A model wraps the JSON object the API returned. Typed readers convert values
+  # on access (nested objects become models, date-times become +Time+) and never
+  # raise: a value that does not have the documented shape is returned as is.
+  # Fields the SDK does not know yet stay readable with {#[]} and {#to_h}.
+  #
+  # Field types are written as +:string+, +:integer+, +:float+, +:boolean+,
+  # +:datetime+, +:date+, +:any+, a model class (or its name under +Didit::Types+),
+  # +[:array, type]+, +[:map, type]+ or +[:union, [type, ...]]+ (the first type that fits the value).
+  class Model
+    class << self
+      # The typed fields of this class and its ancestors: reader name => [JSON name, type].
+      #
+      # @return [Hash{Symbol => Array}]
+      def fields
+        @fields ||= begin
+          parent = superclass
+          parent.is_a?(Class) && parent < Model ? Model.fields_of(parent) : {}
+        end
+      end
+
+      # @api private
+      def fields_of(klass)
+        # @type var klass: singleton(Model)
+        klass.fields.dup
+      end
+
+      # Declares a typed reader +name+ for the JSON property +wire+.
+      #
+      # @return [void]
+      def field(name, wire, type = :any)
+        fields[name] = [wire, type]
+        define_method(name) do
+          # @type self: Didit::Model
+          read_field(name)
+        end
+      end
+
+      # Builds an instance from a parsed JSON value; anything but an object is returned unchanged.
+      def from_json(value)
+        value.is_a?(Hash) ? new(value) : value
+      end
+
+      # Converts a parsed JSON +value+ to +type+, leniently.
+      def coerce(value, type)
+        return value if value.nil?
+
+        case type
+        when Array then coerce_container(value, type)
+        when :float then value.is_a?(Integer) ? value.to_f : value
+        when :datetime then parse_time(value)
+        when :date then parse_date(value)
+        when Symbol then value
+        else coerce_model(value, type)
+        end
+      end
+
+      private
+
+      def coerce_container(value, type)
+        kind, inner = type
+        if kind == :union
+          member = inner.find { |m| fits?(value, m) }
+          member ? coerce(value, member) : value
+        elsif kind == :array && value.is_a?(Array)
+          value.map { |item| coerce(item, inner) }
+        elsif kind == :map && value.is_a?(Hash)
+          value.transform_values { |item| coerce(item, inner) }
+        else
+          value
+        end
+      end
+
+      # Whether +value+ has the JSON shape of +type+ (for unions).
+      def fits?(value, type)
+        case value
+        when Hash then type.is_a?(String) || type.is_a?(Class) || (type.is_a?(Array) && type.first == :map)
+        when Array then type.is_a?(Array) && type.first == :array
+        when String then %i[string datetime date].include?(type)
+        when Integer then %i[integer float].include?(type)
+        when Float then type == :float
+        when true, false then type == :boolean
+        else false
+        end
+      end
+
+      def coerce_model(value, type)
+        klass = type.is_a?(String) ? Didit::Types.const_get(type, false) : type
+        value.is_a?(Hash) && klass.is_a?(Class) && klass <= Model ? klass.new(value) : value
+      end
+
+      def parse_time(value)
+        return value unless value.is_a?(String)
+
+        Time.iso8601(value.sub(" ", "T"))
+      rescue ArgumentError
+        value
+      end
+
+      def parse_date(value)
+        return value unless value.is_a?(String)
+
+        Date.iso8601(value)
+      rescue ArgumentError
+        value
+      end
+    end
+
+    # @param data [Hash] the JSON object, as parsed (string keys); symbol keys are accepted too
+    def initialize(data = {})
+      raise ArgumentError, "#{self.class.name} needs a Hash, got #{data.class}" unless data.is_a?(Hash)
+
+      # @type var normalized: Hash[String, untyped]
+      normalized = data.each_key.all?(String) ? (_ = data.dup) : data.transform_keys(&:to_s)
+      @data = normalized.freeze
+      @cache = {}
+    end
+
+    # The raw JSON value of any property, known to the SDK or not.
+    #
+    # @param key [String, Symbol] the property name as the API sends it
+    def [](key)
+      @data[key.to_s]
+    end
+
+    # Whether the API sent the property (also when its value is +null+).
+    def key?(key)
+      @data.key?(key.to_s)
+    end
+
+    # The JSON object as a Hash with symbol keys, nested objects included.
+    #
+    # @return [Hash{Symbol => Object}]
+    def to_h
+      Model.symbolize(@data)
+    end
+
+    # @return [String] the JSON object, unchanged
+    def to_json(*args)
+      JSON.generate(@data, args.first)
+    end
+
+    # Pattern matching on the typed readers: +in {status: "Approved"}+.
+    def deconstruct_keys(keys)
+      fields = self.class.fields
+      # @type var out: Hash[Symbol, untyped]
+      out = {}
+      (keys || fields.keys).each { |name| out[name] = public_send(name) if fields.key?(name) }
+      out
+    end
+
+    def ==(other)
+      other.class == self.class && other.raw_data == @data
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, @data].hash
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@data.inspect}>"
+    end
+    alias to_s inspect
+
+    # @api private
+    def self.symbolize(value)
+      case value
+      when Hash then value.to_h { |k, v| [k.to_sym, symbolize(v)] }
+      when Array then value.map { |v| symbolize(v) }
+      else value
+      end
+    end
+
+    protected
+
+    # @api private
+    def raw_data
+      @data
+    end
+
+    private
+
+    def read_field(name)
+      return @cache[name] if @cache.key?(name)
+
+      wire, type = self.class.fields.fetch(name)
+      @cache[name] = Model.coerce(@data[wire], type)
+    end
+  end
+end

data/lib/didit/page.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Didit
+  # One page of a list (docs/DESIGN.md section 8): the API's +{count, next, previous, results}+.
+  #
+  #   page = didit.sessions.list(limit: 50)
+  #   page.each { |session| ... }               # this page
+  #   page.auto_paging_each { |session| ... }   # every page, fetched as needed
+  #
+  # +total_count+ is the API's +count+ (Enumerable#count counts the items of this page).
+  class Page
+    include Enumerable
+
+    # @return [Array] the items of this page, typed
+    attr_reader :results
+
+    # @api private
+    def initialize(client:, prepared:, item:, data:, seen: nil)
+      @client = client
+      @prepared = prepared
+      @item = item
+      @data = data.is_a?(Hash) ? data : {}
+      list = @data["results"]
+      @results = list.is_a?(Array) ? list.map { |value| Model.coerce(value, item) } : []
+      @seen = seen || [Page.normalize(prepared.uri)]
+    end
+
+    # @return [Integer, nil] the total number of items across pages
+    def total_count
+      @data["count"]
+    end
+
+    # @return [String, nil]
+    def next_url
+      link(@data["next"])
+    end
+
+    # @return [String, nil]
+    def previous_url
+      link(@data["previous"])
+    end
+
+    # Iterates the items of this page.
+    def each(&)
+      return enum_for(:each) unless block_given?
+
+      results.each(&)
+      self
+    end
+
+    def next_page?
+      !next_url.nil?
+    end
+
+    # Fetches the next page, or returns nil on the last one.
+    # @return [Didit::Page, nil]
+    def next_page
+      url = next_url
+      return nil if url.nil?
+
+      target = resolve(url)
+      key = Page.normalize(target)
+      if @seen.include?(key)
+        raise APIResponseValidationError.new(
+          "The API returned the pagination link #{Internal::Util.display_url(target)} twice; stopping to avoid " \
+          "a loop.", status: 200
+        )
+      end
+      @client.fetch_page(@prepared, target, @item, @seen + [key])
+    end
+
+    # Iterates every item of every page, fetching pages as needed.
+    # @return [Enumerator] without a block
+    def auto_paging_each(&block)
+      return enum_for(:auto_paging_each) unless block
+
+      # @type var page: Page[untyped]?
+      page = self
+      while page
+        page.results.each(&block)
+        page = page.next_page
+      end
+      nil
+    end
+
+    # The raw value of any property of the page.
+    def [](key)
+      @data[key.to_s]
+    end
+
+    # @return [Hash{Symbol => Object}]
+    def to_h
+      Model.symbolize(@data)
+    end
+
+    def inspect
+      "#<Didit::Page total_count=#{total_count.inspect} results=#{results.size} next=#{next_page?}>"
+    end
+
+    # @api private
+    def self.normalize(uri)
+      uri = uri.dup
+      uri.fragment = nil
+      # @type var query: Array[[String, String]]
+      query = uri.query ? URI.decode_www_form(uri.query).sort : []
+      [Internal::Util.origin(uri), uri.path, query]
+    end
+
+    private
+
+    def link(value)
+      value.is_a?(String) && !value.strip.empty? ? value.strip : nil
+    end
+
+    def resolve(url)
+      target = URI.join(@prepared.uri.to_s, url)
+      unless %w[http https].include?(target.scheme) && Internal::Util.origin(target) == @prepared.origin
+        raise APIResponseValidationError.new(
+          "Refusing to follow a pagination link to another origin (#{Internal::Util.origin(target)}); " \
+          "the API key is only sent to #{@prepared.origin}.", status: 200
+        )
+      end
+      target
+    rescue URI::Error => e
+      raise APIResponseValidationError.new("The API returned an invalid pagination link: #{e.message}", status: 200)
+    end
+  end
+end

data/lib/didit/raw_response.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Didit
+  # The HTTP response behind a result, from +didit.with_raw_response+:
+  #
+  #   raw = didit.with_raw_response.sessions.create(workflow_id: "...")
+  #   raw.status      # => 201
+  #   raw.request_id  # => "..."
+  #   session = raw.parse
+  class RawResponse
+    # @return [Integer]
+    attr_reader :status
+    # @return [Hash{String => String}] header names in lower case
+    attr_reader :headers
+    # @return [String, nil] the body bytes (nil when a block received them)
+    attr_reader :body
+    # @return [Integer] how many retries it took
+    attr_reader :retries_taken
+    # @return [Float] seconds the last attempt took
+    attr_reader :elapsed
+
+    # @api private
+    def initialize(status:, headers:, body:, retries_taken:, elapsed:, parser:)
+      @status = status
+      @headers = headers
+      @body = body
+      @retries_taken = retries_taken
+      @elapsed = elapsed
+      @parser = parser
+      @parsed = false
+      @value = nil
+    end
+
+    # @return [Integer] alias of {#status}
+    def status_code
+      status
+    end
+
+    # @return [String, nil]
+    def request_id
+      Internal::Util.request_id(headers)
+    end
+
+    # The typed result the method returns without +with_raw_response+.
+    def parse
+      unless @parsed
+        @value = @parser.call
+        @parsed = true
+      end
+      @value
+    end
+
+    def inspect
+      "#<Didit::RawResponse status=#{status} request_id=#{request_id.inspect}>"
+    end
+  end
+end

data/lib/didit/resource.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Didit
+  # Base class of the generated resources (+didit.sessions+, +didit.sessions.imports+, ...).
+  class Resource
+    # @param client [Didit::Client]
+    def initialize(client)
+      @client = client
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+  end
+end