smallpict 0.0.6 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c32e00d3a73e92ac5781a8e3d61cb90d6e81a62880d45318caaeaa87e29b39f
-  data.tar.gz: 1aad44c760c834fc47b7bfa4c2513ec498a0c57c3830bd7317c82b5a9ed99391
+  metadata.gz: 559f8ad84228a8b7beb0b3b10f3cd49192701ab548aa72602bf36e87011eb75b
+  data.tar.gz: b4965ff68dd978df9f8168a0c863baf3256fd6876276ad18c6df2debf363e881
 SHA512:
-  metadata.gz: 715d75a35e3dd824d2a9b98ef720ff4a8f9a6dbf79a92076517aae7ea4da5f8d8edafd8d3999b402620a846b06a56ac892e85033117748c73b932e886a63e279
-  data.tar.gz: 6eeb642b7b22f49d7c90d50188f5afb1f4c632b61819d592a483cb7d199505bfcbd6916e3e198d67c138715e6c5513dc0f140b992f1a24b3f2153c94224c929a
+  metadata.gz: 6f9839d872ea23a77cb895f1138dff6f83c852a318035c56f83ff120db7453f36fc299f43775434a2463152d6fd5cfd302dc483f3a929ddb7aae8e2d94bb4aee
+  data.tar.gz: adbfe70b0b6b5d06584ca3160f207d9b0353ff90521bdd4c61f4cc42c76ae211c5d5a3f0fc7a240a5cf7ff6eb374a050c60a5bccefab753b3581cebf4ac1344f

data/CHANGELOG.md

@@ -5,12 +5,75 @@ 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).
 
+## [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
+
+### Added
+- `SmallPict::Mode::AUTO` (`"auto"`, also in `Mode::ALL`): the server picks the quality per image from a visual score (CMP-07). Plans: WP Pro and Business, Velocity, Momentum and sandbox; a server without auto enabled answers `400 invalid_mode` (`ValidationError`).
+- `mode:` option on `optimize` (`"lossy"` default, `"extreme"`, `"lossless"`), with constants `SmallPict::Mode::LOSSY`, `EXTREME`, `LOSSLESS` and the frozen list `SmallPict::Mode::ALL`. The server checks the mode against the plan: `403 mode_not_in_plan` raises `PermissionDeniedError` with `details["mode"]` and `details["allowed_modes"]`; `400 invalid_mode` raises `ValidationError`.
+- `JobStatusResult#mode_applied` and `#quality_applied`, as reported by the server (`nil` for jobs created before modes existed).
+- `folder:` option on `optimize`, sent as `options.folder` and omitted when unset. The server stores the file under that folder of your account and lower-cases the value; `OptimizeResult#folder` and `JobStatusResult#folder` return it as stored (`nil` without one). The client rejects empty segments (`a//b`, leading or trailing `/`), `..` segments and more than 3 segments with `ValidationError` before any request; the server checks the full format (`400 invalid_folder` raises `ValidationError` with the server's message).
+- `purge_cdn(purge_type: "folder", folder: "...")` purges one upload folder. `folder:` is required for that type (`ValidationError` before any request when missing or malformed) and is sent only with it; `url` and `all` purges are unchanged.
+- `QuotaResponse#capacity`: the read-only capacity of `GET /v1/quota` as `SmallPict::Models::Capacity` (`period_end`, `storage`, `cdn`, `booster` with `next_expiry`, `lapse`, `manage_url`). Members that do not apply to the plan are `nil`; `capacity` is `nil` when the server could not read it and on older servers that do not send it. Existing quota fields are unchanged. Capacity is bought only in the dashboard; the SDK exposes `manage_url` as a string and never opens or fetches it.
+- `SmallPict::Error#upgrade_url` on every error: `details["upgrade_url"]` when it is a string (sent with `402` quota, storage and read-only errors), otherwise `nil`. `PermissionDeniedError#allowed_modes` returns `details["allowed_modes"]` of `403 mode_not_in_plan`, otherwise `nil`. Status-to-class mapping is unchanged.
+
+### Changed
+- README: example of `mode: SmallPict::Mode::EXTREME` without `quality:`.
+- `429 purge_rate_limited` (hourly limit: 10 `folder` and 2 `all` purges per hour) raises `RateLimitError` without automatic retries, since the limit does not reset within seconds. Other 429 responses are still retried as before.
+- Errors raised as the base `SmallPict::Error` (statuses without a dedicated class, such as `409`) now carry the server's `error.code` in `#code` instead of `"INTERNAL_ERROR"`; `"INTERNAL_ERROR"` remains when the body has no code. Typed errors keep their fixed codes.
+
+### Deprecated
+- `lossless:` option on `optimize`. Use `mode: SmallPict::Mode::LOSSLESS` instead. `lossless: true` without `mode:` is sent as `mode: "lossless"`; `lossless: true` with a different `mode:` raises `ValidationError` before any request. Using it emits a `:deprecated` category warning (shown when `Warning[:deprecated]` is enabled). It will not be removed before the next major version.
+
+### Fixed
+- `quality:` is no longer sent when unset (its default is now `nil` instead of `80`), so the server picks the default per mode: lossy stays at 80, and `extreme` now gets its per-codec default instead of a lossy-sized Q80 result. A quality you set is still sent. `OptimizeOptions#quality` returns `nil` when unset.
+- `lossless: true` used to be ignored by the server; it is now honoured (sent as `mode: "lossless"`). The SDK no longer sends `lossless` on the wire.
+
 ## [0.0.2] - 2026-08-22
 
 ### 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,27 +40,58 @@ 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,
   format: "avif",
   quality: 80,
-  max_width: 1920
+  max_width: 1920,
+  mode: SmallPict::Mode::LOSSY, # LOSSY (default) | EXTREME | LOSSLESS | AUTO; replaces the deprecated `lossless:`
+  folder: "products/shoes"      # optional, 1-3 segments; stored lower case, returned as result.folder
 )
 
 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
+
+```ruby
+result = SmallPict.optimize(
+  File.binread("hero-banner.png"),
+  format: "webp",
+  mode: SmallPict::Mode::EXTREME # no quality: the server picks it per format
+)
+```
+
 ### 2. Rails Initializer (`config/initializers/smallpict.rb`)
 
 ```ruby
@@ -69,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
 ```
 
@@ -106,8 +138,37 @@ puts "Plan: #{quota.plan}, Quota Used: #{quota.quota_percentage}%"
 # 2. Invalidate CDN cache for updated images
 purge = SmallPict.purge_cdn(["https://cdn.smallpict.app/opt/hero-banner.avif"])
 puts purge.message
+
+# 3. Purge one upload folder, or all of your files
+SmallPict.purge_cdn(purge_type: "folder", folder: "products/shoes")
+SmallPict.purge_cdn(purge_type: "all")
+# Folder purges are limited to 10 per hour and "all" to 2 per hour: one more raises
+# SmallPict::RateLimitError (429 purge_rate_limited), which the client does not retry.
+```
+
+### Capacity and upgrade links
+
+`get_quota` also returns the read-only `capacity` of the key's product. Members that do not apply to your plan are `nil`, and `capacity` itself is `nil` when the server could not read it or does not send it.
+
+```ruby
+cap = SmallPict.get_quota.capacity
+if cap
+  puts "Storage: #{cap.storage.used_bytes}/#{cap.storage.limit_bytes}" if cap.storage
+  puts "CDN status: #{cap.cdn.status}" if cap.cdn
+  puts "Account lapsed (#{cap.lapse.stage}), manage it at #{cap.manage_url}" if cap.lapse
+end
+
+begin
+  SmallPict.optimize("photo.jpg")
+rescue SmallPict::QuotaExceededError => e
+  puts "Add capacity at #{e.upgrade_url}" if e.upgrade_url
+rescue SmallPict::PermissionDeniedError => e
+  puts "Allowed modes: #{e.allowed_modes.join(', ')}" if e.allowed_modes
+end
 ```
 
+Capacity is bought only in the dashboard. `manage_url` and `upgrade_url` are plain strings to show your users; the SDK never opens or fetches them.
+
 ---
 
 ## 🧪 Testing
@@ -121,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
@@ -68,12 +98,18 @@ module SmallPict
       Models::QuotaResponse.new(res)
     end
 
-    def purge_cdn(urls = [], purge_type: "url")
+    # purge_type: "url" (default), "folder" (with `folder:`) or "all".
+    def purge_cdn(urls = [], purge_type: "url", folder: nil)
       url_list = urls.is_a?(Array) ? urls : [urls]
       payload = {
         purge_type: purge_type.to_s,
         urls:       url_list
       }
+      if payload[:purge_type] == "folder"
+        raise ValidationError, "folder is required for purge_type \"folder\"" if folder.nil? || folder.to_s.empty?
+
+        payload[:folder] = Folder.validate!(folder)
+      end
 
       res = request(:post, "/v1/purge", payload)
       Models::PurgeResponse.new(res)
@@ -82,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)
@@ -109,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
 
@@ -118,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
@@ -145,20 +238,19 @@ module SmallPict
           request_id = response.headers["x-request-id"]
           retry_after = response.headers["retry-after"]&.to_i
 
-          if status == 429 || (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
@@ -170,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
@@ -184,6 +276,11 @@ module SmallPict
       end
     end
 
+    # 429 purge_rate_limited is an hourly limit: retrying within seconds cannot succeed.
+    def hourly_purge_limit?(body)
+      body.is_a?(Hash) && body["error"].is_a?(Hash) && body["error"]["code"] == "purge_rate_limited"
+    end
+
     def parse_body(body_str)
       return {} if body_str.nil? || body_str.empty?
 
@@ -195,11 +292,13 @@ module SmallPict
     def handle_error_response(status, body, request_id, retry_after)
       message = "API request failed with HTTP #{status}"
       details = nil
+      code = "INTERNAL_ERROR"
 
       if body.is_a?(Hash)
         if body["error"].is_a?(Hash)
           message = body["error"]["message"] || message
           details = body["error"]["details"]
+          code = body["error"]["code"] if body["error"]["code"].is_a?(String)
         elsif body["error"].is_a?(String)
           message = body["error"]
         elsif body["message"].is_a?(String)
@@ -215,42 +314,60 @@ 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, status_code: status, request_id: request_id, details: details)
+        raise Error.new(message, code: code, status_code: status, request_id: request_id, details: details)
       end
     end
 
     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

@@ -2,7 +2,9 @@
 
 module SmallPict
   class Error < StandardError
-    attr_reader :code, :status_code, :request_id, :details
+    # upgrade_url: dashboard page where the missing capacity is added
+    # (details.upgrade_url), or nil. The SDK never opens or fetches it.
+    attr_reader :code, :status_code, :request_id, :details, :upgrade_url
 
     def initialize(message = "", code: "INTERNAL_ERROR", status_code: nil, request_id: nil, details: nil)
       @raw_message = self.class.sanitize(message)
@@ -10,6 +12,8 @@ module SmallPict
       @status_code = status_code
       @request_id  = request_id
       @details     = details
+      url          = details.is_a?(Hash) ? (details["upgrade_url"] || details[:upgrade_url]) : nil
+      @upgrade_url = url.is_a?(String) ? url : nil
       super(@raw_message)
     end
 
@@ -34,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
@@ -58,8 +63,13 @@ module SmallPict
   end
 
   class PermissionDeniedError < Error
+    # Modes the plan allows, from details.allowed_modes of 403 mode_not_in_plan; otherwise nil.
+    attr_reader :allowed_modes
+
     def initialize(message = "Permission denied for this resource", request_id: nil, details: nil)
       super(message, code: "FORBIDDEN", status_code: 403, request_id: request_id, details: details)
+      modes = details.is_a?(Hash) ? (details["allowed_modes"] || details[:allowed_modes]) : nil
+      @allowed_modes = modes.is_a?(Array) ? modes.grep(String) : nil
     end
   end
 

data/lib/smallpict/folder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SmallPict
+  # Light client-side check of an upload folder. The server is the authority
+  # (400 invalid_folder): it lower-cases the value and enforces the full format.
+  module Folder
+    MAX_SEGMENTS = 3
+
+    def self.validate!(folder)
+      segments = folder.to_s.split("/", -1)
+      if segments.empty? || segments.any?(&:empty?) || segments.include?("..") || segments.size > MAX_SEGMENTS
+        raise ValidationError, "Invalid folder #{folder.inspect}: use 1-#{MAX_SEGMENTS} non-empty segments separated by '/', without '..'."
+      end
+
+      folder.to_s
+    end
+  end
+end

data/lib/smallpict/mode.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SmallPict
+  # Compression modes for `optimize(mode: ...)`. The server checks the mode
+  # against the plan (403 mode_not_in_plan); the SDK does not.
+  module Mode
+    LOSSY    = "lossy"
+    EXTREME  = "extreme"
+    LOSSLESS = "lossless"
+    AUTO     = "auto" # the server picks the quality per image from a visual score (CMP-07)
+    ALL      = [LOSSY, EXTREME, LOSSLESS, AUTO].freeze
+  end
+end

data/lib/smallpict/models/capacity.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SmallPict
+  module Models
+    CapacityStorage = Data.define(:limit_bytes, :used_bytes, :base_bytes, :addon_blocks)
+    CapacityCdn     = Data.define(:limit_bytes, :used_bytes, :status)
+    CapacityBooster = Data.define(:active, :wp_quota_bytes, :api_transforms, :cdn_bytes, :next_expiry)
+    CapacityExpiry  = Data.define(:kind, :units, :expires_at)
+    CapacityLapse   = Data.define(:stage, :delete_after)
+
+    # Read-only capacity of the key's product from GET /v1/quota. A member that
+    # does not apply to the product or plan is nil. manage_url is a plain string:
+    # the SDK never opens or fetches it; capacity is bought only in the dashboard.
+    Capacity = Data.define(:period_end, :storage, :cdn, :booster, :lapse, :manage_url) do
+      def self.from_hash(data)
+        return nil unless data.is_a?(Hash)
+
+        s  = get(data, :storage)
+        cd = get(data, :cdn)
+        b  = get(data, :booster) || {}
+        e  = get(b, :next_expiry)
+        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,
+            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))
+          ),
+          lapse:      l && CapacityLapse.new(stage: get(l, :stage), delete_after: get(l, :delete_after)),
+          manage_url: get(data, :manage_url)
+        )
+      end
+
+      # String keys from JSON, symbol keys from callers; keeps false and nil as sent.
+      def self.get(hash, key)
+        hash.is_a?(Hash) ? hash.fetch(key.to_s) { hash[key] } : nil
+      end
+    end
+  end
+end

data/lib/smallpict/models/job_status_result.rb

@@ -4,7 +4,7 @@ module SmallPict
   module Models
     class JobStatusResult
       attr_reader :job_id, :status, :url, :format, :bytes_saved,
-                  :error, :created_at, :updated_at
+                  :error, :created_at, :updated_at, :mode_applied, :quality_applied, :folder
 
       def initialize(attributes = {})
         @job_id      = attributes[:job_id] || attributes["job_id"]
@@ -15,6 +15,10 @@ module SmallPict
         @error       = attributes[:error] || attributes["error"]
         @created_at  = attributes[:created_at] || attributes["created_at"]
         @updated_at  = attributes[:updated_at] || attributes["updated_at"]
+        # Reported by the server; nil for jobs created before modes existed.
+        @mode_applied    = attributes[:mode_applied] || attributes["mode_applied"]
+        @quality_applied = attributes[:quality_applied] || attributes["quality_applied"]
+        @folder          = attributes[:folder] || attributes["folder"]
       end
     end
   end

data/lib/smallpict/models/optimize_options.rb

@@ -3,17 +3,22 @@
 module SmallPict
   module Models
     class OptimizeOptions
-      attr_reader :format, :quality, :max_width, :max_height, :max_dimension, :fit,
-                  :lossless, :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.
+      # folder:   optional upload folder, e.g. "products/shoes"; the server lower-cases it.
+      # lossless: deprecated, use `mode: SmallPict::Mode::LOSSLESS`; removal not before the next major.
       def initialize(
         format: "auto",
-        quality: 80,
+        quality: nil,
         max_width: nil,
         max_height: nil,
         max_dimension: nil,
-        fit: "cover",
-        lossless: false,
+        mode: nil,
+        lossless: nil,
+        folder: nil,
         strip_metadata: true,
         filename: nil,
         mime_type: nil,
@@ -25,27 +30,42 @@ 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,
-          lossless: @lossless,
+          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
+
+      private
+
+      # `lossless:` is deprecated: map it to `mode:` and never send it on the wire.
+      def resolve_mode(mode, lossless)
+        mode = mode&.to_s
+        unless lossless.nil?
+          Kernel.warn("SmallPict: `lossless:` is deprecated, use `mode: SmallPict::Mode::LOSSLESS`.",
+                      category: :deprecated)
+        end
+        return mode unless lossless == true
+        return Mode::LOSSLESS if mode.nil? || mode == Mode::LOSSLESS
+
+        raise ValidationError, "`lossless: true` contradicts `mode: #{mode.inspect}`; set only `mode:`."
+      end
     end
   end
 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
+                  :data, :folder, :mode_applied, :quality_applied
 
       def initialize(attributes = {})
         @job_id             = attributes[:job_id] || attributes["job_id"] || "sync"
@@ -15,9 +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/models/quota_response.rb

@@ -5,7 +5,7 @@ module SmallPict
     class QuotaResponse
       attr_reader :plan, :bytes_used, :quota_limit, :quota_percentage,
                   :cdn_egress_used_bytes, :cdn_egress_quota_bytes,
-                  :active_keys_count, :active_sites_count
+                  :active_keys_count, :active_sites_count, :capacity
 
       def initialize(attributes = {})
         @plan                   = attributes[:plan] || attributes["plan"] || "free"
@@ -16,6 +16,8 @@ module SmallPict
         @cdn_egress_quota_bytes = attributes[:cdn_egress_quota_bytes] || attributes["cdn_egress_quota_bytes"]
         @active_keys_count      = attributes[:active_keys_count] || attributes["active_keys_count"]
         @active_sites_count     = attributes[:active_sites_count] || attributes["active_sites_count"]
+        # nil when the server could not read capacity, and from older servers that omit it.
+        @capacity               = Capacity.from_hash(attributes[:capacity] || attributes["capacity"])
       end
 
       private

data/lib/smallpict/version.rb

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

data/lib/smallpict.rb

@@ -4,13 +4,15 @@ require_relative "smallpict/version"
 require_relative "smallpict/configuration"
 require_relative "smallpict/crypto"
 require_relative "smallpict/errors"
+require_relative "smallpict/mode"
+require_relative "smallpict/folder"
 require_relative "smallpict/models/optimize_options"
 require_relative "smallpict/models/optimize_result"
+require_relative "smallpict/models/capacity"
 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
@@ -20,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!
@@ -39,8 +42,8 @@ module SmallPict
       client.get_quota
     end
 
-    def purge_cdn(urls = [], purge_type: "url")
-      client.purge_cdn(urls, purge_type: purge_type)
+    def purge_cdn(urls = [], purge_type: "url", folder: nil)
+      client.purge_cdn(urls, purge_type: purge_type, folder: folder)
     end
 
     def validate_key

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smallpict
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.8
 platform: ruby
 authors:
 - SmallPict Engineering
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-13 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,11 +79,13 @@ 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
 - lib/smallpict/errors.rb
+- lib/smallpict/folder.rb
+- lib/smallpict/mode.rb
+- lib/smallpict/models/capacity.rb
 - lib/smallpict/models/job_status_result.rb
 - lib/smallpict/models/optimize_options.rb
 - lib/smallpict/models/optimize_result.rb
@@ -111,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