reducto_ai 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f3f04f8ea07aee427498d4c7ba86fb8c75d9dca84c2ed58a05847b6ba4a314a
-  data.tar.gz: 8ae056c6425f3c9b627b689df5a5dbc68f29cc1179b981a0c98a2083e55ba4b2
+  metadata.gz: e94dd6ff1f85cd61aed7ca9c9a1cd6a62318a99b6caa941cd4e2cbee608d69f7
+  data.tar.gz: 80da8255e7d17627bda7fa1fdcf14bb5c2fd6795514868cf939d76f135bca8e5
 SHA512:
-  metadata.gz: b29571a22856368389897a10e62a0c8c9eba9e5bf0e1255b31be83e2f42506705aa9b31efc51c8742d5918255cea81f3e1965cd6a8ca6847e1cade2423af588a
-  data.tar.gz: 5cf91cf24e3e5977c096696bbfe126d66341ce2c778a28d90be2539c2c9614506e47c317f8d5f81f8c06e661760ed338b9aa59d1ada9881c9ae843bedbe82b5e
+  metadata.gz: 7429c001e1349f3ecdaaf60c3908c6b2a730d7b1780fed07df786c755cfafcab9952dd4a3673fd3e653e3dbd848510519c17cae52d4bae0be692ea90a5b0eff6
+  data.tar.gz: a9e0d1f1e03e80f420a0a77c98789ed6ad6df2b4b94c350c63ad76091298651a91dd923bea9e541e35b7a6786af142bcd280d225aa6a4bd705dfb7c547428033

data/CHANGELOG.md

@@ -1,3 +1,36 @@
+## [Unreleased]
+
+## [0.2.0] - 2026-03-30
+
+### Added
+- Async payload support for parse/extract/split/edit/pipeline using current Reducto async options
+- `Resources::Jobs` lifecycle helpers: status normalization, predicates, and `wait`
+- Svix-backed webhook verification helpers and a thin Rails request verifier
+- New job/webhook error classes and configuration for webhook secrets
+- `RateLimitError` exception class for HTTP 429 responses
+- Path traversal protection in job_id validation
+- `AsyncPayload` module for shared async options handling
+- Comprehensive test coverage for async operations, webhook verification, and job lifecycle
+
+### Changed
+- README examples now reflect current async lifecycle and webhook portal behavior
+- Test suite expanded to cover async payload translation, job polling, webhook verification, and edge cases
+- `RequestVerifier` now extracts only webhook headers (svix-*) instead of full Rack environment
+- Consolidated `normalize_input` method into shared `AsyncPayload` module
+- Simplified `Jobs` class to use `include ReductoAI::JobStatus` instead of delegation
+- Lazy-load Svix gem only when webhook verification is used
+- Case-insensitive status normalization via downcase lookup
+- Replaced deprecated `Faraday::UploadIO` with `Faraday::Multipart::FilePart`
+- HTTP 403 now handled as standard client error
+
+### Fixed
+- Security: Path traversal vulnerability in cancel/retrieve job_id interpolation
+- Security: Rack environment variable leak in webhook header extraction
+- Error handling: Added user-friendly message for invalid Svix secret format
+- Error handling: HTTP 429 (rate limit) now raises dedicated exception
+- Error handling: HTTP 403 (forbidden) now properly caught as client error
+- Code quality: Removed dead `raise_exceptions` configuration attribute
+
 ## [0.1.3] - 2026-01-04
 
 ### Added

data/README.md

@@ -27,49 +27,51 @@ end
 - **Split**: Use after parsing when you need logical sections. Provide `split_description` names/rules to segment the parsed document into labeled ranges.
 - **Extract**: Run when you need structured answers (fields, JSON). Supply instructions or schema to pull values from raw input or an existing parse `job_id`.
 - **Edit**: Generate marked-up PDFs using `document_url` plus `edit_instructions` (PDF forms supported via `form_schema`).
-- **Pipeline**: Trigger a saved Studio pipeline with `input` + `pipeline_id` to orchestrate Parse/Split/Extract/Edit in one call.
+- **Pipeline**: The current gem surface remains `steps:`-based for multi-step workflows.
 
 ### Async Operations
 
-All resources support async variants that return a `job_id` for polling:
+Async variants return immediately with a `job_id`. Use `client.jobs.wait(...)` for polling or configure Svix-backed webhooks in your app.
+
+Notes:
+- Reducto prioritizes sync jobs over async jobs.
+- Async results may be deleted on Reducto's normal 12-hour cleanup cadence unless you persist them yourself or opt into `persist_results`.
+- `client.jobs.configure_webhook` returns a Svix portal URL string.
+- `client.jobs.wait` requires either `timeout:` or `max_attempts:` so it cannot poll forever by accident.
+- `client.edit.async` is the exception to the generic async shape: Reducto's `/edit_async` endpoint only accepts top-level `priority` and `webhook`, not async `metadata`.
 
 ```ruby
 client = ReductoAI::Client.new
 
-# Start async parse
-# API Reference: https://docs.reducto.ai/api-reference/parse-async
-job = client.parse.async(input: "https://example.com/large-doc.pdf")
-job_id = job["job_id"]
+job = client.parse.async(
+  input: "https://example.com/large-doc.pdf",
+  output_formats: { markdown: true },
+  async: {
+    priority: false,
+    webhook: { mode: "svix", channels: ["production"] },
+    metadata: { document_id: "doc-123" }
+  },
+  settings: { persist_results: true }
+)
 
-# Response:
-# {
-#   "job_id" => "async-123",
-#   "status" => "processing"
-# }
+# => { "job_id" => "async-123", "status" => "Pending" }
 
-# Poll for completion
-# API Reference: https://docs.reducto.ai/api-reference/get-job
-result = client.jobs.retrieve(job_id: job_id)
+result = client.jobs.wait(job_id: job["job_id"], interval: 2, timeout: 300)
 
-# Response:
-# {
-#   "job_id" => "async-123",
-#   "status" => "complete",
-#   "result" => {...},
-#   "usage" => {"credits" => 1.0}
-# }
+# => { "job_id" => "async-123", "status" => "Completed", "result" => {...} }
 
-# Or configure webhooks for notifications
-# API Reference: https://docs.reducto.ai/api-reference/webhook-portal
-client.jobs.configure_webhook
+portal_url = client.jobs.configure_webhook
+# => "https://dashboard.svix.com/..."
 ```
 
-Available async methods:
-- `client.parse.async(input:, **options)` - [Parse Async API](https://docs.reducto.ai/api-reference/parse-async)
-- `client.extract.async(input:, instructions:, **options)` - [Extract Async API](https://docs.reducto.ai/api-reference/extract-async)
-- `client.split.async(input:, **options)` - [Split Async API](https://docs.reducto.ai/api-reference/split-async)
-- `client.edit.async(input:, instructions:, **options)` - [Edit Async API](https://docs.reducto.ai/api-reference/edit-async)
-- `client.pipeline.async(input:, steps:, **options)` - [Pipeline Async API](https://docs.reducto.ai/api-reference/pipeline-async)
+Available async helpers:
+- `client.parse.async(input:, async:, **options)`
+- `client.extract.async(input:, instructions:, async:, **options)`
+- `client.split.async(input:, async:, **options)`
+- `client.edit.async(input:, instructions:, async:, **options)` where `async:` may only include `priority` and `webhook`
+- `client.pipeline.async(input:, steps:, async:, **options)`
+- `client.jobs.wait(job_id:, interval: 2, timeout: nil, max_attempts: nil, raise_on_failure: true)`
+- `client.jobs.pending?/in_progress?/completing?/completed?/failed?/terminal?`
 
 ### Rails
 
@@ -78,14 +80,38 @@ Create `config/initializers/reducto_ai.rb`:
 ```ruby
 ReductoAI.configure do |c|
   c.api_key = Rails.application.credentials.dig(:reducto, :api_key)
+  c.webhook_secret = Rails.application.credentials.dig(:reducto, :webhook_secret)
   # c.base_url = "https://platform.reducto.ai"
   # c.open_timeout = 5; c.read_timeout = 30
 end
+```
 
-# Optional: override shared client (multi-tenant or custom timeouts)
-# ReductoAI.client = ReductoAI::Client.new(api_key: ..., read_timeout: 10)
+In your host app, own the route/controller/job:
+
+```ruby
+# config/routes.rb
+post "/webhooks/reducto", to: "reducto_webhooks#create"
 ```
 
+```ruby
+class ReductoWebhooksController < ActionController::API
+  def create
+    event = ReductoAI::Rails::RequestVerifier.verify!(request)
+
+    return head :ok if WebhookDelivery.exists?(provider: "reducto", delivery_id: event.svix_id)
+
+    WebhookDelivery.create!(provider: "reducto", delivery_id: event.svix_id, job_id: event.job_id)
+    ReductoWebhookJob.perform_later(event.job_id, event.svix_id)
+
+    head :ok
+  rescue ReductoAI::WebhookVerificationError
+    head :unauthorized
+  end
+end
+```
+
+Return 2xx quickly, dedupe on `svix-id`, and fetch/store final results in the background job.
+
 ### Quick Start
 
 ```ruby
@@ -99,7 +125,7 @@ job_id = parse["job_id"]
 # Response:
 # {
 #   "job_id" => "abc-123",
-#   "status" => "complete",
+#   "status" => "Completed",
 #   "result" => {...}
 # }
 
@@ -141,7 +167,7 @@ parse = client.parse.sync(input: "https://example.com/invoices.pdf")
 # Response:
 # {
 #   "job_id" => "parse-123",
-#   "status" => "complete",
+#   "status" => "Completed",
 #   "result" => {...}
 # }
 
@@ -362,11 +388,7 @@ job = client.parse.async(input: large_pdf_url)
 job_id = job["job_id"]
 
 # Poll or use webhooks
-loop do
-  result = client.jobs.retrieve(job_id: job_id)
-  break if result["status"] == "complete"
-  sleep 2
-end
+result = client.jobs.wait(job_id: job_id, interval: 2, timeout: 300)
 
 # Then reuse the job_id for split/extract
 split = client.split.sync(input: job_id, split_description: [...])

data/lib/reducto_ai/client.rb

@@ -3,6 +3,7 @@
 require "faraday"
 require "json"
 require "faraday/multipart"
+require_relative "resources/async_payload"
 require_relative "resources/parse"
 require_relative "resources/extract"
 require_relative "resources/split"
@@ -176,6 +177,7 @@ module ReductoAI
 
       parsed_body = parse_error_body(body)
       return handle_auth_error(parsed_body, status) if status == 401
+      return handle_rate_limit_error(parsed_body, status) if status == 429
       return handle_client_error(parsed_body, status) if client_error?(status)
       return handle_server_error(parsed_body, status) if server_error?(status)
 
@@ -214,7 +216,7 @@ module ReductoAI
     end
 
     def client_error?(status)
-      [400, 404, 422].include?(status)
+      [400, 403, 404, 422].include?(status)
     end
 
     def server_error?(status)
@@ -225,6 +227,10 @@ module ReductoAI
       raise AuthenticationError.new("Unauthorized (401): check API key", status: status, body: body)
     end
 
+    def handle_rate_limit_error(body, status)
+      raise RateLimitError.new(error_message(status, body), status: status, body: body)
+    end
+
     def handle_client_error(body, status)
       raise ClientError.new(error_message(status, body), status: status, body: body)
     end

data/lib/reducto_ai/config.rb

@@ -38,8 +38,11 @@ module ReductoAI
     # @return [Integer] Request read timeout in seconds (default: 30)
     attr_accessor :read_timeout
 
-    # @return [Boolean] Whether to raise exceptions on API errors (default: true)
-    attr_accessor :raise_exceptions
+    # @return [String, nil] Svix webhook signing secret
+    attr_accessor :webhook_secret
+
+    # @return [Proc, nil] Proc that resolves webhook secret from request headers
+    attr_accessor :webhook_secret_resolver
 
     # @return [Logger] Logger instance for debugging
     attr_writer :logger
@@ -50,7 +53,8 @@ module ReductoAI
       @base_url = ENV.fetch("REDUCTO_BASE_URL", "https://platform.reducto.ai")
       @open_timeout = integer_or_default("REDUCTO_OPEN_TIMEOUT", 5)
       @read_timeout = integer_or_default("REDUCTO_READ_TIMEOUT", 30)
-      @raise_exceptions = true
+      @webhook_secret = ENV.fetch("REDUCTO_WEBHOOK_SECRET", nil)
+      @webhook_secret_resolver = nil
     end
 
     # Returns the logger instance.
@@ -59,7 +63,7 @@ module ReductoAI
     #
     # @return [Logger] the logger instance
     def logger
-      @logger ||= (defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger) || Logger.new($stderr)
+      @logger ||= (defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger) || Logger.new($stderr)
     end
 
     private

data/lib/reducto_ai/engine.rb

@@ -7,7 +7,7 @@ module ReductoAI
   # loading and configuration within Rails applications.
   #
   # @api private
-  if defined?(Rails)
+  if defined?(::Rails)
     class Engine < ::Rails::Engine
       isolate_namespace ReductoAI
     end

data/lib/reducto_ai/errors.rb

@@ -57,6 +57,12 @@ module ReductoAI
   #   # => ReductoAI::ClientError: HTTP 400: Invalid input URL
   class ClientError < Error; end
 
+  # Raised on 429 Too Many Requests responses.
+  #
+  # Indicates API rate limit has been exceeded. Consumers should implement
+  # retry logic with backoff.
+  class RateLimitError < ClientError; end
+
   # Raised on 5xx server errors.
   #
   # Indicates Reducto API internal errors or temporary failures.
@@ -77,4 +83,13 @@ module ReductoAI
   #   client.parse.sync(input: "https://example.com/large-doc.pdf")
   #   # => ReductoAI::NetworkError: Network error: execution expired
   class NetworkError < Error; end
+
+  # Raised when waiting for an async job exceeds the configured timeout or attempt limit.
+  class JobTimeoutError < Error; end
+
+  # Raised when an async job reaches a failed terminal state.
+  class JobFailedError < Error; end
+
+  # Raised when webhook signature verification fails.
+  class WebhookVerificationError < Error; end
 end

data/lib/reducto_ai/job_status.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ReductoAI
+  module JobStatus
+    extend self
+
+    STATUS_MAP = {
+      "pending" => "Pending",
+      "idle" => "Pending",
+      "inprogress" => "InProgress",
+      "processing" => "InProgress",
+      "running" => "InProgress",
+      "completing" => "Completing",
+      "completed" => "Completed",
+      "complete" => "Completed",
+      "succeeded" => "Completed",
+      "failed" => "Failed"
+    }.freeze
+
+    def normalize_status(value_or_response)
+      raw_status = extract_status(value_or_response)
+      return nil if raw_status.nil?
+
+      STATUS_MAP.fetch(raw_status.to_s.downcase, raw_status.to_s)
+    end
+
+    def pending?(value_or_response)
+      normalize_status(value_or_response) == "Pending"
+    end
+
+    def in_progress?(value_or_response)
+      normalize_status(value_or_response) == "InProgress"
+    end
+
+    def completing?(value_or_response)
+      normalize_status(value_or_response) == "Completing"
+    end
+
+    def completed?(value_or_response)
+      normalize_status(value_or_response) == "Completed"
+    end
+
+    def failed?(value_or_response)
+      normalize_status(value_or_response) == "Failed"
+    end
+
+    def terminal?(value_or_response)
+      completed?(value_or_response) || failed?(value_or_response)
+    end
+
+    private
+
+    def extract_status(value_or_response)
+      case value_or_response
+      when Hash
+        value_or_response["status"] || value_or_response[:status]
+      else
+        if value_or_response.respond_to?(:status)
+          value_or_response.status
+        else
+          value_or_response
+        end
+      end
+    end
+  end
+end

data/lib/reducto_ai/rails/request_verifier.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ReductoAI
+  module Rails
+    class RequestVerifier
+      WEBHOOK_HEADERS = %w[svix-id svix-timestamp svix-signature].freeze
+      private_constant :WEBHOOK_HEADERS
+
+      class << self
+        def verify!(request, secret: nil)
+          payload = request.raw_post
+          headers = extract_webhook_headers(request)
+          verified_payload = Webhooks::Verifier.verify!(payload: payload, headers: headers, secret: secret)
+
+          Webhooks::Event.parse(verified_payload, headers: headers)
+        end
+
+        private
+
+        def extract_webhook_headers(request)
+          WEBHOOK_HEADERS.each_with_object({}) do |key, h|
+            value = request.headers[key]
+            h[key] = value.to_s if value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/reducto_ai/resources/async_payload.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ReductoAI
+  module Resources
+    module AsyncPayload
+      private
+
+      def normalize_input(input)
+        return input unless input.is_a?(Hash)
+
+        input[:url] || input["url"] || input
+      end
+
+      def apply_async_payload!(payload, async)
+        normalized_async = normalize_async_payload(async)
+        payload[:async] = normalized_async unless normalized_async.nil?
+        payload
+      end
+
+      def normalize_async_payload(async)
+        case async
+        when nil, false
+          nil
+        when true
+          {}
+        when Hash
+          deep_compact(async)
+        else
+          raise ArgumentError, "async must be a Hash, true, false, or nil"
+        end
+      end
+
+      def deep_compact(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, child_value), compacted|
+            normalized_child = deep_compact(child_value)
+            compacted[key] = normalized_child unless normalized_child.nil?
+          end
+        when Array
+          value.map { |child_value| deep_compact(child_value) }.compact
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/reducto_ai/resources/edit.rb

@@ -18,6 +18,8 @@ module ReductoAI
     # @note Edit operations consume credits based on document size and
     #   instruction complexity.
     class Edit
+      include AsyncPayload
+
       # @param client [Client] the Reducto API client
       # @api private
       def initialize(client)
@@ -33,7 +35,7 @@ module ReductoAI
       #
       # @return [Hash] Edit results with keys:
       #   * "job_id" [String] - Job identifier
-      #   * "status" [String] - Job status ("succeeded")
+      #   * "status" [String] - Job status ("Completed")
       #   * "result" [Hash] - Contains "document_url" with marked PDF
       #   * "usage" [Hash] - Credit usage details
       #
@@ -64,12 +66,14 @@ module ReductoAI
       #
       # @param input [String, Hash] Document URL or hash with :url key
       # @param instructions [String] Natural language editing instructions
-      # @param async [Boolean, nil] Async mode flag
+      # @param async [Boolean, Hash, nil] Async options. `true` keeps the legacy no-options call,
+      #   while a hash is translated to Reducto's current top-level edit async fields.
+      #   `/edit_async` only accepts `priority` and `webhook`, not generic async metadata.
       # @param options [Hash] Additional editing options
       #
       # @return [Hash] Job status with keys:
       #   * "job_id" [String] - Job identifier for polling
-      #   * "status" [String] - Initial status ("processing")
+      #   * "status" [String] - Initial status ("Pending")
       #
       # @raise [ArgumentError] if input or instructions are nil/empty
       #
@@ -88,8 +92,9 @@ module ReductoAI
           raise ArgumentError, "instructions are required"
         end
 
-        payload = build_payload(input, instructions, options)
-        payload[:async] = async unless async.nil?
+        payload = build_payload(input, instructions, {})
+        payload.merge!(translate_async_options(async))
+        payload.merge!(options.compact)
 
         @client.post("/edit_async", payload)
       end
@@ -102,11 +107,26 @@ module ReductoAI
         { document_url: document_url, edit_instructions: instructions, **options }.compact
       end
 
-      # @private
-      def normalize_input(input)
-        return input unless input.is_a?(Hash)
+      # Edit API uses top-level async keys (priority, webhook) rather than
+      # the nested `async` object used by other resources. This mirrors the
+      # Reducto API design where edit_async accepts these fields at root level.
+      def translate_async_options(async)
+        case async
+        when nil, false, true
+          {}
+        when Hash
+          normalized_async = async.each_with_object({}) do |(key, value), normalized|
+            normalized[key.to_sym] = value
+          end
+          unsupported_keys = normalized_async.keys - %i[priority webhook]
+          unless unsupported_keys.empty?
+            raise ArgumentError, "unsupported async options: #{unsupported_keys.join(", ")}"
+          end
 
-        input[:url] || input["url"] || input
+          normalized_async.compact
+        else
+          raise ArgumentError, "async must be a Hash, true, false, or nil"
+        end
       end
     end
   end

data/lib/reducto_ai/resources/extract.rb

@@ -24,6 +24,8 @@ module ReductoAI
     # @note Extraction operations consume credits based on document complexity
     #   and schema size.
     class Extract
+      include AsyncPayload
+
       # @param client [Client] the Reducto API client
       # @api private
       def initialize(client)
@@ -40,7 +42,7 @@ module ReductoAI
       #
       # @return [Hash] Extraction results with keys:
       #   * "job_id" [String] - Job identifier
-      #   * "status" [String] - Job status ("succeeded")
+      #   * "status" [String] - Job status ("Completed")
       #   * "result" [Hash] - Extracted data matching schema
       #   * "usage" [Hash] - Credit usage details
       #
@@ -74,12 +76,13 @@ module ReductoAI
       #
       # @param input [String, Hash] Document URL or hash with :url key
       # @param instructions [Hash, String] Extraction schema (same as {#sync})
-      # @param async [Boolean, nil] Async mode flag
+      # @param async [Boolean, Hash, nil] Async options. `true` becomes an empty async payload,
+      #   while a hash is sent as Reducto's nested `async` object.
       # @param options [Hash] Additional extraction options
       #
       # @return [Hash] Job status with keys:
       #   * "job_id" [String] - Job identifier for polling
-      #   * "status" [String] - Initial status ("processing")
+      #   * "status" [String] - Initial status ("Pending")
       #
       # @raise [ArgumentError] if input or instructions are nil/empty
       #
@@ -99,7 +102,7 @@ module ReductoAI
         end
 
         payload = build_payload(input, instructions, options)
-        payload[:async] = async unless async.nil?
+        apply_async_payload!(payload, async)
 
         @client.post("/extract_async", payload)
       end
@@ -114,13 +117,6 @@ module ReductoAI
         { input: normalized_input, instructions: normalized_instructions, **options }.compact
       end
 
-      # @private
-      def normalize_input(input)
-        return input unless input.is_a?(Hash)
-
-        input[:url] || input["url"] || input
-      end
-
       # @private
       def normalize_instructions(instructions)
         return { schema: instructions } unless instructions.is_a?(Hash)

data/lib/reducto_ai/resources/jobs.rb

@@ -13,7 +13,7 @@ module ReductoAI
     #
     #   loop do
     #     status = client.jobs.retrieve(job_id: job["job_id"])
-    #     break if status["status"] == "succeeded"
+    #     break if client.jobs.completed?(status)
     #     sleep 2
     #   end
     #   result = status["result"]
@@ -23,6 +23,8 @@ module ReductoAI
     #   document_url = upload_result["url"]
     #   client.parse.sync(input: document_url)
     class Jobs
+      include ReductoAI::JobStatus
+
       # @param client [Client] the Reducto API client
       # @api private
       def initialize(client)
@@ -43,7 +45,7 @@ module ReductoAI
       # Lists jobs with optional filtering.
       #
       # @param options [Hash] Query parameters for filtering
-      # @option options [String] :status Filter by job status ("processing", "succeeded", "failed")
+      # @option options [String] :status Filter by raw job status returned by Reducto
       # @option options [Integer] :limit Maximum number of jobs to return
       # @option options [Integer] :offset Pagination offset
       #
@@ -59,7 +61,8 @@ module ReductoAI
       # @see https://docs.reducto.ai/api-reference/jobs
       def list(**options)
         params = options.compact
-        @client.request(:get, "/jobs", params: params)
+        response = @client.request(:get, "/jobs", params: params)
+        normalize_job_list(response)
       end
 
       # Cancels a running async job.
@@ -76,7 +79,7 @@ module ReductoAI
       #
       # @see https://docs.reducto.ai/api-reference/cancel
       def cancel(job_id:)
-        raise ArgumentError, "job_id is required" if job_id.nil? || job_id.to_s.strip.empty?
+        validate_job_id!(job_id)
 
         @client.request(:post, "/cancel/#{job_id}")
       end
@@ -90,9 +93,9 @@ module ReductoAI
       #
       # @return [Hash] Job status with keys:
       #   * "job_id" [String] - Job identifier
-      #   * "status" [String] - Current status ("processing", "succeeded", "failed")
-      #   * "result" [Hash] - Results (only present when status is "succeeded")
-      #   * "error" [String] - Error message (only present when status is "failed")
+      #   * "status" [String] - Current raw Reducto status (for example "Pending", "Completed", "Failed")
+      #   * "result" [Hash] - Results (only present when the job completed)
+      #   * "error" [String] - Error message (only present when the job failed)
       #
       # @raise [ArgumentError] if job_id is nil or empty
       # @raise [ClientError] if job doesn't exist
@@ -100,13 +103,13 @@ module ReductoAI
       # @example Poll until complete
       #   loop do
       #     status = client.jobs.retrieve(job_id: job_id)
-      #     break if %w[succeeded failed].include?(status["status"])
+      #     break if client.jobs.terminal?(status)
       #     sleep 2
       #   end
       #
       # @see https://docs.reducto.ai/api-reference/job
       def retrieve(job_id:)
-        raise ArgumentError, "job_id is required" if job_id.nil? || job_id.to_s.strip.empty?
+        validate_job_id!(job_id)
 
         @client.request(:get, "/job/#{job_id}")
       end
@@ -149,18 +152,107 @@ module ReductoAI
 
       # Configures webhook notifications for async jobs.
       #
-      # @return [Hash] Webhook configuration result
+      # @return [String] Svix portal URL for webhook configuration
       #
       # @example
       #   client.jobs.configure_webhook
       #
-      # @see https://docs.reducto.ai/api-reference/configure-webhook
+      # @see https://docs.reducto.ai/api-reference/webhook-portal
       def configure_webhook
-        @client.request(:post, "/configure_webhook")
+        response = @client.request(:post, "/configure_webhook")
+        normalize_webhook_portal_url(response)
+      end
+
+      def wait(job_id:, interval: 2, timeout: nil, max_attempts: nil, raise_on_failure: true)
+        validate_wait_arguments!(interval: interval, timeout: timeout, max_attempts: max_attempts)
+
+        started_at = monotonic_time
+        attempts = 0
+
+        loop do
+          attempts += 1
+          response = retrieve(job_id: job_id)
+          terminal_response = resolve_terminal_response(job_id, response, raise_on_failure)
+          return terminal_response if terminal_response
+
+          raise_if_attempt_limit_reached!(job_id, response, attempts, max_attempts)
+          raise_if_timeout_exceeded!(job_id, response, started_at, timeout)
+          sleep(interval)
+        end
       end
 
       private
 
+      def validate_job_id!(job_id)
+        raise ArgumentError, "job_id is required" if job_id.nil? || job_id.to_s.strip.empty?
+        raise ArgumentError, "job_id contains invalid characters" unless job_id.to_s.match?(/\A[\w\-.]+\z/)
+      end
+
+      def validate_wait_arguments!(interval:, timeout:, max_attempts:)
+        validate_wait_interval!(interval)
+        validate_wait_timeout!(timeout)
+        validate_wait_max_attempts!(max_attempts)
+        validate_wait_bounds!(timeout, max_attempts)
+      end
+
+      def validate_wait_interval!(interval)
+        raise ArgumentError, "interval must be non-negative" if interval.negative?
+      end
+
+      def validate_wait_timeout!(timeout)
+        raise ArgumentError, "timeout must be non-negative" if timeout&.negative?
+      end
+
+      def validate_wait_max_attempts!(max_attempts)
+        raise ArgumentError, "max_attempts must be positive" if max_attempts && max_attempts < 1
+      end
+
+      def validate_wait_bounds!(timeout, max_attempts)
+        raise ArgumentError, "timeout or max_attempts is required" if timeout.nil? && max_attempts.nil?
+      end
+
+      def resolve_terminal_response(job_id, response, raise_on_failure)
+        return response if completed?(response)
+        return nil unless failed?(response)
+        return response unless raise_on_failure
+
+        raise JobFailedError.new(response["error"] || "Job #{job_id} failed", body: response)
+      end
+
+      def raise_if_attempt_limit_reached!(job_id, response, attempts, max_attempts)
+        return unless max_attempts && attempts >= max_attempts
+
+        raise JobTimeoutError.new("Timed out waiting for job #{job_id}", body: response)
+      end
+
+      def raise_if_timeout_exceeded!(job_id, response, started_at, timeout)
+        return unless timeout && (monotonic_time - started_at) >= timeout
+
+        raise JobTimeoutError.new("Timed out waiting for job #{job_id}", body: response)
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def normalize_job_list(response)
+        return response if response.is_a?(Hash)
+        return { "results" => response, "next_cursor" => nil } if response.is_a?(Array)
+
+        response
+      end
+
+      def normalize_webhook_portal_url(response)
+        return response if response.is_a?(String)
+
+        if response.is_a?(Hash)
+          portal_url = response["portal_url"] || response[:portal_url] || response["url"] || response[:url]
+          return portal_url if portal_url.is_a?(String)
+        end
+
+        raise ServerError.new("Unexpected webhook portal response", body: response)
+      end
+
       # @private
       def build_upload_io(file)
         if file.is_a?(String)
@@ -173,9 +265,8 @@ module ReductoAI
                      else
                        "upload"
                      end
-
         end
-        Faraday::UploadIO.new(file, "application/octet-stream", filename)
+        Faraday::Multipart::FilePart.new(file, "application/octet-stream", filename)
       end
     end
   end

data/lib/reducto_ai/resources/parse.rb

@@ -29,6 +29,8 @@ module ReductoAI
     # @note Each parse operation consumes credits based on document complexity.
     #   See Reducto documentation for pricing details.
     class Parse
+      include AsyncPayload
+
       # @param client [Client] the Reducto API client
       # @api private
       def initialize(client)
@@ -48,7 +50,7 @@ module ReductoAI
       #
       # @return [Hash] Parsed document with keys:
       #   * "job_id" [String] - Job identifier
-      #   * "status" [String] - Job status ("succeeded")
+      #   * "status" [String] - Job status ("Completed")
       #   * "result" [Hash] - Parsed content by format (e.g., "markdown", "html")
       #   * "usage" [Hash] - Credit usage details
       #
@@ -76,12 +78,13 @@ module ReductoAI
       # Returns immediately with a job_id. Poll with {Jobs#retrieve} to get results.
       #
       # @param input [String, Hash] Document URL or hash with :url key
-      # @param async [Boolean, nil] Async mode flag (defaults to true if not provided)
+      # @param async [Boolean, Hash, nil] Async options. `true` becomes an empty async payload,
+      #   while a hash is sent as Reducto's nested `async` object.
       # @param options [Hash] Additional parsing options (same as {#sync})
       #
       # @return [Hash] Job status with keys:
       #   * "job_id" [String] - Job identifier for polling
-      #   * "status" [String] - Initial status ("processing")
+      #   * "status" [String] - Initial status ("Pending")
       #
       # @raise [ArgumentError] if input is nil
       #
@@ -92,31 +95,22 @@ module ReductoAI
       #   # Poll for completion
       #   loop do
       #     status = client.jobs.retrieve(job_id: job_id)
-      #     break if status["status"] == "succeeded"
+      #     break if client.jobs.completed?(status)
       #     sleep 2
       #   end
       #
       # @see Jobs#retrieve
-      # @see https://docs.reducto.ai/api-reference/parse-async Reducto Async Parse
+      # @see https://docs.reducto.ai/api-reference/async-parse Reducto Async Parse
       def async(input:, async: nil, **options)
         raise ArgumentError, "input is required" if input.nil?
 
         normalized_input = normalize_input(input)
         payload = { input: normalized_input }
-        payload[:async] = async unless async.nil?
+        apply_async_payload!(payload, async)
         payload.merge!(options.compact)
 
         @client.post("/parse_async", payload)
       end
-
-      private
-
-      # @private
-      def normalize_input(input)
-        return input unless input.is_a?(Hash)
-
-        input[:url] || input["url"] || input
-      end
     end
   end
 end

data/lib/reducto_ai/resources/pipeline.rb

@@ -20,6 +20,8 @@ module ReductoAI
     #
     # @note Pipeline operations consume credits based on all steps executed.
     class Pipeline
+      include AsyncPayload
+
       # @param client [Client] the Reducto API client
       # @api private
       def initialize(client)
@@ -36,7 +38,7 @@ module ReductoAI
       #
       # @return [Hash] Pipeline results with keys:
       #   * "job_id" [String] - Job identifier
-      #   * "status" [String] - Job status ("succeeded")
+      #   * "status" [String] - Job status ("Completed")
       #   * "result" [Hash] - Contains "steps" array with each step's result
       #   * "usage" [Hash] - Credit usage details
       #
@@ -68,12 +70,13 @@ module ReductoAI
       #
       # @param input [String, Hash] Document URL or hash with :url key
       # @param steps [Array<Hash>] Array of step configurations (same as {#sync})
-      # @param async [Boolean, nil] Async mode flag
+      # @param async [Boolean, Hash, nil] Async options. `true` becomes an empty async payload,
+      #   while a hash is sent as Reducto's nested `async` object.
       # @param options [Hash] Additional pipeline options
       #
       # @return [Hash] Job status with keys:
       #   * "job_id" [String] - Job identifier for polling
-      #   * "status" [String] - Initial status ("processing")
+      #   * "status" [String] - Initial status ("Pending")
       #
       # @raise [ArgumentError] if input or steps are nil/empty
       #
@@ -94,7 +97,7 @@ module ReductoAI
         raise ArgumentError, "steps are required" if steps.nil? || (steps.respond_to?(:empty?) && steps.empty?)
 
         payload = { input: input, steps: steps }
-        payload[:async] = async unless async.nil?
+        apply_async_payload!(payload, async)
         payload.merge!(options.compact)
 
         @client.post("/pipeline_async", payload)

data/lib/reducto_ai/resources/split.rb

@@ -18,6 +18,8 @@ module ReductoAI
     #
     # @note Split operations consume credits based on document size.
     class Split
+      include AsyncPayload
+
       # @param client [Client] the Reducto API client
       # @api private
       def initialize(client)
@@ -31,7 +33,7 @@ module ReductoAI
       #
       # @return [Hash] Split results with keys:
       #   * "job_id" [String] - Job identifier
-      #   * "status" [String] - Job status ("succeeded")
+      #   * "status" [String] - Job status ("Completed")
       #   * "result" [Hash] - Sections with page ranges
       #   * "usage" [Hash] - Credit usage details
       #
@@ -58,12 +60,13 @@ module ReductoAI
       # Returns immediately with a job_id. Poll with {Jobs#retrieve} to get results.
       #
       # @param input [String, Hash] Document URL or hash with :url key
-      # @param async [Boolean, nil] Async mode flag
+      # @param async [Boolean, Hash, nil] Async options. `true` becomes an empty async payload,
+      #   while a hash is sent as Reducto's nested `async` object.
       # @param options [Hash] Additional splitting options
       #
       # @return [Hash] Job status with keys:
       #   * "job_id" [String] - Job identifier for polling
-      #   * "status" [String] - Initial status ("processing")
+      #   * "status" [String] - Initial status ("Pending")
       #
       # @raise [ArgumentError] if input is nil
       #
@@ -80,20 +83,11 @@ module ReductoAI
 
         normalized_input = normalize_input(input)
         payload = { input: normalized_input }
-        payload[:async] = async unless async.nil?
+        apply_async_payload!(payload, async)
         payload.merge!(options.compact)
 
         @client.post("/split_async", payload)
       end
-
-      private
-
-      # @private
-      def normalize_input(input)
-        return input unless input.is_a?(Hash)
-
-        input[:url] || input["url"] || input
-      end
     end
   end
 end

data/lib/reducto_ai/version.rb

@@ -2,5 +2,5 @@
 
 module ReductoAI
   # Gem version
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end

data/lib/reducto_ai/webhooks/event.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ReductoAI
+  module Webhooks
+    class Event
+      attr_reader :payload, :headers
+
+      def self.parse(payload, headers: {})
+        parsed_payload = payload.is_a?(String) ? JSON.parse(payload) : payload
+        new(parsed_payload, headers: headers)
+      end
+
+      def initialize(payload, headers: {})
+        @payload = stringify_keys(payload || {})
+        @headers = stringify_keys(headers || {})
+      end
+
+      def svix_id
+        headers["svix-id"] || headers["webhook-id"]
+      end
+
+      def job_id
+        payload["job_id"]
+      end
+
+      def status
+        payload["status"]
+      end
+
+      def metadata
+        payload["metadata"] || {}
+      end
+
+      def normalized_status
+        ReductoAI::JobStatus.normalize_status(status)
+      end
+
+      def completed?
+        ReductoAI::JobStatus.completed?(status)
+      end
+
+      def failed?
+        ReductoAI::JobStatus.failed?(status)
+      end
+
+      def to_h
+        payload
+      end
+
+      private
+
+      def stringify_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, child_value), normalized|
+            normalized[key.to_s] = stringify_keys(child_value)
+          end
+        when Array
+          value.map { |child_value| stringify_keys(child_value) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/reducto_ai/webhooks/verifier.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "svix"
+
+module ReductoAI
+  module Webhooks
+    class Verifier
+      class << self
+        def verify!(payload:, headers:, secret: nil)
+          normalized_headers = normalize_headers(headers)
+          resolved_secret = resolve_secret(secret, normalized_headers)
+
+          raise WebhookVerificationError, "webhook secret is required" if resolved_secret.to_s.strip.empty?
+
+          build_webhook(resolved_secret).verify(payload.to_s, normalized_headers)
+        rescue Svix::WebhookVerificationError => e
+          raise WebhookVerificationError, e.message
+        end
+
+        private
+
+        def build_webhook(secret)
+          Svix::Webhook.new(secret)
+        rescue ArgumentError => e
+          raise WebhookVerificationError, "invalid webhook secret format: #{e.message}"
+        end
+
+        def resolve_secret(secret, headers)
+          return secret unless secret.nil? || secret.to_s.strip.empty?
+
+          configuration = ReductoAI.config
+          return configuration.webhook_secret_resolver.call(headers) if configuration.webhook_secret_resolver
+
+          configuration.webhook_secret
+        end
+
+        def normalize_headers(headers)
+          return {} if headers.nil?
+
+          headers.each_with_object({}) do |(key, value), normalized|
+            normalized[key.to_s.downcase] = value.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/reducto_ai.rb

@@ -3,6 +3,9 @@
 require_relative "reducto_ai/version"
 require_relative "reducto_ai/config"
 require_relative "reducto_ai/errors"
+require_relative "reducto_ai/job_status"
+require_relative "reducto_ai/webhooks/verifier"
+require_relative "reducto_ai/webhooks/event"
 require_relative "reducto_ai/client"
 require_relative "reducto_ai/engine"
 
@@ -24,6 +27,10 @@ require_relative "reducto_ai/engine"
 # @see Client
 # @see Config
 module ReductoAI
+  module Rails
+    autoload :RequestVerifier, "reducto_ai/rails/request_verifier"
+  end
+
   class << self
     # Returns the global configuration instance.
     #

data/sig/reducto_ai.rbs

@@ -1,4 +1,96 @@
 module ReductoAI
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  def self.config: () -> Config
+  def self.configure: () { (Config) -> void } -> void
+  def self.reset_configuration!: () -> void
+
+  class Config
+    attr_accessor api_key: String?
+    attr_accessor base_url: String
+    attr_accessor open_timeout: Integer
+    attr_accessor read_timeout: Integer
+    attr_accessor webhook_secret: String?
+    attr_accessor webhook_secret_resolver: Proc?
+    attr_writer logger: untyped
+
+    def logger: () -> untyped
+  end
+
+  class Error < StandardError
+    attr_reader status: Integer?
+    attr_reader body: untyped
+  end
+
+  class AuthenticationError < Error
+  end
+
+  class ClientError < Error
+  end
+
+  class RateLimitError < ClientError
+  end
+
+  class ServerError < Error
+  end
+
+  class NetworkError < Error
+  end
+
+  class JobTimeoutError < Error
+  end
+
+  class JobFailedError < Error
+  end
+
+  class WebhookVerificationError < Error
+  end
+
+  module Resources
+    class Jobs
+      def version: () -> Hash[untyped, untyped]
+      def list: (?status: String?, ?limit: Integer?, ?offset: Integer?) -> Hash[untyped, untyped]
+      def cancel: (job_id: String) -> Hash[untyped, untyped]
+      def retrieve: (job_id: String) -> Hash[untyped, untyped]
+      def upload: (file: untyped, ?extension: String?) -> Hash[untyped, untyped]
+      def normalize_status: (String | Hash[untyped, untyped] | untyped) -> String?
+      def pending?: (String | Hash[untyped, untyped] | untyped) -> bool
+      def in_progress?: (String | Hash[untyped, untyped] | untyped) -> bool
+      def completing?: (String | Hash[untyped, untyped] | untyped) -> bool
+      def completed?: (String | Hash[untyped, untyped] | untyped) -> bool
+      def failed?: (String | Hash[untyped, untyped] | untyped) -> bool
+      def terminal?: (String | Hash[untyped, untyped] | untyped) -> bool
+      def wait: (job_id: String, ?interval: Numeric, timeout: Numeric, ?max_attempts: Integer?, ?raise_on_failure: bool) -> Hash[untyped, untyped]
+               | (job_id: String, ?interval: Numeric, ?timeout: Numeric?, max_attempts: Integer, ?raise_on_failure: bool) -> Hash[untyped, untyped]
+      def configure_webhook: () -> String
+    end
+  end
+
+  module Webhooks
+    class Verifier
+      def self.verify!: (payload: String, headers: Hash[untyped, untyped], ?secret: String?) -> Hash[Symbol, untyped]
+    end
+
+    class Event
+      attr_reader payload: Hash[String, untyped]
+      attr_reader headers: Hash[String, untyped]
+
+      def self.parse: (String | Hash[untyped, untyped], ?headers: Hash[untyped, untyped]) -> Event
+      def initialize: (Hash[untyped, untyped], ?headers: Hash[untyped, untyped]) -> void
+      def svix_id: () -> String?
+      def job_id: () -> String?
+      def status: () -> String?
+      def metadata: () -> Hash[String, untyped]
+      def normalized_status: () -> String?
+      def completed?: () -> bool
+      def failed?: () -> bool
+      def to_h: () -> Hash[String, untyped]
+    end
+  end
+
+  module Rails
+    class RequestVerifier
+      def self.verify!: (untyped request, ?secret: String?) -> Webhooks::Event
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reducto_ai
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - dpaluy
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -37,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: svix
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: ReductoAI provides a lightweight Faraday-based wrapper for Reducto's
   Parse, Split, Extract, Edit, and Pipeline endpoints including async helpers and
   Rails-friendly configuration.
@@ -59,6 +87,9 @@ files:
 - lib/reducto_ai/config.rb
 - lib/reducto_ai/engine.rb
 - lib/reducto_ai/errors.rb
+- lib/reducto_ai/job_status.rb
+- lib/reducto_ai/rails/request_verifier.rb
+- lib/reducto_ai/resources/async_payload.rb
 - lib/reducto_ai/resources/edit.rb
 - lib/reducto_ai/resources/extract.rb
 - lib/reducto_ai/resources/jobs.rb
@@ -66,6 +97,8 @@ files:
 - lib/reducto_ai/resources/pipeline.rb
 - lib/reducto_ai/resources/split.rb
 - lib/reducto_ai/version.rb
+- lib/reducto_ai/webhooks/event.rb
+- lib/reducto_ai/webhooks/verifier.rb
 - sig/reducto_ai.rbs
 homepage: https://github.com/dpaluy/reducto_ai
 licenses: