PSA/ee/docs/plans/2026-03-15-multiple-email-addresses-per-contact/SCRATCHPAD.md

# Scratchpad — Multiple Email Addresses Per Contact

- Plan slug: `2026-03-15-multiple-email-addresses-per-contact`
- Created: `2026-03-15`

## What This Is

Working memory for adding multiple email addresses to contacts using a compatibility-preserving hybrid model:

- `contacts.email` stays required and remains the authoritative default email
- primary/default email label metadata lives on `contacts`
- additional non-default emails live in a child table
- changing default swaps the selected additional email into `contacts.email`

## Decisions

- (2026-03-15) Contacts may have multiple email addresses, but every stored email address remains unique per tenant across both the primary and additional-email storage locations.
- (2026-03-15) `contacts.email` remains required and authoritative. This effort does not make it nullable or replace it with a derived default.
- (2026-03-15) Changing the default email swaps the selected additional email into `contacts.email` and demotes the old primary email into the additional-email table.
- (2026-03-15) The primary/default email also carries a label.
- (2026-03-15) Canonical email labels are `work`, `personal`, `billing`, and `other`, with freeform tenant-scoped custom labels.
- (2026-03-15) The implementation should mirror the existing phone-label architecture and editor behavior where practical.

## Discoveries / Constraints

- (2026-03-15) The original fully normalized design was broader than necessary because many application surfaces already use `contacts.email` exactly the way we want the default email to behave.
- (2026-03-15) The biggest remaining change surface under the hybrid model is:
  - contact schema/model persistence
  - contact edit/create/import/export UI
  - lookup/query paths that must match additional emails
  - inbound/workflow paths that must distinguish matched sender email from `contacts.email`
- (2026-03-15) A large set of outbound and auth-adjacent consumers likely stays compatible with little or no contract change because they already read `contacts.email`:
  - portal invitation and registration flows
  - survey sends
  - invoice/billing sends
  - ticket/project notifications that already resolve a contact and then send to `contact.email`
  - many summary payloads such as `contact_email` / `author_contact_email`
- (2026-03-15) Search and lookup paths still need real changes because the app currently matches only `contacts.email` in several places:
  - `shared/services/emailService.ts`
  - `shared/workflow/actions/emailWorkflowActions.ts`
  - `shared/workflow/runtime/actions/businessOperations/contacts.ts`
  - `server/src/lib/api/services/ContactService.ts`
  - `packages/clients/src/actions/queryActions.ts`
  - `packages/integrations/src/actions/clientLookupActions.ts`
- (2026-03-15) Watch-list and similar recipient stores are email-keyed snapshots today. Under the hybrid model, they are likely safest to leave snapshot-based unless a surface explicitly re-resolves a contact from user input.

## Key Files To Revisit

- `shared/interfaces/contact.interfaces.ts`
- `packages/types/src/interfaces/contact.interfaces.ts`
- `shared/models/contactModel.ts`
- `server/src/lib/api/schemas/contact.ts`
- `server/src/lib/api/services/ContactService.ts`
- `packages/clients/src/components/contacts/ContactDetailsEdit.tsx`
- `packages/clients/src/components/contacts/ContactDetailsView.tsx`
- `packages/clients/src/components/contacts/QuickAddContact.tsx`
- `packages/clients/src/components/clients/QuickAddClient.tsx`
- `packages/clients/src/components/contacts/Contacts.tsx`
- `packages/clients/src/components/contacts/ContactsImportDialog.tsx`
- `packages/clients/src/actions/queryActions.ts`
- `shared/services/emailService.ts`
- `shared/services/email/processInboundEmailInApp.ts`
- `shared/workflow/actions/emailWorkflowActions.ts`
- `shared/workflow/runtime/actions/registerEmailWorkflowActions.ts`
- `shared/workflow/runtime/actions/businessOperations/contacts.ts`
- `shared/workflow/streams/domainEventBuilders/contactEventBuilders.ts`
- `packages/portal-shared/src/actions/portalInvitationActions.ts`
- `packages/auth/src/lib/registrationHelpers.ts`
- `packages/users/src/actions/user-actions/registrationActions.ts`
- `packages/client-portal/src/actions/portal-actions/tenantRecoveryActions.ts`
- `server/src/services/surveyService.ts`
- `server/src/lib/jobs/handlers/invoiceEmailHandler.ts`
- `packages/billing/src/actions/invoiceJobActions.ts`
- `shared/lib/tickets/watchList.ts`
- `packages/n8n-nodes-alga-psa/nodes/AlgaPsa/AlgaPsa.node.ts`
- `packages/integrations/src/actions/clientLookupActions.ts`
- `packages/integrations/src/actions/email-actions/emailActions.ts`
- `packages/integrations/src/services/xeroCsvClientSyncService.ts`

## Suggested Delivery Order

1. Schema and shared contracts
2. Contact model validation, hydration, persistence, and swap behavior
3. Shared email editor plus contact CRUD UI
4. Query/search/import/export surfaces
5. Inbound email and workflow lookup paths
6. REST, n8n, and integrations
7. Compatibility regressions for existing `contacts.email` consumers

## Commands / Runbooks

- Search scalar contact-email consumers:
  - `rg -n "\\bcontact\\.email\\b|contacts\\.email|contact_email|author_contact_email" server ee packages shared -g '!**/node_modules/**'`
- Search current phone-label reference pattern:
  - `rg -n "phone_numbers|default_phone_number|contact_phone|custom_phone_type" server ee packages shared -g '!**/node_modules/**'`
- Search lookup paths that currently match only `contacts.email`:
  - `rg -n "findContactByEmail|createOrFindContact|contacts\\.find|contacts\\.search|where\\(\\{ 'contacts\\.email'" server ee packages shared -g '!**/node_modules/**'`

## Open Questions

- None blocking the regenerated plan. The working assumptions are:
  - `contacts.email` stays required and authoritative
  - primary email changes are swaps, not pointer changes
  - additional emails are not independent login aliases
  - snapshot recipient stores remain snapshot-based unless later product direction changes

## Updates

- (2026-03-15) Original full-normalization plan replaced with a safer hybrid plan after design pivot.
- (2026-03-15) The regenerated plan reduces scope by preserving `contacts.email` compatibility for many existing outbound and auth-adjacent consumers.
- (2026-03-15) The regenerated feature inventory now concentrates on schema/model, editor UI, lookup/query behavior, inbound/workflow semantics, and contract extensions rather than rewriting every default-email consumer.
## Update (2026-03-15)
- Completed first milestone for schema/interface foundation:
  - Added shared email canonical labels and email row interfaces in `shared/interfaces/contact.interfaces.ts`.
  - Mirrored contact email interface updates in `packages/types/src/interfaces/contact.interfaces.ts`.
  - Added migration `20260315120000_create_contact_additional_email_addresses_schema.cjs` to support:
    - `contacts.primary_email_canonical_type`
    - `contacts.primary_email_custom_type_id` with tenant-scoped FK to `contact_email_type_definitions`
    - new `contact_email_type_definitions` table
    - new `contact_additional_email_addresses` table
    - normalized email uniqueness and tenant scoping
    - trigger-backed cross-table uniqueness checks
    - backfill of existing contacts with default primary email canonical type
- Added tests:
  - `server/src/test/unit/migrations/contactAdditionalEmailAddressesMigration.test.ts` for migration-level assertions.
  - `shared/models/__tests__/contactInterfaceParity.test.ts` for contract parity between shared interfaces and `@alga-psa/types`.
- Decision made to model primary email label metadata as explicit columns on `contacts` and use child rows for additional emails only.
- Constraint to keep: keep `contacts.email` as authoritative default and compatibility boundary for downstream consumers.
- (2026-03-15) Completed compatibility/regression closeout for default-email consumers:
  - Added `server/src/test/unit/contacts/ContactEmailDefaultConsumer.contract.test.ts` to lock portal/auth, billing, survey, project, ticket, and scheduling flows onto `contacts.email`.
  - Extended `shared/lib/tickets/__tests__/watchList.test.ts` to prove watcher recipients remain email-keyed snapshots even if later contact metadata differs.
  - Added `server/src/test/integration/contactEmailLookup.integration.test.ts` regression covering create -> promote additional email -> lookup by both addresses -> uniqueness guards.
- (2026-03-15) Found and fixed a real cross-table uniqueness bug while finishing `T049`:
  - `check_contact_additional_email_uniqueness()` originally compared against `NEW.normalized_email_address` inside a `BEFORE` trigger, but generated columns are not available there yet.
  - Fixed the migration trigger to normalize from `NEW.email_address` directly.
  - Updated `ContactModel.updateContact()` promotion flow to clear existing additional-email rows before swapping the primary email, then reinsert the final additional-email set after the primary update so immediate uniqueness triggers never observe an invalid intermediate state.
- (2026-03-15) Verification run for the final closeout:
  - `cd server && pnpm vitest run src/test/unit/migrations/contactAdditionalEmailAddressesMigration.test.ts src/test/unit/contacts/ContactEmailDefaultConsumer.contract.test.ts src/test/integration/contactModelEmailAddresses.integration.test.ts src/test/integration/contactEmailLookup.integration.test.ts --coverage=false`
  - `cd shared && pnpm vitest run lib/tickets/__tests__/watchList.test.ts --coverage=false`
- Completed shared email editor milestone:
  - Added `packages/clients/src/components/contacts/ContactEmailAddressesEditor.tsx` with:
    - pinned primary/default row
    - additional row add/remove/reorder/promote behavior
    - canonical plus custom label editing
    - helper exports for normalize/compact/reorder/promote/validate flows
  - Validation now allows reuse of the same custom label across rows because labels are tenant-scoped reusable definitions, not per-contact unique values.
  - Added focused helper coverage in `packages/clients/src/components/contacts/ContactEmailAddressesEditor.test.ts`.
  - Added jsdom interaction coverage in `server/src/test/unit/contacts/ContactEmailAddressesEditor.test.tsx`.
- Commands run for the shared editor milestone:
  - `../../node_modules/.bin/vitest run src/components/contacts/ContactEmailAddressesEditor.test.ts --coverage=false` from `packages/clients`
  - `cd server && pnpm vitest run src/test/unit/contacts/ContactEmailAddressesEditor.test.tsx --coverage=false`
- Completed contact-surface wiring milestone:
  - `ContactDetailsEdit.tsx` now edits and saves the hybrid email payload through `ContactEmailAddressesEditor`, validates it on submit, and sends compacted email rows through `updateContact`.
  - `ContactDetailsView.tsx` now renders the primary/default email distinctly and lists additional email addresses with labels underneath.
  - `QuickAddContact.tsx` now authors the hybrid email payload, including additional email rows, through the shared editor before calling `addContact`.
  - `QuickAddClient.tsx` inline contact creation now authors the same hybrid email payload before calling `createClientContact`.
  - `contactActions.tsx` now forwards primary-email label metadata and additional email rows through `addContact`, `updateContact`, and `createClientContact`.
- Added coverage for the contact-surface wiring milestone:
  - `server/src/test/unit/contacts/ContactDetailsEmailAddresses.contract.test.ts`
  - `server/src/test/unit/contacts/QuickAddContact.phoneNumbers.test.tsx`
  - `server/src/test/unit/contacts/QuickAddClient.phoneNumbers.test.tsx`
- Commands run for the contact-surface wiring milestone:
  - `cd server && pnpm vitest run src/test/unit/contacts/ContactEmailAddressesEditor.test.tsx src/test/unit/contacts/ContactDetailsEmailAddresses.contract.test.ts src/test/unit/contacts/QuickAddContact.phoneNumbers.test.tsx src/test/unit/contacts/QuickAddClient.phoneNumbers.test.tsx --coverage=false`
- Completed summary-surface compatibility audit:
  - `Contacts.tsx`, `ClientDetails.tsx`, `ContactPicker.tsx`, and `ContactPickerDialog.tsx` already remained anchored on scalar `contact.email` for summary rendering and picker search.
  - Added a contract regression test to lock in that list and picker surfaces keep using the primary/default `contacts.email` field even as detailed contact rendering grows richer.
- Added coverage for the summary-surface compatibility audit:
  - `server/src/test/unit/contacts/ContactSummaryEmail.contract.test.ts`
- Command run for the summary-surface compatibility audit:
  - `cd server && pnpm vitest run src/test/unit/contacts/ContactSummaryEmail.contract.test.ts --coverage=false`

## Update (2026-03-15, validation/persistence block)
- Completed `F008` through `F011` in the shared contact model and flipped `T008` through `T016` to implemented.
- Added input support for `primary_email_custom_type` in shared and `@alga-psa/types` contact contracts so callers can create or update primary custom labels without pre-resolving definition IDs.
- Tightened validation in `shared/models/contactModel.ts` to enforce canonical-vs-custom exclusivity for primary labels and to reject primary custom labels that duplicate canonical values.
- Fixed a swap edge case: promoting an additional email with a custom label now preserves that custom label on the promoted primary row instead of dropping back to `null`.
- Fixed a persistence edge case: demoting a custom-labeled primary email during swap now preserves its existing `custom_email_type_id` when writing the additional-email row.
- Confirmed the current cleanup helpers already count both `contacts.primary_email_custom_type_id` and `contact_additional_email_addresses.custom_email_type_id`, so orphan detection/deletion works across both storage locations.
- Updated tests:
  - `shared/models/__tests__/contactModel.test.ts`
  - `shared/models/__tests__/contactInterfaceParity.test.ts`
  - `server/src/test/integration/contactModelEmailAddresses.integration.test.ts`
- Verification runbook used:
  - `pnpm vitest run models/__tests__/contactModel.test.ts models/__tests__/contactInterfaceParity.test.ts` from `shared/`
  - `pnpm vitest run src/test/integration/contactModelEmailAddresses.integration.test.ts` from `server/`
- Gotcha discovered:
  - The first draft of the model only supported custom primary labels by stored definition ID, which was insufficient for create/update flows and broke promotion of custom-labeled additional emails. The fix was to treat primary labels like additional rows at the input boundary, then resolve/create the tenant-scoped label definition inside the model transaction.

## Update (2026-03-15, event/workflow contracts)
- Completed `F012` and flipped `T017` to implemented.
- Updated contact domain-event builders to emit:
  - `primaryEmailCanonicalType`
  - `primaryEmailCustomTypeId`
  - `primaryEmailType`
  - `additionalEmailAddresses`
  while still leaving the summary/default address on top-level `email`.
- Added an alias rule in `buildContactUpdatedPayload` so workflow/event diffs treat input-only `primary_email_custom_type` changes as changes to the persisted `primary_email_type` and `primary_email_custom_type_id` fields.
- Updated both schema copies of CRM event payloads:
  - `shared/workflow/runtime/schemas/crmEventSchemas.ts`
  - `packages/event-schemas/src/schemas/domain/crmEventSchemas.ts`
- Updated both workflow event publishers that build `CONTACT_CREATED` payloads:
  - `server/src/lib/api/services/ContactService.ts`
  - `packages/clients/src/actions/contact-actions/contactActions.tsx`
- Verification runbook used:
  - `pnpm vitest run workflow/streams/domainEventBuilders/__tests__/contactEventBuilders.test.ts` from `shared/`

## Update (2026-03-15, contact search/export compatibility)
- Completed `F018` and flipped `T026` and `T027` to implemented.
- Extended server-side contact email searching so `ContactService` now treats both the primary `contacts.email` column and `contact_additional_email_addresses.email_address` as valid matches for:
  - search clauses targeting the `email` field
  - list filters using `email`
  - free-text contact search
- Kept compatibility boundaries intact:
  - contact lists, pickers, and exports continue rendering/emitting scalar `contact.email` as the summary/default address
  - local client-side filtering in `Contacts.tsx` now includes additional email rows without changing the visible summary email column
- Added regression coverage:
  - `server/src/test/integration/contactServiceEmailSearch.integration.test.ts`
  - `server/src/test/unit/contacts/ContactsAdditionalEmailSearch.contract.test.ts`
  - `server/src/test/unit/contacts/ContactSummaryEmail.contract.test.ts`
- Verification runbook used:
  - `cd server && pnpm vitest run src/test/unit/contacts/ContactSummaryEmail.contract.test.ts src/test/unit/contacts/ContactsAdditionalEmailSearch.contract.test.ts src/test/integration/contactServiceEmailSearch.integration.test.ts --coverage=false`

## Update (2026-03-15, contact CSV hybrid email support)
- Completed `F019` and flipped `T028` through `T030` to implemented.
- Added a shared CSV email-field helper in `packages/clients/src/lib/contactCsvEmailFields.ts` so contact CSV import/export/template generation uses one representation for:
  - `primary_email_type`
  - `additional_email_addresses` as `label:email@example.com | label:email@example.com`
- Updated `contactActions.tsx` so contact CSV flows now:
  - export primary email labels and formatted additional-email rows while keeping scalar `email` as the primary/default address
  - generate a CSV template with the new hybrid email columns and example values
  - check existing emails across both `contacts.email` and `contact_additional_email_addresses`
  - import/create/update contacts with primary label metadata and additional-email rows
  - support updating an existing contact when the import row matches one of that contact's additional email addresses
- Updated `ContactsImportDialog.tsx` so CSV mapping, validation, preview, and upload copy understand the new hybrid-email fields and collision checks.
- Added/updated regression coverage in `server/src/test/integration/contactCsvPhoneImportExport.integration.test.ts` for:
  - DB-backed create/update import behavior with primary and additional email rows when the local test Postgres harness is available
- Added no-DB contract coverage for the CSV email representation and import wiring:
  - `server/src/test/unit/contacts/contactCsvEmailImportExport.contract.test.ts`
  - `server/src/test/unit/contacts/contactCsvImport.contract.test.ts`
- Verification runbook used:
  - `cd server && pnpm vitest run src/test/unit/contacts/contactCsvEmailImportExport.contract.test.ts src/test/unit/contacts/contactCsvImport.contract.test.ts --coverage=false`
- Gotchas discovered:
  - Import updates that match by an additional email need pre-normalization before calling `ContactModel.updateContact`, otherwise the model correctly rejects a raw primary-email change that has not been expressed as a promote/swap.
  - When the import row promotes an existing additional email to primary, the import layer must omit the old primary from the incoming additional-email list because the model appends the demoted primary row transactionally during the swap.

## Update (2026-03-15, shared lookup helpers)
- Completed `F020` and flipped `T031` and `T032` to implemented.
- Updated `ContactModel.getContactByEmail` so shared lookup now resolves contacts by either:
  - `contacts.email`
  - `contact_additional_email_addresses.normalized_email_address`
- Updated `findContactByEmailAddress` in `packages/clients/src/actions/queryActions.ts` to defer to the shared model helper instead of running a primary-only SQL query.
- `createOrFindContactByEmail` now inherits the hybrid lookup behavior through `ContactModel.getContactByEmail` while still creating new contacts with only a primary email on `contacts.email` when no match exists.
- Added focused no-DB regression coverage:
  - `shared/models/__tests__/contactModel.getContactByEmail.test.ts`
  - `server/src/test/unit/contacts/contactEmailLookup.contract.test.ts`
- Verification runbook used:
  - `cd shared && pnpm vitest run models/__tests__/contactModel.getContactByEmail.test.ts --coverage=false`
  - `cd server && pnpm vitest run src/test/unit/contacts/contactEmailLookup.contract.test.ts --coverage=false`

## Update (2026-03-15, shared email service lookup semantics)
- Completed `F021` and flipped `T033` and `T034` to implemented.
- Updated `shared/services/emailService.ts` so `EmailService.findContactByEmail` now:
  - delegates contact resolution to `ContactModel.getContactByEmail`
  - preserves the canonical primary/default contact email on `email`
  - surfaces the exact lookup match separately on `matched_email`
  - still hydrates default phone and client name for downstream consumers
- Confirmed `EmailService.createOrFindContact` remains compatibility-safe:
  - it reuses the hybrid lookup path through `findContactByEmail`
  - it still creates new contacts with only `contacts.email` populated and no additional-email rows when no match exists
- Added focused no-DB coverage:
  - `shared/services/__tests__/emailService.contactLookup.test.ts`
- Added a DB-backed integration regression for environments where the local test harness is available:
  - `server/src/test/integration/emailServiceContactLookup.integration.test.ts`
- Verification runbook used:
  - `cd shared && pnpm vitest run services/__tests__/emailService.contactLookup.test.ts --coverage=false`

## Update (2026-03-15, workflow contact email lookup)
- Completed `F022` and flipped `T035` to implemented.
- Updated `shared/workflow/actions/emailWorkflowActions.ts#findContactByEmail` so workflow contact matching now searches both:
  - `contacts.email`
  - `contact_additional_email_addresses.normalized_email_address`
- Kept the existing context-aware ticket/default-client resolution logic intact after broadening the candidate query, so inbound workflow attribution still prefers ticket/default-client boundaries when multiple mocked candidates are present in tests.
- `createOrFindContact` in the workflow action already used `ContactModel.getContactByEmail`, so it now inherits the hybrid lookup behavior while continuing to create new contacts with only a primary email on `contacts.email`.
- Extended the existing workflow unit suite:
  - `shared/workflow/actions/__tests__/emailWorkflowActions.findContactByEmail.context.test.ts`
- Verification runbook used:
  - `cd shared && pnpm vitest run workflow/actions/__tests__/emailWorkflowActions.findContactByEmail.context.test.ts --coverage=false`

## Update (2026-03-15, inbound matched-email preservation)
- Completed `F023` and flipped `T036` and `T037` to implemented.
- Updated `shared/services/email/processInboundEmailInApp.ts` so inbound comment metadata now preserves both:
  - `metadata.email.matchedAddress` for the exact sender address that matched lookup
  - `metadata.email.contactEmail` for the matched contact's primary/default `contacts.email`
- Kept the existing authorship routing intact:
  - `contact_id`, `author_id`, and `client_id` continue to resolve from the matched contact record
  - default-email consumers can continue to treat `contacts.email` as authoritative
- Added a focused regression covering the additional-email-match path:
  - `shared/services/email/__tests__/processInboundEmailInApp.additionalPaths.test.ts`
- Verification runbook used:
  - `cd shared && pnpm vitest run services/email/__tests__/processInboundEmailInApp.additionalPaths.test.ts --coverage=false`

## Update (2026-03-15, runtime matched-email contracts)
- Completed `F024` and flipped `T038` to implemented.
- Updated `shared/workflow/actions/emailWorkflowActions.ts` so workflow contact lookups now return `matched_email` alongside the primary/default `email`.
- Updated `shared/workflow/runtime/actions/registerEmailWorkflowActions.ts` so runtime contact outputs now expose:
  - `email` for the primary/default `contacts.email`
  - `matched_email` for the exact sender email that matched when it differs from the primary email
- Updated `shared/workflow/runtime/schemas/emailWorkflowSchemas.ts` so the shared runtime schema vocabulary can describe both the primary/default email and the matched sender email separately.
- Extended runtime registry coverage:
  - `shared/workflow/actions/__tests__/emailWorkflowActions.findContactByEmail.context.test.ts`
  - `shared/workflow/runtime/actions/__tests__/registerEmailWorkflowActions.contactAuthorship.test.ts`
- Verification runbook used:
  - `cd shared && pnpm vitest run workflow/actions/__tests__/emailWorkflowActions.findContactByEmail.context.test.ts workflow/runtime/actions/__tests__/registerEmailWorkflowActions.contactAuthorship.test.ts services/email/__tests__/processInboundEmailInApp.additionalPaths.test.ts --coverage=false`
- Constraint observed:
  - `cd server && pnpm vitest run src/test/integration/workflowRuntimeV2.email.integration.test.ts --coverage=false` is currently blocked locally because the configured `server` test database does not exist in this environment.

## Update (2026-03-15, workflow business contact email search)
- Completed `F025` and flipped `T039` to implemented.
- Updated `shared/workflow/runtime/actions/businessOperations/contacts.ts` so:
  - `contacts.find` resolves email lookups through `ContactModel.getContactByEmail`, which now covers both primary and additional contact emails
  - `contacts.search` keeps summary rows sourced from `contacts.email` while adding an `EXISTS` search clause for `contact_additional_email_addresses`
- Added focused unit coverage:
  - `shared/workflow/runtime/actions/__tests__/businessOperations.contacts.emailSearch.test.ts`
- Verification runbook used:
  - `cd shared && pnpm vitest run workflow/runtime/actions/__tests__/businessOperations.contacts.emailSearch.test.ts --coverage=false`

## Update (2026-03-15, REST contact hybrid email contracts)
- Completed `F026` and flipped `T040` and `T041` to implemented.
- Updated `server/src/lib/api/schemas/contact.ts` so REST contact schemas now accept and return:
  - scalar `email` as the primary/default address
  - `primary_email_canonical_type`
  - `primary_email_custom_type`
  - `primary_email_custom_type_id`
  - `primary_email_type` on responses
  - `additional_email_addresses`
- Updated `server/src/lib/api/services/ContactService.ts#create` so create requests stop dropping the hybrid email fields before they reach `ContactModel.createContact`.
- Added focused unit coverage:
  - `server/src/test/unit/validation/contactPhoneSchemas.test.ts`
  - `server/src/test/unit/api/contactService.hybridEmailFields.test.ts`
- Verification runbook used:
  - `cd server && pnpm vitest run src/test/unit/validation/contactPhoneSchemas.test.ts src/test/unit/api/contactService.hybridEmailFields.test.ts --coverage=false`
- Constraint observed:
  - A DB-backed `ContactService` integration variant was not kept because local Postgres connectivity to the `.env.localtest` harness is currently blocked (`EPERM` to `127.0.0.1:5438` / `::1:5438`) in this environment.

## Update (2026-03-15, n8n hybrid email payloads)
- Completed `F027` and flipped `T042` to implemented.
- Updated `packages/n8n-nodes-alga-psa/nodes/AlgaPsa/helpers.ts` so contact create/update payload builders now preserve:
  - scalar `email` as the primary/default address
  - `primary_email_canonical_type`
  - `primary_email_custom_type`
  - `primary_email_custom_type_id`
  - `additional_email_addresses`
- Added `parseContactEmailAddresses` to normalize the freeform JSON field used for additional email rows and keep n8n validation errors local to the node layer.
- Updated `packages/n8n-nodes-alga-psa/nodes/AlgaPsa/AlgaPsa.node.ts` so contact create/update operations expose hybrid-email fields in the node UI.
- Updated supporting docs and examples:
  - `packages/n8n-nodes-alga-psa/README.md`
  - `packages/n8n-nodes-alga-psa/examples/create-update-contact.workflow.json`
- Added focused package coverage:
  - `packages/n8n-nodes-alga-psa/__tests__/helpers.test.ts`
  - `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__/docs.test.ts`
- Verification runbook used:
  - `cd packages/n8n-nodes-alga-psa && ../../node_modules/.bin/vitest run --config vitest.config.ts __tests__/helpers.test.ts __tests__/node-description-loadoptions.test.ts __tests__/node-execute.test.ts __tests__/docs.test.ts`

## Update (2026-03-15, integration contact email lookup)
- Completed `F028` and flipped `T043` to implemented.
- Updated `packages/integrations/src/actions/clientLookupActions.ts` so integration contact lookup now routes through `ContactModel.getContactByEmail` instead of querying only `contacts.email`.
- This broadens both:
  - `findIntegrationContactByEmailAddress`
  - `createOrFindIntegrationContactByEmail`
  to resolve contacts when the requested email matches an additional-email row while still returning the primary/default `contacts.email` on the hydrated contact object.
- Confirmed the higher-level integration email helper inherits the same behavior because `packages/integrations/src/actions/email-actions/emailActions.ts#findContactByEmail` still delegates into the client lookup helper.
- Added focused coverage:
  - `packages/integrations/src/actions/clientLookupActions.emailLookup.test.ts`
- Verification runbooks used:
  - `cd packages/integrations && ../../node_modules/.bin/vitest run src/actions/clientLookupActions.emailLookup.test.ts`
- Constraint observed:
  - `node_modules/.bin/tsc -p packages/integrations/tsconfig.json --noEmit` currently fails in pre-existing shared-model code under `shared/models/contactModel.ts` because `ContactEmailAddressInput` typing there does not include `normalized_email_address` / `normalized_custom_type`. This check is not blocked by the `F028` package changes themselves.

## Update (2026-03-15, external sync email compatibility)
- Completed `F029` and flipped `T044` to implemented.
- Audited the remaining external sync/import/export adapter surface after `F028`:
  - no remaining adapter-specific contact lookup path was bypassing the shared integration contact-email helpers
  - `packages/integrations/src/services/xeroCsvClientSyncService.ts` does not resolve contact email aliases directly; it operates on client billing/summary email fields
- Made the compatibility boundary explicit by extracting `getClientSummaryEmail` inside `packages/integrations/src/services/xeroCsvClientSyncService.ts` and keeping export behavior anchored on the client's primary billing/summary email before any location fallback.
- Added focused regression coverage:
  - `packages/integrations/src/services/xeroCsvClientSyncService.emailSummary.test.ts`
- Verification runbook used:
  - `cd packages/integrations && ../../node_modules/.bin/vitest run src/services/xeroCsvClientSyncService.emailSummary.test.ts`

## Update (2026-03-15, contact helper fixtures and seeds)
- Completed `F030` and flipped `T045` to implemented.
- Updated reusable contact helpers to author the hybrid email model directly through `ContactModel.createContact`:
  - `server/src/test/e2e/factories/contact.factory.ts`
  - `server/src/test/e2e/utils/contactTestDataFactory.ts`
  - `server/src/test/e2e/utils/email-test-factory.ts`
- Those helpers now support:
  - labeled primary email metadata
  - optional additional email rows with normalized `display_order`
  - backward-compatible defaults that still create a primary email label when tests only pass a scalar email
- Updated the dev seed fixture:
  - `server/seeds/dev/05_contacts.cjs`
  - added primary email labels on seeded contacts
  - added an example `contact_additional_email_addresses` row
- Added DB-backed regression coverage:
  - `server/src/test/integration/contactTestHelpersEmailRows.integration.test.ts`
- Verification runbook used:
  - `cd server && pnpm vitest run src/test/integration/contactTestHelpersEmailRows.integration.test.ts --coverage=false`
- Constraint observed:
  - the additional-email seed must not set `normalized_email_address` directly because that column is generated by the database schema.