@livetronics/wocul-domain 1.1.0 → 1.3.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,
@@ -40,9 +40,69 @@ const subTaskOf = { idTaskParent: id.optional() };
40
40
  * id among the tasks it shows.
41
41
  */
42
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
+ };
43
103
  exports.eventDataSchemas = {
44
104
  'task.created': zod_1.z
45
- .object({ idTask: id, ...logged, ...subTaskOf, ...onBoard })
105
+ .object({ idTask: id, ...logged, ...subTaskOf, ...onBoard, ...factual })
46
106
  .passthrough(),
47
107
  'task.changed': zod_1.z
48
108
  .object({
@@ -51,27 +111,35 @@ exports.eventDataSchemas = {
51
111
  ...subTaskOf,
52
112
  ...onBoard,
53
113
  idAssignee: id.optional(),
54
- idTaskComment: id.optional()
114
+ idTaskComment: id.optional(),
115
+ ...factual
55
116
  })
56
117
  .passthrough(),
57
118
  'task.removed': zod_1.z
58
- .object({ idTask: id, ...logged, ...subTaskOf, ...onBoard })
119
+ .object({ idTask: id, ...logged, ...subTaskOf, ...onBoard, ...factual })
59
120
  .passthrough(),
60
121
  'comment.changed': zod_1.z
61
- .object({ idTask: id, idTaskComment: id, ...logged })
122
+ .object({ idTask: id, idTaskComment: id, ...logged, ...factual })
62
123
  .passthrough(),
63
124
  'approval.changed': zod_1.z
64
- .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 })
65
135
  .passthrough(),
66
- 'board.changed': zod_1.z.object({ idSprint: id, ...logged }).passthrough(),
67
- 'project.changed': zod_1.z.object({ idProject: id, ...logged }).passthrough(),
68
- 'membership.changed': zod_1.z.object({ idProject: id, ...logged }).passthrough(),
69
136
  'okr.changed': zod_1.z
70
137
  .object({
71
138
  idObjective: id,
72
139
  ...logged,
73
140
  /** Every project the objective is mapped to. */
74
- projects: zod_1.z.array(id).optional()
141
+ projects: zod_1.z.array(id).optional(),
142
+ ...factual
75
143
  })
76
144
  .passthrough(),
77
145
  'run.changed': zod_1.z
@@ -82,7 +150,8 @@ exports.eventDataSchemas = {
82
150
  stepType: zod_1.z.string().optional(),
83
151
  stepStatus: zod_1.z.string().optional(),
84
152
  needsInput: zod_1.z.boolean().optional(),
85
- triggerType: zod_1.z.string().optional()
153
+ triggerType: zod_1.z.string().optional(),
154
+ ...factual
86
155
  })
87
156
  .passthrough(),
88
157
  'draft.changed': zod_1.z
@@ -91,40 +160,49 @@ exports.eventDataSchemas = {
91
160
  status: zod_1.z.string().optional(),
92
161
  actionType: zod_1.z.string().optional(),
93
162
  progress: zod_1.z.record(zod_1.z.unknown()).optional(),
94
- staff: staff.optional()
163
+ staff: staff.optional(),
164
+ ...factual
95
165
  })
96
166
  .passthrough(),
97
167
  'pulse.changed': zod_1.z
98
168
  .object({
99
169
  idFeedback: stringId,
100
170
  idSprint: id,
101
- status: zod_1.z.string().optional()
171
+ status: zod_1.z.string().optional(),
172
+ ...factual
102
173
  })
103
174
  .passthrough(),
104
175
  'kb.changed': zod_1.z
105
- .object({ idDocument: stringId, status: zod_1.z.string().optional() })
176
+ .object({ idDocument: stringId, status: zod_1.z.string().optional(), ...factual })
106
177
  .passthrough(),
107
178
  'cycle.closed': zod_1.z
108
179
  .object({
109
180
  idSprintCycle: id,
110
181
  idSprint: id,
111
- onTime: zod_1.z.boolean().optional()
182
+ onTime: zod_1.z.boolean().optional(),
183
+ ...factual
112
184
  })
113
185
  .passthrough(),
114
186
  'dictionary.profiled': zod_1.z
115
- .object({ idDataDictionary: id, idOrganisationDatabaseConnection: id })
187
+ .object({
188
+ idDataDictionary: id,
189
+ idOrganisationDatabaseConnection: id,
190
+ ...factual
191
+ })
116
192
  .passthrough(),
117
193
  'subscription.changed': zod_1.z
118
194
  .object({
119
195
  status: zod_1.z.string().optional(),
120
- category: zod_1.z.string().optional()
196
+ category: zod_1.z.string().optional(),
197
+ ...factual
121
198
  })
122
199
  .passthrough(),
123
200
  'deepwork.changed': zod_1.z
124
201
  .object({
125
202
  idDeepWorkSession: id,
126
203
  status: zod_1.z.string().optional(),
127
- staff: staff.optional()
204
+ staff: staff.optional(),
205
+ ...factual
128
206
  })
129
207
  .passthrough(),
130
208
  'plan.changed': zod_1.z
@@ -132,7 +210,8 @@ exports.eventDataSchemas = {
132
210
  idPlanRun: stringId,
133
211
  runType: zod_1.z.string().optional(),
134
212
  status: zod_1.z.string().optional(),
135
- staff: staff.optional()
213
+ staff: staff.optional(),
214
+ ...factual
136
215
  })
137
216
  .passthrough(),
138
217
  'notification.created': zod_1.z
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import type { RealtimeEventType } from './types';
2
+ import type { KnownFields, RealtimeEventType } from './types';
3
3
  import type { EventData } from './data';
4
4
  /**
5
5
  * The frame a realtime subscriber receives. core-ts's relay and
@@ -103,7 +103,7 @@ export declare const frameSchema: z.ZodObject<{
103
103
  export type Frame = z.infer<typeof frameSchema>;
104
104
  /** A frame whose type this package knows, with its `data` typed. */
105
105
  export type RealtimeMessage = {
106
- [T in RealtimeEventType]: Omit<Frame, 'type' | 'data'> & {
106
+ [T in RealtimeEventType]: Omit<KnownFields<Frame>, 'type' | 'data'> & {
107
107
  type: T;
108
108
  data: EventData<T>;
109
109
  };
@@ -25,3 +25,11 @@ export type ActorType = (typeof ACTOR_TYPES)[number];
25
25
  export declare const isDomainEventType: (value: unknown) => value is DomainEventType;
26
26
  export declare const isRealtimeEventType: (value: unknown) => value is RealtimeEventType;
27
27
  export declare const isIntentType: (value: unknown) => value is IntentType;
28
+ /**
29
+ * A passthrough schema's type without its index signature. `Omit` over a
30
+ * type with one keeps only the signature, so every named field would read
31
+ * as `unknown`; strip it first.
32
+ */
33
+ export type KnownFields<T> = {
34
+ [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
35
+ };
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, KnownFields } 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
@@ -280,7 +281,7 @@ export declare const intentMessageSchema: z.ZodObject<{
280
281
  export type IntentEnvelope = z.infer<typeof intentMessageSchema>;
281
282
  /** An intent whose type this package knows, with its payload typed. */
282
283
  export type IntentMessage = {
283
- [T in IntentType]: Omit<IntentEnvelope, 'type' | 'data'> & {
284
+ [T in IntentType]: Omit<KnownFields<IntentEnvelope>, 'type' | 'data'> & {
284
285
  type: T;
285
286
  data: IntentPayload<T>;
286
287
  };
@@ -303,3 +304,137 @@ 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
+ /**
317
+ * A domain-stream entry: the intent envelope plus who made the change
318
+ * (`actor`, null for the system with nobody behind it) and the entity's
319
+ * `version`. Both are optional: entries written before core 4.5 lack them.
320
+ * The actor type is a string, so a newer type does not invalidate an entry.
321
+ */
322
+ export declare const domainStreamEnvelopeSchema: z.ZodObject<{
323
+ eventId: z.ZodString;
324
+ type: z.ZodString;
325
+ idOrganisation: z.ZodNumber;
326
+ idProject: z.ZodNullable<z.ZodNumber>;
327
+ entity: z.ZodObject<{
328
+ type: z.ZodString;
329
+ id: z.ZodString;
330
+ }, "strip", z.ZodTypeAny, {
331
+ type: string;
332
+ id: string;
333
+ }, {
334
+ type: string;
335
+ id: string;
336
+ }>;
337
+ createdAt: z.ZodString;
338
+ data: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
339
+ } & {
340
+ version: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
341
+ actor: z.ZodOptional<z.ZodNullable<z.ZodObject<{
342
+ type: z.ZodString;
343
+ idStaff: z.ZodNullable<z.ZodNumber>;
344
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
345
+ type: z.ZodString;
346
+ idStaff: z.ZodNullable<z.ZodNumber>;
347
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
348
+ type: z.ZodString;
349
+ idStaff: z.ZodNullable<z.ZodNumber>;
350
+ }, z.ZodTypeAny, "passthrough">>>>;
351
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
352
+ eventId: z.ZodString;
353
+ type: z.ZodString;
354
+ idOrganisation: z.ZodNumber;
355
+ idProject: z.ZodNullable<z.ZodNumber>;
356
+ entity: z.ZodObject<{
357
+ type: z.ZodString;
358
+ id: z.ZodString;
359
+ }, "strip", z.ZodTypeAny, {
360
+ type: string;
361
+ id: string;
362
+ }, {
363
+ type: string;
364
+ id: string;
365
+ }>;
366
+ createdAt: z.ZodString;
367
+ data: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
368
+ } & {
369
+ version: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
370
+ actor: z.ZodOptional<z.ZodNullable<z.ZodObject<{
371
+ type: z.ZodString;
372
+ idStaff: z.ZodNullable<z.ZodNumber>;
373
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
374
+ type: z.ZodString;
375
+ idStaff: z.ZodNullable<z.ZodNumber>;
376
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
377
+ type: z.ZodString;
378
+ idStaff: z.ZodNullable<z.ZodNumber>;
379
+ }, z.ZodTypeAny, "passthrough">>>>;
380
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
381
+ eventId: z.ZodString;
382
+ type: z.ZodString;
383
+ idOrganisation: z.ZodNumber;
384
+ idProject: z.ZodNullable<z.ZodNumber>;
385
+ entity: z.ZodObject<{
386
+ type: z.ZodString;
387
+ id: z.ZodString;
388
+ }, "strip", z.ZodTypeAny, {
389
+ type: string;
390
+ id: string;
391
+ }, {
392
+ type: string;
393
+ id: string;
394
+ }>;
395
+ createdAt: z.ZodString;
396
+ data: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
397
+ } & {
398
+ version: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
399
+ actor: z.ZodOptional<z.ZodNullable<z.ZodObject<{
400
+ type: z.ZodString;
401
+ idStaff: z.ZodNullable<z.ZodNumber>;
402
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
403
+ type: z.ZodString;
404
+ idStaff: z.ZodNullable<z.ZodNumber>;
405
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
406
+ type: z.ZodString;
407
+ idStaff: z.ZodNullable<z.ZodNumber>;
408
+ }, z.ZodTypeAny, "passthrough">>>>;
409
+ }, z.ZodTypeAny, "passthrough">>;
410
+ export type DomainStreamEnvelope = z.infer<typeof domainStreamEnvelopeSchema>;
411
+ /** A domain-stream entry whose type this package knows, `data` typed. */
412
+ export type DomainStreamMessage = {
413
+ [T in DomainEventType]: Omit<KnownFields<DomainStreamEnvelope>, 'type' | 'data'> & {
414
+ type: T;
415
+ data: EventData<T>;
416
+ };
417
+ }[DomainEventType];
418
+ export type DomainStreamParseResult =
419
+ /**
420
+ * `factsError` when the event was fine but its facts were not: they are
421
+ * dropped and the event kept, so a reader loses a fact, not the event.
422
+ */
423
+ {
424
+ kind: 'known';
425
+ message: DomainStreamMessage;
426
+ factsError?: string;
427
+ }
428
+ /** A well-formed entry of a type this version does not know. */
429
+ | {
430
+ kind: 'unknown';
431
+ message: DomainStreamEnvelope;
432
+ } | {
433
+ kind: 'invalid';
434
+ error: string;
435
+ };
436
+ /**
437
+ * Validates one domain-stream entry: pass `JSON.parse(entry[INTENT_FIELD])`.
438
+ * Never throws. Unknown fields, facts included, pass through.
439
+ */
440
+ 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.domainStreamEnvelopeSchema = 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,77 @@ 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
+ * A domain-stream entry: the intent envelope plus who made the change
163
+ * (`actor`, null for the system with nobody behind it) and the entity's
164
+ * `version`. Both are optional: entries written before core 4.5 lack them.
165
+ * The actor type is a string, so a newer type does not invalidate an entry.
166
+ */
167
+ exports.domainStreamEnvelopeSchema = exports.intentMessageSchema.extend({
168
+ version: zod_1.z.number().int().nullable().optional(),
169
+ actor: zod_1.z
170
+ .object({ type: zod_1.z.string(), idStaff: zod_1.z.number().int().nullable() })
171
+ .passthrough()
172
+ .nullable()
173
+ .optional()
174
+ });
175
+ /**
176
+ * Validates one domain-stream entry: pass `JSON.parse(entry[INTENT_FIELD])`.
177
+ * Never throws. Unknown fields, facts included, pass through.
178
+ */
179
+ function parseDomainStreamEntry(raw) {
180
+ const envelope = exports.domainStreamEnvelopeSchema.safeParse(raw);
181
+ if (!envelope.success) {
182
+ const issue = envelope.error.issues[0];
183
+ return {
184
+ kind: 'invalid',
185
+ error: `${issue?.path.join('.') || 'message'}: ${issue?.message ?? 'not an entry'}`
186
+ };
187
+ }
188
+ const { type } = envelope.data;
189
+ if (!(0, types_1.isDomainEventType)(type)) {
190
+ return { kind: 'unknown', message: envelope.data };
191
+ }
192
+ const fields = (envelope.data.data ?? {});
193
+ const describe = (issue) => `${type}: data.${issue?.path.join('.') ?? ''} ${issue?.message ?? ''}`.trim();
194
+ const data = data_1.eventDataSchemas[type].safeParse(fields);
195
+ if (data.success) {
196
+ return {
197
+ kind: 'known',
198
+ message: {
199
+ ...envelope.data,
200
+ type,
201
+ data: data.data
202
+ }
203
+ };
204
+ }
205
+ // A bad fact costs the fact, not the event: when every issue is inside
206
+ // `facts`, keep the event without them and say why.
207
+ const onlyFacts = data.error.issues.every((issue) => issue.path[0] === 'facts');
208
+ if (onlyFacts) {
209
+ const rest = { ...fields };
210
+ delete rest.facts;
211
+ const withoutFacts = data_1.eventDataSchemas[type].safeParse(rest);
212
+ if (withoutFacts.success) {
213
+ return {
214
+ kind: 'known',
215
+ message: {
216
+ ...envelope.data,
217
+ type,
218
+ data: withoutFacts.data
219
+ },
220
+ factsError: describe(data.error.issues[0])
221
+ };
222
+ }
223
+ }
224
+ return { kind: 'invalid', error: describe(data.error.issues[0]) };
225
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@livetronics/wocul-domain",
3
- "version": "1.1.0",
3
+ "version": "1.3.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",