@crossworks/client-types 0.400.16 → 0.400.24

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crossworks/client-types",
3
- "version": "0.400.16",
3
+ "version": "0.400.24",
4
4
  "type": "module",
5
5
  "main": "./src/index.ts",
6
6
  "types": "./src/index.ts",
@@ -0,0 +1,96 @@
1
+ /**
2
+ * Calls between people (calls plan page 886126b4, sections 5, 8, 9 and 20):
3
+ * a call is a LiveKit room named after a messenger conversation. The routes
4
+ * live under /api/messenger; the brain mints every token and never hands
5
+ * out an admin grant. The system lines that mark a call ride the message
6
+ * stream (MessengerMessage.event, dto/messenger.ts).
7
+ */
8
+
9
+ /** GET /api/messenger/capabilities, cached a minute client-side. */
10
+ export type MessengerCapabilities = {
11
+ /** The Calls service is on for this brain: show the Call button. */
12
+ calls: boolean;
13
+ /** The agent worker is registered on this box (P2): show the assistant
14
+ * row's Call button only then. */
15
+ callsAgent: boolean;
16
+ /** Always false in P1. */
17
+ video: false;
18
+ };
19
+
20
+ /**
21
+ * The ICE override of section 20. LiveKit tells a browser to reach its
22
+ * TURN/TLS server on port 443, which Caddy holds; the brain hands the client
23
+ * the same credential pair with the port LiveKit really listens on. The
24
+ * client passes this as `rtcConfig.iceServers` (and nothing else) when it
25
+ * connects; `username` is the room's name and `credential` the room's TURN
26
+ * password, as LiveKit minted them. Null when the box has no calls host or
27
+ * TURN is off: connect with LiveKit's own list then.
28
+ */
29
+ export type MessengerCallIce = {
30
+ /** turns:<host>:5349?transport=tcp first, then turn:<host>:3478?transport=udp. */
31
+ urls: string[];
32
+ username: string;
33
+ credential: string;
34
+ };
35
+
36
+ /** POST /api/messenger/c/:id/call, .../call/token, and the assistant twins
37
+ * POST /api/assistant/:agentId/call, .../call/token. */
38
+ export type MessengerCallJoinResponse = {
39
+ /** The call row (GET .../calls); null for a call with your own assistant,
40
+ * which has no row. */
41
+ callId: string | null;
42
+ /** The LiveKit room: msgr-<conversationId>, or asst-<agentId>-<loginId>. */
43
+ room: string;
44
+ /** The signalling URL (wss://<site>/livekit behind Caddy). */
45
+ url: string;
46
+ /** A one-hour JWT for this login in this room: join, publish the
47
+ * microphone, subscribe, send data. Refresh before `expiresAt`. */
48
+ token: string;
49
+ expiresAt: string;
50
+ ice: MessengerCallIce | null;
51
+ };
52
+
53
+ /** POST .../call and the assistant twin take this body. */
54
+ export type MessengerCallStartRequest = {
55
+ /** What this client is ("web", "desktop", "phone"), at most 32 chars. */
56
+ device?: string | null;
57
+ };
58
+
59
+ export type MessengerCallEndedReason =
60
+ 'finished' | 'cap_reached' | 'closed_by_admin' | 'service_off' | 'reconciled';
61
+
62
+ export type MessengerCallParticipant = {
63
+ kind: 'login' | 'agent';
64
+ /** The login id or the agent id. */
65
+ id: string;
66
+ joinedAt: string;
67
+ /** Null while the stay is open. */
68
+ leftAt: string | null;
69
+ device: string | null;
70
+ };
71
+
72
+ /** One call of a conversation. */
73
+ export type MessengerCall = {
74
+ id: string;
75
+ conversationId: string;
76
+ kind: 'audio' | 'video';
77
+ /** The login that tapped Call, or null once that login is gone. */
78
+ startedBy: string | null;
79
+ /** The seq of its "call started" line. */
80
+ startedSeq: number;
81
+ startedAt: string;
82
+ /** Null while the call is open. */
83
+ endedAt: string | null;
84
+ endedReason: MessengerCallEndedReason | null;
85
+ durationS: number | null;
86
+ /** The most people in it at once. */
87
+ maxParticipants: number;
88
+ participants: MessengerCallParticipant[];
89
+ };
90
+
91
+ /** GET /api/messenger/c/:id/calls?before=<ISO>&limit=: newest first. */
92
+ export type MessengerCallsResponse = {
93
+ calls: MessengerCall[];
94
+ /** Older calls exist before the last one returned. */
95
+ hasMore: boolean;
96
+ };
@@ -31,6 +31,11 @@ export type MessengerPreview = {
31
31
  authorKind: MessengerAuthorKind;
32
32
  };
33
33
 
34
+ /** The avatar a login chose in Appearance, or an agent's: its seed and
35
+ * builder parts, drawn in the brain's one style. The shape GET /api/shell
36
+ * gives as `avatar` for the caller's own. */
37
+ export type MessengerAvatar = { style: string; seed: string; parts: unknown };
38
+
34
39
  export type MessengerParticipant = {
35
40
  kind: MessengerParticipantKind;
36
41
  /** The login id or the agent id. */
@@ -40,6 +45,14 @@ export type MessengerParticipant = {
40
45
  admin: boolean;
41
46
  /** ISO, or null while the participant is in the chat. */
42
47
  leftAt: string | null;
48
+ /** A login's from its own Appearance seed; an agent's from its avatar
49
+ * (its slug when it has no seed). null: initials. */
50
+ avatar?: MessengerAvatar | null;
51
+ /** Logins only: the uploaded photo's version, the `v` of
52
+ * GET /api/messenger/photo/:loginId?v= (what the shell's
53
+ * `avatarPhotoVersion` is for the caller). null: no photo. The photo
54
+ * outranks the avatar. */
55
+ photoVersion?: string | null;
43
56
  };
44
57
 
45
58
  /** One row of GET /api/messenger/conversations. */
@@ -48,6 +61,11 @@ export type MessengerListRow = {
48
61
  /** The conversation id, or the agent id for an agent thread. */
49
62
  id: string;
50
63
  title: string;
64
+ /** A group's icon (one emoji) and colour (an app tint key, APP_TINTS in
65
+ * app-nav); null for a direct chat or a group without one; absent on an
66
+ * agent thread. */
67
+ icon?: string | null;
68
+ color?: string | null;
51
69
  /** null for an agent thread (its order is by time). */
52
70
  lastSeq: number | null;
53
71
  /** ISO, null when nothing was said yet. */
@@ -71,6 +89,13 @@ export type MessengerConversation = {
71
89
  id: string;
72
90
  kind: MessengerConversationKind;
73
91
  title: string | null;
92
+ /** As on a list row: a group's icon and colour, null for a direct chat. */
93
+ icon?: string | null;
94
+ color?: string | null;
95
+ /** A group's info (0343): what it is for and its rules, plain text (at
96
+ * most 2000 characters) its admins write; null for a direct chat and a
97
+ * group without one. Shown, never run. Not on a list row. */
98
+ info: string | null;
74
99
  createdBy: string | null;
75
100
  createdAt: string;
76
101
  archivedAt: string | null;
@@ -94,6 +119,13 @@ export type MessengerConversation = {
94
119
 
95
120
  export type MessengerMention = { kind: MessengerParticipantKind; id: string };
96
121
 
122
+ /** What a system line marks (calls plan section 8). The client tells a
123
+ * call line apart by `type`; `callId` names the call (GET .../calls). */
124
+ export type MessengerEvent =
125
+ | { type: 'call_started'; callId: string }
126
+ | { type: 'call_ended'; callId: string; seconds: number; participants: number }
127
+ | { type: 'call_cap'; callId: string; seconds: number; participants: number };
128
+
97
129
  export type MessengerReaction = { emoji: string; count: number; mine: boolean };
98
130
 
99
131
  export type MessengerMessage = {
@@ -115,6 +147,9 @@ export type MessengerMessage = {
115
147
  replyToSeq: number | null;
116
148
  clientMsgId: string | null;
117
149
  status: MessengerMessageStatus;
150
+ /** What a system line marks (a call started, ended or cut at the cap;
151
+ * dto/calls.ts); null on every other row. */
152
+ event: MessengerEvent | null;
118
153
  editedAt: string | null;
119
154
  deletedAt: string | null;
120
155
  createdAt: string;
@@ -140,6 +175,13 @@ export type MessengerCreateRequest = {
140
175
  * name none (a group of one, "message yourself"). */
141
176
  participants: string[];
142
177
  title?: string;
178
+ /** A group's icon (one emoji, at most 16 characters) and colour (an app
179
+ * tint key); a direct chat ignores both. */
180
+ icon?: string | null;
181
+ color?: string | null;
182
+ /** A group's info (at most 2000 characters; whitespace trimmed, blank is
183
+ * none); a direct chat refuses it (400). */
184
+ info?: string | null;
143
185
  };
144
186
 
145
187
  export type MessengerCreateResponse = {
@@ -148,6 +190,18 @@ export type MessengerCreateResponse = {
148
190
  created: boolean;
149
191
  };
150
192
 
193
+ /** PATCH /api/messenger/c/:id: at least one field. The title, icon,
194
+ * colour and info are a group admin's (null or '' clears one; a direct
195
+ * chat refuses each, 403); `muted` is mine. Answers `{ conversation }`. */
196
+ export type MessengerPatchRequest = {
197
+ title?: string | null;
198
+ icon?: string | null;
199
+ color?: string | null;
200
+ /** At most 2000 characters, whitespace trimmed; null clears it. */
201
+ info?: string | null;
202
+ muted?: boolean;
203
+ };
204
+
151
205
  /** POST /api/messenger/c/:id/messages. */
152
206
  export type MessengerSendRequest = {
153
207
  body: string;
@@ -172,6 +226,10 @@ export type MessengerDirectoryEntry = {
172
226
  online: boolean;
173
227
  /** An agent's slug (agents only). */
174
228
  slug?: string;
229
+ /** As on a participant. */
230
+ avatar?: MessengerAvatar | null;
231
+ /** Logins only, as on a participant. */
232
+ photoVersion?: string | null;
175
233
  };
176
234
 
177
235
  export type MessengerDirectoryResponse = { entries: MessengerDirectoryEntry[] };
@@ -0,0 +1,58 @@
1
+ /**
2
+ * People (Messenger V1 plan page d8954876, section 23): what a person shares
3
+ * with its team, under /api/people/*. Every login is approved by hand, so a
4
+ * person's card (its name, avatar, photo and presence; later a status) is
5
+ * open to the logins that may see it, and to nobody else: itself, the
6
+ * people sharing a live workspace with it (an Admin user sees every usable
7
+ * login), and the people of its chats. A login the caller may not see and a
8
+ * login that does not exist answer the same (a 404, or left out of a list).
9
+ */
10
+
11
+ /** The avatar a login chose in Appearance, drawn in the brain's one style:
12
+ * the shape GET /api/shell gives as `avatar` for the caller's own (the
13
+ * messenger's MessengerAvatar). */
14
+ export type PersonAvatar = { style: string; seed: string; parts: unknown };
15
+
16
+ /** Where a person is. This step sends 'online' (its stream beat in the last
17
+ * two minutes) or 'offline'; 'idle' and 'busy' come later, so a client
18
+ * handles every member of the union. */
19
+ export type PersonPresenceState = 'online' | 'idle' | 'busy' | 'offline';
20
+
21
+ export type PersonPresence = {
22
+ state: PersonPresenceState;
23
+ /** ISO: when its stream last beat; null when it never did. */
24
+ lastActiveAt: string | null;
25
+ };
26
+
27
+ /** A status the person set ("in a meeting"), with when it ends. */
28
+ export type PersonStatus = { text: string; until: string | null };
29
+
30
+ /** One person as the team sees it. */
31
+ export type PersonCard = {
32
+ /** The login id. */
33
+ id: string;
34
+ name: string;
35
+ /** null: the client draws initials. */
36
+ avatar: PersonAvatar | null;
37
+ /** The uploaded photo's version, the `v` of GET /api/people/:id/photo?v=
38
+ * (what the shell's `avatarPhotoVersion` is for the caller). null: no
39
+ * photo. The photo outranks the avatar. */
40
+ photoVersion: string | null;
41
+ presence: PersonPresence;
42
+ /** Not stored yet: always null in this step. */
43
+ status: PersonStatus | null;
44
+ };
45
+
46
+ /** GET /api/people: every person the caller may see, itself included, by
47
+ * name. */
48
+ export type PeopleListResponse = { people: PersonCard[] };
49
+
50
+ /** GET /api/people/:id. */
51
+ export type PersonResponse = { person: PersonCard };
52
+
53
+ /** One entry of GET /api/people/presence?ids=a,b,c (the cheap poll). */
54
+ export type PersonPresenceEntry = { id: string } & PersonPresence;
55
+
56
+ /** GET /api/people/presence: only the ids the caller may see (at most 200
57
+ * asked; the rest of a longer list is not read). */
58
+ export type PeoplePresenceResponse = { presence: PersonPresenceEntry[] };
@@ -1,14 +1,17 @@
1
1
  /**
2
2
  * Optional services: the box services an admin can switch on and off from
3
- * the dashboard (sandboxes, the local embedder and, on a core box, the
4
- * PDF-export helper). The parser service is core, never switched. GET
3
+ * the dashboard (sandboxes, the local embedder, the documents engine and,
4
+ * on a core box, the PDF-export helper). The parser service is core, never switched. GET
5
5
  * /api/services returns a
6
6
  * {@link ServicesView}; POST /api/services/:name {enable} asks the updater
7
7
  * sidecar to switch one; GET /api/services/status is the progress poll.
8
8
  */
9
9
 
10
- /** Each name is also the service's compose profile. */
11
- export type OptionalServiceName = 'sandboxes' | 'local-embedder' | 'helpers';
10
+ /** Each name is also the service's compose profile. `calls` is LiveKit
11
+ * (calls between people in the messenger); `documents` is the documents
12
+ * engine (Gotenberg). */
13
+ export type OptionalServiceName =
14
+ 'sandboxes' | 'local-embedder' | 'helpers' | 'calls' | 'documents';
12
15
 
13
16
  /**
14
17
  * - `off`: the compose profile is not active (the resting state).
package/src/dto/views.ts CHANGED
@@ -689,6 +689,13 @@ export type SystemHealth = {
689
689
  up: boolean | null;
690
690
  version: string | null;
691
691
  };
692
+ /** The documents engine (Gotenberg: Chromium + LibreOffice + PDF
693
+ * engines), the `documents` service. `up: null` means it is switched off
694
+ * or not wired on this brain; absent from a brain older than it. */
695
+ documents?: {
696
+ up: boolean | null;
697
+ version: string | null;
698
+ };
692
699
  /** The configured embedding server. For the `local` provider this is the
693
700
  * self-hosted Ollama/LM Studio/TEI on MANTLE_LOCAL_EMBEDDING_URL (the
694
701
  * bundled `ollama` compose service in prod). `up: true` means it's
package/src/index.ts CHANGED
@@ -108,6 +108,7 @@ export type {
108
108
  export type { MemberMcpClient, MemberMcpConnector, MemberMcpView } from './dto/member-mcp';
109
109
  export type {
110
110
  MessengerAuthorKind,
111
+ MessengerAvatar,
111
112
  MessengerConversation,
112
113
  MessengerConversationKind,
113
114
  MessengerCreateRequest,
@@ -123,6 +124,7 @@ export type {
123
124
  MessengerMessagesResponse,
124
125
  MessengerParticipant,
125
126
  MessengerParticipantKind,
127
+ MessengerPatchRequest,
126
128
  MessengerPreview,
127
129
  MessengerReaction,
128
130
  MessengerRowKind,
@@ -131,6 +133,17 @@ export type {
131
133
  MessengerStreamEvent,
132
134
  MessengerUnreadResponse,
133
135
  } from './dto/messenger';
136
+ export type {
137
+ PeopleListResponse,
138
+ PeoplePresenceResponse,
139
+ PersonAvatar,
140
+ PersonCard,
141
+ PersonPresence,
142
+ PersonPresenceEntry,
143
+ PersonPresenceState,
144
+ PersonResponse,
145
+ PersonStatus,
146
+ } from './dto/people';
134
147
  export type {
135
148
  BulkDeleteCascadeResponse,
136
149
  BulkDeleteFilesResponse,