n8n-nodes-nextlead

Community node for n8n that integrates NextLead CRM.

• npm: n8n-nodes-nextlead
• GitHub: CREACH-Agency/nextlead-n8n

Features

AI → Run is read-only by default. Writes require both the explicit Allow Mutations toggle and sufficient permissions for the member selected in Execute as User, whose role is enforced server-side.

Architecture

nodes/NextLead/
├── NextLead.node.ts          # Main node — resource router
├── NextLeadTrigger.node.ts   # Polling trigger node
├── core/
│   ├── NextLeadApiService.ts # HTTP client wrapping the NextLead REST API
│   ├── NextLeadErrorHandler.ts
│   ├── ResourceManager.ts    # Dispatches operations to the right resource
│   ├── interfaces/
│   │   └── IResourceStrategy.ts  # Strategy interface for each resource
│   └── types/
│       ├── NextLeadTypes.ts       # ResourceType / OperationType enums
│       ├── shared/ApiTypes.ts
│       └── api/                   # Typed API response shapes
├── resources/
│   ├── ContactResource.ts    # Implements IResourceStrategy for contacts
│   ├── StructureResource.ts
│   ├── SaleResource.ts
│   ├── ActionResource.ts
│   ├── GroupResource.ts
│   ├── ListResource.ts
│   ├── IdentifyResource.ts
│   ├── AiResource.ts
│   └── <resource>/
│       └── <Resource>Fields.ts   # n8n field definitions per resource
└── utils/
    ├── DateUtils.ts
    ├── FieldDefinitionUtils.ts    # Factories for the n8n field definitions
    ├── MetadataCache.ts           # Caches dropdown metadata calls
    ├── OperationHandlerUtils.ts
    ├── PollDedup.ts               # Deduplicates items across trigger polls
    ├── ResponseUtils.ts
    └── TeamMemberUtils.ts

credentials/
└── NextLeadApi.credentials.ts    # API key + domain credential

dist/   # Compiled output (git-ignored, generated by build)

Key design decisions

• Strategy pattern: each resource (ContactResource, SaleResource, …) implements IResourceStrategy. ResourceManager picks the right one at runtime based on the resource parameter, and scopes every field definition to its own resource.
• NextLeadApiService: thin wrapper around n8n's helpers.requestWithAuthentication, so auth headers are injected automatically from the stored credential.
• NextLeadErrorHandler: turns an API rejection into a NodeApiError that carries the server's own explanation rather than a generic HTTP message.

Local development

Prerequisites

• Node.js ≥ 20.15
• pnpm (npm install -g pnpm)
• A running n8n instance (local or Docker)

Install dependencies

pnpm install

Build

pnpm run build

Compiled files are output to dist/. The build runs the TypeScript compiler through n8n-node build, then copies the static assets (SVG icons, codex files).

Run against a live n8n (hot reload)

pnpm run dev

Starts an n8n instance on http://localhost:5678 with this package linked and reloaded on save.
This is the recommended way to test: neither the linter nor the compiler validates runtime
behaviour (API calls, date formats, dropdown loading).

Lint

pnpm run lint        # check
pnpm run lint:fix    # auto-fix

Format

pnpm run format

Test locally in n8n

Link the package into a local n8n install so changes are reflected immediately:

# In this repo
npm link

# In your n8n directory
npm link n8n-nodes-nextlead

Then restart n8n. The NextLead nodes will appear in the node picker.

Publishing to npm

Full step-by-step, including troubleshooting: RELEASE.md.

Publishing happens exclusively through GitHub Actions. n8n requires verified community
nodes to be published with an npm provenance statement, which proves the package was built
from this repository at this commit — an npm publish from a developer machine does not
produce that proof.

# On a clean `main`
pnpm run release

The command lints, builds, generates the changelog, prompts for the version, then commits and
pushes a vX.Y.Z tag. Pushing that tag triggers
.github/workflows/publish.yml, which runs
npm publish --provenance.

Only the dist/ folder is shipped (configured via "files" in package.json).

n8n community node requirements

• Package name must start with n8n-nodes-
• keywords must include "n8n-community-node-package"
• License must be MIT
• No runtime dependencies — only n8n-workflow as a peer dependency
• Published from a GitHub Action, with provenance

See the n8n verification guidelines for the full list.

Setup for end users

1. In n8n, go to Settings > Community Nodes and install n8n-nodes-nextlead.
2. Create a NextLead API credential:
   • API Key: found in NextLead under Settings > Automation > API Key
   • Domain: your NextLead instance URL
3. Add a NextLead node to your workflow and select a resource + operation.

Resources

• NextLead API documentation — the Developer space, reachable from the API Documentation button next to your automation key
• n8n community nodes docs
• n8n community forum

License

MIT — see LICENSE.md