scanii-ruby 0.0.1 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a216ea149bec56b29bd6b1a9337b07c31084a9387aaf74be336b6e0c08a53145
-  data.tar.gz: 24b8201eb8ed2cf9596ab5ca94850107f908b2268dc59edc6dc0f9c78d099db3
+  metadata.gz: 0e3c62870b928231999c133d889594f002682b74b34769c5741dbfe9a9c12693
+  data.tar.gz: a1673812fa7c2e46fa12657a3898fb01fdf56399c04146e95dfdf048d12ef185
 SHA512:
-  metadata.gz: b4e5e75b11d1989195d0d46399ad9e906883bb06bba7b8040cc32931b8cfee9347a3bcac01e571671bcb619a97f5be368b9bf41855ad837053b789468a3a96b8
-  data.tar.gz: d8df27af608f542892c73a4b2a93de77a3032e4d5f1f0a3e978df73164185caac083290bea6b0f6a8102b7847810ce36eb3b565d80ec2c558b9b95312626f127
+  metadata.gz: 1afa93f5a49873f5813dbf9701d5886b173a3e3d5dbdda9d214690308eb77d92b8ff96bde66b6fa78b2f455af32d317bf8e1ce1338824fa0a5801f2dbe4786cd
+  data.tar.gz: 6ed39afbb9846cec5916f8a77c8119a717f6e5c6e6da81dd17756a456fa069735063a20762a772090400d09b1e4fd85c883a92176beecf36479fe10d38ae7bd4

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to `scanii-ruby` are documented here. Versions follow [SemVer](https://semver.org).
+
+## 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.
+
+## 1.0.0 — Initial release
+
+First public release of the Scanii Ruby SDK on RubyGems as `scanii-ruby` (the plain `scanii` gem name is held by an abandoned third-party gem; this SDK uses the `scanii-ruby` convention matching `twilio-ruby`). Supersedes the `scanii-ruby 0.0.1` namespace-reservation placeholder.
+
+Reference implementation frozen at scanii-java v8.0.0.
+
+### API surface
+
+- `Scanii::Client#process(file_path, metadata:, callback:)` → `Scanii::ProcessingResult`
+- `Scanii::Client#process_async(file_path, metadata:, callback:)` → `Scanii::PendingResult`
+- `Scanii::Client#fetch(url, metadata:, callback:)` → `Scanii::PendingResult`
+- `Scanii::Client#retrieve(id)` → `Scanii::ProcessingResult`
+- `Scanii::Client#ping` → `true`
+- `Scanii::Client#create_auth_token(timeout_seconds)` → `Scanii::AuthToken`
+- `Scanii::Client#retrieve_auth_token(id)` → `Scanii::AuthToken`
+- `Scanii::Client#delete_auth_token(id)` → `true`
+
+Errors: `Scanii::Error` (base), `Scanii::AuthError` (401/403), `Scanii::RateLimitError` (429, with `retry_after`).
+
+### Highlights
+
+- **Zero runtime dependencies.** Stdlib `net/http` + `json` + `securerandom` + `base64` only.
+- **Hand-rolled multipart/form-data encoder** (no `multipart-post`, no `rack-mime`).
+- **Synchronous.** Single-threaded by default; create one `Scanii::Client` per thread.
+- **Targets Ruby 3.4+.**
+- **scanii-cli** integration tests cover Linux / macOS / Windows on Ruby 3.4 and 4.0 without burning real Scanii credits. (Ruby 3.5 was preview-only and has no rubyinstaller2 build for Windows.)
+- **OIDC trusted publishing** to RubyGems via `rubygems/release-gem` — no long-lived API key in repo secrets.

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -1,5 +1,134 @@
-# scanii-ruby (placeholder)
+# scanii-ruby
 
-The official Scanii Ruby SDK is being released as `scanii-ruby` v1.0.0 shortly.
+Official Ruby SDK for the [Scanii](https://www.scanii.com) content security API.
 
-In the meantime, see [scanii.com](https://scanii.com) and [github.com/scanii/scanii-ruby](https://github.com/scanii/scanii-ruby).
+[![Gem Version](https://img.shields.io/gem/v/scanii-ruby.svg)](https://rubygems.org/gems/scanii-ruby)
+
+> **Looking for `scanii`?** That gem name is held by an abandoned third-party gem. The official Scanii Ruby SDK is published as **`scanii-ruby`** (matching the [`twilio-ruby`](https://rubygems.org/gems/twilio-ruby) convention).
+
+## SDK Principles
+
+1. **Light.** Zero runtime dependencies, stdlib only.
+2. **Up to date.** Always current with the latest Scanii API.
+3. **Integration-only.** Wraps the REST API — retries, concurrency, and batching are the caller's responsibility.
+
+## Install
+
+Add to your `Gemfile`:
+
+```ruby
+gem "scanii-ruby", "~> 1.0"
+```
+
+Or install directly:
+
+```bash
+gem install scanii-ruby
+```
+
+Targets Ruby 3.4+. Zero runtime dependencies.
+
+## Quickstart
+
+```ruby
+require "scanii"
+
+client = Scanii::Client.new(key: "your-key", secret: "your-secret")
+
+result = client.process("./file.pdf")
+puts "findings: #{result.findings.inspect}"
+```
+
+`findings` is an `Array<String>`. An empty array means the content is clean.
+
+## API
+
+| Method | REST | Returns |
+|---|---|---|
+| `process(file_path, metadata:, callback:)` | `POST /files` | `Scanii::ProcessingResult` |
+| `process_async(file_path, metadata:, callback:)` | `POST /files/async` | `Scanii::PendingResult` |
+| `fetch(url, metadata:, callback:)` | `POST /files/fetch` | `Scanii::PendingResult` |
+| `retrieve(id)` | `GET /files/{id}` | `Scanii::ProcessingResult` |
+| `ping` | `GET /ping` | `true` |
+| `create_auth_token(timeout_seconds)` | `POST /auth/tokens` | `Scanii::AuthToken` |
+| `retrieve_auth_token(id)` | `GET /auth/tokens/{id}` | `Scanii::AuthToken` |
+| `delete_auth_token(id)` | `DELETE /auth/tokens/{id}` | `true` |
+
+Full API reference: <https://scanii.github.io/openapi/v22/>.
+
+## Regional endpoints
+
+```ruby
+client = Scanii::Client.new(
+  key: "k",
+  secret: "s",
+  endpoint: "https://api-eu1.scanii.com"
+)
+```
+
+| Region | 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` |
+
+## Errors
+
+```ruby
+require "scanii"
+
+begin
+  client.ping
+rescue Scanii::AuthError => e
+  warn "bad creds: #{e.message} (request_id=#{e.request_id})"
+rescue Scanii::RateLimitError => e
+  warn "rate-limited; retry after #{e.retry_after}s"
+rescue Scanii::Error => e
+  warn "other error: #{e.message} (status=#{e.status_code})"
+end
+```
+
+Error hierarchy:
+
+- `Scanii::Error` — base class, carries `status_code`, `request_id`, `host_id`, `body`
+- `Scanii::AuthError` — HTTP 401 / 403
+- `Scanii::RateLimitError` — HTTP 429, with `retry_after` (seconds, when the server provided `Retry-After`)
+
+Per SDK Principle 3, the SDK does not retry on the caller's behalf — backoff and retry policy belong to your application.
+
+## Auth tokens
+
+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")
+token = server_client.create_auth_token(300)
+
+token_client = Scanii::Client.new(token: token.id)
+token_client.ping
+```
+
+## Local testing with scanii-cli
+
+The SDK ships integration tests against [scanii-cli](https://github.com/scanii/scanii-cli), a local mock server. No real Scanii credentials are needed.
+
+```bash
+docker run -d --name scanii-cli -p 4000:4000 ghcr.io/scanii/scanii-cli:latest server
+
+bundle install
+bundle exec rake test
+```
+
+Test credentials are `key` / `secret`. Override the endpoint by exporting `SCANII_TEST_ENDPOINT=...` before `rake test`. Integration tests self-skip when scanii-cli is not reachable, so `rake test` is safe to run in any environment.
+
+## Contributing
+
+Bug reports and PRs welcome at <https://github.com/scanii/scanii-ruby/issues>.
+
+## License
+
+[Apache-2.0](LICENSE).

data/lib/scanii/auth_token.rb

@@ -0,0 +1,40 @@
+require "json"
+
+module Scanii
+  # Short-lived auth token returned by Client#create_auth_token and
+  # Client#retrieve_auth_token.
+  #
+  # Pass id back as the token: keyword argument when constructing a Client to
+  # authenticate using the token instead of API key + secret.
+  #
+  # @see https://scanii.github.io/openapi/v22/
+  class AuthToken
+    attr_reader :id, :creation_date, :expiration_date,
+                :request_id, :host_id, :resource_location, :raw_response
+
+    def initialize(id:, creation_date:, expiration_date:,
+                   request_id:, host_id:, resource_location:, raw_response:)
+      @id                = id
+      @creation_date     = creation_date
+      @expiration_date   = expiration_date
+      @request_id        = request_id
+      @host_id           = host_id
+      @resource_location = resource_location
+      @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,
+        creation_date: json["creation_date"]&.to_s,
+        expiration_date: json["expiration_date"]&.to_s,
+        request_id: headers["x-scanii-request-id"],
+        host_id: headers["x-scanii-host-id"],
+        resource_location: headers["location"],
+        raw_response: body
+      )
+    end
+  end
+end

data/lib/scanii/client.rb

@@ -0,0 +1,271 @@
+require "json"
+require "net/http"
+require "uri"
+
+module Scanii
+  # Synchronous client for the Scanii REST API v2.2.
+  #
+  # Construct with either +key:+ + +secret:+ (HTTP Basic Auth) or +token:+
+  # (auth-token authentication). Mixing the two raises ArgumentError.
+  #
+  # Per SDK Principle 3 the client is integration-only: it does not retry,
+  # batch, or paginate. Each public method maps to exactly one HTTP request.
+  #
+  # @see https://scanii.github.io/openapi/v22/
+  #
+  # @example
+  #   client = Scanii::Client.new(key: "your-key", secret: "your-secret")
+  #   result = client.process("./file.pdf")
+  #   puts result.findings  # [] when clean
+  class Client
+    DEFAULT_ENDPOINT = "https://api.scanii.com".freeze
+    DEFAULT_TIMEOUT  = 60
+    API_VERSION_PATH = "/v2.2".freeze
+    USER_AGENT       = "scanii-ruby/#{Scanii::VERSION}".freeze
+
+    attr_reader :endpoint, :timeout, :user_agent
+
+    # @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 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)
+      @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?
+
+      @base_uri = URI.parse("#{@endpoint}#{API_VERSION_PATH}")
+      raise ArgumentError, "endpoint must be http(s)" unless %w[http https].include?(@base_uri.scheme)
+
+      @timeout    = Integer(timeout)
+      @user_agent = user_agent && !user_agent.empty? ? "#{user_agent} #{USER_AGENT}" : USER_AGENT
+    end
+
+    # Submit a file for synchronous scanning.
+    #
+    # @see https://scanii.github.io/openapi/v22/  POST /files
+    # @return [Scanii::ProcessingResult]
+    def process(file_path, metadata: nil, callback: nil)
+      assert_readable(file_path)
+      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)
+      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.
+    #
+    # @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)
+      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)
+      raise_for_status(status, resp_body, headers) unless status == 202
+      PendingResult.from_response(resp_body, headers)
+    end
+
+    # Ask Scanii to download a remote URL and scan it asynchronously.
+    #
+    # @see https://scanii.github.io/openapi/v22/  POST /files/fetch
+    # @return [Scanii::PendingResult]
+    def fetch(url, metadata: nil, callback: nil)
+      raise ArgumentError, "url must not be empty" if url.nil? || url.empty?
+
+      form = { "location" => url }
+      form["callback"] = callback if callback && !callback.empty?
+      (metadata || {}).each { |k, v| form["metadata[#{k}]"] = v.to_s }
+
+      status, resp_body, headers = post(
+        "/files/fetch",
+        body: URI.encode_www_form(form),
+        content_type: "application/x-www-form-urlencoded"
+      )
+      raise_for_status(status, resp_body, headers) unless status == 202
+      PendingResult.from_response(resp_body, headers)
+    end
+
+    # Retrieve a previously submitted scan result by id.
+    #
+    # @see https://scanii.github.io/openapi/v22/  GET /files/{id}
+    # @return [Scanii::ProcessingResult]
+    def retrieve(id)
+      raise ArgumentError, "id must not be empty" if id.nil? || id.empty?
+
+      status, resp_body, headers = request("GET", "/files/#{url_encode(id)}")
+      raise_for_status(status, resp_body, headers) unless status == 200
+      ProcessingResult.from_response(resp_body, headers)
+    end
+
+    # Verify that the configured credentials reach the API.
+    #
+    # @see https://scanii.github.io/openapi/v22/  GET /ping
+    # @return [Boolean] true when the API responds 200
+    def ping
+      status, resp_body, headers = request("GET", "/ping")
+      return true if status == 200
+
+      raise_for_status(status, resp_body, headers)
+    end
+
+    # Mint a short-lived auth token. timeout_seconds must be positive.
+    #
+    # @see https://scanii.github.io/openapi/v22/  POST /auth/tokens
+    # @return [Scanii::AuthToken]
+    def create_auth_token(timeout_seconds)
+      ts = Integer(timeout_seconds)
+      raise ArgumentError, "timeout_seconds must be positive" if ts <= 0
+
+      status, resp_body, headers = post(
+        "/auth/tokens",
+        body: URI.encode_www_form("timeout" => ts),
+        content_type: "application/x-www-form-urlencoded"
+      )
+      raise_for_status(status, resp_body, headers) unless [200, 201].include?(status)
+      AuthToken.from_response(resp_body, headers)
+    end
+
+    # Inspect a previously created auth token.
+    #
+    # @see https://scanii.github.io/openapi/v22/  GET /auth/tokens/{id}
+    # @return [Scanii::AuthToken]
+    def retrieve_auth_token(id)
+      raise ArgumentError, "id must not be empty" if id.nil? || id.empty?
+
+      status, resp_body, headers = request("GET", "/auth/tokens/#{url_encode(id)}")
+      raise_for_status(status, resp_body, headers) unless status == 200
+      AuthToken.from_response(resp_body, headers)
+    end
+
+    # Revoke an auth token.
+    #
+    # @see https://scanii.github.io/openapi/v22/  DELETE /auth/tokens/{id}
+    # @return [Boolean] true on 204
+    def delete_auth_token(id)
+      raise ArgumentError, "id must not be empty" if id.nil? || id.empty?
+
+      status, resp_body, headers = request("DELETE", "/auth/tokens/#{url_encode(id)}")
+      raise_for_status(status, resp_body, headers) unless status == 204
+      true
+    end
+
+    private
+
+    def build_auth_header(key, secret, token)
+      if token && !token.empty?
+        raise ArgumentError, "supply either token: or key:+secret:, not both" if key || secret
+
+        "Basic #{base64_encode("#{token}:")}"
+      else
+        raise ArgumentError, "key must be set (or use token: for auth-token mode)" if key.nil? || key.empty?
+        raise ArgumentError, "key must not contain a colon" if key.include?(":")
+        raise ArgumentError, "secret must be set when using key auth" if secret.nil? || secret.empty?
+
+        "Basic #{base64_encode("#{key}:#{secret}")}"
+      end
+    end
+
+    # Stdlib-only base64. Array#pack("m0") emits RFC 4648 base64 with no
+    # newlines -- identical output to Base64.strict_encode64 -- without
+    # requiring the unbundled `base64` gem on Ruby 3.4+.
+    def base64_encode(value)
+      [value].pack("m0")
+    end
+
+    def assert_readable(path)
+      raise ArgumentError, "file at #{path} is not readable" unless File.file?(path) && File.readable?(path)
+    end
+
+    def build_text_fields(metadata, callback)
+      fields = {}
+      (metadata || {}).each { |k, v| fields["metadata[#{k}]"] = v.to_s }
+      fields["callback"] = callback if callback && !callback.empty?
+      fields
+    end
+
+    def post(path, body:, content_type:)
+      request("POST", path, body: body, content_type: content_type)
+    end
+
+    def request(method, path, body: nil, content_type: nil)
+      uri = URI.parse("#{@base_uri}#{path}")
+
+      req = build_request(method, uri, body, content_type)
+
+      Net::HTTP.start(uri.hostname, uri.port,
+                      use_ssl: uri.scheme == "https",
+                      open_timeout: @timeout,
+                      read_timeout: @timeout) do |http|
+        response = http.request(req)
+        headers = capture_headers(response)
+        [response.code.to_i, response.body.to_s, headers]
+      end
+    rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Net::OpenTimeout, Net::ReadTimeout, SocketError => e
+      raise Scanii::Error, "transport error: #{e.class}: #{e.message}"
+    end
+
+    def build_request(method, uri, body, content_type)
+      klass = case method
+              when "GET"    then Net::HTTP::Get
+              when "POST"   then Net::HTTP::Post
+              when "DELETE" then Net::HTTP::Delete
+              else raise ArgumentError, "unsupported method: #{method}"
+              end
+
+      req = klass.new(uri.request_uri)
+      req["Authorization"] = @auth_header
+      req["User-Agent"]    = @user_agent
+      req["Accept"]        = "application/json"
+      req["Content-Type"]  = content_type if content_type
+      req.body = body if body
+      req
+    end
+
+    def capture_headers(response)
+      headers = {}
+      response.each_header { |name, value| headers[name.downcase] = value }
+      headers
+    end
+
+    def raise_for_status(status, body, headers)
+      request_id = headers["x-scanii-request-id"]
+      host_id    = headers["x-scanii-host-id"]
+      message    = extract_error_message(body) || "HTTP #{status}"
+
+      case status
+      when 401, 403
+        raise Scanii::AuthError.new(message, status_code: status, request_id: request_id,
+                                             host_id: host_id, body: body)
+      when 429
+        retry_after = headers["retry-after"]&.to_i
+        raise Scanii::RateLimitError.new(message, status_code: status, request_id: request_id,
+                                                  host_id: host_id, body: body, retry_after: retry_after)
+      else
+        raise Scanii::Error.new(message, status_code: status, request_id: request_id,
+                                         host_id: host_id, body: body)
+      end
+    end
+
+    def extract_error_message(body)
+      return nil if body.nil? || body.empty?
+
+      decoded = JSON.parse(body)
+      return decoded["error"].to_s if decoded.is_a?(Hash) && decoded["error"].is_a?(String)
+
+      body
+    rescue JSON::ParserError
+      body
+    end
+
+    def url_encode(value)
+      URI.encode_www_form_component(value)
+    end
+  end
+end

data/lib/scanii/error.rb

@@ -0,0 +1,36 @@
+module Scanii
+  # Base class for all errors raised by Scanii::Client. Carries the API-supplied
+  # message plus optional X-Scanii-Request-Id and X-Scanii-Host-Id headers for
+  # support handoffs.
+  #
+  # Per SDK Principle 3 (integration-only) the SDK does not retry on the caller's
+  # behalf -- backoff is the caller's responsibility.
+  #
+  # @see https://scanii.github.io/openapi/v22/
+  class Error < StandardError
+    attr_reader :status_code, :request_id, :host_id, :body
+
+    def initialize(message, status_code: nil, request_id: nil, host_id: nil, body: nil)
+      super(message)
+      @status_code = status_code
+      @request_id  = request_id
+      @host_id     = host_id
+      @body        = body
+    end
+  end
+
+  # Raised on HTTP 401 / 403 -- the credentials were rejected by the API.
+  class AuthError < Error
+  end
+
+  # Raised on HTTP 429. retry_after carries the value of the Retry-After
+  # response header in seconds when the server provided one.
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: nil, **)
+      super(message, **)
+      @retry_after = retry_after
+    end
+  end
+end

data/lib/scanii/multipart.rb

@@ -0,0 +1,100 @@
+require "securerandom"
+
+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
+
+    # Generate a unique multipart boundary.
+    def make_boundary
+      "----scanii-ruby-boundary-#{SecureRandom.hex(16)}"
+    end
+
+    # Build the Content-Type header value for a request using boundary.
+    def make_content_type(boundary)
+      "multipart/form-data; boundary=#{boundary}"
+    end
+
+    # Encode a multipart body containing the bytes at file_path plus the given
+    # text fields.
+    #
+    # @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 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")
+      boundary = make_boundary
+
+      filename = File.basename(file_path)
+      content_type = guess_content_type(file_path)
+      file_bytes = File.binread(file_path)
+
+      body = String.new(encoding: Encoding::BINARY)
+
+      fields.each do |name, value|
+        write_text_part(body, boundary, name.to_s, value.to_s)
+      end
+
+      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
+
+      [body, make_content_type(boundary)]
+    end
+
+    # Best-effort content-type lookup by 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
+      MIME_TYPES.fetch(ext, "application/octet-stream")
+    end
+
+    MIME_TYPES = {
+      "txt" => "text/plain",
+      "html" => "text/html",
+      "htm" => "text/html",
+      "css" => "text/css",
+      "csv" => "text/csv",
+      "json" => "application/json",
+      "xml" => "application/xml",
+      "pdf" => "application/pdf",
+      "zip" => "application/zip",
+      "gz" => "application/gzip",
+      "jpg" => "image/jpeg",
+      "jpeg" => "image/jpeg",
+      "png" => "image/png",
+      "gif" => "image/gif",
+      "webp" => "image/webp",
+      "svg" => "image/svg+xml",
+      "mp3" => "audio/mpeg",
+      "mp4" => "video/mp4",
+      "mov" => "video/quicktime",
+      "doc" => "application/msword",
+      "docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "xls" => "application/vnd.ms-excel",
+      "xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    }.freeze
+    private_constant :MIME_TYPES
+
+    def write_text_part(body, boundary, 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.b
+      body << "\r\n".b
+    end
+    private_class_method :write_text_part
+  end
+end

data/lib/scanii/pending_result.rb

@@ -0,0 +1,34 @@
+require "json"
+
+module Scanii
+  # Result of an asynchronous scan submission returned by Client#process_async
+  # and Client#fetch.
+  #
+  # The actual scan result is fetched later via Client#retrieve, or delivered
+  # to the supplied callback URL.
+  #
+  # @see https://scanii.github.io/openapi/v22/
+  class PendingResult
+    attr_reader :id, :request_id, :host_id, :resource_location, :raw_response
+
+    def initialize(id:, request_id:, host_id:, resource_location:, raw_response:)
+      @id                = id
+      @request_id        = request_id
+      @host_id           = host_id
+      @resource_location = resource_location
+      @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,
+        request_id: headers["x-scanii-request-id"],
+        host_id: headers["x-scanii-host-id"],
+        resource_location: headers["location"],
+        raw_response: body
+      )
+    end
+  end
+end

data/lib/scanii/processing_result.rb

@@ -0,0 +1,51 @@
+require "json"
+
+module Scanii
+  # Result of a synchronous file scan returned by Client#process and
+  # Client#retrieve.
+  #
+  # findings is always an Array. Empty array means the content is clean.
+  #
+  # @see https://scanii.github.io/openapi/v22/
+  class ProcessingResult
+    attr_reader :id, :findings, :checksum, :content_length, :content_type,
+                :metadata, :creation_date, :error,
+                :request_id, :host_id, :resource_location, :raw_response
+
+    def initialize(id:, findings:, checksum:, content_length:, content_type:,
+                   metadata:, creation_date:, error:,
+                   request_id:, host_id:, resource_location:, raw_response:)
+      @id                = id
+      @findings          = findings
+      @checksum          = checksum
+      @content_length    = content_length
+      @content_type      = content_type
+      @metadata          = metadata
+      @creation_date     = creation_date
+      @error             = error
+      @request_id        = request_id
+      @host_id           = host_id
+      @resource_location = resource_location
+      @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,
+        findings: Array(json["findings"]).map(&:to_s),
+        checksum: json["checksum"]&.to_s,
+        content_length: json["content_length"]&.to_i,
+        content_type: json["content_type"]&.to_s,
+        metadata: (json["metadata"] || {}).transform_values(&:to_s),
+        creation_date: json["creation_date"]&.to_s,
+        error: json["error"]&.to_s,
+        request_id: headers["x-scanii-request-id"],
+        host_id: headers["x-scanii-host-id"],
+        resource_location: headers["location"],
+        raw_response: body
+      )
+    end
+  end
+end

data/lib/scanii/version.rb

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

data/lib/scanii.rb

@@ -0,0 +1,13 @@
+require_relative "scanii/version"
+require_relative "scanii/error"
+require_relative "scanii/processing_result"
+require_relative "scanii/pending_result"
+require_relative "scanii/auth_token"
+require_relative "scanii/multipart"
+require_relative "scanii/client"
+
+# Top-level namespace for the Scanii Ruby SDK.
+#
+# See https://scanii.github.io/openapi/v22/ for the full API reference.
+module Scanii
+end

metadata

@@ -1,30 +1,95 @@
 --- !ruby/object:Gem::Specification
 name: scanii-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.1
 platform: ruby
 authors:
 - Scanii
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-28 00:00:00.000000000 Z
-dependencies: []
-description: Placeholder release. See https://github.com/scanii/scanii-ruby for the
-  upcoming v1.0.0.
-email: 
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: Ruby client for Scanii (scanii.com). Stdlib only -- no runtime dependencies.
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
 - README.md
+- lib/scanii.rb
+- lib/scanii/auth_token.rb
+- lib/scanii/client.rb
+- lib/scanii/error.rb
+- lib/scanii/multipart.rb
+- lib/scanii/pending_result.rb
+- lib/scanii/processing_result.rb
+- lib/scanii/version.rb
 homepage: https://github.com/scanii/scanii-ruby
 licenses:
 - Apache-2.0
 metadata:
   homepage_uri: https://scanii.com
   source_code_uri: https://github.com/scanii/scanii-ruby
-post_install_message: 
+  documentation_uri: https://scanii.github.io/openapi/v22/
+  changelog_uri: https://github.com/scanii/scanii-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -39,9 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 4.0.6
 specification_version: 4
-summary: Placeholder. The official Scanii Ruby SDK is releasing as scanii-ruby v1.0.0
-  — coming soon.
+summary: Zero-dependency Ruby SDK for the Scanii content security API
 test_files: []