scanii-ruby 1.0.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e3c62870b928231999c133d889594f002682b74b34769c5741dbfe9a9c12693
-  data.tar.gz: a1673812fa7c2e46fa12657a3898fb01fdf56399c04146e95dfdf048d12ef185
+  metadata.gz: 2b4cc56c7cdba5d949e11dd004f7dbaa29ada9dab5e7b64173f5a523dc4f4e51
+  data.tar.gz: 37b10fb0ee6aa5dfbabf6b9c097fbf837f297fd557e27f0dc97e49278ed355d6
 SHA512:
-  metadata.gz: 1afa93f5a49873f5813dbf9701d5886b173a3e3d5dbdda9d214690308eb77d92b8ff96bde66b6fa78b2f455af32d317bf8e1ce1338824fa0a5801f2dbe4786cd
-  data.tar.gz: 6ed39afbb9846cec5916f8a77c8119a717f6e5c6e6da81dd17756a456fa069735063a20762a772090400d09b1e4fd85c883a92176beecf36479fe10d38ae7bd4
+  metadata.gz: 97c6569f83a40beb529c5d4a2189a57443201d17eafc9be2c75e693316ddf6d98e3306a9819d20346c6f573b0d3fbb182eea3493ad8269f4d8bdeef640b79096
+  data.tar.gz: 70cc50536847e7f83fce477098f6feb780ce6bf9ed3571d1ed92b0f8cd6b929eb5dd2fd2bd4cbdc5afc9d4b989f3df07ffdb86ae901e698e66de2884c95811c6

data/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 All notable changes to `scanii-ruby` are documented here. Versions follow [SemVer](https://semver.org).
 
+## [1.2.0] — v2.2 surface
+
+### New API
+
+- `Scanii::Client#retrieve_trace(id)` → `Scanii::TraceResult` or `nil` — retrieves the
+  ordered processing event trace for a scan via `GET /files/{id}/trace`. Returns `nil` on 404
+  (no trace for that id). v2.2 preview surface; API shape may shift before marked stable.
+- `Scanii::Client#process_from_url(location, callback: nil, metadata: nil)` →
+  `Scanii::ProcessingResult` — submits a URL for synchronous scanning via `POST /files` with
+  `location` as a multipart/form-data field. Distinct from `fetch`, which submits to
+  `/files/fetch` for asynchronous server-side fetching. `location` must be a String URL.
+  v2.2 preview surface.
+- `Scanii::TraceResult` — new result class with `id`, `events`, `request_id`, `host_id`,
+  `raw_response`.
+- `Scanii::TraceEvent` — new model with `timestamp` (String) and `message` (String).
+
+### Deprecations
+
+- `Scanii::ProcessingResult#error` — deprecated. The server never populates this field on
+  successful responses; errors arrive as non-2xx HTTP responses that raise `Scanii::Error`
+  subclasses. The field still exists and emits a runtime `warn` on access. Will be removed
+  in a future major version.
+
+## 1.1.0 — Streaming standardization
+
+Adds stream-based `process` and `process_async` methods, aligning scanii-ruby with the
+cross-SDK streaming standard. File content is now truly streamed to the socket via
+`Net::HTTP#body_stream=` rather than buffered into a single String.
+
+### New API
+
+- `Scanii::Client#process(io, filename:, content_type: nil, metadata: nil, callback: nil)` →
+  `Scanii::ProcessingResult` — accepts any IO-like object (anything responding to `read(n)`).
+  Both `File` (opened with `File.open(path, "rb")`) and `StringIO` work.
+- `Scanii::Client#process_file(path, metadata: nil, callback: nil)` →
+  `Scanii::ProcessingResult` — convenience wrapper that opens the file in binary mode and
+  delegates to `process`. This is the replacement for the old `process(path, ...)` form.
+- Same shapes for `process_async` / `process_async_file`.
+
+### Deprecations
+
+- `process(path_string, ...)` — passing a String path to `process` is deprecated; use
+  `process_file(path)` instead. The old form still works and emits a runtime `warn`. Will be
+  removed in a future major version.
+- `process_async(path_string, ...)` — same; use `process_async_file(path)`. Will be removed
+  in a future major version.
+
+### Internals
+
+- `Scanii::Multipart.stream_encode` replaces the old `encode`. Returns a `[ChainedIO,
+  content_type, content_length]` triple. `ChainedIO` reads prologue → caller IO → epilogue
+  without ever buffering the full body.
+
 ## 1.0.1 — Release infrastructure fix
 
 Wires up `bundler/gem_tasks` in the Rakefile so `bundle exec rake release` (invoked by `rubygems/release-gem@v1`) resolves correctly. v1.0.0 was tagged but never published to RubyGems because the release workflow failed at the `rake release` task lookup; v1.0.1 is functionally identical to that tag. No SDK behavior changes.

data/README.md

@@ -30,12 +30,23 @@ Targets Ruby 3.4+. Zero runtime dependencies.
 
 ## Quickstart
 
+Scan a file from disk:
+
 ```ruby
 require "scanii"
 
 client = Scanii::Client.new(key: "your-key", secret: "your-secret")
 
-result = client.process("./file.pdf")
+result = client.process_file("./file.pdf")
+puts "findings: #{result.findings.inspect}"
+```
+
+Scan content already in memory (no temp file needed):
+
+```ruby
+require "stringio"
+
+result = client.process(StringIO.new(bytes), filename: "upload.bin")
 puts "findings: #{result.findings.inspect}"
 ```
 
@@ -45,10 +56,14 @@ puts "findings: #{result.findings.inspect}"
 
 | Method | REST | Returns |
 |---|---|---|
-| `process(file_path, metadata:, callback:)` | `POST /files` | `Scanii::ProcessingResult` |
-| `process_async(file_path, metadata:, callback:)` | `POST /files/async` | `Scanii::PendingResult` |
+| `process(io, filename:, content_type:, metadata:, callback:)` | `POST /files` | `Scanii::ProcessingResult` |
+| `process_file(path, metadata:, callback:)` | `POST /files` | `Scanii::ProcessingResult` |
+| `process_async(io, filename:, content_type:, metadata:, callback:)` | `POST /files/async` | `Scanii::PendingResult` |
+| `process_async_file(path, metadata:, callback:)` | `POST /files/async` | `Scanii::PendingResult` |
+| `process_from_url(location, callback:, metadata:)` | `POST /files` | `Scanii::ProcessingResult` (v2.2 preview) |
 | `fetch(url, metadata:, callback:)` | `POST /files/fetch` | `Scanii::PendingResult` |
 | `retrieve(id)` | `GET /files/{id}` | `Scanii::ProcessingResult` |
+| `retrieve_trace(id)` | `GET /files/{id}/trace` | `Scanii::TraceResult` or `nil` (v2.2 preview) |
 | `ping` | `GET /ping` | `true` |
 | `create_auth_token(timeout_seconds)` | `POST /auth/tokens` | `Scanii::AuthToken` |
 | `retrieve_auth_token(id)` | `GET /auth/tokens/{id}` | `Scanii::AuthToken` |

data/lib/scanii/client.rb

@@ -13,10 +13,13 @@ module Scanii
   #
   # @see https://scanii.github.io/openapi/v22/
   #
-  # @example
+  # @example Scan a file from disk
   #   client = Scanii::Client.new(key: "your-key", secret: "your-secret")
-  #   result = client.process("./file.pdf")
+  #   result = client.process_file("./file.pdf")
   #   puts result.findings  # [] when clean
+  #
+  # @example Scan content already in memory
+  #   result = client.process(StringIO.new(bytes), filename: "upload.bin")
   class Client
     DEFAULT_ENDPOINT = "https://api.scanii.com".freeze
     DEFAULT_TIMEOUT  = 60
@@ -44,34 +47,111 @@ module Scanii
       @user_agent = user_agent && !user_agent.empty? ? "#{user_agent} #{USER_AGENT}" : USER_AGENT
     end
 
-    # Submit a file for synchronous scanning.
+    # Submit an IO-like object for synchronous scanning.
+    #
+    # +io+ is duck-typed: anything responding to +read(n)+ returning a String.
+    # Both +File+ (opened with +File.open(path, "rb")+) and +StringIO+ work.
+    # The body is streamed to the socket; file content is never fully buffered.
+    #
+    # Passing a String path is deprecated — use {#process_file} instead.
+    #
+    # @overload process(io, filename:, content_type: nil, metadata: nil, callback: nil)
+    #   @param io [#read] IO-like object
+    #   @param filename [String] filename sent in the multipart part
+    #   @param content_type [String, nil] content-type of the file part; guessed from filename when nil
+    #   @param metadata [Hash{String=>String}, nil] arbitrary key/value pairs attached to the result
+    #   @param callback [String, nil] URL to POST the result to on completion
     #
     # @see https://scanii.github.io/openapi/v22/  POST /files
     # @return [Scanii::ProcessingResult]
-    def process(file_path, metadata: nil, callback: nil)
-      assert_readable(file_path)
+    def process(first_arg, filename: nil, content_type: nil, metadata: nil, callback: nil)
+      if first_arg.is_a?(String)
+        # @deprecated Use {#process_file} instead. Will be removed in a future major version.
+        warn "[DEPRECATION] `Scanii::Client#process(path)` is deprecated; " \
+             "use `process_file(path)` instead. Will be removed in a future major version."
+        return process_file(first_arg, metadata: metadata, callback: callback)
+      end
+
+      raise ArgumentError, "io must respond to read" unless first_arg.respond_to?(:read)
+      raise ArgumentError, "filename: is required" if filename.nil? || filename.to_s.empty?
+
       fields = build_text_fields(metadata, callback)
-      body, content_type = Multipart.encode(fields, file_path)
-      status, resp_body, headers = post("/files", body: body, content_type: content_type)
+      stream, ct, length = Multipart.stream_encode(fields, first_arg, filename.to_s, content_type)
+      status, resp_body, headers = post("/files", body_stream: stream, content_type: ct,
+                                                  content_length: length)
       raise_for_status(status, resp_body, headers) unless status == 201
       ProcessingResult.from_response(resp_body, headers)
     end
 
-    # Submit a file for server-side asynchronous scanning. Returns a pending
-    # id; the final result is delivered to +callback+ (when supplied) or
-    # fetched via #retrieve.
+    # Submit a file path for synchronous scanning.
+    #
+    # Opens the file in binary mode, streams it to Scanii, and closes it.
+    # Delegates to {#process} with +filename+ set to the basename.
+    #
+    # @param file_path [String] path to the file to upload
+    # @param metadata [Hash{String=>String}, nil]
+    # @param callback [String, nil]
+    # @see https://scanii.github.io/openapi/v22/  POST /files
+    # @return [Scanii::ProcessingResult]
+    def process_file(file_path, metadata: nil, callback: nil)
+      assert_readable(file_path)
+      File.open(file_path.to_s, "rb") do |f|
+        process(f, filename: File.basename(file_path.to_s), metadata: metadata, callback: callback)
+      end
+    end
+
+    # Submit an IO-like object for server-side asynchronous scanning.
+    #
+    # Returns a pending id; the final result is delivered to +callback+ (when
+    # supplied) or fetched via {#retrieve}.
+    #
+    # Passing a String path is deprecated — use {#process_async_file} instead.
+    #
+    # @overload process_async(io, filename:, content_type: nil, metadata: nil, callback: nil)
+    #   @param io [#read] IO-like object
+    #   @param filename [String] filename sent in the multipart part
+    #   @param content_type [String, nil]
+    #   @param metadata [Hash{String=>String}, nil]
+    #   @param callback [String, nil]
     #
     # @see https://scanii.github.io/openapi/v22/  POST /files/async
     # @return [Scanii::PendingResult]
-    def process_async(file_path, metadata: nil, callback: nil)
-      assert_readable(file_path)
+    def process_async(first_arg, filename: nil, content_type: nil, metadata: nil, callback: nil)
+      if first_arg.is_a?(String)
+        # @deprecated Use {#process_async_file} instead. Will be removed in a future major version.
+        warn "[DEPRECATION] `Scanii::Client#process_async(path)` is deprecated; " \
+             "use `process_async_file(path)` instead. Will be removed in a future major version."
+        return process_async_file(first_arg, metadata: metadata, callback: callback)
+      end
+
+      raise ArgumentError, "io must respond to read" unless first_arg.respond_to?(:read)
+      raise ArgumentError, "filename: is required" if filename.nil? || filename.to_s.empty?
+
       fields = build_text_fields(metadata, callback)
-      body, content_type = Multipart.encode(fields, file_path)
-      status, resp_body, headers = post("/files/async", body: body, content_type: content_type)
+      stream, ct, length = Multipart.stream_encode(fields, first_arg, filename.to_s, content_type)
+      status, resp_body, headers = post("/files/async", body_stream: stream, content_type: ct,
+                                                        content_length: length)
       raise_for_status(status, resp_body, headers) unless status == 202
       PendingResult.from_response(resp_body, headers)
     end
 
+    # Submit a file path for server-side asynchronous scanning.
+    #
+    # Opens the file in binary mode and delegates to {#process_async}.
+    #
+    # @param file_path [String] path to the file to upload
+    # @param metadata [Hash{String=>String}, nil]
+    # @param callback [String, nil]
+    # @see https://scanii.github.io/openapi/v22/  POST /files/async
+    # @return [Scanii::PendingResult]
+    def process_async_file(file_path, metadata: nil, callback: nil)
+      assert_readable(file_path)
+      File.open(file_path.to_s, "rb") do |f|
+        process_async(f, filename: File.basename(file_path.to_s), metadata: metadata,
+                         callback: callback)
+      end
+    end
+
     # Ask Scanii to download a remote URL and scan it asynchronously.
     #
     # @see https://scanii.github.io/openapi/v22/  POST /files/fetch
@@ -104,6 +184,70 @@ module Scanii
       ProcessingResult.from_response(resp_body, headers)
     end
 
+    # Retrieve the processing event trace for a previously submitted scan.
+    #
+    # Returns nil when no trace exists for the given id (HTTP 404).
+    #
+    # This is a v2.2 preview surface; the API shape may shift before it is
+    # marked stable.
+    #
+    # @param id [String] processing id returned by process or process_file
+    # @see https://scanii.github.io/openapi/v22/  GET /files/{id}/trace
+    # @return [Scanii::TraceResult, nil]
+    def retrieve_trace(id)
+      raise ArgumentError, "id must not be empty" if id.nil? || id.empty?
+
+      status, resp_body, headers = request("GET", "/files/#{url_encode(id)}/trace")
+      return nil if status == 404
+
+      raise_for_status(status, resp_body, headers) unless status == 200
+      TraceResult.from_response(resp_body, headers)
+    end
+
+    # Submit a remote URL for synchronous scanning.
+    #
+    # Sends the URL as a +location+ field in a multipart/form-data POST to
+    # +/files+. The Scanii server fetches and scans the URL synchronously and
+    # returns a ProcessingResult. This is distinct from {#fetch}, which submits
+    # to +/files/fetch+ for asynchronous server-side fetching.
+    #
+    # +location+ must be a String URL. This matches the existing {#fetch}
+    # String-URL convention and the Java reference (processFromUrl(String)).
+    #
+    # This is a v2.2 preview surface; the API shape may shift before it is
+    # marked stable.
+    #
+    # @param location [String] URL of the content to scan
+    # @param callback [String, nil] URL to POST the result to on completion
+    # @param metadata [Hash{String=>String}, nil] arbitrary key/value pairs attached to the result
+    # @see https://scanii.github.io/openapi/v22/  POST /files
+    # @return [Scanii::ProcessingResult]
+    def process_from_url(location, callback: nil, metadata: nil)
+      raise ArgumentError, "location must not be empty" if location.nil? || location.to_s.empty?
+
+      fields = build_text_fields(metadata, callback)
+      fields["location"] = location.to_s
+
+      boundary = Multipart.make_boundary
+      body = String.new(encoding: Encoding::BINARY)
+      fields.each do |name, value|
+        body << "--#{boundary}\r\n".b
+        body << "Content-Disposition: form-data; name=\"#{name}\"\r\n".b
+        body << "Content-Type: text/plain; charset=UTF-8\r\n\r\n".b
+        body << value.to_s.b
+        body << "\r\n".b
+      end
+      body << "--#{boundary}--\r\n".b
+
+      status, resp_body, headers = post(
+        "/files",
+        body: body,
+        content_type: Multipart.make_content_type(boundary)
+      )
+      raise_for_status(status, resp_body, headers) unless status == 201
+      ProcessingResult.from_response(resp_body, headers)
+    end
+
     # Verify that the configured credentials reach the API.
     #
     # @see https://scanii.github.io/openapi/v22/  GET /ping
@@ -190,14 +334,16 @@ module Scanii
       fields
     end
 
-    def post(path, body:, content_type:)
-      request("POST", path, body: body, content_type: content_type)
+    def post(path, body: nil, content_type: nil, body_stream: nil, content_length: nil)
+      request("POST", path, body: body, content_type: content_type,
+                            body_stream: body_stream, content_length: content_length)
     end
 
-    def request(method, path, body: nil, content_type: nil)
+    def request(method, path, body: nil, content_type: nil, body_stream: nil, content_length: nil)
       uri = URI.parse("#{@base_uri}#{path}")
 
-      req = build_request(method, uri, body, content_type)
+      req = build_request(method, uri, body: body, content_type: content_type,
+                                       body_stream: body_stream, content_length: content_length)
 
       Net::HTTP.start(uri.hostname, uri.port,
                       use_ssl: uri.scheme == "https",
@@ -211,7 +357,7 @@ module Scanii
       raise Scanii::Error, "transport error: #{e.class}: #{e.message}"
     end
 
-    def build_request(method, uri, body, content_type)
+    def build_request(method, uri, body: nil, content_type: nil, body_stream: nil, content_length: nil)
       klass = case method
               when "GET"    then Net::HTTP::Get
               when "POST"   then Net::HTTP::Post
@@ -224,7 +370,14 @@ module Scanii
       req["User-Agent"]    = @user_agent
       req["Accept"]        = "application/json"
       req["Content-Type"]  = content_type if content_type
-      req.body = body if body
+
+      if body_stream
+        req.body_stream = body_stream
+        req["Content-Length"] = content_length.to_s
+      elsif body
+        req.body = body
+      end
+
       req
     end
 

data/lib/scanii/multipart.rb

@@ -1,14 +1,11 @@
 require "securerandom"
+require "stringio"
 
 module Scanii
   # Hand-rolled multipart/form-data encoder (RFC 7578).
   #
   # Ruby's stdlib Net::HTTP does not bundle a multipart encoder; this is the
   # smallest viable implementation that covers the Scanii POST /files payload.
-  #
-  # Body is assembled as a single binary-encoded String -- file contents are
-  # read into memory rather than streamed. This matches the PHP SDK's approach;
-  # callers scanning very large files should be aware.
   module Multipart
     module_function
 
@@ -22,42 +19,45 @@ module Scanii
       "multipart/form-data; boundary=#{boundary}"
     end
 
-    # Encode a multipart body containing the bytes at file_path plus the given
-    # text fields.
+    # Encode a multipart body as a streaming ChainedIO.
+    #
+    # Builds the RFC 7578 prologue and epilogue as binary Strings, chains them
+    # around the caller's IO, and returns the triple required for
+    # Net::HTTP body_stream= uploads. The caller's IO is never read here --
+    # only when Net::HTTP reads from the returned ChainedIO.
     #
-    # @param fields [Hash{String=>String}] text form fields (e.g. metadata[k] => v, callback => url)
-    # @param file_path [String] path to the file to upload
+    # @param fields [Hash{String=>String}] text form fields (e.g. metadata[k]=v, callback)
+    # @param io [#read, #size] IO-like object (anything responding to read(n))
+    # @param filename [String] filename for the file part
+    # @param content_type [String, nil] content-type of the file part; falls back to extension lookup
     # @param file_field [String] name of the file form field; default "file"
-    # @return [Array(String, String)] tuple of [body, content_type]
-    def encode(fields, file_path, file_field: "file")
+    # @return [Array(ChainedIO, String, Integer)] [body_stream, content_type_header, content_length]
+    def stream_encode(fields, io, filename, content_type = nil, file_field: "file")
       boundary = make_boundary
+      ct = content_type || guess_content_type(filename)
 
-      filename = File.basename(file_path)
-      content_type = guess_content_type(file_path)
-      file_bytes = File.binread(file_path)
-
-      body = String.new(encoding: Encoding::BINARY)
-
+      prologue = String.new(encoding: Encoding::BINARY)
       fields.each do |name, value|
-        write_text_part(body, boundary, name.to_s, value.to_s)
+        write_text_part(prologue, boundary, name.to_s, value.to_s)
       end
+      prologue << "--#{boundary}\r\n".b
+      prologue << "Content-Disposition: form-data; name=\"#{file_field}\"; filename=\"#{filename}\"\r\n".b
+      prologue << "Content-Type: #{ct}\r\n\r\n".b
 
-      body << "--#{boundary}\r\n".b
-      body << "Content-Disposition: form-data; name=\"#{file_field}\"; filename=\"#{filename}\"\r\n".b
-      body << "Content-Type: #{content_type}\r\n\r\n".b
-      body << file_bytes.b
-      body << "\r\n".b
-      body << "--#{boundary}--\r\n".b
+      epilogue = "\r\n--#{boundary}--\r\n".b
 
-      [body, make_content_type(boundary)]
+      io_size = io_remaining_bytes(io)
+      total_length = prologue.bytesize + io_size + epilogue.bytesize
+
+      [ChainedIO.new(prologue, io, epilogue), make_content_type(boundary), total_length]
     end
 
-    # Best-effort content-type lookup by extension. Falls back to
+    # Best-effort content-type lookup by filename extension. Falls back to
     # application/octet-stream. The Scanii API does not require an accurate
     # content-type on the multipart part -- the server inspects the bytes -- so
     # a short table is sufficient.
-    def guess_content_type(path)
-      ext = File.extname(path).delete_prefix(".").downcase
+    def guess_content_type(filename)
+      ext = File.extname(filename.to_s).delete_prefix(".").downcase
       MIME_TYPES.fetch(ext, "application/octet-stream")
     end
 
@@ -96,5 +96,60 @@ module Scanii
       body << "\r\n".b
     end
     private_class_method :write_text_part
+
+    # Return the number of bytes remaining to be read from io.
+    # Requires io to respond to size (File and StringIO both do).
+    def io_remaining_bytes(io)
+      if io.respond_to?(:pos) && io.respond_to?(:size)
+        io.size - io.pos
+      elsif io.respond_to?(:size)
+        io.size
+      else
+        raise ArgumentError, "io must respond to size (File and StringIO do; got #{io.class})"
+      end
+    end
+    private_class_method :io_remaining_bytes
+
+    # Reads prologue_str, then io, then epilogue_str in sequence.
+    # Used as Net::HTTP body_stream for streaming multipart uploads.
+    class ChainedIO
+      def initialize(prologue, io, epilogue)
+        @parts = [StringIO.new(prologue), io, StringIO.new(epilogue)]
+        @idx   = 0
+      end
+
+      def read(length = nil, buf = nil)
+        result = length.nil? ? read_all : read_n(length)
+        return nil if result.nil?
+
+        buf ? buf.replace(result) : result
+      end
+
+      private
+
+      def read_all
+        result = String.new(encoding: Encoding::BINARY)
+        @parts[@idx..].each do |part|
+          chunk = part.read
+          result << chunk.b if chunk
+        end
+        @idx = @parts.size
+        result
+      end
+
+      def read_n(length)
+        result = String.new(encoding: Encoding::BINARY)
+        while result.bytesize < length && @idx < @parts.size
+          chunk = @parts[@idx].read(length - result.bytesize)
+          if chunk.nil? || chunk.empty?
+            @idx += 1
+          else
+            result << chunk.b
+          end
+        end
+        result.empty? ? nil : result
+      end
+    end
+    private_constant :ChainedIO
   end
 end

data/lib/scanii/processing_result.rb

@@ -9,7 +9,7 @@ module Scanii
   # @see https://scanii.github.io/openapi/v22/
   class ProcessingResult
     attr_reader :id, :findings, :checksum, :content_length, :content_type,
-                :metadata, :creation_date, :error,
+                :metadata, :creation_date,
                 :request_id, :host_id, :resource_location, :raw_response
 
     def initialize(id:, findings:, checksum:, content_length:, content_type:,
@@ -22,13 +22,23 @@ module Scanii
       @content_type      = content_type
       @metadata          = metadata
       @creation_date     = creation_date
-      @error             = error
+      @_error            = error
       @request_id        = request_id
       @host_id           = host_id
       @resource_location = resource_location
       @raw_response      = raw_response
     end
 
+    # @deprecated The server never populates this field on successful responses;
+    #   errors arrive as non-2xx HTTP responses that raise Scanii::Error
+    #   subclasses. Will be removed in a future major version.
+    def error
+      warn "[DEPRECATION] `Scanii::ProcessingResult#error` is deprecated; " \
+           "rescue Scanii::Error (and its subclasses) to handle server-side errors. " \
+           "Will be removed in a future major version."
+      @_error
+    end
+
     def self.from_response(body, headers)
       json = body.nil? || body.empty? ? {} : JSON.parse(body)
 

data/lib/scanii/trace_event.rb

@@ -0,0 +1,20 @@
+module Scanii
+  # A single processing event in a {Scanii::TraceResult}.
+  #
+  # @see https://scanii.github.io/openapi/v22/
+  class TraceEvent
+    attr_reader :timestamp, :message
+
+    def initialize(timestamp:, message:)
+      @timestamp = timestamp
+      @message   = message
+    end
+
+    def self.from_hash(hash)
+      new(
+        timestamp: hash["timestamp"]&.to_s,
+        message: hash["message"]&.to_s
+      )
+    end
+  end
+end

data/lib/scanii/trace_result.rb

@@ -0,0 +1,33 @@
+require "json"
+
+module Scanii
+  # Result of Client#retrieve_trace — ordered processing events for a scan.
+  #
+  # This is a v2.2 preview surface; the API shape may shift before it is
+  # marked stable.
+  #
+  # @see https://scanii.github.io/openapi/v22/
+  class TraceResult
+    attr_reader :id, :events, :request_id, :host_id, :raw_response
+
+    def initialize(id:, events:, request_id:, host_id:, raw_response:)
+      @id           = id
+      @events       = events
+      @request_id   = request_id
+      @host_id      = host_id
+      @raw_response = raw_response
+    end
+
+    def self.from_response(body, headers)
+      json = body.nil? || body.empty? ? {} : JSON.parse(body)
+
+      new(
+        id: (json["id"] || "").to_s,
+        events: Array(json["events"]).map { |e| TraceEvent.from_hash(e) },
+        request_id: headers["x-scanii-request-id"],
+        host_id: headers["x-scanii-host-id"],
+        raw_response: body
+      )
+    end
+  end
+end

data/lib/scanii/version.rb

@@ -1,3 +1,3 @@
 module Scanii
-  VERSION = "1.0.1".freeze
+  VERSION = "1.2.0".freeze
 end

data/lib/scanii.rb

@@ -3,6 +3,8 @@ require_relative "scanii/error"
 require_relative "scanii/processing_result"
 require_relative "scanii/pending_result"
 require_relative "scanii/auth_token"
+require_relative "scanii/trace_event"
+require_relative "scanii/trace_result"
 require_relative "scanii/multipart"
 require_relative "scanii/client"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scanii-ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Scanii
@@ -80,6 +80,8 @@ files:
 - lib/scanii/multipart.rb
 - lib/scanii/pending_result.rb
 - lib/scanii/processing_result.rb
+- lib/scanii/trace_event.rb
+- lib/scanii/trace_result.rb
 - lib/scanii/version.rb
 homepage: https://github.com/scanii/scanii-ruby
 licenses: