comprestack 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a6e40abe6461ca88dbd5e6360f0aa988d7cd6de70e34e40a904e24835d6117aa
+  data.tar.gz: bbc09479df08c1a371f10e5fe2fa22742a8d746ab32280187b0ff652e22d8520
+SHA512:
+  metadata.gz: b76f731b7b0e69401f1f0e4c4e2edfb9219fa885865a085bf37a743caafa225daced91d90fff0a8929e37407ac7637a89077e17484a25f794a0ddaa051144e70
+  data.tar.gz: cae34687b21dba715c78272d28165ed287248666ca61c3cd8f3fba0ea9ff7dd34ff8b0e7e0ff004f2bad04ca285e93ecdf83e573aeb165b37f396128ca4ce19a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Comprestack
+
+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,85 @@
+# comprestack (Ruby)
+
+Official Ruby SDK for the [Comprestack](https://www.comprestack.com) image optimization API.
+
+Same REST surface as the [API docs](https://www.comprestack.com/docs) and [OpenAPI](https://api.comprestack.com/openapi.yaml). Fits Rails, Sidekiq, and Shopify apps — keep the key on the server.
+
+---
+
+## Install
+
+```bash
+gem install comprestack
+# or Gemfile:
+# gem "comprestack"
+```
+
+**Requirements:** Ruby 3.1+.
+
+```bash
+export COMPRESTACK_API_KEY=csk_live_…
+```
+
+---
+
+## Quick start
+
+```ruby
+require "comprestack"
+
+client = Comprestack::Client.new  # reads COMPRESTACK_API_KEY
+
+job = client.convert("photo.jpg", "webp", quality: "balanced", maxWidth: 1600)
+File.binwrite("photo.webp", client.download(job))
+puts "#{job.dig("usage", "remaining")} images left this period"
+```
+
+Compress without changing format:
+
+```ruby
+job = client.compress(["hero.png"], quality: "high")
+```
+
+In Rails, put the key in credentials / ENV and call from a job or controller — never from the browser.
+
+---
+
+## What you can do
+
+| Goal | Method |
+|------|--------|
+| Shrink, keep format | `compress(files, **options)` |
+| Change format + shrink | `convert(files, format, **options)` |
+| Re-fetch job metadata | `get_job(id)` |
+| Download ZIP / result | `download(job)` or `download(url)` |
+| Download one file in a batch | `download_file(job_id, index)` |
+| Check quota | `usage` |
+| White-label billing report | `room_report(room_id)` |
+
+Files may be a path, `IO`, or `{ data:, filename: }`. Pricing and quotas are enforced by the API.
+
+---
+
+## Options
+
+| Field | Description |
+|--------|-------------|
+| `quality` | `"balanced"`, `"high"`, `"smallest"`, or `1–100` (paid) |
+| `format` | **convert only** |
+| `maxWidth` / `maxHeight` | Downscale to fit |
+| `target_kb` | Size hint (paid) |
+| `lossless` / `keep_metadata` | Encoding flags |
+
+The client retries HTTP 429 / 503 (honours `Retry-After`). Failed calls raise `Comprestack::Error` (`status`, `code`, `retry_after`).
+
+---
+
+## Links
+
+- [API reference](https://www.comprestack.com/docs)
+- [OpenAPI 3.1](https://api.comprestack.com/openapi.yaml)
+- [Dashboard — API keys](https://www.comprestack.com/dashboard?section=api)
+
+## License
+
+MIT © Comprestack

data/lib/comprestack/client.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+require "net/http"
+require "pathname"
+require "securerandom"
+require "stringio"
+require "uri"
+
+module Comprestack
+  # Synchronous client for the Comprestack REST API.
+  # Keep API keys on the server (Rails jobs, Shopify apps, workers).
+  class Client
+    USER_AGENT = "comprestack-ruby/#{VERSION}"
+
+    attr_reader :api_key, :base_url, :origin, :timeout, :max_retries
+
+    def initialize(api_key: nil, base_url: DEFAULT_API_BASE, origin: DEFAULT_ORIGIN,
+                   timeout: 300, max_retries: 2, headers: {}, on_progress: nil, http_handler: nil)
+      key = api_key.to_s.strip
+      key = ENV["COMPRESTACK_API_KEY"].to_s.strip if key.empty?
+      key = ENV["COMPRESS_API_KEY"].to_s.strip if key.empty?
+      raise ArgumentError, "apiKey is required" if key.empty?
+
+      @api_key = key
+      @base_url = base_url.to_s.sub(%r{/+\z}, "")
+      @origin = origin.to_s.sub(%r{/+\z}, "")
+      @timeout = timeout.to_f
+      @max_retries = max_retries.to_i
+      @extra_headers = headers || {}
+      @on_progress = on_progress
+      @http_handler = http_handler
+    end
+
+    def compress(files, **options)
+      multipart("/compress", files, options)
+    end
+
+    def convert(files, format, **options)
+      raise ArgumentError, "format is required" if format.to_s.strip.empty?
+
+      multipart("/convert", files, options, extra: { "format" => format.to_s })
+    end
+
+    def get_job(job_id)
+      request_json("GET", "/jobs/#{CGI.escape(job_id.to_s)}")
+    end
+
+    def usage
+      request_json("GET", "/usage", timeout: [@timeout, 30].min)
+    end
+
+    def room_report(room_id)
+      request_json("GET", "/rooms/#{CGI.escape(room_id.to_s)}/report", timeout: [@timeout, 30].min)
+    end
+
+    def resolve_download_url(download_url)
+      return download_url if download_url.to_s.match?(%r{\Ahttps?://}i)
+
+      "#{@origin}/#{download_url.to_s.sub(%r{\A/+}, "")}"
+    end
+
+    def download(job_or_url)
+      url =
+        if job_or_url.is_a?(String)
+          resolve_download_url(job_or_url)
+        else
+          download_url = job_or_url.is_a?(Hash) ? (job_or_url["download_url"] || job_or_url[:download_url]) : nil
+          raise ArgumentError, "job must include a download_url string" unless download_url.is_a?(String)
+
+          resolve_download_url(download_url)
+        end
+
+      fetch_binary(url, "/jobs/.../download")
+    end
+
+    def download_file(job_id, index)
+      raise ArgumentError, "index must be a non-negative integer" unless index.is_a?(Integer) && index >= 0
+
+      path = "/jobs/#{CGI.escape(job_id.to_s)}/files/#{index}"
+      fetch_binary("#{@base_url}#{path}", path)
+    end
+
+    private
+
+    def multipart(path, files, options, extra: {})
+      list = files.is_a?(Array) ? files : [files]
+      raise ArgumentError, "at least one file is required" if list.empty?
+
+      max_attempts = @max_retries + 1
+      last_error = nil
+
+      (1..max_attempts).each do |attempt|
+        emit(phase: attempt == 1 ? "start" : "retry", path: path, attempt: attempt,
+             max_attempts: max_attempts, retry_after_sec: last_error&.retry_after)
+
+        boundary = "----Comprestack#{SecureRandom.hex(12)}"
+        body = build_multipart_body(list, options, extra, boundary)
+        begin
+          response = raw_request("POST", "#{@base_url}#{path}", body, {
+            "Content-Type" => "multipart/form-data; boundary=#{boundary}"
+          }, @timeout)
+        rescue Error => e
+          last_error = e
+          raise e unless attempt < max_attempts && e.retryable?
+
+          sleep retry_delay_sec(e.retry_after, attempt)
+          next
+        end
+
+        emit(phase: "complete", path: path, attempt: attempt, max_attempts: max_attempts)
+        return decode_json(response[:body])
+      end
+
+      raise last_error || Error.new("Request failed after retries", status: 503, code: "busy")
+    end
+
+    def build_multipart_body(files, options, extra, boundary)
+      parts = String.new(encoding: Encoding::BINARY)
+      files.each_with_index do |file, index|
+        filename, contents, content_type = normalize_upload(file, index)
+        parts << "--#{boundary}\r\n"
+        parts << "Content-Disposition: form-data; name=\"files[]\"; filename=\"#{escape_filename(filename)}\"\r\n"
+        parts << "Content-Type: #{content_type}\r\n\r\n"
+        parts << contents
+        parts << "\r\n"
+      end
+      option_fields(options).merge(stringify_keys(extra)).each do |name, value|
+        parts << "--#{boundary}\r\n"
+        parts << "Content-Disposition: form-data; name=\"#{name}\"\r\n\r\n"
+        parts << value.to_s
+        parts << "\r\n"
+      end
+      parts << "--#{boundary}--\r\n"
+      parts
+    end
+
+    def option_fields(options)
+      opts = stringify_keys(options)
+      fields = {}
+      fields["quality"] = opts["quality"].to_s if opts.key?("quality") && !opts["quality"].nil?
+      fields["target_kb"] = opts["target_kb"].to_s if opts["target_kb"]
+      fields["lossless"] = opts["lossless"] ? "true" : "false" unless opts["lossless"].nil?
+      fields["maxWidth"] = opts["maxWidth"].to_s if opts["maxWidth"]
+      fields["maxHeight"] = opts["maxHeight"].to_s if opts["maxHeight"]
+      fields["keep_metadata"] = opts["keep_metadata"] ? "true" : "false" unless opts["keep_metadata"].nil?
+      fields
+    end
+
+    def stringify_keys(hash)
+      hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+    end
+
+    def normalize_upload(input, index)
+      case input
+      when String, Pathname
+        path = input.to_s
+        raise ArgumentError, "File not found: #{path}" unless File.file?(path)
+
+        filename = File.basename(path)
+        [filename, File.binread(path).force_encoding(Encoding::BINARY), guess_content_type(filename)]
+      when IO, StringIO
+        data = input.read.to_s.dup.force_encoding(Encoding::BINARY)
+        input.rewind if input.respond_to?(:rewind)
+        name = input.respond_to?(:path) && input.path ? File.basename(input.path) : "image-#{index + 1}"
+        [name, data, guess_content_type(name)]
+      when Hash
+        filename = (input[:filename] || input["filename"] || "image-#{index + 1}").to_s
+        if (path = input[:path] || input["path"])
+          return normalize_upload(path, index)
+        end
+
+        data = input[:data] || input["data"] || input[:contents] || input["contents"]
+        raise ArgumentError, "dict uploads require data/contents" if data.nil?
+
+        data = data.to_s.dup.force_encoding(Encoding::BINARY)
+        content_type = input[:content_type] || input["content_type"] || guess_content_type(filename)
+        [filename, data, content_type]
+      else
+        raise ArgumentError,
+              "Unsupported upload input — pass a path, IO, or { data:, filename: }"
+      end
+    end
+
+    def guess_content_type(filename)
+      case File.extname(filename).downcase
+      when ".jpg", ".jpeg" then "image/jpeg"
+      when ".png" then "image/png"
+      when ".gif" then "image/gif"
+      when ".webp" then "image/webp"
+      when ".avif" then "image/avif"
+      when ".tif", ".tiff" then "image/tiff"
+      when ".bmp" then "image/bmp"
+      when ".ico" then "image/x-icon"
+      when ".heic", ".heif" then "image/heic"
+      else "application/octet-stream"
+      end
+    end
+
+    def escape_filename(name)
+      name.to_s.tr("\"\r\n", "")
+    end
+
+    def request_json(method, path, timeout: @timeout, retryable: true)
+      decode_json(request_raw(method, "#{@base_url}#{path}", nil, timeout, retryable))
+    end
+
+    def fetch_binary(url, path_label)
+      request_raw("GET", url, nil, @timeout, true, path_label: path_label)
+    end
+
+    def request_raw(method, url, body, timeout, retryable, path_label: nil)
+      max_attempts = retryable ? @max_retries + 1 : 1
+      last_error = nil
+      label = path_label || begin
+        i = url.index("/api/v1")
+        i ? url[(i + "/api/v1".length)..] : url
+      end
+
+      (1..max_attempts).each do |attempt|
+        emit(phase: attempt == 1 ? "start" : "retry", path: label, attempt: attempt, max_attempts: max_attempts)
+        begin
+          response = raw_request(method, url, body, {}, timeout)
+        rescue Error => e
+          last_error = e
+          raise e unless attempt < max_attempts && e.retryable?
+
+          sleep retry_delay_sec(e.retry_after, attempt)
+          next
+        end
+        emit(phase: "complete", path: label, attempt: attempt, max_attempts: max_attempts)
+        return response[:body]
+      end
+
+      raise last_error || Error.new("Request failed after retries", status: 503, code: "busy")
+    end
+
+    def raw_request(method, url, body, extra_headers, timeout)
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => USER_AGENT
+      }.merge(@extra_headers).merge(extra_headers)
+
+      response =
+        if @http_handler
+          @http_handler.call(method, url, body, headers, timeout)
+        else
+          default_http(method, url, body, headers, timeout)
+        end
+
+      status = response[:status].to_i
+      resp_headers = downcase_keys(response[:headers] || {})
+      resp_body = response[:body].to_s
+      retry_after = parse_retry_after(resp_headers["retry-after"])
+
+      return response.merge(headers: resp_headers) if status.between?(200, 299)
+
+      parsed = begin
+        JSON.parse(resp_body)
+      rescue JSON::ParserError
+        {}
+      end
+      msg = parsed["message"] || parsed["error"] || "HTTP #{status}"
+      code = parsed["code"] || "server_error"
+      raise Error.new(msg, status: status, code: code, retry_after: retry_after, body: resp_body)
+    end
+
+    def default_http(method, url, body, headers, timeout)
+      uri = URI(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = timeout
+      http.open_timeout = [timeout, 30].min
+
+      req_class = Net::HTTP.const_get(method.capitalize)
+      req = req_class.new(uri.request_uri)
+      headers.each { |k, v| req[k] = v }
+      req.body = body if body
+
+      res = http.request(req)
+      {
+        status: res.code.to_i,
+        headers: res.to_hash.transform_values { |v| v.is_a?(Array) ? v.first : v },
+        body: res.body
+      }
+    end
+
+    def decode_json(body)
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    end
+
+    def downcase_keys(hash)
+      hash.each_with_object({}) { |(k, v), acc| acc[k.to_s.downcase] = v.is_a?(Array) ? v.first : v }
+    end
+
+    def parse_retry_after(raw)
+      return nil if raw.nil? || raw.to_s.empty?
+      return raw.to_f if raw.to_s.match?(/\A\d+(\.\d+)?\z/)
+
+      nil
+    end
+
+    def retry_delay_sec(retry_after, attempt)
+      return [60.0, retry_after].min if retry_after && retry_after >= 0
+
+      [10.0, 0.5 * (2**(attempt - 1))].min
+    end
+
+    def emit(event)
+      @on_progress&.call(event)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/comprestack/error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Comprestack
+  class Error < StandardError
+    attr_reader :status, :code, :retry_after, :body
+
+    def initialize(message, status: 0, code: "error", retry_after: nil, body: nil)
+      super(message)
+      @status = status
+      @code = code
+      @retry_after = retry_after
+      @body = body
+    end
+
+    def retryable?
+      status == 429 || status == 503
+    end
+  end
+end

data/lib/comprestack/version.rb

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

data/lib/comprestack.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "comprestack/version"
+require_relative "comprestack/error"
+require_relative "comprestack/client"
+
+module Comprestack
+  DEFAULT_API_BASE = "https://api.comprestack.com/api/v1"
+  DEFAULT_ORIGIN = "https://api.comprestack.com"
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: comprestack
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Comprestack
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+description: Compress or convert images from Rails, Shopify, and plain Ruby. Same
+  REST surface as the Comprestack API.
+email:
+- hello@comprestack.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/comprestack.rb
+- lib/comprestack/client.rb
+- lib/comprestack/error.rb
+- lib/comprestack/version.rb
+homepage: https://www.comprestack.com/docs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.comprestack.com/docs
+  source_code_uri: https://github.com/MichaelGenesisII/Comprestack-API/tree/main/sdk/ruby
+  changelog_uri: https://www.comprestack.com/docs#changelog
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the Comprestack image optimization API
+test_files: []