feat(api): manual updates

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 42
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc%2Fimagekit-667f7f4988b44bc587d6eb9960ff5c8326e9f7e9b072f3f724f9f54166eff8b1.yml
 openapi_spec_hash: f2081864a4abee0480e5ff991b4c936a
-config_hash: 4e73c7e12a531edcd1366dab7eccc360
+config_hash: 08e12746cdca1c59c897cf2e50893c3c

api.md

@@ -208,6 +208,7 @@ Methods:
 
 Types:
 
+- <code><a href="./src/resources/webhooks.ts">BaseWebhookEvent</a></code>
 - <code><a href="./src/resources/webhooks.ts">UploadPostTransformErrorEvent</a></code>
 - <code><a href="./src/resources/webhooks.ts">UploadPostTransformSuccessEvent</a></code>
 - <code><a href="./src/resources/webhooks.ts">UploadPreTransformErrorEvent</a></code>

src/client.ts

@@ -27,6 +27,7 @@ import {
   CustomMetadataFields,
 } from './resources/custom-metadata-fields';
 import {
+  BaseWebhookEvent,
   UnsafeUnwrapWebhookEvent,
   UnwrapWebhookEvent,
   UploadPostTransformErrorEvent,
@@ -894,6 +895,7 @@ export declare namespace ImageKit {
 
   export {
     Webhooks as Webhooks,
+    type BaseWebhookEvent as BaseWebhookEvent,
     type UploadPostTransformErrorEvent as UploadPostTransformErrorEvent,
     type UploadPostTransformSuccessEvent as UploadPostTransformSuccessEvent,
     type UploadPreTransformErrorEvent as UploadPreTransformErrorEvent,

src/resources/index.ts

@@ -45,6 +45,7 @@ export {
 } from './folders/folders';
 export {
   Webhooks,
+  type BaseWebhookEvent,
   type UploadPostTransformErrorEvent,
   type UploadPostTransformSuccessEvent,
   type UploadPreTransformErrorEvent,

src/resources/webhooks.ts

@@ -23,12 +23,23 @@ export class Webhooks extends APIResource {
   }
 }
 
-export interface UploadPostTransformErrorEvent {
+export interface BaseWebhookEvent {
   /**
    * Unique identifier for the event.
    */
   id: string;
 
+  /**
+   * The type of webhook event.
+   */
+  type: string;
+}
+
+/**
+ * Triggered when a post-transformation fails. The original file remains available,
+ * but the requested transformation could not be generated.
+ */
+export interface UploadPostTransformErrorEvent extends BaseWebhookEvent {
   /**
    * Timestamp of when the event occurred in ISO8601 format.
    */
@@ -110,12 +121,12 @@ export namespace UploadPostTransformErrorEvent {
   }
 }
 
-export interface UploadPostTransformSuccessEvent {
-  /**
-   * Unique identifier for the event.
-   */
-  id: string;
-
+/**
+ * Triggered when a post-transformation completes successfully. The transformed
+ * version of the file is now ready and can be accessed via the provided URL. Note
+ * that each post-transformation generates a separate webhook event.
+ */
+export interface UploadPostTransformSuccessEvent extends BaseWebhookEvent {
   /**
    * Timestamp of when the event occurred in ISO8601 format.
    */
@@ -175,12 +186,11 @@ export namespace UploadPostTransformSuccessEvent {
   }
 }
 
-export interface UploadPreTransformErrorEvent {
-  /**
-   * Unique identifier for the event.
-   */
-  id: string;
-
+/**
+ * Triggered when a pre-transformation fails. The file upload may have been
+ * accepted, but the requested transformation could not be applied.
+ */
+export interface UploadPreTransformErrorEvent extends BaseWebhookEvent {
   /**
    * Timestamp of when the event occurred in ISO8601 format.
    */
@@ -236,12 +246,12 @@ export namespace UploadPreTransformErrorEvent {
   }
 }
 
-export interface UploadPreTransformSuccessEvent {
-  /**
-   * Unique identifier for the event.
-   */
-  id: string;
-
+/**
+ * Triggered when a pre-transformation completes successfully. The file has been
+ * processed with the requested transformation and is now available in the Media
+ * Library.
+ */
+export interface UploadPreTransformSuccessEvent extends BaseWebhookEvent {
   /**
    * Timestamp of when the event occurred in ISO8601 format.
    */
@@ -480,12 +490,12 @@ export namespace UploadPreTransformSuccessEvent {
   }
 }
 
-export interface VideoTransformationAcceptedEvent {
-  /**
-   * Unique identifier for the event.
-   */
-  id: string;
-
+/**
+ * Triggered when a new video transformation request is accepted for processing.
+ * This event confirms that ImageKit has received and queued your transformation
+ * request. Use this for debugging and tracking transformation lifecycle.
+ */
+export interface VideoTransformationAcceptedEvent extends BaseWebhookEvent {
   /**
    * Timestamp when the event was created in ISO8601 format.
    */
@@ -609,12 +619,13 @@ export namespace VideoTransformationAcceptedEvent {
   }
 }
 
-export interface VideoTransformationErrorEvent {
-  /**
-   * Unique identifier for the event.
-   */
-  id: string;
-
+/**
+ * Triggered when an error occurs during video encoding. Listen to this webhook to
+ * log error reasons and debug issues. Check your origin and URL endpoint settings
+ * if the reason is related to download failure. For other errors, contact ImageKit
+ * support.
+ */
+export interface VideoTransformationErrorEvent extends BaseWebhookEvent {
   /**
    * Timestamp when the event was created in ISO8601 format.
    */
@@ -751,12 +762,13 @@ export namespace VideoTransformationErrorEvent {
   }
 }
 
-export interface VideoTransformationReadyEvent {
-  /**
-   * Unique identifier for the event.
-   */
-  id: string;
-
+/**
+ * Triggered when video encoding is finished and the transformed resource is ready
+ * to be served. This is the key event to listen for - update your database or CMS
+ * flags when you receive this so your application can start showing the
+ * transformed video to users.
+ */
+export interface VideoTransformationReadyEvent extends BaseWebhookEvent {
   /**
    * Timestamp when the event was created in ISO8601 format.
    */
@@ -942,6 +954,11 @@ export namespace VideoTransformationReadyEvent {
   }
 }
 
+/**
+ * Triggered when a new video transformation request is accepted for processing.
+ * This event confirms that ImageKit has received and queued your transformation
+ * request. Use this for debugging and tracking transformation lifecycle.
+ */
 export type UnsafeUnwrapWebhookEvent =
   | VideoTransformationAcceptedEvent
   | VideoTransformationReadyEvent
@@ -951,6 +968,11 @@ export type UnsafeUnwrapWebhookEvent =
   | UploadPostTransformSuccessEvent
   | UploadPostTransformErrorEvent;
 
+/**
+ * Triggered when a new video transformation request is accepted for processing.
+ * This event confirms that ImageKit has received and queued your transformation
+ * request. Use this for debugging and tracking transformation lifecycle.
+ */
 export type UnwrapWebhookEvent =
   | VideoTransformationAcceptedEvent
   | VideoTransformationReadyEvent
@@ -962,6 +984,7 @@ export type UnwrapWebhookEvent =
 
 export declare namespace Webhooks {
   export {
+    type BaseWebhookEvent as BaseWebhookEvent,
     type UploadPostTransformErrorEvent as UploadPostTransformErrorEvent,
     type UploadPostTransformSuccessEvent as UploadPostTransformSuccessEvent,
     type UploadPreTransformErrorEvent as UploadPreTransformErrorEvent,

tests/api-resources/webhooks.test.ts

@@ -14,7 +14,7 @@ describe('resource webhooks', () => {
   test.skip('unwrap', async () => {
     const key = 'whsec_c2VjcmV0Cg==';
     const payload =
-      '{"id":"id","created_at":"2019-12-27T18:11:19.117Z","data":{"asset":{"url":"https://example.com"},"transformation":{"type":"video-transformation","options":{"audio_codec":"aac","auto_rotate":true,"format":"mp4","quality":0,"stream_protocol":"HLS","variants":["string"],"video_codec":"h264"}}},"request":{"url":"https://example.com","x_request_id":"x_request_id","user_agent":"user_agent"},"type":"video.transformation.accepted"}';
+      '{"id":"id","type":"video.transformation.accepted","created_at":"2019-12-27T18:11:19.117Z","data":{"asset":{"url":"https://example.com"},"transformation":{"type":"video-transformation","options":{"audio_codec":"aac","auto_rotate":true,"format":"mp4","quality":0,"stream_protocol":"HLS","variants":["string"],"video_codec":"h264"}}},"request":{"url":"https://example.com","x_request_id":"x_request_id","user_agent":"user_agent"}}';
     const msgID = '1';
     const timestamp = new Date();
     const wh = new Webhook(key);