Polish docs and harden API request handling

Author: vipulnsward

README.md

@@ -19,6 +19,7 @@ The gem is built around:
 - full endpoint coverage through `client.api.rest` and `client.api.upload`
 
 - [Requirements](#requirements)
+- [Compatibility](#compatibility)
 - [Installation](#installation)
 - [Design](#design)
 - [Quick Start](#quick-start)
@@ -27,10 +28,12 @@ The gem is built around:
 - [Uploads](#uploads)
 - [Files](#files)
 - [Groups](#groups)
+- [Project](#project)
 - [Metadata](#metadata)
 - [Webhooks](#webhooks)
 - [Add-ons](#add-ons)
 - [Conversions](#conversions)
+- [Secure Delivery](#secure-delivery)
 - [Errors and Results](#errors-and-results)
 - [Request Options](#request-options)
 - [Raw API Access](#raw-api-access)
@@ -41,6 +44,14 @@ The gem is built around:
 
 - Ruby 3.3+
 
+## Compatibility
+
+This gem is intended for plain Ruby applications and for framework integrations built on top of it.
+
+- Use explicit `Uploadcare::Client` instances when you need multiple accounts in one process.
+- Use `Uploadcare.configure` and `Uploadcare.client` when one global default client is enough.
+- Use `client.api.rest` and `client.api.upload` when you want endpoint-level parity with the official API references.
+
 ## Installation
 
 Add the gem to your Gemfile:
@@ -125,6 +136,30 @@ end
 
 The recommended style is explicit `Uploadcare::Client` instances. Global configuration is best treated as a default.
 
+## Example Usage
+
+This is the shortest end-to-end flow for the main public API:
+
+```ruby
+require "uploadcare"
+
+client = Uploadcare::Client.new(
+  public_key: ENV.fetch("UPLOADCARE_PUBLIC_KEY"),
+  secret_key: ENV.fetch("UPLOADCARE_SECRET_KEY")
+)
+
+file = File.open("photo.jpg", "rb") do |io|
+  client.files.upload(io, store: true)
+end
+
+group = client.groups.create(uuids: [file.uuid])
+
+puts file.uuid
+puts file.cdn_url
+puts group.id
+puts group.cdn_url
+```
+
 ## Configuration
 
 Use `Uploadcare.configure` to set process-wide defaults:
@@ -306,6 +341,19 @@ Common upload options:
 - `async: true` for URL uploads
 - `threads:` and `part_size:` for multipart uploads
 
+If you prefer the older top-level style, the same flows can still be written through the global client:
+
+```ruby
+Uploadcare.configure do |config|
+  config.public_key = ENV.fetch("UPLOADCARE_PUBLIC_KEY")
+  config.secret_key = ENV.fetch("UPLOADCARE_SECRET_KEY")
+end
+
+file = File.open("photo.jpg", "rb") do |io|
+  Uploadcare.files.upload(io, store: true)
+end
+```
+
 ## Files
 
 ### Find a file
@@ -329,6 +377,12 @@ files.previous_page
 files.all
 ```
 
+Filters and API parameters can still be passed through:
+
+```ruby
+files = client.files.list(stored: true, removed: false, limit: 100)
+```
+
 ### Resource operations
 
 ```ruby
@@ -392,6 +446,18 @@ group.cdn_url
 group.file_cdn_urls
 ```
 
+## Project
+
+Fetch the current project:
+
+```ruby
+project = client.project.current
+
+puts project.name
+puts project.pub_key
+puts project.collaborators
+```
+
 ## Metadata
 
 ```ruby
@@ -453,6 +519,26 @@ Document conversion `convert` returns the API response hash.
 
 Video conversion `convert` returns a `Uploadcare::VideoConversion` resource.
 
+## Secure Delivery
+
+The gem includes signed URL generators for delivery workflows.
+
+```ruby
+generator = Uploadcare::SignedUrlGenerators::AkamaiGenerator.new(
+  cdn_host: "example.com",
+  secret_key: "your_hex_encoded_akamai_secret"
+)
+
+signed_url = generator.generate_url("a7d5645e-5cd7-4046-819f-a6a2933bafe3")
+```
+
+Custom ACL and wildcard examples:
+
+```ruby
+generator.generate_url("a7d5645e-5cd7-4046-819f-a6a2933bafe3", "/*")
+generator.generate_url("a7d5645e-5cd7-4046-819f-a6a2933bafe3", wildcard: true)
+```
+
 ## Errors and Results
 
 The convenience layer raises exceptions:
@@ -525,6 +611,8 @@ client.api.upload.groups.create(files: ["uuid-1", "uuid-2"])
 
 Use this layer when you want exact control over the documented endpoints or when you are wrapping the gem from another library.
 
+The raw layer is part of the public surface, but it is intentionally less promoted than `client.files`, `client.groups`, and the other convenience accessors.
+
 ## Examples
 
 - [api_examples/README.md](./api_examples/README.md): one canonical script per documented REST and Upload API endpoint

lib/uploadcare.rb

@@ -41,46 +41,48 @@ def client(config: nil, **options)
       Client.new(config: config || configuration, **options)
     end
 
-    # Convenience accessor for files domain.
-    #
     # @return [Uploadcare::Client::FilesAccessor]
     def files
       client.files
     end
 
-    # Convenience accessor for groups domain.
-    #
     # @return [Uploadcare::Client::GroupsAccessor]
     def groups
       client.groups
     end
 
-    # Convenience accessor for uploads domain.
-    #
     # @return [Uploadcare::Operations::UploadRouter]
     def uploads
       client.uploads
     end
 
-    # Convenience accessor for project domain.
-    #
     # @return [Uploadcare::Client::ProjectAccessor]
     def project
       client.project
     end
 
+    # Eager-load the gem namespace through Zeitwerk.
+    #
+    # @return [void]
     def eager_load!
       @loader.eager_load
     end
   end
 
-  # --- Public top-level constants (per blueprint compatibility policy) ---
+  # Top-level aliases for the public resource classes.
   File = Resources::File
+  # Alias for the group resource.
   Group = Resources::Group
+  # Alias for the project resource.
   Project = Resources::Project
+  # Alias for the webhook resource.
   Webhook = Resources::Webhook
+  # Alias for the file metadata resource.
   FileMetadata = Resources::FileMetadata
+  # Alias for the add-on execution resource.
   AddonExecution = Resources::AddonExecution
+  # Alias for the document conversion resource.
   DocumentConversion = Resources::DocumentConversion
+  # Alias for the video conversion resource.
   VideoConversion = Resources::VideoConversion
 end

lib/uploadcare/api/rest.rb

@@ -19,6 +19,7 @@ class Uploadcare::Api::Rest
   include Uploadcare::Internal::ErrorHandler
   include Uploadcare::Internal::ThrottleHandler
 
+  # Verb name used when deciding whether params belong in the query string.
   HTTP_GET = 'GET'
 
   # @return [Uploadcare::Configuration]
@@ -186,10 +187,11 @@ def build_request_uri(path, params, method)
 
   def prepare_headers(req, method, uri, params, headers)
     body_content = body_content_for_signature(method, params)
-    content_type = headers['Content-Type'] || authenticator.default_headers['Content-Type']
+    content_type = extract_content_type(headers) || authenticator.default_headers['Content-Type']
     auth_headers = authenticator.headers(method, uri, body_content, content_type)
+    normalized_headers = normalize_content_type_header(headers, content_type)
     req.headers.merge!(auth_headers)
-    req.headers.merge!(headers)
+    req.headers.merge!(normalized_headers)
   end
 
   def body_content_for_signature(method, params)
@@ -217,6 +219,19 @@ def apply_request_options(req, request_options)
     req.options.open_timeout = request_options[:open_timeout] if request_options[:open_timeout]
   end
 
+  def extract_content_type(headers)
+    headers['Content-Type'] || headers['content-type'] || headers[:content_type] || headers[:'Content-Type']
+  end
+
+  def normalize_content_type_header(headers, content_type)
+    normalized_headers = headers.dup
+    normalized_headers.delete('content-type')
+    normalized_headers.delete(:content_type)
+    normalized_headers.delete(:'Content-Type')
+    normalized_headers['Content-Type'] = content_type if content_type
+    normalized_headers
+  end
+
   def build_uri(path, query_params = {})
     if query_params.empty?
       path

lib/uploadcare/api/rest/video_conversions.rb

@@ -20,7 +20,10 @@ def initialize(rest:)
   # @return [Uploadcare::Result] Conversion details
   # @see https://uploadcare.com/api-refs/rest-api/v0.7.0/#tag/Video/operation/convertVideo
   def convert(paths:, options: {}, request_options: {})
-    params = { paths: paths }.merge(options)
+    params = { paths: paths }
+    params[:store] = normalize_bool_param(options[:store]) if options.key?(:store)
+    params.merge!(options.except(:store))
+    params.compact!
     rest.post(path: '/convert/video/', params: params, headers: {}, request_options: request_options)
   end
 
@@ -34,4 +37,16 @@ def status(token:, request_options: {})
     rest.get(path: "/convert/video/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

lib/uploadcare/api/upload.rb

@@ -112,13 +112,13 @@ def upload_part_to_url(presigned_url, part_data, max_retries: 3)
 
       true
     rescue StandardError => e
-      retries += 1
       if retries >= max_retries
         raise Uploadcare::Exception::MultipartUploadError,
               "Failed to upload part after #{max_retries} retries: #{e.message}"
       end
 
       sleep(2**retries)
+      retries += 1
       retry
     end
   end

lib/uploadcare/client.rb

@@ -22,51 +22,93 @@
 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)
   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.with, **options)
+    self.class.new(config: config, **options)
   end
 
+  # Access the raw endpoint-parity API.
+  #
+  # @return [Uploadcare::Client::Api]
   def api
     @api ||= Api.new(config: config)
   end
 
+  # Access file operations and upload helpers.
+  #
+  # @return [Uploadcare::Client::FilesAccessor]
   def files
     @files ||= FilesAccessor.new(client: self)
   end
 
+  # Access group operations.
+  #
+  # @return [Uploadcare::Client::GroupsAccessor]
   def groups
     @groups ||= GroupsAccessor.new(client: self)
   end
 
+  # Access upload routing helpers.
+  #
+  # @return [Uploadcare::Operations::UploadRouter]
   def uploads
     @uploads ||= Uploadcare::Operations::UploadRouter.new(client: self)
   end
 
+  # Access project operations.
+  #
+  # @return [Uploadcare::Client::ProjectAccessor]
   def project
     @project ||= ProjectAccessor.new(client: self)
   end
 
+  # Access webhook operations.
+  #
+  # @return [Uploadcare::Client::WebhooksAccessor]
   def webhooks
     @webhooks ||= WebhooksAccessor.new(client: self)
   end
 
+  # Access add-on execution helpers.
+  #
+  # @return [Uploadcare::Client::AddonsAccessor]
   def addons
     @addons ||= AddonsAccessor.new(client: self)
   end
 
+  # Access file metadata operations.
+  #
+  # @return [Uploadcare::Client::FileMetadataAccessor]
   def file_metadata
     @file_metadata ||= FileMetadataAccessor.new(client: self)
   end
 
+  # Access conversion helpers.
+  #
+  # @return [Uploadcare::Client::ConversionsAccessor]
   def conversions
     @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