fireimg 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5250ba61c2e4e5c42e372bf3947a710a941eb6d1a3c208e466f3a42185931056
+  data.tar.gz: bf9ec77b5168637ad0ca494cc74038b83b37a4b45c82810ab9dcc345b85a6571
+SHA512:
+  metadata.gz: 6632550c999b8450549eeda9214af9c853c2e49b29931eb2e25be227c86fd579e40f5fcf73a2ecc063e11121cb5e336d2ecb4169e41ea646b201c7d47bac899d
+  data.tar.gz: f50017794cf2dfd83bfc463850d972eb8f7807356b40c0a59ee5d5c501486d856b3ffeb897513507eb0be6d3d0b6432a5c12fa6fb3afad59f7fefd93ea43174e

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 1.0.0
+
+- Presign uploads (folder keys, optional `sizes` to pre-generate variants)
+- Moderate and delete images via the API-key HTTP API
+- Build public and query-parameter CDN URLs

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firelit Studio
+
+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,73 @@
+# fireimg
+
+Ruby client for [FireImg](https://fireimg.com): API-key uploads, optional
+moderation, and CDN URLs.
+
+Source of truth is developed in the private FireImg repo and mirrored here.
+
+## Install
+
+```ruby
+gem 'fireimg', '~> 1.0'
+```
+
+```bash
+bundle add fireimg
+```
+
+## Configure
+
+```ruby
+Fireimg.configure do |c|
+  c.api_key = ENV.fetch('FIREIMG_API_KEY')
+  c.project = ENV.fetch('FIREIMG_PROJECT')
+  c.api_base = ENV.fetch('FIREIMG_API_BASE', 'https://api.fireimg.com')
+  c.cdn_base = ENV.fetch('FIREIMG_CDN_BASE', 'https://img.fireimg.com')
+end
+```
+
+`FIREIMG_API_KEY` and `FIREIMG_PROJECT` are also read automatically if you skip
+the block. `FIREIMG_API_BASE` and `FIREIMG_CDN_BASE` have the defaults above.
+
+## Upload
+
+```ruby
+result = Fireimg.presign(
+  filename: 'feed_items/43/uuid.jpg',
+  content_type: 'image/jpeg',
+  sizes: [
+    { width: 800, quality: 'medium' },
+    { width: 160, height: 160, fit: 'cover', pos: 'center' }
+  ]
+)
+
+# PUT raw bytes to result.upload_url with the same Content-Type.
+```
+
+`filename` may include folders. Optional `sizes` (up to 20) are generated
+asynchronously after the `PUT` and **replace** the project's default image
+params for that upload. Omit `sizes` to keep project defaults. Pass `sizes: []`
+to pre-generate only FireImg's 80px dashboard thumbnail.
+
+## Moderate and delete
+
+```ruby
+labels = Fireimg.moderate('feed_items/43/uuid.jpg')
+Fireimg.delete('feed_items/43/uuid.jpg')
+```
+
+Moderation returns FireImg labels; your app applies policy.
+
+## URLs
+
+```ruby
+Fireimg.public_url('feed_items/43/uuid.jpg')
+# => https://img.fireimg.com/{project}/images/feed_items/43/uuid.jpg
+
+Fireimg.url('feed_items/43/uuid.jpg', width: 800, quality: 'medium', fmt: 'webp')
+# => …/images/feed_items/43/uuid.jpg?width=800&quality=medium&fmt=webp
+```
+
+## License
+
+MIT

data/lib/fireimg/client.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module Fireimg
+  class Client
+    def initialize(config = Fireimg.configuration)
+      @config = config
+    end
+
+    def configured?
+      @config.configured?
+    end
+
+    def project
+      @config.project
+    end
+
+    def api_base
+      @config.api_base
+    end
+
+    def cdn_base
+      @config.cdn_base
+    end
+
+    def public_url(image_key)
+      key = image_key.to_s.sub(%r{\A/+}, '')
+      "#{cdn_base}/#{project}/images/#{key}"
+    end
+
+    # CDN URL with query-parameter transforms, matching @fireimg/js getUrl.
+    def url(image_key, **options)
+      key = image_key.to_s.sub(%r{\A/+}, '')
+      qs = query_string(options)
+      base = "#{cdn_base}/#{project}/images/#{key}"
+      qs.empty? ? base : "#{base}?#{qs}"
+    end
+
+    def presign(filename:, content_type:, sizes: nil)
+      rows = presign_many(files: [{ filename: filename, content_type: content_type }], sizes: sizes)
+      raise Error, 'FireImg presign returned no URLs' if rows.empty?
+
+      rows.first
+    end
+
+    def presign_many(files:, sizes: nil)
+      payload = {
+        'slug' => project,
+        'files' => Array(files).map { |file| file_payload(file) }
+      }
+      payload['sizes'] = Array(sizes).map { |size| Size.from(size).to_h } unless sizes.nil?
+
+      body = post_json('/v1/api/presigned-upload-urls', payload)
+      Array(body['urls']).map { |row| parse_presign_row(row) }
+    end
+
+    def moderate(image_key)
+      post_json("/v1/api/projects/#{project}/images/moderation/#{image_key}", {})
+    end
+
+    def delete(image_key)
+      request_json(Net::HTTP::Delete, "/v1/api/projects/#{project}/images/#{image_key}", nil)
+      true
+    end
+
+    private
+
+    def file_payload(file)
+      h = stringify_keys(file)
+      filename = h['filename'] || h[:filename]
+      content_type = h['content_type'] || h['contentType'] || h[:content_type]
+      raise Error, 'filename is required' if filename.to_s.strip.empty?
+      raise Error, 'content_type is required' if content_type.to_s.strip.empty?
+
+      { 'filename' => filename, 'contentType' => content_type }
+    end
+
+    def parse_presign_row(row)
+      h = stringify_keys(row)
+      PresignResult.new(
+        upload_url: h['uploadUrl'] || h['upload_url'],
+        s3_key: h['s3Key'] || h['s3_key'],
+        filename: h['filename'],
+        expires_in_secs: h['expiresInSecs'] || h['expires_in_secs']
+      )
+    end
+
+    def query_string(options)
+      params = []
+      w = options[:width]
+      h = options[:height]
+      params << ['width', w] if w && w.to_i > 0
+      params << ['height', h] if h && h.to_i > 0
+      q = options[:quality]
+      params << ['quality', q] unless q.nil? || q.to_s.empty?
+      fmt = options[:fmt] || options[:format]
+      params << ['fmt', fmt] unless fmt.nil? || fmt.to_s.empty?
+      fit = options[:fit]
+      params << ['fit', fit] unless fit.nil? || fit.to_s.empty?
+      pos = options[:pos] || options[:position]
+      params << ['pos', pos] unless pos.nil? || pos.to_s.empty?
+      fill = options[:fill]
+      params << ['fill', fill] unless fill.nil? || fill.to_s.empty?
+      params.map { |k, v| "#{k}=#{URI.encode_www_form_component(v.to_s)}" }.join('&')
+    end
+
+    def post_json(path, body)
+      request_json(Net::HTTP::Post, path, body)
+    end
+
+    def request_json(method_class, path, body)
+      raise Error, 'FireImg is not configured (set api_key and project)' unless configured?
+
+      uri = URI.parse("#{api_base}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = 5
+      http.read_timeout = 20
+      req = method_class.new(uri.request_uri)
+      req['Content-Type'] = 'application/json'
+      req['Accept'] = 'application/json'
+      req['X-Api-Key'] = @config.api_key
+      req.body = JSON.generate(body) unless body.nil?
+      res = http.request(req)
+      parsed = parse_json(res.body)
+      unless res.is_a?(Net::HTTPSuccess)
+        message = parsed['error'] || parsed['message'] || res.message
+        raise Error, "FireImg #{res.code}: #{message}"
+      end
+      parsed
+    end
+
+    def parse_json(raw)
+      JSON.parse(raw.to_s.empty? ? '{}' : raw)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def stringify_keys(value)
+      return {} if value.nil?
+      return value.transform_keys(&:to_s) if value.respond_to?(:transform_keys)
+
+      value.to_h.transform_keys(&:to_s)
+    end
+  end
+end

data/lib/fireimg/configuration.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Fireimg
+  class Configuration
+    DEFAULT_API_BASE = 'https://api.fireimg.com'
+    DEFAULT_CDN_BASE = 'https://img.fireimg.com'
+
+    attr_accessor :api_key, :project, :api_base, :cdn_base
+
+    def initialize
+      @api_key = ENV['FIREIMG_API_KEY'].to_s.strip
+      @project = (ENV['FIREIMG_PROJECT'] || '').to_s.strip
+      @api_base = strip_slash(ENV['FIREIMG_API_BASE'].to_s.strip)
+      @api_base = DEFAULT_API_BASE if @api_base.empty?
+      @cdn_base = strip_slash(ENV['FIREIMG_CDN_BASE'].to_s.strip)
+      @cdn_base = DEFAULT_CDN_BASE if @cdn_base.empty?
+    end
+
+    def configured?
+      !api_key.to_s.strip.empty? && !project.to_s.strip.empty?
+    end
+
+    def api_base=(value)
+      @api_base = strip_slash(value.to_s)
+      @api_base = DEFAULT_API_BASE if @api_base.empty?
+    end
+
+    def cdn_base=(value)
+      @cdn_base = strip_slash(value.to_s)
+      @cdn_base = DEFAULT_CDN_BASE if @cdn_base.empty?
+    end
+
+    private
+
+    def strip_slash(value)
+      value.to_s.sub(%r{/\z}, '')
+    end
+  end
+end

data/lib/fireimg/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Fireimg
+  class Error < StandardError; end
+end

data/lib/fireimg/presign_result.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Fireimg
+  PresignResult = Struct.new(:upload_url, :s3_key, :filename, :expires_in_secs, keyword_init: true) do
+    def to_h
+      {
+        'upload_url' => upload_url,
+        's3_key' => s3_key,
+        'filename' => filename,
+        'expires_in_secs' => expires_in_secs
+      }
+    end
+  end
+end

data/lib/fireimg/size.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Fireimg
+  # A variant to pre-generate after upload. Matches FireImg `sizes` JSON
+  # (`width`/`height`, `quality`, `fmt`, `fit`, `pos`, `fill`).
+  class Size
+    attr_reader :width, :height, :quality, :fmt, :fit, :pos, :fill
+
+    def initialize(width: nil, height: nil, quality: nil, fmt: nil, fit: nil, pos: nil, fill: nil)
+      @width = width
+      @height = height
+      @quality = quality
+      @fmt = fmt
+      @fit = fit
+      @pos = pos
+      @fill = fill
+    end
+
+    def self.from(value)
+      case value
+      when Size
+        value
+      when Hash
+        h = value.transform_keys { |k| k.to_s.tr('-', '_') }
+        new(
+          width: h['width'],
+          height: h['height'],
+          quality: h['quality'],
+          fmt: h['fmt'] || h['format'],
+          fit: h['fit'],
+          pos: h['pos'] || h['position'],
+          fill: h['fill']
+        )
+      else
+        raise ArgumentError, "expected Fireimg::Size or Hash, got #{value.class}"
+      end
+    end
+
+    def to_h
+      out = {}
+      out[:width] = Integer(width) if width && Integer(width) > 0
+      out[:height] = Integer(height) if height && Integer(height) > 0
+      out[:quality] = quality.to_s unless quality.nil? || quality.to_s.empty?
+      out[:fmt] = fmt.to_s unless fmt.nil? || fmt.to_s.empty?
+      out[:fit] = fit.to_s unless fit.nil? || fit.to_s.empty?
+      out[:pos] = pos.to_s unless pos.nil? || pos.to_s.empty?
+      out[:fill] = fill.to_s unless fill.nil? || fill.to_s.empty?
+      out
+    end
+  end
+end

data/lib/fireimg/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Fireimg
+  VERSION = '1.0.0'
+end

data/lib/fireimg.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative 'fireimg/version'
+require_relative 'fireimg/error'
+require_relative 'fireimg/configuration'
+require_relative 'fireimg/size'
+require_relative 'fireimg/presign_result'
+require_relative 'fireimg/client'
+
+module Fireimg
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+      @client = nil
+      configuration
+    end
+
+    def reset!
+      @configuration = Configuration.new
+      @client = nil
+    end
+
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    def configured?
+      configuration.configured?
+    end
+
+    def public_url(image_key)
+      client.public_url(image_key)
+    end
+
+    def url(image_key, **options)
+      client.url(image_key, **options)
+    end
+
+    def presign(...)
+      client.presign(...)
+    end
+
+    def presign_many(...)
+      client.presign_many(...)
+    end
+
+    def moderate(image_key)
+      client.moderate(image_key)
+    end
+
+    def delete(image_key)
+      client.delete(image_key)
+    end
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: fireimg
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Firelit Studio
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-25 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Server-side Ruby client for FireImg. Request presigned uploads (including
+  folder keys and optional pre-generated sizes), run content moderation, and
+  build CDN URLs. Matches the FireImg API-key HTTP API and @fireimg/js URL
+  query parameters.
+email:
+- hello@firelit.studio
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/fireimg.rb
+- lib/fireimg/client.rb
+- lib/fireimg/configuration.rb
+- lib/fireimg/error.rb
+- lib/fireimg/presign_result.rb
+- lib/fireimg/size.rb
+- lib/fireimg/version.rb
+homepage: https://github.com/FirelitStudio/fireimg-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/FirelitStudio/fireimg-ruby
+  source_code_uri: https://github.com/FirelitStudio/fireimg-ruby
+  changelog_uri: https://github.com/FirelitStudio/fireimg-ruby/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+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.3
+signing_key:
+specification_version: 4
+summary: Ruby client for FireImg uploads, moderation, and CDN URLs
+test_files: []