Polish v5 migration docs and wrapper return examples

Author: vipulnsward

MIGRATING_V5.md

@@ -10,6 +10,10 @@ This guide covers migration from `uploadcare-rails` 3.x/4.x to 5.0.
 
 - Minimum supported Ruby is now `3.3+`.
 
+### Rails version
+
+- Minimum supported Rails is now `7.0+`.
+
 ### Dependency baseline
 
 - `uploadcare-ruby` 5.x is now required.
@@ -47,6 +51,16 @@ Methods in `Uploadcare::*Api` wrappers now return `uploadcare-ruby` v5 objects/r
 
 `Uploadcare::WebhookApi.delete_webhook` returns the direct SDK response payload.
 
+### Wrapper object return contract
+
+Mounted wrappers still work, but now return v5-native objects:
+
+- `post.picture.store` -> `Uploadcare::Rails::File`
+- `post.picture.delete` -> `Uploadcare::File`
+- `post.picture.load` -> `Uploadcare::Rails::File`
+- `post.attachments.store` -> `Uploadcare::Group`
+- `post.attachments.load` -> `Uploadcare::Rails::Group`
+
 ### Conversion API return contract
 
 `Uploadcare::ConversionApi` no longer uses `dry-monads` style `Success(...)`/`Failure(...)` wrappers.
@@ -58,11 +72,41 @@ It now returns direct v5 SDK values:
 - `get_document_conversion_status` -> `Uploadcare::DocumentConverter`
 - `get_document_conversion_formats_info` -> `Uploadcare::DocumentConverter`
 
+## New in 5.0
+
+### Per-model Uploadcare config selection
+
+`mount_uploadcare_file` and `mount_uploadcare_file_group` now accept `uploadcare_config:`.
+You can pass either an `Uploadcare::Configuration` instance or a proc.
+
+```ruby
+class Post < ApplicationRecord
+  mount_uploadcare_file :picture, uploadcare_config: -> {
+    Uploadcare::Rails.client_config(
+      public_key: tenant_uploadcare_public_key,
+      secret_key: tenant_uploadcare_secret_key
+    )
+  }
+end
+```
+
+When async store/delete jobs are enabled, this configuration is serialized and passed into jobs automatically.
+
+### Active Storage integration
+
+`ActiveStorage::Service::UploadcareService` is available in `5.0`.
+
+Current limitation:
+
+- Direct upload URL flow is not implemented yet (`url_for_direct_upload` raises `NotImplementedError`).
+
 ## Migration checklist
 
 1. Upgrade Ruby to `3.3+`.
-2. Upgrade to `uploadcare-rails` 5.x.
-3. Replace any `Uploadcare.config` usage with `Uploadcare.configuration`.
-4. Update integrations that expected Hash/monad responses from wrapper APIs.
-5. Run your full application and test suite.
-
+2. Upgrade Rails to `7.0+`.
+3. Upgrade to `uploadcare-rails` 5.x.
+4. Replace any `Uploadcare.config` usage with `Uploadcare.configuration`.
+5. Update integrations that expected Hash/monad responses from wrapper APIs.
+6. If you use per-tenant keys, move mounts/API calls to explicit `uploadcare_config:` / `config:` usage.
+7. If you use Active Storage direct upload flow, keep your existing service until this is implemented.
+8. Run your full application and test suite.

README.md

@@ -247,6 +247,19 @@ class Post < ApplicationRecord
 end
 ```
 
+For multi-tenant setups, you can bind a non-default Uploadcare config:
+
+```ruby
+class Post < ApplicationRecord
+  mount_uploadcare_file :picture, uploadcare_config: -> {
+    Uploadcare::Rails.client_config(
+      public_key: tenant_uploadcare_public_key,
+      secret_key: tenant_uploadcare_secret_key
+    )
+  }
+end
+```
+
 ```erb
 <!-- app/views/posts/new.html.erb -->
 <h1> NEW POST </h1>
@@ -272,6 +285,8 @@ class Post < ApplicationRecord
 end
 ```
 
+`mount_uploadcare_file_group` also supports `uploadcare_config:` in the same way.
+
 ```erb
 <!-- app/views/posts/new.html.erb -->
 <h1> NEW POST </h1>
@@ -372,18 +387,12 @@ Now the `post.picture` is an Uploadcare::Rails::File. Following methods are supp
 ```ruby
 # Store the file on an Uploadcare server permanently:
 post.picture.store
-#   => {
-#         "cdn_url"=>"https://ucarecdn.com/2d33999d-c74a-4ff9-99ea-abc23496b052/",
-#          ...other group data...
-#      }
+#   => #<Uploadcare::Rails::File ...>
 
 #
 # Delete the file from an Uploadcare server permanently:
 post.picture.delete
-#   => {
-#         "datetime_removed"=>"2021-07-30T09:19:30.797174Z",
-#          ...other group data...
-#      }
+#   => #<Uploadcare::File ...>
 
 # Get CDN-url of an object attribute:
 post.picture.to_s
@@ -393,10 +402,7 @@ post.picture.to_s
 # This data will be cached if the cache_files option is set to true
 # Default data (without asking an Uploadcare server) for each file contains cdn_url and uuid only:
 post.picture.load
-#   => {
-#         "cdn_url"=>"https://ucarecdn.com/2d33999d-c74a-4ff9-99ea-abc23496b052/",
-#          ...other file data...
-#      }
+#   => #<Uploadcare::Rails::File ...>
 
 # Check if an attribute loaded from the server.
 # Will return false unless the :load or the :store methods are called:
@@ -431,37 +437,20 @@ Now the `post.attachments` is an Uploadcare::Rails::Group. Following methods are
 ```ruby
 # Store the file group on an Uploadcare server permanently:
 post.attachments.store
-#   => {
-#         "cdn_url"=>"https://ucarecdn.com/dbc4e868-b7a6-43ff-a35f-2ebef935dc1b~1/",
-#          ...other group data...
-#         "files"=> [{
-#            "datetime_stored"=>"2021-07-29T08:31:45.668354Z",
-#            ...other file data...
-#         }]
-#      }
+#   => #<Uploadcare::Group ...>
 
 #
 # Delete the file group from an Uploadcare server permanently:
 post.attachments.delete
-#   => {
-#         "datetime_removed"=>"2021-07-30T09:19:30.797174Z",
-#          ...other group data...
-#      }
+#   => #<direct SDK response payload>
 
 # Get CDN-url of an object attribute:
 post.attachments.to_s
 #   => "https://ucarecdn.com/dbc4e868-b7a6-43ff-a35f-2ebef935dc1b~1/"
 
 # Load object — works the same way as for the File:
 post.attachments.load
-#   => {
-#         "cdn_url"=>"https://ucarecdn.com/dbc4e868-b7a6-43ff-a35f-2ebef935dc1b~1/",
-#          ...other group data...
-#         "files"=> [{
-#            "datetime_stored"=>"2021-07-29T08:31:45.668354Z",
-#            ...other file data...
-#         }]
-#      }
+#   => #<Uploadcare::Rails::Group ...>
 
 # Check if an attribute loaded from the server:
 post.attachments.loaded?