Merge pull request #81 from imagekit-developer/release-please--branches--master--changes--next

imagekitio · web-flow · commit baf338768bd9 · 2026-04-13T07:33:18.000+05:30
release: 5.4.0
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "5.3.0"
+  ".": "5.4.0"
 }
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 48
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc%2Fimagekit-63aff1629530786015da3c86131afa8a9b60545d488884b77641f1d4b89c6e9d.yml
-openapi_spec_hash: 586d357bd7e5217d240a99e0d83c6d1f
-config_hash: 47cb702ee2cb52c58d803ae39ade9b44
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc%2Fimagekit-70c42eda2bee929830b2537f758400a58dded1f1ef5686a286e2469c35a041a0.yml
+openapi_spec_hash: cdaeed824e91657b45092765cf55eb42
+config_hash: e3c2679d25f6235381dfb11962fbf3d9
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,35 @@
 # Changelog
 
+## 5.4.0 (2026-04-13)
+
+Full Changelog: [v5.3.0...v5.4.0](https://github.com/imagekit-developer/imagekit-python/compare/v5.3.0...v5.4.0)
+
+### Features
+
+* **api:** dam related webhook events ([8803680](https://github.com/imagekit-developer/imagekit-python/commit/8803680ae4bb3ea801d71520cc1354b7a1558bc6))
+* **api:** fix spec indentation ([1a2417d](https://github.com/imagekit-developer/imagekit-python/commit/1a2417d4336d1b9403eb1bc2b65187209fe833c7))
+* **api:** indentation fix ([6ad7341](https://github.com/imagekit-developer/imagekit-python/commit/6ad7341af30e43252519a3c44826be408323cbbe))
+* **api:** merge with main to bring back missing parameters ([a07e952](https://github.com/imagekit-developer/imagekit-python/commit/a07e95275e50dcd975f3ec816420eee7645ce223))
+* **api:** update webhook event names and remove DAM prefix ([bf9e082](https://github.com/imagekit-developer/imagekit-python/commit/bf9e082da50cea2f983b5bd88caca825e5039ec5))
+
+
+### Bug Fixes
+
+* **api:** extract shared schemas to prevent Go webhook union breaking changes ([9dcc234](https://github.com/imagekit-developer/imagekit-python/commit/9dcc234c1a5cd387a0989806819ced1b823277c0))
+* **api:** rename DamFile events to File for consistency ([16b113f](https://github.com/imagekit-developer/imagekit-python/commit/16b113f1e6f42b4ac1af43c4cf0567cae55f6ecf))
+* **client:** preserve hardcoded query params when merging with user params ([cbdc71f](https://github.com/imagekit-developer/imagekit-python/commit/cbdc71fee37ce26c0a05cabc55cb03b46c29b216))
+* ensure file data are only sent as 1 parameter ([aa0272a](https://github.com/imagekit-developer/imagekit-python/commit/aa0272a8fe212b1a841031d25fddaa49359ec9d9))
+
+
+### Documentation
+
+* improve examples ([bc9d18e](https://github.com/imagekit-developer/imagekit-python/commit/bc9d18e102e37ad28dfe7181cbc3b8323ed79cb2))
+
+
+### Refactors
+
+* AITags to singular AITag schema with array items pattern ([96ad1bb](https://github.com/imagekit-developer/imagekit-python/commit/96ad1bb10dbfdad7112d82f5b6cc7199429e0fe3))
+
 ## 5.3.0 (2026-04-06)
 
 Full Changelog: [v5.2.0...v5.3.0](https://github.com/imagekit-developer/imagekit-python/compare/v5.2.0...v5.3.0)
diff --git a/api.md b/api.md
@@ -265,6 +265,11 @@ Types:
 ```python
 from imagekitio.types import (
     BaseWebhookEvent,
+    FileCreateEvent,
+    FileDeleteEvent,
+    FileUpdateEvent,
+    FileVersionCreateEvent,
+    FileVersionDeleteEvent,
     UploadPostTransformErrorEvent,
     UploadPostTransformSuccessEvent,
     UploadPreTransformErrorEvent,
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "imagekitio"
-version = "5.3.0"
+version = "5.4.0"
 description = "The official Python library for the ImageKit API"
 dynamic = ["readme"]
 license = "Apache-2.0"
diff --git a/src/imagekitio/_base_client.py b/src/imagekitio/_base_client.py
@@ -540,6 +540,10 @@ def _build_request(
                 files = cast(HttpxRequestFiles, ForceMultipartDict())
 
         prepared_url = self._prepare_url(options.url)
+        # preserve hard-coded query params from the url
+        if params and prepared_url.query:
+            params = {**dict(prepared_url.params.items()), **params}
+            prepared_url = prepared_url.copy_with(raw_path=prepared_url.raw_path.split(b"?", 1)[0])
         if "_" in prepared_url.host:
             # work around https://github.com/encode/httpx/discussions/2880
             kwargs["extensions"] = {"sni_hostname": prepared_url.host.replace("_", "-")}
diff --git a/src/imagekitio/_utils/_utils.py b/src/imagekitio/_utils/_utils.py
@@ -86,8 +86,9 @@ def _extract_items(
     index += 1
     if is_dict(obj):
         try:
-            # We are at the last entry in the path so we must remove the field
-            if (len(path)) == index:
+            # Remove the field if there are no more dict keys in the path,
+            # only "<array>" traversal markers or end.
+            if all(p == "<array>" for p in path[index:]):
                 item = obj.pop(key)
             else:
                 item = obj[key]
diff --git a/src/imagekitio/_version.py b/src/imagekitio/_version.py
@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "imagekitio"
-__version__ = "5.3.0"  # x-release-please-version
+__version__ = "5.4.0"  # x-release-please-version
diff --git a/src/imagekitio/types/__init__.py b/src/imagekitio/types/__init__.py
@@ -33,6 +33,9 @@
 from .file_copy_params import FileCopyParams as FileCopyParams
 from .file_move_params import FileMoveParams as FileMoveParams
 from .asset_list_params import AssetListParams as AssetListParams
+from .file_create_event import FileCreateEvent as FileCreateEvent
+from .file_delete_event import FileDeleteEvent as FileDeleteEvent
+from .file_update_event import FileUpdateEvent as FileUpdateEvent
 from .base_webhook_event import BaseWebhookEvent as BaseWebhookEvent
 from .file_copy_response import FileCopyResponse as FileCopyResponse
 from .file_move_response import FileMoveResponse as FileMoveResponse
@@ -56,6 +59,8 @@
 from .folder_create_response import FolderCreateResponse as FolderCreateResponse
 from .folder_delete_response import FolderDeleteResponse as FolderDeleteResponse
 from .folder_rename_response import FolderRenameResponse as FolderRenameResponse
+from .file_version_create_event import FileVersionCreateEvent as FileVersionCreateEvent
+from .file_version_delete_event import FileVersionDeleteEvent as FileVersionDeleteEvent
 from .update_file_request_param import UpdateFileRequestParam as UpdateFileRequestParam
 from .unsafe_unwrap_webhook_event import UnsafeUnwrapWebhookEvent as UnsafeUnwrapWebhookEvent
 from .saved_extension_create_params import SavedExtensionCreateParams as SavedExtensionCreateParams
diff --git a/src/imagekitio/types/beta/v2/file_upload_response.py b/src/imagekitio/types/beta/v2/file_upload_response.py
@@ -12,17 +12,21 @@
 
 
 class AITag(BaseModel):
+    """AI-generated tag associated with an image.
+
+    These tags can be added using the `google-auto-tagging` or `aws-auto-tagging` extensions.
+    """
+
     confidence: Optional[float] = None
     """Confidence score of the tag."""
 
     name: Optional[str] = None
     """Name of the tag."""
 
     source: Optional[str] = None
-    """Array of `AITags` associated with the image.
+    """Source of the tag.
 
-    If no `AITags` are set, it will be null. These tags can be added using the
-    `google-auto-tagging` or `aws-auto-tagging` extensions.
+    Possible values are `google-auto-tagging` and `aws-auto-tagging`.
     """
 
 
diff --git a/src/imagekitio/types/file.py b/src/imagekitio/types/file.py
@@ -12,6 +12,11 @@
 
 
 class AITag(BaseModel):
+    """AI-generated tag associated with an image.
+
+    These tags can be added using the `google-auto-tagging` or `aws-auto-tagging` extensions.
+    """
+
     confidence: Optional[float] = None
     """Confidence score of the tag."""
 
@@ -80,7 +85,7 @@ class SelectedFieldsSchema(BaseModel):
 
 
 class VersionInfo(BaseModel):
-    """An object with details of the file version."""
+    """An object containing the file or file version's `id` (versionId) and `name`."""
 
     id: Optional[str] = None
     """Unique identifier of the file version."""
@@ -93,7 +98,10 @@ class File(BaseModel):
     """Object containing details of a file or file version."""
 
     ai_tags: Optional[List[AITag]] = FieldInfo(alias="AITags", default=None)
-    """An array of tags assigned to the file by auto tagging."""
+    """Array of AI-generated tags associated with the image.
+
+    If no AITags are set, it will be null.
+    """
 
     audio_codec: Optional[str] = FieldInfo(alias="audioCodec", default=None)
     """The audio codec used in the video (only for video/audio)."""
diff --git a/src/imagekitio/types/file_create_event.py b/src/imagekitio/types/file_create_event.py
@@ -0,0 +1,22 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from datetime import datetime
+from typing_extensions import Literal
+
+from .file import File
+from .base_webhook_event import BaseWebhookEvent
+
+__all__ = ["FileCreateEvent"]
+
+
+class FileCreateEvent(BaseWebhookEvent):
+    """Triggered when a file is created."""
+
+    created_at: datetime
+    """Timestamp of when the event occurred in ISO8601 format."""
+
+    data: File
+    """Object containing details of a file or file version."""
+
+    type: Literal["file.created"]  # type: ignore
+    """Type of the webhook event."""
diff --git a/src/imagekitio/types/file_delete_event.py b/src/imagekitio/types/file_delete_event.py
@@ -0,0 +1,28 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from datetime import datetime
+from typing_extensions import Literal
+
+from pydantic import Field as FieldInfo
+
+from .._models import BaseModel
+from .base_webhook_event import BaseWebhookEvent
+
+__all__ = ["FileDeleteEvent", "FileDeleteEventData"]
+
+
+class FileDeleteEventData(BaseModel):
+    file_id: str = FieldInfo(alias="fileId")
+    """The unique `fileId` of the deleted file."""
+
+
+class FileDeleteEvent(BaseWebhookEvent):
+    """Triggered when a file is deleted."""
+
+    created_at: datetime
+    """Timestamp of when the event occurred in ISO8601 format."""
+
+    data: FileDeleteEventData
+
+    type: Literal["file.deleted"]  # type: ignore
+    """Type of the webhook event."""
diff --git a/src/imagekitio/types/file_update_event.py b/src/imagekitio/types/file_update_event.py
@@ -0,0 +1,22 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from datetime import datetime
+from typing_extensions import Literal
+
+from .file import File
+from .base_webhook_event import BaseWebhookEvent
+
+__all__ = ["FileUpdateEvent"]
+
+
+class FileUpdateEvent(BaseWebhookEvent):
+    """Triggered when a file is updated."""
+
+    created_at: datetime
+    """Timestamp of when the event occurred in ISO8601 format."""
+
+    data: File
+    """Object containing details of a file or file version."""
+
+    type: Literal["file.updated"]  # type: ignore
+    """Type of the webhook event."""
diff --git a/src/imagekitio/types/file_upload_response.py b/src/imagekitio/types/file_upload_response.py
@@ -12,17 +12,21 @@
 
 
 class AITag(BaseModel):
+    """AI-generated tag associated with an image.
+
+    These tags can be added using the `google-auto-tagging` or `aws-auto-tagging` extensions.
+    """
+
     confidence: Optional[float] = None
     """Confidence score of the tag."""
 
     name: Optional[str] = None
     """Name of the tag."""
 
     source: Optional[str] = None
-    """Array of `AITags` associated with the image.
+    """Source of the tag.
 
-    If no `AITags` are set, it will be null. These tags can be added using the
-    `google-auto-tagging` or `aws-auto-tagging` extensions.
+    Possible values are `google-auto-tagging` and `aws-auto-tagging`.
     """
 
 
diff --git a/src/imagekitio/types/file_version_create_event.py b/src/imagekitio/types/file_version_create_event.py
@@ -0,0 +1,22 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from datetime import datetime
+from typing_extensions import Literal
+
+from .file import File
+from .base_webhook_event import BaseWebhookEvent
+
+__all__ = ["FileVersionCreateEvent"]
+
+
+class FileVersionCreateEvent(BaseWebhookEvent):
+    """Triggered when a file version is created."""
+
+    created_at: datetime
+    """Timestamp of when the event occurred in ISO8601 format."""
+
+    data: File
+    """Object containing details of a file or file version."""
+
+    type: Literal["file-version.created"]  # type: ignore
+    """Type of the webhook event."""
diff --git a/src/imagekitio/types/file_version_delete_event.py b/src/imagekitio/types/file_version_delete_event.py
@@ -0,0 +1,31 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from datetime import datetime
+from typing_extensions import Literal
+
+from pydantic import Field as FieldInfo
+
+from .._models import BaseModel
+from .base_webhook_event import BaseWebhookEvent
+
+__all__ = ["FileVersionDeleteEvent", "FileVersionDeleteEventData"]
+
+
+class FileVersionDeleteEventData(BaseModel):
+    file_id: str = FieldInfo(alias="fileId")
+    """The unique `fileId` of the deleted file."""
+
+    version_id: str = FieldInfo(alias="versionId")
+    """The unique `versionId` of the deleted file version."""
+
+
+class FileVersionDeleteEvent(BaseWebhookEvent):
+    """Triggered when a file version is deleted."""
+
+    created_at: datetime
+    """Timestamp of when the event occurred in ISO8601 format."""
+
+    data: FileVersionDeleteEventData
+
+    type: Literal["file-version.deleted"]  # type: ignore
+    """Type of the webhook event."""
diff --git a/src/imagekitio/types/unsafe_unwrap_webhook_event.py b/src/imagekitio/types/unsafe_unwrap_webhook_event.py
@@ -4,6 +4,11 @@
 from typing_extensions import Annotated, TypeAlias
 
 from .._utils import PropertyInfo
+from .file_create_event import FileCreateEvent
+from .file_delete_event import FileDeleteEvent
+from .file_update_event import FileUpdateEvent
+from .file_version_create_event import FileVersionCreateEvent
+from .file_version_delete_event import FileVersionDeleteEvent
 from .upload_pre_transform_error_event import UploadPreTransformErrorEvent
 from .video_transformation_error_event import VideoTransformationErrorEvent
 from .video_transformation_ready_event import VideoTransformationReadyEvent
@@ -23,6 +28,11 @@
         UploadPreTransformErrorEvent,
         UploadPostTransformSuccessEvent,
         UploadPostTransformErrorEvent,
+        FileCreateEvent,
+        FileUpdateEvent,
+        FileDeleteEvent,
+        FileVersionCreateEvent,
+        FileVersionDeleteEvent,
     ],
     PropertyInfo(discriminator="type"),
 ]
diff --git a/src/imagekitio/types/unwrap_webhook_event.py b/src/imagekitio/types/unwrap_webhook_event.py
@@ -4,6 +4,11 @@
 from typing_extensions import Annotated, TypeAlias
 
 from .._utils import PropertyInfo
+from .file_create_event import FileCreateEvent
+from .file_delete_event import FileDeleteEvent
+from .file_update_event import FileUpdateEvent
+from .file_version_create_event import FileVersionCreateEvent
+from .file_version_delete_event import FileVersionDeleteEvent
 from .upload_pre_transform_error_event import UploadPreTransformErrorEvent
 from .video_transformation_error_event import VideoTransformationErrorEvent
 from .video_transformation_ready_event import VideoTransformationReadyEvent
@@ -23,6 +28,11 @@
         UploadPreTransformErrorEvent,
         UploadPostTransformSuccessEvent,
         UploadPostTransformErrorEvent,
+        FileCreateEvent,
+        FileUpdateEvent,
+        FileDeleteEvent,
+        FileVersionCreateEvent,
+        FileVersionDeleteEvent,
     ],
     PropertyInfo(discriminator="type"),
 ]
diff --git a/src/imagekitio/types/upload_pre_transform_success_event.py b/src/imagekitio/types/upload_pre_transform_success_event.py
diff --git a/tests/api_resources/test_custom_metadata_fields.py b/tests/api_resources/test_custom_metadata_fields.py
diff --git a/tests/api_resources/test_dummy.py b/tests/api_resources/test_dummy.py
diff --git a/tests/api_resources/test_files.py b/tests/api_resources/test_files.py
diff --git a/tests/test_client.py b/tests/test_client.py
diff --git a/tests/test_extract_files.py b/tests/test_extract_files.py

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`{`
`2`		`- ".": "5.3.0"`
	`2`	`+ ".": "5.4.0"`
`3`	`3`	`}`