smallpict 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c99d1d9f8d685017396f2c3e94e7715fbed0aa6a2e2c2315bf7dca11a1ec336
-  data.tar.gz: d87ea5708336c3600cc10d2e7bd11c219f0f355014eedeab0041accb30fc57fa
+  metadata.gz: 559f8ad84228a8b7beb0b3b10f3cd49192701ab548aa72602bf36e87011eb75b
+  data.tar.gz: b4965ff68dd978df9f8168a0c863baf3256fd6876276ad18c6df2debf363e881
 SHA512:
-  metadata.gz: 0ae9beee1528a5242fa7bede52a15186be036bce30f85456c03a6210bf5a6eaa7e533d73f54d3bd0fe54d1259e87286080cf1c79f04fdc489f8d72dd8b1b6bec
-  data.tar.gz: b7166c544f39637266ee9633a7cc7cdc4bf6912e89657da7fd3707744c3186411707499614a3c79047ec66e4a7c07c6cb9857c52a1a6d1fe171ce4af0dd6ddf6
+  metadata.gz: 6f9839d872ea23a77cb895f1138dff6f83c852a318035c56f83ff120db7453f36fc299f43775434a2463152d6fd5cfd302dc483f3a929ddb7aae8e2d94bb4aee
+  data.tar.gz: adbfe70b0b6b5d06584ca3160f207d9b0353ff90521bdd4c61f4cc42c76ae211c5d5a3f0fc7a240a5cf7ff6eb374a050c60a5bccefab753b3581cebf4ac1344f

data/CHANGELOG.md

@@ -5,7 +5,45 @@ All notable changes to the `smallpict` gem will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.0.8] - Unreleased
+
+Next release after v0.0.7. It includes the changes first written up as 0.1.0, which was never tagged or published.
+
+### Fixed
+- A `base_url` that ends in `/v1` (the form `SDK_SPEC.md` names) no longer produces `/v1/v1/...` paths and 404s; the client strips the suffix and adds `/v1` itself.
+- A queued optimize answer without `upload_url` or `job_id` raises `SmallPict::Error` with code `invalid_response` before any upload, instead of a raw URI error from Faraday.
+- Every Faraday error (for example `Faraday::SSLError` from a proxy with its own CA) is wrapped in `SmallPict::NetworkError`, so `rescue SmallPict::Error` catches it. `validate_key` returns `false` only for 401 and 403; an outage raises `NetworkError` instead of being reported as an invalid key.
+- `SmallPict.configure` takes effect after the first module-level call too. The memoised default client was never rebuilt, so a second `configure` (per-tenant rake task, test suite) kept the first keys.
+- The signature covers the request path without the query string, as the contract says; the status poll used to sign `/v1/optimize/status?job_id=...`, which only worked through a server-side fallback. `get_job_status` URL-encodes the job id instead of interpolating it raw into the query.
+- A 2xx response whose body is not JSON (a proxy or WAF page) raises `SmallPict::Error` with code `invalid_response` instead of being read as an empty result: `get_quota` returned plan `"free"`, `validate_key` returned `true` and `optimize` polled a phantom job until `wait_timeout`.
+- `mime_type` is detected when the caller gives none: from the first bytes (PNG, JPEG, GIF, WebP, AVIF), then from the filename extension, then `image/jpeg`. A PNG passed as bytes or a Tempfile was declared and uploaded as `image/jpeg`. An explicit `mime_type:` still wins.
+- `Retry-After` is capped at 30 seconds (`Client::MAX_RETRY_AFTER`). A 429 or 5xx with `Retry-After: 60` slept a Puma thread for a minute per attempt, up to three times in one request; the retry now waits at most 30 s.
+- Every request carries a fresh `X-Nonce`, so a retry inside the same second is no longer refused by the server as a replay (401 "Replay attack detected"); before, a transient 429 or 5xx could surface as `AuthenticationError`. `Idempotency-Key` is generated once per call and kept across retries instead of once per attempt.
+- `SmallPict::Client#inspect` and `SmallPict::Configuration#inspect` (and `to_s`) no longer print the API key and secret key; they show the base URL only. `Error.sanitize` also masks server-issued `sps_...` secrets, not only the `sec_`/`secret_` fixtures.
+- `optimize(bytes)` no longer raises `ArgumentError: path name contains null byte` for real image data. A String source was probed with `File.exist?`, which refuses the NUL bytes every PNG and JPEG header contains, so `SmallPict.optimize(File.binread("x.png"))` crashed before any request. A String is now sent as bytes unless it is NUL-free and names an existing file; a `Pathname` is read from disk and its basename becomes `filename`.
+
+### Removed
+- The `fit:` option (always sent as `"cover"`, not a server field, so it never did anything) and the `content_type` field of the request body (a duplicate of `mime_type`). `content_type:` is still accepted as an alias of `mime_type:`. The `faraday-retry` runtime dependency, which was never required (retries are implemented in the client), is gone from the gemspec.
+- `SmallPict::ActiveStorage::Service`. It was not an `ActiveStorage::Service` (no `upload`, `download`, `delete`, `exist?`, `url`; not configurable from `config/storage.yml`), and its `url_for` sent an empty body that the API rejects with 400, so it always raised. Use `SmallPict.optimize` on the bytes you hold.
+
+### Changed
+- RuboCop passes and runs in CI. `.rubocop.yml` now states the code's own conventions (double quotes, table-aligned hashes, 140-column lines outside specs) and turns off the size metrics and two naming cops that argued with the public API; the remaining offences were autocorrected.
+- **`secret_key` is required.** `SmallPict::Client.new` raises `ValidationError` when neither `secret_key:`, `SmallPict.configure` nor `SMALLPICT_SECRET_KEY` provides one. The Bearer-only mode (API key without signature) is gone: the API refuses it with 403 "Legacy Bearer token format is no longer supported", so a client built that way never worked. README examples pass both keys.
+- Release workflow runs `bundle exec rspec` before `gem build`, passes the RubyGems key through `GEM_HOST_API_KEY` instead of writing `~/.gem/credentials`, restricts the token to `contents: read`, and pins actions to commit SHAs.
+
+### Fixed
+- **`optimize` now returns an optimized image.** `POST /v1/optimize` only queues the job and returns a pre-signed `upload_url`; the SDK stopped there, so the worker failed every job with "client upload never arrived" and callers got an empty `url` with 0 % saved. `optimize` now PUTs the bytes to `upload_url` (plain PUT with `Content-Type` and `Content-Length` as sent, no API headers, no retry), polls `GET /v1/optimize/status` every `poll_interval` (default 1 s) and returns once the job is `completed`, with `url`, `format`, `bytes_saved`, `mode_applied`, `quality_applied` and `folder` from the job status (`SDK_SPEC.md` section 3d).
+
+### Added
+- `poll_interval` (seconds, default 1) and `wait_timeout` (seconds, default 120) on `SmallPict::Client.new` and `SmallPict.configure`.
+- `OptimizeResult#mode_applied` and `#quality_applied`.
+- Error codes `job_failed` (a failed job: `SmallPict::Error` with the server's `error.message` and `details["job_id"]`) and `upload_failed` (the storage refused the PUT: `SmallPict::Error` with the HTTP status in `#status_code`). A job still running after `wait_timeout` raises `SmallPict::TimeoutError` with the job id; it keeps running on the server, and `get_job_status` reads it later. A PUT that cannot connect raises `NetworkError`.
+
+### Changed
+- **`OptimizeResult#status` is always `"completed"`** and `#upload_url` is gone: there is no result to return before the job finished. Code that checked for `"queued"` or used `upload_url` to upload by itself can drop that.
+- **An `http://` or `https://` string source raises `ValidationError`** before any request. The API never fetched URLs, so such calls failed on the server; the SDK does not download on your behalf. A source that is neither an IO, a file path nor a String of bytes raises `ValidationError` too (it used to send `filesize: 0`).
+- `compressed_size` and `savings_percentage` are derived from the bytes sent and `bytes_saved` of the job status.
+- README: "What `optimize` does".
 
 ## [0.0.7] - 2026-10-31
 
@@ -35,7 +73,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Official Ruby SDK implementation for SmallPict OpenAPI 3.1.0 API.
 - Block-based global configuration (`SmallPict.configure { |c| ... }`) and standalone client instances (`SmallPict::Client.new`).
-- Rails ActiveStorage Service adapter (`SmallPict::ActiveStorage::Service`).
+- Rails ActiveStorage Service adapter (`SmallPict::ActiveStorage::Service`). Removed in the next release: it was not an ActiveStorage service.
 - 4 unified core client methods: `optimize`, `get_quota`, `purge_cdn`, and `validate_key`.
 - Helper `get_job_status` for polling asynchronous image conversion tasks.
 - Faraday connection pooling with automatic retry and jitter on HTTP 429/5xx.

data/README.md

@@ -1,6 +1,6 @@
 # SmallPict Ruby SDK
 
-Official Ruby gem for the [SmallPict Image Optimization API](https://smallpict.app) — high-performance next-gen image transcoding (AVIF, WebP), smart compression, Edge CDN delivery, cache purging, and Rails ActiveStorage support.
+Official Ruby gem for the [SmallPict Image Optimization API](https://smallpict.app) — high-performance next-gen image transcoding (AVIF, WebP), smart compression, Edge CDN delivery and cache purging.
 
 [![Gem Version](https://img.shields.io/gem/v/smallpict.svg)](https://rubygems.org/gems/smallpict)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -11,11 +11,10 @@ Official Ruby gem for the [SmallPict Image Optimization API](https://smallpict.a
 ## ⚡ Features
 
 - **💎 Idiomatic Ruby Design:** Block-based configuration (`SmallPict.configure`) and flexible standalone instances.
-- **🚀 Rails ActiveStorage Ready:** Built-in service adapter (`SmallPict::ActiveStorage::Service`).
-- **🛡️ Secure HMAC-SHA256 & Bearer Auth:** Tamper-proof payload verification.
+- **🛡️ HMAC-SHA256 request signing:** every request is signed with your secret key; both `api_key` and `secret_key` are required.
 - **✨ 4 Core Unified Methods:** `optimize()`, `get_quota()`, `purge_cdn()`, and `validate_key()`.
 - **🔄 Resilience & Fault Tolerance:** Automatic `Idempotency-Key` UUID injection, 30s timeouts, and exponential backoff with jitter on HTTP 429/5xx.
-- **🔒 Zero-Leak Privacy:** API keys and credentials are automatically redacted from `to_s` and `inspect` error logs.
+- **🔒 Zero-Leak Privacy:** API keys and secrets are redacted from error messages, and `Client#inspect` / `Configuration#inspect` show only the base URL.
 
 ---
 
@@ -24,7 +23,7 @@ Official Ruby gem for the [SmallPict Image Optimization API](https://smallpict.a
 Add to your application's `Gemfile`:
 
 ```ruby
-gem "smallpict", "~> 0.0.2"
+gem "smallpict", "~> 0.0.8"
 ```
 
 And then execute:
@@ -41,15 +40,18 @@ gem install smallpict
 
 ### 1. Global Block Configuration & Standalone Ruby
 
+`SmallPict.configure` is process-global: every `SmallPict.optimize` call in the process shares it. Code that serves several tenants with different keys builds its own `SmallPict::Client.new(api_key: ..., secret_key: ...)` per tenant.
+
 ```ruby
 require "smallpict"
 
 SmallPict.configure do |config|
   config.api_key    = ENV["SMALLPICT_API_KEY"]
-  config.secret_key = ENV["SMALLPICT_SECRET_KEY"] # Optional HMAC Secret Key
+  config.secret_key = ENV["SMALLPICT_SECRET_KEY"]
 end
 
 image_data = File.binread("hero-banner.png")
+# A source can be the image bytes (String), an open File or IO, or a Pathname.
 
 result = SmallPict.optimize(
   image_data,
@@ -64,6 +66,20 @@ puts "Optimized CDN URL: #{result.url}"
 puts "Saved: #{result.savings_percentage}% (#{result.bytes_saved} bytes)"
 ```
 
+#### What `optimize` does
+
+`optimize` returns a finished job. It sends the request, uploads the bytes to the pre-signed `upload_url` the API returns, then polls the job status every `poll_interval` seconds (default 1) until the job is completed, for at most `wait_timeout` seconds (default 120). The result has `status == "completed"`, `url`, `format`, `bytes_saved`, `mode_applied`, `quality_applied` and `folder` from the job status, plus `original_size` (the bytes you sent), `compressed_size` and `savings_percentage`.
+
+- Pass the image as bytes (a String), an IO (`File`, `Tempfile`, `StringIO`) or a local file path. An `http://` or `https://` URL raises `SmallPict::ValidationError`: the API does not fetch URLs, so download the image and pass its bytes.
+- A failed job raises `SmallPict::Error` with `code == "job_failed"`, the server's message and `details["job_id"]`. A refused upload raises `SmallPict::Error` with `code == "upload_failed"` and the HTTP status in `status_code`.
+- A job still running after `wait_timeout` raises `SmallPict::TimeoutError` with the job id in the message. The job keeps running on the server; read it later with `SmallPict.get_job_status(job_id)`.
+- A retry after a 5xx may create a second job until the server honours `Idempotency-Key`.
+
+```ruby
+client = SmallPict::Client.new(api_key: ENV["SMALLPICT_API_KEY"], secret_key: ENV["SMALLPICT_SECRET_KEY"],
+                               poll_interval: 2, wait_timeout: 60)
+```
+
 `AUTO` picks, per image, the lowest quality that keeps the visual score (SSIMULACRA 2) at or above 70, and ignores `quality`. It is on WP Pro and Business, Velocity, Momentum and sandbox keys (5 auto jobs per minute per sandbox key); where it cannot search (PNG or GIF output, animation, time limit) the job is lossy and `mode_applied` says so.
 
 `EXTREME` gives the smallest files on every plan. Leave `quality` out so the server uses its default for the output format; a quality you set is kept or raised to the format floor. Mode comparison: https://smallpict.app/en/docs/image-settings
@@ -83,6 +99,8 @@ SmallPict.configure do |config|
   config.api_key       = Rails.application.credentials.dig(:smallpict, :api_key)
   config.secret_key    = Rails.application.credentials.dig(:smallpict, :secret_key)
   config.fallback_mode = :passthrough # :throw | :passthrough
+  config.poll_interval = 1   # seconds between job status polls in optimize
+  config.wait_timeout  = 120 # seconds optimize waits before SmallPict::TimeoutError
 end
 ```
 
@@ -164,7 +182,7 @@ bundle exec rubocop
 
 ## 🔒 Security & Schema Compatibility (2026)
 
-- **`mime_type` & `content_type` Dual Support**: `OptimizeOptions` accepts both `mime_type` and `content_type` keyword arguments. Outgoing optimization payloads include both `mime_type` and `content_type` fields, ensuring seamless zero-disruption compatibility across all SmallPict API versions.
+- **`content_type` alias**: `OptimizeOptions` still accepts `content_type:` as an alias of `mime_type:` for older callers; only `mime_type` is sent, which is the field the API reads.
 
 ---
 

data/lib/smallpict/client.rb

@@ -3,10 +3,31 @@
 require "faraday"
 require "json"
 require "securerandom"
+require "uri"
 
 module SmallPict
   class Client
-    attr_reader :api_key, :secret_key, :base_url, :timeout, :max_retries, :fallback_mode
+    # Longest wait a Retry-After header may impose; the hourly purge limit would otherwise block a thread for an hour.
+    MAX_RETRY_AFTER = 30
+
+    MAGIC_MIMES = {
+      "\x89PNG".b      => "image/png",
+      "\xFF\xD8\xFF".b => "image/jpeg",
+      "GIF8".b         => "image/gif"
+    }.freeze
+
+    EXTENSION_MIMES = {
+      ".png" => "image/png", ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg", ".gif" => "image/gif",
+      ".webp" => "image/webp", ".avif" => "image/avif", ".svg" => "image/svg+xml"
+    }.freeze
+
+    attr_reader :api_key, :secret_key, :base_url, :timeout, :max_retries, :fallback_mode,
+                :poll_interval, :wait_timeout
+
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect}>"
+    end
+    alias to_s inspect
 
     def initialize(
       api_key: nil,
@@ -14,16 +35,21 @@ module SmallPict
       base_url: nil,
       timeout: nil,
       max_retries: nil,
-      fallback_mode: nil
+      fallback_mode: nil,
+      poll_interval: nil,
+      wait_timeout: nil
     )
       config = SmallPict.configuration
 
       @api_key       = api_key || config.api_key
       @secret_key    = secret_key || config.secret_key
-      @base_url      = (base_url || config.base_url).chomp("/")
+      # The client adds /v1 itself; SDK_SPEC names the base URL with it, so accept both forms.
+      @base_url      = (base_url || config.base_url).chomp("/").sub(%r{/v1\z}, "")
       @timeout       = (timeout || config.timeout).to_i
       @max_retries   = (max_retries || config.max_retries).to_i
       @fallback_mode = (fallback_mode || config.fallback_mode).to_sym
+      @poll_interval = poll_interval || config.poll_interval
+      @wait_timeout  = wait_timeout || config.wait_timeout
 
       validate_configuration!
     end
@@ -33,34 +59,38 @@ module SmallPict
       resolved = resolve_source(source, opts)
 
       payload = {
-        filename:     resolved[:filename],
-        mime_type:    resolved[:mime_type],
-        content_type: resolved[:mime_type],
-        filesize:     resolved[:filesize],
-        options:      opts.to_h
+        filename:  resolved[:filename],
+        mime_type: resolved[:mime_type],
+        filesize:  resolved[:filesize],
+        options:   opts.to_h
       }
 
       begin
-        res = request(:post, "/v1/optimize", payload, idempotency_key: opts.idempotency_key)
-        Models::OptimizeResult.new(res)
+        queued = request(:post, "/v1/optimize", payload, idempotency_key: opts.idempotency_key)
       rescue QuotaExceededError => e
-        if @fallback_mode == :passthrough
-          format_str = resolved[:mime_type].to_s.sub("image/", "")
-          Models::OptimizeResult.new(
-            job_id:             "fallback-passthrough",
-            status:             "completed",
-            url:                "",
-            format:             format_str,
-            original_size:      resolved[:filesize],
-            compressed_size:    resolved[:filesize],
-            bytes_saved:        0,
-            savings_percentage: 0.0,
-            data:               resolved[:bytes]
-          )
-        else
-          raise e
-        end
+        raise e unless @fallback_mode == :passthrough
+
+        format_str = resolved[:mime_type].to_s.sub("image/", "")
+        return Models::OptimizeResult.new(
+          job_id:             "fallback-passthrough",
+          status:             "completed",
+          url:                "",
+          format:             format_str,
+          original_size:      resolved[:filesize],
+          compressed_size:    resolved[:filesize],
+          bytes_saved:        0,
+          savings_percentage: 0.0,
+          data:               resolved[:bytes]
+        )
       end
+
+      unless queued.is_a?(Hash) && queued["upload_url"].is_a?(String) && queued["job_id"].is_a?(String)
+        raise Error.new("optimize response has no upload_url or job_id", code: "invalid_response", status_code: 200)
+      end
+
+      # The worker waits 30 s from the request for the object: upload now, poll after.
+      upload(queued["upload_url"], resolved[:bytes], resolved[:mime_type])
+      wait_for_job(queued["job_id"], resolved[:filesize])
     end
 
     def get_quota
@@ -88,23 +118,84 @@ module SmallPict
     def validate_key
       get_quota
       true
-    rescue StandardError
+    rescue AuthenticationError, PermissionDeniedError
       false
     end
 
     def get_job_status(job_id)
       raise ValidationError, "job_id is required" if job_id.nil? || job_id.to_s.empty?
 
-      res = request(:get, "/v1/optimize/status?job_id=#{job_id}")
+      res = request(:get, "/v1/optimize/status?job_id=#{URI.encode_www_form_component(job_id)}")
       Models::JobStatusResult.new(res)
     end
 
     private
 
+    # PUT the bytes to the pre-signed URL with only the two headers it was signed for:
+    # S3 refuses API headers or another type or length with 403. No retry: the worker
+    # stops waiting for the object 30 s after the job was queued.
+    def upload(url, bytes, mime_type)
+      response = connection.put(url) do |req|
+        req.headers = { "Content-Type" => mime_type, "Content-Length" => bytes.bytesize.to_s }
+        req.body = bytes
+      end
+      return if response.status >= 200 && response.status < 300
+
+      text = response.body.to_s
+      message = "Upload to staging failed with HTTP #{response.status}#{": #{text}" unless text.empty?}"
+      raise Error.new(message, code: "upload_failed", status_code: response.status)
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError, "Upload to staging timed out: #{e.message}"
+    rescue Faraday::Error => e
+      raise NetworkError, e.message
+    end
+
+    def wait_for_job(job_id, original_size)
+      deadline = monotonic_now + @wait_timeout
+      loop do
+        sleep((deadline - monotonic_now).clamp(0, @poll_interval))
+        status = get_job_status(job_id)
+
+        case status.status
+        when "completed"
+          bytes_saved = status.bytes_saved.to_i
+          return Models::OptimizeResult.new(
+            job_id:          status.job_id || job_id,
+            status:          "completed",
+            url:             status.url || "",
+            format:          status.format || "",
+            original_size:   original_size,
+            compressed_size: original_size - bytes_saved,
+            bytes_saved:     bytes_saved,
+            mode_applied:    status.mode_applied,
+            quality_applied: status.quality_applied,
+            folder:          status.folder
+          )
+        when "failed"
+          err = status.error
+          message = err.is_a?(Hash) ? err["message"] : err
+          message = "The optimization job failed." if message.nil? || message.to_s.empty?
+          raise Error.new(message.to_s, code: "job_failed", details: { "job_id" => job_id })
+        end
+
+        if monotonic_now >= deadline
+          raise TimeoutError,
+                "Job #{job_id} did not finish within #{@wait_timeout}s; poll get_job_status(\"#{job_id}\") later."
+        end
+      end
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     def validate_configuration!
       if @api_key.nil? || @api_key.to_s.strip.empty?
         raise ValidationError, "Missing required SmallPict API key. Provide `api_key:` or configure via `SmallPict.configure`."
       end
+      return unless @secret_key.nil? || @secret_key.to_s.strip.empty?
+
+      raise ValidationError, "Missing required SmallPict secret key. Provide `secret_key:` or set SMALLPICT_SECRET_KEY."
     end
 
     def request(method, path, body = nil, idempotency_key: nil)
@@ -115,6 +206,7 @@ module SmallPict
       body_str = body ? JSON.generate(body) : nil
       body_hash = body_str ? Crypto.sha256_hex(body_str) : Crypto::EMPTY_SHA256
 
+      idempotency_key ||= SecureRandom.uuid
       attempt = 0
       base_delay = 0.25 # 250ms
 
@@ -124,23 +216,18 @@ module SmallPict
           timestamp = Time.now.to_i.to_s
 
           headers = {
-            "Accept"     => "application/json",
-            "X-API-Key"  => @api_key
+            "Accept"    => "application/json",
+            "X-API-Key" => @api_key
           }
           headers["Content-Type"] = "application/json" if body_str
 
-          if @secret_key
-            string_to_sign = Crypto.build_string_to_sign(method, clean_path, timestamp, body_hash)
-            signature = Crypto.hmac_sha256_hex(@secret_key, string_to_sign)
-            headers["X-Timestamp"] = timestamp
-            headers["X-Signature"] = signature
-          else
-            headers["Authorization"] = "Bearer #{@api_key}"
-          end
+          string_to_sign = Crypto.build_string_to_sign(method, clean_path.split("?", 2).first, timestamp, body_hash)
+          headers["X-Timestamp"] = timestamp
+          headers["X-Signature"] = Crypto.hmac_sha256_hex(@secret_key, string_to_sign)
 
-          if %i[post patch delete].include?(method.to_s.downcase.to_sym)
-            headers["Idempotency-Key"] = idempotency_key || SecureRandom.uuid
-          end
+          # The server rejects a repeated signature as a replay unless the nonce differs.
+          headers["X-Nonce"] = SecureRandom.uuid
+          headers["Idempotency-Key"] = idempotency_key if %i[post patch delete].include?(method.to_s.downcase.to_sym)
 
           response = connection.send(method.to_s.downcase.to_sym, url) do |req|
             req.headers = headers
@@ -151,20 +238,19 @@ module SmallPict
           request_id = response.headers["x-request-id"]
           retry_after = response.headers["retry-after"]&.to_i
 
-          if (status == 429 && !hourly_purge_limit?(response.body)) || (status >= 500 && status <= 504)
-            if attempt <= @max_retries
-              delay = base_delay * (2**(attempt - 1))
-              delay = retry_after if retry_after && retry_after.positive?
-              jitter = rand(0..100) / 1000.0
-              sleep(delay + jitter)
-              next
-            end
-          end
-
           parsed = parse_body(response.body)
+          if ((status == 429 && !hourly_purge_limit?(parsed)) || status.between?(500, 504)) && (attempt <= @max_retries)
+            delay = base_delay * (2**(attempt - 1))
+            delay = [retry_after, MAX_RETRY_AFTER].min if retry_after&.positive?
+            jitter = rand(0..100) / 1000.0
+            sleep(delay + jitter)
+            next
+          end
 
-          if status < 200 || status >= 300
-            handle_error_response(status, parsed, request_id, retry_after)
+          handle_error_response(status, parsed, request_id, retry_after) if status < 200 || status >= 300
+          if parsed.key?("raw")
+            raise Error.new("Expected a JSON body, got: #{parsed["raw"].to_s[0, 200]}",
+                            code: "invalid_response", status_code: status, request_id: request_id)
           end
 
           return parsed
@@ -176,10 +262,10 @@ module SmallPict
             next
           end
           raise NetworkError, e.message
+        rescue Faraday::Error => e
+          raise NetworkError, e.message
         end
       end
-
-      raise TimeoutError, "Request failed after maximum retry attempts"
     end
 
     def connection
@@ -191,8 +277,7 @@ module SmallPict
     end
 
     # 429 purge_rate_limited is an hourly limit: retrying within seconds cannot succeed.
-    def hourly_purge_limit?(body_str)
-      body = parse_body(body_str)
+    def hourly_purge_limit?(body)
       body.is_a?(Hash) && body["error"].is_a?(Hash) && body["error"]["code"] == "purge_rate_limited"
     end
 
@@ -229,9 +314,7 @@ module SmallPict
       when 404 then raise NotFoundError.new(message, request_id: request_id, details: details)
       when 429 then raise RateLimitError.new(message, retry_after: retry_after, request_id: request_id, details: details)
       else
-        if status >= 500
-          raise ServerError.new(message, status_code: status, request_id: request_id, details: details)
-        end
+        raise ServerError.new(message, status_code: status, request_id: request_id, details: details) if status >= 500
 
         raise Error.new(message, code: code, status_code: status, request_id: request_id, details: details)
       end
@@ -239,32 +322,52 @@ module SmallPict
 
     def resolve_source(source, options)
       filename = options.filename || "image.jpg"
-      mime_type = options.mime_type || (options.respond_to?(:content_type) ? options.content_type : nil) || "image/jpeg"
+      explicit_mime = options.mime_type
       filesize = 0
       bytes = nil
 
+      if source.is_a?(String) && source.start_with?("http://", "https://")
+        raise ValidationError, "the API does not fetch URLs; download the image and pass its bytes"
+      end
+
       if source.respond_to?(:read)
         bytes = source.read
         filesize = bytes.bytesize
-        filename = File.basename(source.path) if source.respond_to?(:path) && options.filename.nil?
+        path = source.respond_to?(:to_path) ? source.to_path : (source.path if source.respond_to?(:path))
+        filename = File.basename(path) if path && options.filename.nil?
       elsif source.is_a?(String)
-        if File.exist?(source) && File.file?(source)
+        # Image bytes hold NUL, which File.file? refuses with ArgumentError; only probe a plausible path.
+        if !source.include?("\0") && File.file?(source)
           filename = File.basename(source) if options.filename.nil?
           bytes = File.binread(source)
-          filesize = bytes.bytesize
         else
           # Raw binary data
           bytes = source
-          filesize = bytes.bytesize
         end
+        filesize = bytes.bytesize
+      else
+        raise ValidationError, "Unsupported image source: pass an IO, a file path or the image bytes as a String"
       end
 
       {
         filename:  filename,
-        mime_type: mime_type,
+        mime_type: explicit_mime || detect_mime(bytes) || extension_mime(filename) || "image/jpeg",
         filesize:  filesize,
         bytes:     bytes
       }
     end
+
+    def detect_mime(bytes)
+      head = bytes.byteslice(0, 12).to_s.b
+      MAGIC_MIMES.each { |magic, mime| return mime if head.start_with?(magic) }
+      return "image/webp" if head.start_with?("RIFF".b) && head.byteslice(8, 4) == "WEBP".b
+      return "image/avif" if head.byteslice(4, 8) == "ftypavif".b
+
+      nil
+    end
+
+    def extension_mime(filename)
+      EXTENSION_MIMES[File.extname(filename.to_s).downcase]
+    end
   end
 end

data/lib/smallpict/configuration.rb

@@ -2,15 +2,23 @@
 
 module SmallPict
   class Configuration
-    attr_accessor :api_key, :secret_key, :base_url, :timeout, :max_retries, :fallback_mode
+    attr_accessor :api_key, :secret_key, :base_url, :timeout, :max_retries, :fallback_mode,
+                  :poll_interval, :wait_timeout
 
     def initialize
-      @api_key       = ENV["SMALLPICT_API_KEY"]
-      @secret_key    = ENV["SMALLPICT_SECRET_KEY"]
+      @api_key       = ENV.fetch("SMALLPICT_API_KEY", nil)
+      @secret_key    = ENV.fetch("SMALLPICT_SECRET_KEY", nil)
       @base_url      = (ENV["SMALLPICT_BASE_URL"] || "https://api.smallpict.app").chomp("/")
       @timeout       = 30
       @max_retries   = 3
       @fallback_mode = :throw
+      @poll_interval = 1   # seconds between job status polls in optimize
+      @wait_timeout  = 120 # seconds optimize waits for the job before TimeoutError
     end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect}>"
+    end
+    alias to_s inspect
   end
 end

data/lib/smallpict/errors.rb

@@ -38,7 +38,8 @@ module SmallPict
         end
       end
 
-      sanitized = sanitized.gsub(/(sec|secret)_[a-zA-Z0-9_-]{8,}/i, "***REDACTED***")
+      # Server-issued secrets are "sps_" + hex; sec_/secret_ are the test fixtures.
+      sanitized = sanitized.gsub(/(sps_[a-f0-9]{16,}|(sec|secret)_[a-zA-Z0-9_-]{8,})/i, "***REDACTED***")
       sanitized.gsub(/Bearer\s+[a-zA-Z0-9._-]+/i, "Bearer ***REDACTED***")
     end
   end

data/lib/smallpict/models/capacity.rb

@@ -22,19 +22,19 @@ module SmallPict
         l  = get(data, :lapse)
         new(
           period_end: get(data, :period_end),
-          storage: s && CapacityStorage.new(limit_bytes: get(s, :limit_bytes), used_bytes: get(s, :used_bytes),
-                                            base_bytes: get(s, :base_bytes), addon_blocks: get(s, :addon_blocks)),
-          cdn: cd && CapacityCdn.new(limit_bytes: get(cd, :limit_bytes), used_bytes: get(cd, :used_bytes),
-                                     status: get(cd, :status)),
-          booster: CapacityBooster.new(
-            active: get(b, :active) == true,
+          storage:    s && CapacityStorage.new(limit_bytes: get(s, :limit_bytes), used_bytes: get(s, :used_bytes),
+                                               base_bytes: get(s, :base_bytes), addon_blocks: get(s, :addon_blocks)),
+          cdn:        cd && CapacityCdn.new(limit_bytes: get(cd, :limit_bytes), used_bytes: get(cd, :used_bytes),
+                                            status: get(cd, :status)),
+          booster:    CapacityBooster.new(
+            active:         get(b, :active) == true,
             wp_quota_bytes: get(b, :wp_quota_bytes),
             api_transforms: get(b, :api_transforms),
-            cdn_bytes: get(b, :cdn_bytes),
-            next_expiry: e && CapacityExpiry.new(kind: get(e, :kind), units: get(e, :units),
-                                                 expires_at: get(e, :expires_at))
+            cdn_bytes:      get(b, :cdn_bytes),
+            next_expiry:    e && CapacityExpiry.new(kind: get(e, :kind), units: get(e, :units),
+                                                    expires_at: get(e, :expires_at))
           ),
-          lapse: l && CapacityLapse.new(stage: get(l, :stage), delete_after: get(l, :delete_after)),
+          lapse:      l && CapacityLapse.new(stage: get(l, :stage), delete_after: get(l, :delete_after)),
           manage_url: get(data, :manage_url)
         )
       end

data/lib/smallpict/models/optimize_options.rb

@@ -3,8 +3,8 @@
 module SmallPict
   module Models
     class OptimizeOptions
-      attr_reader :format, :quality, :max_width, :max_height, :max_dimension, :fit,
-                  :mode, :lossless, :folder, :strip_metadata, :filename, :mime_type, :content_type, :idempotency_key
+      attr_reader :format, :quality, :max_width, :max_height, :max_dimension,
+                  :mode, :lossless, :folder, :strip_metadata, :filename, :mime_type, :idempotency_key
 
       # mode:     SmallPict::Mode::LOSSY (server default when omitted), EXTREME or LOSSLESS.
       # quality:  optional 1-100; omitted when nil so the server picks the default per mode.
@@ -16,7 +16,6 @@ module SmallPict
         max_width: nil,
         max_height: nil,
         max_dimension: nil,
-        fit: "cover",
         mode: nil,
         lossless: nil,
         folder: nil,
@@ -31,27 +30,24 @@ module SmallPict
         @max_width       = max_width
         @max_height      = max_height
         @max_dimension   = max_dimension
-        @fit             = fit.to_s
         @lossless        = lossless
         @mode            = resolve_mode(mode, lossless)
         @folder          = folder.nil? ? nil : Folder.validate!(folder)
         @strip_metadata  = strip_metadata
         @filename        = filename
         @mime_type       = mime_type || content_type
-        @content_type    = content_type || mime_type
         @idempotency_key = idempotency_key
       end
 
       def to_h
         {
-          format: @format,
-          quality: @quality,
-          max_width: @max_width,
-          max_height: @max_height,
-          max_dimension: @max_dimension,
-          fit: @fit,
-          mode: @mode,
-          folder: @folder,
+          format:         @format,
+          quality:        @quality,
+          max_width:      @max_width,
+          max_height:     @max_height,
+          max_dimension:  @max_dimension,
+          mode:           @mode,
+          folder:         @folder,
           strip_metadata: @strip_metadata
         }.compact
       end

data/lib/smallpict/models/optimize_result.rb

@@ -5,7 +5,7 @@ module SmallPict
     class OptimizeResult
       attr_reader :job_id, :status, :url, :format, :original_size,
                   :compressed_size, :bytes_saved, :savings_percentage,
-                  :upload_url, :data, :folder
+                  :data, :folder, :mode_applied, :quality_applied
 
       def initialize(attributes = {})
         @job_id             = attributes[:job_id] || attributes["job_id"] || "sync"
@@ -15,11 +15,14 @@ module SmallPict
         @original_size      = (attributes[:original_size] || attributes["original_size"] || 0).to_i
         @compressed_size    = (attributes[:compressed_size] || attributes["compressed_size"] || @original_size).to_i
         @bytes_saved        = (attributes[:bytes_saved] || attributes["bytes_saved"] || [@original_size - @compressed_size, 0].max).to_i
-        @savings_percentage = (attributes[:savings_percentage] || attributes["savings_percentage"] || calculate_savings_percentage).to_f.round(2)
-        @upload_url         = attributes[:upload_url] || attributes["upload_url"]
+        @savings_percentage = (attributes[:savings_percentage] || attributes["savings_percentage"] ||
+                               calculate_savings_percentage).to_f.round(2)
         @data               = attributes[:data]
         # Normalized (lower case) by the server; nil without a folder.
         @folder             = attributes[:folder] || attributes["folder"]
+        # As reported by the job status; nil for a passthrough result.
+        @mode_applied       = attributes[:mode_applied] || attributes["mode_applied"]
+        @quality_applied    = attributes[:quality_applied] || attributes["quality_applied"]
       end
 
       private

data/lib/smallpict/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SmallPict
-  VERSION = "0.0.7"
+  VERSION = "0.0.8"
 end

data/lib/smallpict.rb

@@ -13,7 +13,6 @@ require_relative "smallpict/models/quota_response"
 require_relative "smallpict/models/purge_response"
 require_relative "smallpict/models/job_status_result"
 require_relative "smallpict/client"
-require_relative "smallpict/active_storage/service"
 
 module SmallPict
   class << self
@@ -23,6 +22,7 @@ module SmallPict
 
     def configure
       yield(configuration)
+      @default_client = nil # the next SmallPict.client picks up the new values
     end
 
     def reset_configuration!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smallpict
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: ruby
 authors:
 - SmallPict Engineering
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-02 00:00:00.000000000 Z
+date: 2026-11-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -24,20 +24,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: faraday-retry
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -53,35 +39,35 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.12'
 - !ruby/object:Gem::Dependency
-  name: webmock
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.18'
+        version: '1.50'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.18'
+        version: '1.50'
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.50'
+        version: '3.18'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.50'
+        version: '3.18'
 description: High-performance next-gen image transcoding (AVIF, WebP), smart compression,
-  Edge CDN delivery, and Rails ActiveStorage integration.
+  and Edge CDN delivery.
 email:
 - support@smallpict.app
 executables: []
@@ -93,7 +79,6 @@ files:
 - README.md
 - SECURITY.md
 - lib/smallpict.rb
-- lib/smallpict/active_storage/service.rb
 - lib/smallpict/client.rb
 - lib/smallpict/configuration.rb
 - lib/smallpict/crypto.rb
@@ -114,6 +99,7 @@ metadata:
   homepage_uri: https://smallpict.app
   source_code_uri: https://github.com/smallPict/smallpict-ruby
   changelog_uri: https://github.com/smallPict/smallpict-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:

data/lib/smallpict/active_storage/service.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module SmallPict
-  module ActiveStorage
-    class Service
-      attr_reader :client
-
-      def initialize(api_key: nil, secret_key: nil, base_url: nil, **options)
-        @client = SmallPict::Client.new(
-          api_key:    api_key,
-          secret_key: secret_key,
-          base_url:   base_url,
-          **options
-        )
-      end
-
-      def optimize(key, io, options = {})
-        opts = options.merge(filename: key)
-        @client.optimize(io, opts)
-      end
-
-      def url_for(key, options = {})
-        opts = options.merge(filename: key)
-        result = @client.optimize("", opts)
-        result.url
-      end
-    end
-  end
-end