sirv_rest_api 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7988f44acfb48928112d2a3f31248e986d17dcaf89e92958d801c7dfb6df2c61
+  data.tar.gz: b9d7df63ec359638f85eca234d9738bd59ffd4151e98d5787e8080f91d466fbe
+SHA512:
+  metadata.gz: 5dbcaa95009de205b9840857f30f4a4f9036035ce6ac456b766e97bd3e8e9ee0506413c300d08eb26a091853e95e986d14ed015253f309d49a1b82e2b7864a83
+  data.tar.gz: 0c8613b0eee94fa033d99189484196ee6be94f5510ea068ddad5f9ed19893fda037e682eaa2d5f79091587cf4a73a95a07d63f6d84a548e940ac16e30f3c7db7

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sirv Ltd
+
+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,305 @@
+# Sirv REST API Ruby SDK
+
+Official Ruby SDK for the [Sirv REST API](https://apidocs.sirv.com/). Provides a simple, type-safe way to interact with Sirv's image hosting and processing platform.
+
+## Features
+
+- Complete coverage of all 40+ Sirv REST API endpoints
+- Automatic token management with configurable expiry
+- Thread-safe client
+- Retry logic with exponential backoff
+- Comprehensive model classes
+- Iterator patterns for paginated results
+- Zero external dependencies (uses Ruby stdlib only)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sirv_rest_api'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install sirv_rest_api
+```
+
+## Requirements
+
+- Ruby 2.7 or later
+
+## Quick Start
+
+```ruby
+require 'sirv_rest_api'
+
+# Create client
+client = SirvRestApi::Client.new(
+  client_id: 'your-client-id',
+  client_secret: 'your-client-secret'
+)
+
+# Connect (authenticate)
+token = client.connect
+puts "Connected! Token expires in #{token.expires_in} seconds"
+
+# Get account info
+account = client.get_account_info
+puts "Account: #{account.alias}"
+puts "CDN URL: #{account.cdn_url}"
+
+# List folder contents
+folder = client.read_folder_contents('/')
+folder.contents.each do |item|
+  type = item.directory? ? '[DIR]' : '[FILE]'
+  puts "#{type} #{item.filename}"
+end
+```
+
+## Configuration
+
+```ruby
+client = SirvRestApi::Client.new(
+  # Required
+  client_id: 'your-client-id',
+  client_secret: 'your-client-secret',
+
+  # Optional
+  base_url: 'https://api.sirv.com',  # Default
+  auto_refresh_token: true,           # Default: true
+  token_refresh_buffer: 60,           # Seconds before expiry to refresh (default: 60)
+  timeout: 30,                         # Request timeout in seconds (default: 30)
+  max_retries: 3                       # Max retries on 5xx errors (default: 3)
+)
+```
+
+## Custom Token Expiry
+
+You can customize how long the token is valid (5-604800 seconds):
+
+```ruby
+# Request a token valid for 1 hour (3600 seconds)
+token = client.connect(expires_in: 3600)
+
+# Request a token valid for 7 days (604800 seconds)
+token = client.connect(expires_in: 604800)
+```
+
+## API Reference
+
+### Authentication
+
+```ruby
+# Connect and get token
+token = client.connect
+token = client.connect(expires_in: 3600)  # Custom expiry
+
+# Check connection status
+client.connected?
+
+# Get current token
+client.access_token
+```
+
+### Account Operations
+
+```ruby
+# Get account info
+account = client.get_account_info
+
+# Update account settings
+client.update_account(minify: { enabled: true })
+
+# Get rate limits
+limits = client.get_account_limits
+
+# Get storage info
+storage = client.get_storage_info
+
+# Get billing plan
+plan = client.get_billing_plan
+
+# Get account users
+users = client.get_account_users
+
+# Search events
+events = client.search_events(level: 'error', from: '2024-01-01')
+```
+
+### File Operations
+
+```ruby
+# Get file info
+info = client.get_file_info('/path/to/file.jpg')
+
+# Read folder contents
+folder = client.read_folder_contents('/my-folder')
+
+# Iterate folder (handles pagination)
+client.each_folder_item('/my-folder') do |file|
+  puts file.filename
+end
+
+# Search files
+results = client.search_files(query: '*.jpg', size: 10)
+
+# Iterate search results (handles pagination)
+client.each_search_result(query: '*') do |file|
+  puts file.filename
+end
+
+# Upload file
+client.upload_file('/path/to/dest.jpg', File.binread('./image.jpg'))
+
+# Upload from local path
+client.upload_file_from_path('/path/to/dest.jpg', './local-file.jpg')
+
+# Download file
+content = client.download_file('/path/to/file.jpg')
+
+# Download file to local path
+client.download_file_to('/path/to/file.jpg', './local-file.jpg')
+
+# Create folder
+client.create_folder('/new-folder')
+
+# Delete file
+client.delete_file('/path/to/file.jpg')
+
+# Copy file
+client.copy_file(from: '/source.jpg', to: '/dest.jpg')
+
+# Rename/move file
+client.rename_file(from: '/old.jpg', to: '/new.jpg')
+
+# Fetch from URL
+client.fetch_url(url: 'https://example.com/image.jpg', filename: '/fetched/image.jpg')
+```
+
+### Metadata Operations
+
+```ruby
+# Get file metadata
+meta = client.get_file_meta('/path/to/file.jpg')
+
+# Set file metadata
+client.set_file_meta('/path/to/file.jpg', {
+  title: 'My Image',
+  description: 'A beautiful image',
+  tags: ['nature', 'landscape']
+})
+
+# Get/set individual metadata fields
+title = client.get_file_title('/path/to/file.jpg')
+client.set_file_title('/path/to/file.jpg', 'New Title')
+
+tags = client.get_file_tags('/path/to/file.jpg')
+client.add_file_tags('/path/to/file.jpg', ['tag1', 'tag2'])
+client.remove_file_tags('/path/to/file.jpg', ['tag1'])
+
+# Product metadata
+product = client.get_product_meta('/path/to/file.jpg')
+client.set_product_meta('/path/to/file.jpg', {
+  name: 'Product Name',
+  sku: 'SKU-123',
+  brand: 'Brand Name'
+})
+
+# Approval flag
+approved = client.get_approval_flag('/path/to/file.jpg')
+client.set_approval_flag('/path/to/file.jpg', true)
+```
+
+### JWT Protected URLs
+
+```ruby
+jwt = client.generate_jwt(filename: '/protected/image.jpg', expires_in: 3600)
+puts "Protected URL: #{jwt.url}"
+```
+
+### Spins/360 Operations
+
+```ruby
+# Convert spin to video
+video_file = client.spin_to_video('/spin/product.spin', options: {
+  width: 800,
+  height: 600
+})
+
+# Convert video to spin
+spin_file = client.video_to_spin('/video/product.mp4')
+
+# Export spin to marketplaces
+client.export_spin_to_amazon(filename: '/spin/product.spin', asin: 'B01234567')
+client.export_spin_to_walmart(filename: '/spin/product.spin')
+client.export_spin_to_home_depot(filename: '/spin/product.spin')
+client.export_spin_to_lowes(filename: '/spin/product.spin')
+client.export_spin_to_grainger(filename: '/spin/product.spin')
+```
+
+### Statistics
+
+```ruby
+# HTTP transfer stats
+http_stats = client.get_http_stats(from: '2024-01-01', to: '2024-01-31')
+
+# Spin views stats (max 5-day range)
+spin_stats = client.get_spin_views_stats(from: '2024-01-01', to: '2024-01-05')
+
+# Storage stats
+storage_stats = client.get_storage_stats(from: '2024-01-01', to: '2024-01-31')
+```
+
+## Error Handling
+
+```ruby
+begin
+  account = client.get_account_info
+rescue SirvRestApi::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue SirvRestApi::NotFoundError => e
+  puts "Not found: #{e.message}"
+rescue SirvRestApi::RateLimitError => e
+  puts "Rate limit exceeded: #{e.message}"
+rescue SirvRestApi::ApiError => e
+  puts "API error: #{e.message} (status #{e.status_code})"
+end
+```
+
+## Thread Safety
+
+The client is thread-safe and can be used from multiple threads:
+
+```ruby
+threads = 10.times.map do |i|
+  Thread.new do
+    info = client.get_file_info("/file#{i}.jpg")
+    puts info.filename
+  end
+end
+threads.each(&:join)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Sirv Website](https://sirv.com)
+- [API Documentation](https://apidocs.sirv.com/)
+- [Sirv Help Center](https://sirv.com/help/)

data/Rakefile

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test
+
+desc "Run tests with real credentials"
+task :test_live do
+  ruby "test/live_test.rb"
+end
+
+desc "Generate YARD documentation"
+task :doc do
+  sh "yard doc lib/**/*.rb"
+end
+
+desc "Build the gem"
+task :build do
+  sh "gem build sirv_rest_api.gemspec"
+end