Merge pull request #575 from cloudinary/parameter-typing-impoved

feat: detailed typing for parameters

Author: tamaracloudinary

types/index.d.ts

@@ -1,3 +1,4 @@
+import { AnyARecord } from 'dns';
 import { Transform } from 'stream';
 
 
@@ -260,9 +261,9 @@ declare module 'cloudinary' {
         background?: string;
         angle?: Angle;
         radius?: number | string;
-        overlay?: string | object;
+        overlay?: string | object; //might be Record<any, any>
         custom_function?: string | { function_type: string | "wasm" | "remote", source: string }
-        variables?: Array<string | object>;
+        variables?: Array<string | object>; //might be Record<any, any>
         if?: string;
         else?: string;
         end_if?: string;
@@ -274,7 +275,7 @@ declare module 'cloudinary' {
     }
 
     export interface ImageTransformationOptions extends CommonTransformationOptions {
-        underlay?: string | Object;
+        underlay?: string | Object; //might be Record<any, any>
         color?: string;
         color_space?: ColorSpace;
         opacity?: number | string;
@@ -293,7 +294,7 @@ declare module 'cloudinary' {
     interface VideoTransformationOptions extends CommonTransformationOptions {
         audio_codec?: AudioCodec;
         audio_frequency?: AudioFrequency;
-        video_codec?: string | Object;
+        video_codec?: string | Object; //might be Record<any, any>
         bit_rate?: number | string;
         fps?: string | Array<number | string>;
         keyframe_interval?: string;
@@ -340,7 +341,7 @@ declare module 'cloudinary' {
         sign_url?: boolean;
         long_url_signature?: boolean;
         use_root_path?: boolean;
-        auth_token?: object;
+        auth_token?: AuthTokenApiOptions;
         account_id?: string;
         provisioning_api_key?: string;
         provisioning_api_secret?: string;
@@ -365,8 +366,8 @@ declare module 'cloudinary' {
     export interface ImageTagOptions {
         html_height?: string;
         html_width?: string;
-        srcset?: object;
-        attributes?: object;
+        srcset?: object; //might be Record<any, any>
+        attributes?: object; //might be Record<any, any>
         client_hints?: boolean;
         responsive?: boolean;
         hidpi?: boolean;
@@ -379,7 +380,7 @@ declare module 'cloudinary' {
         source_types?: string | string[];
         source_transformation?: TransformationOptions;
         fallback_content?: string;
-        poster?: string | object;
+        poster?: string | object; //might be Record<any, any>
         controls?: boolean;
         preload?: string;
 
@@ -388,7 +389,7 @@ declare module 'cloudinary' {
 
     /****************************** Admin API Options *************************************/
     export interface AdminApiOptions {
-        agent?: object;
+        agent?: object; //might be Record<any, any>
         content_type?: string;
         oauth_token?: string;
 
@@ -436,7 +437,7 @@ declare module 'cloudinary' {
         similarity_search?: string;
         tags?: string | string[];
         moderation_status?: string;
-        unsafe_update?: object;
+        unsafe_update?: object; //might be Record<any, any>
         allowed_for_strict?: boolean;
         asset_folder?: string;
         unique_display_name?: boolean;
@@ -507,7 +508,7 @@ declare module 'cloudinary' {
         proxy?: string;
         public_id?: string;
         quality_analysis?: boolean;
-        responsive_breakpoints?: object;
+        responsive_breakpoints?: Record<any,any>;
         return_delete_token?: boolean
         timestamp?: number;
         transformation?: TransformationOptions;
@@ -527,7 +528,7 @@ declare module 'cloudinary' {
         account_id?: string;
         provisioning_api_key?: string;
         provisioning_api_secret?: string;
-        agent?: object;
+        agent?: object; //might be Record<any, any>?
         content_type?: string;
 
         [futureKey: string]: any;
@@ -548,7 +549,7 @@ declare module 'cloudinary' {
         | string[]
         | VideoTransformationOptions
         | ImageTransformationOptions
-        | Object
+        | Object //might be Record<any, any>
         | Array<ImageTransformationOptions>
         | Array<VideoTransformationOptions>;
 
@@ -593,8 +594,8 @@ declare module 'cloudinary' {
         original_filename: string;
         moderation: Array<string>;
         access_control: Array<string>;
-        context: object;
-        metadata: object;
+        context: object; //won't change since it's response, we need to discuss documentation team about it before implementing.
+        metadata: object; //won't change since it's response, we need to discuss documentation team about it before implementing.
         colors?: [string, number][];
 
         [futureKey: string]: any;
@@ -622,8 +623,8 @@ declare module 'cloudinary' {
         label?: string;
         mandatory?: boolean;
         default_value?: number;
-        validation?: object;
-        datasource?: object;
+        validation?: object; //there are 4 types, we need to discuss documentation team about it before implementing.
+        datasource?: DatasourceEntry;
 
         [futureKey: string]: any;
     }
@@ -634,8 +635,8 @@ declare module 'cloudinary' {
         label: string;
         mandatory: boolean;
         default_value: number;
-        validation: object;
-        datasource: object;
+        validation: object; //there are 4 types, we need to discuss documentation team about it before implementing.
+        datasource: DatasourceEntry;
 
         [futureKey: string]: any;
     }
@@ -645,7 +646,7 @@ declare module 'cloudinary' {
     }
 
     export interface DatasourceChange {
-        values: Array<object>
+        values: Array<DatasourceEntry>
     }
 
     export interface ResourceApiResponse {
@@ -666,19 +667,19 @@ declare module 'cloudinary' {
                 url: string;
                 secure_url: string;
                 tags: Array<string>;
-                context: object;
+                context: object; //won't change since it's response, we need to discuss documentation team about it before implementing.
                 next_cursor: string;
                 derived_next_cursor: string;
-                exif: object;
-                image_metadata: object;
+                exif: object; //won't change since it's response, we need to discuss documentation team about it before implementing.
+                image_metadata: object; //won't change since it's response, we need to discuss documentation team about it before implementing.
                 faces: number[][];
                 quality_analysis: number;
                 colors: [string, number][];
                 derived: Array<string>;
-                moderation: object;
+                moderation: object; //won't change since it's response, we need to discuss documentation team about it before implementing.
                 phash: string;
-                predominant: object;
-                coordinates: object;
+                predominant: object; //won't change since it's response, we need to discuss documentation team about it before implementing.
+                coordinates: object; //won't change since it's response, we need to discuss documentation team about it before implementing.
                 access_control: Array<string>;
                 pages: number;
 
@@ -687,6 +688,12 @@ declare module 'cloudinary' {
         ]
     }
 
+    export type SignApiOptions = Record<string, any>;
+
+    export interface DatasourceEntry {
+        external_id?: string;
+        value: string;
+    }
 
     export namespace v2 {
 
@@ -716,9 +723,9 @@ declare module 'cloudinary' {
 
         namespace utils {
 
-            function sign_request(params_to_sign: object, options?: ConfigAndUrlOptions): { signature: string; api_key: string; [key:string]:any};
+            function sign_request(params_to_sign: SignApiOptions, options?: ConfigAndUrlOptions): { signature: string; api_key: string; [key:string]:any};
 
-            function api_sign_request(params_to_sign: object, api_secret: string): string;
+            function api_sign_request(params_to_sign: SignApiOptions, api_secret: string): string;
 
             function verifyNotificationSignature(body: string, timestamp: number, signature: string, valid_for?: number): boolean;
 
@@ -957,9 +964,9 @@ declare module 'cloudinary' {
 
             function update_metadata_field(external_id: string, field: MetadataFieldApiOptions, callback?: ResponseCallback): Promise<MetadataFieldApiResponse>;
 
-            function update_metadata_field_datasource(field_external_id: string, entries_external_id: object, options?: AdminApiOptions, callback?: ResponseCallback): Promise<DatasourceChange>;
+            function update_metadata_field_datasource(field_external_id: string, entries_external_id: DatasourceChange, options?: AdminApiOptions, callback?: ResponseCallback): Promise<DatasourceChange>;
 
-            function update_metadata_field_datasource(field_external_id: string, entries_external_id: object, callback?: ResponseCallback): Promise<DatasourceChange>;
+            function update_metadata_field_datasource(field_external_id: string, entries_external_id: DatasourceChange, callback?: ResponseCallback): Promise<DatasourceChange>;
 
             function delete_datasource_entries(field_external_id: string, entries_external_id: string[], options?: AdminApiOptions, callback?: ResponseCallback): Promise<DatasourceChange>;
 
@@ -1067,9 +1074,9 @@ declare module 'cloudinary' {
 
             /****************************** Structured Metadata API V2 Methods *************************************/
 
-            function update_metadata(metadata: string | object, public_ids: string[], options?:UploadApiOptions, callback?: ResponseCallback): Promise<MetadataFieldApiResponse>;
+            function update_metadata(metadata: string | Record<any, any>, public_ids: string[], options?:UploadApiOptions, callback?: ResponseCallback): Promise<MetadataFieldApiResponse>;
 
-            function update_metadata(metadata: string| object, public_ids: string[], callback?: ResponseCallback): Promise<MetadataFieldApiResponse>;
+            function update_metadata(metadata: string| Record<any, any>, public_ids: string[], callback?: ResponseCallback): Promise<MetadataFieldApiResponse>;
         }
 
         /****************************** Search API *************************************/
@@ -1115,11 +1122,11 @@ declare module 'cloudinary' {
 
                 function sub_account(subAccountId: string, options?: ProvisioningApiOptions, callback?: ResponseCallback): Promise<any>;
 
-                function create_sub_account(name: string, cloudName: string, customAttributes?: object, enabled?: boolean, baseAccount?: string, options?: ProvisioningApiOptions, callback?: ResponseCallback): Promise<any>;
+                function create_sub_account(name: string, cloudName: string, customAttributes?: Record<any,any>, enabled?: boolean, baseAccount?: string, options?: ProvisioningApiOptions, callback?: ResponseCallback): Promise<any>;
 
                 function delete_sub_account(subAccountId: string, options?: ProvisioningApiOptions, callback?: ResponseCallback): Promise<any>;
 
-                function update_sub_account(subAccountId: string, name?: string, cloudName?: string, customAttributes?: object, enabled?: boolean, options?: ProvisioningApiOptions, callback?: ResponseCallback): Promise<any>;
+                function update_sub_account(subAccountId: string, name?: string, cloudName?: string, customAttributes?: Record<any,any>, enabled?: boolean, options?: ProvisioningApiOptions, callback?: ResponseCallback): Promise<any>;
 
                 function user(userId: string, options?: ProvisioningApiOptions, callback?: ResponseCallback): Promise<any>;