Structured metadata support

* Add structured metadata APIs and entities

Author: RTLcoil

lib-es5/api.js

@@ -618,4 +618,169 @@ exports.update_resources_access_mode_by_ids = function update_resources_access_m
   var options = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
 
   return updateResourcesAccessMode(access_mode, "public_ids[]", ids, callback, options);
+};
+
+/**
+ * Creates a new metadata field definition
+ *
+ * @see https://cloudinary.com/documentation/admin_api#create_a_metadata_field
+ *
+ * @param {Object}   field    The field to add
+ * @param {Function} callback Callback function
+ * @param {Object}   options  Configuration options
+ *
+ * @return {Object}
+ */
+exports.add_metadata_field = function add_metadata_field(field, callback) {
+  var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+
+  var params = only(field, "external_id", "type", "label", "mandatory", "default_value", "validation", "datasource");
+  options.content_type = "json";
+  return call_api("post", ["metadata_fields"], params, callback, options);
+};
+
+/**
+ * Returns a list of all metadata field definitions
+ *
+ * @see https://cloudinary.com/documentation/admin_api#get_metadata_fields
+ *
+ * @param {Function} callback Callback function
+ * @param {Object}   options  Configuration options
+ *
+ * @return {Object}
+ */
+exports.list_metadata_fields = function list_metadata_fields(callback) {
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+
+  return call_api("get", ["metadata_fields"], {}, callback, options);
+};
+
+/**
+ * Deletes a metadata field definition.
+ *
+ * The field should no longer be considered a valid candidate for all other endpoints
+ *
+ * @see https://cloudinary.com/documentation/admin_api#delete_a_metadata_field_by_external_id
+ *
+ * @param {String}   field_external_id  The external id of the field to delete
+ * @param {Function} callback           Callback function
+ * @param {Object}   options            Configuration options
+ *
+ * @return {Object}
+ */
+exports.delete_metadata_field = function delete_metadata_field(field_external_id, callback) {
+  var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+
+  return call_api("delete", ["metadata_fields", field_external_id], {}, callback, options);
+};
+
+/**
+ * Get a metadata field by external id
+ *
+ * @see https://cloudinary.com/documentation/admin_api#get_a_metadata_field_by_external_id
+ *
+ * @param {String}   external_id  The ID of the metadata field to retrieve
+ * @param {Function} callback     Callback function
+ * @param {Object}   options      Configuration options
+ *
+ * @return {Object}
+ */
+exports.metadata_field_by_field_id = function metadata_field_by_field_id(external_id, callback) {
+  var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+
+  return call_api("get", ["metadata_fields", external_id], {}, callback, options);
+};
+
+/**
+ * Updates a metadata field by external id
+ *
+ * Updates a metadata field definition (partially, no need to pass the entire object) passed as JSON data.
+ * See {@link https://cloudinary.com/documentation/admin_api#generic_structure_of_a_metadata_field Generic structure of a metadata field} for details.
+ *
+ * @see https://cloudinary.com/documentation/admin_api#update_a_metadata_field_by_external_id
+ *
+ * @param {String}   external_id  The ID of the metadata field to update
+ * @param {Object}   field        Updated values of metadata field
+ * @param {Function} callback     Callback function
+ * @param {Object}   options      Configuration options
+ *
+ * @return {Object}
+ */
+exports.update_metadata_field = function update_metadata_field(external_id, field, callback) {
+  var options = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
+
+  var params = only(field, "external_id", "type", "label", "mandatory", "default_value", "validation", "datasource");
+  options.content_type = "json";
+  return call_api("put", ["metadata_fields", external_id], params, callback, options);
+};
+
+/**
+ * Updates a metadata field datasource
+ *
+ * Updates the datasource of a supported field type (currently only enum and set), passed as JSON data. The
+ * update is partial: datasource entries with an existing external_id will be updated and entries with new
+ * external_id’s (or without external_id’s) will be appended.
+ *
+ * @see https://cloudinary.com/documentation/admin_api#update_a_metadata_field_datasource
+ *
+ * @param {String}   field_external_id    The ID of the field to update
+ * @param {Object}   entries_external_id  Updated values for datasource
+ * @param {Function} callback             Callback function
+ * @param {Object}   options              Configuration options
+ *
+ * @return {Object}
+ */
+exports.update_metadata_field_datasource = function update_metadata_field_datasource(field_external_id, entries_external_id, callback) {
+  var options = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
+
+  var params = only(entries_external_id, "values");
+  options.content_type = "json";
+  return call_api("put", ["metadata_fields", field_external_id, "datasource"], params, callback, options);
+};
+
+/**
+ * Deletes entries in a metadata field datasource
+ *
+ * Deletes (blocks) the datasource entries for a specified metadata field definition. Sets the state of the
+ * entries to inactive. This is a soft delete, the entries still exist under the hood and can be activated again
+ * with the restore datasource entries method.
+ *
+ * @see https://cloudinary.com/documentation/admin_api#delete_entries_in_a_metadata_field_datasource
+ *
+ * @param {String}   field_external_id    The ID of the metadata field
+ * @param {Array}    entries_external_id  An array of IDs of datasource entries to delete
+ * @param {Function} callback             Callback function
+ * @param {Object}   options              Configuration options
+ *
+ * @return {Object}
+ */
+exports.delete_datasource_entries = function delete_datasource_entries(field_external_id, entries_external_id, callback) {
+  var options = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
+
+  options.content_type = "json";
+  var params = { external_ids: entries_external_id };
+  return call_api("delete", ["metadata_fields", field_external_id, "datasource"], params, callback, options);
+};
+
+/**
+ * Restores entries in a metadata field datasource
+ *
+ * Restores (unblocks) any previously deleted datasource entries for a specified metadata field definition.
+ * Sets the state of the entries to active.
+ *
+ * @see https://cloudinary.com/documentation/admin_api#restore_entries_in_a_metadata_field_datasource
+ *
+ * @param {String}   field_external_id    The ID of the metadata field
+ * @param {Array}    entries_external_id  An array of IDs of datasource entries to delete
+ * @param {Function} callback             Callback function
+ * @param {Object}   options              Configuration options
+ *
+ * @return {Object}
+ */
+exports.restore_metadata_field_datasource = function restore_metadata_field_datasource(field_external_id, entries_external_id, callback) {
+  var options = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
+
+  options.content_type = "json";
+  var params = { external_ids: entries_external_id };
+  return call_api("post", ["metadata_fields", field_external_id, "datasource_restore"], params, callback, options);
 };

lib-es5/uploader.js

@@ -654,4 +654,28 @@ exports.unsigned_image_upload_tag = function unsigned_image_upload_tag(field, up
     unsigned: true,
     upload_preset: upload_preset
   }));
+};
+
+/**
+ * Populates metadata fields with the given values. Existing values will be overwritten.
+ *
+ * @param {Object}   metadata   A list of custom metadata fields (by external_id) and the values to assign to each
+ * @param {Array}    public_ids The public IDs of the resources to update
+ * @param {Function} callback   Callback function
+ * @param {Object}   options    Configuration options
+ *
+ * @return {Object}
+ */
+exports.update_metadata = function update_metadata(metadata, public_ids, callback) {
+  var options = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
+
+  return call_api("metadata", callback, options, function () {
+    var params = {
+      metadata: utils.encode_context(metadata),
+      public_ids: utils.build_array(public_ids),
+      timestamp: utils.timestamp(),
+      type: options.type
+    };
+    return [params];
+  });
 };

lib-es5/utils/index.js

@@ -705,6 +705,9 @@ function updateable_resource_params(options) {
   if (options.context != null) {
     params.context = utils.encode_context(options.context);
   }
+  if (options.metadata != null) {
+    params.metadata = utils.encode_context(options.metadata);
+  }
   if (options.custom_coordinates != null) {
     params.custom_coordinates = utils.encode_double_array(options.custom_coordinates);
   }

lib-es5/v2/api.js

@@ -51,5 +51,13 @@ v1_adapters(exports, api, {
   update_resources_access_mode_by_tag: 2,
   update_resources_access_mode_by_ids: 2,
   search: 1,
-  delete_derived_by_transformation: 2
+  delete_derived_by_transformation: 2,
+  add_metadata_field: 1,
+  list_metadata_fields: 1,
+  delete_metadata_field: 1,
+  metadata_field_by_field_id: 1,
+  update_metadata_field: 2,
+  update_metadata_field_datasource: 2,
+  delete_datasource_entries: 2,
+  restore_metadata_field_datasource: 2
 });

lib-es5/v2/uploader.js

@@ -26,7 +26,8 @@ v1_adapters(exports, uploader, {
   remove_all_context: 1,
   replace_tag: 2,
   create_archive: 0,
-  create_zip: 0
+  create_zip: 0,
+  update_metadata: 2
 });
 
 exports.direct_upload = uploader.direct_upload;

lib/api.js

@@ -498,3 +498,152 @@ exports.update_resources_access_mode_by_ids = function update_resources_access_m
 ) {
   return updateResourcesAccessMode(access_mode, "public_ids[]", ids, callback, options);
 };
+
+/**
+ * Creates a new metadata field definition
+ *
+ * @see https://cloudinary.com/documentation/admin_api#create_a_metadata_field
+ *
+ * @param {Object}   field    The field to add
+ * @param {Function} callback Callback function
+ * @param {Object}   options  Configuration options
+ *
+ * @return {Object}
+ */
+exports.add_metadata_field = function add_metadata_field(field, callback, options = {}) {
+  const params = only(field, "external_id", "type", "label", "mandatory", "default_value", "validation", "datasource");
+  options.content_type = "json";
+  return call_api("post", ["metadata_fields"], params, callback, options);
+};
+
+/**
+ * Returns a list of all metadata field definitions
+ *
+ * @see https://cloudinary.com/documentation/admin_api#get_metadata_fields
+ *
+ * @param {Function} callback Callback function
+ * @param {Object}   options  Configuration options
+ *
+ * @return {Object}
+ */
+exports.list_metadata_fields = function list_metadata_fields(callback, options = {}) {
+  return call_api("get", ["metadata_fields"], {}, callback, options);
+};
+
+/**
+ * Deletes a metadata field definition.
+ *
+ * The field should no longer be considered a valid candidate for all other endpoints
+ *
+ * @see https://cloudinary.com/documentation/admin_api#delete_a_metadata_field_by_external_id
+ *
+ * @param {String}   field_external_id  The external id of the field to delete
+ * @param {Function} callback           Callback function
+ * @param {Object}   options            Configuration options
+ *
+ * @return {Object}
+ */
+exports.delete_metadata_field = function delete_metadata_field(field_external_id, callback, options = {}) {
+  return call_api("delete", ["metadata_fields", field_external_id], {}, callback, options);
+};
+
+/**
+ * Get a metadata field by external id
+ *
+ * @see https://cloudinary.com/documentation/admin_api#get_a_metadata_field_by_external_id
+ *
+ * @param {String}   external_id  The ID of the metadata field to retrieve
+ * @param {Function} callback     Callback function
+ * @param {Object}   options      Configuration options
+ *
+ * @return {Object}
+ */
+exports.metadata_field_by_field_id = function metadata_field_by_field_id(external_id, callback, options = {}) {
+  return call_api("get", ["metadata_fields", external_id], {}, callback, options);
+};
+
+/**
+ * Updates a metadata field by external id
+ *
+ * Updates a metadata field definition (partially, no need to pass the entire object) passed as JSON data.
+ * See {@link https://cloudinary.com/documentation/admin_api#generic_structure_of_a_metadata_field Generic structure of a metadata field} for details.
+ *
+ * @see https://cloudinary.com/documentation/admin_api#update_a_metadata_field_by_external_id
+ *
+ * @param {String}   external_id  The ID of the metadata field to update
+ * @param {Object}   field        Updated values of metadata field
+ * @param {Function} callback     Callback function
+ * @param {Object}   options      Configuration options
+ *
+ * @return {Object}
+ */
+exports.update_metadata_field = function update_metadata_field(external_id, field, callback, options = {}) {
+  const params = only(field, "external_id", "type", "label", "mandatory", "default_value", "validation", "datasource");
+  options.content_type = "json";
+  return call_api("put", ["metadata_fields", external_id], params, callback, options);
+};
+
+/**
+ * Updates a metadata field datasource
+ *
+ * Updates the datasource of a supported field type (currently only enum and set), passed as JSON data. The
+ * update is partial: datasource entries with an existing external_id will be updated and entries with new
+ * external_id’s (or without external_id’s) will be appended.
+ *
+ * @see https://cloudinary.com/documentation/admin_api#update_a_metadata_field_datasource
+ *
+ * @param {String}   field_external_id    The ID of the field to update
+ * @param {Object}   entries_external_id  Updated values for datasource
+ * @param {Function} callback             Callback function
+ * @param {Object}   options              Configuration options
+ *
+ * @return {Object}
+ */
+exports.update_metadata_field_datasource = function update_metadata_field_datasource(field_external_id, entries_external_id, callback, options = {}) {
+  const params = only(entries_external_id, "values");
+  options.content_type = "json";
+  return call_api("put", ["metadata_fields", field_external_id, "datasource"], params, callback, options);
+};
+
+/**
+ * Deletes entries in a metadata field datasource
+ *
+ * Deletes (blocks) the datasource entries for a specified metadata field definition. Sets the state of the
+ * entries to inactive. This is a soft delete, the entries still exist under the hood and can be activated again
+ * with the restore datasource entries method.
+ *
+ * @see https://cloudinary.com/documentation/admin_api#delete_entries_in_a_metadata_field_datasource
+ *
+ * @param {String}   field_external_id    The ID of the metadata field
+ * @param {Array}    entries_external_id  An array of IDs of datasource entries to delete
+ * @param {Function} callback             Callback function
+ * @param {Object}   options              Configuration options
+ *
+ * @return {Object}
+ */
+exports.delete_datasource_entries = function delete_datasource_entries(field_external_id, entries_external_id, callback, options = {}) {
+  options.content_type = "json";
+  const params = { external_ids: entries_external_id };
+  return call_api("delete", ["metadata_fields", field_external_id, "datasource"], params, callback, options);
+};
+
+/**
+ * Restores entries in a metadata field datasource
+ *
+ * Restores (unblocks) any previously deleted datasource entries for a specified metadata field definition.
+ * Sets the state of the entries to active.
+ *
+ * @see https://cloudinary.com/documentation/admin_api#restore_entries_in_a_metadata_field_datasource
+ *
+ * @param {String}   field_external_id    The ID of the metadata field
+ * @param {Array}    entries_external_id  An array of IDs of datasource entries to delete
+ * @param {Function} callback             Callback function
+ * @param {Object}   options              Configuration options
+ *
+ * @return {Object}
+ */
+exports.restore_metadata_field_datasource = function restore_metadata_field_datasource(field_external_id, entries_external_id, callback, options = {}) {
+  options.content_type = "json";
+  const params = { external_ids: entries_external_id };
+  return call_api("post", ["metadata_fields", field_external_id, "datasource_restore"], params, callback, options);
+};