PSA/ee/docs/plans/2026-03-14-n8n-contact-crud/PRD.md

# PRD — N8n Contact CRUD Node Expansion

- Slug: `n8n-contact-crud`
- Date: `2026-03-14`
- Status: Draft

## Summary
Expand the `Alga PSA` n8n community node so automation builders can work with contacts directly, not just tickets and lookup resources. The first pass adds a first-class `Contact` resource with `Create`, `Get`, `List`, `Update`, and `Delete` operations, and matches the current ticket node’s ergonomics for field grouping, validation, normalized output, and continue-on-fail behavior.

## Problem
The current `n8n-nodes-alga-psa` package exposes ticket CRUD plus helper lookup resources, but it does not expose contact CRUD. Teams building Alga PSA automations in n8n cannot create or maintain contacts without falling back to generic HTTP nodes, hand-rolled request payloads, and manual error handling.

That gap creates three problems:
- Contact workflows are inconsistent with ticket workflows in the same package.
- Users lose the package’s built-in lookup, validation, and output normalization behavior.
- Common automations such as “create contact from form submission” or “update a contact before creating a ticket” require lower-level API wiring than they should.

## Goals
1. Add `Contact` as a first-class resource in the `Alga PSA` n8n node.
2. Support contact `Create`, `Get`, `List`, `Update`, and `Delete`.
3. Mirror the ticket node’s editor conventions: separate required and optional fields, manual UUID fallback for lookups, normalized success output, and continue-on-fail support.
4. Limit the first pass to core contact fields already supported by the current API contract.
5. Update examples, README, release notes, and package tests so the feature is complete and publishable.

## Non-goals
- No `Contact -> Search` operation in this pass.
- No attempt to expose the full contact schema on day one.
- No backend API changes unless implementation discovers an actual API gap.
- No full resource-registry rewrite for the n8n package.
- No new credential model or authentication behavior.

## Users and Primary Flows
- n8n workflow builder:
  - Selects `Contact` as the resource.
  - Creates a contact from upstream automation data.
  - Lists contacts with filters for downstream branching or enrichment.
  - Fetches, updates, or deletes a contact by ID.

- Existing Alga PSA node user:
  - Expects contact operations to feel like ticket operations.
  - Reuses `Client` lookup behavior when setting `client_id`.
  - Expects list responses and error objects to follow the package’s current conventions.

## UX / UI Notes
- Add `Contact` to the resource selector beside `Ticket`, `Client`, `Board`, `Status`, and `Priority`.
- When `Contact` is selected, show a dedicated `contactOperation` selector.
- Use ticket-style field organization:
  - required top-level fields for `Create`
  - optional “additional fields” collections for `Create` and `Update`
  - dedicated ID field for `Get`, `Update`, and `Delete`
  - dedicated pagination/filter fields for `List`
- `client_id` should use the same `resourceLocator` pattern as ticket references:
  - `From List`
  - `By ID`
- `phone_numbers` should be authored as JSON in the first pass rather than as a nested collection UI.
- Do not expose a contact search operation in the first pass.

## Requirements

### Functional Requirements
- FR-01: The node resource selector includes `Contact`.
- FR-02: The node exposes `Contact` operations: `Create`, `Get`, `List`, `Update`, and `Delete`.
- FR-03: `Contact -> Create` requires `full_name`.
- FR-04: `Contact -> Create` supports optional `email`, `client_id`, `role`, `notes`, `is_inactive`, and `phone_numbers`.
- FR-05: `Contact -> Update` supports optional `full_name`, `email`, `client_id`, `role`, `notes`, `is_inactive`, and `phone_numbers`.
- FR-06: `client_id` input for contact create/update supports both lookup mode and manual UUID mode.
- FR-07: `Contact -> Get`, `Update`, and `Delete` validate `contactId` before making a request.
- FR-08: `Contact -> List` supports pagination and core filters needed for practical automation: `page`, `limit`, `client_id`, `search_term`, and `is_inactive`.
- FR-09: Contact create requests send `POST /api/v1/contacts` with a compact payload that omits empty values.
- FR-10: Contact get requests send `GET /api/v1/contacts/{id}`.
- FR-11: Contact list requests send `GET /api/v1/contacts` and preserve pagination metadata in node output.
- FR-12: Contact update requests send `PUT /api/v1/contacts/{id}` with only provided fields.
- FR-13: Contact delete requests send `DELETE /api/v1/contacts/{id}` and return a non-empty normalized success object.
- FR-14: Contact operations use the package’s existing API response normalization so wrapped `{ data: ... }` contact responses are unwrapped for downstream nodes.
- FR-15: Continue-on-fail behavior works for contact operations with the same item-level error shape already used by ticket operations.
- FR-16: `phone_numbers` input is validated before request dispatch and must match the API’s expected array-of-objects shape.
- FR-17: The README operation matrix and examples include contact support.
- FR-18: Release notes mention the contact CRUD expansion.

### Non-functional Requirements
- NFR-01: Existing ticket, client, board, status, and priority behaviors remain unchanged.
- NFR-02: Contact support follows the package’s current TypeScript, Vitest, and helper conventions rather than introducing a second style.
- NFR-03: Validation failures for contact IDs or `phone_numbers` occur before outbound HTTP requests are made.
- NFR-04: The first pass avoids gold-plating and stays limited to core CRUD plus documentation and test coverage.

## Data / API / Integrations
- Package scope:
  - `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/__tests__/*`
  - `packages/n8n-nodes-alga-psa/README.md`
  - `packages/n8n-nodes-alga-psa/RELEASE_NOTES.md`
  - `packages/n8n-nodes-alga-psa/examples/*`

- Existing API endpoints:
  - `POST /api/v1/contacts`
  - `GET /api/v1/contacts`
  - `GET /api/v1/contacts/{id}`
  - `PUT /api/v1/contacts/{id}`
  - `DELETE /api/v1/contacts/{id}`

- Relevant server contracts:
  - `server/src/lib/api/schemas/contact.ts`
  - `server/src/lib/api/controllers/ApiContactController.ts`

- Contact payload scope for the first pass:
  - `full_name`
  - `email`
  - `client_id`
  - `role`
  - `notes`
  - `is_inactive`
  - `phone_numbers`

- `phone_numbers` API shape:
  - array of objects
  - each entry requires `phone_number`
  - optional keys include `contact_phone_number_id`, `canonical_type`, `custom_type`, `is_default`, and `display_order`

## Security / Permissions
- The node continues using the existing `Alga PSA API` credential with `x-api-key`.
- No permission model changes are required in the node package.
- Client and contact UUID fields must be validated before request dispatch.
- `phone_numbers` JSON must be validated before dispatch to prevent opaque API failures caused by malformed local input.

## Observability
- No new telemetry or logging work is planned in this pass.
- Existing request tests, helper tests, and documentation tests are the primary quality controls for this package-level change.

## Rollout / Migration
- No migration is required because this is a package surface expansion.
- Existing installed workflows remain unchanged.
- Contact support should ship as a package release with updated docs and example workflows.

## Open Questions
1. Should the first-pass list UI expose only the agreed core filters, or should it also expose additional contact API filters such as `full_name`, `email`, `phone_number`, `role`, `has_client`, and `client_name`?
2. Should the first example workflow focus on create-only, or demonstrate a chained CRUD flow such as create then update?

## Acceptance Criteria (Definition of Done)
1. The `Alga PSA` node exposes `Contact` with `Create`, `Get`, `List`, `Update`, and `Delete`.
2. Contact create and update support the agreed core fields and validate IDs plus `phone_numbers` locally.
3. Contact list preserves pagination metadata and supports core filters required for practical automation use.
4. Contact operations return normalized outputs and item-level continue-on-fail errors consistent with existing ticket behavior.
5. Automated tests cover node description, request construction, validation failures, list behavior, delete normalization, and docs synchronization.
6. README, release notes, and at least one example workflow reflect the new contact support.