scanii-ruby 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0418285adf3f56f3389b379b9eedadd5b281591cd2c7e62ad05092a8e8b22595'
-  data.tar.gz: a61ce21d24bc78f557e09394868fc0c50b9fb2777b8649dce59b017a7d6a427c
+  metadata.gz: 2b4cc56c7cdba5d949e11dd004f7dbaa29ada9dab5e7b64173f5a523dc4f4e51
+  data.tar.gz: 37b10fb0ee6aa5dfbabf6b9c097fbf837f297fd557e27f0dc97e49278ed355d6
 SHA512:
-  metadata.gz: 504165ee4f450fa8266675e1eb9d43d54a44e76547a5a8fe870865b4123c1563a4d9bf693df893855ecef9197288beb0e5da3425bf3a4524aa76cc1d02bbec25
-  data.tar.gz: 897b47ed149ea571105dde92462e61d69f43fd496f20a50200dc64d0bce2e2ab7b52ade2837de7d5d6ac5a0f25f5de93f98f0d0ad5781f474b076d8c76c874e0
+  metadata.gz: 97c6569f83a40beb529c5d4a2189a57443201d17eafc9be2c75e693316ddf6d98e3306a9819d20346c6f573b0d3fbb182eea3493ad8269f4d8bdeef640b79096
+  data.tar.gz: 70cc50536847e7f83fce477098f6feb780ce6bf9ed3571d1ed92b0f8cd6b929eb5dd2fd2bd4cbdc5afc9d4b989f3df07ffdb86ae901e698e66de2884c95811c6

data/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 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

data/README.md

@@ -60,8 +60,10 @@ puts "findings: #{result.findings.inspect}"
 | `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

@@ -184,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

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.1.0".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.1.0
+  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: