@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 +91 -2
- package/dist/api/generated.d.ts +39302 -0
- package/dist/api/generated.js +2 -0
- package/dist/api/index.d.ts +37 -0
- package/dist/api/index.js +2 -0
- package/dist/channels.d.ts +31 -0
- package/dist/channels.js +34 -0
- package/dist/events/data.d.ts +409 -0
- package/dist/events/data.js +135 -0
- package/dist/events/message.d.ts +188 -0
- package/dist/events/message.js +99 -0
- package/dist/events/types.d.ts +27 -0
- package/dist/events/types.js +83 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +45 -0
- package/dist/intents.d.ts +305 -0
- package/dist/intents.js +149 -0
- package/package.json +40 -5
package/README.md
CHANGED
|
@@ -1,3 +1,92 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @livetronics/wocul-domain
|
|
2
2
|
|
|
3
|
-
|
|
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.
|