usesmileid 12.0.0

data/lib/usesmileid/client/config.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module SmileID
+  # Immutable client configuration (spec section 2.1). Sandbox by default.
+  #
+  # Fleet standards (2026-07-03): base_url must be an absolute https URL with
+  # no query or fragment — there is deliberately no allow-insecure option.
+  # Callback URLs must be https, validated at construction for the default and
+  # before send for per-request values.
+  class Config
+    PARTNER_ID = /\A[1-9]\d*\z/
+    BASE_URLS = {
+      sandbox: 'https://testapi.smileidentity.com',
+      production: 'https://api.smileidentity.com'
+    }.freeze
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 2
+
+    attr_reader :partner_id, :api_key, :environment,
+                :default_callback_url, :base_url, :timeout, :max_retries, :http_client
+
+    def initialize(partner_id:, api_key:, environment: :sandbox,
+                   default_callback_url: nil, base_url: nil, timeout: DEFAULT_TIMEOUT,
+                   max_retries: DEFAULT_MAX_RETRIES, http_client: nil)
+      @partner_id = partner_id.to_s
+      @api_key = api_key.to_s
+      @environment = normalize_environment(environment)
+      @default_callback_url = default_callback_url
+      @timeout = timeout
+      @max_retries = max_retries
+      @http_client = http_client
+      @base_url = (base_url || BASE_URLS.fetch(@environment)).chomp('/')
+      validate!
+    end
+
+    # Validate that a callback URL is an absolute https URL. Raises the local
+    # validation error so no request is made with an insecure callback.
+    def self.validate_callback_url!(value, field: 'callback_url')
+      uri = begin
+        URI.parse(value.to_s)
+      rescue URI::InvalidURIError
+        nil
+      end
+      unless uri.is_a?(URI::Generic) && uri.absolute? && uri.host
+        raise Errors::ValidationError.new("#{field} must be an absolute https URL")
+      end
+      return if uri.scheme == 'https'
+
+      raise Errors::ValidationError.new("#{field} must use https")
+    end
+
+    private
+
+    def normalize_environment(env)
+      sym = env.to_s.downcase.to_sym
+      return sym if BASE_URLS.key?(sym)
+
+      raise ArgumentError, "environment must be one of #{BASE_URLS.keys.join(', ')}"
+    end
+
+    def validate!
+      raise ArgumentError, 'partner_id is required' if @partner_id.empty?
+      raise ArgumentError, 'api_key is required' if @api_key.empty?
+      unless @partner_id.match?(PARTNER_ID)
+        raise ArgumentError, 'partner_id must be a numeric string with no leading zeros'
+      end
+
+      validate_base_url!
+      return if @default_callback_url.nil?
+
+      self.class.validate_callback_url!(@default_callback_url, field: 'default_callback_url')
+    end
+
+    def validate_base_url!
+      uri = begin
+        URI.parse(@base_url)
+      rescue URI::InvalidURIError
+        nil
+      end
+      unless uri.is_a?(URI::Generic) && uri.absolute? && uri.host
+        raise ArgumentError, 'base_url must be an absolute URL'
+      end
+      raise ArgumentError, 'base_url must use https' unless uri.scheme == 'https'
+      return unless uri.query || uri.fragment
+
+      raise ArgumentError, 'base_url must not include a query or fragment'
+    end
+  end
+
+  # Telemetry headers sent on every request (spec section 2.4).
+  module Telemetry
+    SDK_NAME = 'ruby'
+
+    module_function
+
+    def headers
+      {
+        'SmileID-Source-SDK' => SDK_NAME,
+        'SmileID-Source-SDK-Version' => SmileID::VERSION,
+        'User-Agent' => "smileid-sdk-ruby/#{SmileID::VERSION} (ruby/#{RUBY_VERSION})"
+      }
+    end
+  end
+end

data/lib/usesmileid/client/resources.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+module SmileID
+  # Resource namespaces exposing the public SDK surface (spec section 4).
+  # Each maps a verb to an operation, coerces and validates input, and wraps the
+  # response in a typed model.
+  module Resources
+    # Shared behaviour for all resources.
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def coerce_consent(consent)
+        Consent.coerce(consent)
+      end
+
+      def coerce_user_details(user_details)
+        UserDetails.coerce(user_details)
+      end
+
+      # Use an explicit callback_url, else fall back to the configured default.
+      # Per-request callback URLs must be https (fleet standard); validated
+      # before any request is made. The default was validated at construction.
+      def resolve_callback(callback_url)
+        Config.validate_callback_url!(callback_url) if callback_url
+        callback_url || @client.config.default_callback_url
+      end
+
+      def accepted(response)
+        Generated::Models::AcceptedResponse.from(response.json)
+      end
+    end
+
+    # POST /v3/enhanced_kyc
+    class EnhancedKyc < Base
+      def verify(country:, id_type:, id_number:, user_details:, consent:,
+                 callback_url: nil, bank_code: nil, operator: nil,
+                 partner_params: nil, metadata: nil, user_id: nil, timeout: nil)
+        form = {
+          'country' => country,
+          'id_type' => id_type,
+          'id_number' => id_number,
+          'user_details' => coerce_user_details(user_details),
+          'consent' => coerce_consent(consent),
+          'callback_url' => resolve_callback(callback_url),
+          'bank_code' => bank_code,
+          'operator' => operator,
+          'partner_params' => partner_params,
+          'metadata' => metadata
+        }.compact
+        accepted(@client.call(:enhanced_kyc, form: form, user_id_header: user_id, timeout: timeout))
+      end
+    end
+
+    # POST /v3/document_verification and /v3/enhanced_document_verification
+    class Documents < Base
+      def verify(selfie_image:, liveness_images:, document:, consent:, country:, user_details:,
+                 document_back: nil, id_type: nil, callback_url: nil,
+                 partner_params: nil, metadata: nil, user_id: nil, timeout: nil)
+        form = document_form(
+          selfie_image: selfie_image, liveness_images: liveness_images, document: document,
+          document_back: document_back, consent: consent, country: country, id_type: id_type,
+          user_details: user_details, callback_url: callback_url,
+          partner_params: partner_params, metadata: metadata
+        )
+        accepted(@client.call(:document_verification, form: form, user_id_header: user_id, timeout: timeout))
+      end
+
+      # id_type is REQUIRED for enhanced document verification (spec section 6.3).
+      def verify_enhanced(id_type:, selfie_image:, liveness_images:, document:, consent:, country:,
+                          user_details:, document_back: nil, callback_url: nil,
+                          partner_params: nil, metadata: nil, user_id: nil, timeout: nil)
+        if id_type.to_s.empty?
+          raise Errors::ValidationError.new('id_type is required for enhanced document verification')
+        end
+
+        form = document_form(
+          selfie_image: selfie_image, liveness_images: liveness_images, document: document,
+          document_back: document_back, consent: consent, country: country, id_type: id_type,
+          user_details: user_details, callback_url: callback_url,
+          partner_params: partner_params, metadata: metadata
+        )
+        accepted(@client.call(:enhanced_document_verification, form: form,
+                                                               user_id_header: user_id, timeout: timeout))
+      end
+
+      private
+
+      def document_form(selfie_image:, liveness_images:, document:, document_back:, consent:,
+                        country:, id_type:, user_details:, callback_url:, partner_params:, metadata:)
+        {
+          'country' => country,
+          'id_type' => id_type,
+          'selfie_image' => selfie_image,
+          'liveness_images' => liveness_images,
+          'document' => document,
+          'document_back' => document_back,
+          'user_details' => coerce_user_details(user_details),
+          'consent' => coerce_consent(consent),
+          'callback_url' => resolve_callback(callback_url),
+          'partner_params' => partner_params,
+          'metadata' => metadata
+        }.compact
+      end
+    end
+
+    # POST /v3/biometric_kyc
+    class BiometricKyc < Base
+      def verify(selfie_image:, liveness_images:, consent:, country:, id_type:, id_number:,
+                 user_details:, callback_url: nil, sandbox_result: nil,
+                 partner_params: nil, metadata: nil, user_id: nil, timeout: nil)
+        form = {
+          'country' => country,
+          'id_type' => id_type,
+          'id_number' => id_number,
+          'selfie_image' => selfie_image,
+          'liveness_images' => liveness_images,
+          'user_details' => coerce_user_details(user_details),
+          'consent' => coerce_consent(consent),
+          'callback_url' => resolve_callback(callback_url),
+          'sandbox_result' => sandbox_result,
+          'partner_params' => partner_params,
+          'metadata' => metadata
+        }.compact
+        accepted(@client.call(:biometric_kyc, form: form, user_id_header: user_id, timeout: timeout))
+      end
+    end
+
+    # POST /v3/registration, /v3/authentication, /v3/compare
+    class Biometric < Base
+      def enroll(selfie_image:, liveness_images:, consent:, user_details:,
+                 allow_new_enroll: nil, callback_url: nil, sandbox_result: nil,
+                 partner_params: nil, metadata: nil, user_id: nil, timeout: nil)
+        form = {
+          'selfie_image' => selfie_image,
+          'liveness_images' => liveness_images,
+          'user_details' => coerce_user_details(user_details),
+          'consent' => coerce_consent(consent),
+          'allow_new_enroll' => allow_new_enroll,
+          'callback_url' => resolve_callback(callback_url),
+          'sandbox_result' => sandbox_result,
+          'partner_params' => partner_params,
+          'metadata' => metadata
+        }.compact
+        accepted(@client.call(:registration, form: form, user_id_header: user_id, timeout: timeout))
+      end
+
+      # user_id goes in the BODY here (required), not the User-ID header.
+      def authenticate(user_id:, consent:, user_details:, selfie_image: nil, liveness_images: nil,
+                       use_enrolled_image: nil, callback_url: nil, sandbox_result: nil,
+                       partner_params: nil, metadata: nil, timeout: nil)
+        require_images!(use_enrolled_image, selfie_image, liveness_images)
+        form = {
+          'user_id' => user_id,
+          'selfie_image' => selfie_image,
+          'liveness_images' => liveness_images,
+          'user_details' => coerce_user_details(user_details),
+          'consent' => coerce_consent(consent),
+          'use_enrolled_image' => use_enrolled_image,
+          'callback_url' => resolve_callback(callback_url),
+          'sandbox_result' => sandbox_result,
+          'partner_params' => partner_params,
+          'metadata' => metadata
+        }.compact
+        accepted(@client.call(:authentication, form: form, timeout: timeout))
+      end
+
+      # user_id is optional here, and goes in the BODY when present.
+      def compare(selfie_image:, comparison_image:, comparison_image_type:, consent:, user_details:,
+                  liveness_images: nil, allow_new_enroll: nil, user_id: nil, callback_url: nil,
+                  sandbox_result: nil, partner_params: nil, metadata: nil, timeout: nil)
+        form = {
+          'selfie_image' => selfie_image,
+          'comparison_image' => comparison_image,
+          'comparison_image_type' => comparison_image_type,
+          'liveness_images' => liveness_images,
+          'user_details' => coerce_user_details(user_details),
+          'consent' => coerce_consent(consent),
+          'allow_new_enroll' => allow_new_enroll,
+          'user_id' => user_id,
+          'callback_url' => resolve_callback(callback_url),
+          'sandbox_result' => sandbox_result,
+          'partner_params' => partner_params,
+          'metadata' => metadata
+        }.compact
+        accepted(@client.call(:compare, form: form, timeout: timeout))
+      end
+
+      private
+
+      def require_images!(use_enrolled_image, selfie_image, liveness_images)
+        return if use_enrolled_image == true
+        return unless selfie_image.nil? || liveness_images.nil? || Array(liveness_images).empty?
+
+        raise Errors::ValidationError.new(
+          'selfie_image and liveness_images are required unless use_enrolled_image is true'
+        )
+      end
+    end
+
+    # GET /v3/status, POST /v3/replay, plus the wait_until_complete poll helper.
+    class Verifications < Base
+      def retrieve(job_id, timeout: nil)
+        response = @client.call(:status, path_params: { 'job_id' => job_id }, timeout: timeout)
+        Generated::Models::JobStatus.from(response.json)
+      end
+
+      def wait_until_complete(job_id, interval: 2, timeout: 60, treat_not_found_as_pending: true)
+        deadline = monotonic + timeout
+        loop do
+          status = retrieve(job_id)
+          return status if status.complete?
+          return status if status.not_found? && !treat_not_found_as_pending
+
+          if monotonic >= deadline
+            raise Errors::TimeoutError.new(
+              "wait_until_complete timed out after #{timeout}s waiting for #{job_id}"
+            )
+          end
+          sleep_interval(interval)
+        end
+      end
+
+      # The optional callback_url override goes in a multipart body (any other
+      # content type gets a 415 from the backend); no override, no body.
+      def replay(job_id, callback_url: nil, timeout: nil)
+        Config.validate_callback_url!(callback_url) if callback_url
+        form = callback_url ? { 'callback_url' => callback_url } : nil
+        response = @client.call(:replay, path_params: { 'job_id' => job_id },
+                                         form: form, timeout: timeout)
+        Generated::Models::AcceptedStatusResponse.from(response.json)
+      end
+
+      private
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def sleep_interval(interval)
+        sleep(interval)
+      end
+    end
+
+    # POST /v3/users/{user_id}/report_fraud, plus flag/clear convenience wrappers.
+    class Users < Base
+      REASONS = %w[
+        FIRST_PARTY_FRAUD SECOND_PARTY_FRAUD THIRD_PARTY_FRAUD SYNTHETIC_IDENTITY
+        ACCOUNT_TAKEOVER DOCUMENT_FORGERY IDENTITY_FARMING MULE_ACCOUNT OTHER
+      ].freeze
+
+      def report_fraud(user_id, is_fraud:, reported_by:, reason: nil, notes: nil, timeout: nil)
+        validate_fraud!(is_fraud, reason, notes)
+        form = {
+          'is_fraud' => is_fraud,
+          'reported_by' => reported_by,
+          'reason' => reason,
+          'notes' => notes
+        }.compact
+        response = @client.call(:report_fraud, path_params: { 'user_id' => user_id },
+                                               form: form, timeout: timeout)
+        Generated::Models::AcceptedStatusResponse.from(response.json)
+      end
+
+      def flag_fraud(user_id, reason:, reported_by:, notes: nil, timeout: nil)
+        report_fraud(user_id, is_fraud: true, reason: reason, notes: notes,
+                              reported_by: reported_by, timeout: timeout)
+      end
+
+      def clear_fraud(user_id, notes:, reported_by:, timeout: nil)
+        report_fraud(user_id, is_fraud: false, notes: notes, reported_by: reported_by, timeout: timeout)
+      end
+
+      private
+
+      def validate_fraud!(is_fraud, reason, notes)
+        if is_fraud
+          raise Errors::ValidationError.new('reason is required when is_fraud is true') if reason.to_s.empty?
+          unless REASONS.include?(reason.to_s)
+            raise Errors::ValidationError.new("reason must be one of #{REASONS.join(', ')}")
+          end
+          if reason.to_s == 'OTHER' && notes.to_s.empty?
+            raise Errors::ValidationError.new('notes is required when reason is OTHER')
+          end
+        elsif notes.to_s.empty?
+          raise Errors::ValidationError.new('notes is required when is_fraud is false')
+        end
+      end
+    end
+
+    # GET /v3/services/*
+    class Services < Base
+      def bank_codes(country: nil, timeout: nil)
+        response = @client.call(:bank_codes, query: { 'country' => country }.compact, timeout: timeout)
+        Generated::Models::BankCodesResponse.from(response.json)
+      end
+
+      def supported_id_types(country: nil, timeout: nil)
+        response = @client.call(:supported_id_types, query: { 'country' => country }.compact,
+                                                     timeout: timeout)
+        Generated::Models::SupportedIdTypesResponse.from(response.json)
+      end
+
+      def supported_documents(continent: nil, country_code: nil, locale: nil, timeout: nil)
+        query = { 'continent' => continent, 'country_code' => country_code, 'locale' => locale }.compact
+        response = @client.call(:supported_documents, query: query, timeout: timeout)
+        Generated::Models::SupportedDocumentsResponse.from(response.json)
+      end
+
+      def id_status(country:, id_type:, timeout: nil)
+        query = { 'country' => country, 'id_type' => id_type }
+        response = @client.call(:id_status, query: query, timeout: timeout)
+        Generated::Models::IdStatusResponse.from(response.json)
+      end
+    end
+  end
+end

data/lib/usesmileid/client/transport.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'time'
+
+module SmileID
+  # Normalized HTTP response returned by the transport.
+  class Response
+    attr_reader :status, :headers, :raw_body
+
+    def initialize(status:, headers:, raw_body:)
+      @status = status
+      @headers = headers
+      @raw_body = raw_body
+    end
+
+    # Parsed JSON body, or nil when the body is empty or not JSON.
+    def json
+      return @json if defined?(@json)
+
+      @json = parse
+    end
+
+    private
+
+    def parse
+      return nil if raw_body.nil? || raw_body.to_s.empty?
+
+      JSON.parse(raw_body)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+
+  # The single HTTP transport (spec section 2.2, 2.6). Builds the Faraday
+  # request, sends it, retries idempotent operations on transient failures
+  # honouring Retry-After, and normalizes the response. It does not touch auth;
+  # the client injects tokens and handles the refresh-on-401 dance.
+  class Transport
+    RETRY_STATUSES = [408, 429, 500, 502, 503, 504].freeze
+    BACKOFF_BASE = 0.5
+    # Ceiling for an honoured Retry-After, so a hostile or misconfigured
+    # header cannot block the caller indefinitely.
+    RETRY_AFTER_CAP = 60
+
+    def initialize(config)
+      @config = config
+      @connection = build_connection
+    end
+
+    def send_request(method:, url:, headers:, query: {}, body: nil, retryable: false, timeout: nil)
+      attempt = 0
+      loop do
+        response = perform(method, url, headers, query, body, timeout)
+        if retryable && RETRY_STATUSES.include?(response.status) && attempt < @config.max_retries
+          sleep_for(backoff(attempt, response.headers['retry-after']))
+          attempt += 1
+          next
+        end
+        return response
+      rescue Faraday::TimeoutError, Faraday::ConnectionFailed, Faraday::SSLError => e
+        raise Errors::ConnectionError.new(e.message) unless retryable && attempt < @config.max_retries
+
+        sleep_for(backoff(attempt, nil))
+        attempt += 1
+      end
+    end
+
+    private
+
+    def perform(method, url, headers, query, body, timeout)
+      resp = @connection.run_request(method, url, body, headers) do |req|
+        req.params.update(query) if query && !query.empty?
+        req.options.timeout = timeout || @config.timeout
+      end
+      Response.new(status: resp.status, headers: resp.headers, raw_body: resp.body)
+    end
+
+    def build_connection
+      return @config.http_client if @config.http_client.is_a?(Faraday::Connection)
+
+      Faraday.new do |f|
+        f.adapter(Faraday.default_adapter)
+      end
+    end
+
+    # Exponential backoff with jitter; honour Retry-After (capped) when present.
+    def backoff(attempt, retry_after)
+      honoured = parse_retry_after(retry_after)
+      return [honoured, RETRY_AFTER_CAP].min if honoured
+
+      (BACKOFF_BASE * (2**attempt)) + (rand * BACKOFF_BASE)
+    end
+
+    # Retry-After is either delta-seconds or an RFC 7231 HTTP-date. Returns
+    # the delay in seconds (floored at 0), or nil when absent or unparseable.
+    def parse_retry_after(value)
+      str = value.to_s.strip
+      return nil if str.empty?
+      return str.to_f if str.match?(/\A\d+(\.\d+)?\z/)
+
+      begin
+        [Time.httpdate(str) - Time.now, 0].max
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    def sleep_for(seconds)
+      sleep(seconds)
+    end
+  end
+end

data/lib/usesmileid/errors.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module SmileID
+  # Typed error hierarchy over both wire error shapes (spec section 7).
+  #
+  # Wire shapes handled:
+  #   - { "status": <text>, "message": <human> }  (most endpoints; id_status reorders keys)
+  #   - { "error": <human>, "code": <string> }     (the three unauthenticated services endpoints)
+  #
+  # The class is chosen by HTTP status, never by body contents.
+  module Errors
+    # Base class for every error the SDK raises.
+    class SmileIDError < StandardError
+      # HTTP status code (Integer), or nil for connection/local errors.
+      attr_reader :status_code
+      # HTTP status text from the body when present (e.g. "Bad Request").
+      attr_reader :status
+      # Machine code, present only on the services { error, code } shape.
+      attr_reader :code
+      # Request id, populated from a response header if one exists, else nil.
+      attr_reader :request_id
+      # The unparsed response body.
+      attr_reader :raw_body
+
+      def initialize(message = nil, status_code: nil, status: nil, code: nil,
+                     request_id: nil, raw_body: nil)
+        super(message)
+        @status_code = status_code
+        @status = status
+        @code = code
+        @request_id = request_id
+        @raw_body = raw_body
+      end
+    end
+
+    # 400 and 415 — malformed request, or a failed client-side validation.
+    class InvalidRequestError < SmileIDError; end
+
+    # Raised before send when a local validation rule fails (spec section 5.1, 6.11).
+    class ValidationError < InvalidRequestError; end
+
+    # 401 — token missing, invalid, or expired after a single refresh attempt.
+    class AuthenticationError < SmileIDError; end
+
+    # 402 — insufficient wallet balance.
+    class PaymentRequiredError < SmileIDError; end
+
+    # 403 — not authorized (includes the services { error, code } shape).
+    class PermissionError < SmileIDError; end
+
+    # 404 — not found. Note: jobs.retrieve does NOT raise this (spec section 6.8).
+    class NotFoundError < SmileIDError; end
+
+    # 409 — business-state conflict (replay still processing). Never auto-retried.
+    class ConflictError < SmileIDError; end
+
+    # 413 — payload too large.
+    class PayloadTooLargeError < SmileIDError; end
+
+    # 429 — rate limited.
+    class RateLimitError < SmileIDError; end
+
+    # 5xx — server error.
+    class APIError < SmileIDError; end
+
+    # Network failure or timeout with no HTTP response.
+    class ConnectionError < SmileIDError; end
+
+    # SDK-local — raised by verifications.wait_until_complete when the deadline passes.
+    class TimeoutError < SmileIDError; end
+
+    # A 2xx success response whose body is not the expected JSON object —
+    # typically proxy interference or an upstream contract break.
+    class UnexpectedResponseError < SmileIDError; end
+
+    STATUS_CLASSES = {
+      400 => InvalidRequestError,
+      401 => AuthenticationError,
+      402 => PaymentRequiredError,
+      403 => PermissionError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      413 => PayloadTooLargeError,
+      415 => InvalidRequestError,
+      429 => RateLimitError
+    }.freeze
+
+    # The response header names we probe for a request id (none is defined in the
+    # spec today; populate from a header if the backend ever sends one).
+    REQUEST_ID_HEADERS = %w[x-request-id smileid-request-id request-id].freeze
+
+    # Select the error class for an HTTP status code.
+    def self.class_for(status_code)
+      return STATUS_CLASSES[status_code] if STATUS_CLASSES.key?(status_code)
+      return APIError if status_code && status_code >= 500
+
+      SmileIDError
+    end
+
+    # Build a typed error from a response (see parse_error, spec section 2A).
+    def self.from_response(status_code:, body:, raw_body:, headers: {})
+      body = {} unless body.is_a?(Hash)
+      message = body['message'] || body['error']
+      klass = class_for(status_code)
+      klass.new(
+        message,
+        status_code: status_code,
+        status: body['status'],
+        code: body['code'],
+        request_id: request_id_from(headers),
+        raw_body: raw_body
+      )
+    end
+
+    def self.request_id_from(headers)
+      return nil unless headers.respond_to?(:[])
+
+      REQUEST_ID_HEADERS.each do |name|
+        value = headers[name] || headers[name.split('-').map(&:capitalize).join('-')]
+        return value if value
+      end
+      nil
+    end
+  end
+end