uploadcare-ruby 4.4.3 → 5.0.0.rc1

data/examples/README.md

@@ -0,0 +1,39 @@
+# Workflow Examples
+
+This directory contains higher-level workflow demos built on the public client API.
+
+For endpoint-by-endpoint coverage, use [api_examples/README.md](../api_examples/README.md).
+
+## Setup
+
+```bash
+export UPLOADCARE_PUBLIC_KEY=your_public_key
+export UPLOADCARE_SECRET_KEY=your_secret_key
+```
+
+Run scripts with project-managed Ruby:
+
+```bash
+mise exec -- ruby examples/simple_upload.rb spec/fixtures/kitten.jpeg
+```
+
+## Scripts
+
+- `examples/simple_upload.rb`
+  Upload one file and print its UUID and CDN URL.
+- `examples/upload_with_progress.rb`
+  Upload one large file with multipart progress reporting.
+- `examples/batch_upload.rb`
+  Upload multiple files in one call.
+- `examples/large_file_upload.rb`
+  Force multipart upload and show throughput details.
+- `examples/url_upload.rb`
+  Upload a remote URL and show async polling as a follow-up example.
+- `examples/group_creation.rb`
+  Upload multiple files, create a group, and print group details.
+
+## Notes
+
+- These are workflow demos.
+- The canonical API inventory lives in `api_examples/`.
+- The examples assume real Uploadcare credentials and network access.

data/examples/batch_upload.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/uploadcare'
+require 'dotenv/load'
+
+file_paths = ARGV
+
+if file_paths.empty?
+  puts 'Usage: ruby batch_upload.rb <file1> <file2> <file3> ...'
+  puts 'Example: ruby batch_upload.rb photo1.jpg photo2.jpg photo3.jpg'
+  exit 1
+end
+
+file_paths.each do |path|
+  unless File.exist?(path)
+    puts "Error: File not found: #{path}"
+    exit 1
+  end
+end
+
+puts "Batch Upload - #{file_paths.length} files"
+puts '=' * 50
+puts
+
+files = file_paths.map { |path| File.open(path, 'rb') }
+
+begin
+  client = Uploadcare::Client.new(
+    public_key: ENV.fetch('UPLOADCARE_PUBLIC_KEY'),
+    secret_key: ENV.fetch('UPLOADCARE_SECRET_KEY')
+  )
+
+  results = client.uploads.upload(files, store: true)
+
+  puts '✓ Batch upload complete!'
+  puts
+  puts 'Results:'
+  puts '-' * 50
+
+  results.each_with_index do |file, index|
+    puts "#{index + 1}. #{file.original_filename}"
+    puts "   UUID: #{file.uuid}"
+    puts "   CDN URL: #{file.cdn_url}"
+    puts
+  end
+
+  puts "Successfully uploaded #{results.length} files"
+rescue StandardError => e
+  puts "✗ Batch upload failed: #{e.message}"
+  exit 1
+ensure
+  files.each(&:close)
+end

data/examples/group_creation.rb

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/uploadcare'
+require 'dotenv/load'
+
+file_paths = ARGV
+
+if file_paths.empty?
+  script_name = File.basename($PROGRAM_NAME)
+  puts "Usage: ruby examples/#{script_name} <file1> <file2> <file3> ..."
+  puts "Example: ruby examples/#{script_name} photo1.jpg photo2.jpg photo3.jpg"
+  exit 1
+end
+
+file_paths.each do |path|
+  unless File.exist?(path)
+    puts "Error: File not found: #{path}"
+    exit 1
+  end
+end
+
+puts "Group Creation - #{file_paths.length} files"
+puts '=' * 50
+puts
+
+begin
+  client = Uploadcare::Client.new(
+    public_key: ENV.fetch('UPLOADCARE_PUBLIC_KEY'),
+    secret_key: ENV.fetch('UPLOADCARE_SECRET_KEY')
+  )
+
+  puts 'Step 1: Uploading files...'
+  uuids = []
+
+  file_paths.each_with_index do |path, index|
+    uploaded = File.open(path, 'rb') do |file|
+      client.files.upload(file, store: true)
+    end
+
+    uuids << uploaded.uuid
+    puts "  #{index + 1}. #{File.basename(path)} → #{uploaded.uuid}"
+  end
+
+  puts
+  puts "✓ Uploaded #{uuids.length} files"
+  puts
+
+  puts 'Step 2: Creating group...'
+  group = client.groups.create(uuids: uuids)
+
+  puts '✓ Group created!'
+  puts
+  puts 'Group Details:'
+  puts '-' * 50
+  puts "Group ID: #{group.id}"
+  puts "Files count: #{group.files_count}"
+  puts "CDN URL: #{group.cdn_url}"
+  puts "Created at: #{group.datetime_created}"
+  puts
+
+  puts 'Step 3: Retrieving group info...'
+  info = client.groups.find(group_id: group.id)
+
+  puts '✓ Group info retrieved'
+  puts
+  puts 'Files in group:'
+  puts '-' * 50
+
+  Array(info.files).each_with_index do |file, index|
+    file_resource = Uploadcare::Resources::File.new(file, client)
+    puts "#{index + 1}. #{file_resource.original_filename}"
+    puts "   UUID: #{file_resource.uuid}"
+    puts "   Size: #{(file_resource.size / 1024.0).round(2)} KB"
+    puts "   URL: #{file_resource.cdn_url}"
+    puts
+  end
+
+  puts 'Group URL:'
+  puts group.cdn_url
+  puts
+  puts 'You can access individual files in the group:'
+  puts "#{group.cdn_url}nth/0/"
+  puts "#{group.cdn_url}nth/1/"
+rescue StandardError => e
+  puts "✗ Group creation failed: #{e.message}"
+  exit 1
+end

data/examples/large_file_upload.rb

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/uploadcare'
+require 'dotenv/load'
+
+file_path = ARGV[0]
+threads = (ARGV[1] || 4).to_i
+
+unless file_path && File.exist?(file_path)
+  puts 'Usage: ruby large_file_upload.rb <file_path> [threads]'
+  puts 'Example: ruby large_file_upload.rb large_video.mp4 4'
+  puts
+  puts 'threads: Number of parallel upload threads (default: 4)'
+  exit 1
+end
+
+file_size = File.size(file_path)
+file_size_mb = (file_size / 1024.0 / 1024.0).round(2)
+
+if file_size < 10_000_000
+  puts 'Warning: File is < 10MB. Multipart upload is recommended for files >= 10MB'
+  puts 'The upload will still work but may use base upload instead.'
+  puts
+end
+
+puts 'Large File Upload'
+puts '=' * 50
+puts "File: #{file_path}"
+puts "Size: #{file_size_mb} MB"
+puts "Threads: #{threads}"
+puts
+
+begin
+  client = Uploadcare::Client.new(
+    public_key: ENV.fetch('UPLOADCARE_PUBLIC_KEY'),
+    secret_key: ENV.fetch('UPLOADCARE_SECRET_KEY')
+  )
+
+  start_time = Time.now
+  result = nil
+
+  File.open(file_path, 'rb') do |file|
+    result = client.uploads.multipart_upload(
+      file: file,
+      store: true,
+      threads: threads,
+      metadata: {
+        source: 'large_file_example',
+        upload_method: 'multipart'
+      }
+    ) do |progress|
+      uploaded_mb = (progress[:uploaded] / 1024.0 / 1024.0).round(2)
+      total_mb = (progress[:total] / 1024.0 / 1024.0).round(2)
+      percentage = ((progress[:uploaded].to_f / progress[:total]) * 100).round
+      part = progress[:part]
+      total_parts = progress[:total_parts]
+
+      bar_length = 30
+      filled = (bar_length * percentage / 100).to_i
+      bar = ('#' * filled) + ('.' * (bar_length - filled))
+
+      print "\r#{bar} #{percentage}% | Part #{part}/#{total_parts} | #{uploaded_mb}/#{total_mb} MB"
+      $stdout.flush
+    end
+  end
+
+  elapsed = Time.now - start_time
+
+  puts
+  puts
+  puts '✓ Upload successful!'
+  puts
+  puts 'Upload Details:'
+  puts '-' * 50
+  puts "UUID: #{result.uuid}"
+  puts "Size: #{file_size_mb} MB"
+  puts "Time: #{elapsed.round(2)} seconds"
+  puts "Speed: #{(file_size_mb / elapsed).round(2)} MB/s"
+  puts "Threads: #{threads}"
+  puts 'Method: Multipart upload'
+  puts
+  puts "CDN URL: #{result.cdn_url}"
+rescue StandardError => e
+  puts
+  puts "✗ Upload failed: #{e.message}"
+  exit 1
+end

data/examples/simple_upload.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/uploadcare'
+require 'dotenv/load'
+
+file_path = ARGV[0]
+
+unless file_path && File.exist?(file_path)
+  puts 'Usage: ruby simple_upload.rb <file_path>'
+  puts 'Example: ruby simple_upload.rb photo.jpg'
+  exit 1
+end
+
+puts "Uploading: #{file_path}"
+puts "Size: #{(File.size(file_path) / 1024.0).round(2)} KB"
+puts
+
+begin
+  client = Uploadcare::Client.new(
+    public_key: ENV.fetch('UPLOADCARE_PUBLIC_KEY'),
+    secret_key: ENV.fetch('UPLOADCARE_SECRET_KEY')
+  )
+
+  uploaded_file = File.open(file_path, 'rb') do |file|
+    client.files.upload(file, store: true)
+  end
+
+  puts '✓ Upload successful!'
+  puts
+  puts "UUID: #{uploaded_file.uuid}"
+  puts "Filename: #{uploaded_file.original_filename}"
+  puts "CDN URL: #{uploaded_file.cdn_url}"
+  puts
+  puts 'The file has been stored and is ready to use.'
+rescue StandardError => e
+  puts "✗ Upload failed: #{e.message}"
+  exit 1
+end

data/examples/upload_with_progress.rb

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/uploadcare'
+require 'dotenv/load'
+
+file_path = ARGV[0]
+script_name = File.basename($PROGRAM_NAME)
+multipart_threshold = 10 * 1024 * 1024
+
+unless file_path && File.exist?(file_path)
+  puts "Usage: ruby examples/#{script_name} <file_path>"
+  puts "Example: ruby examples/#{script_name} large_video.mp4"
+  puts
+  puts 'Note: Progress tracking works best with files >= 10 MiB'
+  exit 1
+end
+
+file_size = File.size(file_path)
+file_size_mb = (file_size / 1024.0 / 1024.0).round(2)
+
+puts "Uploading: #{file_path}"
+puts "Size: #{file_size_mb} MB"
+puts
+
+if file_size < multipart_threshold
+  puts 'Note: File is < 10 MiB, so the upload may complete without multipart progress updates'
+  puts
+end
+
+file = nil
+
+begin
+  client = Uploadcare::Client.new(
+    public_key: ENV.fetch('UPLOADCARE_PUBLIC_KEY'),
+    secret_key: ENV.fetch('UPLOADCARE_SECRET_KEY')
+  )
+
+  file = File.open(file_path, 'rb')
+  start_time = Time.now
+
+  result = client.uploads.upload(file, store: true) do |progress|
+    uploaded_mb = (progress[:uploaded] / 1024.0 / 1024.0).round(2)
+    total_mb = (progress[:total] / 1024.0 / 1024.0).round(2)
+    percentage = ((progress[:uploaded].to_f / progress[:total]) * 100).round
+    part = progress[:part]
+    total_parts = progress[:total_parts]
+
+    elapsed = Time.now - start_time
+    speed_mbps = uploaded_mb / elapsed
+    remaining_mb = total_mb - uploaded_mb
+    eta_seconds = remaining_mb / speed_mbps if speed_mbps.positive?
+
+    bar_length = 40
+    filled = (bar_length * percentage / 100).to_i
+    bar = ('#' * filled) + ('.' * (bar_length - filled))
+
+    print "\r#{bar} #{percentage}% | "
+    print "#{uploaded_mb}/#{total_mb} MB | "
+    print "Part #{part}/#{total_parts} | "
+    print "Speed: #{speed_mbps.round(2)} MB/s"
+    print " | ETA: #{eta_seconds.to_i}s" if eta_seconds
+    $stdout.flush
+  end
+
+  elapsed = Time.now - start_time
+
+  puts
+  puts
+  puts '✓ Upload successful!'
+  puts
+  puts "UUID: #{result.uuid}"
+  puts "Filename: #{result.original_filename}"
+  puts "Total time: #{elapsed.round(2)} seconds"
+  puts "Average speed: #{(file_size_mb / elapsed).round(2)} MB/s"
+  puts
+  puts "CDN URL: #{result.cdn_url}"
+rescue StandardError => e
+  puts
+  puts "✗ Upload failed: #{e.message}"
+  exit 1
+ensure
+  file&.close
+end

data/examples/url_upload.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/uploadcare'
+require 'dotenv/load'
+
+url = ARGV[0]
+
+unless url&.match?(%r{^https?://})
+  puts 'Usage: ruby url_upload.rb <url>'
+  puts 'Example: ruby url_upload.rb https://example.com/image.jpg'
+  exit 1
+end
+
+puts 'URL Upload'
+puts '=' * 50
+puts "URL: #{url}"
+puts
+
+begin
+  client = Uploadcare::Client.new(
+    public_key: ENV.fetch('UPLOADCARE_PUBLIC_KEY'),
+    secret_key: ENV.fetch('UPLOADCARE_SECRET_KEY')
+  )
+
+  puts 'Starting upload...'
+  result = client.files.upload_from_url(url, store: true)
+
+  puts '✓ Upload successful!'
+  puts
+  puts "UUID: #{result.uuid}"
+  puts "Filename: #{result.original_filename}"
+  puts "Size: #{(result.size / 1024.0).round(2)} KB"
+  puts "MIME type: #{result.mime_type}"
+  puts
+  puts "CDN URL: #{result.cdn_url}"
+  puts
+  puts 'Advanced Usage:'
+  puts
+  puts '# Async mode (returns immediately with token):'
+  puts 'client = Uploadcare::Client.new(public_key: "...", secret_key: "...")'
+  puts "response = client.uploads.upload_from_url(url: '#{url}', async: true)"
+  puts "token = response['token']"
+  puts
+  puts '# Check status later:'
+  puts 'status = client.uploads.upload_from_url_status(token: token)'
+  puts "puts status['status']"
+rescue StandardError => e
+  puts "✗ Upload failed: #{e.message}"
+  puts
+  puts 'Common issues:'
+  puts '- URL must be publicly accessible'
+  puts '- URL must return a valid file'
+  puts '- Some file types may not be supported'
+  exit 1
+end

data/lib/uploadcare/api/rest/addons.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# REST API endpoint for add-on operations.
+#
+# Supports AWS Rekognition (labels & moderation), ClamAV virus scan, and Remove.bg.
+#
+# @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Add-Ons
+class Uploadcare::Api::Rest::Addons
+  # @return [Uploadcare::Api::Rest] Parent REST client
+  attr_reader :rest
+
+  # @param rest [Uploadcare::Api::Rest] Parent REST client
+  def initialize(rest:)
+    @rest = rest
+  end
+
+  # Execute AWS Rekognition label detection.
+  #
+  # @param uuid [String] File UUID to process
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Hash with request_id
+  # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Add-Ons/operation/awsRekognitionExecute
+  def aws_rekognition_detect_labels(uuid:, request_options: {})
+    rest.post(path: '/addons/aws_rekognition_detect_labels/execute/',
+              params: { target: uuid }, headers: {}, request_options: request_options)
+  end
+
+  # Check AWS Rekognition label detection status.
+  #
+  # @param request_id [String] Request ID from execution
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Hash with status
+  # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Add-Ons/operation/awsRekognitionExecutionStatus
+  def aws_rekognition_detect_labels_status(request_id:, request_options: {})
+    rest.get(path: '/addons/aws_rekognition_detect_labels/execute/status/',
+             params: { request_id: request_id }, headers: {}, request_options: request_options)
+  end
+
+  # Execute AWS Rekognition moderation label detection.
+  #
+  # @param uuid [String] File UUID to process
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Hash with request_id
+  # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Add-Ons/operation/awsRekognitionDetectModerationLabelsExecute
+  def aws_rekognition_detect_moderation_labels(uuid:, request_options: {})
+    rest.post(path: '/addons/aws_rekognition_detect_moderation_labels/execute/',
+              params: { target: uuid }, headers: {}, request_options: request_options)
+  end
+
+  # Check AWS Rekognition moderation label detection status.
+  #
+  # @param request_id [String] Request ID from execution
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Hash with status
+  # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Add-Ons/operation/awsRekognitionDetectModerationLabelsExecutionStatus
+  def aws_rekognition_detect_moderation_labels_status(request_id:, request_options: {})
+    rest.get(path: '/addons/aws_rekognition_detect_moderation_labels/execute/status/',
+             params: { request_id: request_id }, headers: {}, request_options: request_options)
+  end
+
+  # Execute ClamAV virus scan.
+  #
+  # @param uuid [String] File UUID to process
+  # @param params [Hash] Optional scan parameters
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Hash with request_id
+  # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Add-Ons/operation/ucClamavVirusScanExecute
+  def uc_clamav_virus_scan(uuid:, params: {}, request_options: {})
+    body = { target: uuid }.merge(params)
+    rest.post(path: '/addons/uc_clamav_virus_scan/execute/', params: body, headers: {},
+              request_options: request_options)
+  end
+
+  # Check ClamAV virus scan status.
+  #
+  # @param request_id [String] Request ID from execution
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Hash with status
+  # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Add-Ons/operation/ucClamavVirusScanExecutionStatus
+  def uc_clamav_virus_scan_status(request_id:, request_options: {})
+    rest.get(path: '/addons/uc_clamav_virus_scan/execute/status/',
+             params: { request_id: request_id }, headers: {}, request_options: request_options)
+  end
+
+  # Execute Remove.bg background removal.
+  #
+  # @param uuid [String] File UUID to process
+  # @param params [Hash] Optional parameters for the add-on
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Hash with request_id
+  # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Add-Ons/operation/removeBgExecute
+  def remove_bg(uuid:, params: {}, request_options: {})
+    rest.post(path: '/addons/remove_bg/execute/',
+              params: { target: uuid, params: params }, headers: {}, request_options: request_options)
+  end
+
+  # Check Remove.bg execution status.
+  #
+  # @param request_id [String] Request ID from execution
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Hash with status and result
+  # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Add-Ons/operation/removeBgExecutionStatus
+  def remove_bg_status(request_id:, request_options: {})
+    rest.get(path: '/addons/remove_bg/execute/status/',
+             params: { request_id: request_id }, headers: {}, request_options: request_options)
+  end
+end

data/lib/uploadcare/api/rest/document_conversions.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# REST API endpoint for document conversion operations.
+#
+# @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Conversion
+class Uploadcare::Api::Rest::DocumentConversions
+  # @return [Uploadcare::Api::Rest] Parent REST client
+  attr_reader :rest
+
+  # @param rest [Uploadcare::Api::Rest] Parent REST client
+  def initialize(rest:)
+    @rest = rest
+  end
+
+  # Get document format information and possible conversion formats.
+  #
+  # @param uuid [String] Document file UUID
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Document format info
+  # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Conversion/operation/documentConvertInfo
+  def info(uuid:, request_options: {})
+    encoded_uuid = URI.encode_www_form_component(uuid.to_s)
+    rest.get(path: "/convert/document/#{encoded_uuid}/", params: {}, headers: {},
+             request_options: request_options)
+  end
+
+  # Convert a document to a specified format.
+  #
+  # @param paths [Array<String>] Conversion paths (e.g., ["uuid/document/-/format/pdf/"])
+  # @param options [Hash] Optional parameters (:store, :save_in_group)
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Conversion details with result and problems
+  # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Conversion/operation/documentConvert
+  def convert(paths:, options: {}, request_options: {})
+    body = { paths: paths }
+    body[:store] = normalize_bool_param(options[:store]) if options.key?(:store)
+    body[:save_in_group] = normalize_bool_param(options[:save_in_group]) if options.key?(:save_in_group)
+    body.compact!
+
+    rest.post(path: '/convert/document/', params: body, headers: {}, request_options: request_options)
+  end
+
+  # Get document conversion job status.
+  #
+  # @param token [String, Integer] Conversion job token
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Result] Job status and result
+  # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Conversion/operation/documentConvertStatus
+  def status(token:, request_options: {})
+    rest.get(path: "/convert/document/status/#{token}/", params: {}, headers: {},
+             request_options: request_options)
+  end
+
+  private
+
+  def normalize_bool_param(value)
+    normalized = value.is_a?(String) ? value.strip.downcase : value
+
+    case normalized
+    when true, 1, '1', 'true' then '1'
+    when false, 0, '0', 'false' then '0'
+    else value
+    end
+  end
+end