uploadcare-ruby 4.4.2 → 5.0.0.rc1

data/api_examples/support/example_helper.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'dotenv/load'
+require 'tempfile'
+require 'securerandom'
+
+require_relative '../../lib/uploadcare'
+
+module ApiExamples
+end
+
+module ApiExamples::ExampleHelper
+  SAMPLE_IMAGE_URL = 'https://upload.wikimedia.org/wikipedia/commons/3/3f/JPEG_example_flower.jpg'
+  SAMPLE_VIDEO_URL = 'https://samplelib.com/lib/preview/mp4/sample-5s.mp4'
+
+  module_function
+
+  def client
+    @client ||= Uploadcare::Client.new(
+      public_key: ENV.fetch('UPLOADCARE_PUBLIC_KEY'),
+      secret_key: ENV.fetch('UPLOADCARE_SECRET_KEY'),
+      auth_type: ENV.fetch('UPLOADCARE_AUTH_TYPE', 'Uploadcare.Simple')
+    )
+  end
+
+  def run
+    output(yield(client))
+  rescue StandardError => e
+    warn("#{e.class}: #{e.message}")
+    exit 1
+  end
+
+  def output(value)
+    puts JSON.pretty_generate(value)
+  end
+
+  def unwrap(result)
+    Uploadcare::Result.unwrap(result)
+  end
+
+  def skip(message)
+    output('skipped' => true, 'reason' => message)
+    exit 0
+  end
+
+  def fixture_path(name)
+    File.expand_path("../../spec/fixtures/#{name}", __dir__)
+  end
+
+  def with_uploaded_file(path: fixture_path('kitten.jpeg'), store: true, metadata: {})
+    handle = File.open(path, 'rb')
+    file = client.files.upload(handle, store: store, metadata: metadata)
+    yield file
+  ensure
+    handle&.close
+    safe_delete_file(file)
+  end
+
+  def with_uploaded_files(paths: [fixture_path('kitten.jpeg'), fixture_path('another_kitten.jpeg')], store: true)
+    handles = paths.map { |path| File.open(path, 'rb') }
+    files = client.files.upload(handles, store: store)
+    yield files
+  ensure
+    handles&.each(&:close)
+    Array(files).each { |file| safe_delete_file(file) }
+  end
+
+  def with_fixture_file(name)
+    handle = File.open(fixture_path(name), 'rb')
+    response = yield handle
+    response
+  ensure
+    handle&.close
+    safe_delete_file(uploaded_uuid_from_base_response(response)) if response
+  end
+
+  def with_uploaded_group
+    with_uploaded_files do |files|
+      group = client.groups.create(uuids: files.map(&:uuid))
+      yield group, files
+    ensure
+      safe_delete_group(group)
+    end
+  end
+
+  def with_webhook
+    webhook = client.webhooks.create(
+      target_url: "https://example.com/uploadcare-webhook/#{SecureRandom.hex(4)}",
+      is_active: true
+    )
+    yield webhook
+  ensure
+    safe_delete_webhook(webhook)
+  end
+
+  def with_uploaded_pdf
+    pdf = Tempfile.new(['uploadcare-example', '.pdf'])
+    pdf.write(minimal_pdf)
+    pdf.rewind
+    file = client.files.upload(pdf, store: true)
+    yield file
+  ensure
+    pdf&.close!
+    safe_delete_file(file)
+  end
+
+  def with_uploaded_video
+    file = client.files.upload_from_url(SAMPLE_VIDEO_URL, store: true)
+    yield file
+  ensure
+    safe_delete_file(file)
+  end
+
+  def multipart_part_size
+    5 * 1024 * 1024
+  end
+
+  def with_multipart_session
+    file = File.open(fixture_path('big.jpeg'), 'rb')
+    response = unwrap(
+      client.api.upload.files.multipart_start(
+        filename: File.basename(file.path),
+        size: file.size,
+        content_type: 'image/jpeg',
+        part_size: multipart_part_size,
+        store: true
+      )
+    )
+    yield file, response
+  ensure
+    file&.close
+    safe_delete_file(response['completed_uuid']) if response.is_a?(Hash) && response['completed_uuid']
+  end
+
+  def upload_multipart_part(file:, session:, index:)
+    file.seek(index * multipart_part_size)
+    data = file.read(multipart_part_size)
+    return nil unless data && !data.empty?
+
+    client.api.upload.upload_part_to_url(session.fetch('parts').fetch(index), data)
+    data.bytesize
+  end
+
+  def finish_multipart_upload(file:, session:, skip_indices: [])
+    session.fetch('parts').each_index do |index|
+      next if skip_indices.include?(index)
+
+      upload_multipart_part(file: file, session: session, index: index)
+    end
+    result = unwrap(client.api.upload.files.multipart_complete(uuid: session.fetch('uuid')))
+    session['completed_uuid'] = result['uuid']
+    result
+  end
+
+  def uploaded_uuid_from_base_response(response)
+    response.values.first
+  end
+
+  def conversion_token(response)
+    result = if response.respond_to?(:result)
+               response.result
+             else
+               response.fetch('result')
+             end
+
+    Array(result).first.fetch('token')
+  end
+
+  def safe_delete_file(file)
+    return unless file
+
+    uuid = if file.respond_to?(:uuid)
+             file.uuid
+           elsif file.is_a?(Hash)
+             file['uuid'] || file[:uuid]
+           else
+             file
+           end
+    return if uuid.to_s.empty?
+
+    client.api.rest.files.delete(uuid: uuid)
+  rescue StandardError
+    nil
+  end
+
+  def safe_delete_group(group)
+    group_id = if group.respond_to?(:id)
+                 group.id
+               elsif group.is_a?(Hash)
+                 group['id'] || group[:id]
+               else
+                 group
+               end
+    return if group_id.to_s.empty?
+
+    client.api.rest.groups.delete(uuid: group_id)
+  rescue StandardError
+    nil
+  end
+
+  def safe_delete_webhook(webhook)
+    return unless webhook&.target_url
+
+    client.api.rest.webhooks.delete(target_url: webhook.target_url)
+  rescue StandardError
+    nil
+  end
+
+  def minimal_pdf
+    <<~PDF
+      %PDF-1.4
+      1 0 obj
+      << /Type /Catalog /Pages 2 0 R >>
+      endobj
+      2 0 obj
+      << /Type /Pages /Kids [3 0 R] /Count 1 >>
+      endobj
+      3 0 obj
+      << /Type /Page /Parent 2 0 R /MediaBox [0 0 300 144] /Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> >>
+      endobj
+      4 0 obj
+      << /Length 44 >>
+      stream
+      BT
+      /F1 18 Tf
+      72 100 Td
+      (Uploadcare PDF) Tj
+      ET
+      endstream
+      endobj
+      5 0 obj
+      << /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
+      endobj
+      xref
+      0 6
+      0000000000 65535 f
+      0000000009 00000 n
+      0000000058 00000 n
+      0000000115 00000 n
+      0000000241 00000 n
+      0000000334 00000 n
+      trailer
+      << /Size 6 /Root 1 0 R >>
+      startxref
+      404
+      %%EOF
+    PDF
+  end
+end

data/api_examples/support/run_rest_example.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require_relative 'example_helper'
+
+module ApiExamples::RunRestExample
+  module_function
+
+  def call
+    ApiExamples::ExampleHelper.run do |client|
+      case File.basename($PROGRAM_NAME)
+      when 'get_project.rb'
+        client.project.current
+      when 'get_files.rb'
+        client.files.list(limit: 2)
+      when 'get_files_uuid.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          client.files.find(uuid: file.uuid)
+        end
+      when 'put_files_uuid_storage.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file(store: false, &:store)
+      when 'delete_files_uuid_storage.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file(&:delete)
+      when 'put_files_storage.rb'
+        ApiExamples::ExampleHelper.with_uploaded_files(store: false) do |files|
+          client.files.batch_store(uuids: files.map(&:uuid))
+        end
+      when 'delete_files_storage.rb'
+        ApiExamples::ExampleHelper.with_uploaded_files do |files|
+          client.files.batch_delete(uuids: files.map(&:uuid))
+        end
+      when 'post_files_local_copy.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          copied = client.files.copy_to_local(source: file.uuid, options: { store: true })
+          copied
+        ensure
+          ApiExamples::ExampleHelper.safe_delete_file(copied)
+        end
+      when 'post_files_remote_copy.rb'
+        target = ENV.fetch('UPLOADCARE_REMOTE_STORAGE', nil)
+        if target.to_s.empty?
+          ApiExamples::ExampleHelper.skip('Set UPLOADCARE_REMOTE_STORAGE to a configured custom storage name.')
+        end
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          client.files.copy_to_remote(source: file.uuid, target: target)
+        end
+      when 'get_groups.rb'
+        client.groups.list(limit: 2)
+      when 'get_groups_uuid.rb'
+        ApiExamples::ExampleHelper.with_uploaded_group do |group, _files|
+          client.groups.find(group_id: group.id)
+        end
+      when 'delete_groups_uuid.rb'
+        ApiExamples::ExampleHelper.with_uploaded_group do |group, _files|
+          group.delete
+        end
+      when 'get_webhooks.rb'
+        client.webhooks.list
+      when 'post_webhooks.rb'
+        ApiExamples::ExampleHelper.with_webhook do |webhook|
+          {
+            'id' => webhook.id,
+            'target_url' => webhook.target_url,
+            'is_active' => webhook.is_active,
+            'event' => webhook.event
+          }
+        end
+      when 'put_webhooks_id.rb'
+        ApiExamples::ExampleHelper.with_webhook do |webhook|
+          client.webhooks.update(id: webhook.id, is_active: false)
+        end
+      when 'delete_webhooks_unsubscribe.rb'
+        ApiExamples::ExampleHelper.with_webhook do |webhook|
+          client.webhooks.delete(target_url: webhook.target_url)
+          { 'target_url' => webhook.target_url, 'deleted' => true }
+        end
+      when 'get_files_uuid_metadata.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          client.file_metadata.update(uuid: file.uuid, key: 'color', value: 'orange')
+          client.file_metadata.index(uuid: file.uuid)
+        end
+      when 'get_files_uuid_metadata_key.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          client.file_metadata.update(uuid: file.uuid, key: 'color', value: 'orange')
+          client.file_metadata.show(uuid: file.uuid, key: 'color')
+        end
+      when 'put_files_uuid_metadata_key.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          client.file_metadata.update(uuid: file.uuid, key: 'color', value: 'orange')
+        end
+      when 'delete_files_uuid_metadata_key.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          client.file_metadata.update(uuid: file.uuid, key: 'color', value: 'orange')
+          client.file_metadata.delete(uuid: file.uuid, key: 'color')
+          { 'uuid' => file.uuid, 'key' => 'color', 'deleted' => true }
+        end
+      when 'post_addons_aws_rekognition_detect_labels_execute.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          client.addons.aws_rekognition_detect_labels(uuid: file.uuid)
+        end
+      when 'get_addons_aws_rekognition_detect_labels_execute_status.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          response = client.addons.aws_rekognition_detect_labels(uuid: file.uuid)
+          client.addons.aws_rekognition_detect_labels_status(request_id: response.request_id)
+        end
+      when 'post_addons_aws_rekognition_detect_moderation_labels_execute.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          client.addons.aws_rekognition_detect_moderation_labels(uuid: file.uuid)
+        end
+      when 'get_addons_aws_rekognition_detect_moderation_labels_execute_status.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          response = client.addons.aws_rekognition_detect_moderation_labels(uuid: file.uuid)
+          client.addons.aws_rekognition_detect_moderation_labels_status(request_id: response.request_id)
+        end
+      when 'post_addons_uc_clamav_virus_scan_execute.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          client.addons.uc_clamav_virus_scan(uuid: file.uuid)
+        end
+      when 'get_addons_uc_clamav_virus_scan_execute_status.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          response = client.addons.uc_clamav_virus_scan(uuid: file.uuid)
+          client.addons.uc_clamav_virus_scan_status(request_id: response.request_id)
+        end
+      when 'post_addons_remove_bg_execute.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          client.addons.remove_bg(uuid: file.uuid)
+        end
+      when 'get_addons_remove_bg_execute_status.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          response = client.addons.remove_bg(uuid: file.uuid)
+          client.addons.remove_bg_status(request_id: response.request_id)
+        end
+      when 'get_convert_document_uuid.rb'
+        ApiExamples::ExampleHelper.with_uploaded_pdf do |file|
+          client.conversions.documents.info(uuid: file.uuid)
+        end
+      when 'post_convert_document.rb'
+        ApiExamples::ExampleHelper.with_uploaded_pdf do |file|
+          client.conversions.documents.convert(uuid: file.uuid, format: :jpg)
+        end
+      when 'get_convert_document_status_token.rb'
+        ApiExamples::ExampleHelper.with_uploaded_pdf do |file|
+          response = client.conversions.documents.convert(uuid: file.uuid, format: :jpg)
+          client.conversions.documents.status(token: ApiExamples::ExampleHelper.conversion_token(response))
+        end
+      when 'post_convert_video.rb'
+        ApiExamples::ExampleHelper.with_uploaded_video do |file|
+          client.conversions.videos.convert(uuid: file.uuid, format: :webm, quality: :normal)
+        end
+      when 'get_convert_video_status_token.rb'
+        ApiExamples::ExampleHelper.with_uploaded_video do |file|
+          response = client.conversions.videos.convert(uuid: file.uuid, format: :webm, quality: :normal)
+          client.conversions.videos.status(token: ApiExamples::ExampleHelper.conversion_token(response))
+        end
+      else
+        raise "No REST API example mapped for #{File.basename($PROGRAM_NAME)}"
+      end
+    end
+  end
+end
+
+ApiExamples::RunRestExample.call

data/api_examples/support/run_upload_example.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative 'example_helper'
+
+module ApiExamples::RunUploadExample
+  module_function
+
+  def call
+    ApiExamples::ExampleHelper.run do |client|
+      case File.basename($PROGRAM_NAME)
+      when 'post_base.rb'
+        run_base_upload(client)
+      when 'post_from_url.rb'
+        run_url_upload(client)
+      when 'get_from_url_status.rb'
+        response = ApiExamples::ExampleHelper.unwrap(
+          client.api.upload.files.from_url(
+            source_url: ApiExamples::ExampleHelper::SAMPLE_IMAGE_URL,
+            async: true,
+            store: true
+          )
+        )
+        ApiExamples::ExampleHelper.unwrap(client.api.upload.files.from_url_status(token: response.fetch('token')))
+      when 'get_info.rb'
+        ApiExamples::ExampleHelper.with_uploaded_file do |file|
+          ApiExamples::ExampleHelper.unwrap(client.api.upload.files.info(file_id: file.uuid))
+        end
+      when 'post_group.rb'
+        ApiExamples::ExampleHelper.with_uploaded_files do |files|
+          group = ApiExamples::ExampleHelper.unwrap(client.api.upload.groups.create(files: files.map(&:uuid)))
+          group
+        ensure
+          ApiExamples::ExampleHelper.safe_delete_group(group)
+        end
+      when 'get_group_info.rb'
+        ApiExamples::ExampleHelper.with_uploaded_group do |group, _files|
+          ApiExamples::ExampleHelper.unwrap(client.api.upload.groups.info(group_id: group.id))
+        end
+      when 'post_multipart_start.rb'
+        ApiExamples::ExampleHelper.with_multipart_session do |file, session|
+          completed_file = ApiExamples::ExampleHelper.finish_multipart_upload(file: file, session: session)
+          {
+            'uuid' => session.fetch('uuid'),
+            'parts' => session.fetch('parts').length,
+            'completed_file' => completed_file.fetch('uuid')
+          }
+        end
+      when 'put_multipart_part.rb'
+        ApiExamples::ExampleHelper.with_multipart_session do |file, session|
+          uploaded = ApiExamples::ExampleHelper.upload_multipart_part(file: file, session: session, index: 0)
+          completed = ApiExamples::ExampleHelper.finish_multipart_upload(
+            file: file,
+            session: session,
+            skip_indices: [0]
+          )
+          {
+            'uuid' => session.fetch('uuid'),
+            'uploaded_bytes' => uploaded,
+            'completed_file' => completed.fetch('uuid')
+          }
+        end
+      when 'post_multipart_complete.rb'
+        ApiExamples::ExampleHelper.with_multipart_session do |file, session|
+          ApiExamples::ExampleHelper.finish_multipart_upload(file: file, session: session)
+        end
+      else
+        raise "No Upload API example mapped for #{File.basename($PROGRAM_NAME)}"
+      end
+    end
+  end
+
+  def run_base_upload(client)
+    ApiExamples::ExampleHelper.with_fixture_file('kitten.jpeg') do |handle|
+      ApiExamples::ExampleHelper.unwrap(client.api.upload.files.direct(file: handle, store: true))
+    end
+  end
+
+  def run_url_upload(client)
+    response = ApiExamples::ExampleHelper.unwrap(
+      client.api.upload.files.from_url(source_url: ApiExamples::ExampleHelper::SAMPLE_IMAGE_URL, store: true)
+    )
+    response
+  ensure
+    ApiExamples::ExampleHelper.safe_delete_file(response['uuid']) if response && response['uuid']
+  end
+end
+
+ApiExamples::RunUploadExample.call

data/api_examples/upload_api/get_from_url_status.rb

@@ -1,6 +1,4 @@
-require 'uploadcare'
-Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
-Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-token = '945ebb27-1fd6-46c6-a859-b9893712d650'
-puts Uploadcare::Uploader.get_upload_from_url_status(token)
+require_relative '../support/run_upload_example'

data/api_examples/upload_api/get_group_info.rb

@@ -1,7 +1,4 @@
-require 'uploadcare'
-Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
-Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-uuid = '0d712319-b970-4602-850c-bae1ced521a6~1'
-info = Uploadcare::Group.info(uuid)
-puts info.inspect
+require_relative '../support/run_upload_example'

data/api_examples/upload_api/get_info.rb

@@ -1,7 +1,4 @@
-require 'uploadcare'
-Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
-Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-uuid = '740e1b8c-1ad8-4324-b7ec-112c79d8eac2'
-info = Uploadcare::File.info(uuid)
-puts info.inspect
+require_relative '../support/run_upload_example'

data/api_examples/upload_api/post_base.rb

@@ -1,6 +1,4 @@
-require 'uploadcare'
-Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
-Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-source_file = File.open('image.png')
-Uploadcare::Uploader.upload(source_file, store: 'auto')
+require_relative '../support/run_upload_example'

data/api_examples/upload_api/post_from_url.rb

@@ -1,6 +1,4 @@
-require 'uploadcare'
-Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
-Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-source_url = 'https://source.unsplash.com/featured'
-Uploadcare::Uploader.upload(source_url, store: 'auto')
+require_relative '../support/run_upload_example'

data/api_examples/upload_api/post_group.rb

@@ -1,9 +1,4 @@
-require 'uploadcare'
-Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
-Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-uuids = [
-  'd6d34fa9-addd-472c-868d-2e5c105f9fcd',
-  'b1026315-8116-4632-8364-607e64fca723/-/resize/x800/'
-]
-Uploadcare::Group.create(uuids)
+require_relative '../support/run_upload_example'

data/api_examples/upload_api/post_multipart_complete.rb

@@ -1,8 +1,4 @@
-# Uploadcare lib provides high level API for multipart uploads that does everything for you
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require 'uploadcare'
-Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
-Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
-
-source_file = File.open('image.png')
-Uploadcare::Uploader.upload(source_file, store: 'auto')
+require_relative '../support/run_upload_example'

data/api_examples/upload_api/post_multipart_start.rb

@@ -1,8 +1,4 @@
-# Uploadcare lib provides high level API for multipart uploads that does everything for you
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require 'uploadcare'
-Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
-Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'
-
-source_file = File.open('image.png')
-Uploadcare::Uploader.upload(source_file, store: 'auto')
+require_relative '../support/run_upload_example'

data/api_examples/upload_api/put_multipart_part.rb

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../support/run_upload_example'

data/bin/console

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 require 'bundler/setup'
-require 'uploadcare/ruby'
+require 'uploadcare'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.

data/docs/release-notes-5.0.0.rc1.md

@@ -0,0 +1,34 @@
+# uploadcare-ruby 5.0.0.rc1
+
+This release candidate is the first public v5 cut from the rewritten codebase.
+
+Please review [MIGRATING_V5.md](../MIGRATING_V5.md) before upgrading from v4.x.
+
+## Highlights
+
+- New client-first public API centered on `Uploadcare::Client`
+- Full endpoint-parity access through `client.api.rest` and `client.api.upload`
+- Multi-account support through client-scoped `Uploadcare::Configuration`
+- Faraday + Zeitwerk modernization across the codebase
+- Ruby 4.0 support in the CI matrix
+
+## Important Fixes Included In RC1
+
+- REST signing uses deterministic protocol-required digests (`MD5` and `SHA1`)
+- REST query signing uses the same nested parameter encoding as request transmission
+- Multipart upload retries/timeouts now honor configuration (`max_upload_retries`, `upload_timeout`)
+- Multipart upload worker cancellation now stops remaining queued work after first worker error
+- Upload-from-URL polling now supports exponential backoff with configurable cap
+- Multipart start payload no longer sends unsupported `part_size` to `/multipart/start/`
+- Upload API batch uploads avoid duplicate filename key collisions without mutating caller-visible filenames
+- `FileMetadata` resource instance initialization correctly assigns `uuid`
+
+## Upgrade Notes
+
+- Ruby support baseline is now `>= 3.3`.
+- If you use multiple Uploadcare projects/accounts, prefer explicit `Uploadcare::Client` instances.
+- Keep rollback simple by pinning to the latest v4 release if your app depends on removed internal APIs.
+
+## Full Changelog
+
+See [CHANGELOG.md](../CHANGELOG.md).