@livetronics/wocul-domain 0.0.0-stage → 1.0.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.
package/README.md CHANGED
@@ -1,3 +1,92 @@
1
- # Temporary Holding Version
1
+ # @livetronics/wocul-domain
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The contracts Wocul's services share, in one place:
4
+
5
+ | Module | What it has |
6
+ | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
7
+ | events | every realtime event, intent, entity and actor name; a zod schema for each event's `data`; `parseMessage()` for a raw socket frame |
8
+ | channels | channel kinds, `channelName.task(42)`-style helpers, `parseChannel()`, the gateway's patterns |
9
+ | intents | intent stream names, which stream each intent goes to, payload schemas |
10
+ | api | Core API types generated from `packages/openapi/openapi.yaml` |
11
+
12
+ The server side of events and channels is described in core-ts
13
+ `docs/realtime-events.md`.
14
+
15
+ ## Using it
16
+
17
+ ```ts
18
+ import {
19
+ parseMessage,
20
+ isMessageOf,
21
+ channelName
22
+ } from '@livetronics/wocul-domain'
23
+
24
+ const result = parseMessage(JSON.parse(raw))
25
+ if (result.kind === 'known' && isMessageOf(result.message, 'task.changed')) {
26
+ result.message.data.idTask // number
27
+ }
28
+ // 'control': the gateway's own frames (ready, subscribed, unsubscribed,
29
+ // resync, error); route these before events.
30
+ // 'unknown': a newer server's type; treat it as a plain hint.
31
+ // 'invalid': not a frame; `error` names the field. parseMessage never throws.
32
+ ```
33
+
34
+ Intents arrive in a stream entry as JSON under `INTENT_FIELD` (`e`), in an
35
+ envelope whose `data` is the payload:
36
+
37
+ ```ts
38
+ import { INTENT_FIELD, parseIntent } from '@livetronics/wocul-domain'
39
+
40
+ const result = parseIntent(JSON.parse(entry[INTENT_FIELD]))
41
+ if (result.kind === 'known' && result.message.type === 'run.requested') {
42
+ result.message.data.idAgentRun // number
43
+ }
44
+ // On 'invalid', still claim by entity.id if you can: the queue row is the record.
45
+ ```
46
+
47
+ ```ts
48
+ import type {
49
+ ApiResponse,
50
+ ApiRequestBody,
51
+ api
52
+ } from '@livetronics/wocul-domain'
53
+
54
+ type Profile = ApiResponse<'/staffs/profile', 'get'>
55
+ type Schemas = api.components['schemas']
56
+ ```
57
+
58
+ API paths are relative to the API base (`/api`), as in the spec.
59
+
60
+ ## Rules the schemas follow
61
+
62
+ - **Only ids are required.** core-ts trims an oversized payload to its id
63
+ fields, so every other field may be missing.
64
+ - **Unknown fields pass through.** A server can add a field without a package
65
+ release; an unknown event type parses as `unknown`, not as an error.
66
+ - **Hints carry no content.** `data` holds ids, statuses and categories. Read
67
+ the thing itself through the API.
68
+
69
+ ## Changing it
70
+
71
+ - **A new event type or intent** goes into core-ts and here in the same PR.
72
+ `tests/coreParity.test.ts` reads core-ts's own lists and fails when they
73
+ differ.
74
+ - **An API change** goes into `packages/openapi/openapi.yaml`; then run
75
+ `npm run gen:api` here and commit `src/api/generated.ts`. CI runs
76
+ `npm run check:api`, which fails when the two differ. Do not edit or
77
+ format `generated.ts` by hand (it is excluded from prettier and eslint).
78
+ - **Checking against real data.** The fixtures are a sample of the dev outbox.
79
+ To check every row, export the outbox to JSON and run
80
+ `WOCUL_DOMAIN_DEV_FRAMES=frames.json WOCUL_DOMAIN_DEV_INTENTS=intents.json npm test`.
81
+
82
+ ## Publishing
83
+
84
+ Public on npm under the `livetronics` account, like `wocul-email-config`.
85
+ From this folder, after bumping `version`:
86
+
87
+ ```bash
88
+ npm publish # prepublishOnly runs check:api, the tests and the build
89
+ ```
90
+
91
+ Semver: a removed or renamed field, type or export is a major; a new event
92
+ type, field or route is a minor.