uploadcare-ruby 4.4.2 → 5.0.0.rc1

data/lib/uploadcare/client/addons_accessor.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# High-level add-on execution helpers scoped to a client instance.
+class Uploadcare::Client::AddonsAccessor
+  attr_reader :client
+
+  # @param client [Uploadcare::Client]
+  def initialize(client:)
+    @client = client
+  end
+
+  # @param uuid [String]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::AddonExecution]
+  def aws_rekognition_detect_labels(uuid:, request_options: {})
+    Uploadcare::Resources::AddonExecution.aws_rekognition_detect_labels(
+      uuid: uuid, client: client, request_options: request_options
+    )
+  end
+
+  # @param request_id [String]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::AddonExecution]
+  def aws_rekognition_detect_labels_status(request_id:, request_options: {})
+    Uploadcare::Resources::AddonExecution.aws_rekognition_detect_labels_status(
+      request_id: request_id, client: client, request_options: request_options
+    )
+  end
+
+  # @param uuid [String]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::AddonExecution]
+  def aws_rekognition_detect_moderation_labels(uuid:, request_options: {})
+    Uploadcare::Resources::AddonExecution.aws_rekognition_detect_moderation_labels(
+      uuid: uuid, client: client, request_options: request_options
+    )
+  end
+
+  # @param request_id [String]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::AddonExecution]
+  def aws_rekognition_detect_moderation_labels_status(request_id:, request_options: {})
+    Uploadcare::Resources::AddonExecution.aws_rekognition_detect_moderation_labels_status(
+      request_id: request_id, client: client, request_options: request_options
+    )
+  end
+
+  # @param uuid [String]
+  # @param params [Hash]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::AddonExecution]
+  def uc_clamav_virus_scan(uuid:, params: {}, request_options: {})
+    Uploadcare::Resources::AddonExecution.uc_clamav_virus_scan(
+      uuid: uuid, params: params, client: client, request_options: request_options
+    )
+  end
+
+  # @param request_id [String]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::AddonExecution]
+  def uc_clamav_virus_scan_status(request_id:, request_options: {})
+    Uploadcare::Resources::AddonExecution.uc_clamav_virus_scan_status(
+      request_id: request_id, client: client, request_options: request_options
+    )
+  end
+
+  # @param uuid [String]
+  # @param params [Hash]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::AddonExecution]
+  def remove_bg(uuid:, params: {}, request_options: {})
+    Uploadcare::Resources::AddonExecution.remove_bg(
+      uuid: uuid, params: params, client: client, request_options: request_options
+    )
+  end
+
+  # @param request_id [String]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::AddonExecution]
+  def remove_bg_status(request_id:, request_options: {})
+    Uploadcare::Resources::AddonExecution.remove_bg_status(
+      request_id: request_id, client: client, request_options: request_options
+    )
+  end
+end

data/lib/uploadcare/client/api.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Access to the endpoint-parity REST and Upload API clients for one configuration.
+class Uploadcare::Client::Api
+  attr_reader :config
+
+  # @param config [Uploadcare::Configuration]
+  def initialize(config:)
+    @config = config
+    @memo_mutex = Mutex.new
+  end
+
+  # @return [Uploadcare::Api::Rest]
+  def rest
+    memoized(:@rest) { Uploadcare::Api::Rest.new(config: config) }
+  end
+
+  # @return [Uploadcare::Api::Upload]
+  def upload
+    memoized(:@upload) { Uploadcare::Api::Upload.new(config: config) }
+  end
+
+  private
+
+  def memoized(ivar)
+    cached = instance_variable_get(ivar)
+    return cached if cached
+
+    @memo_mutex.synchronize do
+      instance_variable_get(ivar) || instance_variable_set(ivar, yield)
+    end
+  end
+end

data/lib/uploadcare/client/conversions_accessor.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Entry point for document and video conversion helpers on a client.
+class Uploadcare::Client::ConversionsAccessor
+  attr_reader :client
+
+  # @param client [Uploadcare::Client]
+  def initialize(client:)
+    @client = client
+    @memo_mutex = Mutex.new
+  end
+
+  # @return [Uploadcare::Client::DocumentConversionsAccessor]
+  def documents
+    memoized(:@documents) { Uploadcare::Client::DocumentConversionsAccessor.new(client: client) }
+  end
+
+  # @return [Uploadcare::Client::VideoConversionsAccessor]
+  def videos
+    memoized(:@videos) { Uploadcare::Client::VideoConversionsAccessor.new(client: client) }
+  end
+
+  private
+
+  def memoized(ivar)
+    cached = instance_variable_get(ivar)
+    return cached if cached
+
+    @memo_mutex.synchronize do
+      instance_variable_get(ivar) || instance_variable_set(ivar, yield)
+    end
+  end
+end

data/lib/uploadcare/client/document_conversions_accessor.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# High-level document conversion helpers scoped to a client instance.
+class Uploadcare::Client::DocumentConversionsAccessor
+  attr_reader :client
+
+  # @param client [Uploadcare::Client]
+  def initialize(client:)
+    @client = client
+  end
+
+  # @param uuid [String]
+  # @param format [String, Symbol]
+  # @param options [Hash]
+  # @param request_options [Hash]
+  # @return [Hash]
+  def convert(uuid:, format:, options: {}, request_options: {})
+    Uploadcare::Resources::DocumentConversion.convert_document(
+      params: { uuid: uuid, format: format }, options: options, client: client,
+      request_options: request_options
+    )
+  end
+
+  # @param token [String]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::DocumentConversion]
+  def status(token:, request_options: {})
+    Uploadcare::Resources::DocumentConversion.status(
+      token: token, client: client, request_options: request_options
+    )
+  end
+
+  # @param uuid [String]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::DocumentConversion]
+  def info(uuid:, request_options: {})
+    Uploadcare::Resources::DocumentConversion.info_for(
+      uuid: uuid, client: client, request_options: request_options
+    )
+  end
+end

data/lib/uploadcare/client/file_metadata_accessor.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# File metadata operations scoped to a client instance.
+class Uploadcare::Client::FileMetadataAccessor
+  attr_reader :client
+
+  # @param client [Uploadcare::Client]
+  def initialize(client:)
+    @client = client
+  end
+
+  # @param uuid [String]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::FileMetadata]
+  def index(uuid:, request_options: {})
+    Uploadcare::Resources::FileMetadata.index(uuid: uuid, client: client, request_options: request_options)
+  end
+
+  # @param uuid [String]
+  # @param key [String]
+  # @param request_options [Hash]
+  # @return [String, nil]
+  def show(uuid:, key:, request_options: {})
+    Uploadcare::Resources::FileMetadata.show(uuid: uuid, key: key, client: client,
+                                             request_options: request_options)
+  end
+
+  # @param uuid [String]
+  # @param key [String]
+  # @param value [String]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::FileMetadata]
+  def update(uuid:, key:, value:, request_options: {})
+    Uploadcare::Resources::FileMetadata.update(uuid: uuid, key: key, value: value, client: client,
+                                               request_options: request_options)
+  end
+
+  # @param uuid [String]
+  # @param key [String]
+  # @param request_options [Hash]
+  # @return [nil]
+  def delete(uuid:, key:, request_options: {})
+    Uploadcare::Resources::FileMetadata.delete(uuid: uuid, key: key, client: client,
+                                               request_options: request_options)
+  end
+end

data/lib/uploadcare/client/files_accessor.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# High-level file operations scoped to a client instance.
+class Uploadcare::Client::FilesAccessor
+  attr_reader :client
+
+  # @param client [Uploadcare::Client]
+  def initialize(client:)
+    @client = client
+  end
+
+  # @param uuid [String]
+  # @param params [Hash]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::File]
+  def find(uuid:, params: {}, request_options: {})
+    Uploadcare::Resources::File.find(
+      uuid: uuid, params: params, client: client, request_options: request_options
+    )
+  end
+
+  # @param request_options [Hash]
+  # @param options [Hash]
+  # @return [Uploadcare::Collections::Paginated]
+  def list(request_options: {}, **options)
+    Uploadcare::Resources::File.list(
+      options: options, client: client, request_options: request_options
+    )
+  end
+
+  # @param source [IO, Array<IO>, String]
+  # @param request_options [Hash]
+  # @param options [Hash]
+  # @yield [Hash]
+  # @return [Uploadcare::Resources::File, Array<Uploadcare::Resources::File>, Hash]
+  def upload(source, request_options: {}, **options, &block)
+    client.uploads.upload(source, request_options: request_options, **options, &block)
+  end
+
+  # @param url [String]
+  # @param request_options [Hash]
+  # @param options [Hash]
+  # @return [Uploadcare::Resources::File, Hash]
+  def upload_from_url(url, request_options: {}, **options)
+    client.uploads.upload_from_url(url: url, request_options: request_options, **options)
+  end
+
+  # @param uuids [Array<String>]
+  # @param request_options [Hash]
+  # @return [Uploadcare::BatchResult]
+  def batch_store(uuids:, request_options: {})
+    Uploadcare::Resources::File.batch_store(uuids: uuids, client: client, request_options: request_options)
+  end
+
+  # @param uuids [Array<String>]
+  # @param request_options [Hash]
+  # @return [Uploadcare::BatchResult]
+  def batch_delete(uuids:, request_options: {})
+    Uploadcare::Resources::File.batch_delete(uuids: uuids, client: client, request_options: request_options)
+  end
+
+  # @param source [String]
+  # @param options [Hash]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::File]
+  def copy_to_local(source:, options: {}, request_options: {})
+    Uploadcare::Resources::File.local_copy(
+      source: source, options: options, client: client, request_options: request_options
+    )
+  end
+
+  # @param source [String]
+  # @param target [String]
+  # @param options [Hash]
+  # @param request_options [Hash]
+  # @return [Hash]
+  def copy_to_remote(source:, target:, options: {}, request_options: {})
+    Uploadcare::Resources::File.remote_copy(
+      source: source, target: target, options: options, client: client, request_options: request_options
+    )
+  end
+end

data/lib/uploadcare/client/groups_accessor.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# High-level group operations scoped to a client instance.
+class Uploadcare::Client::GroupsAccessor
+  attr_reader :client
+
+  # @param client [Uploadcare::Client]
+  def initialize(client:)
+    @client = client
+  end
+
+  # @param uuids [Array<String>]
+  # @param request_options [Hash]
+  # @param options [Hash]
+  # @return [Uploadcare::Resources::Group]
+  def create(uuids:, request_options: {}, **options)
+    Uploadcare::Resources::Group.create(
+      uuids: uuids, client: client, request_options: request_options, **options
+    )
+  end
+
+  # @param group_id [String]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::Group]
+  def find(group_id:, request_options: {})
+    Uploadcare::Resources::Group.find(group_id: group_id, client: client, request_options: request_options)
+  end
+
+  # @param request_options [Hash]
+  # @param params [Hash]
+  # @return [Uploadcare::Collections::Paginated]
+  def list(request_options: {}, **params)
+    Uploadcare::Resources::Group.list(params: params, client: client, request_options: request_options)
+  end
+end

data/lib/uploadcare/client/project_accessor.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Project endpoint wrapper scoped to a client instance.
+class Uploadcare::Client::ProjectAccessor
+  attr_reader :client
+
+  # @param client [Uploadcare::Client]
+  def initialize(client:)
+    @client = client
+  end
+
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::Project]
+  def current(request_options: {})
+    Uploadcare::Resources::Project.current(client: client, request_options: request_options)
+  end
+end

data/lib/uploadcare/client/video_conversions_accessor.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# High-level video conversion helpers scoped to a client instance.
+class Uploadcare::Client::VideoConversionsAccessor
+  attr_reader :client
+
+  # @param client [Uploadcare::Client]
+  def initialize(client:)
+    @client = client
+  end
+
+  # @param uuid [String]
+  # @param format [String, Symbol]
+  # @param quality [String, Symbol]
+  # @param options [Hash]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::VideoConversion]
+  def convert(uuid:, format:, quality:, options: {}, request_options: {})
+    Uploadcare::Resources::VideoConversion.convert(
+      params: { uuid: uuid, format: format, quality: quality }, options: options, client: client,
+      request_options: request_options
+    )
+  end
+
+  # @param token [String]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::VideoConversion]
+  def status(token:, request_options: {})
+    Uploadcare::Resources::VideoConversion.status(
+      token: token, client: client, request_options: request_options
+    )
+  end
+end

data/lib/uploadcare/client/webhooks_accessor.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# High-level webhook operations scoped to a client instance.
+class Uploadcare::Client::WebhooksAccessor
+  attr_reader :client
+
+  # @param client [Uploadcare::Client]
+  def initialize(client:)
+    @client = client
+  end
+
+  # @param request_options [Hash]
+  # @return [Array<Uploadcare::Resources::Webhook>]
+  def list(request_options: {})
+    Uploadcare::Resources::Webhook.list(client: client, request_options: request_options)
+  end
+
+  # @param target_url [String]
+  # @param request_options [Hash]
+  # @param options [Hash]
+  # @return [Uploadcare::Resources::Webhook]
+  def create(target_url:, request_options: {}, **options)
+    Uploadcare::Resources::Webhook.create(
+      target_url: target_url, client: client, request_options: request_options, **options
+    )
+  end
+
+  # @param id [String]
+  # @param request_options [Hash]
+  # @param options [Hash]
+  # @return [Uploadcare::Resources::Webhook]
+  def update(id:, request_options: {}, **options)
+    Uploadcare::Resources::Webhook.update(id: id, client: client, request_options: request_options, **options)
+  end
+
+  # @param target_url [String]
+  # @param request_options [Hash]
+  # @return [nil]
+  def delete(target_url:, request_options: {})
+    Uploadcare::Resources::Webhook.delete(target_url: target_url, client: client, request_options: request_options)
+  end
+end

data/lib/uploadcare/client.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# Primary entry point for interacting with the Uploadcare API.
+#
+# Each Client instance owns its own configuration and provides domain-scoped
+# accessors for all API operations. Multiple clients can coexist for
+# multi-account support.
+#
+# @example Basic usage
+#   client = Uploadcare::Client.new(public_key: "pk", secret_key: "sk")
+#   file = client.files.upload(File.open("photo.jpg"), store: true)
+#   file = client.files.find(uuid: "file-uuid")
+#   files = client.files.list(limit: 100)
+#
+# @example Multi-account
+#   account_a = Uploadcare::Client.new(public_key: "a", secret_key: "x")
+#   account_b = Uploadcare::Client.new(public_key: "b", secret_key: "y")
+#
+# @example Raw API access
+#   client.api.rest.files.list(params: { limit: 10 })
+#   client.api.upload.files.direct(file: file_obj)
+class Uploadcare::Client
+  attr_reader :config
+
+  # Build a client bound to a specific configuration.
+  #
+  # @param config [Uploadcare::Configuration, nil] Base configuration to clone
+  # @param options [Hash] Per-client configuration overrides
+  def initialize(config: nil, **options)
+    base_config = config || Uploadcare.configuration
+    @config = base_config.with(**options)
+    @memo_mutex = Mutex.new
+  end
+
+  # Build a new client derived from this client.
+  #
+  # @param options [Hash] Configuration overrides
+  # @return [Uploadcare::Client]
+  def with(**options)
+    self.class.new(config: config, **options)
+  end
+
+  # Access the raw endpoint-parity API.
+  #
+  # @return [Uploadcare::Client::Api]
+  def api
+    memoized(:@api) { Api.new(config: config) }
+  end
+
+  # Access file operations and upload helpers.
+  #
+  # @return [Uploadcare::Client::FilesAccessor]
+  def files
+    memoized(:@files) { FilesAccessor.new(client: self) }
+  end
+
+  # Access group operations.
+  #
+  # @return [Uploadcare::Client::GroupsAccessor]
+  def groups
+    memoized(:@groups) { GroupsAccessor.new(client: self) }
+  end
+
+  # Access upload routing helpers.
+  #
+  # @return [Uploadcare::Operations::UploadRouter]
+  def uploads
+    memoized(:@uploads) { Uploadcare::Operations::UploadRouter.new(client: self) }
+  end
+
+  # Access project operations.
+  #
+  # @return [Uploadcare::Client::ProjectAccessor]
+  def project
+    memoized(:@project) { ProjectAccessor.new(client: self) }
+  end
+
+  # Access webhook operations.
+  #
+  # @return [Uploadcare::Client::WebhooksAccessor]
+  def webhooks
+    memoized(:@webhooks) { WebhooksAccessor.new(client: self) }
+  end
+
+  # Access add-on execution helpers.
+  #
+  # @return [Uploadcare::Client::AddonsAccessor]
+  def addons
+    memoized(:@addons) { AddonsAccessor.new(client: self) }
+  end
+
+  # Access file metadata operations.
+  #
+  # @return [Uploadcare::Client::FileMetadataAccessor]
+  def file_metadata
+    memoized(:@file_metadata) { FileMetadataAccessor.new(client: self) }
+  end
+
+  # Access conversion helpers.
+  #
+  # @return [Uploadcare::Client::ConversionsAccessor]
+  def conversions
+    memoized(:@conversions) { ConversionsAccessor.new(client: self) }
+  end
+
+  # Upload a source through the convenience upload router.
+  #
+  # @param source [IO, Array<IO>, String] File object, file array, or URL
+  # @param request_options [Hash] Per-request HTTP options
+  # @param options [Hash] Upload options
+  # @yield [Hash] Multipart progress callback
+  # @return [Uploadcare::Resources::File, Array<Uploadcare::Resources::File>, Hash]
+  def upload(source, request_options: {}, **options, &block)
+    uploads.upload(source, request_options: request_options, **options, &block)
+  end
+
+  private
+
+  def memoized(ivar)
+    cached = instance_variable_get(ivar)
+    return cached if cached
+
+    @memo_mutex.synchronize do
+      instance_variable_get(ivar) || instance_variable_set(ivar, yield)
+    end
+  end
+end

data/lib/uploadcare/cname_generator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# lib/uploadcare/client/cname_generator.rb
+require 'digest'
+require 'monitor'
+require 'uri'
+
+# CNAME generator for Uploadcare CDN.
+# @see https://uploadcare.com/docs/delivery/cdn
+class Uploadcare::CnameGenerator
+  # CNAME prefix length.
+  CNAME_PREFIX_LEN = 10
+
+  class << self
+    # Build CDN base URL with a generated CNAME prefix.
+    #
+    # @param config [Uploadcare::Configuration]
+    # @return [String]
+    def cdn_base_postfix(config: Uploadcare.configuration)
+      key = [config.cdn_base_postfix, config.public_key]
+      cached = @cdn_base_postfix_cache&.[](key)
+      return cached if cached
+
+      cache_mutex.synchronize do
+        @cdn_base_postfix_cache ||= {}
+        @cdn_base_postfix_cache[key] ||= begin
+          uri = URI.parse(config.cdn_base_postfix)
+          uri.host = "#{generate_cname(public_key: config.public_key)}.#{uri.host}"
+          uri.to_s
+        rescue URI::InvalidURIError => e
+          raise Uploadcare::Exception::ConfigurationError, "Invalid cdn_base_postfix URL: #{e.message}"
+        end
+      end
+    end
+
+    # Generate a CNAME prefix for the current public key.
+    #
+    # @param public_key [String]
+    # @return [String]
+    def generate_cname(public_key: Uploadcare.configuration.public_key)
+      custom_cname(public_key)
+    end
+
+    private
+
+    # Generate CNAME prefix
+    def custom_cname(public_key = Uploadcare.configuration.public_key)
+      raise Uploadcare::Exception::ConfigurationError, "Invalid public_key: #{public_key}" if public_key.nil?
+
+      cached = @custom_cname_cache&.[](public_key)
+      return cached if cached
+
+      cache_mutex.synchronize do
+        @custom_cname_cache ||= {}
+        @custom_cname_cache[public_key] ||= begin
+          sha256_hex = Digest::SHA256.hexdigest(public_key)
+          sha256_hex = sha256_hex.to_i(16)
+          sha256_base36 = sha256_hex.to_s(36)
+          sha256_base36[0, CNAME_PREFIX_LEN]
+        end
+      end
+    end
+
+    def cache_mutex
+      @cache_mutex ||= Monitor.new
+    end
+  end
+end

data/lib/uploadcare/collections/batch_result.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Result object for batch file operations (store/delete).
+#
+# Wraps the response from batch operations and provides access to:
+# - Successfully processed files
+# - Files that encountered problems
+# - Overall operation status
+#
+# @example
+#   result = client.files.batch_store(uuids: ["uuid1", "uuid2"])
+#   result.result.each { |file| puts file.uuid }
+#   result.problems.each { |uuid, error| puts "#{uuid}: #{error}" }
+class Uploadcare::Collections::BatchResult
+  # @return [Integer, nil] HTTP status code of the operation
+  attr_reader :status
+
+  # @return [Array<Uploadcare::Resources::File>] Successfully processed File objects
+  attr_reader :result
+
+  # @return [Hash] Hash mapping UUIDs to error messages
+  attr_reader :problems
+
+  # Initialize a new BatchResult.
+  #
+  # @param status [Integer, nil] HTTP status code
+  # @param result [Array<Hash>] Array of file data hashes from the API
+  # @param problems [Hash] Hash of UUIDs to error messages
+  # @param client [Uploadcare::Client] Client for creating File objects
+  def initialize(status:, result:, problems:, client:)
+    @status = status
+    @result = result ? result.map { |file_data| Uploadcare::Resources::File.new(file_data, client) } : []
+    @problems = problems || {}
+  end
+end