@open-mercato/shared 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/events/__tests__/factory.test.ts

@@ -1,3 +1,99 @@
+/**
+ * Events factory — payloadSchema declaration and the generated CRUD default.
+ *
+ * Verifies the additive `payloadSchema` contract on `EventDefinition`:
+ * platform CRUD after-events (`*.created`/`*.updated`/`*.deleted`, category
+ * `crud`) receive the generated `{ id, organizationId, tenantId, syncOrigin }`
+ * default; explicit declarations are preserved untouched; lifecycle/system
+ * events and CRUD "before" events get no default; and `getDeclaredEvents()`
+ * exposes the same definitions the module config carries.
+ */
+
+import {
+  createModuleEvents,
+  getDeclaredEvents,
+  DEFAULT_CRUD_PAYLOAD_SCHEMA,
+} from '../factory'
+import type { EventPayloadSchema } from '../types'
+
+const explicitSchema: EventPayloadSchema = {
+  fields: [
+    { path: 'id', type: 'text' },
+    { path: 'amount', type: 'number', optional: true },
+    { path: 'meta', type: 'object' },
+  ],
+}
+
+const config = createModuleEvents({
+  moduleId: 'factory_test',
+  events: [
+    { id: 'factory_test.widget.created', label: 'Widget Created', entity: 'widget', category: 'crud' },
+    { id: 'factory_test.widget.updated', label: 'Widget Updated', entity: 'widget', category: 'crud' },
+    { id: 'factory_test.widget.deleted', label: 'Widget Deleted', entity: 'widget', category: 'crud' },
+    { id: 'factory_test.widget.creating', label: 'Widget Creating', entity: 'widget', category: 'crud', excludeFromTriggers: true },
+    { id: 'factory_test.widget.archived', label: 'Widget Archived', entity: 'widget', category: 'lifecycle' },
+    { id: 'factory_test.widget.scored', label: 'Widget Scored', entity: 'widget', category: 'lifecycle', payloadSchema: explicitSchema },
+    { id: 'factory_test.widget.replaced', label: 'Widget Replaced', entity: 'widget', category: 'crud', payloadSchema: explicitSchema },
+  ] as const,
+})
+
+function findEvent(id: string) {
+  const event = config.events.find(e => e.id === id)
+  if (!event) throw new Error(`[internal] event ${id} missing from config`)
+  return event
+}
+
+describe('createModuleEvents payloadSchema', () => {
+  it('attaches the generated CRUD default to platform CRUD after-events', () => {
+    for (const suffix of ['created', 'updated', 'deleted']) {
+      expect(findEvent(`factory_test.widget.${suffix}`).payloadSchema).toEqual(DEFAULT_CRUD_PAYLOAD_SCHEMA)
+    }
+  })
+
+  it('generated default mirrors the engine emit payload fields', () => {
+    expect(DEFAULT_CRUD_PAYLOAD_SCHEMA.fields.map(f => f.path)).toEqual([
+      'id',
+      'organizationId',
+      'tenantId',
+      'syncOrigin',
+    ])
+    const idField = DEFAULT_CRUD_PAYLOAD_SCHEMA.fields.find(f => f.path === 'id')
+    expect(idField).toEqual({ path: 'id', type: 'text' })
+    expect(DEFAULT_CRUD_PAYLOAD_SCHEMA.fields.filter(f => f.optional).map(f => f.path)).toEqual([
+      'organizationId',
+      'tenantId',
+      'syncOrigin',
+    ])
+  })
+
+  it('does not default CRUD "before" lifecycle suffixes or non-crud categories', () => {
+    expect(findEvent('factory_test.widget.creating').payloadSchema).toBeUndefined()
+    expect(findEvent('factory_test.widget.archived').payloadSchema).toBeUndefined()
+  })
+
+  it('preserves an explicit payloadSchema over the generated default', () => {
+    expect(findEvent('factory_test.widget.replaced').payloadSchema).toBe(explicitSchema)
+    expect(findEvent('factory_test.widget.scored').payloadSchema).toBe(explicitSchema)
+  })
+
+  it('exposes the same definitions through getDeclaredEvents()', () => {
+    const declared = getDeclaredEvents().filter(e => e.module === 'factory_test')
+    expect(declared).toHaveLength(config.events.length)
+    const declaredCreated = declared.find(e => e.id === 'factory_test.widget.created')
+    expect(declaredCreated?.payloadSchema).toEqual(DEFAULT_CRUD_PAYLOAD_SCHEMA)
+    const declaredScored = declared.find(e => e.id === 'factory_test.widget.scored')
+    expect(declaredScored?.payloadSchema).toBe(explicitSchema)
+  })
+
+  it('keeps unrelated declaration fields intact when defaulting', () => {
+    const creating = findEvent('factory_test.widget.creating')
+    expect(creating.excludeFromTriggers).toBe(true)
+    const created = findEvent('factory_test.widget.created')
+    expect(created.module).toBe('factory_test')
+    expect(created.entity).toBe('widget')
+  })
+})
+
 const GLOBAL_EVENT_REGISTRY_KEY = '__openMercatoEventDefinitionRegistry__'
 
 type EventFactoryModule = typeof import('../factory')

package/src/modules/events/factory.ts

@@ -9,6 +9,7 @@ import type {
   EventDefinition,
   EventModuleConfig,
   EventPayload,
+  EventPayloadSchema,
   EmitOptions,
   CreateModuleEventsOptions,
   ModuleEventEmitter,
@@ -101,18 +102,44 @@ function getEventRegistryState(): EventRegistryState {
   }
 }
 
+const CRUD_AFTER_EVENT_SUFFIXES = ['.created', '.updated', '.deleted'] as const
+
+/**
+ * Generated payload schema for platform-emitted CRUD after-events. Mirrors the
+ * default payload built by the data engine's `emitOrmEntityEvent` when no
+ * `buildPayload` override is configured: `{ id, organizationId, tenantId }`
+ * plus `syncOrigin` when the write originated from a sync. organizationId and
+ * tenantId keys are always present but may be null, so they are `optional`.
+ */
+export const DEFAULT_CRUD_PAYLOAD_SCHEMA: EventPayloadSchema = {
+  fields: [
+    { path: 'id', type: 'text' },
+    { path: 'organizationId', type: 'text', optional: true },
+    { path: 'tenantId', type: 'text', optional: true },
+    { path: 'syncOrigin', type: 'text', optional: true },
+  ],
+}
+
+function applyDefaultCrudPayloadSchema(event: EventDefinition): EventDefinition {
+  if (event.payloadSchema) return event
+  if (event.category !== 'crud') return event
+  if (!CRUD_AFTER_EVENT_SUFFIXES.some(suffix => event.id.endsWith(suffix))) return event
+  return { ...event, payloadSchema: DEFAULT_CRUD_PAYLOAD_SCHEMA }
+}
+
 function addDeclaredEvent(event: EventDefinition): void {
+  const declared = applyDefaultCrudPayloadSchema(event)
   const state = getEventRegistryState()
-  state.declaredEventIds.add(event.id)
-  const existingIndex = state.declaredEvents.findIndex((candidate) => candidate.id === event.id)
+  state.declaredEventIds.add(declared.id)
+  const existingIndex = state.declaredEvents.findIndex((candidate) => candidate.id === declared.id)
   if (existingIndex < 0) {
-    state.declaredEvents.push(event)
+    state.declaredEvents.push(declared)
     return
   }
   // Refresh a module's own definition in place during HMR without allowing a
   // duplicate declaration from another module to take over the event id.
-  if (state.declaredEvents[existingIndex]?.module === event.module) {
-    state.declaredEvents[existingIndex] = event
+  if (state.declaredEvents[existingIndex]?.module === declared.module) {
+    state.declaredEvents[existingIndex] = declared
   }
 }
 
@@ -271,11 +298,15 @@ export function createModuleEvents<
   // Build set of valid event IDs for runtime validation
   const validEventIds = new Set(events.map(e => e.id))
 
-  // Build full event definitions with module added
-  const fullEvents: EventDefinition[] = events.map(e => ({
-    ...e,
-    module: moduleId,
-  }))
+  // Build full event definitions with module added and the generated CRUD
+  // payload-schema default applied, so config consumers and the global
+  // registry see the same definitions.
+  const fullEvents: EventDefinition[] = events.map(e =>
+    applyDefaultCrudPayloadSchema({
+      ...e,
+      module: moduleId,
+    }),
+  )
 
   // Register all event IDs and definitions in the global registry.
   for (const event of fullEvents) {

package/src/modules/events/types.ts

@@ -14,6 +14,43 @@
  */
 export type EventCategory = 'crud' | 'lifecycle' | 'system' | 'custom'
 
+/**
+ * Type vocabulary for declared event payload fields. Mirrors the flat
+ * path/type contract consumed by editor surfaces (path pickers, typed value
+ * controls, the workflows context ledger), so declarations flow into those
+ * consumers without translation.
+ */
+export type EventPayloadFieldType =
+  | 'text'
+  | 'number'
+  | 'boolean'
+  | 'select'
+  | 'date'
+  | 'object'
+  | 'unknown'
+
+/**
+ * One declared payload field: a flat dot-path into the emitted payload plus
+ * its type. `optional` marks fields whose key may be absent or whose value may
+ * be null on some emits.
+ */
+export interface EventPayloadSchemaField {
+  path: string
+  type: EventPayloadFieldType
+  label?: string
+  optional?: boolean
+}
+
+/**
+ * Optional payload typing for an event declaration. A flat field list (not a
+ * nested JSON Schema): nested payload shapes are declared as dot-paths
+ * (`customer.id`) or a single `object`-typed entry. Declare only fields the
+ * emitter verifiably sends.
+ */
+export interface EventPayloadSchema {
+  fields: ReadonlyArray<EventPayloadSchemaField>
+}
+
 /**
  * Event definition structure
  */
@@ -38,6 +75,13 @@ export interface EventDefinition {
   crossProcessBroadcast?: boolean
   /** When true, this event is bridged to the customer portal via SSE (Portal Event Bridge). Default: false */
   portalBroadcast?: boolean
+  /**
+   * Optional declared payload typing. Platform-emitted CRUD events
+   * (`*.created`/`*.updated`/`*.deleted` with category `crud`) receive a
+   * generated default at registration time; other events carry it only when
+   * the declaring module opts in.
+   */
+  payloadSchema?: EventPayloadSchema
 }
 
 // =============================================================================