@open-mercato/core 0.7.1-develop.7178.1.ab93fbaf4e → 0.7.1-develop.7180.1.9717fbbb43

package/src/modules/staff/events.payloads.ts

@@ -0,0 +1,268 @@
+/**
+ * Payload contracts for the `staff.timesheets.*` event family.
+ *
+ * **Why this file exists.** Outbound webhooks in this platform are not registered
+ * per event: `packages/webhooks` subscribes once with `event: '*'`
+ * (`subscribers/outbound-dispatch.ts`) and matches each emitted id against the
+ * patterns a webhook endpoint subscribed to, so declaring an event in `events.ts`
+ * IS its registration — it appears in `GET /api/webhooks/events` and is deliverable
+ * from that moment (`packages/webhooks/AGENTS.md` → "When You Need Outbound
+ * Webhooks", step 1). Two properties decide whether a declared event actually
+ * reaches an endpoint, and neither is checked anywhere else:
+ *
+ *  1. the dispatcher drops any payload without a `tenantId` — it cannot resolve a
+ *     webhook without one, so an event emitted without tenant scope is silently
+ *     undeliverable;
+ *  2. the delivered body IS the event payload, verbatim, so the payload is the
+ *     integration contract an external billing or PM system codes against.
+ *
+ * The webhooks package has no payload-schema registry to register with, so these
+ * schemas are that contract, published here and pinned by
+ * `__tests__/timeTrackingEventPayloads.test.ts`: every declared `staff.timesheets.*`
+ * id must appear below, and every schema must require `tenantId`.
+ *
+ * Each schema is `passthrough()`: the listed keys are what a subscriber may rely on,
+ * additional keys are allowed so a later emitter can add one without breaking a
+ * consumer that validates against this schema.
+ *
+ * Money note: `time_report.closed` carries minute totals but no amount, and
+ * `time_project.budget_threshold_reached` carries an `amount` budget's value only
+ * when the budget is measured in hours. Both events are `clientBroadcast: true` and
+ * the DOM Event Bridge has no feature gate, so the amounts are withheld from the
+ * payload itself rather than from one of its two audiences.
+ *
+ * Money is not the only thing that audience decides. A `clientBroadcast: true`
+ * payload must also carry no operator free text and no customer identity: SSE
+ * reaches every signed-in user of the organization, so `time_report.unlocked` omits
+ * its mandatory `reason` and `time_report.closed` omits `customerId`.
+ * `__tests__/timeTrackingEventPayloads.test.ts` fails if either reappears.
+ */
+
+import { z } from 'zod'
+
+const scope = z.object({
+  tenantId: z.string(),
+  organizationId: z.string().nullable().optional(),
+})
+
+/** The `{ id, tenantId, organizationId }` shape every CRUD lifecycle event carries. */
+const crudPayload = scope.extend({ id: z.string() }).passthrough()
+
+const timerStarted = scope
+  .extend({
+    id: z.string(),
+    staffMemberId: z.string().nullable(),
+    startedAt: z.string(),
+  })
+  .passthrough()
+
+const timerStopped = scope
+  .extend({
+    id: z.string(),
+    staffMemberId: z.string().nullable(),
+    stoppedAt: z.string(),
+    durationMinutes: z.number(),
+  })
+  .passthrough()
+
+const entryBulkUpdated = scope
+  .extend({
+    staffMemberId: z.string(),
+    created: z.number(),
+    updated: z.number(),
+    deleted: z.number(),
+    entryIds: z.array(z.string()),
+  })
+  .passthrough()
+
+/** `sourceId` is the entry the copy was made from; `date` only on the copy-day path. */
+const entryCopied = scope
+  .extend({
+    id: z.string(),
+    sourceId: z.string(),
+    staffMemberId: z.string().optional(),
+    date: z.string().optional(),
+  })
+  .passthrough()
+
+/** Batch-level: a report freeze/unfreeze names the report, never one entry. */
+const entryLockToggled = scope
+  .extend({
+    reportId: z.string(),
+  })
+  .passthrough()
+
+const segmentPayload = scope
+  .extend({
+    id: z.string(),
+    timeEntryId: z.string(),
+  })
+  .passthrough()
+
+const taskStatusChanged = scope
+  .extend({
+    id: z.string(),
+    taskId: z.string().optional(),
+    timeProjectId: z.string().optional(),
+    previousTaskStatusId: z.string().nullable().optional(),
+    taskStatusId: z.string().optional(),
+  })
+  .passthrough()
+
+/**
+ * No `customerId`: the event is `clientBroadcast: true` and the DOM Event Bridge
+ * applies no feature check, so the one field linking a report to a named client is
+ * withheld from the payload rather than from one of its two audiences — the same
+ * trade the amount already makes. The emitter documents the field-by-field call.
+ */
+const reportClosed = scope
+  .extend({
+    id: z.string(),
+    reportId: z.string(),
+    reference: z.string(),
+    lockedEntryCount: z.number(),
+    totalBillableMinutes: z.number(),
+    totalNonbillableMinutes: z.number(),
+  })
+  .passthrough()
+
+/**
+ * No `reason`: unlocking demands a written justification of up to 2000 characters,
+ * and this event reaches every browser in the organization with no feature check.
+ * The prose lives on the `StaffTimeReportEvent` audit row, behind the ACL.
+ */
+const reportUnlocked = scope
+  .extend({
+    id: z.string(),
+    reference: z.string(),
+    actorUserId: z.string().nullable(),
+    unlockedEntryCount: z.number(),
+  })
+  .passthrough()
+
+const reportExported = scope
+  .extend({
+    id: z.string(),
+    reference: z.string(),
+    format: z.string(),
+    grouping: z.string(),
+    rowCount: z.number(),
+  })
+  .passthrough()
+
+const reportPortalPublished = scope
+  .extend({
+    id: z.string(),
+    reference: z.string(),
+    periodFrom: z.string(),
+    periodTo: z.string(),
+    /**
+     * The portal SSE stream narrows a broadcast to these customer-user ids. The
+     * emitter never publishes this event with an empty list, so a report can only
+     * ever reach the portal users of its own customer.
+     */
+    recipientUserIds: z.array(z.string()).min(1),
+  })
+  .passthrough()
+
+const projectCurrencyChanged = scope
+  .extend({
+    id: z.string(),
+    currencyCode: z.string(),
+    previousCurrencyCode: z.string().nullable(),
+    converted: z.boolean(),
+  })
+  .passthrough()
+
+const budgetThresholdReached = scope
+  .extend({
+    id: z.string(),
+    timeProjectId: z.string(),
+    thresholdPercent: z.number(),
+    percent: z.number().nullable(),
+    budgetKind: z.string(),
+    /** Present only for an `hours` budget — an `amount` budget states money. */
+    budgetValue: z.number().nullable().optional(),
+    /** Present only for an `hours` budget — see `budgetValue`. */
+    usedValue: z.number().nullable().optional(),
+  })
+  .passthrough()
+
+const projectAccessRequested = scope
+  .extend({
+    requesterUserId: z.string(),
+    requesterName: z.string(),
+    timeProjectId: z.string().nullable(),
+    timeProjectName: z.string().nullable(),
+    requestedAt: z.string(),
+  })
+  .passthrough()
+
+const projectAccessDecision = scope.extend({ id: z.string() }).passthrough()
+
+const settingsUpdated = scope.extend({ settings: z.record(z.string(), z.unknown()) }).passthrough()
+
+const roundingReapplied = scope
+  .extend({
+    progressJobId: z.string(),
+    candidateCount: z.number(),
+  })
+  .passthrough()
+
+/**
+ * Every declared `staff.timesheets.*` event id and the payload a webhook endpoint
+ * subscribed to it receives.
+ */
+export const staffTimeTrackingEventPayloadSchemas = {
+  'staff.timesheets.time_entry.created': crudPayload,
+  'staff.timesheets.time_entry.updated': crudPayload,
+  'staff.timesheets.time_entry.deleted': crudPayload,
+  'staff.timesheets.time_entry.timer_started': timerStarted,
+  'staff.timesheets.time_entry.timer_stopped': timerStopped,
+  'staff.timesheets.time_entry.bulk_updated': entryBulkUpdated,
+  'staff.timesheets.time_entry.copied': entryCopied,
+  'staff.timesheets.time_entry.locked': entryLockToggled,
+  'staff.timesheets.time_entry.unlocked': entryLockToggled,
+  'staff.timesheets.time_entry_segment.created': segmentPayload,
+  'staff.timesheets.time_entry_segment.updated': segmentPayload,
+  'staff.timesheets.time_entry_segment.deleted': segmentPayload,
+  'staff.timesheets.time_project.created': crudPayload,
+  'staff.timesheets.time_project.updated': crudPayload,
+  'staff.timesheets.time_project.deleted': crudPayload,
+  'staff.timesheets.time_project.currency_changed': projectCurrencyChanged,
+  'staff.timesheets.time_project.budget_threshold_reached': budgetThresholdReached,
+  'staff.timesheets.time_project_member.created': crudPayload,
+  'staff.timesheets.time_project_member.updated': crudPayload,
+  'staff.timesheets.time_project_member.deleted': crudPayload,
+  'staff.timesheets.time_project_access.granted': projectAccessDecision,
+  'staff.timesheets.time_project_access.denied': projectAccessDecision,
+  'staff.timesheets.project_access.requested': projectAccessRequested,
+  'staff.timesheets.time_task.created': crudPayload,
+  'staff.timesheets.time_task.updated': crudPayload,
+  'staff.timesheets.time_task.deleted': crudPayload,
+  'staff.timesheets.time_task.status_changed': taskStatusChanged,
+  'staff.timesheets.time_task_status.created': crudPayload,
+  'staff.timesheets.time_task_status.updated': crudPayload,
+  'staff.timesheets.time_task_status.deleted': crudPayload,
+  'staff.timesheets.time_tag.created': crudPayload,
+  'staff.timesheets.time_tag.updated': crudPayload,
+  'staff.timesheets.time_tag.deleted': crudPayload,
+  'staff.timesheets.time_task_comment.created': crudPayload,
+  'staff.timesheets.time_task_comment.updated': crudPayload,
+  'staff.timesheets.time_task_comment.deleted': crudPayload,
+  'staff.timesheets.time_report.created': crudPayload,
+  'staff.timesheets.time_report.updated': crudPayload,
+  'staff.timesheets.time_report.deleted': crudPayload,
+  'staff.timesheets.time_report.closed': reportClosed,
+  'staff.timesheets.time_report.unlocked': reportUnlocked,
+  'staff.timesheets.time_report.exported': reportExported,
+  'staff.timesheets.time_report.portal_published': reportPortalPublished,
+  'staff.timesheets.time_tracking.settings_updated': settingsUpdated,
+  'staff.timesheets.time_tracking.rounding_reapplied': roundingReapplied,
+} as const
+
+export type StaffTimeTrackingEventId = keyof typeof staffTimeTrackingEventPayloadSchemas
+
+export type StaffTimeTrackingEventPayload<TEventId extends StaffTimeTrackingEventId> = z.infer<
+  typeof staffTimeTrackingEventPayloadSchemas[TEventId]
+>

package/src/modules/staff/events.ts

@@ -27,17 +27,99 @@ const events = [
   { id: 'staff.job_history.deleted', label: 'Job History Deleted', entity: 'job_history', category: 'crud' },
 
   // Timesheets (Phase 1)
-  { id: 'staff.timesheets.time_entry.created', label: 'Time Entry Created', entity: 'time_entry', category: 'crud' },
-  { id: 'staff.timesheets.time_entry.updated', label: 'Time Entry Updated', entity: 'time_entry', category: 'crud' },
-  { id: 'staff.timesheets.time_entry.deleted', label: 'Time Entry Deleted', entity: 'time_entry', category: 'crud' },
-  { id: 'staff.timesheets.time_entry.timer_started', label: 'Timer Started', entity: 'time_entry', category: 'lifecycle' },
-  { id: 'staff.timesheets.time_entry.timer_stopped', label: 'Timer Stopped', entity: 'time_entry', category: 'lifecycle' },
+  { id: 'staff.timesheets.time_entry.created', label: 'Time Entry Created', entity: 'time_entry', category: 'crud', clientBroadcast: true },
+  { id: 'staff.timesheets.time_entry.updated', label: 'Time Entry Updated', entity: 'time_entry', category: 'crud', clientBroadcast: true },
+  { id: 'staff.timesheets.time_entry.deleted', label: 'Time Entry Deleted', entity: 'time_entry', category: 'crud', clientBroadcast: true },
+  { id: 'staff.timesheets.time_entry.timer_started', label: 'Timer Started', entity: 'time_entry', category: 'lifecycle', clientBroadcast: true },
+  { id: 'staff.timesheets.time_entry.timer_stopped', label: 'Timer Stopped', entity: 'time_entry', category: 'lifecycle', clientBroadcast: true },
   { id: 'staff.timesheets.time_project.created', label: 'Time Project Created', entity: 'time_project', category: 'crud' },
   { id: 'staff.timesheets.time_project.updated', label: 'Time Project Updated', entity: 'time_project', category: 'crud' },
   { id: 'staff.timesheets.time_project.deleted', label: 'Time Project Deleted', entity: 'time_project', category: 'crud' },
   { id: 'staff.timesheets.time_project_member.created', label: 'Time Project Member Assigned', entity: 'time_project_member', category: 'crud' },
   { id: 'staff.timesheets.time_project_member.updated', label: 'Time Project Member Updated', entity: 'time_project_member', category: 'crud' },
   { id: 'staff.timesheets.time_project_member.deleted', label: 'Time Project Member Unassigned', entity: 'time_project_member', category: 'crud' },
+
+  // Time tracking (Phase 2)
+  { id: 'staff.timesheets.time_task.created', label: 'Time Task Created', entity: 'time_task', category: 'crud' },
+  { id: 'staff.timesheets.time_task.updated', label: 'Time Task Updated', entity: 'time_task', category: 'crud' },
+  { id: 'staff.timesheets.time_task.deleted', label: 'Time Task Deleted', entity: 'time_task', category: 'crud' },
+  { id: 'staff.timesheets.time_task.status_changed', label: 'Time Task Status Changed', entity: 'time_task', category: 'lifecycle', clientBroadcast: true },
+  { id: 'staff.timesheets.time_task_status.created', label: 'Time Task Status Created', entity: 'time_task_status', category: 'crud' },
+  { id: 'staff.timesheets.time_task_status.updated', label: 'Time Task Status Updated', entity: 'time_task_status', category: 'crud' },
+  { id: 'staff.timesheets.time_task_status.deleted', label: 'Time Task Status Deleted', entity: 'time_task_status', category: 'crud' },
+  { id: 'staff.timesheets.time_tag.created', label: 'Time Tag Created', entity: 'time_tag', category: 'crud' },
+  { id: 'staff.timesheets.time_tag.updated', label: 'Time Tag Updated', entity: 'time_tag', category: 'crud' },
+  { id: 'staff.timesheets.time_tag.deleted', label: 'Time Tag Deleted', entity: 'time_tag', category: 'crud' },
+  { id: 'staff.timesheets.time_task_comment.created', label: 'Time Task Comment Created', entity: 'time_task_comment', category: 'crud' },
+  { id: 'staff.timesheets.time_task_comment.updated', label: 'Time Task Comment Updated', entity: 'time_task_comment', category: 'crud' },
+  { id: 'staff.timesheets.time_task_comment.deleted', label: 'Time Task Comment Deleted', entity: 'time_task_comment', category: 'crud' },
+  { id: 'staff.timesheets.time_report.created', label: 'Time Report Created', entity: 'time_report', category: 'crud' },
+  { id: 'staff.timesheets.time_report.updated', label: 'Time Report Updated', entity: 'time_report', category: 'crud' },
+  { id: 'staff.timesheets.time_report.deleted', label: 'Time Report Deleted', entity: 'time_report', category: 'crud' },
+  { id: 'staff.timesheets.time_report.closed', label: 'Time Report Closed', entity: 'time_report', category: 'lifecycle', clientBroadcast: true },
+  { id: 'staff.timesheets.time_report.unlocked', label: 'Time Report Unlocked', entity: 'time_report', category: 'lifecycle', clientBroadcast: true },
+  { id: 'staff.timesheets.time_project.budget_threshold_reached', label: 'Time Project Budget Threshold Reached', entity: 'time_project', category: 'lifecycle', clientBroadcast: true },
+  { id: 'staff.timesheets.project_access.requested', label: 'Time Project Access Requested', entity: 'time_project', category: 'lifecycle' },
+
+  // `clientBroadcast: true` above puts the event on the DOM Event Bridge, whose only
+  // audience filter is tenant + organization (`events/api/stream/route.ts`): every
+  // signed-in user of the organization receives the payload, with no feature check.
+  // So a broadcast payload MUST NOT carry a rate, a cost or an amount — money is
+  // gated on `staff.timesheets.rates.view` (staff/AGENTS.md), a gate SSE cannot
+  // apply. `time_report.closed` and `time_project.budget_threshold_reached` emit
+  // their money fields conditionally for exactly this reason; see their emitters.
+  //
+  // Money is not the only thing that audience decides. The same absence of a feature
+  // check is why `time_report.unlocked` broadcasts no `reason` — the operator's
+  // mandatory, free-text unlock justification, which lives on the audit row instead —
+  // and why `time_report.closed` broadcasts no `customerId`.
+
+  // Time tracking (Phase 3) — transitions owned by the hand-rolled routes that sit
+  // beside the CRUD factory resources. Declared here so a third-party module can
+  // subscribe to a bulk grid save, a copy, a segment edit, an export or a settings
+  // change with the same contract the CRUD ids already offer.
+  { id: 'staff.timesheets.time_entry.bulk_updated', label: 'Time Entries Bulk Saved', entity: 'time_entry', category: 'lifecycle' },
+  { id: 'staff.timesheets.time_entry.copied', label: 'Time Entry Copied', entity: 'time_entry', category: 'lifecycle' },
+  { id: 'staff.timesheets.time_entry.locked', label: 'Time Entries Locked', entity: 'time_entry', category: 'lifecycle' },
+  { id: 'staff.timesheets.time_entry.unlocked', label: 'Time Entries Unlocked', entity: 'time_entry', category: 'lifecycle' },
+  { id: 'staff.timesheets.time_entry_segment.created', label: 'Time Entry Segment Created', entity: 'time_entry_segment', category: 'crud' },
+  { id: 'staff.timesheets.time_entry_segment.updated', label: 'Time Entry Segment Updated', entity: 'time_entry_segment', category: 'crud' },
+  { id: 'staff.timesheets.time_entry_segment.deleted', label: 'Time Entry Segment Deleted', entity: 'time_entry_segment', category: 'crud' },
+  { id: 'staff.timesheets.time_report.exported', label: 'Time Report Exported', entity: 'time_report', category: 'lifecycle' },
+  { id: 'staff.timesheets.time_project.currency_changed', label: 'Time Project Currency Changed', entity: 'time_project', category: 'lifecycle' },
+  { id: 'staff.timesheets.time_project_access.granted', label: 'Time Project Access Granted', entity: 'time_project', category: 'lifecycle' },
+  { id: 'staff.timesheets.time_project_access.denied', label: 'Time Project Access Denied', entity: 'time_project', category: 'lifecycle' },
+  { id: 'staff.timesheets.time_tracking.settings_updated', label: 'Time Tracking Settings Updated', entity: 'time_tracking', category: 'lifecycle' },
+  { id: 'staff.timesheets.time_tracking.rounding_reapplied', label: 'Time Tracking Rounding Reapplied', entity: 'time_tracking', category: 'lifecycle' },
+
+  // Time tracking (Phase 6) — the customer-portal bridge (EP-06 / EP-50).
+  //
+  // This is a SEPARATE id rather than `portalBroadcast: true` on
+  // `time_report.closed`, and the difference is a disclosure, not a style choice.
+  // The portal SSE stream (`customer_accounts/api/portal/events/stream.ts`)
+  // filters a broadcast by tenant + organization and narrows to specific people
+  // only when the payload carries `recipientUserId(s)`. One organization serves
+  // many customers, so flagging `time_report.closed` — which carries `reference`
+  // and the minute totals — would hand every client of the tenant a running feed
+  // of every other client's reports. `time_report.closed` also has
+  // `clientBroadcast: true` and a published webhook payload, so it cannot be
+  // narrowed without breaking its backoffice consumers.
+  //
+  // `subscribers/time-report-portal-broadcast.ts` is the only emitter: it pins
+  // `recipientUserIds` to the portal users of the report's own customer and does
+  // not emit at all when that list is empty — the rule
+  // `warranty_claims/AGENTS.md` states for its own portal event.
+  //
+  // Exports are deliberately not mirrored. An export changes nothing the portal
+  // renders; the portal reads the report, not the file.
+  {
+    id: 'staff.timesheets.time_report.portal_published',
+    label: 'Time Report Published To Portal',
+    entity: 'time_report',
+    category: 'lifecycle',
+    portalBroadcast: true,
+    excludeFromTriggers: true,
+  },
 ] as const
 
 export const eventsConfig = createModuleEvents({