usesmileid 12.0.0

data/lib/usesmileid/generated/models.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module SmileID
+  module Generated
+    # Wire response models (spec section 5.2). Field names mirror the wire
+    # verbatim. These live under generated/ because a generator would own them
+    # later; the hand-written client and helpers must survive regeneration.
+    module Models
+      # Response from the seven entry endpoints (HTTP 202). The `status` value
+      # differs by endpoint ("Accepted" or "accepted"); use #accepted? rather
+      # than branching on raw casing.
+      class AcceptedResponse
+        attr_reader :status, :message, :job_id, :user_id, :created_at, :raw
+
+        def initialize(status:, message: nil, job_id: nil, user_id: nil, created_at: nil, raw: nil)
+          @status = status
+          @message = message
+          @job_id = job_id
+          @user_id = user_id
+          @created_at = created_at
+          @raw = raw
+        end
+
+        # Normalized accessor — true when status is "accepted" in any casing.
+        def accepted?
+          status.to_s.downcase == 'accepted'
+        end
+
+        def self.from(hash)
+          new(
+            status: hash['status'],
+            message: hash['message'],
+            job_id: hash['job_id'],
+            user_id: hash['user_id'],
+            created_at: hash['created_at'],
+            raw: hash
+          )
+        end
+      end
+
+      # Response from GET /v3/status (spec section 5.2, 6.8). `status` is
+      # `processing` while the job runs, `not_found` for a job the API does not
+      # know, and otherwise the terminal decision itself: `clear`, `block`,
+      # `attention` or `error`. `message` carries no sub-state.
+      class JobStatus
+        attr_reader :status, :job_id, :user_id, :message, :raw
+
+        def initialize(status:, job_id: nil, user_id: nil, message: nil, raw: nil)
+          @status = status
+          @job_id = job_id
+          @user_id = user_id
+          @message = message
+          @raw = raw
+        end
+
+        # Terminal when the job is neither still running nor unknown — the
+        # status is then the decision (clear/block/attention/error).
+        def complete?
+          return false if status.to_s.empty?
+
+          !processing? && !not_found?
+        end
+
+        def processing?
+          status.to_s == 'processing'
+        end
+
+        def not_found?
+          status.to_s == 'not_found'
+        end
+
+        def self.from(hash)
+          new(
+            status: hash['status'],
+            job_id: hash['job_id'],
+            user_id: hash['user_id'],
+            message: hash['message'],
+            raw: hash
+          )
+        end
+      end
+
+      # Wraps the accepted-shaped responses from replay and report_fraud.
+      class AcceptedStatusResponse
+        attr_reader :status, :message, :job_id, :user_id, :raw
+
+        def initialize(status:, message: nil, job_id: nil, user_id: nil, raw: nil)
+          @status = status
+          @message = message
+          @job_id = job_id
+          @user_id = user_id
+          @raw = raw
+        end
+
+        def accepted?
+          status.to_s.downcase == 'accepted'
+        end
+
+        def self.from(hash)
+          new(
+            status: hash['status'],
+            message: hash['message'],
+            job_id: hash['job_id'],
+            user_id: hash['user_id'],
+            raw: hash
+          )
+        end
+      end
+
+      # Service responses (spec section 5.2). Nested collections are exposed as
+      # plain hashes with string keys, exactly as they arrive on the wire.
+      class BankCodesResponse
+        attr_reader :bank_codes, :raw
+
+        def initialize(bank_codes:, raw: nil)
+          @bank_codes = bank_codes
+          @raw = raw
+        end
+
+        def self.from(hash)
+          new(bank_codes: hash['bank_codes'] || [], raw: hash)
+        end
+      end
+
+      class SupportedIdTypesResponse
+        attr_reader :id_types, :raw
+
+        def initialize(id_types:, raw: nil)
+          @id_types = id_types
+          @raw = raw
+        end
+
+        def self.from(hash)
+          new(id_types: hash['id_types'] || [], raw: hash)
+        end
+      end
+
+      class SupportedDocumentsResponse
+        attr_reader :valid_documents, :raw
+
+        def initialize(valid_documents:, raw: nil)
+          @valid_documents = valid_documents
+          @raw = raw
+        end
+
+        def self.from(hash)
+          new(valid_documents: hash['valid_documents'] || [], raw: hash)
+        end
+      end
+
+      class IdStatusResponse
+        attr_reader :last_checked, :last_check_status, :last_hour_success_rate,
+                    :last_known_status, :last_check_success_rate, :raw
+
+        def initialize(hash)
+          @last_checked = hash['last_checked']
+          @last_check_status = hash['last_check_status']
+          @last_hour_success_rate = hash['last_hour_success_rate']
+          @last_known_status = hash['last_known_status']
+          @last_check_success_rate = hash['last_check_success_rate']
+          @raw = hash
+        end
+
+        def self.from(hash)
+          new(hash)
+        end
+      end
+    end
+  end
+end

data/lib/usesmileid/generated/operations.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module SmileID
+  module Generated
+    # Per-operation descriptors (spec section 6). One entry per HTTP operation.
+    # A generator would own this table later; the hand-written transport reads it
+    # to route auth, headers, body kind, and retry behaviour.
+    module Operations
+      Operation = Struct.new(
+        :http_method,     # :get / :post
+        :path,            # path template, e.g. "/v3/status/{job_id}"
+        :authenticated,   # attach SmileID-Token?
+        :partner_id_header, # attach SmileID-Partner-ID?
+        :body_kind,       # :multipart / :json / nil
+        :idempotent,      # safe to auto-retry? (GETs + token only)
+        :success_statuses, # statuses treated as success (not raised)
+        keyword_init: true
+      )
+
+      OPS = {
+        enhanced_kyc: Operation.new(
+          http_method: :post, path: '/v3/enhanced_kyc', authenticated: true,
+          partner_id_header: false, body_kind: :multipart, idempotent: false,
+          success_statuses: [202]
+        ),
+        document_verification: Operation.new(
+          http_method: :post, path: '/v3/document_verification', authenticated: true,
+          partner_id_header: true, body_kind: :multipart, idempotent: false,
+          success_statuses: [202]
+        ),
+        enhanced_document_verification: Operation.new(
+          http_method: :post, path: '/v3/enhanced_document_verification', authenticated: true,
+          partner_id_header: true, body_kind: :multipart, idempotent: false,
+          success_statuses: [202]
+        ),
+        biometric_kyc: Operation.new(
+          http_method: :post, path: '/v3/biometric_kyc', authenticated: true,
+          partner_id_header: true, body_kind: :multipart, idempotent: false,
+          success_statuses: [202]
+        ),
+        registration: Operation.new(
+          http_method: :post, path: '/v3/registration', authenticated: true,
+          partner_id_header: false, body_kind: :multipart, idempotent: false,
+          success_statuses: [202]
+        ),
+        authentication: Operation.new(
+          http_method: :post, path: '/v3/authentication', authenticated: true,
+          partner_id_header: false, body_kind: :multipart, idempotent: false,
+          success_statuses: [202]
+        ),
+        compare: Operation.new(
+          http_method: :post, path: '/v3/compare', authenticated: true,
+          partner_id_header: false, body_kind: :multipart, idempotent: false,
+          success_statuses: [202]
+        ),
+        status: Operation.new(
+          http_method: :get, path: '/v3/status/{job_id}', authenticated: true,
+          partner_id_header: false, body_kind: nil, idempotent: true,
+          success_statuses: [200, 202, 404]
+        ),
+        replay: Operation.new(
+          http_method: :post, path: '/v3/replay/{job_id}', authenticated: true,
+          partner_id_header: false, body_kind: :multipart, idempotent: false,
+          success_statuses: [202]
+        ),
+        report_fraud: Operation.new(
+          http_method: :post, path: '/v3/users/{user_id}/report_fraud', authenticated: true,
+          partner_id_header: false, body_kind: :multipart, idempotent: false,
+          success_statuses: [202]
+        ),
+        bank_codes: Operation.new(
+          http_method: :get, path: '/v3/services/bank_codes', authenticated: false,
+          partner_id_header: false, body_kind: nil, idempotent: true,
+          success_statuses: [200]
+        ),
+        supported_id_types: Operation.new(
+          http_method: :get, path: '/v3/services/supported_id_types', authenticated: false,
+          partner_id_header: false, body_kind: nil, idempotent: true,
+          success_statuses: [200]
+        ),
+        supported_documents: Operation.new(
+          http_method: :get, path: '/v3/services/supported_documents', authenticated: false,
+          partner_id_header: false, body_kind: nil, idempotent: true,
+          success_statuses: [200]
+        ),
+        id_status: Operation.new(
+          http_method: :get, path: '/v3/services/id_status', authenticated: true,
+          partner_id_header: false, body_kind: nil, idempotent: true,
+          success_statuses: [200]
+        )
+      }.freeze
+
+      def self.fetch(name)
+        OPS.fetch(name)
+      end
+    end
+  end
+end

data/lib/usesmileid/helpers/consent.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module SmileID
+  # Builder for the shared `consent` object required on all seven entry
+  # endpoints (spec section 5.1). Serialized as a JSON multipart part.
+  #
+  #   SmileID::Consent.granted(
+  #     granted_at: Time.now.utc,
+  #     notice_language: "EN",
+  #     notice_privacy_policy_url: "https://example.com/privacy"
+  #   )
+  class Consent
+    NOTICE_LANGUAGE = /\A[A-Z]{2}\z/
+
+    attr_reader :granted, :granted_at, :notice_language, :notice_privacy_policy_url
+
+    def initialize(granted:, granted_at:, notice_language:, notice_privacy_policy_url:)
+      @granted = granted
+      @granted_at = granted_at
+      @notice_language = notice_language
+      @notice_privacy_policy_url = notice_privacy_policy_url
+    end
+
+    # Build a consent object with granted set to true.
+    def self.granted(granted_at:, notice_language:, notice_privacy_policy_url:)
+      new(
+        granted: true,
+        granted_at: granted_at,
+        notice_language: notice_language,
+        notice_privacy_policy_url: notice_privacy_policy_url
+      )
+    end
+
+    def to_h
+      {
+        'granted' => granted,
+        'granted_at' => format_time(granted_at),
+        'notice_language' => notice_language,
+        'notice_privacy_policy_url' => notice_privacy_policy_url
+      }
+    end
+
+    # Coerce a Consent or a plain Hash into a validated wire hash.
+    def self.coerce(input)
+      consent = input.is_a?(Consent) ? input : from_hash(input)
+      consent.validate!
+      consent.to_h
+    end
+
+    def self.from_hash(hash)
+      h = stringify(hash)
+      new(
+        granted: h.key?('granted') ? h['granted'] : true,
+        granted_at: h['granted_at'],
+        notice_language: h['notice_language'],
+        notice_privacy_policy_url: h['notice_privacy_policy_url']
+      )
+    end
+
+    def validate!
+      raise Errors::ValidationError.new('consent.granted must be true') unless granted == true
+      raise Errors::ValidationError.new('consent.granted_at is required') if granted_at.nil?
+      unless notice_language.to_s.match?(NOTICE_LANGUAGE)
+        raise Errors::ValidationError.new('consent.notice_language must be a two-letter uppercase code')
+      end
+      return unless notice_privacy_policy_url.to_s.empty?
+
+      raise Errors::ValidationError.new('consent.notice_privacy_policy_url is required')
+    end
+
+    def self.stringify(hash)
+      raise Errors::ValidationError.new('consent is required') if hash.nil?
+
+      hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+    end
+
+    def format_time(value)
+      return value.utc.strftime('%Y-%m-%dT%H:%M:%S.%LZ') if value.is_a?(Time)
+
+      value
+    end
+  end
+end

data/lib/usesmileid/helpers/multipart.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+require 'faraday'
+require 'faraday/multipart'
+
+module SmileID
+  module Helpers
+    # Hand-assembles multipart/form-data bodies to guarantee the exact wire shape
+    # required by spec section 5.3:
+    #   - repeated `liveness_images` parts (one per image, never CSV/indexed),
+    #   - object/array fields as JSON parts with Content-Type: application/json,
+    #   - single binary parts with a filename and content type,
+    #   - scalar fields as plain text parts.
+    #
+    # Faraday's multipart middleware indexes array parts as `liveness_images[0]`,
+    # so the body is built here rather than delegated to it (spec section 5.3
+    # item 4, the OpenAPI-Generator bug to avoid).
+    module Multipart
+      # Fields serialized as JSON parts.
+      JSON_PART_FIELDS = %w[consent user_details partner_params metadata].freeze
+      # Single binary fields.
+      BINARY_FIELDS = %w[selfie_image document document_back comparison_image].freeze
+      # Repeated binary fields.
+      BINARY_ARRAY_FIELDS = %w[liveness_images].freeze
+
+      DEFAULT_CONTENT_TYPES = {
+        'selfie_image' => 'image/jpeg',
+        'document' => 'image/jpeg',
+        'document_back' => 'image/jpeg',
+        'comparison_image' => 'image/jpeg',
+        'liveness_images' => 'image/jpeg'
+      }.freeze
+
+      # Only document and document_back may be PNG (spec section 5.3 rule 3);
+      # selfie, liveness and comparison images are always image/jpeg.
+      PNG_CAPABLE_FIELDS = %w[document document_back].freeze
+      PNG_MAGIC = "\x89PNG".b.freeze
+
+      # RFC 6838 type/subtype tokens — anything else is rejected before send.
+      MEDIA_TYPE = %r{\A[A-Za-z0-9!\#$&^_.+-]+/[A-Za-z0-9!\#$&^_.+-]+\z}
+
+      DEFAULT_FILENAMES = {
+        'selfie_image' => 'selfie.jpg',
+        'document' => 'document.jpg',
+        'document_back' => 'document_back.jpg',
+        'comparison_image' => 'comparison.jpg'
+      }.freeze
+
+      CRLF = "\r\n"
+
+      module_function
+
+      # Build a multipart body from an ordered field hash.
+      #
+      # @return [Array(String, String)] content-type header value and body bytes.
+      def build(form, boundary: default_boundary)
+        body = +''.b
+        form.each do |name, value|
+          next if value.nil?
+
+          field = name.to_s
+          append_field(body, field, value, boundary)
+        end
+        body << "--#{boundary}--#{CRLF}".b
+        ["multipart/form-data; boundary=#{boundary}", body]
+      end
+
+      def default_boundary
+        "----smileid#{SecureRandom.hex(16)}"
+      end
+
+      def append_field(body, field, value, boundary)
+        if BINARY_ARRAY_FIELDS.include?(field)
+          Array(value).each_with_index do |img, index|
+            body << binary_part(field, img, boundary, index: index)
+          end
+        elsif BINARY_FIELDS.include?(field)
+          body << binary_part(field, value, boundary)
+        elsif JSON_PART_FIELDS.include?(field)
+          body << json_part(field, value, boundary)
+        else
+          body << text_part(field, scalar_string(value), boundary)
+        end
+      end
+
+      def text_part(name, value, boundary)
+        part = "--#{boundary}#{CRLF}"
+        part << "Content-Disposition: form-data; name=\"#{name}\"#{CRLF}#{CRLF}"
+        part << value.to_s
+        part << CRLF
+        part.b
+      end
+
+      def json_part(name, value, boundary)
+        part = "--#{boundary}#{CRLF}"
+        part << "Content-Disposition: form-data; name=\"#{name}\"#{CRLF}"
+        part << "Content-Type: application/json#{CRLF}#{CRLF}"
+        part << JSON.generate(value)
+        part << CRLF
+        part.b
+      end
+
+      def binary_part(name, input, boundary, index: nil)
+        upload = coerce_binary(name, input, index: index)
+        # Sanitization runs here so it covers EVERY input path — FilePart,
+        # hash, path, raw bytes, IO — including explicit content types.
+        filename = sanitize_filename(upload[:filename])
+        content_type = validate_content_type!(upload[:content_type])
+        header = "--#{boundary}#{CRLF}"
+        header << 'Content-Disposition: form-data; ' \
+                  "name=\"#{name}\"; filename=\"#{filename}\"#{CRLF}"
+        header << "Content-Type: #{content_type}#{CRLF}#{CRLF}"
+        (header.b + upload[:bytes].b + CRLF.b)
+      end
+
+      # Strip header-injection vectors from filenames: CR, LF and other
+      # control characters are removed; double quotes are percent-encoded so
+      # they cannot terminate the quoted filename attribute.
+      def sanitize_filename(filename)
+        filename.to_s.gsub(/[\x00-\x1f\x7f]/, '').gsub('"', '%22')
+      end
+
+      # Content types must be a plain media type token pair; anything else
+      # (including CR/LF injection) fails validation before send.
+      def validate_content_type!(content_type)
+        value = content_type.to_s
+        return value if value.match?(MEDIA_TYPE)
+
+        raise Errors::ValidationError.new('content_type must be a valid media type')
+      end
+
+      # Coerce a binary input (path, bytes, IO, Hash, or Faraday FilePart) into
+      # { bytes:, filename:, content_type: }. An explicitly provided content
+      # type wins; otherwise the field's default applies, with PNG detection
+      # for the document fields only.
+      def coerce_binary(field, input, index: nil)
+        default_fn = filename_for(field, index)
+
+        upload =
+          case input
+          when Faraday::Multipart::FilePart
+            from_file_part(input, default_fn)
+          when Hash
+            from_hash(input, default_fn)
+          when String
+            from_string(input, default_fn)
+          else
+            unless input.respond_to?(:read)
+              raise Errors::ValidationError.new("#{field} must be a file path, bytes, IO, or FilePart")
+            end
+
+            from_io(input, default_fn)
+          end
+
+        resolve_content_type(field, upload)
+      end
+
+      def resolve_content_type(field, upload)
+        return upload if upload[:content_type]
+
+        default = DEFAULT_CONTENT_TYPES[field] || 'application/octet-stream'
+        if PNG_CAPABLE_FIELDS.include?(field) && png?(upload)
+          upload[:content_type] = 'image/png'
+          if upload[:filename] == DEFAULT_FILENAMES[field]
+            upload[:filename] = upload[:filename].sub(/\.jpg\z/, '.png')
+          end
+        else
+          upload[:content_type] = default
+        end
+        upload
+      end
+
+      def png?(upload)
+        upload[:filename].to_s.downcase.end_with?('.png') ||
+          upload[:bytes].to_s.b.start_with?(PNG_MAGIC)
+      end
+
+      def filename_for(field, index)
+        return DEFAULT_FILENAMES[field] if DEFAULT_FILENAMES.key?(field)
+
+        "#{field}_#{(index || 0) + 1}.jpg"
+      end
+
+      def from_file_part(part, default_fn)
+        io = part.instance_variable_get(:@io)
+        local_path = part.instance_variable_get(:@local_path)
+        bytes = io ? read_all(io) : File.binread(local_path)
+        {
+          bytes: bytes,
+          filename: part.original_filename || default_fn,
+          content_type: part.content_type
+        }
+      end
+
+      def from_hash(hash, default_fn)
+        h = hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+        bytes =
+          if h[:bytes]
+            h[:bytes]
+          elsif h[:path]
+            File.binread(h[:path])
+          elsif h[:io]
+            read_all(h[:io])
+          else
+            raise Errors::ValidationError.new('binary hash needs one of :bytes, :path, or :io')
+          end
+        {
+          bytes: bytes,
+          filename: h[:filename] || (h[:path] ? File.basename(h[:path]) : default_fn),
+          content_type: h[:content_type]
+        }
+      end
+
+      def from_string(str, default_fn)
+        if plausible_path?(str) && File.exist?(str)
+          { bytes: File.binread(str), filename: File.basename(str), content_type: nil }
+        else
+          { bytes: str, filename: default_fn, content_type: nil }
+        end
+      end
+
+      # Raw image bytes routinely contain null bytes or invalid UTF-8, which
+      # File.exist? rejects with ArgumentError. Only probe the filesystem for
+      # strings that could plausibly be paths.
+      def plausible_path?(str)
+        str.length < 4096 && str.valid_encoding? && !str.include?("\0")
+      end
+
+      def from_io(io, default_fn)
+        filename = io.respond_to?(:path) && io.path ? File.basename(io.path) : default_fn
+        { bytes: read_all(io), filename: filename, content_type: nil }
+      end
+
+      def read_all(io)
+        io.rewind if io.respond_to?(:rewind)
+        io.read
+      end
+
+      def scalar_string(value)
+        case value
+        when true then 'true'
+        when false then 'false'
+        else value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/usesmileid/helpers/user_details.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SmileID
+  # Builder and validator for the shared `user_details` object required on all
+  # seven entry endpoints (spec section 5.1). Serialized as a JSON multipart part.
+  #
+  # At least one of email / phone_number MUST be present — enforced client-side
+  # before the request is sent.
+  class UserDetails
+    PHONE_NUMBER = /\A\+[1-9]\d{6,14}\z/
+
+    attr_reader :given_names, :last_name, :email, :phone_number
+
+    def initialize(given_names:, last_name:, email: nil, phone_number: nil)
+      @given_names = given_names
+      @last_name = last_name
+      @email = email
+      @phone_number = phone_number
+    end
+
+    def to_h
+      {
+        'given_names' => given_names,
+        'last_name' => last_name,
+        'email' => email,
+        'phone_number' => phone_number
+      }.compact
+    end
+
+    # Coerce a UserDetails or plain Hash into a validated wire hash.
+    def self.coerce(input)
+      details = input.is_a?(UserDetails) ? input : from_hash(input)
+      details.validate!
+      details.to_h
+    end
+
+    def self.from_hash(hash)
+      raise Errors::ValidationError.new('user_details is required') if hash.nil?
+
+      h = hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+      new(
+        given_names: h['given_names'],
+        last_name: h['last_name'],
+        email: h['email'],
+        phone_number: h['phone_number']
+      )
+    end
+
+    def validate!
+      raise Errors::ValidationError.new('user_details.given_names is required') if given_names.to_s.empty?
+      raise Errors::ValidationError.new('user_details.last_name is required') if last_name.to_s.empty?
+
+      if email.to_s.empty? && phone_number.to_s.empty?
+        raise Errors::ValidationError.new(
+          'user_details requires at least one of email or phone_number'
+        )
+      end
+      return unless !phone_number.to_s.empty? && !phone_number.to_s.match?(PHONE_NUMBER)
+
+      raise Errors::ValidationError.new('user_details.phone_number must be E.164 format')
+    end
+  end
+end

data/lib/usesmileid/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SmileID
+  VERSION = '12.0.0'
+end

data/lib/usesmileid.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'usesmileid/version'
+require 'usesmileid/errors'
+require 'usesmileid/generated/models'
+require 'usesmileid/generated/operations'
+require 'usesmileid/helpers/consent'
+require 'usesmileid/helpers/user_details'
+require 'usesmileid/helpers/multipart'
+require 'usesmileid/client/config'
+require 'usesmileid/client/transport'
+require 'usesmileid/client/auth'
+require 'usesmileid/client/resources'
+require 'usesmileid/client/client'
+
+# Smile ID's official server-side SDK for Ruby, covering the V3 APIs.
+#
+# Construct a client and call resource verbs:
+#
+#   require "usesmileid"
+#   smile = SmileID::Client.new(partner_id: "1234", api_key: ENV.fetch("SMILE_API_KEY"))
+#   accepted = smile.enhanced_kyc.verify(...)
+module SmileID
+end