retab 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03451c10ad95d1e8c1c4735d27f0111c41bd3f70c2c56f47a8b6c6f4b814d805
-  data.tar.gz: e2fb7d8224adcd5c7028132d39552a66262509b9536c9e4d1faf4c11131a2dce
+  metadata.gz: ec5a7c94ae5550b0264067af9b62e78aa26c70c6080f0aa19a16d62a22ed0657
+  data.tar.gz: f666c564ffa300ab11fca9e88c9892f77ffc040d157a39a9d393de08ef841586
 SHA512:
-  metadata.gz: 28d6058f953e1cebfbde309eddcd726c0654d4961d19aff4474d008e53d1e0be7815883fb43767ef800e34ccf32513a56ac0621a824216e1151471e5ddd10763
-  data.tar.gz: 9ac931a257550fbf1a1cb191ce1802887415b6d603d1e40bf9335e71b31c84acff26156172f9f8dbd3a4ea7f887f5705b18556ec27b501500df245ce6bff4dcf
+  metadata.gz: 87d9b4548bb1b36fcfb7129e3d2367f537f5b8caa227cce87fe71d1cc6306a1b30f8c32d1cc12f61f327db6394c951a9affdad1d8b0436253c5b16cec380c938
+  data.tar.gz: 6a40f27a46700369053a581ba5c1a98edd1b03cbdfdbaeed0005da52366966442e98472168c36f967f31357f28c3d4904313f83ae1bf66aebb131fcd2eb8ba9c

data/lib/retab/base_client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# This file is auto-generated by oagen. Do not edit.
+
 # @oagen-ignore-file
 #
 # Hand-maintained HTTP runtime. Generated resource methods call
@@ -7,22 +9,22 @@
 # and wrap the result in spec-derived model classes.
 #
 # This is intentionally minimal — net/http + JSON, no retry/backoff polish.
-# A future revision should mirror the WorkOS Ruby SDK's `BaseClient` for
-# retries, idempotency keys, and structured error mapping.
+# A future revision should grow retries, idempotency keys, and structured
+# error mapping; the spec doesn't describe any of those.
 
-require 'json'
-require 'net/http'
-require 'uri'
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
 
 module Retab
   class BaseClient
     attr_reader :configuration
 
-    def initialize(api_key: nil, api_host: nil, configuration: nil, **opts)
-      @configuration =
-        configuration ||
-          Configuration.new(api_key: api_key, api_host: api_host, **opts)
-      raise ConfigurationError, 'api_key is required' if @configuration.api_key.nil?
+    def initialize(api_key: nil, api_host: nil, base_url: nil, configuration: nil, **opts)
+      @configuration = configuration ||
+        Configuration.new(api_key: api_key, api_host: api_host, base_url: base_url, **opts)
+      raise ConfigurationError, "api_key is required" if @configuration.api_key.nil?
     end
 
     def api_key
@@ -52,6 +54,7 @@ module Retab
         query = URI.encode_www_form(params.reject { |_, v| v.nil? })
         uri.query = query unless query.empty?
       end
+
       uri
     end
 
@@ -62,59 +65,83 @@ module Retab
         put: Net::HTTP::Put,
         patch: Net::HTTP::Patch,
         delete: Net::HTTP::Delete,
-        head: Net::HTTP::Head,
+        head: Net::HTTP::Head
       }.fetch(method.to_sym) { raise ArgumentError, "unsupported HTTP method: #{method}" }
       req = klass.new(uri.request_uri)
-      req['Accept'] = 'application/json'
-      req['User-Agent'] = @configuration.user_agent
+      req["Accept"] = "application/json"
+      req["User-Agent"] = @configuration.user_agent
       if auth
-        key = (request_options[:api_key] || request_options['api_key'] || api_key)
-        req['Authorization'] = "Bearer #{key}" if key
+        key = (request_options[:api_key] || request_options["api_key"] || api_key)
+        # Retab's API expects the raw key in `Api-Key` (not `Authorization: Bearer ...`).
+        # Confirmed against the Python SDK's `client.py` and the server response on
+        # /v1/files: "Provide a valid Bearer token, API Key, ..." — the API Key path
+        # is the `Api-Key` header.
+        req["Api-Key"] = key if key
       end
-      if (idem = request_options[:idempotency_key] || request_options['idempotency_key'])
-        req['Idempotency-Key'] = idem
+
+      if (idem = request_options[:idempotency_key] || request_options["idempotency_key"])
+        req["Idempotency-Key"] = idem
       end
-      extra_headers = request_options[:headers] || request_options['headers'] || {}
+
+      extra_headers = request_options[:headers] || request_options["headers"] || {}
       extra_headers.each { |k, v| req[k.to_s] = v.to_s }
       if body && %i[post put patch].include?(method.to_sym)
-        req['Content-Type'] = 'application/json'
+        req["Content-Type"] = "application/json"
         req.body = body.is_a?(String) ? body : JSON.generate(body)
       end
+
       req
     end
 
     def perform(uri, req, request_options:)
       http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = (uri.scheme == 'https')
+      http.use_ssl = (uri.scheme == "https")
       http.read_timeout = request_options[:timeout] || @configuration.timeout
       http.open_timeout = request_options[:timeout] || @configuration.timeout
       http.request(req)
     rescue Net::OpenTimeout, Net::ReadTimeout => e
       raise TimeoutError, e.message
+    rescue Errno::ECONNREFUSED,
+      Errno::EHOSTUNREACH,
+      Errno::ENETUNREACH,
+      Errno::ECONNRESET,
+      Errno::EPIPE,
+      SocketError,
+      OpenSSL::SSL::SSLError => e
+      raise ConnectionError, "#{e.class.name.split("::").last}: #{e.message}"
     end
 
     def raise_for_status(response)
       code = response.code.to_i
       return if code < 400
       body = parse_body(response)
-      message = body.is_a?(Hash) ? (body['message'] || body['error'] || response.message) : response.message
+      message = extract_error_message(body) || response.message
       args = {
         message: message,
         http_status: code,
-        request_id: response['x-request-id'],
-        code: body.is_a?(Hash) ? body['code'] : nil,
-        body: body,
+        request_id: response["x-request-id"],
+        code: extract_error_code(body),
+        body: body
       }
       case code
-      when 400 then raise BadRequestError.new(**args)
-      when 401 then raise AuthenticationError.new(**args)
-      when 403 then raise AuthorizationError.new(**args)
-      when 404 then raise NotFoundError.new(**args)
-      when 409 then raise ConflictError.new(**args)
-      when 422 then raise UnprocessableEntityError.new(**args)
-      when 429 then raise RateLimitExceededError.new(**args)
-      when 500..599 then raise InternalServerError.new(**args)
-      else raise APIError.new(**args)
+      when 400
+        raise BadRequestError.new(**args)
+      when 401
+        raise AuthenticationError.new(**args)
+      when 403
+        raise AuthorizationError.new(**args)
+      when 404
+        raise NotFoundError.new(**args)
+      when 409
+        raise ConflictError.new(**args)
+      when 422
+        raise UnprocessableEntityError.new(**args)
+      when 429
+        raise RateLimitExceededError.new(**args)
+      when 500..599
+        raise InternalServerError.new(**args)
+      else
+        raise APIError.new(**args)
       end
     end
 
@@ -124,5 +151,113 @@ module Retab
     rescue JSON::ParserError
       response.body
     end
+
+    # Walk Retab's nested error envelope to find the most specific
+    # human-readable message. The server uses two distinct shapes:
+    #
+    #   HTTPException family (4xx/5xx domain errors):
+    #     { "detail": { "code": "...", "message": "...",
+    #                   "details": { "error": "<the real one-liner>" } } }
+    #     { "detail": { "code": "...", "message": "...",
+    #                   "details": { "error": { "message": "<deep>",
+    #                                            "code": "..." } } } }
+    #
+    #   Validation family (422, FastAPI / pydantic):
+    #     { "status_code": 10422,
+    #       "message": "[{"type": "missing", "loc": [...], "msg": "Field required"}, ...]",
+    #       "data": null }
+    #
+    # Plus FastAPI's stock { "detail": "..." } and { "detail": [...] } forms.
+    # Fall back through every shape rather than returning "Bad Request".
+    def extract_error_message(body)
+      raw = walk_error_message(body)
+      # The validation-family wrapper carries a stringified JSON array in
+      # `message`. Unstringify and surface a readable summary instead of the
+      # opaque `[{"type": "missing", ...}]` blob.
+      if raw.is_a?(String) && raw.strip.start_with?("[", "{")
+        begin
+          require "json"
+
+          parsed = JSON.parse(raw)
+          return walk_error_message(parsed) || raw
+        rescue JSON::ParserError
+          # not actually JSON — keep the raw string
+        end
+      end
+
+      raw
+    end
+
+    # Recursive walk: unwrap each layer (detail / details / error / message),
+    # bottoming out at the first string. Handles arbitrary nesting depth so a
+    # `details.error` payload that is itself a {message, code} hash doesn't
+    # leak into the exception message verbatim.
+    #
+    # Order matters: we prefer the DEEPEST message (the most specific one).
+    # Walk into `details`/`detail`/`error` first; only fall back to the
+    # current level's `message` when no deeper string is reachable.
+    def walk_error_message(node)
+      case node
+      when nil
+        nil
+      when String
+        node
+      when Array
+        return nil if node.empty?
+        # FastAPI validation errors arrive as an Array of
+        # { type, loc, msg } hashes. Concatenate them into a single line
+        # like "msg1 (a.b); msg2 (x.y)" rather than just returning the
+        # first `msg` — multiple errors deserve to all surface.
+        if node.first.is_a?(Hash)
+          formatted = node
+            .map do |item|
+              msg = item["msg"] || item[:msg]
+              loc = item["loc"] || item[:loc]
+              if msg && loc.is_a?(Array) && !loc.empty?
+                "#{msg} (#{loc.join(".")})"
+              else
+                msg || walk_error_message(item)
+              end
+            end
+            .compact
+          return formatted.join("; ") unless formatted.empty?
+        end
+
+        node.first.to_s
+      when Hash
+        %w[details detail error].each do |k|
+          inner = node[k] || node[k.to_sym]
+          next if inner.nil?
+          result = walk_error_message(inner)
+          return result unless result.nil?
+        end
+
+        msg = node["message"] || node[:message]
+        return msg if msg.is_a?(String)
+        nil
+      else
+        node.to_s
+      end
+    end
+
+    def extract_error_code(body)
+      walk_error_code(body)
+    end
+
+    # Prefer the deepest code (same logic as walk_error_message). The outer
+    # envelope's code is generic ("HTTP_EXCEPTION"); deeper layers carry the
+    # specific one ("TARGET_HAS_NO_INPUT_HANDLE", etc.).
+    def walk_error_code(node)
+      return nil unless node.is_a?(Hash)
+      %w[details detail error].each do |k|
+        inner = node[k] || node[k.to_sym]
+        next if inner.nil?
+        c = walk_error_code(inner)
+        return c unless c.nil?
+      end
+
+      code = node["code"] || node[:code]
+      code.is_a?(String) ? code : nil
+    end
   end
 end

data/lib/retab/classifications/category.rb

@@ -11,12 +11,14 @@ module Retab
       description: :description
     }.freeze
 
-    attr_accessor \
+    attr_accessor(
       :name,
       :handle_key,
       :description
+    )
 
     def initialize(json)
+      super()
       hash = self.class.normalize(json)
       @name = hash[:name]
       @handle_key = hash[:handle_key]

data/lib/retab/classifications/classification.rb

@@ -18,7 +18,7 @@ module Retab
       created_at: :created_at
     }.freeze
 
-    attr_accessor \
+    attr_accessor(
       :id,
       :file,
       :model,
@@ -29,8 +29,10 @@ module Retab
       :consensus,
       :usage,
       :created_at
+    )
 
     def initialize(json)
+      super()
       hash = self.class.normalize(json)
       @id = hash[:id]
       @file = hash[:file] ? Retab::FileRef.new(hash[:file]) : nil

data/lib/retab/classifications/classification_consensus.rb

@@ -10,11 +10,13 @@ module Retab
       likelihoods: :likelihoods
     }.freeze
 
-    attr_accessor \
+    attr_accessor(
       :choices,
       :likelihoods
+    )
 
     def initialize(json)
+      super()
       hash = self.class.normalize(json)
       @choices = (hash[:choices] || []).map { |item| item ? Retab::ClassificationDecision.new(item) : nil }
       @likelihoods = hash[:likelihoods]

data/lib/retab/classifications/classification_decision.rb

@@ -10,11 +10,13 @@ module Retab
       category: :category
     }.freeze
 
-    attr_accessor \
+    attr_accessor(
       :reasoning,
       :category
+    )
 
     def initialize(json)
+      super()
       hash = self.class.normalize(json)
       @reasoning = hash[:reasoning]
       @category = hash[:category]

data/lib/retab/classifications/classification_request.rb

@@ -15,7 +15,7 @@ module Retab
       bust_cache: :bust_cache
     }.freeze
 
-    attr_accessor \
+    attr_accessor(
       :document,
       :categories,
       :model,
@@ -23,8 +23,10 @@ module Retab
       :instructions,
       :n_consensus,
       :bust_cache
+    )
 
     def initialize(json)
+      super()
       hash = self.class.normalize(json)
       @document = hash[:document] ? Retab::MimeData.new(hash[:document]) : nil
       @categories = (hash[:categories] || []).map { |item| item ? Retab::Category.new(item) : nil }

data/lib/retab/classifications.rb

@@ -2,7 +2,7 @@
 
 # This file is auto-generated by oagen. Do not edit.
 
-require 'json'
+require "json"
 
 module Retab
   class Classifications
@@ -19,34 +19,34 @@ module Retab
     # @param from_date [String, nil]
     # @param to_date [String, nil]
     # @param request_options [Hash] (see Retab::Types::RequestOptions)
-    # @return [Retab::Types::ListStruct<Retab::Classification>]
+    # @return [Retab::PaginatedList<Retab::Classification>]
     def list(
       before: nil,
       after: nil,
       limit: 10,
-      order: 'desc',
+      order: "desc",
       filename: nil,
       from_date: nil,
       to_date: nil,
       request_options: {}
     )
       params = {
-        'before' => before,
-        'after' => after,
-        'limit' => limit,
-        'order' => order,
-        'filename' => filename,
-        'from_date' => from_date,
-        'to_date' => to_date
+        "before" => before,
+        "after" => after,
+        "limit" => limit,
+        "order" => order,
+        "filename" => filename,
+        "from_date" => from_date,
+        "to_date" => to_date
       }.compact
       response = @client.request(
         method: :get,
-        path: '/v1/classifications',
+        path: "/v1/classifications",
         auth: true,
         params: params,
         request_options: request_options
       )
-      fetch_next = ->(cursor) {
+      fetch_next = -> (cursor) {
         list(
           before: before,
           after: cursor,
@@ -58,10 +58,17 @@ module Retab
           request_options: request_options
         )
       }
-      Retab::Types::ListStruct.from_response(
+      Retab::PaginatedList.from_response(
         response,
         model: Retab::Classification,
-        filters: { before: before, limit: limit, order: order, filename: filename, from_date: from_date, to_date: to_date },
+        filters: {
+          before: before,
+          limit: limit,
+          order: order,
+          filename: filename,
+          from_date: from_date,
+          to_date: to_date
+        },
         fetch_next: fetch_next
       )
     end
@@ -88,23 +95,27 @@ module Retab
     )
       document = Retab::MimeData.coerce(document) unless document.nil?
       body = {
-        'document' => document,
-        'categories' => categories,
-        'model' => model,
-        'first_n_pages' => first_n_pages,
-        'instructions' => instructions,
-        'n_consensus' => n_consensus,
-        'bust_cache' => bust_cache
+        "document" => document,
+        "categories" => categories,
+        "model" => model,
+        "first_n_pages" => first_n_pages,
+        "instructions" => instructions,
+        "n_consensus" => n_consensus,
+        "bust_cache" => bust_cache
       }.compact
       response = @client.request(
         method: :post,
-        path: '/v1/classifications',
+        path: "/v1/classifications",
         auth: true,
         body: body,
         request_options: request_options
       )
       result = Retab::Classification.new(response.body)
-      result.last_response = Retab::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
+      result.last_response = Retab::Types::ApiResponse.new(
+        http_status: response.code.to_i,
+        http_headers: response.each_header.to_h,
+        request_id: response["x-request-id"]
+      )
       result
     end
 
@@ -123,7 +134,11 @@ module Retab
         request_options: request_options
       )
       result = Retab::Classification.new(response.body)
-      result.last_response = Retab::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
+      result.last_response = Retab::Types::ApiResponse.new(
+        http_status: response.code.to_i,
+        http_headers: response.each_header.to_h,
+        request_id: response["x-request-id"]
+      )
       result
     end
 
@@ -135,7 +150,7 @@ module Retab
       classification_id:,
       request_options: {}
     )
-      response = @client.request(
+      @client.request(
         method: :delete,
         path: "/v1/classifications/#{Retab::Util.encode_path(classification_id)}",
         auth: true,

data/lib/retab/client.rb

@@ -33,78 +33,10 @@ module Retab
       @files ||= Retab::Files.new(self)
     end
 
-    def workflow_runs
-      @workflow_runs ||= Retab::WorkflowRuns.new(self)
-    end
-
-    def workflow_steps
-      @workflow_steps ||= Retab::WorkflowSteps.new(self)
-    end
-
-    def workflow_reviews
-      @workflow_reviews ||= Retab::WorkflowReviews.new(self)
-    end
-
-    def workflow_review_versions
-      @workflow_review_versions ||= Retab::WorkflowReviewVersions.new(self)
-    end
-
-    def workflow_artifacts
-      @workflow_artifacts ||= Retab::WorkflowArtifacts.new(self)
-    end
-
-    def workflow_test_runs
-      @workflow_test_runs ||= Retab::WorkflowTestRuns.new(self)
-    end
-
-    def workflow_test_run_results
-      @workflow_test_run_results ||= Retab::WorkflowTestRunResults.new(self)
-    end
-
-    def workflow_blocks
-      @workflow_blocks ||= Retab::WorkflowBlocks.new(self)
-    end
-
-    def workflow_edges
-      @workflow_edges ||= Retab::WorkflowEdges.new(self)
-    end
-
-    def workflow_tests
-      @workflow_tests ||= Retab::WorkflowTests.new(self)
-    end
-
-    def experiment_runs
-      @experiment_runs ||= Retab::ExperimentRuns.new(self)
-    end
-
-    def experiment_run_results
-      @experiment_run_results ||= Retab::ExperimentRunResults.new(self)
-    end
-
-    def experiment_run_metrics
-      @experiment_run_metrics ||= Retab::ExperimentRunMetrics.new(self)
-    end
-
-    def workflow_experiments
-      @workflow_experiments ||= Retab::WorkflowExperiments.new(self)
-    end
-
-    def workflow_block_executions
-      @workflow_block_executions ||= Retab::WorkflowBlockExecutions.new(self)
-    end
-
     def workflows
       @workflows ||= Retab::Workflows.new(self)
     end
 
-    def workflow_specs
-      @workflow_specs ||= Retab::WorkflowSpecs.new(self)
-    end
-
-    def edit_templates
-      @edit_templates ||= Retab::EditTemplates.new(self)
-    end
-
     def edits
       @edits ||= Retab::Edits.new(self)
     end

data/lib/retab/configuration.rb

@@ -1,22 +1,24 @@
 # frozen_string_literal: true
 
+# This file is auto-generated by oagen. Do not edit.
+
 # @oagen-ignore-file
 #
-# Hand-maintained configuration. Mirrors the spec-derived resources' usage
-# of `@client.api_key` and friends.
+# Hand-maintained configuration. The spec-driven resources read `@client.api_key`
+# and friends; defaults here drive that.
 
 module Retab
   class Configuration
-    DEFAULT_API_HOST = 'https://api.retab.com'
+    DEFAULT_API_HOST = "https://api.retab.com"
 
     attr_accessor :api_key, :api_host, :timeout, :max_retries, :user_agent
 
-    def initialize(api_key: nil, api_host: nil, timeout: nil, max_retries: nil, user_agent: nil)
+    def initialize(api_key: nil, api_host: nil, base_url: nil, timeout: nil, max_retries: nil, user_agent: nil)
       @api_key = api_key
-      @api_host = api_host || DEFAULT_API_HOST
+      @api_host = api_host || base_url || DEFAULT_API_HOST
       @timeout = timeout || 60
       @max_retries = max_retries || 3
-      @user_agent = user_agent || "retab-ruby/#{Retab::VERSION rescue '0.1.0'}"
+      @user_agent = user_agent || "retab-ruby/#{Retab::VERSION rescue "0.1.0"}"
     end
   end
 end

data/lib/retab/edit_templates/create_edit_template_request.rb

@@ -11,12 +11,14 @@ module Retab
       form_fields: :form_fields
     }.freeze
 
-    attr_accessor \
+    attr_accessor(
       :name,
       :document,
       :form_fields
+    )
 
     def initialize(json)
+      super()
       hash = self.class.normalize(json)
       @name = hash[:name]
       @document = hash[:document] ? Retab::MimeData.new(hash[:document]) : nil

data/lib/retab/edit_templates/edit_template.rb

@@ -15,7 +15,7 @@ module Retab
       updated_at: :updated_at
     }.freeze
 
-    attr_accessor \
+    attr_accessor(
       :id,
       :name,
       :file,
@@ -23,8 +23,10 @@ module Retab
       :field_count,
       :created_at,
       :updated_at
+    )
 
     def initialize(json)
+      super()
       hash = self.class.normalize(json)
       @id = hash[:id]
       @name = hash[:name]

data/lib/retab/edit_templates/update_edit_template_request.rb

@@ -10,11 +10,13 @@ module Retab
       form_fields: :form_fields
     }.freeze
 
-    attr_accessor \
+    attr_accessor(
       :name,
       :form_fields
+    )
 
     def initialize(json)
+      super()
       hash = self.class.normalize(json)
       @name = hash[:name]
       @form_fields = (hash[:form_fields] || []).map { |item| item ? Retab::FormField.new(item) : nil }