# Nodes Worth Building

A shortlist of nodes this platform does not have yet, ordered by how much each
would change day-to-day use rather than by how interesting it is to write.

Everything here is a JavaScript file in `nodes/` unless marked **needs C++**.
The runner already exposes `http`, `storage` (including the file store),
`credentials`, `crypto`, `fs`, `process.exec`, `imap`, `smtp`, `mysql`,
`postgresql` and `utils` - see [nodes.md](nodes.md) for the full API.

## What exists today

56 node definitions across: triggers (click, get/post/put, imap, schedule with
cron and overlap control, error), flow control (if-condition, loop, wait), data
(rss-reader, the six storage nodes), email (four imap nodes plus smtp-send), AI
(ollama-chat, comfyui-prompt), integration (telegram-send, nextcloud-talk),
media (image, via ImageMagick), OCR (seven nodes), database (mysql, postgresql),
security (crypto), http (http-request) and developer (code).

## Tier 1 - data shaping and flow control

Built. `set-fields`, `switch`, `filter`, `merge`, `split-out`, `aggregate`,
`sort-limit-dedupe`, `template`, `json`, `datetime` and `stop-and-error` all
live in `nodes/core/`, with a verification case each under `tests/nodes/`.

Two platform changes came with them: a node may declare `dynamicOutputs` to grow
an output per config entry, which is how `switch` works, and `const inputs` is
now parsed, which is how `merge` gets two input handles.

## Tier 2 - triggers

Built. `respond-to-webhook`, `database-change`, `file-watch` and
`wait-for-approval` all live in `nodes/`, with fixtures under `tests/nodes/`.

Three platform changes came with them: `fs.readdir`, so a node can see what is
in a directory; a `_webhookResponse` marker any node can return to set the
status, headers and body a webhook replies with; and resumable executions - an
execution can pause on a `_pause` marker and be continued later through
`POST /api/v1/executions/{id}/resume`, rebuilt from the workflow snapshot stored
with it.

Two things the original entries claimed turned out not to hold. The webhook
controller never fired and forgot: it already waited for completion and returned
a body, and what was missing was control over the status code, the headers, and
which node decides the response. And File Watch could not be pure JavaScript,
because the filesystem API had no way to list a directory.

Cron and interval scheduling are already covered by `schedule-trigger`,
including its overlap policy.

## Tier 3 - integrations

All pure JavaScript over `http` and `credentials`, in the same shape as
`telegram-send`.

- **Nextcloud Files (WebDAV)** - upload, download, list, share. Note that
  `http.request` silently turns any method outside its list into GET
  (`src/runner/engine/script_engine.cpp`, `performHttpRequest`), so PROPFIND,
  MKCOL and MOVE need a small engine fix first. Worth doing regardless.
- **ntfy / Gotify** - self-hosted push, trivial
- **Discord / Slack / Matrix** - webhook POST nodes, trivial
- **Home Assistant** - REST plus a long-lived token
- **Paperless-ngx** - pairs directly with the OCR nodes
- **Immich / PhotoPrism** - pairs with the image pipeline
- **S3 / MinIO** - needs SigV4 signing, which `crypto.hmac` can carry. Medium
- **SFTP / FTP** - **needs C++**, though libcurl already speaks both
- **Redis**, **MongoDB** - **needs C++**, a client each

## Tier 4 - AI

- **OpenAI-compatible Chat** - one node covers OpenAI, OpenRouter, vLLM, LM
  Studio and llama.cpp. The most reach for the least work, built like
  `ollama-chat`
- **Embeddings + Vector Search** - store vectors in the database and do cosine
  search in JS, turning the database into a small RAG store
- **Speech to Text** - Whisper over HTTP
- **A1111 / Forge** - the same shape as `comfyui-prompt`, for people not running
  ComfyUI
- **ComfyUI Upload Image** - `comfyui-prompt` submits graphs but cannot push an
  input image to `/upload/image`, so image-to-image is out of reach

## Tier 5 - operations

- **Execute Sub-workflow** - **needs C++.** Call another workflow and use its
  result. The main thing standing between this and reusable building blocks
- **Execute Command** - wraps `process.exec` with arguments, a timeout and
  captured output
- **Sticky Note** - canvas annotation, WebUI only

## Where to start

Tier 1 is built, so the OpenAI-compatible chat node is what is left of the
original shortlist - one node covering OpenAI, OpenRouter, vLLM, LM Studio and
llama.cpp, built like `ollama-chat`.

Two entries are ranked below their worth, purely because they need engine work
rather than a JavaScript file: **Respond to Webhook** and **Execute
Sub-workflow**. For the platform to feel finished rather than merely
well-stocked, those matter more than any ten integrations.