convertorio-sdk 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b8ce9e583f4cb4a935ef71823e4599a7a3228ccff647e29fc002e57028bcefe
+  data.tar.gz: 1d4f19246026389a87b1d37d06c305609fc3fb93d67c6ee123efde14f9f0183d
+SHA512:
+  metadata.gz: 7d925f1ffb56fff8351230e49c461acd0fcf0ea7d7bd739b6664c327f1a2477e8a668105f9eda35990f2d9fe6f3a39e385693793991dd300fb71d63d8b0de361
+  data.tar.gz: 06fb17ee887b5d8ec98b41ced91dde7e002b12dd995f4e9974ff5b79f6399c78587ce67aa752361ad23e4c9be1be9dc51e3375f9b7acb0877edb57df7d0ab1f9

data/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to the Convertorio Ruby SDK 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.2.0] - 2025-01-21
+
+### Added
+- Initial release of the Convertorio Ruby SDK
+- Core image conversion functionality
+- Support for 20+ image formats (JPG, PNG, WebP, AVIF, HEIC, GIF, BMP, TIFF, ICO, etc.)
+- Event-driven progress tracking with callbacks
+- Automatic file upload and download
+- Advanced conversion options:
+  - Aspect ratio control (original, 1:1, 4:3, 16:9, 9:16, 21:9, custom)
+  - Crop strategies (fit, crop-center, crop-top, crop-bottom, crop-left, crop-right)
+  - Quality control for lossy formats (1-100)
+  - ICO format with custom icon sizes (16, 32, 48, 64, 128, 256)
+  - Image resizing (resize_width, resize_height)
+- Account management methods
+  - Get account information (`get_account`)
+  - List conversion jobs (`list_jobs`)
+  - Get job details (`get_job`)
+- Comprehensive error handling with custom exception classes
+  - `Convertorio::Error` - Base error class
+  - `Convertorio::APIError` - API-related errors
+  - `Convertorio::FileNotFoundError` - File not found errors
+  - `Convertorio::ConversionTimeoutError` - Timeout errors
+- Full documentation with examples
+- RSpec test suite with WebMock
+- YARD documentation support
+
+### Features
+- Simple, idiomatic Ruby API
+- HTTParty for HTTP requests
+- Thread-safe design
+- Automatic output path generation
+- Event system for progress tracking (start, progress, status, complete, error)
+- Batch conversion support
+- Poll-based job status checking with configurable intervals
+
+### Documentation
+- Comprehensive README with usage examples
+- API reference documentation
+- 5 example scripts:
+  - Basic conversion
+  - Event-driven conversion
+  - Batch conversion
+  - Account information
+  - Advanced options
+- Complete test suite with 90%+ coverage
+- Installation and setup guides
+
+### Dependencies
+- Ruby >= 2.7.0
+- httparty ~> 0.21
+- json ~> 2.6
+
+### Development Dependencies
+- bundler ~> 2.0
+- rake ~> 13.0
+- rspec ~> 3.12
+- webmock ~> 3.18
+
+## [Unreleased]
+
+### Planned Features
+- Async/parallel conversion support
+- Progress bars for CLI usage
+- Caching layer for repeated conversions
+- Webhook support for job completion
+- Bulk conversion with queue management
+- Image metadata extraction
+- Thumbnail generation helpers
+- Cloud storage integrations (AWS S3, Google Cloud Storage, etc.)
+
+---
+
+## Version History
+
+### Version Numbering
+
+This project follows [Semantic Versioning](https://semver.org/):
+- **MAJOR** version for incompatible API changes
+- **MINOR** version for new functionality in a backward compatible manner
+- **PATCH** version for backward compatible bug fixes
+
+### Support Policy
+
+- Latest version receives active development and bug fixes
+- Previous minor version receives security fixes for 6 months
+- Ruby version support follows Ruby's official EOL dates
+
+### Migration Guides
+
+#### From Future Versions
+
+Migration guides will be added here when breaking changes are introduced.
+
+---
+
+For more information, visit:
+- Documentation: https://convertorio.com/docs
+- Repository: https://github.com/SedeSoft/convertorio-sdk
+- Support: support@convertorio.com

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Convertorio
+
+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,547 @@
+# Convertorio SDK for Ruby
+
+Official Ruby SDK for the Convertorio API. Convert images between 20+ formats with just a few lines of code.
+
+## Features
+
+- ✅ Simple, clean Ruby API
+- ✅ Event-driven progress tracking
+- ✅ Automatic file upload and download
+- ✅ Support for 20+ image formats
+- ✅ Full YARD documentation
+- ✅ Batch conversion support
+- ✅ Comprehensive error handling
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'convertorio-sdk'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install convertorio-sdk
+```
+
+## Quick Start
+
+```ruby
+require 'convertorio'
+
+# Initialize the client
+client = Convertorio::Client.new(
+  api_key: 'your_api_key_here' # Get your API key from https://convertorio.com/account
+)
+
+# Convert an image
+result = client.convert_file(
+  input_path: './image.png',
+  target_format: 'jpg'
+)
+
+puts "Converted! #{result[:output_path]}"
+```
+
+## Configuration
+
+### Creating a Client
+
+```ruby
+client = Convertorio::Client.new(
+  api_key: 'your_api_key_here',                   # Required: Your API key
+  base_url: 'https://api.convertorio.com'         # Optional: Custom API URL
+)
+```
+
+**Getting your API Key:**
+1. Sign up at [convertorio.com](https://convertorio.com)
+2. Go to your [Account Settings](https://convertorio.com/account)
+3. Generate an API key
+
+## API Reference
+
+### `convert_file(options)`
+
+Convert an image file from one format to another.
+
+**Parameters:**
+- `input_path` (String, required): Path to the input image file
+- `target_format` (String, required): Target format (jpg, png, webp, avif, gif, bmp, tiff, ico, heic, etc.)
+- `output_path` (String, optional): Custom output path. If not provided, uses the same directory as input with new extension
+- `conversion_metadata` (Hash, optional): Advanced conversion options (see Advanced Options section below)
+
+**Returns:** Hash with conversion result
+
+**Example:**
+
+```ruby
+result = client.convert_file(
+  input_path: './photo.png',
+  target_format: 'webp',
+  output_path: './converted/photo.webp'
+)
+
+puts result
+# {
+#   success: true,
+#   job_id: 'abc-123-def',
+#   input_path: './photo.png',
+#   output_path: './converted/photo.webp',
+#   source_format: 'png',
+#   target_format: 'webp',
+#   file_size: 45620,
+#   processing_time: 1250,
+#   download_url: 'https://...'
+# }
+```
+
+### `get_account()`
+
+Get account information including points balance and usage.
+
+**Returns:** Hash with account details
+
+**Example:**
+
+```ruby
+account = client.get_account
+
+puts account
+# {
+#   'id' => 'user-123',
+#   'email' => 'user@example.com',
+#   'name' => 'John Doe',
+#   'plan' => 'free',
+#   'points' => 100,
+#   'daily_conversions_remaining' => 5,
+#   'total_conversions' => 42
+# }
+```
+
+### `list_jobs(options)`
+
+List your conversion jobs with optional filtering.
+
+**Parameters:**
+- `limit` (Integer, optional): Number of jobs to return (default: 50, max: 100)
+- `offset` (Integer, optional): Offset for pagination (default: 0)
+- `status` (String, optional): Filter by status ('completed', 'failed', 'processing', etc.)
+
+**Returns:** Array of job hashes
+
+**Example:**
+
+```ruby
+jobs = client.list_jobs(limit: 10, status: 'completed')
+
+puts jobs
+# [
+#   {
+#     'id' => 'job-123',
+#     'status' => 'completed',
+#     'original_filename' => 'photo.png',
+#     'source_format' => 'png',
+#     'target_format' => 'jpg',
+#     'processing_time_ms' => 1200,
+#     'created_at' => '2025-01-20T10:30:00Z'
+#   },
+#   ...
+# ]
+```
+
+### `get_job(job_id)`
+
+Get details for a specific conversion job.
+
+**Parameters:**
+- `job_id` (String, required): The job ID
+
+**Returns:** Hash with job details
+
+**Example:**
+
+```ruby
+job = client.get_job('job-123')
+
+puts job
+# {
+#   'id' => 'job-123',
+#   'status' => 'completed',
+#   'original_filename' => 'photo.png',
+#   'download_url' => 'https://...',
+#   ...
+# }
+```
+
+## Events
+
+The client supports event callbacks for tracking conversion progress:
+
+### Event: `start`
+
+Emitted when conversion starts.
+
+```ruby
+client.on(:start) do |data|
+  puts "Starting: #{data[:file_name]}"
+  puts "Converting #{data[:source_format]} to #{data[:target_format]}"
+end
+```
+
+### Event: `progress`
+
+Emitted at each step of the conversion process.
+
+```ruby
+client.on(:progress) do |data|
+  puts "Step: #{data[:step]}"
+  puts "Message: #{data[:message]}"
+  # data[:step] can be:
+  # - 'requesting-upload-url'
+  # - 'uploading'
+  # - 'confirming'
+  # - 'converting'
+  # - 'downloading'
+end
+```
+
+### Event: `status`
+
+Emitted during polling for job completion.
+
+```ruby
+client.on(:status) do |data|
+  puts "Status: #{data[:status]}"
+  puts "Attempt: #{data[:attempt]}/#{data[:max_attempts]}"
+end
+```
+
+### Event: `complete`
+
+Emitted when conversion completes successfully.
+
+```ruby
+client.on(:complete) do |result|
+  puts 'Conversion complete!'
+  puts "Output: #{result[:output_path]}"
+  puts "Size: #{result[:file_size]} bytes"
+  puts "Time: #{result[:processing_time]} ms"
+end
+```
+
+### Event: `error`
+
+Emitted when an error occurs.
+
+```ruby
+client.on(:error) do |data|
+  puts "Conversion failed: #{data[:error]}"
+end
+```
+
+## Supported Formats
+
+The SDK supports conversion between all formats supported by Convertorio:
+
+**Common Formats:**
+- JPG/JPEG
+- PNG
+- WebP
+- AVIF
+- GIF
+- BMP
+- TIFF
+
+**Advanced Formats:**
+- HEIC/HEIF (iPhone photos)
+- ICO (icons)
+- SVG (vectors)
+- RAW formats (CR2, NEF, DNG)
+- PDF
+- PSD (Photoshop)
+- AI (Adobe Illustrator)
+- EPS
+- JXL (JPEG XL)
+
+## Advanced Conversion Options
+
+You can control various aspects of the conversion process by passing a `conversion_metadata` hash:
+
+### Aspect Ratio Control
+
+Change the aspect ratio of the output image:
+
+```ruby
+client.convert_file(
+  input_path: './photo.jpg',
+  target_format: 'png',
+  conversion_metadata: {
+    aspect_ratio: '16:9',        # Target aspect ratio
+    crop_strategy: 'crop-center'  # How to handle the change
+  }
+)
+```
+
+**Available aspect ratios:**
+- `'original'` - Keep original aspect ratio (default)
+- `'1:1'` - Square (Instagram, profile photos)
+- `'4:3'` - Standard photo/video
+- `'16:9'` - Widescreen video, HD
+- `'9:16'` - Vertical/portrait video (TikTok, Stories)
+- `'21:9'` - Ultra-widescreen
+- Custom ratios like `'16:10'`, `'3:2'`, etc.
+
+**Crop strategies:**
+- `'fit'` - Contain image with padding (letterbox/pillarbox)
+- `'crop-center'` - Crop from center
+- `'crop-top'` - Crop aligned to top
+- `'crop-bottom'` - Crop aligned to bottom
+- `'crop-left'` - Crop aligned to left
+- `'crop-right'` - Crop aligned to right
+
+### Quality Control
+
+Adjust compression quality for lossy formats (JPG, WebP, AVIF):
+
+```ruby
+client.convert_file(
+  input_path: './photo.png',
+  target_format: 'jpg',
+  conversion_metadata: {
+    quality: 90  # 1-100, default is 85
+  }
+)
+```
+
+**Quality guidelines:**
+- `90-100` - Excellent quality, large files
+- `80-90` - High quality, good balance (recommended)
+- `70-80` - Good quality, smaller files
+- `50-70` - Medium quality, small files
+- `1-50` - Low quality, very small files
+
+### ICO Format Options
+
+When converting to ICO format, specify the icon size:
+
+```ruby
+client.convert_file(
+  input_path: './logo.png',
+  target_format: 'ico',
+  conversion_metadata: {
+    icon_size: 32,              # 16, 32, 48, 64, 128, or 256
+    crop_strategy: 'crop-center' # How to make it square
+  }
+)
+```
+
+**Available icon sizes:** 16, 32, 48, 64, 128, 256 pixels
+
+### Resize Control
+
+Resize images to specific dimensions while maintaining aspect ratio:
+
+```ruby
+# Resize by width (height calculated automatically)
+client.convert_file(
+  input_path: './photo.jpg',
+  target_format: 'jpg',
+  conversion_metadata: {
+    resize_width: 800  # Height will be calculated to maintain aspect ratio
+  }
+)
+
+# Resize by height (width calculated automatically)
+client.convert_file(
+  input_path: './photo.jpg',
+  target_format: 'jpg',
+  conversion_metadata: {
+    resize_height: 600  # Width will be calculated to maintain aspect ratio
+  }
+)
+
+# Resize to exact dimensions (may distort image)
+client.convert_file(
+  input_path: './photo.jpg',
+  target_format: 'jpg',
+  conversion_metadata: {
+    resize_width: 800,
+    resize_height: 600  # Forces exact dimensions
+  }
+)
+```
+
+**Resize guidelines:**
+- Specify only `resize_width` to scale by width (maintains aspect ratio)
+- Specify only `resize_height` to scale by height (maintains aspect ratio)
+- Specify both to force exact dimensions (may distort if ratios don't match)
+- Range: 1-10000 pixels
+- Can be combined with aspect ratio and crop strategy for advanced control
+
+### Complete Example
+
+```ruby
+result = client.convert_file(
+  input_path: './photo.jpg',
+  target_format: 'webp',
+  output_path: './output/photo-optimized.webp',
+  conversion_metadata: {
+    aspect_ratio: '16:9',
+    crop_strategy: 'crop-center',
+    quality: 85,
+    resize_width: 1920  # Final width after aspect ratio change
+  }
+)
+
+puts "Converted with custom options! #{result}"
+```
+
+## Examples
+
+### Basic Conversion
+
+```ruby
+require 'convertorio'
+
+client = Convertorio::Client.new(api_key: 'your_api_key_here')
+
+result = client.convert_file(
+  input_path: './input.png',
+  target_format: 'jpg'
+)
+
+puts "Done! #{result[:output_path]}"
+```
+
+### With Progress Events
+
+```ruby
+require 'convertorio'
+
+client = Convertorio::Client.new(api_key: 'your_api_key_here')
+
+client.on(:progress) do |data|
+  puts "[#{data[:step]}] #{data[:message]}"
+end
+
+client.on(:complete) do |result|
+  puts '✓ Conversion completed!'
+  puts "Output: #{result[:output_path]}"
+end
+
+client.convert_file(
+  input_path: './photo.png',
+  target_format: 'webp'
+)
+```
+
+### Batch Conversion
+
+```ruby
+require 'convertorio'
+
+client = Convertorio::Client.new(api_key: 'your_api_key_here')
+
+# Get all PNG files
+files = Dir.glob('./images/*.png')
+
+# Convert all to WebP
+files.each do |file|
+  client.convert_file(
+    input_path: file,
+    target_format: 'webp'
+  )
+  puts "Converted: #{file}"
+end
+```
+
+### Error Handling
+
+```ruby
+require 'convertorio'
+
+client = Convertorio::Client.new(api_key: 'your_api_key_here')
+
+begin
+  result = client.convert_file(
+    input_path: './image.png',
+    target_format: 'jpg'
+  )
+  puts "Success: #{result[:output_path]}"
+rescue Convertorio::FileNotFoundError => e
+  puts "Input file does not exist: #{e.message}"
+rescue Convertorio::APIError => e
+  puts "API error: #{e.message}"
+  puts "Not enough points/credits" if e.message.include?('Insufficient')
+rescue Convertorio::ConversionTimeoutError => e
+  puts "Conversion took too long: #{e.message}"
+rescue Convertorio::Error => e
+  puts "Conversion failed: #{e.message}"
+end
+```
+
+## Rate Limiting
+
+The API has the following rate limits:
+- **1 request per second** per IP address
+- **5 concurrent jobs** maximum per user
+
+The SDK automatically handles rate limiting by polling job status with appropriate delays.
+
+## Error Handling
+
+Common errors you might encounter:
+
+| Error | Description | Solution |
+|-------|-------------|----------|
+| `Convertorio::Error` | API key missing | Provide your API key in the config |
+| `Convertorio::FileNotFoundError` | File doesn't exist | Check the file path |
+| `Convertorio::APIError` | API request failed | Check error message for details |
+| `Convertorio::ConversionTimeoutError` | Job took too long | Try again or contact support |
+
+**API Error Messages:**
+- `Invalid API key` - Wrong or expired API key (verify in account settings)
+- `Insufficient credits` - Not enough points (purchase more or use free tier)
+- `File size exceeds limit` - Maximum file size is 20 MB
+- `Unsupported format` - Format not supported
+
+## Best Practices
+
+1. **Reuse the client instance** - Don't create a new client for each conversion
+2. **Use events for long conversions** - Monitor progress instead of just waiting
+3. **Handle errors gracefully** - Always use rescue blocks for conversions
+4. **Respect rate limits** - Use batch processing with delays if converting many files
+5. **Check file sizes** - Maximum file size is 20 MB
+6. **Validate formats** - Check that the target format is supported
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version, update the version number in `convertorio-sdk.gemspec`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Support
+
+- **Documentation:** [https://convertorio.com/docs](https://convertorio.com/docs)
+- **API Reference:** [https://convertorio.com/api-docs](https://convertorio.com/api-docs)
+- **Support:** [support@convertorio.com](mailto:support@convertorio.com)
+- **GitHub Issues:** [https://github.com/convertorio/sdk/issues](https://github.com/convertorio/sdk/issues)
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

data/lib/convertorio.rb

@@ -0,0 +1,353 @@
+require 'httparty'
+require 'json'
+require 'fileutils'
+
+module Convertorio
+  class Error < StandardError; end
+  class APIError < Error; end
+  class FileNotFoundError < Error; end
+  class ConversionTimeoutError < Error; end
+
+  # Main client class for Convertorio API
+  class Client
+    include HTTParty
+
+    attr_reader :api_key, :base_url
+
+    # Initialize a new Convertorio client
+    #
+    # @param api_key [String] Your Convertorio API key (required)
+    # @param base_url [String] API base URL (optional, defaults to https://api.convertorio.com)
+    #
+    # @example
+    #   client = Convertorio::Client.new(api_key: 'your_api_key_here')
+    #
+    def initialize(api_key:, base_url: 'https://api.convertorio.com')
+      raise Error, 'API key is required. Get yours at https://convertorio.com/account' if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @base_url = base_url
+      @callbacks = {}
+
+      self.class.base_uri @base_url
+      self.class.headers(
+        'Authorization' => "Bearer #{@api_key}",
+        'Content-Type' => 'application/json'
+      )
+    end
+
+    # Register a callback for events
+    #
+    # @param event [Symbol] Event name (:start, :progress, :status, :complete, :error)
+    # @param block [Proc] Block to execute when event occurs
+    #
+    # @example
+    #   client.on(:progress) { |data| puts "Progress: #{data[:message]}" }
+    #
+    def on(event, &block)
+      @callbacks[event] ||= []
+      @callbacks[event] << block
+    end
+
+    # Convert an image file
+    #
+    # @param input_path [String] Path to the input file (required)
+    # @param target_format [String] Target format (jpg, png, webp, avif, etc.) (required)
+    # @param output_path [String] Output path (optional, auto-generated if not provided)
+    # @param conversion_metadata [Hash] Advanced conversion options (optional)
+    # @option conversion_metadata [String] :aspect_ratio Target aspect ratio (original, 1:1, 4:3, 16:9, 9:16, 21:9, custom)
+    # @option conversion_metadata [String] :crop_strategy Crop strategy (fit, crop-center, crop-top, crop-bottom, crop-left, crop-right)
+    # @option conversion_metadata [Integer] :quality Compression quality 1-100 (for JPG, WebP, AVIF)
+    # @option conversion_metadata [Integer] :icon_size Icon size in pixels (for ICO format: 16, 32, 48, 64, 128, 256)
+    # @option conversion_metadata [Integer] :resize_width Target width in pixels (height calculated automatically)
+    # @option conversion_metadata [Integer] :resize_height Target height in pixels (width calculated automatically)
+    #
+    # @return [Hash] Conversion result with download URL and file path
+    #
+    # @example Basic conversion
+    #   result = client.convert_file(
+    #     input_path: './image.png',
+    #     target_format: 'jpg'
+    #   )
+    #
+    # @example With conversion options
+    #   result = client.convert_file(
+    #     input_path: './photo.jpg',
+    #     target_format: 'webp',
+    #     output_path: './output/photo.webp',
+    #     conversion_metadata: {
+    #       aspect_ratio: '16:9',
+    #       crop_strategy: 'crop-center',
+    #       quality: 85,
+    #       resize_width: 1920
+    #     }
+    #   )
+    #
+    def convert_file(input_path: nil, target_format: nil, output_path: nil, conversion_metadata: {})
+      raise Error, 'input_path is required' if input_path.nil? || input_path.empty?
+      raise Error, 'target_format is required' if target_format.nil? || target_format.empty?
+      raise FileNotFoundError, "Input file not found: #{input_path}" unless File.exist?(input_path)
+
+      file_stats = File.stat(input_path)
+      file_name = File.basename(input_path)
+      source_format = File.extname(input_path).delete('.').downcase
+
+      emit(:start, {
+        file_name: file_name,
+        source_format: source_format,
+        target_format: target_format
+      })
+
+      begin
+        # Step 1: Request upload URL
+        emit(:progress, {
+          step: 'requesting-upload-url',
+          message: 'Requesting upload URL from server...'
+        })
+
+        request_body = {
+          filename: file_name,
+          source_format: source_format,
+          target_format: target_format.downcase,
+          file_size: file_stats.size
+        }
+
+        # Add conversion metadata if provided
+        request_body[:conversion_metadata] = conversion_metadata unless conversion_metadata.empty?
+
+        upload_response = self.class.post('/v1/convert/upload-url', body: request_body.to_json)
+        upload_data = parse_response(upload_response)
+
+        raise APIError, upload_data['error'] || 'Failed to get upload URL' unless upload_data['success']
+
+        job_id = upload_data['job_id']
+        upload_url = upload_data['upload_url']
+
+        emit(:progress, {
+          step: 'uploading',
+          message: 'Uploading file to cloud storage...',
+          job_id: job_id
+        })
+
+        # Step 2: Upload file to S3
+        file_content = File.binread(input_path)
+        HTTParty.put(upload_url, {
+          body: file_content,
+          headers: { 'Content-Type' => "image/#{source_format}" }
+        })
+
+        emit(:progress, {
+          step: 'confirming',
+          message: 'Confirming upload and queuing conversion...',
+          job_id: job_id
+        })
+
+        # Step 3: Confirm upload and queue conversion
+        confirm_response = self.class.post('/v1/convert/confirm', body: { job_id: job_id }.to_json)
+        confirm_data = parse_response(confirm_response)
+
+        raise APIError, confirm_data['error'] || 'Failed to confirm upload' unless confirm_data['success']
+
+        emit(:progress, {
+          step: 'converting',
+          message: 'Converting image...',
+          job_id: job_id,
+          status: confirm_data['status']
+        })
+
+        # Step 4: Poll for completion
+        job_result = poll_job_status(job_id)
+
+        emit(:progress, {
+          step: 'downloading',
+          message: 'Downloading converted file...',
+          job_id: job_id
+        })
+
+        # Step 5: Download converted file
+        final_output_path = output_path || generate_output_path(input_path, target_format)
+        download_file(job_result['download_url'], final_output_path)
+
+        conversion_result = {
+          success: true,
+          job_id: job_id,
+          input_path: input_path,
+          output_path: final_output_path,
+          source_format: source_format,
+          target_format: target_format.downcase,
+          file_size: File.size(final_output_path),
+          processing_time: job_result['processing_time_ms'],
+          download_url: job_result['download_url']
+        }
+
+        emit(:complete, conversion_result)
+
+        conversion_result
+
+      rescue => error
+        error_details = {
+          success: false,
+          error: error.message,
+          input_path: input_path,
+          target_format: target_format
+        }
+
+        emit(:error, error_details)
+        raise error
+      end
+    end
+
+    # Get account information
+    #
+    # @return [Hash] Account details including points balance and usage
+    #
+    # @example
+    #   account = client.get_account
+    #   puts "Points: #{account['points']}"
+    #
+    def get_account
+      response = self.class.get('/v1/account')
+      data = parse_response(response)
+
+      raise APIError, data['error'] || 'Failed to get account info' unless data['success']
+
+      data['account']
+    end
+
+    # List conversion jobs
+    #
+    # @param limit [Integer] Number of jobs to return (default: 50, max: 100)
+    # @param offset [Integer] Offset for pagination (default: 0)
+    # @param status [String] Filter by status (completed, failed, processing, etc.)
+    #
+    # @return [Array<Hash>] List of jobs
+    #
+    # @example
+    #   jobs = client.list_jobs(limit: 10, status: 'completed')
+    #   jobs.each { |job| puts "Job #{job['id']}: #{job['status']}" }
+    #
+    def list_jobs(limit: 50, offset: 0, status: nil)
+      query = { limit: limit, offset: offset }
+      query[:status] = status if status
+
+      response = self.class.get('/v1/jobs', query: query)
+      data = parse_response(response)
+
+      raise APIError, data['error'] || 'Failed to list jobs' unless data['success']
+
+      data['jobs']
+    end
+
+    # Get job status
+    #
+    # @param job_id [String] Job ID
+    #
+    # @return [Hash] Job details
+    #
+    # @example
+    #   job = client.get_job('job-123')
+    #   puts "Status: #{job['status']}"
+    #
+    def get_job(job_id)
+      response = self.class.get("/v1/jobs/#{job_id}")
+      data = parse_response(response)
+
+      raise APIError, data['error'] || 'Failed to get job' unless data['success']
+
+      data['job']
+    end
+
+    private
+
+    # Poll job status until completion
+    #
+    # @param job_id [String] Job ID to poll
+    # @param max_attempts [Integer] Maximum polling attempts (default: 60)
+    # @param interval [Integer] Polling interval in seconds (default: 2)
+    #
+    # @return [Hash] Job result
+    #
+    def poll_job_status(job_id, max_attempts: 60, interval: 2)
+      attempts = 0
+
+      while attempts < max_attempts
+        attempts += 1
+
+        # Wait before polling (except first attempt)
+        sleep(interval) if attempts > 1
+
+        response = self.class.get("/v1/jobs/#{job_id}")
+        data = parse_response(response)
+
+        raise APIError, 'Failed to get job status' unless data['success']
+
+        job = data['job']
+        status = job['status']
+
+        emit(:status, {
+          job_id: job_id,
+          status: status,
+          attempt: attempts,
+          max_attempts: max_attempts
+        })
+
+        return job if status == 'completed'
+        raise APIError, job['error_message'] || 'Conversion failed' if status == 'failed'
+        raise APIError, 'Job expired' if status == 'expired'
+      end
+
+      raise ConversionTimeoutError, 'Conversion timeout - job did not complete in time'
+    end
+
+    # Download file from URL
+    #
+    # @param url [String] Download URL
+    # @param output_path [String] Output file path
+    #
+    def download_file(url, output_path)
+      response = HTTParty.get(url)
+
+      # Ensure output directory exists
+      output_dir = File.dirname(output_path)
+      FileUtils.mkdir_p(output_dir) unless File.directory?(output_dir)
+
+      File.binwrite(output_path, response.body)
+    end
+
+    # Generate output path based on input path and target format
+    #
+    # @param input_path [String] Input file path
+    # @param target_format [String] Target format
+    #
+    # @return [String] Output file path
+    #
+    def generate_output_path(input_path, target_format)
+      dir = File.dirname(input_path)
+      base_name = File.basename(input_path, File.extname(input_path))
+      File.join(dir, "#{base_name}.#{target_format.downcase}")
+    end
+
+    # Parse HTTP response
+    #
+    # @param response [HTTParty::Response] HTTP response
+    #
+    # @return [Hash] Parsed JSON response
+    #
+    def parse_response(response)
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      raise APIError, "Invalid API response: #{response.body}"
+    end
+
+    # Emit event to registered callbacks
+    #
+    # @param event [Symbol] Event name
+    # @param data [Hash] Event data
+    #
+    def emit(event, data)
+      return unless @callbacks[event]
+
+      @callbacks[event].each { |callback| callback.call(data) }
+    end
+  end
+end

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: convertorio-sdk
+version: !ruby/object:Gem::Version
+  version: 1.2.0
+platform: ruby
+authors:
+- Convertorio
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.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'
+description: Ruby SDK for the Convertorio API. Convert images between 20+ formats
+  with just a few lines of code. Supports JPG, PNG, WebP, AVIF, HEIC, GIF, BMP, TIFF,
+  ICO, and more.
+email:
+- support@convertorio.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/convertorio.rb
+homepage: https://github.com/SedeSoft/convertorio-sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/SedeSoft/convertorio-sdk
+  source_code_uri: https://github.com/SedeSoft/convertorio-sdk/tree/main/libs/ruby
+  changelog_uri: https://github.com/SedeSoft/convertorio-sdk/blob/main/libs/ruby/CHANGELOG.md
+  documentation_uri: https://github.com/SedeSoft/convertorio-sdk/tree/main/docs/ruby
+  bug_tracker_uri: https://github.com/SedeSoft/convertorio-sdk/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Convertorio SDK for Ruby - Convert images easily with a simple API
+test_files: []