imagekitio 3.0.0 → 4.0.0

data/rbi/imagekitio/resources/beta/v2/files.rbi

@@ -0,0 +1,193 @@
+# typed: strong
+
+module Imagekitio
+  module Resources
+    class Beta
+      class V2
+        class Files
+          # The V2 API enhances security by verifying the entire payload using JWT. This API
+          # is in beta.
+          #
+          # ImageKit.io allows you to upload files directly from both the server and client
+          # sides. For server-side uploads, private API key authentication is used. For
+          # client-side uploads, generate a one-time `token` from your secure backend using
+          # private API.
+          # [Learn more](/docs/api-reference/upload-file/upload-file-v2#how-to-implement-secure-client-side-file-upload)
+          # about how to implement secure client-side file upload.
+          #
+          # **File size limit** \
+          # On the free plan, the maximum upload file sizes are 20MB for images, audio, and raw
+          # files, and 100MB for videos. On the paid plan, these limits increase to 40MB for
+          # images, audio, and raw files, and 2GB for videos. These limits can be further increased
+          # with higher-tier plans.
+          #
+          # **Version limit** \
+          # A file can have a maximum of 100 versions.
+          #
+          # **Demo applications**
+          #
+          # - A full-fledged
+          #   [upload widget using Uppy](https://github.com/imagekit-samples/uppy-uploader),
+          #   supporting file selections from local storage, URL, Dropbox, Google Drive,
+          #   Instagram, and more.
+          # - [Quick start guides](/docs/quick-start-guides) for various frameworks and
+          #   technologies.
+          sig do
+            params(
+              file: Imagekitio::Internal::FileInput,
+              file_name: String,
+              token: String,
+              checks: String,
+              custom_coordinates: String,
+              custom_metadata: T::Hash[Symbol, T.anything],
+              description: String,
+              extensions:
+                T::Array[
+                  T.any(
+                    Imagekitio::ExtensionItem::RemoveBg::OrHash,
+                    Imagekitio::ExtensionItem::AIAutoDescription::OrHash,
+                    Imagekitio::ExtensionItem::AutoTaggingExtension::OrHash
+                  )
+                ],
+              folder: String,
+              is_private_file: T::Boolean,
+              is_published: T::Boolean,
+              overwrite_ai_tags: T::Boolean,
+              overwrite_custom_metadata: T::Boolean,
+              overwrite_file: T::Boolean,
+              overwrite_tags: T::Boolean,
+              response_fields:
+                T::Array[
+                  Imagekitio::Beta::V2::FileUploadParams::ResponseField::OrSymbol
+                ],
+              tags: T::Array[String],
+              transformation:
+                Imagekitio::Beta::V2::FileUploadParams::Transformation::OrHash,
+              use_unique_file_name: T::Boolean,
+              webhook_url: String,
+              request_options: Imagekitio::RequestOptions::OrHash
+            ).returns(Imagekitio::Models::Beta::V2::FileUploadResponse)
+          end
+          def upload(
+            # The API accepts any of the following:
+            #
+            # - **Binary data** – send the raw bytes as `multipart/form-data`.
+            # - **HTTP / HTTPS URL** – a publicly reachable URL that ImageKit’s servers can
+            #   fetch.
+            # - **Base64 string** – the file encoded as a Base64 data URI or plain Base64.
+            #
+            # When supplying a URL, the server must receive the response headers within 8
+            # seconds; otherwise the request fails with 400 Bad Request.
+            file:,
+            # The name with which the file has to be uploaded.
+            file_name:,
+            # This is the client-generated JSON Web Token (JWT). The ImageKit.io server uses
+            # it to authenticate and check that the upload request parameters have not been
+            # tampered with after the token has been generated. Learn how to create the token
+            # on the page below. This field is only required for authentication when uploading
+            # a file from the client side.
+            #
+            # **Note**: Sending a JWT that has been used in the past will result in a
+            # validation error. Even if your previous request resulted in an error, you should
+            # always send a new token.
+            #
+            # **⚠️Warning**: JWT must be generated on the server-side because it is generated
+            # using your account's private API key. This field is required for authentication
+            # when uploading a file from the client-side.
+            token: nil,
+            # Server-side checks to run on the asset. Read more about
+            # [Upload API checks](/docs/api-reference/upload-file/upload-file-v2#upload-api-checks).
+            checks: nil,
+            # Define an important area in the image. This is only relevant for image type
+            # files.
+            #
+            # - To be passed as a string with the x and y coordinates of the top-left corner,
+            #   and width and height of the area of interest in the format `x,y,width,height`.
+            #   For example - `10,10,100,100`
+            # - Can be used with fo-customtransformation.
+            # - If this field is not specified and the file is overwritten, then
+            #   customCoordinates will be removed.
+            custom_coordinates: nil,
+            # JSON key-value pairs to associate with the asset. Create the custom metadata
+            # fields before setting these values.
+            custom_metadata: nil,
+            # Optional text to describe the contents of the file.
+            description: nil,
+            # Array of extensions to be applied to the asset. Each extension can be configured
+            # with specific parameters based on the extension type.
+            extensions: nil,
+            # The folder path in which the image has to be uploaded. If the folder(s) didn't
+            # exist before, a new folder(s) is created. Using multiple `/` creates a nested
+            # folder.
+            folder: nil,
+            # Whether to mark the file as private or not.
+            #
+            # If `true`, the file is marked as private and is accessible only using named
+            # transformation or signed URL.
+            is_private_file: nil,
+            # Whether to upload file as published or not.
+            #
+            # If `false`, the file is marked as unpublished, which restricts access to the
+            # file only via the media library. Files in draft or unpublished state can only be
+            # publicly accessed after being published.
+            #
+            # The option to upload in draft state is only available in custom enterprise
+            # pricing plans.
+            is_published: nil,
+            # If set to `true` and a file already exists at the exact location, its AITags
+            # will be removed. Set `overwriteAITags` to `false` to preserve AITags.
+            overwrite_ai_tags: nil,
+            # If the request does not have `customMetadata`, and a file already exists at the
+            # exact location, existing customMetadata will be removed.
+            overwrite_custom_metadata: nil,
+            # If `false` and `useUniqueFileName` is also `false`, and a file already exists at
+            # the exact location, upload API will return an error immediately.
+            overwrite_file: nil,
+            # If the request does not have `tags`, and a file already exists at the exact
+            # location, existing tags will be removed.
+            overwrite_tags: nil,
+            # Array of response field keys to include in the API response body.
+            response_fields: nil,
+            # Set the tags while uploading the file. Provide an array of tag strings (e.g.
+            # `["tag1", "tag2", "tag3"]`). The combined length of all tag characters must not
+            # exceed 500, and the `%` character is not allowed. If this field is not specified
+            # and the file is overwritten, the existing tags will be removed.
+            tags: nil,
+            # Configure pre-processing (`pre`) and post-processing (`post`) transformations.
+            #
+            # - `pre` — applied before the file is uploaded to the Media Library.
+            #   Useful for reducing file size or applying basic optimizations upfront (e.g.,
+            #   resize, compress).
+            #
+            # - `post` — applied immediately after upload.
+            #   Ideal for generating transformed versions (like video encodes or thumbnails)
+            #   in advance, so they're ready for delivery without delay.
+            #
+            # You can mix and match any combination of post-processing types.
+            transformation: nil,
+            # Whether to use a unique filename for this file or not.
+            #
+            # If `true`, ImageKit.io will add a unique suffix to the filename parameter to get
+            # a unique filename.
+            #
+            # If `false`, then the image is uploaded with the provided filename parameter, and
+            # any existing file with the same name is replaced.
+            use_unique_file_name: nil,
+            # The final status of extensions after they have completed execution will be
+            # delivered to this endpoint as a POST request.
+            # [Learn more](/docs/api-reference/digital-asset-management-dam/managing-assets/update-file-details#webhook-payload-structure)
+            # about the webhook payload structure.
+            webhook_url: nil,
+            request_options: {}
+          )
+          end
+
+          # @api private
+          sig { params(client: Imagekitio::Client).returns(T.attached_class) }
+          def self.new(client:)
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/imagekitio/resources/beta/v2.rbi

@@ -0,0 +1,17 @@
+# typed: strong
+
+module Imagekitio
+  module Resources
+    class Beta
+      class V2
+        sig { returns(Imagekitio::Resources::Beta::V2::Files) }
+        attr_reader :files
+
+        # @api private
+        sig { params(client: Imagekitio::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/imagekitio/resources/beta.rbi

@@ -0,0 +1,15 @@
+# typed: strong
+
+module Imagekitio
+  module Resources
+    class Beta
+      sig { returns(Imagekitio::Resources::Beta::V2) }
+      attr_reader :v2
+
+      # @api private
+      sig { params(client: Imagekitio::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/imagekitio/resources/cache/invalidation.rbi

@@ -0,0 +1,44 @@
+# typed: strong
+
+module Imagekitio
+  module Resources
+    class Cache
+      class Invalidation
+        # This API will purge CDN cache and ImageKit.io's internal cache for a file. Note:
+        # Purge cache is an asynchronous process and it may take some time to reflect the
+        # changes.
+        sig do
+          params(
+            url: String,
+            request_options: Imagekitio::RequestOptions::OrHash
+          ).returns(Imagekitio::Models::Cache::InvalidationCreateResponse)
+        end
+        def create(
+          # The full URL of the file to be purged.
+          url:,
+          request_options: {}
+        )
+        end
+
+        # This API returns the status of a purge cache request.
+        sig do
+          params(
+            request_id: String,
+            request_options: Imagekitio::RequestOptions::OrHash
+          ).returns(Imagekitio::Models::Cache::InvalidationGetResponse)
+        end
+        def get(
+          # Should be a valid requestId.
+          request_id,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Imagekitio::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/imagekitio/resources/cache.rbi

@@ -0,0 +1,15 @@
+# typed: strong
+
+module Imagekitio
+  module Resources
+    class Cache
+      sig { returns(Imagekitio::Resources::Cache::Invalidation) }
+      attr_reader :invalidation
+
+      # @api private
+      sig { params(client: Imagekitio::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/imagekitio/resources/custom_metadata_fields.rbi

@@ -0,0 +1,106 @@
+# typed: strong
+
+module Imagekitio
+  module Resources
+    class CustomMetadataFields
+      # This API creates a new custom metadata field. Once a custom metadata field is
+      # created either through this API or using the dashboard UI, its value can be set
+      # on the assets. The value of a field for an asset can be set using the media
+      # library UI or programmatically through upload or update assets API.
+      sig do
+        params(
+          label: String,
+          name: String,
+          schema: Imagekitio::CustomMetadataFieldCreateParams::Schema::OrHash,
+          request_options: Imagekitio::RequestOptions::OrHash
+        ).returns(Imagekitio::CustomMetadataField)
+      end
+      def create(
+        # Human readable name of the custom metadata field. This should be unique across
+        # all non deleted custom metadata fields. This name is displayed as form field
+        # label to the users while setting field value on an asset in the media library
+        # UI.
+        label:,
+        # API name of the custom metadata field. This should be unique across all
+        # (including deleted) custom metadata fields.
+        name:,
+        schema:,
+        request_options: {}
+      )
+      end
+
+      # This API updates the label or schema of an existing custom metadata field.
+      sig do
+        params(
+          id: String,
+          label: String,
+          schema: Imagekitio::CustomMetadataFieldUpdateParams::Schema::OrHash,
+          request_options: Imagekitio::RequestOptions::OrHash
+        ).returns(Imagekitio::CustomMetadataField)
+      end
+      def update(
+        # Should be a valid custom metadata field id.
+        id,
+        # Human readable name of the custom metadata field. This should be unique across
+        # all non deleted custom metadata fields. This name is displayed as form field
+        # label to the users while setting field value on an asset in the media library
+        # UI. This parameter is required if `schema` is not provided.
+        label: nil,
+        # An object that describes the rules for the custom metadata key. This parameter
+        # is required if `label` is not provided. Note: `type` cannot be updated and will
+        # be ignored if sent with the `schema`. The schema will be validated as per the
+        # existing `type`.
+        schema: nil,
+        request_options: {}
+      )
+      end
+
+      # This API returns the array of created custom metadata field objects. By default
+      # the API returns only non deleted field objects, but you can include deleted
+      # fields in the API response.
+      #
+      # You can also filter results by a specific folder path to retrieve custom
+      # metadata fields applicable at that location. This path-specific filtering is
+      # useful when using the **Path policy** feature to determine which custom metadata
+      # fields are selected for a given path.
+      sig do
+        params(
+          folder_path: String,
+          include_deleted: T::Boolean,
+          request_options: Imagekitio::RequestOptions::OrHash
+        ).returns(T::Array[Imagekitio::CustomMetadataField])
+      end
+      def list(
+        # The folder path (e.g., `/path/to/folder`) for which to retrieve applicable
+        # custom metadata fields. Useful for determining path-specific field selections
+        # when the [Path policy](https://imagekit.io/docs/dam/path-policy) feature is in
+        # use.
+        folder_path: nil,
+        # Set it to `true` to include deleted field objects in the API response.
+        include_deleted: nil,
+        request_options: {}
+      )
+      end
+
+      # This API deletes a custom metadata field. Even after deleting a custom metadata
+      # field, you cannot create any new custom metadata field with the same name.
+      sig do
+        params(
+          id: String,
+          request_options: Imagekitio::RequestOptions::OrHash
+        ).returns(Imagekitio::Models::CustomMetadataFieldDeleteResponse)
+      end
+      def delete(
+        # Should be a valid custom metadata field id.
+        id,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Imagekitio::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/imagekitio/resources/files/bulk.rbi

@@ -0,0 +1,88 @@
+# typed: strong
+
+module Imagekitio
+  module Resources
+    class Files
+      class Bulk
+        # This API deletes multiple files and all their file versions permanently.
+        #
+        # Note: If a file or specific transformation has been requested in the past, then
+        # the response is cached. Deleting a file does not purge the cache. You can purge
+        # the cache using purge cache API.
+        #
+        # A maximum of 100 files can be deleted at a time.
+        sig do
+          params(
+            file_ids: T::Array[String],
+            request_options: Imagekitio::RequestOptions::OrHash
+          ).returns(Imagekitio::Models::Files::BulkDeleteResponse)
+        end
+        def delete(
+          # An array of fileIds which you want to delete.
+          file_ids:,
+          request_options: {}
+        )
+        end
+
+        # This API adds tags to multiple files in bulk. A maximum of 50 files can be
+        # specified at a time.
+        sig do
+          params(
+            file_ids: T::Array[String],
+            tags: T::Array[String],
+            request_options: Imagekitio::RequestOptions::OrHash
+          ).returns(Imagekitio::Models::Files::BulkAddTagsResponse)
+        end
+        def add_tags(
+          # An array of fileIds to which you want to add tags.
+          file_ids:,
+          # An array of tags that you want to add to the files.
+          tags:,
+          request_options: {}
+        )
+        end
+
+        # This API removes AITags from multiple files in bulk. A maximum of 50 files can
+        # be specified at a time.
+        sig do
+          params(
+            ai_tags: T::Array[String],
+            file_ids: T::Array[String],
+            request_options: Imagekitio::RequestOptions::OrHash
+          ).returns(Imagekitio::Models::Files::BulkRemoveAITagsResponse)
+        end
+        def remove_ai_tags(
+          # An array of AITags that you want to remove from the files.
+          ai_tags:,
+          # An array of fileIds from which you want to remove AITags.
+          file_ids:,
+          request_options: {}
+        )
+        end
+
+        # This API removes tags from multiple files in bulk. A maximum of 50 files can be
+        # specified at a time.
+        sig do
+          params(
+            file_ids: T::Array[String],
+            tags: T::Array[String],
+            request_options: Imagekitio::RequestOptions::OrHash
+          ).returns(Imagekitio::Models::Files::BulkRemoveTagsResponse)
+        end
+        def remove_tags(
+          # An array of fileIds from which you want to remove tags.
+          file_ids:,
+          # An array of tags that you want to remove from the files.
+          tags:,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Imagekitio::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/imagekitio/resources/files/metadata.rbi

@@ -0,0 +1,49 @@
+# typed: strong
+
+module Imagekitio
+  module Resources
+    class Files
+      class Metadata
+        # You can programmatically get image EXIF, pHash, and other metadata for uploaded
+        # files in the ImageKit.io media library using this API.
+        #
+        # You can also get the metadata in upload API response by passing `metadata` in
+        # `responseFields` parameter.
+        sig do
+          params(
+            file_id: String,
+            request_options: Imagekitio::RequestOptions::OrHash
+          ).returns(Imagekitio::Metadata)
+        end
+        def get(
+          # The unique `fileId` of the uploaded file. `fileId` is returned in the list and
+          # search assets API and upload API.
+          file_id,
+          request_options: {}
+        )
+        end
+
+        # Get image EXIF, pHash, and other metadata from ImageKit.io powered remote URL
+        # using this API.
+        sig do
+          params(
+            url: String,
+            request_options: Imagekitio::RequestOptions::OrHash
+          ).returns(Imagekitio::Metadata)
+        end
+        def get_from_url(
+          # Should be a valid file URL. It should be accessible using your ImageKit.io
+          # account.
+          url:,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Imagekitio::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/imagekitio/resources/files/versions.rbi

@@ -0,0 +1,89 @@
+# typed: strong
+
+module Imagekitio
+  module Resources
+    class Files
+      class Versions
+        # This API returns details of all versions of a file.
+        sig do
+          params(
+            file_id: String,
+            request_options: Imagekitio::RequestOptions::OrHash
+          ).returns(T::Array[Imagekitio::File])
+        end
+        def list(
+          # The unique `fileId` of the uploaded file. `fileId` is returned in list and
+          # search assets API and upload API.
+          file_id,
+          request_options: {}
+        )
+        end
+
+        # This API deletes a non-current file version permanently. The API returns an
+        # empty response.
+        #
+        # Note: If you want to delete all versions of a file, use the delete file API.
+        sig do
+          params(
+            version_id: String,
+            file_id: String,
+            request_options: Imagekitio::RequestOptions::OrHash
+          ).returns(Imagekitio::Models::Files::VersionDeleteResponse)
+        end
+        def delete(
+          # The unique `versionId` of the uploaded file. `versionId` is returned in list and
+          # search assets API and upload API.
+          version_id,
+          # The unique `fileId` of the uploaded file. `fileId` is returned in list and
+          # search assets API and upload API.
+          file_id:,
+          request_options: {}
+        )
+        end
+
+        # This API returns an object with details or attributes of a file version.
+        sig do
+          params(
+            version_id: String,
+            file_id: String,
+            request_options: Imagekitio::RequestOptions::OrHash
+          ).returns(Imagekitio::File)
+        end
+        def get(
+          # The unique `versionId` of the uploaded file. `versionId` is returned in list and
+          # search assets API and upload API.
+          version_id,
+          # The unique `fileId` of the uploaded file. `fileId` is returned in list and
+          # search assets API and upload API.
+          file_id:,
+          request_options: {}
+        )
+        end
+
+        # This API restores a file version as the current file version.
+        sig do
+          params(
+            version_id: String,
+            file_id: String,
+            request_options: Imagekitio::RequestOptions::OrHash
+          ).returns(Imagekitio::File)
+        end
+        def restore(
+          # The unique `versionId` of the uploaded file. `versionId` is returned in list and
+          # search assets API and upload API.
+          version_id,
+          # The unique `fileId` of the uploaded file. `fileId` is returned in list and
+          # search assets API and upload API.
+          file_id:,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Imagekitio::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end