n8n-nodes-cervio 0.0.0-stage → 0.2.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) Cervio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# n8n-nodes-cervio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Community node for [n8n](https://n8n.io/) that talks to a [Cervio](https://cervio.app) tenant over the public REST API (`/api/v1`).
+
+One node (**Cervio**) + one credential (**Cervio API**). Field lists come from the form write-schema (resource mapper), not free-form JSON. Marked `usableAsTool: true` for n8n AI Agent tools.
+
+| | |
+|--|--|
+| Package | `n8n-nodes-cervio` |
+| Version | see `package.json` / [Releases](https://github.com/cervio-app/n8n-nodes-cervio/releases) |
+| License | [MIT](./LICENSE.md) |
+
+## Quick start
+
+1. Create a PAT in Cervio **Admin → API** (see [Permissions](#permissions)).
+2. In n8n, add credential **Cervio API**:
+   - **Base URL** = tenant host only, e.g. `https://acme.cervio.app` (required; no default)
+   - **Personal Access Token** = `cpat_…`
+3. Drop a **Cervio** node and pick an operation.
+
+### Install (local / custom extensions)
+
+```bash
+git clone https://github.com/cervio-app/n8n-nodes-cervio.git
+cd n8n-nodes-cervio
+npm install && npm run build
+npm link
+
+mkdir -p ~/.n8n/custom && cd ~/.n8n/custom
+npm link n8n-nodes-cervio
+```
+
+Restart n8n. Or run a disposable n8n against this folder:
+
+```bash
+npm run build
+docker compose up
+# → http://localhost:5678  (N8N_CUSTOM_EXTENSIONS mounts this repo)
+```
+
+### Cover / demo screenshot
+
+Import a 2-node workflow (Manual Trigger → Cervio), attach your credential, pick Entity/View (or Form), zoom the canvas, screenshot:
+
+| File | Use |
+|------|-----|
+| [`examples/cover-demo.workflow.json`](./examples/cover-demo.workflow.json) | **List view** — clean cover (recommended) |
+| [`examples/cover-demo-create.workflow.json`](./examples/cover-demo-create.workflow.json) | **Create** — shows the guided field mapper |
+
+In n8n: **⋯ → Import from File** → select the JSON → set **Cervio API** credential → choose Entity + View/Form.
+
+## Operations
+
+| Group | Operation (`value`) | API (summary) | Typical scopes |
+|-------|---------------------|---------------|----------------|
+| Records | `create` | `POST …/entities/{id}/records` | `records:write` |
+| | `update` | `PATCH …/records/{id}` (+ optional `multi_value_modes`) | `records:write` |
+| | `get` | `GET …/records/{id}` | `records:read` |
+| | `delete` | `DELETE …/records/{id}` (soft) | `records:write` |
+| | `upsert` | `POST …/records/upsert` (`match_field`) | `records:write` |
+| | `validateDraft` | `POST …/forms/{name}/validate-draft` | `records:write`¹ |
+| | `listView` | `GET …/views/{id}/records` (cursor pages) | `records:read` |
+| | `listRecords` | `GET …/entities/{id}/records` (`filter[f]=eq.x`, **admin**) | `records:read` + `system_admin` |
+| Relations | `searchRelation` | `GET …/relation-options?q=&limit=` | `records:read` |
+| | `resolveRelation` | `POST …/resolve` | `records:read` |
+| | `linkRecords` / `unlinkRecords` | `POST`/`DELETE …/fields/{through}/links` | `records:write` |
+| Documents | `listDocuments` | `GET …/documents` | `records:read` |
+| | `uploadDocument` | `POST …/documents` (multipart / binary) | `records:write` |
+| | `openDocument` | `GET …/documents/{id}/open` → `signed_url` | `records:read` |
+| | `generateDocument` | `POST …/documents/generate` | `admin:write` + `system_admin` |
+| Workflows | `startWorkflow` | `POST …/workflows/{id}/runs` | `records:write` + trigger ACL |
+| | `getWorkflowRun` | `GET …/admin/workflows/{id}/runs/{runId}` | `admin:read` + `system_admin` |
+
+¹ Route uses the write-scope guard; dry-run does not persist.
+
+**Notes**
+
+- Create / Update / Upsert / Validate draft: pick **Entity** → **Form**, then the resource mapper.
+- N:M **through** fields are not on the mapper — use **Link / Unlink** (or Create on the junction entity).
+- Relation dropdowns are capped (~50); use **Search relation** for larger sets.
+- List view defaults: options = slugs, relations = uuids (ready for Update).
+- Generate document: paste a mapped **template UUID** (no public template catalog in v1 yet).
+
+## Permissions
+
+There is **no n8n-specific ACL** in Cervio. The node is a REST client; Cervio applies **two layers**. Both must allow the call.
+
+```text
+n8n  ──Bearer cpat_…──►  1) PAT scopes (Admin → API)
+                              │  fail → 401 / scope error
+                              ▼
+                         2) User who owns the PAT (same ACL as UI)
+                              │  fail → 403 / 404 / empty / validation
+```
+
+### Layer 1 — Token scopes
+
+| Scope | Opens (in this node) |
+|-------|----------------------|
+| `records:read` | Get, List view/records, Search/Resolve relation, List/Open documents |
+| `records:write` | Create, Update, Delete, Upsert, Validate draft, Upload, Link/Unlink, Start workflow |
+| `admin:read` | Form / view / workflow **dropdowns**, Get workflow run |
+| `admin:write` | Generate document from template |
+
+`*:write` implies the matching `*:read`. Scopes alone do **not** grant row access or `can_create`.
+
+### Layer 2 — User behind the PAT
+
+The PAT impersonates its owner. Entity permissions, record policies, field denials, form/view assignments, document capabilities, and manual-workflow trigger roles still apply — same as the UI.
+
+Example: PAT has `records:write` but the user has no `can_create` on the entity → **Create fails**.
+
+| Setup | PAT owner | Scopes |
+|-------|-----------|--------|
+| Full guided UX (all pickers, generate, run status, List records) | `system_admin` | `admin:read`, `admin:write`, `records:read`, `records:write` |
+| Narrow sync via assigned views/forms | Service user with that ACL | `records:read` / `records:write` only; prefer **List view**; paste ids if you skip admin pickers |
+
+## Repository layout
+
+```text
+credentials/          Cervio API credential + icons
+nodes/Cervio/         Node implementation, helpers, icons, unit tests
+  __tests__/          Vitest (write-schema → resource mapper)
+examples/             Importable demo workflows (cover screenshots)
+scripts/              build helpers + live smoke (optional)
+.github/workflows/    CI + npm publish (dispatch until Trusted Publishing)
+compose.yaml          Local n8n with this package mounted
+Dockerfile            Optional image that bakes the node into n8n
+types/                Ambient stubs for n8n-workflow (compile without native deps)
+```
+
+Published npm package contents: `dist/` only (`package.json` → `files`).
+
+## Development
+
+```bash
+npm install
+npm run build    # tsc + copy icons
+npm test         # unit tests
+npm run verify   # load compiled node + credential offline
+npm run lint     # tsc --noEmit
+```
+
+Conventions, SemVer tags (`vX.Y.Z`), and npm publish: [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+### Live smoke (optional)
+
+Against a real tenant (copy [`.env.example`](./.env.example)):
+
+```bash
+export CERVIO_BASE_URL=https://YOUR_TENANT.cervio.app
+export CERVIO_PAT=cpat_…
+npm run smoke            # create / list view / update
+npm run smoke:extended   # get, upsert, resolve, upload/open, N:M link, workflows
+npm run smoke:relations  # heavier relation/multivalue lab fixtures
+```
+
+| Script | Notes |
+|--------|--------|
+| `smoke:extended` | Requires Wave B routes on the tenant. Unlink needs the PAT junction-listing fix on Cervio. Generate skips without a real template id. Start workflow skips without manual-trigger ACL. |
+| `CERVIO_SMOKE_KEEP=1` | Leave created records |
+| `CERVIO_SMOKE_DELETE_ID` | Also soft-delete another disposable id |
+
+## Known limits
+
+- **List records** without a view is admin-only — partners should use **List view**
+- Nested child create = two Creates (parent, then child with FK)
+- Lookup-only view columns are labels, not UUIDs — use Search relation / Get for ids
+- List view “all pages”: max 10 × 500 rows
+
+## References
+
+- [Cervio](https://cervio.app)
+- Tenant OpenAPI: `public/openapi/v1.yaml` in the Cervio app repo
+- [n8n community nodes](https://docs.n8n.io/integrations/community-nodes/)
+- [Building community nodes](https://docs.n8n.io/integrations/community-nodes/building-community-nodes/)

package/dist/credentials/CervioApi.credentials.d.ts

@@ -0,0 +1,10 @@
+import type { IAuthenticateGeneric, Icon, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class CervioApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    icon: Icon;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}

package/dist/credentials/CervioApi.credentials.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CervioApi = void 0;
+class CervioApi {
+    constructor() {
+        this.name = 'cervioApi';
+        this.displayName = 'Cervio API';
+        this.icon = {
+            light: 'file:cervio.mono.light.svg',
+            dark: 'file:cervio.mono.dark.svg',
+        };
+        this.documentationUrl = 'https://github.com/cervio-app/n8n-nodes-cervio#readme';
+        this.properties = [
+            {
+                displayName: 'Base URL',
+                name: 'baseUrl',
+                type: 'string',
+                default: '',
+                placeholder: 'https://tenant.cervio.app',
+                required: true,
+                description: 'URL dell’istanza Cervio del tenant, senza slash finale (es. https://acme.cervio.app). Va impostata per ogni credenziale.',
+            },
+            {
+                displayName: 'Personal Access Token',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                placeholder: 'cpat_…',
+                description: 'Token creato in Admin → API. Consigliato: admin:read + admin:write + records:read + records:write (system_admin) per tendine, workflow, generate documento e scritture.',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Accept: 'application/json',
+                    Authorization: '=Bearer {{$credentials.apiKey}}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.baseUrl}}',
+                url: '/api/v1/me',
+            },
+        };
+    }
+}
+exports.CervioApi = CervioApi;
+//# sourceMappingURL=CervioApi.credentials.js.map

package/dist/credentials/CervioApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CervioApi.credentials.js","sourceRoot":"","sources":["../../credentials/CervioApi.credentials.ts"],"names":[],"mappings":";;;AAQA,MAAa,SAAS;IAAtB;QACC,SAAI,GAAG,WAAW,CAAC;QAEnB,gBAAW,GAAG,YAAY,CAAC;QAE3B,SAAI,GAAS;YACZ,KAAK,EAAE,4BAA4B;YACnC,IAAI,EAAE,2BAA2B;SACjC,CAAC;QAEF,qBAAgB,GAAG,uDAAuD,CAAC;QAE3E,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,UAAU;gBACvB,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,2BAA2B;gBACxC,QAAQ,EAAE,IAAI;gBACd,WAAW,EACV,0HAA0H;aAC3H;YACD;gBACC,WAAW,EAAE,uBAAuB;gBACpC,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,QAAQ;gBACrB,WAAW,EACV,yKAAyK;aAC1K;SACD,CAAC;QAEF,iBAAY,GAAyB;YACpC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACX,OAAO,EAAE;oBACR,MAAM,EAAE,kBAAkB;oBAC1B,aAAa,EAAE,iCAAiC;iBAChD;aACD;SACD,CAAC;QAEF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,OAAO,EAAE,2BAA2B;gBACpC,GAAG,EAAE,YAAY;aACjB;SACD,CAAC;IACH,CAAC;CAAA;AApDD,8BAoDC"}

package/dist/credentials/cervio.mono.dark.svg

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 60 60" width="60" height="60">
+  <g transform="translate(8.355,16.62)">
+    <path fill="#e2e2e2" d="M17.99,14.53c.54-.36,1.01-.56,1.25-.66.76-.3,1.59-.47,2.46-.47h19.63c1.08,0,1.96-.88,1.96-1.96V1.96c0-1.09-.88-1.96-1.96-1.96h-14.86c-.66,0-1.29.13-1.87.36-.18.07-.54.23-.95.5-.09.06-.43.29-.77.63-.51.51-.77.99-1.09,1.61-.05.09-.44.84-.87,1.69-.34.66-.71,1.38-.97,1.91-.65,1.27-1.28,2.47-1.35,2.6-.42.81-.76,1.45-1.43,2.12-.45.45-.9.75-1.02.83-.54.36-1.01.56-1.25.66-.76.3-1.59.47-2.46.47H1.97s0,0,0,0,0,0,0,0c-1.08,0-1.96.88-1.96,1.96v9.45c0,1.08.86,1.95,1.93,1.96,0,0,.02,0,.03,0s.02,0,.03,0h5.69c.66,0,1.29-.13,1.87-.36.18-.07.54-.23.95-.5.09-.06.43-.29.77-.63.51-.51.77-.99,1.09-1.61.06-.11.61-1.18,1.15-2.23.15-.3.3-.6.44-.87.73-1.43,1.51-2.93,1.59-3.09.42-.81.76-1.45,1.43-2.12.45-.44.9-.75,1.02-.83Z"/>
+    <path fill="#e2e2e2" d="M43.29,18.55c0-1.08-.87-1.95-1.95-1.95h-18.65c-.66,0-1.29.13-1.87.36-.18.07-.54.23-.95.5-.09.06-.43.29-.77.63-.51.51-.77.99-1.09,1.61-.11.21-2.01,3.86-2.18,4.3-.04.11-.07.22-.07.22-.03.12-.09.32-.09.59,0,.54.22,1.02.57,1.38.35.35.84.57,1.38.57h23.72c1.07,0,1.95-.87,1.95-1.95,0,0,0,0,0,0v-6.26s0,0,0,0Z"/>
+  </g>
+</svg>

package/dist/credentials/cervio.mono.light.svg

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 60 60" width="60" height="60">
+  <g transform="translate(8.355,16.62)">
+    <path fill="#333333" d="M17.99,14.53c.54-.36,1.01-.56,1.25-.66.76-.3,1.59-.47,2.46-.47h19.63c1.08,0,1.96-.88,1.96-1.96V1.96c0-1.09-.88-1.96-1.96-1.96h-14.86c-.66,0-1.29.13-1.87.36-.18.07-.54.23-.95.5-.09.06-.43.29-.77.63-.51.51-.77.99-1.09,1.61-.05.09-.44.84-.87,1.69-.34.66-.71,1.38-.97,1.91-.65,1.27-1.28,2.47-1.35,2.6-.42.81-.76,1.45-1.43,2.12-.45.45-.9.75-1.02.83-.54.36-1.01.56-1.25.66-.76.3-1.59.47-2.46.47H1.97s0,0,0,0,0,0,0,0c-1.08,0-1.96.88-1.96,1.96v9.45c0,1.08.86,1.95,1.93,1.96,0,0,.02,0,.03,0s.02,0,.03,0h5.69c.66,0,1.29-.13,1.87-.36.18-.07.54-.23.95-.5.09-.06.43-.29.77-.63.51-.51.77-.99,1.09-1.61.06-.11.61-1.18,1.15-2.23.15-.3.3-.6.44-.87.73-1.43,1.51-2.93,1.59-3.09.42-.81.76-1.45,1.43-2.12.45-.44.9-.75,1.02-.83Z"/>
+    <path fill="#333333" d="M43.29,18.55c0-1.08-.87-1.95-1.95-1.95h-18.65c-.66,0-1.29.13-1.87.36-.18.07-.54.23-.95.5-.09.06-.43.29-.77.63-.51.51-.77.99-1.09,1.61-.11.21-2.01,3.86-2.18,4.3-.04.11-.07.22-.07.22-.03.12-.09.32-.09.59,0,.54.22,1.02.57,1.38.35.35.84.57,1.38.57h23.72c1.07,0,1.95-.87,1.95-1.95,0,0,0,0,0,0v-6.26s0,0,0,0Z"/>
+  </g>
+</svg>

package/dist/nodes/Cervio/Cervio.node.d.ts

@@ -0,0 +1,20 @@
+import type { IExecuteFunctions, ILoadOptionsFunctions, INodeExecutionData, INodePropertyOptions, INodeType, INodeTypeDescription, ResourceMapperFields } from 'n8n-workflow';
+export declare class Cervio implements INodeType {
+    description: INodeTypeDescription;
+    methods: {
+        loadOptions: {
+            getEntities(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getForms(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getViews(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getRelationFields(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getThroughFields(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getMatchFields(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getWorkflows(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+        };
+        resourceMapping: {
+            getFormFieldsCreate(this: ILoadOptionsFunctions): Promise<ResourceMapperFields>;
+            getFormFieldsUpdate(this: ILoadOptionsFunctions): Promise<ResourceMapperFields>;
+        };
+    };
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}