uploadcare-ruby 4.4.3 → 5.0.0.rc1

data/lib/uploadcare/resources/base_resource.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Base class for all Uploadcare resource objects.
+#
+# Resources represent domain objects returned by the Uploadcare API.
+# They hold attributes and a reference to the client that created them,
+# enabling instance methods to make further API calls.
+class Uploadcare::Resources::BaseResource
+  # @return [Uploadcare::Client] Client that created this resource
+  attr_reader :client
+
+  # @return [Uploadcare::Configuration] Configuration from the client
+  attr_reader :config
+
+  # Initialize a new resource with attributes and client context.
+  #
+  # @param attributes [Hash] API response attributes
+  # @param client_or_config [Uploadcare::Client, Uploadcare::Configuration, nil]
+  def initialize(attributes = {}, client_or_config = nil)
+    @client = self.class.resolve_client(client_or_config)
+    @config = @client.config
+    assign_attributes(attributes)
+  end
+
+  protected
+
+  # Assign hash attributes to instance variables via setter methods.
+  #
+  # @param attributes [Hash] Key-value pairs to assign
+  def assign_attributes(attributes)
+    attributes.each do |key, value|
+      setter = "#{key}="
+      public_send(setter, value) if respond_to?(setter)
+    end
+  end
+
+  class << self
+    # Resolve a client from various input types.
+    #
+    # @param client_or_config [Uploadcare::Client, Uploadcare::Configuration, nil]
+    # @param client [Uploadcare::Client, nil] Explicit client
+    # @param config [Uploadcare::Configuration] Configuration fallback
+    # @return [Uploadcare::Client]
+    def resolve_client(client_or_config = nil, client: nil, config: nil)
+      return client if client
+
+      case client_or_config
+      when Uploadcare::Client
+        client_or_config
+      when Uploadcare::Configuration
+        Uploadcare.client(config: client_or_config)
+      when nil
+        return Uploadcare.client(config: config) if config
+
+        raise ArgumentError, 'client or config is required'
+      else
+        raise ArgumentError, 'client or config is required'
+      end
+    end
+  end
+end

data/lib/uploadcare/resources/document_conversion.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Document conversion resource.
+#
+# @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Conversion
+class Uploadcare::Resources::DocumentConversion < Uploadcare::Resources::BaseResource
+  attr_accessor :uuid, :error, :format, :converted_groups, :status, :result
+
+  # Get document format info and possible conversions.
+  #
+  # @param request_options [Hash] Request options
+  # @return [self]
+  def info(request_options: {})
+    raise ArgumentError, 'uuid is required' if uuid.to_s.empty?
+
+    response = Uploadcare::Result.unwrap(
+      client.api.rest.document_conversions.info(uuid: uuid, request_options: request_options)
+    )
+    assign_attributes(response)
+    self
+  end
+
+  # Convert a document to a specified format (class method).
+  #
+  # @param params [Hash] Conversion parameters (:uuid, :format)
+  # @param options [Hash] Optional parameters (:store, :save_in_group)
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param request_options [Hash] Request options
+  # @return [Hash] Conversion response
+  def self.convert_document(params:, options: {}, client: nil, config: Uploadcare.configuration,
+                            request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    paths = Array(params[:uuid]).map do |uuid|
+      "#{uuid}/document/-/format/#{params[:format]}/"
+    end
+
+    Uploadcare::Result.unwrap(
+      resolved_client.api.rest.document_conversions.convert(
+        paths: paths, options: options, request_options: request_options
+      )
+    )
+  end
+
+  # Fetch document conversion status for a job token.
+  #
+  # @param token [String]
+  # @param client [Uploadcare::Client, nil]
+  # @param config [Uploadcare::Configuration]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::DocumentConversion]
+  def self.status(token:, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    new({}, resolved_client).fetch_status(token: token, request_options: request_options)
+  end
+
+  # Fetch document conversion capabilities for a file.
+  #
+  # @param uuid [String]
+  # @param client [Uploadcare::Client, nil]
+  # @param config [Uploadcare::Configuration]
+  # @param request_options [Hash]
+  # @return [Uploadcare::Resources::DocumentConversion]
+  def self.info_for(uuid:, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    new({ 'uuid' => uuid }, resolved_client).info(request_options: request_options)
+  end
+
+  # Get conversion job status.
+  #
+  # @param token [String] Job token
+  # @param request_options [Hash] Request options
+  # @return [self]
+  def fetch_status(token:, request_options: {})
+    response = Uploadcare::Result.unwrap(
+      client.api.rest.document_conversions.status(token: token, request_options: request_options)
+    )
+    assign_attributes(response)
+    self
+  end
+end

data/lib/uploadcare/resources/file.rb

@@ -0,0 +1,366 @@
+# frozen_string_literal: true
+
+# File resource representing an uploaded file in Uploadcare.
+#
+# Provides both class methods (find, list, upload, batch operations, copy)
+# and instance methods (store, delete, reload, convert) for working with files.
+#
+# @example Finding a file
+#   client = Uploadcare.client
+#   file = client.files.find(uuid: "file-uuid")
+#   file.original_filename  # => "photo.jpg"
+#
+# @example Uploading
+#   client = Uploadcare.client
+#   file = client.files.upload(::File.open("photo.jpg"), store: true)
+#
+# @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/File
+class Uploadcare::Resources::File < Uploadcare::Resources::BaseResource
+  # API fields assigned onto file resources.
+  ATTRIBUTES = %i[
+    datetime_removed datetime_stored datetime_uploaded is_image is_ready mime_type original_file_url
+    original_filename size url uuid variations content_info metadata appdata source
+  ].freeze
+
+  attr_writer :uuid
+  attr_accessor :datetime_removed, :datetime_stored, :datetime_uploaded, :is_image, :is_ready, :mime_type,
+                :original_file_url, :original_filename, :size, :url, :variations, :content_info,
+                :metadata, :appdata, :source
+
+  # --- Class methods ---
+
+  # Find a file by UUID.
+  #
+  # @param uuid [String] File UUID
+  # @param params [Hash] Optional parameters (e.g., include: "appdata")
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::File]
+  def self.find(uuid:, params: {}, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.rest.files.info(uuid: uuid, params: params, request_options: request_options)
+    )
+    new(response, resolved_client)
+  end
+
+  class << self
+    alias retrieve find
+    alias info find
+  end
+
+  # List files with optional filtering and pagination.
+  #
+  # @param options [Hash] Query parameters (limit, ordering, etc.)
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Collections::Paginated]
+  def self.list(options: {}, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.rest.files.list(params: options, request_options: request_options)
+    )
+
+    files = response['results'].map { |data| new(data, resolved_client) }
+
+    Uploadcare::Collections::Paginated.new(
+      resources: files,
+      next_page: response['next'],
+      previous_page: response['previous'],
+      per_page: response['per_page'],
+      total: response['total'],
+      api_client: resolved_client.api.rest.files,
+      resource_class: self,
+      client: resolved_client,
+      request_options: request_options
+    )
+  end
+
+  # Upload a single file.
+  #
+  # @param file [File, IO] File to upload
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param options [Hash] Upload options
+  # @return [Uploadcare::Resources::File]
+  def self.upload(file, client: nil, config: Uploadcare.configuration, request_options: {}, **options)
+    resolved_client = resolve_client(client: client, config: config)
+    resolved_client.uploads.upload_file(file: file, request_options: request_options, **options)
+  end
+
+  # Upload multiple files.
+  #
+  # @param files [Array<File, IO>] Files to upload
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param options [Hash] Upload options
+  # @return [Array<Uploadcare::Resources::File>]
+  def self.upload_many(files, client: nil, config: Uploadcare.configuration, request_options: {}, **options)
+    resolved_client = resolve_client(client: client, config: config)
+    resolved_client.uploads.upload_files(files: files, request_options: request_options, **options)
+  end
+
+  # Upload a file from URL.
+  #
+  # @param url [String] Source URL
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param options [Hash] Upload options
+  # @return [Uploadcare::Resources::File]
+  def self.upload_url(url, client: nil, config: Uploadcare.configuration, request_options: {}, **options)
+    resolved_client = resolve_client(client: client, config: config)
+    resolved_client.uploads.upload_from_url(url: url, request_options: request_options, **options)
+  end
+
+  class << self
+    alias upload_from_url upload_url
+  end
+
+  # Batch store files.
+  #
+  # @param uuids [Array<String>] File UUIDs to store
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Collections::BatchResult]
+  def self.batch_store(uuids:, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.rest.files.batch_store(uuids: uuids, request_options: request_options)
+    )
+    normalized = response.transform_keys(&:to_s)
+
+    Uploadcare::Collections::BatchResult.new(
+      status: normalized['status'],
+      result: normalized['result'],
+      problems: normalized['problems'] || {},
+      client: resolved_client
+    )
+  end
+
+  # Batch delete files.
+  #
+  # @param uuids [Array<String>] File UUIDs to delete
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Collections::BatchResult]
+  def self.batch_delete(uuids:, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.rest.files.batch_delete(uuids: uuids, request_options: request_options)
+    )
+    normalized = response.transform_keys(&:to_s)
+
+    Uploadcare::Collections::BatchResult.new(
+      status: normalized['status'],
+      result: normalized['result'],
+      problems: normalized['problems'] || {},
+      client: resolved_client
+    )
+  end
+
+  # Copy a file to local storage (class method).
+  #
+  # @param source [String] CDN URL or UUID
+  # @param options [Hash] Optional parameters
+  # @return [Uploadcare::Resources::File]
+  def self.local_copy(source:, options: {}, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.rest.files.local_copy(source: source, options: options, request_options: request_options)
+    )
+    new(response['result'], resolved_client)
+  end
+
+  class << self
+    alias copy_to_local local_copy
+  end
+
+  # Copy a file to remote storage (class method).
+  #
+  # @param source [String] CDN URL or UUID
+  # @param target [String] Custom storage name
+  # @param options [Hash] Optional parameters
+  # @return [String] URL of the copied file
+  def self.remote_copy(source:, target:, options: {}, client: nil, config: Uploadcare.configuration,
+                       request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.rest.files.remote_copy(
+        source: source, target: target, options: options, request_options: request_options
+      )
+    )
+    response['result']
+  end
+
+  class << self
+    alias copy_to_remote remote_copy
+  end
+
+  # --- Instance methods ---
+
+  # Store this file, making it permanently available.
+  #
+  # @param request_options [Hash] Request options
+  # @return [self]
+  def store(request_options: {})
+    response = Uploadcare::Result.unwrap(client.api.rest.files.store(uuid: uuid, request_options: request_options))
+    assign_attributes(response)
+    self
+  end
+
+  # Delete this file.
+  #
+  # @param request_options [Hash] Request options
+  # @return [self]
+  def delete(request_options: {})
+    response = Uploadcare::Result.unwrap(client.api.rest.files.delete(uuid: uuid, request_options: request_options))
+    assign_attributes(response)
+    self
+  end
+
+  # Reload file information from the API.
+  #
+  # @param params [Hash] Optional parameters
+  # @param request_options [Hash] Request options
+  # @return [self]
+  def reload(params: {}, request_options: {})
+    response = Uploadcare::Result.unwrap(
+      client.api.rest.files.info(uuid: uuid, params: params, request_options: request_options)
+    )
+    assign_attributes(response)
+    self
+  end
+  alias load reload
+
+  # Copy this file to local storage.
+  #
+  # @param options [Hash] Optional parameters
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::File] The copied file
+  def copy_to_local(options: {}, request_options: {})
+    response = Uploadcare::Result.unwrap(
+      client.api.rest.files.local_copy(source: uuid, options: options, request_options: request_options)
+    )
+    self.class.new(response['result'], client)
+  end
+  alias local_copy copy_to_local
+
+  # Copy this file to remote storage.
+  #
+  # @param target [String] Custom storage name
+  # @param options [Hash] Optional parameters
+  # @param request_options [Hash] Request options
+  # @return [String] URL of the copied file
+  def copy_to_remote(target:, options: {}, request_options: {})
+    response = Uploadcare::Result.unwrap(
+      client.api.rest.files.remote_copy(
+        source: uuid, target: target, options: options, request_options: request_options
+      )
+    )
+    response['result']
+  end
+  alias remote_copy copy_to_remote
+
+  # Convert this file to a document format.
+  #
+  # @param params [Hash] Conversion parameters (:format, etc.)
+  # @param options [Hash] Optional parameters (:store, etc.)
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::File] The converted file
+  def convert_to_document(params: {}, options: {}, request_options: {})
+    convert_file(params, Uploadcare::Resources::DocumentConversion, options, request_options: request_options)
+  end
+
+  # Convert this file to a video format.
+  #
+  # @param params [Hash] Conversion parameters (:format, :quality, etc.)
+  # @param options [Hash] Optional parameters (:store, etc.)
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::File] The converted file
+  def convert_to_video(params: {}, options: {}, request_options: {})
+    convert_file(params, Uploadcare::Resources::VideoConversion, options, request_options: request_options)
+  end
+
+  # Returns the file UUID, extracting from URL if needed.
+  #
+  # @return [String, nil]
+  def uuid
+    return @uuid if @uuid
+
+    source =
+      if @url
+        @url
+      elsif uploadcare_cdn_url?(@original_file_url)
+        @original_file_url
+      end
+    return @uuid unless source
+
+    @uuid = source[/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/]
+  end
+
+  # Returns the CDN URL for this file.
+  #
+  # @return [String]
+  def cdn_url
+    return @url if uploadcare_cdn_url?(@url)
+    return @original_file_url if uploadcare_cdn_url?(@original_file_url)
+    return nil unless uuid
+
+    "#{config.cdn_base}#{uuid}/"
+  end
+
+  private
+
+  def uploadcare_cdn_url?(value)
+    value.to_s.start_with?(config.cdn_base.to_s)
+  end
+
+  def convert_file(params, converter, options = {}, request_options: {})
+    raise ArgumentError, 'The first argument must be a Hash' unless params.is_a?(Hash)
+
+    params_with_symbolized_keys = params.transform_keys(&:to_sym)
+    params_with_symbolized_keys[:uuid] = uuid
+
+    result = if converter.respond_to?(:convert_document)
+               converter.convert_document(
+                 params: params_with_symbolized_keys, options: options, config: config,
+                 request_options: request_options
+               )
+             elsif converter.respond_to?(:convert)
+               converter.convert(
+                 params: params_with_symbolized_keys, options: options, config: config,
+                 request_options: request_options
+               )
+             else
+               raise Uploadcare::Exception::ConversionError,
+                     "Converter #{converter.name} must implement .convert_document or .convert"
+             end
+
+    process_convert_result(result, request_options: request_options)
+  end
+
+  def process_convert_result(result, request_options: {})
+    if result.is_a?(Hash) && result['result']&.first
+      return process_hash_result(result, request_options: request_options)
+    end
+
+    if result.respond_to?(:result) && result.result.is_a?(Array) && result.result.first.is_a?(Hash)
+      return process_hash_result({ 'result' => result.result }, request_options: request_options)
+    end
+
+    result
+  end
+
+  def process_hash_result(result, request_options: {})
+    result_data = result['result'].first
+    if result_data['uuid']
+      return self.class.find(uuid: result_data['uuid'], client: client, request_options: request_options)
+    end
+
+    result
+  end
+end

data/lib/uploadcare/resources/file_metadata.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+# File metadata resource for managing key-value metadata on files.
+#
+# @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/File-metadata
+class Uploadcare::Resources::FileMetadata < Uploadcare::Resources::BaseResource
+  attr_accessor :uuid
+
+  def initialize(attributes = {}, client_or_config = nil)
+    super
+    @metadata = {}
+  end
+
+  # --- Instance methods ---
+
+  # Retrieve all metadata for the file.
+  #
+  # @param uuid [String, nil] File UUID (defaults to instance UUID)
+  # @param request_options [Hash] Request options
+  # @return [self]
+  def index(uuid: nil, request_options: {})
+    response = Uploadcare::Result.unwrap(
+      client.api.rest.file_metadata.index(uuid: uuid || @uuid, request_options: request_options)
+    )
+    @metadata = response.is_a?(Hash) ? response.transform_keys(&:to_s) : {}
+    self
+  end
+
+  # Access a metadata value by key.
+  #
+  # @param key [String, Symbol] Metadata key
+  # @return [String, nil] Metadata value
+  def [](key)
+    @metadata[key.to_s]
+  end
+
+  # Set a metadata value by key (local only, call #update to persist).
+  #
+  # @param key [String, Symbol] Metadata key
+  # @param value [String] Metadata value
+  def []=(key, value)
+    @metadata[key.to_s] = value
+  end
+
+  # Return all metadata as a hash.
+  #
+  # @return [Hash]
+  def to_h
+    @metadata.dup
+  end
+
+  # Update a metadata key's value on the server.
+  #
+  # @param key [String] Metadata key
+  # @param value [String] Metadata value
+  # @param uuid [String, nil] File UUID (defaults to instance UUID)
+  # @param request_options [Hash] Request options
+  # @return [String] The updated value
+  def update(key:, value:, uuid: nil, request_options: {})
+    target_uuid = uuid || @uuid
+    result = Uploadcare::Result.unwrap(
+      client.api.rest.file_metadata.update(
+        uuid: target_uuid, key: key, value: value, request_options: request_options
+      )
+    )
+    @metadata[key.to_s] = result if target_uuid == @uuid
+    result
+  end
+
+  # Retrieve a single metadata key's value.
+  #
+  # @param key [String] Metadata key
+  # @param uuid [String, nil] File UUID (defaults to instance UUID)
+  # @param request_options [Hash] Request options
+  # @return [String] Metadata value
+  def show(key:, uuid: nil, request_options: {})
+    target_uuid = uuid || @uuid
+    result = Uploadcare::Result.unwrap(
+      client.api.rest.file_metadata.show(uuid: target_uuid, key: key, request_options: request_options)
+    )
+    @metadata[key.to_s] = result if target_uuid == @uuid
+    result
+  end
+
+  # Delete a metadata key.
+  #
+  # @param key [String] Metadata key
+  # @param uuid [String, nil] File UUID (defaults to instance UUID)
+  # @param request_options [Hash] Request options
+  # @return [nil]
+  def delete(key:, uuid: nil, request_options: {})
+    target_uuid = uuid || @uuid
+    result = Uploadcare::Result.unwrap(
+      client.api.rest.file_metadata.delete(uuid: target_uuid, key: key, request_options: request_options)
+    )
+    @metadata.delete(key.to_s) if target_uuid == @uuid
+    result
+  end
+
+  # --- Class methods ---
+
+  # Get all metadata for a file.
+  def self.index(uuid:, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    Uploadcare::Result.unwrap(
+      resolved_client.api.rest.file_metadata.index(uuid: uuid, request_options: request_options)
+    )
+  end
+
+  # Get a single metadata key's value.
+  def self.show(uuid:, key:, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    Uploadcare::Result.unwrap(
+      resolved_client.api.rest.file_metadata.show(uuid: uuid, key: key, request_options: request_options)
+    )
+  end
+
+  # Update a metadata key's value.
+  def self.update(uuid:, key:, value:, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    Uploadcare::Result.unwrap(
+      resolved_client.api.rest.file_metadata.update(
+        uuid: uuid, key: key, value: value, request_options: request_options
+      )
+    )
+  end
+
+  # Delete a metadata key.
+  def self.delete(uuid:, key:, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    Uploadcare::Result.unwrap(
+      resolved_client.api.rest.file_metadata.delete(uuid: uuid, key: key, request_options: request_options)
+    )
+  end
+end