n8n-nodes-cloudinary 0.0.9 → 0.1.1

package/README.md

@@ -12,6 +12,53 @@ On this page, you'll find a list of operations the Cloudinary node supports.
 	* Update asset metadata fields
 	* Get tags
 	* Get structured metadata definitions
+	* Search assets
+* Transform (builds a delivery URL — no API call)
+	* Image: Optimize, Resize, Crop, Convert
+	* Video: Optimize, Resize, Crop, Trim, Thumbnail
+	* Custom Transformation (raw transformation string)
+	* Compose: Combine Transformations (multi-step, in one node)
+* Widget
+	* Video Player (builds an embed URL + player config)
+
+### Search assets
+
+Uses the [Cloudinary Search API](https://cloudinary.com/documentation/search_api) to find assets by tag, folder, metadata, or any supported expression (e.g. `tags=cat AND uploaded_at>1d`, `folder:products/*`, `tags="back to school"`).
+
+The node emits **one n8n item per matching asset**, so downstream nodes can map over results directly without a Split Out step.
+
+- **Resource Types** — Cloudinary's Search API defaults to image-only when no `resource_type:` clause is in the expression. This node injects the clause automatically based on the Resource Types you select (defaults to `image`). To search across all types, select all three. If your expression already contains a `resource_type:` clause, the selection is ignored.
+- **Return All** — when enabled, the node automatically paginates through Cloudinary's `next_cursor` until all matching assets have been returned. When disabled, only the first page (up to *Max Results*, capped at 500) is returned.
+- **Rate limits** — the node surfaces `429`/`420` responses with a clear "rate limit exceeded" error including the server's `Retry-After`.
+- **Eventual consistency** — newly uploaded assets may take a few seconds to appear in search results. Avoid searching for something you just uploaded in the same workflow without a delay.
+
+### Transformations and chaining
+
+A **transformation** is the instruction string Cloudinary applies when delivering an asset — for example `c_fill,w_400` (crop to 400px wide) or `f_auto/q_auto` (auto format and quality). Each Transform operation builds one and returns it on the output as **`transformation`**, alongside the finished `secure_url`.
+
+Real edits usually need several transformations applied in sequence ("first crop, then optimize"). In Cloudinary's URL these are **components joined with `/`**, applied left to right — each acts on the output of the one before it. For example `c_fill,w_400/f_auto/q_auto` means *crop, then auto-format, then auto-quality*. There are three ways to build a chain with this node, from simplest to most flexible:
+
+1. **One operation.** A single Transform op (e.g. *Image: Resize*) when one step is all you need.
+
+2. **Combine Transformations (one node).** The *Compose → Combine Transformations* operation takes an ordered, reorderable list of steps and chains them inside a single node. Best when the whole recipe is known up front and lives in one place.
+
+3. **Continue From Transformation (across nodes).** Every chainable Transform op has an optional **Continue From Transformation** field. This is the bridge that makes chaining work across separate nodes, and it relies on one property mapping:
+
+   > The upstream op's **`transformation`** output → the downstream op's **Continue From Transformation** input.
+
+   Wire it with an expression: set *Continue From Transformation* to `{{ $json.transformation }}`. The node prepends that incoming string before the current op's own transformation, so the two compound into one delivery URL. Example — a *Resize* node outputs `transformation: "c_fill,w_400"`; feed it into an *Optimize* node's *Continue From Transformation*, and the Optimize node delivers `c_fill,w_400/f_auto/q_auto`.
+
+   This field is available on all single-purpose Transform ops. It is intentionally **not** offered on *Custom Transformation* (you already control the entire string there) or *Combine Transformations* (which chains its own steps internally).
+
+**Tip:** *Resize* and *Crop* don't auto-optimize. To also get `f_auto/q_auto`, either add an *Optimize* step in *Combine Transformations*, or chain an *Optimize* node after them via *Continue From Transformation*.
+
+### Video Player (Widget)
+
+The *Widget → Video Player* operation builds a [Cloudinary Video Player](https://cloudinary.com/documentation/video_player_quickstart_guide) embed URL plus a player config. Its **Transformation** field applies to the **played video stream** (it accepts the same `transformation` string the Transform ops emit, so you can wire `{{ $json.transformation }}` here too). A few constraints worth knowing:
+
+- **Use video-capable transforms.** Image-only effects (e.g. `e_grayscale`) are silently ignored on video and have no visible effect. See [video effects](https://cloudinary.com/documentation/video_effects_and_enhancements).
+- **Adaptive streaming vs. format selection.** If you select an adaptive-streaming **Source Type** (HLS or MPEG-DASH), the transformation must **not** pin a delivery format (an `f_` component such as `f_auto:video`, which an *Optimize* step adds). The two are incompatible — Cloudinary can't apply a streaming profile to a fixed non-streaming format. The node detects this and fails with a clear message; for adaptive streaming, keep the transformation to resize/crop/trim only.
+- **Aspect Ratio crops on top of your Transformation.** Setting an **Aspect Ratio** makes the player re-crop the video to those proportions using the **Crop Mode** field (*Smart*, *Fill*, or *Pad* — default *Smart*). With the default *Smart* mode, that re-crop can't be combined with a Transformation that already crops the video, and the player rejects it. The node fails fast with a clear message; to render either set *Crop Mode* to *Fill* or *Pad*, or clear *Aspect Ratio* and let your Transformation define the framing.
 
 ## Supported authentication methods
 
@@ -34,6 +81,10 @@ If you're a user with a Master admin, Admin, or Technical admin role, you can fi
 4. From the top of the page copy the **Cloud name**.
 5. Enter the cloud name, api key and api secret to your n8n credential.
 
+#### Private CDN / custom delivery hostname (advanced)
+
+Most users can skip this. If your organization is on a **Advanced plan** that uses a [private CDN distribution or a custom delivery hostname (CNAME)](https://cloudinary.com/documentation/advanced_url_delivery_options#private_cdns_and_custom_delivery_hostnames_cnames), enable **Private CDN** in the credential and enter your **Custom Delivery Hostname** so the node builds delivery URLs against your private distribution instead of the default `res.cloudinary.com`. Leave these off if you're unsure — they don't apply to standard accounts.
+
 
 ## Related resources
 

package/dist/credentials/CloudinaryApi.credentials.js

@@ -27,6 +27,22 @@ class CloudinaryApi {
                 default: '',
                 typeOptions: { password: true },
             },
+            {
+                displayName: 'Private CDN',
+                name: 'privateCdn',
+                type: 'boolean',
+                default: false,
+                description: 'Whether your account delivers from a private CDN distribution (<cloud>-res.cloudinary.com). Only affects the delivery URLs built by Transform operations.',
+            },
+            {
+                displayName: 'Custom Delivery Hostname',
+                name: 'secureDistribution',
+                type: 'string',
+                default: '',
+                placeholder: 'assets.example.com',
+                description: 'Custom delivery hostname (CNAME) for your private CDN account. Leave empty to use the default <cloud>-res.cloudinary.com subdomain.',
+                displayOptions: { show: { privateCdn: [true] } },
+            },
         ];
         this.authenticate = {
             type: 'generic',

package/dist/credentials/CloudinaryApi.credentials.js.map

@@ -1 +1 @@
-{"version":3,"file":"CloudinaryApi.credentials.js","sourceRoot":"","sources":["../../credentials/CloudinaryApi.credentials.ts"],"names":[],"mappings":";;;AAOA,MAAa,aAAa;IAA1B;QACC,SAAI,GAAG,eAAe,CAAC;QACvB,gBAAW,GAAG,gBAAgB,CAAC;QAC/B,qBAAgB,GAAG,iEAAiE,CAAC;QACrF,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;aACX;YACD;gBACC,WAAW,EAAE,SAAS;gBACtB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;aACX;YACD;gBACC,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;aAC/B;SACD,CAAC;QAGF,iBAAY,GAAyB;YACpC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACX,IAAI,EAAE;oBACL,QAAQ,EAAE,0BAA0B;oBACpC,QAAQ,EAAE,6BAA6B;iBACvC;aACD;SACD,CAAC;QAGF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,OAAO,EAAE,8DAA8D;gBACvE,GAAG,EAAE,OAAO;aACZ;SACD,CAAC;IACH,CAAC;CAAA;AA7CD,sCA6CC"}
+{"version":3,"file":"CloudinaryApi.credentials.js","sourceRoot":"","sources":["../../credentials/CloudinaryApi.credentials.ts"],"names":[],"mappings":";;;AAOA,MAAa,aAAa;IAA1B;QACC,SAAI,GAAG,eAAe,CAAC;QACvB,gBAAW,GAAG,gBAAgB,CAAC;QAC/B,qBAAgB,GAAG,iEAAiE,CAAC;QACrF,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;aACX;YACD;gBACC,WAAW,EAAE,SAAS;gBACtB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;aACX;YACD;gBACC,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;aAC/B;YACD;gBACC,WAAW,EAAE,aAAa;gBAC1B,IAAI,EAAE,YAAY;gBAClB,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,KAAK;gBACd,WAAW,EACV,2JAA2J;aAC5J;YACD;gBACC,WAAW,EAAE,0BAA0B;gBACvC,IAAI,EAAE,oBAAoB;gBAC1B,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,oBAAoB;gBACjC,WAAW,EACV,qIAAqI;gBACtI,cAAc,EAAE,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE;aAChD;SACD,CAAC;QAGF,iBAAY,GAAyB;YACpC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACX,IAAI,EAAE;oBACL,QAAQ,EAAE,0BAA0B;oBACpC,QAAQ,EAAE,6BAA6B;iBACvC;aACD;SACD,CAAC;QAGF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,OAAO,EAAE,8DAA8D;gBACvE,GAAG,EAAE,OAAO;aACZ;SACD,CAAC;IACH,CAAC;CAAA;AA/DD,sCA+DC"}

package/dist/nodes/Cloudinary/Cloudinary.node.d.ts

@@ -1,6 +1,5 @@
 import { INodeType, INodeTypeDescription, IExecuteFunctions, INodeExecutionData } from 'n8n-workflow';
 export declare class Cloudinary implements INodeType {
-    private static readonly CREDENTIAL_TYPE;
     description: INodeTypeDescription;
     execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
 }