enable passing query params to URLConfig

Author: lbendavid-cloudinary

__TESTS__/unit/url/url.test.ts

@@ -94,4 +94,16 @@ describe('Tests for URL configuration', () => {
 
     expect(url).toEqual(`https://res.cloudinary.com/demo/image/upload/s--${signature}--/c_crop,w_100/sample`);
   });
+
+  it('Should include query params', function () {
+    const image = createNewImage('sample', {cloudName: 'demo'}, {queryParams: {"_i": "abcde", "_z": 1234}});
+    const url = image.toURL();
+    expect(url).toEqual(`https://res.cloudinary.com/demo/image/upload/sample?_i=abcde&_z=1234`);
+  });
+
+  it('Should include query params with analytics', function () {
+    const image = createNewImage('sample', {cloudName: 'demo'}, {analytics: true, queryParams: {"_i": "abcde"}});
+    const url = image.toURL();
+    expect(url).toEqual(`https://res.cloudinary.com/demo/image/upload/sample?_i=abcde&_a=E`);
+  });
 });

__TESTS__/unit/urlConfig.test.ts

@@ -157,7 +157,8 @@ describe('It tests a combination of Cloudinary URL and Configuration', () => {
       .setSecure(true)
       .setShorten(true)
       .setSignUrl(true)
-      .setUseRootPath(true);
+      .setUseRootPath(true)
+      .setQueryParams({foo: 'bar'});
 
     expect(conf.cname).toBe('foo');
     expect(conf.forceVersion).toBe(true);
@@ -167,5 +168,6 @@ describe('It tests a combination of Cloudinary URL and Configuration', () => {
     expect(conf.shorten).toBe(true);
     expect(conf.signUrl).toBe(true);
     expect(conf.useRootPath).toBe(true);
+    expect(conf.queryParams).toEqual({foo: 'bar'});
   });
 });

src/assets/CloudinaryFile.ts

@@ -283,10 +283,17 @@ class CloudinaryFile {
         .replace(/\?/g, '%3F')
         .replace(/=/g, '%3D');
 
+      const queryParams: Record<string, string | number> = this.urlConfig.queryParams || {};
+
       // urlConfig.analytics is true by default, has to be explicitly set to false to overwrite
       // Don't add analytics when publicId includes a '?' to not risk changing existing query params
       if (this.urlConfig.analytics !== false && !(publicID.includes('?'))) {
-        return `${safeURL}?_a=${getSDKAnalyticsSignature(trackedAnalytics)}`;
+        queryParams._a = getSDKAnalyticsSignature(trackedAnalytics);
+      }
+
+      const queryParamsStr = `${Object.entries(queryParams).map(([key, value]) => `${key}=${value}`).join('&')}`;
+      if (queryParamsStr) {
+        return `${safeURL}?${queryParamsStr}`;
       } else {
         return safeURL;
       }

src/config/URLConfig.ts

@@ -13,6 +13,7 @@ class URLConfig extends Config implements IURLConfig {
   useRootPath?: boolean;
   secure?: boolean;
   forceVersion?: boolean;
+  queryParams?: Record<string, string | number>
 
   /**
    * @param {IURLConfig} userURLConfig
@@ -101,6 +102,14 @@ class URLConfig extends Config implements IURLConfig {
     this.forceVersion = value;
     return this;
   }
+
+  /**
+   * @param params Sets additional query params
+   */
+  setQueryParams(params: Record<string, string | number>):this {
+    this.queryParams = params;
+    return this;
+  }
 }
 
 export default URLConfig;

src/config/interfaces/Config/IURLConfig.ts

@@ -13,6 +13,7 @@
  * @prop {boolean} [secure]
  * @prop {boolean} [forceVersion]
  * @prop {boolean} [analytics]
+ * @prop {object} [additionalQueryParams]
  * @example
  * import Cloudinary from '@cloudinary/url-gen';
  * // The Cloudinary Instance accepts a URLConfig under the `url` key
@@ -93,6 +94,11 @@ interface IURLConfig {
    * Whether or not to force a version
    */
   forceVersion?: boolean;
+
+  /**
+   * Additional query params to be added to the URL
+   */
+  queryParams?: Record<string, string | number>
 }
 
 export default IURLConfig;

src/internal/internalConstants.ts

@@ -16,7 +16,8 @@ export const ALLOWED_URL_CONFIG = [
   'useRootPath',
   'secure',
   'forceVersion',
-  'analytics'
+  'analytics',
+  'queryParams'
 ];
 
 /**