scanii-ruby 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0418285adf3f56f3389b379b9eedadd5b281591cd2c7e62ad05092a8e8b22595'
-  data.tar.gz: a61ce21d24bc78f557e09394868fc0c50b9fb2777b8649dce59b017a7d6a427c
+  metadata.gz: 6eafeea25fdb7195d2f1a0f9599fac6f3a815872b403c170573b9d585c87ea76
+  data.tar.gz: 72cb2cd424e382e147c5464f9b8bc6edcd16dcd1887897669ffddabf760e515f
 SHA512:
-  metadata.gz: 504165ee4f450fa8266675e1eb9d43d54a44e76547a5a8fe870865b4123c1563a4d9bf693df893855ecef9197288beb0e5da3425bf3a4524aa76cc1d02bbec25
-  data.tar.gz: 897b47ed149ea571105dde92462e61d69f43fd496f20a50200dc64d0bce2e2ab7b52ade2837de7d5d6ac5a0f25f5de93f98f0d0ad5781f474b076d8c76c874e0
+  metadata.gz: 3cc93b317de609aa3499ff76343b8a3376c5083211b3bf3fe8b2968f1777211040993e750be8fc1602f39bb2f3cde41cbb4d7cbf3ad7072efd45bdece58a23fd
+  data.tar.gz: dc2bfe69e31ccbc2f1ca08dcb1bcc1f8d2c4b38ae800b9c63ed7909689bdaf33454edf4b760125bc7ac6c34b7656a7e7192909b4a795c60c24915e869a73a457

data/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to `scanii-ruby` are documented here. Versions follow [SemVer](https://semver.org).
 
+## [1.3.0] — deprecate AUTO endpoint
+
+### Added
+
+- `Scanii::Target` — typed regional endpoint class with constants `Scanii::Target::US1`,
+  `EU1`, `EU2`, `AP1`, `AP2`, `CA1`. Pass to `Scanii::Client.new(endpoint:)` instead of a
+  bare URL string for ergonomics and IDE autocomplete. The `endpoint:` keyword still accepts
+  bare URL strings (e.g. for scanii-cli), so this is purely additive.
+
+### Deprecated
+
+- Default `endpoint:` parameter (`https://api.scanii.com`) — latency-based routing does not
+  guarantee which region processes your data. Pass an explicit regional endpoint
+  (`Scanii::Target::US1`, `Scanii::Target::EU1`, etc.) for data residency compliance.
+  Constructing a client without an explicit endpoint now emits a `warn` message.
+  Will be removed in a future major version.
+
+## [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

@@ -35,7 +35,7 @@ Scan a file from disk:
 ```ruby
 require "scanii"
 
-client = Scanii::Client.new(key: "your-key", secret: "your-secret")
+client = Scanii::Client.new(key: "your-key", secret: "your-secret", endpoint: Scanii::Target::US1)
 
 result = client.process_file("./file.pdf")
 puts "findings: #{result.findings.inspect}"
@@ -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` |
@@ -75,19 +77,21 @@ Full API reference: <https://scanii.github.io/openapi/v22/>.
 client = Scanii::Client.new(
   key: "k",
   secret: "s",
-  endpoint: "https://api-eu1.scanii.com"
+  endpoint: Scanii::Target::EU1
 )
 ```
 
-| Region | Endpoint |
+The `endpoint:` keyword accepts either a `Scanii::Target` constant or a bare URL String (useful for scanii-cli, e.g. `endpoint: "http://localhost:4000"`).
+
+| Constant | Endpoint |
 |---|---|
-| Auto (default) | `https://api.scanii.com` |
-| US 1 | `https://api-us1.scanii.com` |
-| EU 1 | `https://api-eu1.scanii.com` |
-| EU 2 | `https://api-eu2.scanii.com` |
-| AP 1 | `https://api-ap1.scanii.com` |
-| AP 2 | `https://api-ap2.scanii.com` |
-| CA 1 | `https://api-ca1.scanii.com` |
+| `Scanii::Target::US1` | `https://api-us1.scanii.com` |
+| `Scanii::Target::EU1` | `https://api-eu1.scanii.com` |
+| `Scanii::Target::EU2` | `https://api-eu2.scanii.com` |
+| `Scanii::Target::AP1` | `https://api-ap1.scanii.com` |
+| `Scanii::Target::AP2` | `https://api-ap2.scanii.com` |
+| `Scanii::Target::CA1` | `https://api-ca1.scanii.com` |
+| ~~Auto (default)~~ | ~~`https://api.scanii.com`~~ — **deprecated**, does not guarantee regional data placement |
 
 ## Errors
 
@@ -118,10 +122,10 @@ Per SDK Principle 3, the SDK does not retry on the caller's behalf — backoff a
 Mint a short-lived token server-side and authenticate with it from a less-trusted client:
 
 ```ruby
-server_client = Scanii::Client.new(key: "k", secret: "s")
+server_client = Scanii::Client.new(key: "k", secret: "s", endpoint: Scanii::Target::US1)
 token = server_client.create_auth_token(300)
 
-token_client = Scanii::Client.new(token: token.id)
+token_client = Scanii::Client.new(token: token.id, endpoint: Scanii::Target::US1)
 token_client.ping
 ```
 

data/lib/scanii/client.rb

@@ -31,11 +31,25 @@ module Scanii
     # @param key [String, nil] API key (mutually exclusive with token)
     # @param secret [String, nil] API secret (required when key is set)
     # @param token [String, nil] auth-token id (mutually exclusive with key/secret)
-    # @param endpoint [String] base URL; defaults to https://api.scanii.com
+    # @param endpoint [Scanii::Target, String] base URL or {Scanii::Target} constant;
+    #   defaults to https://api.scanii.com (deprecated)
+    #   @deprecated The default endpoint (https://api.scanii.com) uses latency-based routing
+    #     and does not guarantee which region processes your data. Pass an explicit regional
+    #     endpoint for data residency compliance: {Scanii::Target::US1}, {Scanii::Target::EU1},
+    #     {Scanii::Target::EU2}, {Scanii::Target::AP1}, {Scanii::Target::AP2},
+    #     {Scanii::Target::CA1}. A bare URL String is also accepted (e.g. for scanii-cli).
+    #     Will be removed in a future major version.
     # @param timeout [Integer] open + read timeout in seconds; default 60
     # @param user_agent [String, nil] optional fragment prepended to the SDK's default User-Agent
     def initialize(key: nil, secret: nil, token: nil, endpoint: DEFAULT_ENDPOINT,
                    timeout: DEFAULT_TIMEOUT, user_agent: nil)
+      if endpoint == DEFAULT_ENDPOINT
+        warn "[scanii] DEPRECATION: No explicit endpoint set; defaulting to " \
+             "#{DEFAULT_ENDPOINT} (AUTO routing). This does not guarantee regional data " \
+             "placement. Pass an explicit regional endpoint (e.g. Scanii::Target::US1) " \
+             "for data residency compliance. The AUTO default will be removed in a " \
+             "future major version."
+      end
       @auth_header = build_auth_header(key, secret, token)
       @endpoint    = endpoint.to_s.sub(%r{/+\z}, "")
       raise ArgumentError, "endpoint must not be empty" if @endpoint.empty?
@@ -184,6 +198,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/target.rb

@@ -0,0 +1,50 @@
+module Scanii
+  # Scanii regional API endpoints.
+  #
+  # Pass one of the predefined regional constants (e.g. {US1}) to
+  # {Scanii::Client#initialize} via the +endpoint:+ keyword. The constructor
+  # also accepts an arbitrary URL String for testing against scanii-cli or
+  # other local mocks:
+  #
+  #   Scanii::Client.new(key: "k", secret: "s", endpoint: Scanii::Target::US1)
+  #   Scanii::Client.new(key: "k", secret: "s", endpoint: Scanii::Target.new("http://localhost:4000"))
+  #
+  # +Scanii::Target::AUTO+ (latency-based routing) is intentionally not provided —
+  # customer data residency / chain-of-custody compliance requires an explicit
+  # regional choice.
+  #
+  # @see https://scanii.github.io/openapi/v22/
+  class Target
+    attr_reader :url
+
+    # @param url [String] base URL for the target endpoint
+    def initialize(url)
+      raise ArgumentError, "Target URL must be a non-empty String" if url.nil? || url.to_s.empty?
+
+      @url = url.to_s
+    end
+
+    # Coerce to String (the base URL). Lets +Scanii::Target+ instances be used
+    # interchangeably with String URLs in +endpoint:+.
+    def to_s
+      @url
+    end
+
+    def ==(other)
+      other.is_a?(Target) && other.url == @url
+    end
+
+    alias eql? ==
+
+    def hash
+      @url.hash
+    end
+
+    US1 = new("https://api-us1.scanii.com").freeze
+    EU1 = new("https://api-eu1.scanii.com").freeze
+    EU2 = new("https://api-eu2.scanii.com").freeze
+    AP1 = new("https://api-ap1.scanii.com").freeze
+    AP2 = new("https://api-ap2.scanii.com").freeze
+    CA1 = new("https://api-ca1.scanii.com").freeze
+  end
+end

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.3.0".freeze
 end

data/lib/scanii.rb

@@ -1,8 +1,11 @@
 require_relative "scanii/version"
 require_relative "scanii/error"
+require_relative "scanii/target"
 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.3.0
 platform: ruby
 authors:
 - Scanii
@@ -80,6 +80,9 @@ files:
 - lib/scanii/multipart.rb
 - lib/scanii/pending_result.rb
 - lib/scanii/processing_result.rb
+- lib/scanii/target.rb
+- lib/scanii/trace_event.rb
+- lib/scanii/trace_result.rb
 - lib/scanii/version.rb
 homepage: https://github.com/scanii/scanii-ruby
 licenses: