imagekitio 3.1.0 → 4.0.0

data/README.md

@@ -1,915 +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'
-```
-
-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
-```
-#### 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
-```
+<!-- x-release-please-start-version -->
 
-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
-
-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
+gem "imagekitio", "~> 4.0.0"
 ```
 
-Then you need to modify your model. for example- if your model name is employee, then do these changes.
+<!-- x-release-please-end -->
 
-```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
+### File uploads
 
-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:
+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.
 
 ```ruby
-class Employee < ApplicationRecord
-  has_one_attached :avatar
-end
-```
+require "pathname"
 
-Get image url:
-```ruby
-# If @employee is an object of your model that has data.
+# Use `Pathname` to stream from disk (memory efficient, supports retries):
+response = image_kit.files.upload(file: Pathname("/path/to/file"))
 
-# To get the original image url, use
-@employee.avatar.url
-```
-
-Now, let's configure active_storage as a service for the imagekitio. 
+# Or pass file contents directly
+response = image_kit.files.upload(file: File.read("/path/to/file"))
 
-First add `:active_storage` in initializer 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
-config.service = :active_storage
-``` 
-
-Then add the imagekitio service in the `storage.yml` 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
+### URL generation with transformations
 
-| 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.                                                                                                                                                                                                                                                                                                                                 |
-
-
-## 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.
 
-**Text as overlays**
+### Signed URLs for secure delivery
 
-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
 })
+# 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)
 ```
-**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
-```
-
-**Image as overlays**
 
-You can add an image over a base video or image using an image layer (l-image).
+### Chained transformations
 
-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
+    }
+  ]
 })
-```
-**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
+# Output: https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=w-400,h-300:rt-90,bl-5
 ```
 
-**Solid color blocks as overlays**
+### Using raw parameter for custom transformations
 
-You can add solid color blocks over a base video or image using an image layer (l-image).
-
-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"
+    }
+  ]
 })
+# Output: https://ik.imagekit.io/your_imagekit_id/path/to/image.jpg?tr=w-400,h-300,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
-```
-
-**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,
-    transformation: {
-        pre: 'l-text,i-Imagekit,fs-50,l-end',
-        post: [
-            {
-                type: 'transformation',
-                value: 'w-100'
-            }
-        ]
-    },
-    checks: "'request.folder' : '/'" # To run server side checks before uploading files. Notice the quotes around file.size and 1mb.
-    is_published: 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
+## Helper Methods
 
-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.
+The SDK provides several helper methods for common ImageKit operations.
 
-**List & Search Files**
+### Authentication parameters for client-side uploads
 
-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.
+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.list_files(
-    skip: 0,
-    limit: 5
-)
-```
-**Get File Details**
+require "imagekitio"
 
-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)
-
-```ruby
-imagekitio.get_file_details(
-    file_id: '598821f949c0a938d57563bd'
+image_kit = Imagekitio::Client.new(
+  private_key: ENV["IMAGEKIT_PRIVATE_KEY"]
 )
-```
 
-**Get File Metadata**
+# Generate authentication parameters with default expiry (30 minutes)
+auth_params = image_kit.helper.get_authentication_parameters
 
-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'
-)
+puts auth_params
+# Output: { token: "unique-token", expire: 1234567890, signature: "signature-hash" }
 ```
 
-**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)
+Customize the token and expiration:
 
 ```ruby
-imagekit.get_remote_file_url_metadata(
-    remote_file_url: "https://ik.imagekit.io/demo/tr:w-100/default-image.jpg"
+# 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" }
 ```
 
-**Update File Details**
+These authentication parameters can be used in client-side upload forms to securely upload files without exposing your private API key.
 
-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.
+### Responsive image attributes
 
-```ruby
-imagekitio.update_file_details(
-    file_id: '598821f949c0a938d57563bd',
-    tags: ["image_tag"],
-    custom_coordinates: "10,10,100, 100"
-)
-```
-
-
-**Update publish status**
-
-If `publish` is included in the update options, no other parameters are allowed. If any are present, an error will be returned: `Your request cannot contain any other parameters when publish is present`.
+Generate responsive image attributes for HTML `<img>` tags. This creates optimized `srcset` and `sizes` attributes for responsive images:
 
 ```ruby
-imagekitio.update_file_details(
-    file_id: '598821f949c0a938d57563bd',
-    publish:{
-      isPublished: true,
-      includeFileVersions: true
+# 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
     }
-)
-```
+  ]
+})
 
-**Copy File**
+puts attrs.src
+# Largest candidate URL
 
-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)
+puts attrs.src_set
+# URL1 640w, URL2 750w, URL3 1080w, ...
 
-```ruby
-imagekitio.copy_file(
-    source_file_path: '/path/to/file.jpg',
-    destination_path: '/folder/to/copy/into',
-    include_file_versions: true #default false
-)
+puts attrs.sizes
+# (min-width: 768px) 50vw, 100vw
 ```
 
-**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)
+DPR-based responsive images (generates x descriptors):
 
 ```ruby
-imagekitio.move_file(
-    source_file_path: '/path/to/file.jpg',
-    destination_path: '/folder/to/move/into/'
-)
-```
-
-**Rename File**
+# 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
+    }
+  ]
+})
 
-Rename file as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/rename-file)
+puts attrs.src_set
+# URL1 1x, URL2 2x
 
-```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.width
+# 400
 ```
 
-**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.
+Custom breakpoints for device widths:
 
 ```ruby
-imagekitio.delete_file(
-    file_id: '598821f949c0a938d57563bd'
-)
+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
+    }
+  ]
+})
 ```
-**File versions**
 
-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.
+The returned attributes can be directly used in your HTML:
 
-```ruby
-imagekitio.file_versions(
-    file_id: '598821f949c0a938d57563bd'
-)
+```erb
+<img
+  src="<%= attrs.src %>"
+  srcset="<%= attrs.src_set %>"
+  sizes="<%= attrs.sizes %>"
+  alt="Responsive image"
+/>
 ```
-**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.
+Generate signed responsive image URLs:
 
 ```ruby
-imagekitio.file_version_detail(
-    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
+    }
+  ]
+})
 ```
 
-**Delete file version**
+### Handling errors
 
-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.
+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_file_version(
-    file_id: '598821f949c0a938d57563bd',
-    version_id: '846321f949c0a938d57567ty'
-)
+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
 ```
 
-**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.
+Error codes are as follows:
 
-```ruby
-imagekitio.restore_file_version(
-    file_id: '598821f949c0a938d57563bd',
-    version_id: '846321f949c0a938d57567ty'
-)
-```
+| 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`       |
 
-**Bulk File Delete by IDs**
+### Retries
 
-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.
+Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
 
-```ruby
-imagekitio.delete_bulk_files(
-    file_ids: ["598821f949c0a938d57563bd", "598821f949c0a938d57543bd"]
-)
-```
+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.
 
-**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.
+You can use the `max_retries` option to configure or disable this:
 
 ```ruby
-imagekitio.purge_file_cache(
-    file_url: 'https://ik.imagekit.io/demo/logo-white_SJwqB4Nfe.png'
+# Configure the default for all requests:
+image_kit = Imagekitio::Client.new(
+  max_retries: 0 # default is 2
 )
-```
-**Purge Cache Status**
-
-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)
 
-```ruby
-imagekitio.purge_file_cache_status(
-    request_id: '598821f949c0a938d57543bd'
+# 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}
 )
 ```
 
-**Add Bulk Tags**
+### Timeouts
 
-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)
+By default, requests will time out after 60 seconds. You can use the timeout 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(
+  timeout: nil # default is 60
 )
-``` 
 
-**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: {timeout: 5}
 )
 ```
 
-**Delete Bulk AI Tags**
+On timeout, `Imagekitio::Errors::APITimeoutError` is raised.
 
-Delete bulk ai tags as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/remove-aitags-bulk)
+Note that requests that time out are retried by default.
 
-```ruby
-imagekitio.delete_bulk_ai_tags(
-    file_ids: ['598821f949c0a938d57543bd', '598921f949c0a938d57543bd'],
-    ai_tags: ['custom_ai_tags']
-)
-```
+## Advanced concepts
 
-**Create Folder**
+### BaseModel
 
-Create folder as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/create-folder)
+All parameter and response objects inherit from `Imagekitio::Internal::Type::BaseModel`, which provides several conveniences, including:
 
-```ruby
-imagekitio.create_folder(
-    folder_name: 'new_folder',
-    parent_folder_path: 'source/folder/path' #optional
-)
-```
+1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
 
+2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
 
-**Copy Folder**
+3. Both instances and the classes themselves can be pretty-printed.
 
-Copy folder as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/copy-folder)
+4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
 
-```ruby
-imagekitio.copy_folder(
-    source_folder_path: '/folder/to/copy',
-    destination_path: '/folder/to/copy/into',
-    include_file_versions: true #default false
-)
-```
+### Making custom or undocumented requests
+
+#### Undocumented properties
 
-**Move Folder**
+You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
 
-Move folder as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/move-folder)
+Note: the `extra_` parameters of the same name overrides the documented parameters.
 
 ```ruby
-imagekitio.move_folder(
-    source_folder_path: '/folder/to/move',
-    destination_path: '/folder/to/move/into/'
-)
-```
+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}
+    }
+  )
 
-**Delete Folder**
+puts(response[:my_undocumented_property])
+```
 
-Delete folder as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/delete-folder)
+#### Undocumented request params
 
-```ruby
-imagekitio.delete_folder(
-    folder_path: 'folder/to/delete'
-)
-```
+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.
 
-**Bulk Job Status**
+#### Undocumented endpoints
 
-Get the bulk job status as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/copy-move-folder-status)
+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.bulk_job_status(
-    job_id: '5e21880d5efe355febd4cccd'
+response = client.request(
+  method: :post,
+  path: '/undocumented/endpoint',
+  query: {"dog": "woof"},
+  headers: {"useful-header": "interesting-value"},
+  body: {"hello": "world"}
 )
 ```
 
-**Create a custom metadata field**
-
-Create custom metadata fields as per the [API documentation here](https://docs.imagekit.io/api-reference/custom-metadata-fields-api/create-custom-metadata-field)
+### Concurrency & connection pooling
 
-```ruby
+The `Imagekitio::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.
 
-imagekitio.create_custom_metadata_field(
-    name: 'price',
-    label: 'price_label',
-    schema: {
-      'type': 'Number',
-      'minValue': 100,
-      'maxValue': 300
-    }
-)
-```
+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.
 
-**Get Custom Metadata Fields**
+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.
 
-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)
+Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
 
-```ruby
-imagekitio.get_custom_metadata_fields(
-   include_deleted: true #optional
-)
-```
+## Sorbet
 
-**Update Custom Metadata Fields**
+This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
 
-Update custom metadata fields as per the [API documentation here](https://docs.imagekit.io/api-reference/custom-metadata-fields-api/update-custom-metadata-field)
+You can provide typesafe request parameters like so:
 
 ```ruby
-imagekitio.update_custom_metadata_field(
-    id: '5e21880d5efe355febd4bccd', #field_id
-    label: 'custom-price', #Either label or schema or both should be given
-    schema: nil
+image_kit.files.upload(
+  file: File.read("/path/to/file.jpg"),
+  file_name: "file-name.jpg"
 )
 ```
 
-**Delete Custom Metadata Fields**
-
-Delete custom metadata fields as per the [API documentation here](https://docs.imagekit.io/api-reference/custom-metadata-fields-api/delete-custom-metadata-field)
+Or, equivalently:
 
 ```ruby
-imagekitio.delete_custom_metadata_field(
-    id: '5e21880d5efe355febd4bccd' #field_id
+# Hashes work, but are not typesafe:
+image_kit.files.upload(
+  file: File.read("/path/to/file.jpg"),
+  file_name: "file-name.jpg"
 )
-```
-
-## 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
+# You can also splat a full Params class:
+params = Imagekitio::FileUploadParams.new(
+  file: File.read("/path/to/file.jpg"),
+  file_name: "file-name.jpg"
 )
-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\"}}"
+image_kit.files.upload(**params)
 ```
 
-## Utility functions
-
-We have included the following commonly used utility functions in this package.
-
-**Authentication parameter generation**
-
-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.
-
-_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_
-
-`authentication_parameters = imagekit.get_authentication_parameters(token, expire)`
+### Enums
 
-Returns
+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
-{
-    "token": "unique_token",
-    "expire": "valid_expiry_timestamp",
-    "signature": "generated_signature"
-}
-```
-
-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.
-
-**Distance calculation between two pHash values**
-
-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.
-
-
-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.
+# :all
+puts(Imagekitio::AssetListParams::FileType::ALL)
 
-```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
+# 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).