smallpict 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c32e00d3a73e92ac5781a8e3d61cb90d6e81a62880d45318caaeaa87e29b39f
-  data.tar.gz: 1aad44c760c834fc47b7bfa4c2513ec498a0c57c3830bd7317c82b5a9ed99391
+  metadata.gz: 4c99d1d9f8d685017396f2c3e94e7715fbed0aa6a2e2c2315bf7dca11a1ec336
+  data.tar.gz: d87ea5708336c3600cc10d2e7bd11c219f0f355014eedeab0041accb30fc57fa
 SHA512:
-  metadata.gz: 715d75a35e3dd824d2a9b98ef720ff4a8f9a6dbf79a92076517aae7ea4da5f8d8edafd8d3999b402620a846b06a56ac892e85033117748c73b932e886a63e279
-  data.tar.gz: 6eeb642b7b22f49d7c90d50188f5afb1f4c632b61819d592a483cb7d199505bfcbd6916e3e198d67c138715e6c5513dc0f140b992f1a24b3f2153c94224c929a
+  metadata.gz: 0ae9beee1528a5242fa7bede52a15186be036bce30f85456c03a6210bf5a6eaa7e533d73f54d3bd0fe54d1259e87286080cf1c79f04fdc489f8d72dd8b1b6bec
+  data.tar.gz: b7166c544f39637266ee9633a7cc7cdc4bf6912e89657da7fd3707744c3186411707499614a3c79047ec66e4a7c07c6cb9857c52a1a6d1fe171ce4af0dd6ddf6

data/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.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

data/README.md

@@ -55,13 +55,27 @@ 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)"
 ```
 
+`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
@@ -106,8 +120,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

data/lib/smallpict/client.rb

@@ -68,12 +68,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)
@@ -145,7 +151,7 @@ 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 (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?
@@ -184,6 +190,12 @@ module SmallPict
       end
     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)
+      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 +207,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)
@@ -219,7 +233,7 @@ module SmallPict
           raise ServerError.new(message, status_code: status, request_id: request_id, details: details)
         end
 
-        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
 

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
 
@@ -58,8 +62,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

@@ -4,16 +4,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
+                  :mode, :lossless, :folder, :strip_metadata, :filename, :mime_type, :content_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,
@@ -27,6 +33,8 @@ module SmallPict
         @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
@@ -42,10 +50,26 @@ module SmallPict
           max_height: @max_height,
           max_dimension: @max_dimension,
           fit: @fit,
-          lossless: @lossless,
+          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
+                  :upload_url, :data, :folder
 
       def initialize(attributes = {})
         @job_id             = attributes[:job_id] || attributes["job_id"] || "sync"
@@ -18,6 +18,8 @@ module SmallPict
         @savings_percentage = (attributes[:savings_percentage] || attributes["savings_percentage"] || calculate_savings_percentage).to_f.round(2)
         @upload_url         = attributes[:upload_url] || attributes["upload_url"]
         @data               = attributes[:data]
+        # Normalized (lower case) by the server; nil without a folder.
+        @folder             = attributes[:folder] || attributes["folder"]
       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.7"
 end

data/lib/smallpict.rb

@@ -4,8 +4,11 @@ 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"
@@ -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.7
 platform: ruby
 authors:
 - SmallPict Engineering
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-13 00:00:00.000000000 Z
+date: 2026-11-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -98,6 +98,9 @@ files:
 - 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