nextcloud-collabora-nodered/docs/AGENT-MANUAL.md

# Agent manual — Nextcloud Collabora Node-RED nodes

For flow agents building automations on Nextcloud + Collabora CODE. You edit Node-RED flows, not LibreOffice macros in the browser. File I/O goes through WebDAV or OCS. Document conversion goes through CODE REST.

## Rules

1. Use **app passwords** in `nc-collab-config`. Never account passwords.
2. Do **not overwrite originals**. Default output: `/Dokument/OfficeOut/`.
3. `postMessage` and iframe APIs are browser-only — not Node-RED.
4. Save files with **WebDAV PUT**, not WOPI PutFile.
5. Do not expose port 9980 beyond loopback on the host.
6. Do not touch odds-scraper or unrelated services in flows.

## Environment

| Key | Value |
|-----|-------|
| Nextcloud | `https://cloud.example.com` |
| Existing Node-RED | `nextcloud-node-red` on `:1880` — Collabora nodes integrate here |
| Internal CODE | `https://172.17.0.2:9980` on Docker bridge (container `code`) |
| Auth | Basic + app password, header `OCS-APIRequest: true` |

See [INFRASTRUCTURE.md](INFRASTRUCTURE.md) for network layout.

## Nodes

Full reference: [NODES.md](NODES.md).

**Config:** one `nc-collab-config` per environment — all six flow nodes need it.

**Common msg fields:** `ncPath`, `fileId`, `payload`, `format`, `destNcPath`, `fields`, `transform`, `operation`.

**Prefer `collabora-bridge`** for everyday tasks (`ncFileToPdf`, `fillTemplateSave`). Use low-level `collabora-*` nodes when bridge is not enough.

## Example flows

### A. NC file → PDF

```
inject { ncPath: "/Documents/contract.docx" }
  → collabora-bridge (ncFileToPdf)
  → debug destNcPath
```

### B. Template fill

```
extractToPayload or template:extractFields
  → function (map data to fields)
  → fillTemplateSave or template:fillFields
```

### C. Open in browser

```
nc-office (document:direct) → debug editorUrl
```

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| ECONNREFUSED :9980 | Connect Node-RED to Docker bridge; use detected CODE IP |
| Empty convert response | Use HTTPS to internal CODE; check CODE is healthy |
| WebDAV 401 | New app password; same user as file path |
| WebDAV 404 | Leading slash on path; URL-encode segments |

## Acceptance criteria

- Test document converts to PDF under `/Dokument/OfficeOut/`
- Original unchanged
- Errors in `msg.error`, node status red — no silent failure

See also [NODES.md](NODES.md) for operation tables and examples.