284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
82 lines
6.2 KiB
Markdown
82 lines
6.2 KiB
Markdown
# Scratchpad — N8n Contact CRUD Node Expansion
|
|
|
|
- Plan slug: `n8n-contact-crud`
|
|
- Created: `2026-03-14`
|
|
|
|
## What This Is
|
|
|
|
Keep a lightweight, continuously-updated log of discoveries and decisions made while implementing this plan.
|
|
|
|
## Decisions
|
|
|
|
- (2026-03-14) First pass is ticket-style parity for contacts, but limited to CRUD only: `Create`, `Get`, `List`, `Update`, and `Delete`.
|
|
- (2026-03-14) Contact `Search` is explicitly out of scope for the first pass.
|
|
- (2026-03-14) First-pass field scope is limited to `full_name`, `email`, `client_id`, `role`, `notes`, `is_inactive`, and `phone_numbers`.
|
|
- (2026-03-14) `phone_numbers` will be exposed as a JSON-authored field in the n8n node instead of a more complex nested collection UI.
|
|
- (2026-03-14) Client selection for contacts should reuse the existing client lookup/manual UUID fallback pattern already used by ticket fields.
|
|
- (2026-03-14) This work should stay in the `n8n-nodes-alga-psa` package unless implementation uncovers an actual backend gap.
|
|
- (2026-03-14) Contact list stays limited to the agreed core filters (`client_id`, `search_term`, `is_inactive`) even though the API supports broader filtering; this keeps the first pass aligned with the PRD scope.
|
|
- (2026-03-14) Contact list pagination uses dedicated internal parameter names (`contactPage`, `contactLimit`) with the same user-facing labels (`Page`, `Limit`) to avoid conflicting duplicated node parameter names.
|
|
- (2026-03-14) The packaged contact example uses a `Create -> Update` flow so the README demonstrates both the new contact resource and how downstream nodes can consume the returned `contact_name_id`.
|
|
|
|
## Discoveries / Constraints
|
|
|
|
- (2026-03-14) The existing node implementation is concentrated in `packages/n8n-nodes-alga-psa/nodes/AlgaPsa/AlgaPsa.node.ts`; contact support should avoid turning that file into a second one-off monolith.
|
|
- (2026-03-14) The backend already exposes `POST/GET /api/v1/contacts` plus `GET/PUT/DELETE /api/v1/contacts/{id}` through `ApiContactController`.
|
|
- (2026-03-14) The contact API schema in `server/src/lib/api/schemas/contact.ts` confirms `phone_numbers` is an array of objects with required `phone_number` and optional `canonical_type`, `custom_type`, `is_default`, `display_order`, and `contact_phone_number_id`.
|
|
- (2026-03-14) The contact list API supports at least `client_id`, `search_term`, and `is_inactive`; broader filter exposure remains a product choice, not a technical blocker.
|
|
- (2026-03-14) The package already has strong test coverage patterns in `__tests__/node-description-loadoptions.test.ts`, `__tests__/node-execute.test.ts`, `__tests__/helpers.test.ts`, and `__tests__/docs.test.ts`; new coverage should extend those tests instead of adding a separate style.
|
|
- (2026-03-14) There is already a pre-plan design note at `docs/plans/2026-03-14-n8n-contact-crud-design.md`.
|
|
- (2026-03-14) The outer node execute loop already centralizes continue-on-fail error wrapping, so contact continue-on-fail support comes “for free” once contact operations throw the same normalized validation/API errors as ticket operations.
|
|
- (2026-03-14) `phone_numbers` validation now happens entirely in local helpers before request dispatch, covering malformed JSON, non-array values, missing `phone_number`, invalid optional UUIDs, non-boolean `is_default`, and negative/non-integer `display_order`.
|
|
|
|
## Commands / Runbooks
|
|
|
|
- (2026-03-14) Inspect node package surface:
|
|
- `rg -n "ticket|contact|n8n" packages/n8n-nodes-alga-psa -g '!**/dist/**'`
|
|
- (2026-03-14) Inspect contact API contract:
|
|
- `sed -n '1,260p' server/src/lib/api/schemas/contact.ts`
|
|
- `sed -n '1,260p' server/src/lib/api/controllers/ApiContactController.ts`
|
|
- `sed -n '1,260p' server/src/test/e2e/api/contacts.e2e.test.ts`
|
|
- (2026-03-14) Validate the plan after edits:
|
|
- `python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/validate_plan.py ee/docs/plans/2026-03-14-n8n-contact-crud`
|
|
- (2026-03-14) Validate the implemented contact node surface:
|
|
- `npm run typecheck`
|
|
- `npx vitest run --config vitest.config.ts __tests__/helpers.test.ts __tests__/node-description-loadoptions.test.ts __tests__/node-execute.test.ts`
|
|
- (2026-03-14) Final verification after docs/example updates:
|
|
- `npm test`
|
|
- `python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/validate_plan.py ee/docs/plans/2026-03-14-n8n-contact-crud`
|
|
|
|
## Links / References
|
|
|
|
- Design doc:
|
|
- `docs/plans/2026-03-14-n8n-contact-crud-design.md`
|
|
- Node package:
|
|
- `packages/n8n-nodes-alga-psa/nodes/AlgaPsa/AlgaPsa.node.ts`
|
|
- `packages/n8n-nodes-alga-psa/nodes/AlgaPsa/helpers.ts`
|
|
- `packages/n8n-nodes-alga-psa/nodes/AlgaPsa/transport.ts`
|
|
- `packages/n8n-nodes-alga-psa/README.md`
|
|
- `packages/n8n-nodes-alga-psa/RELEASE_NOTES.md`
|
|
- Existing tests:
|
|
- `packages/n8n-nodes-alga-psa/__tests__/node-description-loadoptions.test.ts`
|
|
- `packages/n8n-nodes-alga-psa/__tests__/node-execute.test.ts`
|
|
- `packages/n8n-nodes-alga-psa/__tests__/helpers.test.ts`
|
|
- `packages/n8n-nodes-alga-psa/__tests__/docs.test.ts`
|
|
- API contract:
|
|
- `server/src/lib/api/schemas/contact.ts`
|
|
- `server/src/lib/api/controllers/ApiContactController.ts`
|
|
- `server/src/app/api/v1/contacts/route.ts`
|
|
- `server/src/app/api/v1/contacts/[id]/route.ts`
|
|
|
|
## Progress Log
|
|
|
|
- (2026-03-14) Completed `F001` through `F023` and `T001` through `T033`.
|
|
- Added `Contact` resource and `contactOperation` selector to the node description.
|
|
- Added contact create/update/list parameter groups, `contactId`, client lookup reuse, and contact execute branches for `POST/GET/PUT/DELETE /api/v1/contacts` plus `GET /api/v1/contacts`.
|
|
- Added contact helper builders for create/update/list plus local `phone_numbers` parsing and validation.
|
|
- Extended node description, helper, and execute tests to cover resource exposure, payload/query construction, normalization, delete success objects, ID validation, and continue-on-fail behavior.
|
|
- (2026-03-14) Completed `F024` through `F026` and `T034` through `T037`.
|
|
- Updated the README operation matrix, contact field guidance, lookup behavior notes, and output expectations.
|
|
- Added `examples/create-update-contact.workflow.json` and referenced it from the README.
|
|
- Added a `0.3.0` release-note entry for the first-pass contact CRUD expansion and extended docs-sync tests.
|