@livetronics/wocul-domain 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.eventDataSchemas = void 0;
3
+ exports.eventDataSchemas = exports.eventFactsSchema = void 0;
4
4
  const zod_1 = require("zod");
5
5
  /**
6
6
  * The `data` each realtime event carries: ids, statuses and categories,
@@ -27,32 +27,119 @@ const logged = {
27
27
  /** People whose own lists change, told on staff:<id>. */
28
28
  staff: staff.optional()
29
29
  };
30
+ /**
31
+ * A sub-task's parent. A sub-task's task.* event is also published on
32
+ * task:<idTaskParent>, where the parent's panel lists its sub-tasks.
33
+ */
34
+ const subTaskOf = { idTaskParent: id.optional() };
35
+ /**
36
+ * The board the task is on as the event goes out, or null when it is on
37
+ * none. Absent from producers before core 4.2: a board treats a missing
38
+ * value as possibly its own. A task that left a board (moved, removed,
39
+ * deleted) names its new board or null; the board it left knows it by the
40
+ * id among the tasks it shows.
41
+ */
42
+ const onBoard = { idSprint: id.nullable().optional() };
43
+ /**
44
+ * What a change did that a later reader cannot read back (core-ts
45
+ * `EventFacts`, docs/realtime-events.md § Facts): who was added or removed,
46
+ * a value before the change, who a notification is for. Server consumers
47
+ * (notification-ts's rules) read them; clients may ignore them.
48
+ *
49
+ * Coded values (`origin`, `decision`, `purpose`, the status codes) are
50
+ * strings, not enums, so a newer server's new value does not make an older
51
+ * reader drop the event. Known values are listed beside each.
52
+ */
53
+ const idList = zod_1.z.array(id);
54
+ exports.eventFactsSchema = zod_1.z
55
+ .object({
56
+ /** Staff this change added: approvers, watchers, board members, invitees. */
57
+ idStaffAdded: idList.optional(),
58
+ /** Staff this change removed; the rows are gone by the time it is read. */
59
+ idStaffRemoved: idList.optional(),
60
+ /** Staff @mentioned for the first time by this change. */
61
+ idStaffMentioned: idList.optional(),
62
+ /** A column move: PENDING, RESOLVED, COMPLETED… before and after. */
63
+ statusFrom: zod_1.z.string().nullable().optional(),
64
+ statusTo: zod_1.z.string().nullable().optional(),
65
+ idKanbanColumnFrom: id.nullable().optional(),
66
+ idKanbanColumnTo: id.nullable().optional(),
67
+ /** The assignee before an assignee change; null when there was none. */
68
+ idAssigneePrevious: id.nullable().optional(),
69
+ priorityFrom: zod_1.z.string().nullable().optional(),
70
+ idKeyResultPrevious: id.nullable().optional(),
71
+ idTaskQuestion: id.optional(),
72
+ /** APPROVED or CHANGES_REQUESTED. */
73
+ decision: zod_1.z.string().optional(),
74
+ /** CREATE, BULK_IMPORT or ROUTINE. */
75
+ origin: zod_1.z.string().optional(),
76
+ /** Why the agent wrote a comment: AI_REPLY or ASSIGNEE_WELCOME. */
77
+ purpose: zod_1.z.string().optional(),
78
+ /** The one person a change is for; null when nobody is to be told. */
79
+ idStaffAddressed: id.nullable().optional(),
80
+ /** Who a feedback is about. */
81
+ idStaffSubject: idList.optional(),
82
+ idFeedback: id.optional(),
83
+ /** Everyone a group deep work session had when it ended. */
84
+ idStaffParticipants: idList.optional(),
85
+ durationSeconds: zod_1.z.number().int().nonnegative().optional(),
86
+ runCode: zod_1.z.string().optional(),
87
+ /** A timer event's due moment, ISO 8601. */
88
+ deadline: zod_1.z.string().optional(),
89
+ endDate: zod_1.z.string().optional(),
90
+ /** Why something stopped (a paused routine), and when. */
91
+ reasonCode: zod_1.z.string().optional(),
92
+ pausedAt: zod_1.z.string().optional(),
93
+ /** Tasks a finished import created, or a board's open tasks. */
94
+ count: zod_1.z.number().int().nonnegative().optional(),
95
+ idSprint: id.optional()
96
+ })
97
+ .passthrough();
98
+ /** On every domain event; `factsDropped` when a cut payload lost its facts. */
99
+ const factual = {
100
+ facts: exports.eventFactsSchema.optional(),
101
+ factsDropped: zod_1.z.boolean().optional()
102
+ };
30
103
  exports.eventDataSchemas = {
31
- 'task.created': zod_1.z.object({ idTask: id, ...logged }).passthrough(),
104
+ 'task.created': zod_1.z
105
+ .object({ idTask: id, ...logged, ...subTaskOf, ...onBoard, ...factual })
106
+ .passthrough(),
32
107
  'task.changed': zod_1.z
33
108
  .object({
34
109
  idTask: id,
35
110
  ...logged,
111
+ ...subTaskOf,
112
+ ...onBoard,
36
113
  idAssignee: id.optional(),
37
- idTaskComment: id.optional()
114
+ idTaskComment: id.optional(),
115
+ ...factual
38
116
  })
39
117
  .passthrough(),
40
- 'task.removed': zod_1.z.object({ idTask: id, ...logged }).passthrough(),
118
+ 'task.removed': zod_1.z
119
+ .object({ idTask: id, ...logged, ...subTaskOf, ...onBoard, ...factual })
120
+ .passthrough(),
41
121
  'comment.changed': zod_1.z
42
- .object({ idTask: id, idTaskComment: id, ...logged })
122
+ .object({ idTask: id, idTaskComment: id, ...logged, ...factual })
43
123
  .passthrough(),
44
124
  'approval.changed': zod_1.z
45
- .object({ idTask: id, ...logged, idTaskComment: id.optional() })
125
+ .object({ idTask: id, ...logged, idTaskComment: id.optional(), ...factual })
126
+ .passthrough(),
127
+ 'board.changed': zod_1.z
128
+ .object({ idSprint: id, ...logged, ...factual })
129
+ .passthrough(),
130
+ 'project.changed': zod_1.z
131
+ .object({ idProject: id, ...logged, ...factual })
132
+ .passthrough(),
133
+ 'membership.changed': zod_1.z
134
+ .object({ idProject: id, ...logged, ...factual })
46
135
  .passthrough(),
47
- 'board.changed': zod_1.z.object({ idSprint: id, ...logged }).passthrough(),
48
- 'project.changed': zod_1.z.object({ idProject: id, ...logged }).passthrough(),
49
- 'membership.changed': zod_1.z.object({ idProject: id, ...logged }).passthrough(),
50
136
  'okr.changed': zod_1.z
51
137
  .object({
52
138
  idObjective: id,
53
139
  ...logged,
54
140
  /** Every project the objective is mapped to. */
55
- projects: zod_1.z.array(id).optional()
141
+ projects: zod_1.z.array(id).optional(),
142
+ ...factual
56
143
  })
57
144
  .passthrough(),
58
145
  'run.changed': zod_1.z
@@ -63,7 +150,8 @@ exports.eventDataSchemas = {
63
150
  stepType: zod_1.z.string().optional(),
64
151
  stepStatus: zod_1.z.string().optional(),
65
152
  needsInput: zod_1.z.boolean().optional(),
66
- triggerType: zod_1.z.string().optional()
153
+ triggerType: zod_1.z.string().optional(),
154
+ ...factual
67
155
  })
68
156
  .passthrough(),
69
157
  'draft.changed': zod_1.z
@@ -72,40 +160,49 @@ exports.eventDataSchemas = {
72
160
  status: zod_1.z.string().optional(),
73
161
  actionType: zod_1.z.string().optional(),
74
162
  progress: zod_1.z.record(zod_1.z.unknown()).optional(),
75
- staff: staff.optional()
163
+ staff: staff.optional(),
164
+ ...factual
76
165
  })
77
166
  .passthrough(),
78
167
  'pulse.changed': zod_1.z
79
168
  .object({
80
169
  idFeedback: stringId,
81
170
  idSprint: id,
82
- status: zod_1.z.string().optional()
171
+ status: zod_1.z.string().optional(),
172
+ ...factual
83
173
  })
84
174
  .passthrough(),
85
175
  'kb.changed': zod_1.z
86
- .object({ idDocument: stringId, status: zod_1.z.string().optional() })
176
+ .object({ idDocument: stringId, status: zod_1.z.string().optional(), ...factual })
87
177
  .passthrough(),
88
178
  'cycle.closed': zod_1.z
89
179
  .object({
90
180
  idSprintCycle: id,
91
181
  idSprint: id,
92
- onTime: zod_1.z.boolean().optional()
182
+ onTime: zod_1.z.boolean().optional(),
183
+ ...factual
93
184
  })
94
185
  .passthrough(),
95
186
  'dictionary.profiled': zod_1.z
96
- .object({ idDataDictionary: id, idOrganisationDatabaseConnection: id })
187
+ .object({
188
+ idDataDictionary: id,
189
+ idOrganisationDatabaseConnection: id,
190
+ ...factual
191
+ })
97
192
  .passthrough(),
98
193
  'subscription.changed': zod_1.z
99
194
  .object({
100
195
  status: zod_1.z.string().optional(),
101
- category: zod_1.z.string().optional()
196
+ category: zod_1.z.string().optional(),
197
+ ...factual
102
198
  })
103
199
  .passthrough(),
104
200
  'deepwork.changed': zod_1.z
105
201
  .object({
106
202
  idDeepWorkSession: id,
107
203
  status: zod_1.z.string().optional(),
108
- staff: staff.optional()
204
+ staff: staff.optional(),
205
+ ...factual
109
206
  })
110
207
  .passthrough(),
111
208
  'plan.changed': zod_1.z
@@ -113,7 +210,8 @@ exports.eventDataSchemas = {
113
210
  idPlanRun: stringId,
114
211
  runType: zod_1.z.string().optional(),
115
212
  status: zod_1.z.string().optional(),
116
- staff: staff.optional()
213
+ staff: staff.optional(),
214
+ ...factual
117
215
  })
118
216
  .passthrough(),
119
217
  'notification.created': zod_1.z
package/dist/intents.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { z } from 'zod';
2
- import type { IntentType } from './events/types';
2
+ import type { DomainEventType, IntentType } from './events/types';
3
+ import type { EventData } from './events/data';
3
4
  /**
4
5
  * Intents: outbox rows core-ts's relay sends to one service's Redis stream
5
6
  * (XADD, field `e`) instead of a channel. Each wakes its consumer to claim a
@@ -303,3 +304,42 @@ export type IntentParseResult = {
303
304
  * `entity.id` if it can, since the queue row is the record.
304
305
  */
305
306
  export declare function parseIntent(raw: unknown): IntentParseResult;
307
+ /**
308
+ * Every domain event, for server consumers (core-ts docs/realtime-events.md
309
+ * § Domain stream): notification-ts's rules read it to decide who hears
310
+ * about a change. Written by core-ts's relay with EVENTS_DOMAIN_STREAM_ENABLED.
311
+ * Entries have the intent shape: one field, `INTENT_FIELD`, holding the
312
+ * envelope as JSON, `data` being the event's payload with its facts.
313
+ * Delivery is at-least-once: dedupe on `eventId`.
314
+ */
315
+ export declare const DOMAIN_EVENT_STREAM = "wocul:events:domain";
316
+ /** A domain-stream entry whose type this package knows, `data` typed. */
317
+ export type DomainStreamMessage = {
318
+ [T in DomainEventType]: Omit<IntentEnvelope, 'type' | 'data'> & {
319
+ type: T;
320
+ data: EventData<T>;
321
+ };
322
+ }[DomainEventType];
323
+ export type DomainStreamParseResult =
324
+ /**
325
+ * `factsError` when the event was fine but its facts were not: they are
326
+ * dropped and the event kept, so a reader loses a fact, not the event.
327
+ */
328
+ {
329
+ kind: 'known';
330
+ message: DomainStreamMessage;
331
+ factsError?: string;
332
+ }
333
+ /** A well-formed entry of a type this version does not know. */
334
+ | {
335
+ kind: 'unknown';
336
+ message: IntentEnvelope;
337
+ } | {
338
+ kind: 'invalid';
339
+ error: string;
340
+ };
341
+ /**
342
+ * Validates one domain-stream entry: pass `JSON.parse(entry[INTENT_FIELD])`.
343
+ * Never throws. Unknown fields, facts included, pass through.
344
+ */
345
+ export declare function parseDomainStreamEntry(raw: unknown): DomainStreamParseResult;
package/dist/intents.js CHANGED
@@ -1,9 +1,11 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.intentMessageSchema = exports.intentPayloadSchemas = exports.INTENT_FIELD = exports.INTENT_STREAM_OF = exports.INTENT_STREAMS = void 0;
3
+ exports.DOMAIN_EVENT_STREAM = exports.intentMessageSchema = exports.intentPayloadSchemas = exports.INTENT_FIELD = exports.INTENT_STREAM_OF = exports.INTENT_STREAMS = void 0;
4
4
  exports.parseIntent = parseIntent;
5
+ exports.parseDomainStreamEntry = parseDomainStreamEntry;
5
6
  const zod_1 = require("zod");
6
7
  const types_1 = require("./events/types");
8
+ const data_1 = require("./events/data");
7
9
  /**
8
10
  * Intents: outbox rows core-ts's relay sends to one service's Redis stream
9
11
  * (XADD, field `e`) instead of a channel. Each wakes its consumer to claim a
@@ -147,3 +149,63 @@ function parseIntent(raw) {
147
149
  message: { ...envelope.data, type, data: payload.data }
148
150
  };
149
151
  }
152
+ /**
153
+ * Every domain event, for server consumers (core-ts docs/realtime-events.md
154
+ * § Domain stream): notification-ts's rules read it to decide who hears
155
+ * about a change. Written by core-ts's relay with EVENTS_DOMAIN_STREAM_ENABLED.
156
+ * Entries have the intent shape: one field, `INTENT_FIELD`, holding the
157
+ * envelope as JSON, `data` being the event's payload with its facts.
158
+ * Delivery is at-least-once: dedupe on `eventId`.
159
+ */
160
+ exports.DOMAIN_EVENT_STREAM = 'wocul:events:domain';
161
+ /**
162
+ * Validates one domain-stream entry: pass `JSON.parse(entry[INTENT_FIELD])`.
163
+ * Never throws. Unknown fields, facts included, pass through.
164
+ */
165
+ function parseDomainStreamEntry(raw) {
166
+ const envelope = exports.intentMessageSchema.safeParse(raw);
167
+ if (!envelope.success) {
168
+ const issue = envelope.error.issues[0];
169
+ return {
170
+ kind: 'invalid',
171
+ error: `${issue?.path.join('.') || 'message'}: ${issue?.message ?? 'not an entry'}`
172
+ };
173
+ }
174
+ const { type } = envelope.data;
175
+ if (!(0, types_1.isDomainEventType)(type)) {
176
+ return { kind: 'unknown', message: envelope.data };
177
+ }
178
+ const fields = (envelope.data.data ?? {});
179
+ const describe = (issue) => `${type}: data.${issue?.path.join('.') ?? ''} ${issue?.message ?? ''}`.trim();
180
+ const data = data_1.eventDataSchemas[type].safeParse(fields);
181
+ if (data.success) {
182
+ return {
183
+ kind: 'known',
184
+ message: {
185
+ ...envelope.data,
186
+ type,
187
+ data: data.data
188
+ }
189
+ };
190
+ }
191
+ // A bad fact costs the fact, not the event: when every issue is inside
192
+ // `facts`, keep the event without them and say why.
193
+ const onlyFacts = data.error.issues.every((issue) => issue.path[0] === 'facts');
194
+ if (onlyFacts) {
195
+ const rest = { ...fields };
196
+ delete rest.facts;
197
+ const withoutFacts = data_1.eventDataSchemas[type].safeParse(rest);
198
+ if (withoutFacts.success) {
199
+ return {
200
+ kind: 'known',
201
+ message: {
202
+ ...envelope.data,
203
+ type,
204
+ data: withoutFacts.data
205
+ },
206
+ factsError: describe(data.error.issues[0])
207
+ };
208
+ }
209
+ }
210
+ return { kind: 'invalid', error: describe(data.error.issues[0]) };
211
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@livetronics/wocul-domain",
3
- "version": "1.0.0",
3
+ "version": "1.2.0",
4
4
  "description": "Shared Wocul domain contracts: realtime event and intent schemas, channel names, and Core API types generated from the OpenAPI spec",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",