n8n-nodes-layerproof

Community nodes for the LayerProof API.

Build

npm install
npm run build

Load the package with N8N_CUSTOM_EXTENSIONS pointing at this directory (absolute path), then restart n8n.

Creating nodes the n8n way

Follow n8n community nodes expectations: one INodeType class per file, description + runtime method (execute and/or supplyData), list compiled .js paths under package.json → n8n.nodes.

A. Programmatic node (main LayerProof pattern)

| Rule | Detail | |------|--------| | Class | export class … implements INodeType with description and async execute(this: IExecuteFunctions). | | description.name | Stable programmatic id (e.g. layerProof). n8n may prefix it as CUSTOM.layerProof in saved workflows. | | description.version | Integer or array; must match what workflows store as typeVersion. | | inputs / outputs | Use ["main"] or [NodeConnectionTypes.Main] — both resolve to connection type main. | | defaults.name | Short default label on canvas; keep distinct from displayName if you want. | | credentials | { name, required: true } aligned with the credential class file in n8n.credentials. | | properties | Order matters for UX: global Resource first, then per-resource Operation + fields. Every field that is not global must use displayOptions.show with resource / operation. | | execute | Use this.getInputData(), this.getNodeParameter(…, itemIndex), this.getCredentials(…), return INodeExecutionData[][]. Throw NodeOperationError for user-facing errors. |

New resource / operation: add operations + fields in src/nodes/LayerProof/resources/<resource>.ts, spread them into LayerProof.node.ts properties, then implement the branch in execute.

B. AI Tool node (LayerProof*Tool pattern)

Tools are nodes whose description exposes outputs containing NodeConnectionTypes.AiTool. That makes NodeHelpers.isTool(description, parameters) true and enables AI Agent / partial-execution tool wiring.

| Rule | Detail | |------|--------| | inputs | [] — tools are fed by the agent subgraph, not by a manual main input. | | outputs | [NodeConnectionTypes.AiTool] (optionally add outputNames: ['Tool'] like core tools). | | description.name | Unique camelCase id per tool (e.g. layerProofProjectGetTool); must match generated file / exports. | | execute | This repo implements execute and delegates to executeToolOperation → proxied LayerProof.execute. Official @n8n/n8n-nodes-langchain tools often use supplyData only (no execute); both patterns can work depending on n8n version — test on your target n8n release. | | Credentials | Same as main node (layerProofApi) so the tool calls the same API. | | Properties | Only parameters needed for that single operation; hide resource/operation in UI by fixing them in code (executeToolOperation forces resource / operation from the tool spec). |

Adding a tool in this repo:

1. Extend LayerProofToolSpec / generator inputs in toolFactory.ts if needed (e.g. toolUsageHints, readOnlyOperations).
2. Add a generated file under src/nodes/LayerProofTools/generated/ using createToolDescription(spec) + executeToolOperation(this, spec).
3. Append the compiled path to package.json → n8n.nodes.
4. npm run build and reload n8n with N8N_CUSTOM_EXTENSIONS.

UX: Connect the tool’s Ai tool output to an AI Agent (or compatible node). Standalone execution on the canvas is not the intended path.

C. package.json registration

• n8n.n8nNodesApiVersion: 1 unless n8n docs require a bump.
• n8n.credentials: paths to built credential files (dist/credentials/...).
• n8n.nodes: paths to every built node file (main + each tool). Missing entries → typeUnknown / workflow validation failures.

D. n8n library alignment notes

1. Pre-flight validation — Before any run, n8n calls NodeHelpers.getNodeParametersIssues on visible/required properties. Bugs there surface as WorkflowHasIssuesError, not as your execute code.
2. required: true inside collection → options — Avoid (see pitfalls below); validate in execute for that operation instead.
3. Built-in HTTP Tool uses supplyData + LangChain Tool objects; this package uses execute + shared LayerProof.execute for one implementation of all operations. If you hit agent/tool runner issues on a new n8n version, compare with the built-in tool node for that release.
4. Pin the n8n version you test against (CLI + N8N_CUSTOM_EXTENSIONS); validation and AI execution change between minors.

Debugging (how we traced WorkflowHasIssuesError)

Use this when the editor shows “The workflow has issues…” or logs report WorkflowHasIssuesError but do not name the broken field.

1. Verbose server logs

export N8N_LOG_LEVEL=debug
export N8N_CUSTOM_EXTENSIONS="/absolute/path/to/automation/n8n"
n8n start

You will see lifecycle lines (save execution, hooks, error-reporter). The generic message still will not list each invalid parameter — go to steps 2–3.

Optional: narrow scopes, e.g. export N8N_LOG_SCOPES=workflow-activation,waiting-executions (see n8n LoggingConfig).

2. Reproduce validation locally (fastest for custom nodes)

WorkflowHasIssuesError is thrown after checkReadyForExecution → NodeHelpers.getNodeParametersIssues. Run the same check in Node from this package after npm run build:

cd automation/n8n
node -e "
const { NodeHelpers } = require('n8n-workflow');
const { LayerProof } = require('./dist/nodes/LayerProof/LayerProof.node.js');
const desc = new LayerProof().description;
const node = {
  parameters: { resource: 'project', operation: 'list', limit: 20 },
  name: 'Test',
  type: 'CUSTOM.layerProof',
  typeVersion: 1,
};
console.log(JSON.stringify(NodeHelpers.getNodeParametersIssues(desc.properties, node, desc), null, 2));
"

• null → no parameter issues for that fake node (problem may be credentials, unknown type, or graph — not this check).
• Object with parameters → those keys are what n8n thinks are missing; fix properties or move required checks into execute (see pitfalls).

Match node.parameters to what the real workflow uses (copy from DB in step 3). For a tool, use new YourTool().description and the parameters that tool exposes.

3. Inspect the workflow and last run in SQLite (default local DB)

Default file: ~/.n8n/database.sqlite (path differs if you set N8N_USER_FOLDER / DB env).

# Workflow id from the URL or execution list
sqlite3 ~/.n8n/database.sqlite \
  "SELECT id, name FROM workflow_entity WHERE id = 'YOUR_WORKFLOW_ID';"

# Saved graph (may be older than the last execution snapshot)
sqlite3 ~/.n8n/database.sqlite \
  "SELECT nodes, connections FROM workflow_entity WHERE id = 'YOUR_WORKFLOW_ID';"

# Latest executions
sqlite3 ~/.n8n/database.sqlite \
  "SELECT id, status, stoppedAt FROM execution_entity WHERE workflowId = 'YOUR_WORKFLOW_ID' ORDER BY id DESC LIMIT 5;"

For a failed run, execution_data.workflowData is usually a plain JSON string of the workflow as executed (nodes + connections + settings). That is the best snapshot to compare with your local validation object:

sqlite3 ~/.n8n/database.sqlite \
  "SELECT workflowData FROM execution_data WHERE executionId = LAST_EXECUTION_ID;" | head -c 8000

Paste the relevant nodes[].parameters into the node -e snippet from step 2. The data column may use n8n’s compressed/dedup format; workflowData is easier to read.

4. Confirm in n8n source (optional)

In the n8n install you run (e.g. global node_modules/n8n):

• WorkflowHasIssuesError message text in n8n-core / errors/workflow-has-issues.error.js
• WorkflowExecute.checkForWorkflowIssues → checkReadyForExecution in n8n-core / execution-engine/workflow-execute.js

That ties the generic error to parameter validation, not necessarily to your execute body.

5. Canvas and graph issues

If validation is null but execution still fails with other errors (e.g. reading 'disabled'), check for stale connections (edge pointing to a deleted node name), wrong bookmarked workflow id after DB reset, or orphan connections vs nodes in exported JSON.

Pitfalls (lessons)

1. Do not use required: true on fields inside collection → options

getNodeParametersIssues may treat those nested options as top-level required for the entire node, so unrelated resources/operations fail with WorkflowHasIssuesError.

Do: omit required on nested options, or required: false, then enforce with NodeOperationError in the matching execute branch.

Example fixed (2026-04): Blog Post aiOperationFields options command / selection had required: true, which broke Project → List until fixed.

2. displayOptions.show must match the intended resource/operation

Otherwise fields leak into validation or the wrong operation’s UI.

3. Duplicate property name (e.g. operation) across resources

Allowed if each block is scoped with displayOptions.show.resource.

4. Verify parameter issues after editing properties

node -e "
const { NodeHelpers } = require('n8n-workflow');
const { LayerProof } = require('./dist/nodes/LayerProof/LayerProof.node.js');
const desc = new LayerProof().description;
const node = {
  parameters: { resource: 'project', operation: 'list', limit: 20 },
  name: 'Test',
  type: 'CUSTOM.layerProof',
  typeVersion: 1,
};
console.log(NodeHelpers.getNodeParametersIssues(desc.properties, node, desc));
"

Expect null. Any object with parameters keys will block execution in the editor the same way.

For a new tool, build a minimal node.parameters object for that tool’s visible fields and run the same check against new XxxTool().description.