{"id":13721072,"url":"https://github.com/kuzzleio/kuzzle-plugin-cloudinary","last_synced_at":"2025-02-27T12:48:13.584Z","repository":{"id":71813405,"uuid":"190592778","full_name":"kuzzleio/kuzzle-plugin-cloudinary","owner":"kuzzleio","description":"Manage your images with Cloudinary","archived":false,"fork":false,"pushed_at":"2021-06-07T14:43:50.000Z","size":366,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-01-10T10:58:45.760Z","etag":null,"topics":["cloudinary","cloudinary-api","kuzzle","kuzzle-plugin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kuzzleio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-06-06T14:10:24.000Z","updated_at":"2021-06-07T14:39:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"b1597bb9-0fdd-4383-8fed-37d380826409","html_url":"https://github.com/kuzzleio/kuzzle-plugin-cloudinary","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuzzleio%2Fkuzzle-plugin-cloudinary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuzzleio%2Fkuzzle-plugin-cloudinary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuzzleio%2Fkuzzle-plugin-cloudinary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuzzleio%2Fkuzzle-plugin-cloudinary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kuzzleio","download_url":"https://codeload.github.com/kuzzleio/kuzzle-plugin-cloudinary/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241015124,"owners_count":19894355,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudinary","cloudinary-api","kuzzle","kuzzle-plugin"],"created_at":"2024-08-03T01:01:12.157Z","updated_at":"2025-02-27T12:48:13.558Z","avatar_url":"https://github.com/kuzzleio.png","language":"JavaScript","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/32480223/59445914-c0f5f700-8e00-11e9-8335-0b69d4728357.png\"/\u003e\n\u003c/p\u003e\n\n# Kuzzle Plugin : Cloudinary\n\nCloudinary is cloud-based image and video management platform. It automates the entire image-processing pipeline: from uploads to on-the-fly manipulations to optimization to dynamic delivery with any CDN.\n\nThis plugin will let you use some of Cloudinary API's functions within Kuzzle. \n\nYou can test this plugin with Swagger UI. Find more in the [Testing section](#testing)\n\n***This plugin is available for 1.8.2 and higher version of Kuzzle***\n\n## Compatibility matrice\n\n| Kuzzle Version | Plugin Version |\n| -------------- | -------------- |\n| 1.x.x          | 1.x.x          | \n| 2.x.x          | 2.x.x          | \n\n## Usage\n \nHere are the existing routes (Note that all of these are preceded by `http://\u003chost\u003e:\u003cport\u003e/_plugin/cloudinary`) \n\n| HTTP Verb | Route |Description | \n| :---- | :---- | :---- | \n| POST | [/assets/search](#search-function) | Searches for some assets corresponding to an expression | \n| POST | [/assets/transform](#transform-function)  | Returns the url of an asset with some transformation |\n| PUT | [/assets/\u003cpublic_id\u003e](#rename-function)  | Renames an asset |\n| DELETE | [/assets/\u003cpublic_id\u003e](#destroy-function)  | Deletes an asset |\n| POST | [/tags/\u003ctag\u003e](#add_tag-function)  | Adds a tag to one or many assets | \n| PUT | [/tags/\u003ctag\u003e](#replace_tag-function)  | Replaces all the tags from one or many assets by another tag |\n| DELETE | [/tags/\u003ctag\u003e](#remove_tag-function)  | Deletes a tag from one or many assets | \n| DELETE | [/tags/remove_all](#remove_all_tags-function)  | Deletes all the tags from one or many assets | \n\n### Assets controller\n\n#### `search` function\nThis function searches for assets corresponding to the given expression\n\nYou can use the cloudinary **search function** by sending a `POST` HTTP-request to this route : `http://\u003chost\u003e:\u003cport\u003e/_plugin/cloudinary/assets/search`\n\nThe expression must be a descriptive string of your research. For more informations on the syntax of this string, check the [Cloudinary documentation about Expressions][cloudinary expression doc]\n\n##### Request format \n```js\n{\n  \"controller\": \"cloudinary/assets\",\n  \"action\": \"search\",\n\n  \"expression\": \"\u003cexpression\u003e\",\n  \"max_results\": \"\u003cnumber_of_result_max\u003e\",\n  \"next_cursor\": \"\u003cnext-cursor\u003e\",\n  \"with_field\": [ \"\u003cadditional_field_to_include\u003e\" ],\n  \"sort_by\": [  [\"\u003cfield\u003e\",\"\u003casc | desc\u003e\"] ]\n}\n```\n\n**You must provide, at least, either the `expression` or the `next_cursor` field. If both are set, `expression` will be ignored** \n\nYou can find more info [here](https://cloudinary.com/documentation/search_api#parameters)\n\n##### Response format \n\n```js\n{\n  \"status\": 200,\n  \"error\": null,\n  \"controller\": \"cloudinary/assets\",\n  \"action\": \"destroy\",\n  \"requestId\": \"\u003cunique request identifier\u003e\",\n  \"result\": {\n      \"total_count\": \"\u003cnumber_of_resources\u003e\",\n      \"time\": \"\u003crequest_processing_time\u003e\",\n      \"next_cursor\": \"\u003ccursor_for_following_request\u003e\",\n      \"resources\" : [ \n          {\n              \"public_id\": \"\u003cnew_public_id\u003e\",\n              \"folder\": \"\u003cfolder\u003e\",\n              \"filename\": \"\u003cfilename\u003e\",\n              \"format\": \"\u003cformat\u003e\",\n              \"resource_type\": \"\u003cressource_type\u003e\",\n              \"type\": \"\u003ctype\u003e\",\n              \"created_at\": \"\u003ccreation_date\u003e\",\n              \"bytes\": \"\u003csize\u003e\",\n              \"backup_bytes\": 0,\n              \"width\": \"\u003cwidth\u003e\",\n              \"height\": \"\u003cheight\u003e\",\n              \"aspect_ratio\": \"\u003cratio\u003e\",\n              \"pixels\": \"\u003cnumber_of_pixels\u003e\",\n              \"url\": \"\u003curl\u003e\",\n              \"secure_url\": \"\u003csecure_url\u003e\",\n              \"status\": \"\u003cstatus\u003e\",\n              \"access_mode\": \"\u003caccess_mode\u003e\",\n          }\n      ],\n      \"rate_limit_allowed\": \"\u003cinitial_request_limit\u003e\",\n      \"rate_limit_reset_at\": \"\u003cdate_of_reset\u003e\",\n      \"rate_limit_remaining\": \"\u003ccurrent_request_limit\u003e\"\n      \n  }\n}\n```\n\nFor more information on search response, see [Cloudinary documentation](https://cloudinary.com/documentation/search_api#response)\n\n#### `transform` function\nThis function returns an url to access the given asset with the given transformations\n\nYou can use the **transform function** by sending a `POST` HTTP-request to this route : \n`http://\u003chost\u003e:\u003cport\u003e/_plugin/cloudinary/assets/transform`\n\n##### Request format \n```js\n{\n  \"controller\": \"cloudinary/assets\",\n  \"action\": \"transform\",\n\n\t\"public_id\" : \"sample\", \n\t\"transformation\" : {\n\t\t\"width\" : 400,\n\t\t\"radius\" : \"100:0:100:100\"\n\t}\n}\n```\n\nThe request body must contain the following properties : \n\n| Property         | Type   | Description                                   |\n| ---------------- | ------ | --------------------------------------------- |\n| `public_id` | string | public_id of the file to be transformed |\n| `transformation`   | JSON | a json describing all the transformations you want to apply to the asset. See [Cloudinary transformation guides][cloudinary transformation doc]     |\n\n##### Response format \n```js\n{\n  \"status\": 200,\n  \"error\": null,\n  \"controller\": \"cloudinary/assets\",\n  \"action\": \"transform\",\n  \"requestId\": \"\u003cunique request identifier\u003e\",\n  \"result\": \"\u003ctransformed_asset_url\u003e\"\n}\n```\n\n#### `rename` function \nThis function renames the given asset\n\nYou can use the cloudinary **rename function** by sending a `PUT` HTTP-request to this route : `http://\u003chost\u003e:\u003cport\u003e/_plugin/cloudinary/assets/\u003cpublic_id\u003e`\n\n:warning: Be aware that Cloudinary allows special characters in the public_id syntax. You may need to encode the public id with escape character\n\n##### Request format \n```js\n{\n  \"controller\": \"cloudinary/assets\",\n  \"action\": \"rename\",\n\n  \"public_id\": \"old_name\",\n  \"new_public_id\": \"new_name\"\n}\n```\n\nThe request must contain the following properties : \n\n| Property         | Type   | Description                                   |\n| ---------------- | ------ | --------------------------------------------- |\n| `public_id` | string | public_id of the file to be renamed |\n| `new_public_id`   | string | new public_id of the file           |\n\n##### Response format \n```js\n{\n  \"status\": 200,\n  \"error\": null,\n  \"controller\": \"cloudinary/assets\",\n  \"action\": \"destroy\",\n  \"requestId\": \"\u003cunique request identifier\u003e\",\n  \"result\": {\n      \"public_id\": \"\u003cnew_public_id\u003e\",\n      \"width\": \"\u003cwidth\u003e\",\n      \"height\": \"\u003cheight\u003e\",\n      \"format\": \"\u003cformat\u003e\",\n      \"resource_type\": \"\u003cressource_type\u003e\",\n      \"created_at\": \"\u003ccreation_date\u003e\",\n      \"tags\": [\n          \"\u003ctag\u003e\"\n      ],\n      \"bytes\": \"\u003csize\u003e\",\n      \"type\": \"\u003ctype\u003e\",\n      \"placeholder\": \"\u003cplaceholder\u003e\",\n      \"url\": \"\u003curl\u003e\",\n      \"secure_url\": \"\u003csecure_url\u003e\"\n  }\n}\n```\n\n#### `destroy` function \nThis function deletes the given asset\n\nYou can use the cloudinary **destroy function** by sending a `DELETE` HTTP-request to this route : `http://\u003chost\u003e:\u003cport\u003e/_plugin/cloudinary/assets/\u003cpublic_id\u003e`\n\n:warning: Be aware that Cloudinary allows special characters in the public_id syntax. You may need to encode the public id with escape character\n\n##### Request format\n```js\n{\n  \"controller\": \"cloudinary/assets\",\n  \"action\": \"destroy\",\n  \"public_id\": \"sample\"\n}\n```\n\nThe request must contain the following properties : \n\n| Property         | Type   | Description                                   |\n| ---------------- | ------ | --------------------------------------------- |\n|`public_id`|string|public_id of the file to be deleted|\n\n\n##### Response format \n```js\n{\n  \"status\": 200,\n  \"error\": null,\n  \"controller\": \"cloudinary/assets\",\n  \"action\": \"destroy\",\n  \"requestId\": \"\u003cunique request identifier\u003e\",\n  \"result\": {\n      \"result\": \"ok\"\n  }\n}\n```\n\n### Tags controller\n\n#### `add_tag` function \nThis function adds the given tag to the given assets\n\nYou can use the cloudinary **add_tag function** by sending a `POST` HTTP-request to this route : `http://\u003chost\u003e:\u003cport\u003e/_plugin/cloudinary/tags/\u003ctag\u003e`\n\n##### Request format\n```js\n{\n  \"controller\": \"cloudinary/tags\",\n  \"action\": \"addTag\",\n\n\t\"public_id\" : [ \"sample\", \"sample2\" ], \n\t\"tag\" : \"\u003ctag_to_add\u003e\"\n}\n```\n\nThe request must contain the following properties : \n\n| Property         | Type   | Description                                   |\n| ---------------- | ------ | --------------------------------------------- |\n|`public_id`|string or [string]|the public_id of the asset to be edited. \u003cbr\u003e **Can concern many assets if you use an array of strings !** \u003cbr\u003e*Be aware of whitespace since Cloudinary authorizes whitespace in the public_id syntax*   |\n|`tag`|string| the tag to be added |\n\nFor more information see the [Cloudinary tags methods][cloudinary tags doc]\n\n##### Response format \n```js\n{\n  \"status\": 200,\n  \"error\": null,\n  \"controller\": \"cloudinary/tags\",\n  \"action\": \"addTag\",\n  \"requestId\": \"\u003cunique request identifier\u003e\",\n  \"result\": {\n      \"public_ids\": [\n          \"sample\",\n          \"sample2\"\n      ] \n  }\n}\n```\n\n#### `replace_tag` function \nThis function replace all the current tag of the given assets by the given tag\n\nYou can use the cloudinary **replace_tag function** by sending a `PUT` HTTP-request to this route : `http://\u003chost\u003e:\u003cport\u003e/_plugin/cloudinary/tags/\u003ctag\u003e`\n\n##### Request format \n```js\n{\n  \"controller\": \"cloudinary/tags\",\n  \"action\": \"replaceTag\",\n\n  \"public_id\" : [ \"sample\", \"sample2\" ],\n  \"tag\": \"a_tag\"\n}\n```\n\nThe request must contain the following properties : \n\n| Property         | Type   | Description                                   |\n| ---------------- | ------ | --------------------------------------------- |\n|`public_id`|string or [string]|the public_id of the asset to be edited. \u003cbr\u003e **Can concern many assets if you use an array of strings !** \u003cbr\u003e*Be aware of whitespace since Cloudinary authorizes whitespace in the public_id syntax*   |\n|`tag`|string| the tag that will replace all the current tag|\n\nFor more information see the [Cloudinary tags methods][cloudinary tags doc]\n\n##### Response format \n```js\n{\n    \"status\": 200,\n    \"error\": null,\n    \"controller\": \"cloudinary/tags\",\n    \"action\": \"replaceTag\",\n    \"requestId\": \"\u003cunique request identifier\u003e\",\n    \"result\": {\n        \"public_ids\": [\n            \"sample\",\n            \"sample2\"\n        ] \n    }\n}\n```\n\n#### `remove_tag` function\nThis function removes the given tag from the given assets \n\nYou can use the cloudinary **remove_tag function** by sending a `DELETE` HTTP-request to this route : `http://\u003chost\u003e:\u003cport\u003e/_plugin/cloudinary/tags/\u003ctag\u003e`\n\n##### Request format \n```js\n{\n    \"controller\": \"cloudinary/tags\",\n    \"action\": \"removeTag\",\n\n\t\"public_id\" : [ \"sample\", \"sample2\" ],\n    \"tag\": \"a_tag\"\n}\n```\n\nThe request must contain the following properties : \n\n| Property         | Type   | Description                                   |\n| ---------------- | ------ | --------------------------------------------- |\n|`public_id`|string or [string]|the public_id of the asset to be edited. \u003cbr\u003e **Can concern many assets if you use an array of strings !** \u003cbr\u003e*Be aware of whitespace since Cloudinary authorizes whitespace in the public_id syntax*   |\n|`tag`|string| the tag to be removed |\n\nFor more information see the [Cloudinary tags methods][cloudinary tags doc]\n\n##### Response format \n```js\n{\n    \"status\": 200,\n    \"error\": null,\n    \"controller\": \"cloudinary/tags\",\n    \"action\": \"removeTag\",\n    \"requestId\": \"\u003cunique request identifier\u003e\",\n    \"result\": {\n        \"public_ids\": [\n            \"sample\",\n            \"sample2\"\n        ] \n    }\n}\n```\n\n#### `remove_all_tags` function \nThis function removes all tags from the given assets\n\nYou can use the cloudinary **remove_all_tags function** by sending a `DELETE` HTTP-request to this route : `http://\u003chost\u003e:\u003cport\u003e/_plugin/cloudinary/tags/remove_all`\n\n##### Request format \n```js\n{\n    \"controller\": \"cloudinary/tags\",\n    \"action\": \"removeAllTags\",\n\n\t\"public_id\" : [ \"sample\", \"sample2\" ] \n}\n```\n\nThe request must contain the following properties : \n\n| Property         | Type   | Description                                   |\n| ---------------- | ------ | --------------------------------------------- |\n|`public_id`|string or [string]|the public_id of the asset to be edited. \u003cbr\u003e **Can concern many assets if you use an array of strings !** \u003cbr\u003e*Be aware of whitespace since Cloudinary authorizes whitespace in the public_id syntax*   |\n\nFor more information see the [Cloudinary tags methods][cloudinary tags doc]\n\n##### Response format \n\n```js\n{\n    \"status\": 200,\n    \"error\": null,\n    \"controller\": \"cloudinary/tags\",\n    \"action\": \"removeAllTags\",\n    \"requestId\": \"\u003cunique request identifier\u003e\",\n    \"result\": {\n        \"public_ids\": [\n            \"sample\",\n            \"sample2\"\n        ] \n    }\n}\n```\n\n## Error handling \n\nAll tag methods can throw a `206 PartialError` if at least one resource has not been updated : This error will contain all the errors encountered during the request. \n\n## Configuration \n\nIn order to use this plugin, you **need to provide your Cloudinary credentials** in the Vault.\n\nHere is the template of the needed structure :\n```json \n{\n  \"cloudinary\": {\n    \"APIKey\":  \"your-cloudinary-api-key\",\n    \"APISecret\": \"your-cloudinary-api-secret\",\n    \"cloudName\": \"your-cloudinary-cloudname\"\n  }\n}\n```\n\nYou can find more about Vault feature on the [Kuzzle documentation][kuzzle vault doc]\n\n## Installation \n\n### On your Kuzzle Stack\n\nClone this repository in your `plugin/available` directory, install all needed modules with `npm install` and then link this directory to your `plugin/enabled` directory. \n\n```bash \ngit clone https://github.com/kuzzleio/kuzzle-plugin-cloudinary.git /path-of-your-kuzzle/plugins/available cloudinary\ncd /path-of-your-kuzzle/plugins/available/cloudinary/\nnpm install \nln -sr ./ ../../plugins/enabled/cloudinary \n```\nYou can now restart Kuzzle and check [http://localhost:7512](http://localhost:7512), you should see the plugin name under the key `serverInfo.kuzzle.plugins.cloudinary`.\n\n## Testing \n\nIf you want to test this plugin, you can use the [Swagger UI online tool](https://petstore.swagger.io)\n\n1) Run Kuzzle with the plugin installed (See [Installation section](#Installation)) **Make sure it is correctly [configured](#Configuration) with your Cloudinary credentials**\n2) Go on the [Swagger UI online tool](https://petstore.swagger.io)\n3) Enter the following link `https://raw.githubusercontent.com/kuzzleio/kuzzle-plugin-cloudinary/master/test/swagger-spec.yaml` and click `Explore`\n4) You have now the details of all available requests, and you can try these out.\n\n[cloudinary tags doc]: https://cloudinary.com/documentation/image_upload_api_reference#tags_method\n[cloudinary expression doc]: https://cloudinary.com/documentation/search_api#expressions\n[cloudinary transformation doc]: https://cloudinary.com/documentation/image_transformation_reference\n[kuzzle vault doc]: https://docs.kuzzle.io/core/2/guides/essentials/secrets-vault/","funding_links":[],"categories":["Plugins"],"sub_categories":["External services plugins"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuzzleio%2Fkuzzle-plugin-cloudinary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuzzleio%2Fkuzzle-plugin-cloudinary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuzzleio%2Fkuzzle-plugin-cloudinary/lists"}