Project

smallpict

0.0
The project is in a healthy, maintained state
smallpicttuxnoob/smallpict-rubyHomepageDocumentationSource CodeBug Tracker
High-performance next-gen image transcoding (AVIF, WebP), smart compression, Edge CDN delivery, and Rails ActiveStorage integration.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
2,896
Stars
0
Forks
0
Watchers
0
 Releases
Current version
0.0.2
Total releases
2
First release
2026-09-01
Latest release
2026-09-06
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2026-09-06
Reverse Dependencies
0

 Dependencies

Development

rspec
~> 3.12
rubocop
~> 1.50
webmock
~> 3.18

Runtime

faraday
>= 2.0
faraday-retry
>= 2.0
 Project Readme

SmallPict Ruby SDK

Official Ruby gem for the SmallPict Image Optimization API — high-performance next-gen image transcoding (AVIF, WebP), smart compression, Edge CDN delivery, cache purging, and Rails ActiveStorage support.

Gem Version License: MIT Ruby Version

⚡ 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:

gem "smallpict", "~> 1.0"

And then execute:

bundle install

🚀 Quick Start

1. Global Block Configuration & Standalone 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)

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

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

# 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

bundle exec rspec
bundle exec rubocop

📄 License

MIT © SmallPict Engineering