PSA/docs/plans/2026-05-15-outbound-webhooks-for-projects/SCRATCHPAD.md

SCRATCHPAD — Outbound Webhooks for Projects

Decisions (with rationale)

• 2026-05-15 — Single project allowlist entity (user-confirmed via AskUserQuestion). Both project- and task-level events route to project; webhookEntityForEventType() unchanged. Accepted cost: field picker for project.created lists task-only fields. Mitigation: task events pass extraAlwaysIncluded:['task_id'] to the projection helper so task_id survives even when not selected.
• 2026-05-15 — Rename projectWebhookPayload → applyPayloadAllowlist. The verb "project" (to project/filter) collides with the new project entity noun; projectWebhookPayload('project', …) is unreadable. Cheap now — Phase 0 already moved the function to payloadFields.ts.
• 2026-05-15 — Keep project.completed / project.task.completed as deprecated accepted aliases, not removed. The public enum gates subscription create/update validation; removal would break stored webhook_subscriptions rows and the OpenAPI contract even though project webhooks never delivered before.
• 2026-05-15 — PROJECT_TASK_UPDATED emitted from updateTaskWithChecklist AND the interactive tag path (F008). The other five task write paths (status/phase-move/reorder/reorder-in-status/ dependency) still have dedicated events or no webhook-relevant delta.
• 2026-05-15 — Tag changes trigger webhooks for project_task AND ticket (F008), parity (user-confirmed; largest of the three options). Emit PROJECT_TASK_UPDATED / TICKET_UPDATED with changes.tags from the interactive tag path. No new public events — reuses *.updated. Rationale: the no-trigger gap is identical for tickets today; fixing only projects would leave the product inconsistent.

Discoveries (grounded against codebase)

• Phase 0 ALREADY IMPLEMENTED as unstaged changes; tests pass (payloadFields.test.ts 2/2; webhookDelivery.* 3/3). It consolidated MORE than the original draft: payloadFields.ts also owns payloadFieldsByEntitySchema, webhookEntityForEventType, and the projection helper (moved out of webhookTicketPayload.ts; deprecated projectTicketWebhookPayload shim deleted). Treat as precondition only.
• ALWAYS_INCLUDED_KEYS_BY_ENTITY shipped as ... as const satisfies Record<WebhookPayloadEntity, readonly string[]> (strict). Keep it — compiler forces the project key when registry grows.
• Tag system (shared/models/tagModel.ts): tagged_type enum = ['client','contact','project_task','document','knowledge_base_article']. → NO project type. Project payload ships without tags. Task payload tags via 'project_task'. (Original draft had this inverted.)
• projectActions.ts emits: PROJECT_CREATED :986, PROJECT_ASSIGNED :1052, PROJECT_STATUS_CHANGED :1089, PROJECT_UPDATED :1101, PROJECT_CLOSED :1532.
• Task mutation entry points in packages/projects/src/actions/projectTaskActions.ts: updateTaskWithChecklist :505 (← emit PROJECT_TASK_UPDATED here only), updateTaskStatus :688, moveTaskToPhase :1559, reorderTask :2102, reorderTasksInStatus :2178, updateTaskDependency :2478.
• Current public enum (webhookSchemas.ts:40-45): project.created, project.updated, project.completed, project.task.created, project.task.updated, project.task.completed. Missing: project.status_changed, project.assigned, project.closed, project.task.status_changed, project.task.assigned.
• OpenAPI route now derives the per-entity payload schema from WEBHOOK_PAYLOAD_FIELDS_BY_ENTITY → adding project auto-extends docs.
• F008 grounding: packages/tags/src/actions/tagActions.ts emits only TAG_DEFINITION_UPDATED (lines 283, 831 — rename/recolor, not per-entity). Entry points: createTag :101, deleteTag :335 (interactive single), createTagsForEntity :534 + createTagsForEntityWithTransaction :571 (bulk, creation-time), deleteAllTagsByText :923 (bulk by text).
• TICKET_UPDATED internal event exists (eventBusSchema.ts:160, schema :785); ticket webhook builder already attaches changes when eventType === 'TICKET_UPDATED' (webhookTicketPayload.ts:143-144) via normalizeChanges (:369). → ticket side of F008 needs ZERO builder change, only event emission. F005 must mirror this changes attach for PROJECT_TASK_UPDATED.
• ⚠️ DOUBLE-FIRE GOTCHA (F008): TaskForm.tsx:910 calls createTagsForEntity(taskId,'project_task',pendingTags) right after the task is created (PROJECT_TASK_CREATED already fired). Emitting from the bulk create path would double-fire CREATED + spurious UPDATED on every create-with-tags. → emit only from interactive single-tag mutations, never the bulk creation-time path. Same caution for ticket create-with-tags.

Open questions / to verify during impl

• Task webhook url route shape: confirm /msp/projects/:id?taskId=:taskId against the Next.js app router before shipping F005.
• Confirm an existing normalizeChanges-style helper in the project actions to reuse for changes (do not roll a new diff util).

Loop runbook

• Feature order (array order in features.json) = F001(verify/commit precondition) → F002 → F003 → F008 → F004 → F005 → F006 → F007. Each feature = one commit. F008 runs 4th (needs F003's PROJECT_TASK_UPDATED; ticket side uses existing TICKET_UPDATED).
• Per-feature gate before flipping implemented:true:
  • cd server && npx vitest run <relevant specs> --coverage=false
  • workspace type-check.
• Useful commands:
  • cd /Users/natalliabukhtsik/Desktop/Desktop/projects/alga-psa/server && npx vitest run src/lib/webhooks/__tests__/payloadFields.test.ts --coverage=false
  • ... npx vitest run src/test/integration/webhookDelivery.entityIdFilter.test.ts src/test/integration/webhookDelivery.tenantIsolation.test.ts --coverage=false
• ⚠️ Repo policy: do NOT stage/commit/push without explicit user request, even inside the loop. The loop implements + verifies; the user commits.

Status log

• 2026-05-15: Plan created (PRD + 7 features + 25 tests). Phase 0 done (F001 implemented:true, uncommitted). Phase 1 not started.
• 2026-05-15: Added F008 (tag-change webhooks, projects + tickets parity) per user decision → 8 features + 30 tests. Runs 4th in execution order.
• 2026-05-15: Completed F002. Renamed projectWebhookPayload to applyPayloadAllowlist in payloadFields.ts, updated the ticket webhook subscriber and payload-field tests, and added the optional extraAlwaysIncluded parameter for future task payload projection. Verification: cd server && npx vitest run src/lib/webhooks/__tests__/payloadFields.test.ts --coverage=false (4/4) and cd server && npx vitest run src/test/integration/webhookDelivery.entityIdFilter.test.ts src/test/integration/webhookDelivery.tenantIsolation.test.ts --coverage=false (3/3). Source search with coverage excluded has no remaining projectWebhookPayload references. npm run typecheck OOMed under the default Node heap; NODE_OPTIONS='--max-old-space-size=8192' npm run typecheck passed and also satisfies T003.
• 2026-05-15: Completed F003. Added canonical PROJECT_TASK_UPDATED schema with projectTaskId + phaseId, exported ProjectTaskUpdatedEvent, and emit it from updateTaskWithChecklist only when buildProjectTaskWebhookChanges(...) returns a non-empty diff. Extracted the diff builder to packages/projects/src/lib/projectTaskWebhookChanges.ts so date normalization and no-op behavior are unit tested without a DB/auth harness. Added a contract test proving the five out-of-scope task mutation entry points do not emit PROJECT_TASK_UPDATED. Verification: cd server && npx vitest run ../packages/event-schemas/src/schemas/eventBusSchema.projectTaskUpdated.test.ts ../packages/projects/src/lib/projectTaskWebhookChanges.test.ts ../packages/projects/src/actions/projectTaskWebhookUpdated.contract.test.ts --coverage=false (9/9) and cd server && NODE_OPTIONS='--max-old-space-size=8192' npm run typecheck.
• 2026-05-15: Completed F008. Interactive createTag / deleteTag now snapshots unique tag text sets before and after mutation and publishes entity update events only when the set changes. project_task resolves { projectId, phaseId } and emits PROJECT_TASK_UPDATED; ticket emits TICKET_UPDATED; both carry changes.tags. Added suppressEntityUpdateEvent for createTag and use it from createTagsForEntity so initial tag application does not double-fire; createTagsForEntityWithTransaction remains bulk-only and never calls the entity update publisher. Added a ticket payload regression proving TICKET_UPDATED tag diffs reach payload.changes. Verification: cd server && npx vitest run ../packages/tags/src/actions/tagActions.webhookEmission.contract.test.ts src/lib/eventBus/subscribers/webhook/__tests__/webhookTicketPayload.test.ts --coverage=false (8/8) and cd server && NODE_OPTIONS='--max-old-space-size=8192' npm run typecheck.
• 2026-05-15: Completed F004. Added project and project-task public events to SUPPORTED_WEBHOOK_EVENTS, webhookEventTypeSchema, and the OpenAPI route event enum, preserving project.completed as the deprecated project.closed compatibility alias. Added WEBHOOK_PROJECT_PAYLOAD_FIELDS and the single project payload entity; project_id is excluded from the selectable list and retained via ALWAYS_INCLUDED_KEYS_BY_ENTITY.project. Task-only tags is present in the combined project field list, with no project-level tag field in the future project payload. Verification: cd server && npx vitest run src/lib/webhooks/__tests__/payloadFields.test.ts src/lib/api/schemas/__tests__/webhookSchemas.test.ts src/lib/actions/__tests__/webhookActions.supportedEvents.test.ts --coverage=false (7/7) and cd server && NODE_OPTIONS='--max-old-space-size=8192' npm run typecheck.
• 2026-05-15: Completed F005. Added webhookProjectEventMap.ts with internal to public project mappings, including PROJECT_CLOSED -> both project.closed and deprecated project.completed. Added webhookProjectPayload.ts for project and task payload builders, 60s/256 LRU caches, project_task tag resolution for task payloads, status-change previous status enrichment, update changes, and uncached phases / task_counts helpers. Task URL is implemented as /msp/projects/:projectId?taskId=:taskId; no existing route reference was found in source search, matching the PRD's accepted shape. Verification: cd server && npx vitest run src/lib/eventBus/subscribers/webhook/__tests__/webhookProjectEventMap.test.ts src/lib/eventBus/subscribers/webhook/__tests__/webhookProjectPayload.test.ts --coverage=false (7/7) and cd server && NODE_OPTIONS='--max-old-space-size=8192' npm run typecheck.
• 2026-05-15: Completed F006. Added live projectWebhookSubscriber.ts, registered it from subscriber index, and widened WebhookDeliveryQueue typing from ticket-only to generic webhook event/payload because the queue was already runtime entity-agnostic. Project events filter on projectId; task events filter on projectTaskId/taskId and project allowlist projection passes extraAlwaysIncluded:['task_id']. Project phases and task_counts opt-ins are fetched lazily once per event and reused for all matching subscribers. Verification: cd server && npx vitest run src/lib/eventBus/subscribers/__tests__/projectWebhookSubscriber.test.ts src/lib/eventBus/subscribers/__tests__/subscriberIndex.projectWebhook.test.ts src/test/integration/webhookDelivery.entityIdFilter.test.ts src/test/integration/webhookDelivery.tenantIsolation.test.ts --coverage=false (6/6) and cd server && NODE_OPTIONS='--max-old-space-size=8192' npm run typecheck.
• 2026-05-15: Completed F007. Added webhookDelivery.projectWebhooks.test.ts covering project.created projection with phases, project.task.updated tag-only delivery with task_id retained, and ticket.updated tag-only parity. The "integration" style matches the existing webhook delivery integration tests in this repo: subscriber registration, event dispatch, mocked model/payload builders, and queue job assertions rather than a live HTTP server/DB row. Verification: cd server && npx vitest run src/test/integration/webhookDelivery.projectWebhooks.test.ts src/test/integration/webhookDelivery.entityIdFilter.test.ts src/test/integration/webhookDelivery.tenantIsolation.test.ts src/lib/eventBus/subscribers/webhook/__tests__/webhookProjectEventMap.test.ts src/lib/eventBus/subscribers/webhook/__tests__/webhookProjectPayload.test.ts src/lib/eventBus/subscribers/__tests__/projectWebhookSubscriber.test.ts src/lib/eventBus/subscribers/__tests__/subscriberIndex.projectWebhook.test.ts src/lib/webhooks/__tests__/payloadFields.test.ts --coverage=false (20/20) and cd server && NODE_OPTIONS='--max-old-space-size=8192' npm run typecheck.