scanii-ruby 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b4cc56c7cdba5d949e11dd004f7dbaa29ada9dab5e7b64173f5a523dc4f4e51
-  data.tar.gz: 37b10fb0ee6aa5dfbabf6b9c097fbf837f297fd557e27f0dc97e49278ed355d6
+  metadata.gz: 6eafeea25fdb7195d2f1a0f9599fac6f3a815872b403c170573b9d585c87ea76
+  data.tar.gz: 72cb2cd424e382e147c5464f9b8bc6edcd16dcd1887897669ffddabf760e515f
 SHA512:
-  metadata.gz: 97c6569f83a40beb529c5d4a2189a57443201d17eafc9be2c75e693316ddf6d98e3306a9819d20346c6f573b0d3fbb182eea3493ad8269f4d8bdeef640b79096
-  data.tar.gz: 70cc50536847e7f83fce477098f6feb780ce6bf9ed3571d1ed92b0f8cd6b929eb5dd2fd2bd4cbdc5afc9d4b989f3df07ffdb86ae901e698e66de2884c95811c6
+  metadata.gz: 3cc93b317de609aa3499ff76343b8a3376c5083211b3bf3fe8b2968f1777211040993e750be8fc1602f39bb2f3cde41cbb4d7cbf3ad7072efd45bdece58a23fd
+  data.tar.gz: dc2bfe69e31ccbc2f1ca08dcb1bcc1f8d2c4b38ae800b9c63ed7909689bdaf33454edf4b760125bc7ac6c34b7656a7e7192909b4a795c60c24915e869a73a457

data/CHANGELOG.md

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

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}"
@@ -77,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
 
@@ -120,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?

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/version.rb

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

data/lib/scanii.rb

@@ -1,5 +1,6 @@
 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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scanii-ruby
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Scanii
@@ -80,6 +80,7 @@ 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