# 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

51 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

| Node | Notes |
| --- | --- |
| **Respond to Webhook** | **Needs C++.** `webhook_controller` fires and forgets, so there is no way to return a computed body. Without it the GET/POST/PUT triggers cannot back a real API |
| **Database Change** | Poll a collection for new or changed documents. Pure JS over `storage.query` plus a stored cursor |
| **File Watch** | Poll a directory through `fs.stat`. Pure JS when paired with a schedule |
| **Queue / Manual Approval** | **Large.** Needs resumable executions; the engine currently runs a workflow to completion in one pass |

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.