# n8n integration

Source: `integrations/n8n-nodes-tricid/`. This is a community node package that follows n8n's
conventions: CommonJS output from `tsc`, an `n8n` manifest in `package.json`, the keyword
`n8n-community-node-package`, and **no runtime dependencies** (a requirement for verified nodes).

## Install
- **Self-hosted, from npm**: Settings → Community Nodes → Install → `n8n-nodes-tricid` (once it is published).
- **From this repo** (a pnpm workspace package):
  ```bash
  pnpm --filter n8n-nodes-tricid build && cd integrations/n8n-nodes-tricid && npm pack
  # in your n8n custom folder (~/.n8n/custom or N8N_CUSTOM_EXTENSIONS):
  npm install /path/to/n8n-nodes-tricid-0.1.0.tgz
  ```
  Then restart n8n.

## Credential "Tricid API"
| Field | |
|---|---|
| Base URL | e.g. `https://render.example.com` (no `/api/rest`) |
| API Token | Project API token (Studio → project → API tokens) |
| Webhook Secret | Optional; used by the Trigger in Manual mode (Automatic mode uses the subscription's own secret) |

The credential test calls `GET /api/rest/templates`.

## Node "Tricid"
| Resource | Operations |
|---|---|
| Image | **Create** (wait for completion), Get, Delete |
| PDF | **Create** (wait for completion), **Merge** (2 to 10 PDF URLs, `POST /api/rest/pdfs/merge`), Get, Delete |
| Video | **Create** (wait for completion), Get, Delete |
| Template | Get Many (List Templates; filters: title, tag, collection, order), Get, **Create** (blank: title + size, or From Template to duplicate; tags, custom data, collections), **Update** (title, tags, custom data), **Delete** |
| Media | Upload (binary property → URL for picture layers) |

**Create** works in two configuration modes:
- **Simple (Map Fields)**: pick a template ("From List" with search, or "By UUID"). The **Layers**
  resource mapper then loads the template's dynamic layers from `GET /api/rest/templates/{uuid}`. It has one
  field per layer × property, for example `TITLE › text` and `PIC › image`, with the main property shown and
  the rest addable. Empty fields keep the template default. In videos, text and image accept a JSON array
  such as `["One","Two"]`. PDFs and videos use one page or clip in this mode.
- **Advanced (JSON)**: image → the `layers` object; PDF → the `pages` array; video → the `clips` array,
  exactly as in the REST API (multi-page and multi-clip).

Options: Output Mode (Final / Preview; preview needs server support), Webhook URL, Passthrough,
Filename, Create Now, Width/Height, Image Format, DPI, Image Quality, FPS, Canvas Background, and
**Download File** (puts the file into binary `data`).

**Wait for Completion** (default on) polls with backoff (1 s → 5 s; videos 3 s → 10 s) for up to
*Wait Timeout* (default 300 s). It returns the finished job with `output_url`. A render that ends in `error`
fails the item with its error code (or is returned when "Continue On Fail" is set). Each create sends
`Idempotency-Key: n8n-<execution>-<node>-<item>`, so n8n's *Retry On Fail* returns the same job instead of
rendering, and charging, twice.

The node is `usableAsTool`, so n8n AI Agents can call it.

## Node "Tricid Trigger" (instant trigger)
Starts a workflow when a job is finished.

**Registration: Automatic (project webhook)** is the default.
- **Activation**: the node subscribes its production URL with `POST /api/rest/webhooks`. The events come
  from *Job Kinds* × *Statuses*, e.g. `image.finished`, `pdf.error`. It stores the subscription id and its
  signing secret, so the trigger receives **every matching job in the project** (REST, URL API, Studio,
  other workflows).
- **Deactivation**: it deletes the subscription.
- **Restart**: n8n checks the subscription still exists, and re-creates it if it does not.

Servers without project webhooks get a clear error asking you to switch to *Manual*.

**Registration: Manual** takes only the jobs created with this node's URL as `webhook_success` (the
Tricid node's *Webhook URL* option).

Options:
- Job Kinds (image / pdf / video)
- Statuses (finished / error)
- Verify Signature (default on)
  - Automatic mode: the subscription secret.
  - Manual mode: the credential's Webhook Secret.
  - 300 s replay window; 401 on mismatch.

Filtered-out deliveries are acknowledged (200) but do not start the workflow.
Output: the job object (with `output_mode` and `credits`), plus `kind`, `output_url`, `event` and `delivery_id`.

## Lint (n8n's official rules)
`pnpm --filter n8n-nodes-tricid lint` runs ESLint with the same configuration as n8n's verification scanner
(`@n8n/scan-community-package`):
- `@n8n/eslint-plugin-community-nodes` `recommended`;
- `eslint-plugin-n8n-nodes-base` `community` (package.json), `credentials` and `nodes`, with the scanner's own off-overrides.

It is clean. The scanner's offline tarball analysis (`analyzePackage` on the packed package) also **passes**. The
provenance and npm-registry steps of the scanner need a published package.

## Tests
`pnpm --filter n8n-nodes-tricid test` (29 tests). The package is part of the pnpm workspace, so
root `pnpm test` runs it too.
- Request building, resource-mapper fields, multipart, polling and signature checks.
- The node classes against a fake n8n context, including subscribe / check / unsubscribe and the manual fallback.

`pnpm --filter n8n-nodes-tricid build` compiles with `tsc`.
