imagekitio 3.0.0 → 4.0.0

data/README.md

@@ -1,885 +1,744 @@
-[<img width="250" alt="ImageKit.io" src="https://raw.githubusercontent.com/imagekit-developer/imagekit-javascript/master/assets/imagekit-light-logo.svg"/>](https://imagekit.io)
-
-# Imagekit Ruby and Rails SDK
-
-[![Ruby Test](https://github.com/imagekit-developer/imagekit-ruby/workflows/Ruby%20Test/badge.svg)](https://github.com/imagekit-developer/imagekit-ruby)
-[![Gem Version](https://badge.fury.io/rb/imagekitio.svg)](https://badge.fury.io/rb/imagekitio)
-[![codecov](https://codecov.io/gh/imagekit-developer/imagekit-ruby/branch/master/graph/badge.svg)](https://codecov.io/gh/imagekit-developer/imagekit-ruby)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Twitter Follow](https://img.shields.io/twitter/follow/imagekitio?label=Follow&style=social)](https://twitter.com/ImagekitIo)
-
-Ruby on Rails gem for [ImageKit](https://imagekit.io/) implements the new APIs and interface for different file operations.
-
-ImageKit is complete media storage, optimization, and transformation solution that comes with an [image and video CDN](https://imagekit.io/features/imagekit-infrastructure). It can be integrated with your existing infrastructure - storage like AWS S3, web servers, your CDN, and custom domain names, allowing you to deliver optimized images in minutes with minimal code changes.
-
-Table of contents -
- * [Changelog](#changelog)
- * [Installation](#installation)
- * [Initialization](#initialization)
-    - [CarrierWave](#carrierwave)
-    - [ActiveStorage](#activestorage)
- * [URL Generation](#url-generation)
- * [File Upload](#file-upload)
- * [File Management](#file-management)
- * [Utility Functions](#utility-functions)
- * [Sample applications](#sample-application)
- * [Upgrade to 2.x](#upgrade-to-2x)
- * [Support](#support)
- * [Links](#links)
-
-
-# Quick start guide
-Get started with [official quick start guide](https://docs.imagekit.io/getting-started/quickstart-guides/ruby-guides) for integrating ImageKit in Ruby on Rails.
-
-## Changelog
-### SDK Version 3.0.0
-#### Breaking changes
-**1. Overlay syntax update**
-* In version 3.0.0, we've removed the old overlay syntax parameters for transformations, such as `oi`, `ot`, `obg`, and [more](https://docs.imagekit.io/features/image-transformations/overlay). These parameters are deprecated and will start returning errors when used in URLs. Please migrate to the new layers syntax that supports overlay nesting, provides better positional control, and allows more transformations at the layer level. You can start with [examples](https://docs.imagekit.io/features/image-transformations/overlay-using-layers#examples) to learn quickly.
-* You can migrate to the new layers syntax using the `raw` transformation parameter.
+# ImageKit.io Ruby SDK
+
+The ImageKit Ruby library provides convenient access to the ImageKit REST API from any Ruby 3.2.0+ application. The library supports building and transforming URLs, generating signed URLs for secure content delivery, and handling file uploads. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/imagekit-developer/imagekit-ruby#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
+
+## Documentation
+
+The official [ImageKit Ruby documentation](https://imagekit.io/docs/integration/ruby) provides complete integration guides and examples.
+
+If you're using Ruby on Rails, the [ImageKit Rails gem](https://github.com/imagekit-developer/imagekit-rails) builds on top of this SDK to provide [Rails-specific integrations](https://imagekit.io/docs/integration/ruby/ruby-on-rails) including Active Storage and view helpers.
+
+## Table of Contents
+
+- [Documentation](#documentation)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [File uploads](#file-uploads)
+- [URL Generation](#url-generation)
+  - [Basic URL generation](#basic-url-generation)
+  - [URL generation with transformations](#url-generation-with-transformations)
+  - [URL generation with image overlay](#url-generation-with-image-overlay)
+  - [URL generation with text overlay](#url-generation-with-text-overlay)
+  - [Signed URLs for secure delivery](#signed-urls-for-secure-delivery)
+  - [Chained transformations](#chained-transformations)
+  - [Using raw parameter for custom transformations](#using-raw-parameter-for-custom-transformations)
+- [Helper Methods](#helper-methods)
+  - [Authentication parameters for client-side uploads](#authentication-parameters-for-client-side-uploads)
+  - [Responsive image attributes](#responsive-image-attributes)
+- [Handling errors](#handling-errors)
+  - [Retries](#retries)
+  - [Timeouts](#timeouts)
+- [Advanced concepts](#advanced-concepts)
+  - [BaseModel](#basemodel)
+  - [Making custom or undocumented requests](#making-custom-or-undocumented-requests)
+  - [Concurrency & connection pooling](#concurrency--connection-pooling)
+- [Sorbet](#sorbet)
+  - [Enums](#enums)
+- [Versioning](#versioning)
+- [Requirements](#requirements)
+- [Contributing](#contributing)
 
 ## Installation
 
-Add `imagekitio` dependency to your application's Gemfile:
+To use this gem, install via Bundler by adding the following to your application's `Gemfile`:
 
-```ruby
-gem 'imagekitio'
-```
+<!-- x-release-please-start-version -->
 
-And then execute:
-```
-$ bundle install
-```
-
-Or install it yourself:
-```
-$ gem install imagekitio
-```
-
-## Initialization
-
-Create a new file `config/initializers/imagekitio.rb` then add the configuration.
 ```ruby
-ImageKitIo.configure do |config|
-  if Rails.env.development?
-    config.public_key = 'your_public_api_key'
-    config.private_key = 'your_private_api_key'
-    config.url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
-  end
-  config.service = :carrierwave
-  #config.service = :active_storage
-  #config.constants.MISSING_PRIVATE_KEY = 'custom error message'
-end
+gem "imagekitio", "~> 4.0.0"
 ```
-#### CarrierWave
-You can create a CarrierWave uploader to attach pictures to your database objects as their attributes. Skip to [this section](https://github.com/imagekit-developer/imagekit-ruby#file-upload) to upload images without designating them as database attributes. Make sure to add service `:carrierwave` as shown in [initialization section](#initialization).
-
-```bash
-rails g uploader <Uploading_attribute_name>
-# For example, if you want to create an uploader for Avatar attribute, then use
-rails g uploader Avatar
-# Generated uploader's path will be app/uploaders/avatar_uploader.rb
-```
-
-After that, you need to edit your generated uploader and make the following changes:
-```ruby
-# include this module inside the top of the uploader class
-include ImageKitIo::CarrierWave
 
-# If you want to add uploading options, then create this method inside the uploader file as an example
+<!-- x-release-please-end -->
 
-def options
-    options={
-        response_fields: 'isPrivateFile, tags',
-        tags: %w[abc def],
-        use_unique_file_name: false,
-        folder: "your_directory/"
-    }
-end
-
-# If you want to set upload dir, then you can use the following method, or you can also use the options method.
-# This method should return a string
-def store_dir
-    "your_directory/"
-end
-```
-
-Then you need to modify your model. for example- if your model name is employee, then do these changes.
-
-```ruby
-class Employee < ApplicationRecord
-    attr_accessor :avatar
-    mount_uploader :avatar, AvatarUploader
-end
-```
+## Usage
 
-Get image url:
 ```ruby
-# If @employee is an object of your model that has data.
-
-# To get the original image url, use
-@employee.avatar.url
+require "imagekitio"
 
-# To get the file metadata
-@employee.avatar.metadata
+image_kit = Imagekitio::Client.new(
+  private_key: ENV["IMAGEKIT_PRIVATE_KEY"], # This is the default and can be omitted
+)
 
+response = image_kit.files.upload(
+  file: Pathname("/path/to/file"),
+  file_name: "file-name.jpg"
+)
 
-# And to get transformed url use
-# options is a transformation options
-@employee.avatar.url_with(options)
+puts(response.file_id)
 ```
 
-#### ActiveStorage
-
-Once you [install](https://guides.rubyonrails.org/active_storage_overview.html#setup) the active_storage gem, then any model can have the attachment using `has_one_attached` or `has_many_attached` like below:
+### File uploads
 
-```ruby
-class Employee < ApplicationRecord
-  has_one_attached :avatar
-end
-```
+Request parameters that correspond to file uploads can be passed as raw contents, a [`Pathname`](https://rubyapi.org/3.2/o/pathname) instance, or an `IO` stream.
 
-Get image url:
 ```ruby
-# If @employee is an object of your model that has data.
+require "pathname"
 
-# To get the original image url, use
-@employee.avatar.url
-```
-
-Now, let's configure active_storage as a service for the imagekitio. 
-
-First add `:active_storage` in initializer file.
+# Use `Pathname` to stream from disk (memory efficient, supports retries):
+response = image_kit.files.upload(file: Pathname("/path/to/file"))
 
-```ruby
-config.service = :active_storage
-``` 
+# Or pass file contents directly
+response = image_kit.files.upload(file: File.read("/path/to/file"))
 
-Then add the imagekitio service in the `storage.yml` file:
+# Or, to control the filename and/or content type:
+file = Imagekitio::FilePart.new(File.read("/path/to/file"), filename: "/path/to/file", content_type: "…")
+response = image_kit.files.upload(file: file)
 
-```ruby
-imagekitio:
-    service: ImageKitIo
+puts(response.file_id)
 ```
 
+Note that you can also pass a raw `IO` descriptor, but this disables retries, as the library can't be sure if the descriptor is a file or pipe (which cannot be rewound).
 
-## Usage
+## URL Generation
 
-You can use this Ruby SDK for three different methods - URL generation, file upload, and media management operations. The usage of the SDK has been explained below.
+The ImageKit SDK provides a powerful `helper.build_url()` method for generating optimized image and video URLs with transformations. Here are examples ranging from simple URLs to complex transformations with overlays and signed URLs.
 
-* `URL Generation`
-* `File Upload`
-* `File Management`
+### Basic URL generation
 
-## URL generation
+Generate a simple URL without any transformations:
 
-**1. Using Image path and image hostname or endpoint**
+```ruby
+require "imagekitio"
 
-This method allows you to create an URL to access a file using the relative file path and the ImageKit URL endpoint (`urlEndpoint`). The file can be an image, video or any other static file supported by ImageKit.
+image_kit = Imagekitio::Client.new(
+  private_key: ENV["IMAGEKIT_PRIVATE_KEY"]
+)
 
-```ruby
-imagekitio = ImageKitIo.client
-image_url = imagekitio.url({
-    path: "/default-image.jpg",
-    url_endpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/",
-    transformation: [{height: "300", width: "400", raw: "ar-4-3,q-40"}]
+# Basic URL without transformations
+url = image_kit.helper.build_url({
+  src: "/default-image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id"
 })
-```
 
-The result in a URL like
-```
-https://ik.imagekit.io/your_imagekit_id/endpoint/tr:h-300,w-400,ar-4-3,q-40/default-image.jpg
+puts url
+# Output: https://ik.imagekit.io/your_imagekit_id/default-image.jpg
 ```
 
-**2.Using full image URL**
-This method allows you to add transformation parameters to an absolute URL. For example, if you have configured a custom CNAME and have absolute asset URLs in your database or CMS, you will often need this.
-
+You can also use absolute URLs:
 
 ```ruby
-image_url = imagekitio.url({
-    src: "https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg",
-    transformation: [{height: "300", width: "400"}],
+url = image_kit.helper.build_url({
+  src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id"
 })
 ```
 
-The results in a URL like
-
-```
-https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=h-300%2Cw-400
-```
-
-
-The `.url()` method accepts the following parameters
-
-| Option                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| url_endpoint            | Optional. The base URL to be appended before the path of the image. If not specified, the URL Endpoint specified at the time of SDK initialization is used. For example, https://ik.imagekit.io/your_imagekit_id/endpoint/                                                                                                                                                                                                                                                                                                                                                                |
-| path                    | Conditional. This is the path at which the image exists. For example, `/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation.                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| src                     | Conditional. This is the complete URL of an image already mapped to ImageKit. For example, `https://ik.imagekit.io/your_imagekit_id/endpoint/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation.                                                                                                                                                                                                                                                                                                                                            |
-| transformation          | Optional. An array of objects specifying the transformation to be applied in the URL. The transformation name and the value should be specified as a key-value pair in the object. Different steps of a [chained transformation](https://docs.imagekit.io/features/image-transformations/chained-transformations) can be specified as different objects of the array. The complete list of supported transformations in the SDK and some examples of using them are given later. If you use a transformation name that is not specified in the SDK, it gets applied as it is in the URL. |
-| transformation_position | Optional. The default value is `path` that places the transformation string as a path parameter in the URL. It can also be specified as `query`, which adds the transformation string as the query parameter `tr` in the URL. If you use `src` parameter to create the URL, then the transformation string is always added as a query parameter.                                                                                                                                                                                                                                                  |
-| query_parameters        | Optional. These are the other query parameters that you want to add to the final URL. These can be any query parameters and not necessarily related to ImageKit. Especially useful if you want to add some versioning parameters to your URLs.                                                                                                                                                                                                                                                                                                                                            |
-| signed                  | Optional. Boolean. Default is `false`. If set to `true`, the SDK generates a signed image URL adding the image signature to the image URL. This can only be used if you are creating the URL with the `url_endpoint` and `path` parameters and not with the `src` parameter.                                                                                                                                                                                                                                                                                                             |
-| expire_seconds          | Optional. Integer. Meant to be used along with the `signed` parameter to specify the time in seconds from now when the URL should expire. If specified, the URL contains the expiry timestamp in the URL, and the image signature is modified accordingly.                                                                                                                                                                                                                                                                                                                                 |
+### URL generation with transformations
 
-
-## Examples of generating URLs
-**1. Chained Transformations as a query parameter**
+Apply common transformations like resizing, cropping, and format conversion:
 
 ```ruby
-image_url = imagekitio.url({
-    path: "/default-image.jpg",
-    url_endpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/",
-    transformation: [{
-        height: "300",
-        width: "400"
-    },{
-        rotation: 90
-    }],
-    transformation_position: "query"
+# URL with basic transformations
+url = image_kit.helper.build_url({
+  src: "/path/to/image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  transformation: [
+    {
+      width: 400,
+      height: 300,
+      crop: :maintain_ratio,
+      quality: 80,
+      format_: :webp
+    }
+  ]
 })
+# Output: https://ik.imagekit.io/your_imagekit_id/path/to/image.jpg?tr=w-400,h-300,c-maintain_ratio,q-80,f-webp
 ```
-Sample Result URL -
-```
-https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=h-300%2Cw-400%3Art-90
-```
-
-**2. Sharpening and contrast transforms and a progressive JPG image**
-
-There are some transforms like [Sharpening](https://docs.imagekit.io/features/image-transformations/image-enhancement-and-color-manipulation)
-that can be added to the URL with or without any other value. To use such transforms without specifying a value, specify
-the value as "-" in the transformation object. Otherwise, specify the value that you want to be
-added to this transformation.
 
+More transformation examples:
 
 ```ruby
-image_url = imagekitio.url({
-    src: "https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg",
-    transformation: [{
-        format: "jpg",
-        progressive: "true",
-        effect_sharpen: "-",
-        effect_contrast: "1"
-    }]
+# Image resizing and cropping
+url = image_kit.helper.build_url({
+  src: "/product.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  transformation: [
+    {
+      width: 800,
+      height: 600,
+      crop: :at_max,
+      focus: "auto"
+    }
+  ]
 })
-```
 
-```
-//Note that because `src` parameter was used, the transformation string gets added as a query parameter `tr`
-https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=f-jpg%2Cpr-true%2Ce-sharpen%2Ce-contrast-1
-```
+# Image effects
+url = image_kit.helper.build_url({
+  src: "/photo.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  transformation: [
+    {
+      blur: 10,
+      grayscale: true,
+      radius: 20
+    }
+  ]
+})
 
-**3. Signed URL that expires in 300 seconds with the default URL endpoint and other query parameters**
+# Format and quality optimization
+url = image_kit.helper.build_url({
+  src: "/image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  transformation: [
+    {
+      format_: :auto,
+      quality: 85,
+      progressive: true
+    }
+  ]
+})
+```
 
-```ruby
-image_url = imagekit.url({
-    path: "/default-image",
-    query_parameters: {
-                "v": "123"
+### URL generation with image overlay
+
+Add image overlays to your base image:
+
+```ruby
+# URL with image overlay
+url = image_kit.helper.build_url({
+  src: "/path/to/base-image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  transformation: [
+    {
+      width: 500,
+      height: 400,
+      overlay: {
+        type: :image,
+        input: "/path/to/overlay-logo.png",
+        position: {
+          x: 10,
+          y_: 10
+        },
+        transformation: [
+          {
+            width: 100,
+            height: 50
+          }
+        ]
+      }
+    }
+  ]
+})
+# Output: URL with image overlay positioned at x:10, y:10
+```
+
+### URL generation with text overlay
+
+Add customized text overlays:
+
+```ruby
+# URL with text overlay
+url = image_kit.helper.build_url({
+  src: "/path/to/base-image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  transformation: [
+    {
+      width: 600,
+      height: 400,
+      overlay: {
+        type: :text,
+        text: "Sample Text Overlay",
+        position: {
+          x: 50,
+          y_: 50,
+          focus: :center
+        },
+        transformation: [
+          {
+            font_size: 40,
+            font_family: "Arial",
+            font_color: "FFFFFF",
+            typography: "b"  # bold
+          }
+        ]
+      }
+    }
+  ]
+})
+# Output: URL with bold white Arial text overlay at center position
+```
+
+You can combine multiple overlays for complex compositions:
+
+```ruby
+# URL with multiple overlays (text + image)
+url = image_kit.helper.build_url({
+  src: "/path/to/base-image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  transformation: [
+    {
+      width: 800,
+      height: 600,
+      overlay: {
+        type: :text,
+        text: "Header Text",
+        position: { x: 20, y_: 20 },
+        transformation: [{ font_size: 30, font_color: "000000" }]
+      }
     },
-    transformation: [{
-        height: "300",
-        width: "400"
-    }],
-    signed: True,
-    expire_seconds: 300
+    {
+      overlay: {
+        type: :image,
+        input: "/watermark.png",
+        position: { focus: :bottom_right },
+        transformation: [{ width: 100, opacity: 70 }]
+      }
+    }
+  ]
 })
+# Output: URL with text overlay at top-left and semi-transparent watermark at bottom-right
 ```
-**Sample Result URL**
-```
-https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400/default-image.jpg?v=123&ik-t=1567358667&ik-s=f2c7cdacbe7707b71a83d49cf1c6110e3d701054
-```
-
-**4. Adding overlays**
 
-ImageKit.io enables you to apply overlays to [images](https://docs.imagekit.io/features/image-transformations/overlay-using-layers) and [videos](https://docs.imagekit.io/features/video-transformation/overlay) using the raw parameter with the concept of [layers](https://docs.imagekit.io/features/image-transformations/overlay-using-layers#layers). The raw parameter facilitates incorporating transformations directly in the URL. A layer is a distinct type of transformation that allows you to define an asset to serve as an overlay, along with its positioning and additional transformations.
+### Signed URLs for secure delivery
 
-**Text as overlays**
-
-You can add any text string over a base video or image using a text layer (l-text).
-
-For example:
+Generate signed URLs that expire after a specified time for secure content delivery:
 
 ```ruby
-image_url = imagekit.url({
-    path: "/default-image",
-    url_endpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/",
-    transformation: [{
-        height: "300",
-        width: "400",
-        raw: "l-text,i-Imagekit,fs-50,l-end"
-    }],
+# Generate a signed URL that expires in 1 hour (3600 seconds)
+url = image_kit.helper.build_url({
+  src: "/private/secure-image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  transformation: [
+    {
+      width: 400,
+      height: 300,
+      quality: 90
+    }
+  ],
+  signed: true,
+  expires_in: 3600  # URL expires in 1 hour
 })
-```
-**Sample Result URL**
-```
-https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-text,i-Imagekit,fs-50,l-end/default-image.jpg
+# Output: URL with signature parameters (?ik-t=timestamp&ik-s=signature)
+
+# Generate a signed URL that doesn't expire
+url = image_kit.helper.build_url({
+  src: "/private/secure-image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  signed: true
+  # No expires_in means the URL won't expire
+})
+# Output: URL with signature parameter (?ik-s=signature)
 ```
 
-**Image as overlays**
+### Chained transformations
 
-You can add an image over a base video or image using an image layer (l-image).
-
-For example:
+Apply multiple transformation steps by passing multiple transformation objects. Each transformation is applied sequentially:
 
 ```ruby
-image_url = imagekit.url({
-    path: "/default-image",
-    url_endpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/",
-    transformation: [{
-        height: "300",
-        width: "400",
-        raw: "l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end"
-    }],
+# First resize, then apply effects
+url = image_kit.helper.build_url({
+  src: "/default-image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  transformation: [
+    {
+      width: 400,
+      height: 300
+    },
+    {
+      rotation: 90,
+      blur: 5
+    }
+  ]
 })
+# Output: https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=w-400,h-300:rt-90,bl-5
 ```
-**Sample Result URL**
-```
-https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end/default-image.jpg
-```
-
-**Solid color blocks as overlays**
 
-You can add solid color blocks over a base video or image using an image layer (l-image).
+### Using raw parameter for custom transformations
 
-For example:
+ImageKit frequently adds new transformation parameters that might not yet be documented in the SDK. You can use the `raw` parameter to access these features or create custom transformation strings:
 
 ```ruby
-image_url = imagekit.url({
-    path: "/img/sample-video",
-    url_endpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/",
-    transformation: [{
-        height: "300",
-        width: "400",
-        raw: "l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end"
-    }],
+# Using raw parameter for custom transformations
+url = image_kit.helper.build_url({
+  src: "/path/to/image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  transformation: [
+    {
+      width: 400,
+      height: 300,
+      raw: "something-new"
+    }
+  ]
 })
-```
-**Sample Result URL**
-```
-https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end/img/sample-video.mp4
+# Output: https://ik.imagekit.io/your_imagekit_id/path/to/image.jpg?tr=w-400,h-300,something-new
 ```
 
-**5. Arithmetic expressions in transformations**
-
-ImageKit allows use of [arithmetic expressions](https://docs.imagekit.io/features/arithmetic-expressions-in-transformations) in certain dimension and position-related parameters, making media transformations more flexible and dynamic.
-
-For example:
+You can control where transformations appear in the URL:
 
 ```ruby
-image_url = imagekit.url({
-    path: "/default-image.jpg",
-    url_endpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/",
-    transformation: [{
-        width: "iw_div_4",
-        height: "ih_div_2",
-        border: "cw_mul_0.05_yellow"
-    }]
-});
-```
-
-**Sample Result URL**
-```
-https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=w-iw_div_4,h-ih_div_2,b-cw_mul_0.05_yellow
+# Add transformations to the URL path instead of query parameters
+url = image_kit.helper.build_url({
+  src: "/default-image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  transformation_position: :path,
+  transformation: [
+    {
+      width: 400,
+      height: 300
+    }
+  ]
+})
+# Output: https://ik.imagekit.io/your_imagekit_id/tr:w-400,h-300/default-image.jpg
 ```
 
-**List of transformations**
-
-The complete list of transformations supported and their usage in ImageKit can be found [here](https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations). The SDK gives a name to each transformation parameter, making the code simpler, making the code simpler, and readable.
-
-If a transformation is supported in ImageKit, but a name for it cannot be found in the table below, then use the transformation code from ImageKit docs as the name when using the `url` function.
-
-If you want to generate transformations in your application and add them to the URL as it is, use the `raw` parameter.
-
-| Supported Transformation Name | Translates to parameter |
-|-------------------------------|-------------------------|
-| height | h |
-| width | w |
-| aspect_ratio | ar |
-| quality | q |
-| crop | c |
-| crop_mode | cm |
-| x | x |
-| y | y |
-| focus | fo |
-| format | f |
-| radius | r |
-| background | bg |
-| border | b |
-| rotation | rt |
-| blur | bl |
-| named | n |
-| progressive | pr |
-| lossless | lo |
-| trim | t |
-| metadata | md |
-| color_profile | cp |
-| default_image | di |
-| dpr | dpr |
-| effect_sharpen | e-sharpen |
-| effect_usm | e-usm |
-| effect_contrast | e-contrast |
-| effect_gray | e-grayscale |
-| effect_shadow | e-shadow |
-| effect_gradient | e-gradient |
-| original | orig |
-| raw | `replaced by the parameter value` |
-
-## File Upload
-This method can be used to directly upload images to your ImageKit Media Library without giving it the designation of an attribute of any database object.
-
-The SDK provides a simple interface using the `.upload()` method to upload files to the ImageKit Media library. It
-accepts all the parameters supported by the [ImageKit Upload API](https://docs.imagekit.io/api-reference/upload-file-api/server-side-file-upload).
-
-The `upload()` method requires at least the `file` and the `file_name` parameter to upload a file and returns
-a callback with the `error` and `result`  as arguments. You can pass other parameters supported by the
-ImageKit upload API using the same parameter name as specified in the upload API documentation. For example, to specify tags for a file at the time of upload, use the `tags` parameter as specified in the [documentation here](https://docs.imagekit.io/api-reference/upload-file-api/server-side-file-upload).
-
-Simple usage
+Add custom query parameters:
 
 ```ruby
-imagekitio.upload_file(
-    file: "<url|base_64|binary>", # required
-    file_name: "my_file_name.jpg",  # required
-    response_fields: 'isPrivateFile, tags',
-    tags: %w[abc def],
-    use_unique_file_name: true
-)
-
+url = image_kit.helper.build_url({
+  src: "/default-image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  query_parameters: {
+    version: "1",
+    cache: "max"
+  }
+})
 ```
 
-If the upload is succeeded, `error` will be `None`, and the result will be the same as what is received from ImageKit's
-servers. If the upload fails, `error` will be the same as what is received from ImageKit's servers, and the result will
-be `None`.
-
-## File Management
-
-The SDK provides a simple interface for all the [media APIs mentioned here](https://docs.imagekit.io/api-reference/media-api)
-to manage your files. This also returns `error` and `result`. The `error` will be `None` if API succeeds.
+## Helper Methods
 
-**List & Search Files**
+The SDK provides several helper methods for common ImageKit operations.
 
-Accepts an object specifying the parameters to be used to list and search files. All parameters specified
-in the [documentation here](https://docs.imagekit.io/api-reference/media-api/list-and-search-files#list-and-search-file-api) can be passed with the
-correct values to get the results.
+### Authentication parameters for client-side uploads
 
-```ruby
-imagekitio.list_files(
-    skip: 0,
-    limit: 5
-)
-```
-**Get File Details**
-Accepts the file ID and fetches the details as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/get-file-details)
+Generate authentication parameters for secure client-side file uploads. These parameters allow you to securely upload files directly from the browser without exposing your private API key:
 
 ```ruby
-imagekitio.get_file_details(
-    file_id: '598821f949c0a938d57563bd'
-)
-```
+require "imagekitio"
 
-**Get File Metadata**
-Accepts the file ID and fetches the metadata as per the [API documentation here](https://docs.imagekit.io/api-reference/metadata-api/get-image-metadata-for-uploaded-media-files)
-```ruby
-imagekit.get_file_metadata(
-    file_id: '598821f949c0a938d57563bd'
+image_kit = Imagekitio::Client.new(
+  private_key: ENV["IMAGEKIT_PRIVATE_KEY"]
 )
-```
 
-**Get File Metadata from remote url**
-Accepts the remote file url and fetches the metadata as per the [API documentation here](https://docs.imagekit.io/api-reference/metadata-api/get-image-metadata-from-remote-url)
+# Generate authentication parameters with default expiry (30 minutes)
+auth_params = image_kit.helper.get_authentication_parameters
 
-```ruby
-imagekit.get_remote_file_url_metadata(
-    remote_file_url: "https://ik.imagekit.io/demo/tr:w-100/default-image.jpg"
-)
+puts auth_params
+# Output: { token: "unique-token", expire: 1234567890, signature: "signature-hash" }
 ```
 
-**Update File Details**
-Update parameters associated with the file as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/update-file-details).
-The first argument to the `update_field_details` method is the file ID, and a second argument is an object with the
-parameters to be updated.
+Customize the token and expiration:
 
 ```ruby
-imagekitio.update_file_details(
-    file_id: '598821f949c0a938d57563bd',
-    tags: ["image_tag"],
-    custom_coordinates: "10,10,100, 100"
+# Custom token and expiry (1 hour from now)
+auth_params = image_kit.helper.get_authentication_parameters(
+  token: "my-custom-token",
+  expire: Time.now.to_i + 3600
 )
+# Output: { token: "my-custom-token", expire: 1234567890, signature: "generated-signature" }
 ```
 
-**Copy File**
+These authentication parameters can be used in client-side upload forms to securely upload files without exposing your private API key.
 
-Copy file from one path to another path using the source file path and the destination path as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/copy-file)
+### Responsive image attributes
 
-```ruby
-imagekitio.copy_file(
-    source_file_path: '/path/to/file.jpg',
-    destination_path: '/folder/to/copy/into',
-    include_file_versions: true #default false
-)
-```
-
-**Move File**
-
-Move file from one folder to another folder using the source file path and destination path as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/move-file)
+Generate responsive image attributes for HTML `<img>` tags. This creates optimized `srcset` and `sizes` attributes for responsive images:
 
 ```ruby
-imagekitio.move_file(
-    source_file_path: '/path/to/file.jpg',
-    destination_path: '/folder/to/move/into/'
-)
-```
+# Width-based responsive images (generates w descriptors)
+attrs = image_kit.helper.get_responsive_image_attributes({
+  src: "/default-image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  sizes: "(min-width: 768px) 50vw, 100vw",
+  transformation: [
+    {
+      quality: 80,
+      format_: :auto
+    }
+  ]
+})
 
-**Rename File**
+puts attrs.src
+# Largest candidate URL
 
-Rename file as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/rename-file)
+puts attrs.src_set
+# URL1 640w, URL2 750w, URL3 1080w, ...
 
-```ruby
-imagekitio.rename_file(
-    file_path: '/path/to/old-file-name.jpg',
-    new_file_name: 'new-file-name.jpg',
-    purge_cache: true #optional
-)
+puts attrs.sizes
+# (min-width: 768px) 50vw, 100vw
 ```
 
-**Delete File**
-
-Delete a file as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/delete-file). The method accepts the file ID of the file that has to be deleted.
+DPR-based responsive images (generates x descriptors):
 
 ```ruby
-imagekitio.delete_file(
-    file_id: '598821f949c0a938d57563bd'
-)
-```
-**File versions**
+# When width is provided without sizes, generates 1x and 2x variants
+attrs = image_kit.helper.get_responsive_image_attributes({
+  src: "/profile.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  width: 400,
+  transformation: [
+    {
+      quality: 85
+    }
+  ]
+})
 
-Get all file versions as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/get-file-versions). The method accepts the file ID of the file.
+puts attrs.src_set
+# URL1 1x, URL2 2x
 
-```ruby
-imagekitio.file_versions(
-    file_id: '598821f949c0a938d57563bd'
-)
+puts attrs.width
+# 400
 ```
-**File version details**
 
-Get all file version detail as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/get-file-version-details). The method accepts the file ID and version ID of the file.
+Custom breakpoints for device widths:
 
 ```ruby
-imagekitio.file_version_detail(
-    file_id: '598821f949c0a938d57563bd',
-    version_id: '846321f949c0a938d57567ty'
-)
+attrs = image_kit.helper.get_responsive_image_attributes({
+  src: "/default-image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  sizes: "100vw",
+  device_breakpoints: [320, 640, 1024, 1920],
+  image_breakpoints: [16, 32, 64],
+  transformation: [
+    {
+      crop: :at_max
+    }
+  ]
+})
 ```
 
-**Delete file version**
+The returned attributes can be directly used in your HTML:
 
-Delete file version as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/delete-file-version). The method accepts the file ID and version ID of the file.
-
-```ruby
-imagekitio.delete_file_version(
-    file_id: '598821f949c0a938d57563bd',
-    version_id: '846321f949c0a938d57567ty'
-)
+```erb
+<img
+  src="<%= attrs.src %>"
+  srcset="<%= attrs.src_set %>"
+  sizes="<%= attrs.sizes %>"
+  alt="Responsive image"
+/>
 ```
 
-**Restore file version**
-
-Restore deleted file version as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/restore-file-version). The method accepts the file ID and version ID of the file.
+Generate signed responsive image URLs:
 
 ```ruby
-imagekitio.restore_file_version(
-    file_id: '598821f949c0a938d57563bd',
-    version_id: '846321f949c0a938d57567ty'
-)
+# Generate signed responsive image URLs
+attrs = image_kit.helper.get_responsive_image_attributes({
+  src: "/default-image.jpg",
+  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
+  sizes: "100vw",
+  signed: true,
+  expires_in: 3600,
+  transformation: [
+    {
+      quality: 80
+    }
+  ]
+})
 ```
 
-**Bulk File Delete by IDs**
+### Handling errors
 
-Delete a file as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/delete-files-bulk). The method accepts a list of file IDs of files that has to be
-deleted.
+When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Imagekitio::Errors::APIError` will be thrown:
 
 ```ruby
-imagekitio.delete_bulk_files(
-    file_ids: ["598821f949c0a938d57563bd", "598821f949c0a938d57543bd"]
-)
+begin
+  file = image_kit.files.upload(
+    file: File.read("/path/to/file.jpg"),
+    file_name: "file-name.jpg"
+  )
+rescue Imagekitio::Errors::APIConnectionError => e
+  puts("The server could not be reached")
+  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
+rescue Imagekitio::Errors::RateLimitError => e
+  puts("A 429 status code was received; we should back off a bit.")
+rescue Imagekitio::Errors::APIStatusError => e
+  puts("Another non-200-range status code was received")
+  puts(e.status)
+end
 ```
 
-**Purge Cache**
-Programmatically issue a clear cache request as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/purge-cache).
-Accepts the full URL of the file for which the cache has to be cleared.
+Error codes are as follows:
 
-```ruby
-imagekitio.purge_file_cache(
-    file_url: 'https://ik.imagekit.io/demo/logo-white_SJwqB4Nfe.png'
-)
-```
-**Purge Cache Status**
+| Cause            | Error Type                 |
+| ---------------- | -------------------------- |
+| HTTP 400         | `BadRequestError`          |
+| HTTP 401         | `AuthenticationError`      |
+| HTTP 403         | `PermissionDeniedError`    |
+| HTTP 404         | `NotFoundError`            |
+| HTTP 409         | `ConflictError`            |
+| HTTP 422         | `UnprocessableEntityError` |
+| HTTP 429         | `RateLimitError`           |
+| HTTP >= 500      | `InternalServerError`      |
+| Other HTTP error | `APIStatusError`           |
+| Timeout          | `APITimeoutError`          |
+| Network error    | `APIConnectionError`       |
 
-Get the purge cache request status using the request ID returned when a purge cache request gets submitted as per the
-[API documentation here](https://docs.imagekit.io/api-reference/media-api/purge-cache-status)
+### Retries
 
-```ruby
-imagekitio.purge_file_cache_status(
-    request_id: '598821f949c0a938d57543bd'
-)
-```
+Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
 
-**Add Bulk Tags**
+Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
 
-Add multiple tags on multiple files using an array of file ids and an array of tags as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/add-tags-bulk)
+You can use the `max_retries` option to configure or disable this:
 
 ```ruby
-imagekitio.add_bulk_tags(
-    file_ids: ['598821f949c0a938d57543bd', '598921f949c0a938d57543bd'],
-    tags: ['custom_tags', 'image', 'favourite']
+# Configure the default for all requests:
+image_kit = Imagekitio::Client.new(
+  max_retries: 0 # default is 2
 )
-``` 
 
-**Delete Bulk Tags**
-
-Remove multiple tags from multiple files using an array of file ids and an array of tags as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/remove-tags-bulk)
-
-```ruby
-imagekitio.delete_bulk_tags(
-    file_ids: ['598821f949c0a938d57543bd', '598921f949c0a938d57543bd'],
-    tags: ['custom_tags', 'image']
+# Or, configure per-request:
+image_kit.files.upload(
+  file: File.read("/path/to/file.jpg"),
+  file_name: "file-name.jpg",
+  request_options: {max_retries: 5}
 )
 ```
 
-**Delete Bulk AI Tags**
+### Timeouts
 
-Delete bulk ai tags as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/remove-aitags-bulk)
+By default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:
 
 ```ruby
-imagekitio.delete_bulk_ai_tags(
-    file_ids: ['598821f949c0a938d57543bd', '598921f949c0a938d57543bd'],
-    ai_tags: ['custom_ai_tags']
+# Configure the default for all requests:
+image_kit = Imagekitio::Client.new(
+  timeout: nil # default is 60
 )
-```
-
-**Create Folder**
-
-Create folder as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/create-folder)
 
-```ruby
-imagekitio.create_folder(
-    folder_name: 'new_folder',
-    parent_folder_path: 'source/folder/path' #optional
+# Or, configure per-request:
+image_kit.files.upload(
+  file: File.read("/path/to/file.jpg"),
+  file_name: "file-name.jpg",
+  request_options: {timeout: 5}
 )
 ```
 
+On timeout, `Imagekitio::Errors::APITimeoutError` is raised.
 
-**Copy Folder**
-
-Copy folder as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/copy-folder)
-
-```ruby
-imagekitio.copy_folder(
-    source_folder_path: '/folder/to/copy',
-    destination_path: '/folder/to/copy/into',
-    include_file_versions: true #default false
-)
-```
+Note that requests that time out are retried by default.
 
-**Move Folder**
+## Advanced concepts
 
-Move folder as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/move-folder)
+### BaseModel
 
-```ruby
-imagekitio.move_folder(
-    source_folder_path: '/folder/to/move',
-    destination_path: '/folder/to/move/into/'
-)
-```
+All parameter and response objects inherit from `Imagekitio::Internal::Type::BaseModel`, which provides several conveniences, including:
 
-**Delete Folder**
+1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
 
-Delete folder as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/delete-folder)
+2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
 
-```ruby
-imagekitio.delete_folder(
-    folder_path: 'folder/to/delete'
-)
-```
+3. Both instances and the classes themselves can be pretty-printed.
 
-**Bulk Job Status**
+4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
 
-Get the bulk job status as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/copy-move-folder-status)
+### Making custom or undocumented requests
 
-```ruby
-imagekitio.bulk_job_status(
-    job_id: '5e21880d5efe355febd4cccd'
-)
-```
+#### Undocumented properties
 
-**Create a custom metadata field**
+You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
 
-Create custom metadata fields as per the [API documentation here](https://docs.imagekit.io/api-reference/custom-metadata-fields-api/create-custom-metadata-field)
+Note: the `extra_` parameters of the same name overrides the documented parameters.
 
 ```ruby
-
-imagekitio.create_custom_metadata_field(
-    name: 'price',
-    label: 'price_label',
-    schema: {
-      'type': 'Number',
-      'minValue': 100,
-      'maxValue': 300
+response =
+  image_kit.files.upload(
+    file: File.read("/path/to/file.jpg"),
+    file_name: "file-name.jpg",
+    request_options: {
+      extra_query: {my_query_parameter: value},
+      extra_body: {my_body_parameter: value},
+      extra_headers: {"my-header": value}
     }
-)
-```
+  )
 
-**Get Custom Metadata Fields**
-
-Get the custom metadata fields as per the [API documentation here](https://docs.imagekit.io/api-reference/custom-metadata-fields-api/get-custom-metadata-field)
-
-```ruby
-imagekitio.get_custom_metadata_fields(
-   include_deleted: true #optional
-)
+puts(response[:my_undocumented_property])
 ```
 
-**Update Custom Metadata Fields**
-
-Update custom metadata fields as per the [API documentation here](https://docs.imagekit.io/api-reference/custom-metadata-fields-api/update-custom-metadata-field)
+#### Undocumented request params
 
-```ruby
-imagekitio.update_custom_metadata_field(
-    id: '5e21880d5efe355febd4bccd', #field_id
-    label: 'custom-price', #Either label or schema or both should be given
-    schema: nil
-)
-```
+If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the examples above.
 
-**Delete Custom Metadata Fields**
+#### Undocumented endpoints
 
-Delete custom metadata fields as per the [API documentation here](https://docs.imagekit.io/api-reference/custom-metadata-fields-api/delete-custom-metadata-field)
+To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so:
 
 ```ruby
-imagekitio.delete_custom_metadata_field(
-    id: '5e21880d5efe355febd4bccd' #field_id
+response = client.request(
+  method: :post,
+  path: '/undocumented/endpoint',
+  query: {"dog": "woof"},
+  headers: {"useful-header": "interesting-value"},
+  body: {"hello": "world"}
 )
 ```
 
-## Access request-id, other response headers and HTTP status code
-
-Each media management function returns a hash with `response`, `error`, `status_code`, `headers`, `raw_body` keys with respective values.
-
-```ruby
-upload = imagekitio.upload_file(
-    file: file,
-    file_name:  "default.jpg",
-    folder: '/test',
-    response_fields: 'tags,customCoordinates,isPrivateFile,metadata',
-    tags: %w[abc def],
-    use_unique_file_name: false,
-    is_private_file: true
-)
-puts upload[:status_code] # 200
-puts upload[:headers]
-
-#   {
-#        "access-control-allow-origin"=>["*"],
-#         "x-ik-requestid"=>["6963194e-014f-8945-b05a-bdb0e088f1bd"],
-#         "content-type"=>["application/json; charset=utf-8"],
-#         "content-length"=>["611"],
-#         "etag"=>["W/\"859-GOeZiRFGOZERjHBgRUhG0EGcODs\""],
-#         "date"=>["Wed, 29 Jun 2022 07:04:33 GMT"],
-#         "x-request-id"=>["6963194e-014f-8945-b05a-bdb0e088f1bd"],
-#         "connection"=>["close"]
-#   }
-
-
-puts upload[:raw_body]
-# "{\"fileId\":\"62bjf980rb886bd691b86760\",\"name\":\"default.jpg\",\"size\":102117,\"versionInfo\":{\"id\":\"62bjf980rb886bd691b86760\",\"name\":\"Version 1\"},\"filePath\":\"/test/default.jpg\",\"url\":\"https://ik.imagekit.io/46865sdf6sdf/test/default.jpg\",\"fileType\":\"image\",\"height\":700,\"width\":1050,\"thumbnailUrl\":\"https://ik.imagekit.io/46865sdf6sdf/tr:n-ik_ml_thumbnail/test/default.jpg\",\"tags\":[\"abc\",\"def\"],\"AITags\":null,\"isPrivateFile\":true,\"customCoordinates\":null,\"metadata\":{\"height\":700,\"width\":1050,\"size\":102117,\"format\":\"jpg\",\"hasColorProfile\":true,\"quality\":0,\"density\":72,\"hasTransparency\":false,\"exif\":{},\"pHash\":\"90249d9b1fc74367\"}}"
-```
+### Concurrency & connection pooling
 
-## Utility functions
+The `Imagekitio::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.
 
-We have included the following commonly used utility functions in this package.
+Each instance of `Imagekitio::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.
 
-**Authentication parameter generation**
+When all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.
 
-If you are looking to implement client-side file upload, you will need a `token`, `expiry` timestamp, and a valid `signature` for that upload. The SDK provides a simple method that you can use in your code to generate these authentication parameters for you.
+Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
 
-_Note: The Private API Key should never be exposed in any client-side code. You must always generate these authentication parameters on the server-side_
+## Sorbet
 
-`authentication_parameters = imagekit.get_authentication_parameters(token, expire)`
+This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
 
-Returns
+You can provide typesafe request parameters like so:
 
 ```ruby
-{
-    "token": "unique_token",
-    "expire": "valid_expiry_timestamp",
-    "signature": "generated_signature"
-}
+image_kit.files.upload(
+  file: File.read("/path/to/file.jpg"),
+  file_name: "file-name.jpg"
+)
 ```
 
-Both the `token` and `expire` parameters are optional. If not specified, the SDK uses the uuid to generate a random token and also generates a valid expiry timestamp internally. The value of the `token` and `expire` used to generate the signature is always returned in the response, no matter if they are provided as an input to this method or not.
+Or, equivalently:
 
-**Distance calculation between two pHash values**
+```ruby
+# Hashes work, but are not typesafe:
+image_kit.files.upload(
+  file: File.read("/path/to/file.jpg"),
+  file_name: "file-name.jpg"
+)
 
-Perceptual hashing allows you to construct a hash value that uniquely identifies an input image based on the contents
-of an image. [imagekit.io metadata API](https://docs.imagekit.io/api-reference/metadata-api) returns the pHash
-value of an image in the response. You can use this value to find a duplicate near the duplicate(similar) image by calculating
-the distance between the two images.
+# You can also splat a full Params class:
+params = Imagekitio::FileUploadParams.new(
+  file: File.read("/path/to/file.jpg"),
+  file_name: "file-name.jpg"
+)
+image_kit.files.upload(**params)
+```
 
+### Enums
 
-This SDK exposes the `phash_distance` function to calculate the distance between two pHash values. It accepts two pHash hexadecimal
-strings and returns a numeric value indicative of the level of difference between the two images.
+Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:
 
 ```ruby
-def calculate_distance():
-    # fetch metadata of two uploaded image files
-    ...
-    # extract pHash strings from both: say 'first_hash' and 'second_hash.'
-    ...
-    # calculate the distance between them:
-
-    distance = imagekitio.phash_distance(first_hash, second_hash)
-    return distance
+# :all
+puts(Imagekitio::AssetListParams::FileType::ALL)
+
+# Revealed type: `T.all(Imagekitio::AssetListParams::FileType, Symbol)`
+T.reveal_type(Imagekitio::AssetListParams::FileType::ALL)
 ```
 
-**Distance calculation examples**
+Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
 
 ```ruby
-imagekitio.phash_distance('f06830ca9f1e3e90', 'f06830ca9f1e3e90')
-# output: 0 (ame image)
-
-imagekitio.phash_distance('2d5ad3936d2e015b', '2d6ed293db36a4fb')
-# output: 17 (similar images)
+# Using the enum constants preserves the tagged type information:
+image_kit.assets.list(
+  file_type: Imagekitio::AssetListParams::FileType::ALL,
+  # …
+)
 
-imagekitio.phash_distance('a4a65595ac94518b', '7838873e791f8400')
-# output: 37 (dissimilar images)
+# Literal values are also permissible:
+image_kit.assets.list(
+  file_type: :all,
+  # …
+)
 ```
 
-## Sample Application
-There are three sample apps:
-
-* Rails application using Carrierwave
-* Rails application using ActiveStorage
-* Plain ruby application
-
-Please see the sample applications in [here](https://github.com/imagekit-samples/quickstart).
+## Versioning
 
-## Upgrade to 2.x
+This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
 
-If you are upgrading to 2.x from version 1.x, make the following changes  in your application:
+This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.
 
-- Remove config from environment file to initializer file as described [here](#Initialization).
-- Include `ImageKitIo::CarrierWave` in uploader class(for Carrierwave).
-- Remove `storage :imagekit_store` config from uploader.
-- Rename class `ImageKit::ImageKitClient` to `ImageKitIo::Client`
-- Rename class `ImageKitIo::ImageKitRequest` to `ImageKitIo::Request`
+## Requirements
 
-## Support
-For any feedback or to report any issues or general implementation support, please reach out to [support@imagekit.io](mailto:support@imagekit.io)
+Ruby 3.2.0 or higher.
 
-## Links
--   [Documentation](https://docs.imagekit.io)
--   [Main website](https://imagekit.io)
+## Contributing
 
-## License
-Released under the MIT license.
+See [the contributing documentation](https://github.com/imagekit-developer/imagekit-ruby/tree/master/CONTRIBUTING.md).