Modular operations + Asset (asset_id) resource + tag Append mode

[eitanp461]

Summary

Restructures the Cloudinary node from a single monolithic execute() into a per-operation handler architecture, completes the per-asset CRUD lifecycle using Cloudinary's asset_id, and reorganizes the user-facing resource taxonomy so new workflows pick the safe path by default while saved workflows keep running unchanged.

This is the cumulative work on refactor/modular-operations-and-search — 10 commits — bundled into one review because the pieces are deeply interdependent (descriptor changes co-evolve with handler registrations, the taxonomy shift only makes sense once the new asset_id ops exist, and the test infrastructure rework underpins all of it).

Functional changes (what users see)

New resource: Asset (asset_id-based)

A clean, asset_id-keyed surface for everything per-asset. Operations:

• Get Asset — fetch a single asset by asset_id with optional info-rich flags (colors, faces, image_metadata, pHash, etc.).
• Update Asset Tags — with a new Mode selector (see below).
• Update Asset Structured Metadata — write key/value pairs to a metadata field.
• Update Asset Display Name — the rename users actually want under dynamic-folder mode (changes the human label, not the delivery URL).
• Delete Assets — bulk delete by public_id (Cloudinary's bulk endpoint is public_id-keyed; no asset_id variant exists).
• Search Assets — moved here from the Admin surface; supports pagination, custom expressions, and structured sort.

asset_id is a single immutable global key — callers don't need to juggle the (resource_type, type) coordinate pair that public_id-keyed endpoints require, which removes a whole class of silent no-op bugs (see "the type-field fix" below).

Reshaped resource taxonomy

The dropdown now reads, top to bottom:

1. Upload — Upload File, Upload From URL (unchanged).
2. Asset — the new asset_id resource above.
3. Library — account-level reads: Get Tags, Get Metadata Fields.
4. Asset (Legacy) — pinned to the bottom of the list. Exposes only the two operations that shipped on master (Update Asset Tags, Update Asset Structured Metadata) so existing workflows keep loading and running. Each operation's description is prefixed with a "Legacy form, public_id only" note pointing users at the new Asset resource.

Operation labels within every resource are alphabetized for predictability.

Update Asset Tags: Set vs Append modes

The single biggest behavioral fix. The pre-existing updateTags operation always replaced the tag list — many users expected it to add to existing tags and were silently losing data. The operation now has a Mode selector:

• Set (Replace All Existing Tags) — default. Preserves the pre-existing behavior exactly; no saved workflow changes meaning.
• Append (Add to Existing Tags) — hits Cloudinary's POST /:resource_type/tags with command=add and signed auth. Existing tags are preserved.

Append mode exposes a Type field (Upload / Private / Authenticated / Fetch) because the tag-action endpoint scopes lookups by (resource_type, type) and silently returns public_ids: [] for assets stored under a non-default type. The field label deliberately matches the type property on the Cloudinary asset object so users can copy the value straight from upstream JSON.

Present on both Asset and Asset (Legacy) resources, so the BC behavior is identical regardless of which surface a user picks.

Technical changes (what reviewers should look at)

Per-operation handler architecture

Replaces the previous monolithic execute() with:

• nodes/Cloudinary/operations/<resource>/<operation>.ts — one file per operation, each exporting an OperationHandler of signature (ctx, i, creds) => Promise<IDataObject[]> (operations/types.ts).
• nodes/Cloudinary/operations/index.ts — a flat ${resource}:${operation} → handler map.
• Cloudinary.node.ts:execute() — a thin loop over input items that resolves credentials once, looks up the handler, and wraps each returned IDataObject into an INodeExecutionData with the correct pairedItem.

Adding a new operation now means: drop a handler file, add a one-line entry to the map, and add the descriptor fields. No more touching a giant switch.

Two auth flows remain disjoint

The node mixes two Cloudinary auth styles depending on endpoint, and this PR keeps them strictly separated:

• HTTP Basic auth — Admin API and Update Asset endpoints. Passed via auth: { username, password } on IHttpRequestOptions.
• Signed Upload API — used by upload/* and now the new appendTags helper. Builds a params object, signs via generateCloudinarySignature (which correctly excludes api_key, file, and signature from the signed payload), and POSTs as application/x-www-form-urlencoded.

Append-tags is the only new code on the signed side. Shared helper at operations/tagAppend.ts is used by both asset:updateTags and updateAsset:updateTags.

Backwards compatibility

Every constraint from CLAUDE.md's "Backwards compatibility" section is respected:

• Every value string on updateAsset:* is preserved. Saved workflows that reference the legacy resource resolve unchanged.
• The new asset resource is net-new — no constraints to violate.
• The new Mode selector on Update Asset Tags defaults to set. Workflows saved before this PR have no stored tagMode → fall back to the default → identical request shape and identical behavior.
• The new Type field on Append mode defaults to upload — the same implicit value Cloudinary would have used pre-PR for any tag-append-style operation. (There was no append op before, so there's no behavior to preserve here, but the default still matches the most common case.)
• displayOptions.show clauses on existing fields are only loosened, never narrowed.
• displayName / description changes (Asset, Asset (Legacy), reorderings) are UI-only metadata, explicitly free-to-change per CLAUDE.md.

No typeVersion bump needed.

Test infrastructure

• Vitest, not Jest — n8n's ecosystem leans Jest but this package was already on Vitest and the convention is documented in CLAUDE.md.
• Shared mock builder at operations/testHelpers.ts (excluded from the build per tsconfig.json exclude so it doesn't leak vitest into the published package).
• vitest.config.ts aliases n8n-workflow to its built CJS entry (n8n-workflow/dist/index.js) — the package's import condition points at raw src/index.ts which Vitest can't load.
• 106 tests passing. Coverage spans signature generation, URL builders, error extraction, metadata serialization, and per-operation request-contract assertions (URL, method, auth shape, body shape) on the mocked HTTP helper.

The type-field fix worth surfacing explicitly

During end-to-end testing, an input batch where one asset was stored as type: "authenticated" and another as type: "upload" revealed that Cloudinary's tag-action endpoint silently returns public_ids: [] (HTTP 200, no error) when the type body parameter doesn't match the asset's storage type. The handler now reads a tagAppendType parameter and threads it into the signed body. Audited all other public_id-keyed operations — updateAsset:updateTags (set mode), updateAsset:updateMetadata, updateAsset:deleteAssets, and asset:deleteAssets — and all already include type in their requests. The asset_id-keyed operations are immune by design.

Out of scope (deferred to follow-up PRs)

• asset:moveAsset (dynamic-folder move via asset_folder).
• asset:renamePublicId (Upload API rename — changes delivery URLs, needs explicit user intent).
• Other delete variants (by prefix, by tag, by public_ids array).
• New entity resources (folder, metadataField, uploadPreset).
• typeVersion: 2 bump that mechanically retires the legacy updateAsset:* surface.
• A public_id → asset_id resolution op (Get-by-public_id) — closes a workflow ergonomics gap surfaced during testing.

Test plan

• npm test — 106/106 pass locally.
• npm run lint — clean.
• npm run build — clean; icons copied to dist/.
• npm run n8n-validate — community-package scan passes.
• Manual smoke in a local n8n instance:
  • Asset → Get Asset by asset_id returns the resource.
  • Asset → Update Asset Tags in Set mode replaces tags (existing BC).
  • Asset → Update Asset Tags in Append mode preserves existing tags.
  • Append mode against an authenticated-type asset succeeds when Type is set correctly; silently no-ops when left at the upload default (documents the failure mode).
  • Asset → Delete Assets removes the targeted public_ids.
  • Asset → Update Asset Display Name updates the human label without changing the delivery URL.
  • Asset (Legacy) → Update Asset Tags still works against public_id exactly as it did on master (load a saved workflow if available).
  • Library → Get Tags and Get Metadata Fields return account-level data.

🤖 Generated with Claude Code