feat: added support for new api in beta - analyze api (#656)

Author: cloudinary-pkoniu

lib/analysis/index.js

@@ -0,0 +1,28 @@
+const utils = require("../utils");
+const {call_analysis_api} = require('../api_client/call_analysis_api');
+
+function analyze_uri(uri, analysis_type, options = {}, callback) {
+  const params = {
+    uri,
+    analysis_type
+  }
+
+  if (analysis_type === 'custom') {
+    if (!('model_name' in options) || !('model_version' in options)) {
+      throw new Error('Setting analysis_type to "custom" requires additional params: "model_name" and "model_version"');
+    }
+    params.parameters = {
+      custom: {
+        model_name: options.model_name,
+        model_version: options.model_version
+      }
+    }
+  }
+
+  let api_uri = ['analysis', 'analyze', 'uri'];
+  return call_analysis_api('POST', api_uri, params, callback, options);
+}
+
+module.exports = {
+  analyze_uri
+};

lib/api_client/call_analysis_api.js

@@ -0,0 +1,32 @@
+const utils = require("../utils");
+const config = require("../config");
+const ensureOption = require('../utils/ensureOption').defaults(config());
+const execute_request = require("./execute_request");
+
+const {ensurePresenceOf} = utils;
+
+function call_analysis_api(method, uri, params, callback, options) {
+  ensurePresenceOf({
+    method,
+    uri
+  });
+  const api_url = utils.base_api_url_v2()(uri, options);
+  let auth = {};
+  if (options.oauth_token || config().oauth_token) {
+    auth = {
+      oauth_token: ensureOption(options, "oauth_token")
+    };
+  } else {
+    auth = {
+      key: ensureOption(options, "api_key"),
+      secret: ensureOption(options, "api_secret")
+    };
+  }
+  options.content_type = 'json';
+
+  return execute_request(method, params, auth, api_url, callback, options);
+}
+
+module.exports = {
+  call_analysis_api
+};

lib/api_client/call_api.js

@@ -8,7 +8,7 @@ const { ensurePresenceOf } = utils;
 
 function call_api(method, uri, params, callback, options) {
   ensurePresenceOf({ method, uri });
-  const api_url = utils.base_api_url(uri, options);
+  const api_url = utils.base_api_url_v1()(uri, options);
   let auth = {};
   if (options.oauth_token || config().oauth_token){
     auth = {

lib/api_client/execute_request.js

@@ -99,9 +99,15 @@ function execute_request(method, params, auth, api_url, callback, options = {})
         if (result.error) {
           result.error.http_code = res.statusCode;
         } else {
-          result.rate_limit_allowed = parseInt(res.headers["x-featureratelimit-limit"]);
-          result.rate_limit_reset_at = new Date(res.headers["x-featureratelimit-reset"]);
-          result.rate_limit_remaining = parseInt(res.headers["x-featureratelimit-remaining"]);
+          if (res.headers["x-featureratelimit-limit"]) {
+            result.rate_limit_allowed = parseInt(res.headers["x-featureratelimit-limit"]);
+          }
+          if (res.headers["x-featureratelimit-reset"]) {
+            result.rate_limit_reset_at = new Date(res.headers["x-featureratelimit-reset"]);
+          }
+          if (res.headers["x-featureratelimit-remaining"]) {
+            result.rate_limit_remaining = parseInt(res.headers["x-featureratelimit-remaining"]);
+          }
         }
 
         if (result.error) {

lib/cloudinary.js

@@ -3,7 +3,9 @@ exports.config = require("./config");
 exports.utils = require("./utils");
 exports.uploader = require("./uploader");
 exports.api = require("./api");
-let account = require("./provisioning/account");
+exports.analysis = require('./analysis');
+
+const account = require("./provisioning/account");
 
 exports.provisioning = {
   account: account

lib/utils/index.js

@@ -1058,17 +1058,31 @@ function unsigned_url_prefix(
   return prefix;
 }
 
-function base_api_url(path = [], options = {}) {
-  let cloudinary = ensureOption(options, "upload_prefix", UPLOAD_PREFIX);
-  let cloud_name = ensureOption(options, "cloud_name");
-  let encode_path = unencoded_path => encodeURIComponent(unencoded_path).replace("'", '%27');
-  let encoded_path = Array.isArray(path) ? path.map(encode_path) : encode_path(path);
-  return [cloudinary, "v1_1", cloud_name].concat(encoded_path).join("/");
+function base_api_url_v1_1() {
+  return base_api_url('v1_1');
+}
+
+function base_api_url_v2() {
+  return base_api_url('v2');
+}
+
+function base_api_url(api_version) {
+  if (!api_version || api_version.length === 0) {
+    throw new Error('api_version needs to be a non-empty string');
+  }
+
+  return (path = [], options = []) => {
+    let cloudinary = ensureOption(options, "upload_prefix", UPLOAD_PREFIX);
+    let cloud_name = ensureOption(options, "cloud_name");
+    let encode_path = unencoded_path => encodeURIComponent(unencoded_path).replace("'", '%27');
+    let encoded_path = Array.isArray(path) ? path.map(encode_path) : encode_path(path);
+    return [cloudinary, api_version, cloud_name].concat(encoded_path).join("/");
+  };
 }
 
 function api_url(action = 'upload', options = {}) {
   let resource_type = options.resource_type || "image";
-  return base_api_url([resource_type, action], options);
+  return base_api_url_v1_1()([resource_type, action], options);
 }
 
 function random_public_id() {
@@ -1225,7 +1239,7 @@ function download_backedup_asset(asset_id, version_id, options = {}) {
     asset_id: asset_id,
     version_id: version_id
   }, options);
-  return exports.base_api_url(['download_backup'], options) + "?" + hashToQuery(params);
+  return exports.base_api_url_v1()(['download_backup'], options) + "?" + hashToQuery(params);
 }
 
 /**
@@ -1681,7 +1695,8 @@ exports.only = pickOnlyExistingValues; // for backwards compatibility
 exports.pickOnlyExistingValues = pickOnlyExistingValues;
 exports.jsonArrayParam = jsonArrayParam;
 exports.download_folder = download_folder;
-exports.base_api_url = base_api_url;
+exports.base_api_url_v1 = base_api_url_v1_1;
+exports.base_api_url_v2 = base_api_url_v2;
 exports.download_backedup_asset = download_backedup_asset;
 exports.compute_hash = compute_hash;
 exports.build_distribution_domain = build_distribution_domain;

test/integration/api/analysis/analyze_spec.js

@@ -0,0 +1,67 @@
+const assert = require('assert');
+const sinon = require('sinon');
+const ClientRequest = require('_http_client').ClientRequest;
+const api_http = require('https');
+
+const cloudinary = require('../../../../cloudinary');
+const helper = require('../../../spechelper');
+
+describe('Analyze API', () => {
+  describe('uri analysis', () => {
+    const mocked = {};
+    const config = {};
+
+    beforeEach(function () {
+      mocked.xhr = sinon.useFakeXMLHttpRequest();
+      mocked.write = sinon.spy(ClientRequest.prototype, 'write');
+      mocked.request = sinon.spy(api_http, 'request');
+
+      config.cloud_name = cloudinary.config().cloud_name;
+    });
+
+    afterEach(function () {
+      mocked.request.restore();
+      mocked.write.restore();
+      mocked.xhr.restore();
+    });
+
+    it('should call analyze endpoint with non-custom analysis_type', () => {
+      cloudinary.analysis.analyze_uri('https://example.com', 'captioning');
+
+      sinon.assert.calledWith(mocked.request, sinon.match({
+        pathname: sinon.match(new RegExp(`/v2/${config.cloud_name}/analysis/analyze/uri`)),
+        method: sinon.match('POST')
+      }));
+      sinon.assert.calledWith(mocked.write, sinon.match(helper.apiJsonParamMatcher('uri', 'https://example.com')));
+      sinon.assert.calledWith(mocked.write, sinon.match(helper.apiJsonParamMatcher('analysis_type', 'captioning')));
+    });
+
+    it('should call analyze endpoint with custom analysis_type', () => {
+      cloudinary.analysis.analyze_uri('https://example.com', 'custom', {
+        model_name: 'my_model',
+        model_version: 1
+      });
+
+      sinon.assert.calledWith(mocked.request, sinon.match({
+        pathname: sinon.match(new RegExp(`/v2/${config.cloud_name}/analysis/analyze/uri`)),
+        method: sinon.match('POST')
+      }));
+      sinon.assert.calledWith(mocked.write, sinon.match(helper.apiJsonParamMatcher('uri', 'https://example.com')));
+      sinon.assert.calledWith(mocked.write, sinon.match(helper.apiJsonParamMatcher('analysis_type', 'custom')));
+      sinon.assert.calledWith(mocked.write, sinon.match(helper.apiJsonParamMatcher('parameters', {
+        custom: {
+          model_name: 'my_model',
+          model_version: 1
+        }
+      })));
+    });
+
+    it('should not allow calling analyze endpoint with incorrect custom analysis parameters', () => {
+      assert.throws(() => {
+        cloudinary.analysis.analyze_uri('https://example.com', 'custom');
+      }, {
+        message: 'Setting analysis_type to "custom" requires additional params: "model_name" and "model_version"'
+      });
+    });
+  });
+});

test/utils/utils_spec.js

@@ -458,7 +458,7 @@ describe("utils", function () {
     });
     it('should escape api urls', function () {
       const folderName = "sub^folder's test";
-      const url = utils.base_api_url(['folders', folderName]);
+      const url = utils.base_api_url_v1()(['folders', folderName]);
       expect(url).to.match(/folders\/sub%5Efolder%27s%20test$/);
     });
   });

types/cloudinary_ts_spec.ts

@@ -1151,6 +1151,14 @@ cloudinary.v2.provisioning.account.user_group_users(
 
     });
 
+// $ExpectType Promise<AnalyzeResponse>
+cloudinary.v2.analysis.analyze_uri('https://example.com', 'captioning');
+
+// $ExpectType Promise<AnalyzeResponse>
+cloudinary.v2.analysis.analyze_uri('https://example.com', 'custom', {
+    model_name: 'my_name',
+    model_version: 1
+});
 
 // $ExpectType string
 cloudinary.v2.utils.private_download_url('foo', 'foo', {

types/index.d.ts

@@ -839,6 +839,26 @@ declare module 'cloudinary' {
 
     export type SignApiOptions = Record<string, any>;
 
+    export interface DatasourceEntry {
+        external_id?: string;
+        value: string;
+    }
+
+    export type AnalysisType = 'custom' | 'captioning' | 'cld_fashion' | 'cld_text' | 'coco' | 'google_tagging' | 'human_anatomy' | 'lvis' | 'shop_classifier' | 'unidet';
+
+    export type CustomAnalysisOptions = {
+        model_name: string,
+        model_version: number
+    }
+
+    export interface AnalyzeResponse {
+        data: {
+            entity: string,
+            analysis: Record<string, Record<string, string> | Array<string> | string>
+        },
+        request_id: string,
+    }
+
     export namespace v2 {
 
         /****************************** Global Utils *************************************/
@@ -1437,5 +1457,9 @@ declare module 'cloudinary' {
                 function user_group_users(groupId: string, options?: ProvisioningApiOptions, callback?: ResponseCallback): Promise<any>;
             }
         }
+
+        namespace analysis {
+            function analyze_uri(uri: string, analysis_type: AnalysisType, options?: ConfigOptions & CustomAnalysisOptions): Promise<AnalyzeResponse>
+        }
     }
 }