smallpict 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 706bf93d2afc08096d18ce827d3aaa4fc90fad68e5da7da9a38ffd242a9050cd
+  data.tar.gz: bc5bef9512ab160df50f785d9989d7e53d92520d064d644849c81accc5a7b374
+SHA512:
+  metadata.gz: 61276a0d74ab07c795ebfc666ea6cd0b4604c763c26226eba8b75833e31b11c6f898bff0e7ff3c4d86254366bf3c4050a4f78552e737422620dc622cb023792d
+  data.tar.gz: 858e4a55bc5a820198f19562e0827c7ea411c825acc9dff62db7230a3f138d4bd3dd0be99eba9b27686ead4a5357f8f11207c560d329aa6be6b246760bc43e15

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+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).
+
+## [1.0.0] - 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`).
+- 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.
+- Custom exception hierarchy with automatic secret redaction in `to_s` and `inspect`.
+- Optional `:passthrough` fallback mode on quota limit exhaustion.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SmallPict Engineering <support@smallpict.app>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,122 @@
+# 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.
+
+[![Gem Version](https://badge.fury.io/rb/smallpict.svg)](https://badge.fury.io/rb/smallpict)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D3.0-ruby.svg)](https://www.ruby-lang.org)
+
+---
+
+## ⚡ 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.
+- **✨ 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.
+
+---
+
+## 📥 Installation
+
+Add to your application's `Gemfile`:
+
+```ruby
+gem "smallpict", "~> 1.0"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Global Block Configuration & Standalone Ruby
+
+```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
+end
+
+image_data = File.binread("hero-banner.png")
+
+result = SmallPict.optimize(
+  image_data,
+  format: "avif",
+  quality: 80,
+  max_width: 1920
+)
+
+puts "Optimized CDN URL: #{result.url}"
+puts "Saved: #{result.savings_percentage}% (#{result.bytes_saved} bytes)"
+```
+
+### 2. Rails Initializer (`config/initializers/smallpict.rb`)
+
+```ruby
+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
+end
+```
+
+### 3. Rails Controller Example
+
+```ruby
+class MediaController < ApplicationController
+  def create
+    uploaded_file = params[:image]
+
+    result = SmallPict.optimize(
+      uploaded_file.tempfile,
+      format: "auto",
+      quality: 85
+    )
+
+    render json: {
+      url: result.url,
+      format: result.format,
+      savings: "#{result.savings_percentage}%"
+    }
+  end
+end
+```
+
+---
+
+## 📊 Account Quota & Edge CDN Purge
+
+```ruby
+# 1. Check real-time quota usage
+quota = SmallPict.get_quota
+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
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+```
+
+---
+
+## 📄 License
+
+MIT © [SmallPict Engineering](https://smallpict.app)

data/SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+Please report vulnerabilities directly to [security@smallpict.app](mailto:security@smallpict.app).
+
+Do not log raw API keys, signatures, or full image payloads.

data/lib/smallpict/active_storage/service.rb

@@ -0,0 +1,29 @@
+# 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

data/lib/smallpict/client.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "securerandom"
+
+module SmallPict
+  class Client
+    attr_reader :api_key, :secret_key, :base_url, :timeout, :max_retries, :fallback_mode
+
+    def initialize(
+      api_key: nil,
+      secret_key: nil,
+      base_url: nil,
+      timeout: nil,
+      max_retries: nil,
+      fallback_mode: 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("/")
+      @timeout       = (timeout || config.timeout).to_i
+      @max_retries   = (max_retries || config.max_retries).to_i
+      @fallback_mode = (fallback_mode || config.fallback_mode).to_sym
+
+      validate_configuration!
+    end
+
+    def optimize(source, options = {})
+      opts = options.is_a?(Models::OptimizeOptions) ? options : Models::OptimizeOptions.new(**options)
+      resolved = resolve_source(source, opts)
+
+      payload = {
+        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)
+      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
+      end
+    end
+
+    def get_quota
+      res = request(:get, "/v1/quota")
+      Models::QuotaResponse.new(res)
+    end
+
+    def purge_cdn(urls = [], purge_type: "url")
+      url_list = urls.is_a?(Array) ? urls : [urls]
+      payload = {
+        purge_type: purge_type.to_s,
+        urls:       url_list
+      }
+
+      res = request(:post, "/v1/purge", payload)
+      Models::PurgeResponse.new(res)
+    end
+
+    def validate_key
+      get_quota
+      true
+    rescue StandardError
+      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}")
+      Models::JobStatusResult.new(res)
+    end
+
+    private
+
+    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
+    end
+
+    def request(method, path, body = nil, idempotency_key: nil)
+      clean_path = path.start_with?("/") ? path : "/#{path}"
+      clean_path = "/v1#{clean_path}" unless clean_path.start_with?("/v1/") || clean_path.start_with?("/v2/")
+
+      url = "#{@base_url}#{clean_path}"
+      body_str = body ? JSON.generate(body) : nil
+      body_hash = body_str ? Crypto.sha256_hex(body_str) : Crypto::EMPTY_SHA256
+
+      attempt = 0
+      base_delay = 0.25 # 250ms
+
+      while attempt <= @max_retries
+        attempt += 1
+        begin
+          timestamp = Time.now.to_i.to_s
+
+          headers = {
+            "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
+
+          if %i[post patch delete].include?(method.to_s.downcase.to_sym)
+            headers["Idempotency-Key"] = idempotency_key || SecureRandom.uuid
+          end
+
+          response = connection.send(method.to_s.downcase.to_sym, url) do |req|
+            req.headers = headers
+            req.body = body_str if body_str
+          end
+
+          status = response.status
+          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 < 200 || status >= 300
+            handle_error_response(status, parsed, request_id, retry_after)
+          end
+
+          return parsed
+        rescue Faraday::TimeoutError => e
+          raise TimeoutError, e.message
+        rescue Faraday::ConnectionFailed => e
+          if attempt <= @max_retries
+            sleep(base_delay * (2**(attempt - 1)))
+            next
+          end
+          raise NetworkError, e.message
+        end
+      end
+
+      raise TimeoutError, "Request failed after maximum retry attempts"
+    end
+
+    def connection
+      @connection ||= Faraday.new do |f|
+        f.options.timeout = @timeout
+        f.options.open_timeout = @timeout
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def parse_body(body_str)
+      return {} if body_str.nil? || body_str.empty?
+
+      JSON.parse(body_str)
+    rescue JSON::ParserError
+      { "raw" => body_str }
+    end
+
+    def handle_error_response(status, body, request_id, retry_after)
+      message = "API request failed with HTTP #{status}"
+      details = nil
+
+      if body.is_a?(Hash)
+        if body["error"].is_a?(Hash)
+          message = body["error"]["message"] || message
+          details = body["error"]["details"]
+        elsif body["error"].is_a?(String)
+          message = body["error"]
+        elsif body["message"].is_a?(String)
+          message = body["message"]
+        end
+      end
+
+      case status
+      when 400 then raise ValidationError.new(message, request_id: request_id, details: details)
+      when 401 then raise AuthenticationError.new(message, request_id: request_id, details: details)
+      when 402 then raise QuotaExceededError.new(message, request_id: request_id, details: details)
+      when 403 then raise PermissionDeniedError.new(message, request_id: request_id, details: details)
+      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 Error.new(message, 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 || "image/jpeg"
+      filesize = 0
+      bytes = nil
+
+      if source.respond_to?(:read)
+        bytes = source.read
+        filesize = bytes.bytesize
+        filename = File.basename(source.path) if source.respond_to?(:path) && options.filename.nil?
+      elsif source.is_a?(String)
+        if File.exist?(source) && 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
+      end
+
+      {
+        filename:  filename,
+        mime_type: mime_type,
+        filesize:  filesize,
+        bytes:     bytes
+      }
+    end
+  end
+end

data/lib/smallpict/configuration.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SmallPict
+  class Configuration
+    attr_accessor :api_key, :secret_key, :base_url, :timeout, :max_retries, :fallback_mode
+
+    def initialize
+      @api_key       = ENV["SMALLPICT_API_KEY"]
+      @secret_key    = ENV["SMALLPICT_SECRET_KEY"]
+      @base_url      = (ENV["SMALLPICT_BASE_URL"] || "https://api.smallpict.app").chomp("/")
+      @timeout       = 30
+      @max_retries   = 3
+      @fallback_mode = :throw
+    end
+  end
+end

data/lib/smallpict/crypto.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module SmallPict
+  module Crypto
+    EMPTY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+
+    module_function
+
+    def sha256_hex(data)
+      return EMPTY_SHA256 if data.nil? || data.empty?
+
+      OpenSSL::Digest::SHA256.hexdigest(data)
+    end
+
+    def hmac_sha256_hex(secret_key, string_to_sign)
+      OpenSSL::HMAC.hexdigest("SHA256", secret_key.to_s, string_to_sign.to_s)
+    end
+
+    def build_string_to_sign(method, path, timestamp, body_hash)
+      clean_path = path.start_with?("/") ? path : "/#{path}"
+      "#{method.to_s.upcase}\n#{clean_path}\n#{timestamp}\n#{body_hash}"
+    end
+  end
+end

data/lib/smallpict/errors.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module SmallPict
+  class Error < StandardError
+    attr_reader :code, :status_code, :request_id, :details
+
+    def initialize(message = "", code: "INTERNAL_ERROR", status_code: nil, request_id: nil, details: nil)
+      @raw_message = self.class.sanitize(message)
+      @code        = code
+      @status_code = status_code
+      @request_id  = request_id
+      @details     = details
+      super(@raw_message)
+    end
+
+    def to_s
+      status_str = @status_code ? " HTTP #{@status_code}" : ""
+      req_str = @request_id ? " (Request ID: #{@request_id})" : ""
+      "[#{@code}#{status_str}]: #{@raw_message}#{req_str}"
+    end
+
+    def inspect
+      "#<#{self.class.name} code=#{@code.inspect} status_code=#{@status_code.inspect} message=#{@raw_message.inspect}>"
+    end
+
+    def self.sanitize(msg)
+      return "" if msg.nil? || msg.empty?
+
+      sanitized = msg.to_s.gsub(/sp_(live|test|sdk|wp)_[a-zA-Z0-9_-]{10,}/) do |match|
+        if match.length > 14
+          "#{match[0..9]}...#{match[-4..]}"
+        else
+          "#{match[0..5]}..."
+        end
+      end
+
+      sanitized = sanitized.gsub(/(sec|secret)_[a-zA-Z0-9_-]{8,}/i, "***REDACTED***")
+      sanitized.gsub(/Bearer\s+[a-zA-Z0-9._-]+/i, "Bearer ***REDACTED***")
+    end
+  end
+
+  class ValidationError < Error
+    def initialize(message = "Validation failed", request_id: nil, details: nil)
+      super(message, code: "VALIDATION_FAILED", status_code: 400, request_id: request_id, details: details)
+    end
+  end
+
+  class AuthenticationError < Error
+    def initialize(message = "Authentication failed", request_id: nil, details: nil)
+      super(message, code: "UNAUTHORIZED", status_code: 401, request_id: request_id, details: details)
+    end
+  end
+
+  class QuotaExceededError < Error
+    def initialize(message = "Storage or optimization quota exceeded", request_id: nil, details: nil)
+      super(message, code: "QUOTA_EXCEEDED", status_code: 402, request_id: request_id, details: details)
+    end
+  end
+
+  class PermissionDeniedError < Error
+    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)
+    end
+  end
+
+  class NotFoundError < Error
+    def initialize(message = "Resource or job ID not found", request_id: nil, details: nil)
+      super(message, code: "NOT_FOUND", status_code: 404, request_id: request_id, details: details)
+    end
+  end
+
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = "Rate limit exceeded", retry_after: nil, request_id: nil, details: nil)
+      super(message, code: "RATE_LIMIT_EXCEEDED", status_code: 429, request_id: request_id, details: details)
+      @retry_after = retry_after
+    end
+  end
+
+  class ServerError < Error
+    def initialize(message = "Internal server error occurred", status_code: 500, request_id: nil, details: nil)
+      super(message, code: "INTERNAL_ERROR", status_code: status_code, request_id: request_id, details: details)
+    end
+  end
+
+  class TimeoutError < Error
+    def initialize(message = "Request timed out after maximum duration", request_id: nil, details: nil)
+      super(message, code: "TIMEOUT_ERROR", status_code: 408, request_id: request_id, details: details)
+    end
+  end
+
+  class NetworkError < Error
+    def initialize(message = "Network communication error", details: nil)
+      super(message, code: "NETWORK_ERROR", status_code: nil, request_id: nil, details: details)
+    end
+  end
+end

data/lib/smallpict/models/job_status_result.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SmallPict
+  module Models
+    class JobStatusResult
+      attr_reader :job_id, :status, :url, :format, :bytes_saved,
+                  :error, :created_at, :updated_at
+
+      def initialize(attributes = {})
+        @job_id      = attributes[:job_id] || attributes["job_id"]
+        @status      = attributes[:status] || attributes["status"] || "processing"
+        @url         = attributes[:url] || attributes["url"]
+        @format      = attributes[:format] || attributes["format"]
+        @bytes_saved = attributes[:bytes_saved] || attributes["bytes_saved"]
+        @error       = attributes[:error] || attributes["error"]
+        @created_at  = attributes[:created_at] || attributes["created_at"]
+        @updated_at  = attributes[:updated_at] || attributes["updated_at"]
+      end
+    end
+  end
+end

data/lib/smallpict/models/optimize_options.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module SmallPict
+  module Models
+    class OptimizeOptions
+      attr_reader :format, :quality, :max_width, :max_height, :fit,
+                  :lossless, :strip_metadata, :filename, :mime_type, :idempotency_key
+
+      def initialize(
+        format: "auto",
+        quality: 80,
+        max_width: nil,
+        max_height: nil,
+        fit: "cover",
+        lossless: false,
+        strip_metadata: true,
+        filename: nil,
+        mime_type: nil,
+        idempotency_key: nil
+      )
+        @format          = format.to_s
+        @quality         = quality&.clamp(1, 100)
+        @max_width       = max_width
+        @max_height      = max_height
+        @fit             = fit.to_s
+        @lossless        = lossless
+        @strip_metadata  = strip_metadata
+        @filename        = filename
+        @mime_type       = mime_type
+        @idempotency_key = idempotency_key
+      end
+
+      def to_h
+        {
+          format: @format,
+          quality: @quality,
+          max_width: @max_width,
+          max_height: @max_height,
+          fit: @fit,
+          lossless: @lossless,
+          strip_metadata: @strip_metadata
+        }.compact
+      end
+    end
+  end
+end

data/lib/smallpict/models/optimize_result.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SmallPict
+  module Models
+    class OptimizeResult
+      attr_reader :job_id, :status, :url, :format, :original_size,
+                  :compressed_size, :bytes_saved, :savings_percentage,
+                  :upload_url, :data
+
+      def initialize(attributes = {})
+        @job_id             = attributes[:job_id] || attributes["job_id"] || "sync"
+        @status             = attributes[:status] || attributes["status"] || "completed"
+        @url                = attributes[:url] || attributes["url"] || ""
+        @format             = attributes[:format] || attributes["format"] || "auto"
+        @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"]
+        @data               = attributes[:data]
+      end
+
+      private
+
+      def calculate_savings_percentage
+        return 0.0 if @original_size.zero?
+
+        ((@bytes_saved.to_f / @original_size) * 100.0).round(2)
+      end
+    end
+  end
+end

data/lib/smallpict/models/purge_response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SmallPict
+  module Models
+    class PurgeResponse
+      attr_reader :message
+
+      def initialize(attributes = {})
+        @message = attributes[:message] || attributes["message"] || "Purge accepted"
+      end
+    end
+  end
+end

data/lib/smallpict/models/quota_response.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SmallPict
+  module Models
+    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
+
+      def initialize(attributes = {})
+        @plan                   = attributes[:plan] || attributes["plan"] || "free"
+        @bytes_used             = (attributes[:bytes_used] || attributes["bytes_used"] || 0).to_i
+        @quota_limit            = (attributes[:quota_limit] || attributes["quota_limit"] || 0).to_i
+        @quota_percentage       = (attributes[:quota_percentage] || attributes["quota_percentage"] || calculate_percentage).to_f.round(2)
+        @cdn_egress_used_bytes  = attributes[:cdn_egress_used_bytes] || attributes["cdn_egress_used_bytes"]
+        @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"]
+      end
+
+      private
+
+      def calculate_percentage
+        return 0.0 if @quota_limit.zero?
+
+        ((@bytes_used.to_f / @quota_limit) * 100.0).round(2)
+      end
+    end
+  end
+end

data/lib/smallpict/version.rb

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

data/lib/smallpict.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "smallpict/version"
+require_relative "smallpict/configuration"
+require_relative "smallpict/crypto"
+require_relative "smallpict/errors"
+require_relative "smallpict/models/optimize_options"
+require_relative "smallpict/models/optimize_result"
+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
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      @default_client = nil
+    end
+
+    def client
+      @default_client ||= Client.new
+    end
+
+    def optimize(source, options = {})
+      client.optimize(source, options)
+    end
+
+    def get_quota
+      client.get_quota
+    end
+
+    def purge_cdn(urls = [], purge_type: "url")
+      client.purge_cdn(urls, purge_type: purge_type)
+    end
+
+    def validate_key
+      client.validate_key
+    end
+
+    def get_job_status(job_id)
+      client.get_job_status(job_id)
+    end
+  end
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: smallpict
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- SmallPict Engineering
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  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: 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
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+description: High-performance next-gen image transcoding (AVIF, WebP), smart compression,
+  Edge CDN delivery, and Rails ActiveStorage integration.
+email:
+- support@smallpict.app
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- 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/models/job_status_result.rb
+- lib/smallpict/models/optimize_options.rb
+- lib/smallpict/models/optimize_result.rb
+- lib/smallpict/models/purge_response.rb
+- lib/smallpict/models/quota_response.rb
+- lib/smallpict/version.rb
+homepage: https://smallpict.app
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://smallpict.app
+  source_code_uri: https://github.com/tuxnoob/smallpict-ruby
+  changelog_uri: https://github.com/tuxnoob/smallpict-ruby/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for SmallPict Image Optimization API
+test_files: []