n8n registry/UI install compatibility

Step 12B hardens the package for npm registry publication and n8n Community Nodes UI installation. The package keeps the npm identity n8n-nodes-invoicerouter@2.1.3, keeps n8n-community-node-package in keywords, removes the install-time n8n-workflow peer dependency risk, and ships a diagnostic script for manual fallback installs.

The n8n editor display names are now prefixed for searchability:

| Search term | Nodes shown |
|—|—|
| InvoiceRouter | all eight custom nodes |
| InvoiceRouter Invoice Sender | sender node |
| InvoiceRouter Request Builder | request builder node |
| InvoiceRouter Provider Loader | provider loader node |

Preferred production install path after npm publish:

n8n Community Nodes UI -> install package: n8n-nodes-invoicerouter

Manual .tgz install remains a fallback only. If used, run the packaged diagnostic from the same n8n runtime/container after installation:

node ~/.n8n/nodes/nodemodules/n8n-nodes-invoicerouter/scripts/diagnose-n8n-package.mjs ~/.n8n/nodes/nodemodules/n8n-nodes-invoicerouter

See InvoiceRouter Version 1 architecture

Manual Trigger
  ├─> Google Sheets: Provider Accounts/Credentials -> Provider Loader ─┐
  ├─> Google Sheets: Email List -> Email List -------------------------┼─> Provider Selector
  └─> Invoice Template ------------------------------------------------┘
Provider Selector allocation ----
Invoice Template -------------------> Request Builder
One normalized recipient ---------/
Request Builder -> Invoice Sender -> Status Checker -> Status Manager
                                                       ├─ workflow result
                                                       ├─ retry queue event
                                                       ├─ metrics/analytics events
                                                       ├─ alert/audit events
                                                       ├─ provider feedback/state update
                                                       └─ Prepare Status Writeback Row -> Google Sheets: invoice_results

The canonical master workflow is included at:

workflows/InvoiceRouter-v2-master-universal.json

The v1 and v1.6 workflow files remain packaged as compatibility/reference templates and are not removed.

Custom nodes

| # | Node | Responsibility |
|—|—|—|
| 1 | InvoiceRouter Provider Loader | Validates Google Sheets provider rows, creates the frozen providers[] structure, stores runtime secrets in an in-process vault, and masks visible credentials. |
| 2 | InvoiceRouter Provider Selector | Maintains provider state, selects an eligible account, applies rate limits/circuit-breaker rules, and creates lock metadata. |
| 3 | InvoiceRouter Invoice Template | Builds fixed invoice fields, repeatable line items, totals, payment terms, custom fields, and dynamic tag definitions. |
| 4 | InvoiceRouter Email List | Validates recipients, removes duplicate emails, generates missing names, preserves custom columns, and reserves each email once per batch. |
| 5 | InvoiceRouter Request Builder | Merges exactly one account + one template + one recipient, resolves dynamic tags, applies provider presets, validates send readiness, and creates one idempotent ready request. |
| 6 | InvoiceRouter Invoice Sender | Resolves runtime credentials, enforces activation/duplicate/bulk gates, executes provider lifecycle stages, uses the Odoo send wizard for invoice email, records provider evidence, and resumes approved post/email retries against the existing invoice. |
| 7 | InvoiceRouter Status Checker | Analyzes provider and lifecycle evidence, distinguishes success/partial/failure outcomes, classifies errors, and emits a standard status object. |
| 8 | InvoiceRouter Status Manager | Applies retry policy, creates approved lifecycle-resume requests, emits truthful bulk counters and management events, and produces normalized execution-log/writeback payloads. |

Manual Trigger and Google Sheets are built-in n8n nodes and are not part of this package.

n8n node icons and cards

All eight custom InvoiceRouter nodes declare polished SVG runtime icons through n8n’s description.icon field. The build copies each SVG into the matching dist/nodes// directory so the packaged node card in the n8n editor can resolve its icon beside the compiled node file.

The runtime SVGs are hand-authored vector interpretations of the existing Version 1.0 node-card motif: purple rounded cards, side connector dots, bottom status pills, and node-specific invoice/provider/status symbols. They intentionally avoid text initials so the n8n node list does not depend on font rendering.

Processing modes

Provider Selector offers two modes plus optional per-item conditional routing:

Conditional routing

Provider Selector can also route each recipient through conditional routing before it allocates an account. It evaluates optional Routing Rules JSON first, then falls back to per-recipient fields such as:

| Email List column | Runtime path | Purpose |
|—|—|—|
| Provider | recipient.customFields.Provider | Selects the provider profile, for example Stripe or Custom. |
| Action | recipient.customFields.Action | Selects the account/action profile, for example Create Invoice. |
| Environment | recipient.customFields.Environment | Selects sandbox or live. |

When Require Conditional Match is enabled, any recipient without a matching rule or routing fields is returned as BLOCKED; Request Builder and Invoice Sender will not create or send an HTTP request for that item.

Sequential — default

Best for Version 1 and beginners. Multiple recipients may reuse the same account because Invoice Sender processes items in order. This is the default in the bundled workflow.

Parallel locks

Keeps each account locked until Status Manager feedback. Use this only when running controlled parallel workers with enough provider accounts. Unavailable work items are marked QUEUED rather than being sent with the wrong account.

Credential model and security boundary

Version 1 intentionally stores provider API keys/secrets in Google Sheets so many changing accounts can be managed without editing n8n credentials individually.

Provider Loader:

Important boundary: the built-in Google Sheets node receives the original row before Provider Loader runs. In production:

1. Keep the spreadsheet private and use least-privilege Google access.
2. Do not commit real credentials to GitHub.
3. Disable or minimize successful execution-data retention in n8n.
4. Restrict access to workflow executions and logs.
5. Rotate credentials with awareness that Google Sheet revision history may retain previous values.
6. Start with Dry Run enabled and test provider sandboxes before live use.

Install from source

Use Node.js 24 for the supported build environment.

npm ci
npm run verify
npm pack

For a typical self-hosted n8n installation:

mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install /absolute/path/n8n-nodes-invoicerouter-1.6.0.tgz

Restart n8n after installation.

Import and configure the workflow

workflows/InvoiceRouter-v1-production.json is a production-shaped template. It is intentionally inactive, uses placeholder spreadsheet and credential IDs, and keeps Invoice Sender → Dry Run enabled.

1. Import workflows/InvoiceRouter-v1-production.json in n8n.
2. Copy the reference workbook into a private Google Sheet.
3. Keep only the provider rows you are actively testing enabled.
4. Replace every demo value required by that provider/action/environment.
5. Open Google Sheets – Provider Accounts and replace the provider spreadsheet ID.
6. Open Google Sheets – Email List and replace the recipient spreadsheet ID.
7. Select your Google Sheets OAuth2 or Service Account credential.
8. Configure Provider Selector deliberately:
– keep environmentFilter explicit; the bundled workflow defaults to sandbox for Dry Run validation, and live must be selected only after sandbox approval;
– either use static providerFilter/actionFilter during single-provider onboarding, or use Conditional Routing with recipient columns/rules;
– the bundled workflow enables Conditional Routing and Require Conditional Match, so missing routes become BLOCKED.
9. Keep Request Builder → Send Guard Mode set to Strict.
10. Keep Request Builder → Idempotency Key Mode set to Provider + Invoice + Recipient unless a reviewed provider-specific reason requires a narrower key.
11. Keep Invoice Sender → Require Send Guard enabled.
12. Keep Invoice Sender → Prevent Duplicate Sends enabled.
13. Keep Status Manager → Respect Provider Retry-After enabled and Retry Max Delay capped for production safety.
14. Keep Invoice Sender → Dry Run enabled.
15. For the first import/run test, use examples/n8ndryrun_validation/ and confirm the expected outcomes in expected-dry-run-outcomes.json.
16. Execute the workflow manually and inspect Provider Loader, Provider Selector, Request Builder, Invoice Sender, Status Checker, and Status Manager output.
17. Configure required provider-specific IDs through custom fields or the Sheet’s Extra Value field.
18. Confirm the invoice ID strategy is stable enough for duplicate prevention.
19. Keep Invoice Sender Activation Safety Mode on dryRunValidation until the n8n dry-run validation package passes.
20. For a real provider sandbox send, set Activation Safety Mode to sandboxRealSend, disable Dry Run, keep routing on sandbox, and enter SENDSANDBOXINVOICES.
21. For a real provider live send, set Activation Safety Mode to liveRealSend, route only live rows, and enter SENDREALINVOICES only after sandbox evidence is accepted.
22. Activate a scheduled/webhook copy only after the manual workflow is stable.

A real invoice-send run is not approved until all setup gates in 10FREEZE.md”>VERSION10FREEZE.md
2. CONTRACTS.md”>docs/freeze/v1.0/NODECONTRACTS.md
4. DECISION.md”>docs/freeze/v1.0/SECURITYDECISION.md
6. DRYRUNVALIDATION.md”>docs/freeze/v1.0/N8NDRYRUNVALIDATION.md
8. REQUESTRESPONSEMAPPING.md”>docs/freeze/v1.0/PROVIDERREQUESTRESPONSEMAPPING.md
10. LIVEACTIVATION.md”>docs/freeze/v1.0/SANDBOXLIVEACTIVATION.md
12. docs/developer/odoo-email-evidence-contract.md.