uploadcare-ruby 4.4.2 → 5.0.0.rc1

data/lib/uploadcare/resources/group.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+# Group resource representing a collection of files in Uploadcare.
+#
+# @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Group
+class Uploadcare::Resources::Group < Uploadcare::Resources::BaseResource
+  # API fields assigned onto group resources.
+  ATTRIBUTES = %i[
+    id datetime_removed datetime_stored datetime_uploaded is_image is_ready mime_type original_file_url cdn_url
+    original_filename size url uuid variations content_info metadata appdata source datetime_created files_count
+    files
+  ].freeze
+
+  attr_writer :id, :cdn_url
+  attr_accessor :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, :datetime_created, :files_count, :files
+
+  # --- Class methods ---
+
+  # List groups with optional filtering and pagination.
+  #
+  # @param params [Hash] Query parameters
+  # @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(params: {}, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.rest.groups.list(params: params, request_options: request_options)
+    )
+    groups = response['results'].map { |data| new(data, resolved_client) }
+
+    Uploadcare::Collections::Paginated.new(
+      resources: groups,
+      next_page: response['next'],
+      previous_page: response['previous'],
+      per_page: response['per_page'],
+      total: response['total'],
+      api_client: resolved_client.api.rest.groups,
+      resource_class: self,
+      client: resolved_client,
+      request_options: request_options
+    )
+  end
+
+  # Find a group by ID.
+  #
+  # @param group_id [String] Group UUID (formatted as UUID~size)
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::Group]
+  def self.find(group_id:, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.rest.groups.info(uuid: group_id, request_options: request_options)
+    )
+    new(response, resolved_client)
+  end
+
+  class << self
+    alias retrieve find
+    alias info find
+  end
+
+  # Create a group from file UUIDs.
+  #
+  # @param uuids [Array<String>] File UUIDs
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param options [Hash] Additional options
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::Group]
+  def self.create(uuids:, client: nil, config: Uploadcare.configuration, request_options: {}, **options)
+    resolved_client = resolve_client(client: client, config: config)
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.upload.groups.create(
+        files: uuids, request_options: request_options, **options
+      )
+    )
+    new(response, resolved_client)
+  end
+
+  # --- Instance methods ---
+
+  # Reload group information from the API.
+  #
+  # @param request_options [Hash] Request options
+  # @return [self]
+  def reload(request_options: {})
+    response = Uploadcare::Result.unwrap(
+      client.api.rest.groups.info(uuid: id, request_options: request_options)
+    )
+    assign_attributes(response)
+    self
+  end
+  alias load reload
+
+  # Delete this group.
+  #
+  # @param request_options [Hash] Request options
+  # @return [nil]
+  def delete(request_options: {})
+    Uploadcare::Result.unwrap(
+      client.api.rest.groups.delete(uuid: id, request_options: request_options)
+    )
+  end
+
+  # Returns group ID, extracting from CDN URL if needed.
+  #
+  # @return [String, nil]
+  def id
+    return @id if @id
+    return @uuid if defined?(@uuid) && !@uuid.to_s.empty?
+    return unless @cdn_url
+
+    uri = URI.parse(@cdn_url)
+    @id = uri.path.split('/').reject(&:empty?).first
+  end
+
+  # Returns the CDN URL for this group.
+  #
+  # @return [String]
+  def cdn_url
+    return @cdn_url if @cdn_url && !@cdn_url.empty?
+
+    "#{config.cdn_base}#{id}/"
+  end
+
+  # Returns CDN URLs for all files in the group.
+  #
+  # @return [Array<String>]
+  def file_cdn_urls
+    return [] if files_count.nil?
+
+    files_count.times.map { |i| "#{cdn_url}nth/#{i}/" }
+  end
+end

data/lib/uploadcare/resources/project.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Project resource representing the current Uploadcare project.
+#
+# @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Project
+class Uploadcare::Resources::Project < Uploadcare::Resources::BaseResource
+  attr_accessor :name, :pub_key, :autostore_enabled, :collaborators
+
+  # Get current project information.
+  #
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::Project]
+  def self.current(client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.rest.project.show(request_options: request_options)
+    )
+    new(response, resolved_client)
+  end
+
+  class << self
+    alias show current
+  end
+end

data/lib/uploadcare/resources/video_conversion.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Video conversion resource.
+#
+# @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Video
+class Uploadcare::Resources::VideoConversion < Uploadcare::Resources::BaseResource
+  attr_accessor :problems, :status, :error, :result
+
+  # Convert a video to a specified format (class method).
+  #
+  # @param params [Hash] Conversion parameters (:uuid, :format, :quality)
+  # @param options [Hash] Optional parameters (:store)
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::VideoConversion]
+  def self.convert(params:, options: {}, client: nil, config: Uploadcare.configuration, request_options: {})
+    raise ArgumentError, 'params must include :uuid' unless params[:uuid]
+    raise ArgumentError, 'params must include :format' unless params[:format]
+    raise ArgumentError, 'params must include :quality' unless params[:quality]
+
+    paths = Array(params[:uuid]).map do |uuid|
+      "#{uuid}/video/-/format/#{params[:format]}/-/quality/#{params[:quality]}/"
+    end
+
+    resolved_client = resolve_client(client: client, config: config)
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.rest.video_conversions.convert(
+        paths: paths, options: options, request_options: request_options
+      )
+    )
+    new(response, resolved_client)
+  end
+
+  # Fetch video 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::VideoConversion]
+  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
+
+  # Refresh this resource from the conversion status endpoint.
+  #
+  # @param token [String]
+  # @param request_options [Hash]
+  # @return [self]
+  def fetch_status(token:, request_options: {})
+    response = Uploadcare::Result.unwrap(
+      client.api.rest.video_conversions.status(token: token, request_options: request_options)
+    )
+    assign_attributes(response)
+    self
+  end
+end

data/lib/uploadcare/resources/webhook.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# Webhook resource for managing Uploadcare webhooks.
+#
+# @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Webhook
+class Uploadcare::Resources::Webhook < Uploadcare::Resources::BaseResource
+  attr_accessor :id, :project, :created, :updated, :event, :target_url, :is_active, :signing_secret, :version
+
+  # List all project webhooks.
+  #
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param request_options [Hash] Request options
+  # @return [Array<Uploadcare::Resources::Webhook>]
+  def self.list(client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.rest.webhooks.list(request_options: request_options)
+    )
+    response.map { |data| new(data, resolved_client) }
+  end
+
+  # Create a new webhook.
+  #
+  # @param target_url [String] Webhook target URL
+  # @param options [Hash] Webhook options
+  # @option options [String] :event Event type (default: "file.uploaded")
+  # @option options [Boolean] :is_active Active flag (default: true)
+  # @option options [String] :signing_secret Signing secret
+  # @option options [String] :version Webhook payload version
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::Webhook]
+  def self.create(target_url:, client: nil, config: Uploadcare.configuration, request_options: {}, **options)
+    resolved_client = resolve_client(client: client, config: config)
+    event = options.fetch(:event, 'file.uploaded')
+    is_active = options.key?(:is_active) ? options[:is_active] : true
+    payload = { target_url: target_url, event: event, is_active: is_active }
+    payload[:signing_secret] = options[:signing_secret] if options[:signing_secret]
+    payload[:version] = options[:version] if options[:version]
+
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.rest.webhooks.create(options: payload, request_options: request_options)
+    )
+    new(response, resolved_client)
+  end
+
+  # Update a webhook.
+  #
+  # @param id [Integer] Webhook ID
+  # @param options [Hash] Webhook options to update
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param request_options [Hash] Request options
+  # @return [Uploadcare::Resources::Webhook]
+  def self.update(id:, client: nil, config: Uploadcare.configuration, request_options: {}, **options)
+    resolved_client = resolve_client(client: client, config: config)
+    payload = options.slice(:target_url, :event, :signing_secret, :version)
+    payload[:is_active] = options[:is_active] if options.key?(:is_active)
+
+    response = Uploadcare::Result.unwrap(
+      resolved_client.api.rest.webhooks.update(id: id, options: payload, request_options: request_options)
+    )
+    new(response, resolved_client)
+  end
+
+  # Delete a webhook by target URL.
+  #
+  # @param target_url [String] Target URL of the webhook to delete
+  # @param client [Uploadcare::Client, nil] Client instance
+  # @param config [Uploadcare::Configuration] Configuration fallback
+  # @param request_options [Hash] Request options
+  # @return [nil]
+  def self.delete(target_url:, client: nil, config: Uploadcare.configuration, request_options: {})
+    resolved_client = resolve_client(client: client, config: config)
+    Uploadcare::Result.unwrap(
+      resolved_client.api.rest.webhooks.delete(target_url: target_url, request_options: request_options)
+    )
+  end
+
+  class << self
+    alias unsubscribe delete
+  end
+end

data/lib/uploadcare/result.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# Result wrapper for success/error handling.
+class Uploadcare::Result
+  attr_reader :value, :error
+
+  def initialize(value: nil, error: nil)
+    @value = value
+    @error = error
+  end
+
+  # Build a success result.
+  #
+  # @param value [Object]
+  # @return [Uploadcare::Result]
+  def self.success(value)
+    new(value: value)
+  end
+
+  # Build a failure result.
+  #
+  # @param error [Object]
+  # @return [Uploadcare::Result]
+  def self.failure(error)
+    new(error: error)
+  end
+
+  # Capture exceptions and wrap in Result.
+  #
+  # @return [Uploadcare::Result]
+  def self.capture
+    success(yield)
+  rescue StandardError => e
+    failure(e)
+  end
+
+  # Unwrap a Result or return the value as-is.
+  #
+  # @param value [Object]
+  # @return [Object]
+  def self.unwrap(value)
+    value.is_a?(Uploadcare::Result) ? value.value! : value
+  end
+
+  def success?
+    @error.nil?
+  end
+
+  def failure?
+    !success?
+  end
+
+  # @return [Object] success value
+  def success
+    @value
+  end
+
+  # @return [Object] error value
+  def failure
+    @error
+  end
+
+  # Return the success value or raise the wrapped error.
+  #
+  # @return [Object]
+  # @raise [Exception, RuntimeError]
+  def value!
+    if failure?
+      error = @error
+      raise error if error.is_a?(Exception)
+      raise error if error.is_a?(String)
+
+      raise error.to_s
+    end
+
+    @value
+  end
+
+  # @return [String, nil] error message
+  def error_message
+    return nil if @error.nil?
+
+    @error.respond_to?(:message) ? @error.message : @error.to_s
+  end
+end

data/lib/uploadcare/signed_url_generators/akamai_generator.rb

@@ -1,63 +1,67 @@
 # frozen_string_literal: true
 
+require 'openssl'
 require_relative 'base_generator'
 
-module Uploadcare
-  module SignedUrlGenerators
-    class AkamaiGenerator < Uploadcare::SignedUrlGenerators::BaseGenerator
-      UUID_REGEX = '[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}'
-      TEMPLATE = 'https://{cdn_host}/{uuid}/?token=exp={expiration}{delimiter}acl={acl}{delimiter}hmac={token}'
-
-      def generate_url(uuid, acl = uuid, wildcard: false)
-        raise ArgumentError, 'Must contain valid UUID' unless valid?(uuid)
-
-        formatted_acl = build_acl(uuid, acl, wildcard: wildcard)
-        expire = build_expire
-        signature = build_signature(expire, formatted_acl)
-
-        TEMPLATE.gsub('{delimiter}', delimiter)
-                .sub('{cdn_host}', sanitized_string(cdn_host))
-                .sub('{uuid}', sanitized_string(uuid))
-                .sub('{acl}', formatted_acl)
-                .sub('{expiration}', expire)
-                .sub('{token}', signature)
-      end
-
-      private
-
-      def valid?(uuid)
-        uuid.match(UUID_REGEX)
-      end
-
-      def delimiter
-        '~'
-      end
-
-      def build_acl(uuid, acl, wildcard: false)
-        if wildcard
-          "/#{sanitized_string(uuid)}/*"
-        else
-          "/#{sanitized_string(acl)}/"
-        end
-      end
-
-      def build_expire
-        (Time.now.to_i + ttl).to_s
-      end
-
-      def build_signature(expire, acl)
-        signature = ["exp=#{expire}", "acl=#{acl}"].join(delimiter)
-        secret_key_bin = Array(secret_key.gsub(/\s/, '')).pack('H*')
-        OpenSSL::HMAC.hexdigest(algorithm, secret_key_bin, signature)
-      end
-
-      # rubocop:disable Style/SlicingWithRange
-      def sanitized_string(string)
-        string = string[1..-1] if string[0] == '/'
-        string = string[0...-1] if string[-1] == '/'
-        string.strip
-      end
-      # rubocop:enable Style/SlicingWithRange
+# Akamai signed URL generator.
+class Uploadcare::SignedUrlGenerators::AkamaiGenerator < Uploadcare::SignedUrlGenerators::BaseGenerator
+  # UUID validation regex.
+  UUID_REGEX = /\A[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}\z/i
+  # Akamai token template.
+  TEMPLATE = 'https://{cdn_host}/{uuid}/?token=exp={expiration}{delimiter}acl={acl}{delimiter}hmac={token}'
+
+  def generate_url(uuid, acl = uuid, wildcard: false)
+    raise ArgumentError, 'Must contain valid UUID' unless valid?(uuid)
+
+    formatted_acl = build_acl(uuid, acl, wildcard: wildcard)
+    expire = build_expire
+    signature = build_signature(expire, formatted_acl)
+
+    TEMPLATE.gsub('{delimiter}', delimiter)
+            .sub('{cdn_host}', sanitized_string(cdn_host))
+            .sub('{uuid}', sanitized_string(uuid))
+            .sub('{acl}', formatted_acl)
+            .sub('{expiration}', expire)
+            .sub('{token}', signature)
+  end
+
+  private
+
+  def valid?(uuid)
+    raise ArgumentError, 'Must contain valid UUID' unless uuid.is_a?(String)
+
+    UUID_REGEX.match?(uuid)
+  end
+
+  def delimiter
+    '~'
+  end
+
+  def build_acl(uuid, acl, wildcard: false)
+    if wildcard
+      "/#{sanitized_delimiter_path(uuid)}/*"
+    else
+      "/#{sanitized_delimiter_path(acl)}/"
     end
   end
+
+  def sanitized_delimiter_path(path)
+    sanitized_string(path).gsub('~') { |escape_char| "%#{escape_char.ord.to_s(16).downcase}" }
+  end
+
+  def build_expire
+    (Time.now.to_i + ttl).to_s
+  end
+
+  def build_signature(expire, acl)
+    signature = ["exp=#{expire}", "acl=#{acl}"].join(delimiter)
+    secret_key_bin = Array(secret_key.delete(" \t\r\n")).pack('H*')
+    OpenSSL::HMAC.hexdigest(algorithm, secret_key_bin, signature)
+  end
+
+  def sanitized_string(string)
+    string = string[1..] if string[0] == '/'
+    string = string[0...-1] if string[-1] == '/'
+    string.strip
+  end
 end

data/lib/uploadcare/signed_url_generators/base_generator.rb

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
-module Uploadcare
-  module SignedUrlGenerators
-    class BaseGenerator
-      attr_accessor :cdn_host, :ttl, :algorithm
-      attr_reader :secret_key
+# Base class for signed URL generators.
+class Uploadcare::SignedUrlGenerators::BaseGenerator
+  attr_accessor :cdn_host, :ttl, :algorithm
+  attr_reader :secret_key
 
-      def initialize(cdn_host:, secret_key:, ttl: 300, algorithm: 'sha256')
-        @ttl = ttl
-        @algorithm = algorithm
-        @cdn_host = cdn_host
-        @secret_key = secret_key
-      end
+  def initialize(cdn_host:, secret_key:, ttl: 300, algorithm: 'sha256')
+    @ttl = ttl
+    @algorithm = algorithm
+    @cdn_host = cdn_host
+    @secret_key = secret_key
+  end
 
-      def generate_url
-        raise NotImplementedError, "#{__method__} method not present"
-      end
-    end
+  # Generate a signed URL.
+  #
+  # @return [String]
+  def generate_url
+    raise NotImplementedError, "#{__method__} method not present"
   end
 end

data/lib/uploadcare/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Root namespace for the Uploadcare Ruby SDK.
+module Uploadcare
+  # Gem version.
+  VERSION = '5.0.0.rc1'
+end

data/lib/uploadcare/webhook_signature_verifier.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+# This object verifies a signature received along with webhook headers
+class Uploadcare::WebhookSignatureVerifier
+  # @see https://uploadcare.com/docs/security/secure-webhooks/
+  def self.valid?(webhook_body: nil, signing_secret: nil, x_uc_signature_header: nil)
+    webhook_body_json = webhook_body
+    signing_secret ||= ENV.fetch('UC_SIGNING_SECRET', nil)
+
+    return false unless valid_parameters?(signing_secret, x_uc_signature_header, webhook_body_json)
+
+    calculated_signature = calculate_signature(signing_secret, webhook_body_json)
+
+    # Use constant-time comparison to prevent timing attacks
+    secure_compare?(calculated_signature, x_uc_signature_header)
+  end
+
+  # Check if all required parameters are present and non-empty
+  # @param signing_secret [String] signing secret
+  # @param signature_header [String] signature from header
+  # @param body [String] webhook body
+  # @return [Boolean] true if all parameters are valid
+  def self.valid_parameters?(signing_secret, signature_header, body)
+    return false if signing_secret.nil? || signing_secret.to_s.empty?
+    return false if signature_header.nil? || signature_header.to_s.empty?
+    return false if body.nil? || body.to_s.empty?
+
+    true
+  end
+
+  # Calculate HMAC signature for webhook body
+  # @param secret [String] signing secret
+  # @param body [String] webhook body JSON
+  # @return [String] calculated signature
+  def self.calculate_signature(secret, body)
+    digest = OpenSSL::Digest.new('sha256')
+    "v1=#{OpenSSL::HMAC.hexdigest(digest, secret, body)}"
+  end
+
+  # Constant-time string comparison to prevent timing attacks
+  # @param first [String] first string
+  # @param second [String] second string
+  # @return [Boolean] true if strings are equal
+  def self.secure_compare?(first, second)
+    return false if first.nil? || second.nil?
+    return false unless first.bytesize == second.bytesize
+
+    OpenSSL.fixed_length_secure_compare(first, second)
+  rescue NoMethodError
+    result = 0
+    index = 0
+    while index < first.bytesize
+      result |= first.getbyte(index) ^ second.getbyte(index)
+      index += 1
+    end
+    result.zero?
+  end
+end