@syrtis-ai/syrtis-javascript-client 6.0.4 → 7.0.1
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 +26 -3
- package/package.json +2 -2
- package/src/Common/SyrtisClient.ts +17 -0
- package/src/Repository/SessionRepository.ts +59 -28
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @syrtis-ai/syrtis-javascript-client
|
|
2
2
|
|
|
3
|
-
Version:
|
|
3
|
+
Version: 7.0.1
|
|
4
4
|
|
|
5
5
|
## Table of Contents
|
|
6
6
|
|
|
@@ -120,6 +120,8 @@ const data = extracted?.getParsedContent();
|
|
|
120
120
|
|
|
121
121
|
No configuration is required: `subscribe()` fetches a scoped, short-lived Mercure subscriber JWT from the API (`session/subscribe-info/{secureId}`) and renews it automatically on reconnection. The API bearer token is enough.
|
|
122
122
|
|
|
123
|
+
The subscription listens to the versioned topic `{apiVersion}/entity/session/event/{secureId}`; events carry `{event, data}` where `data` is the standard API item `{type, entity, metadata, relationships}` — the exact same format and strict hydration gate as REST responses.
|
|
124
|
+
|
|
123
125
|
Subscribe to a session — payloads are hydrated into entities, reconnection with backoff is automatic:
|
|
124
126
|
|
|
125
127
|
```typescript
|
|
@@ -128,7 +130,7 @@ const connection = sessionRepository.subscribe({
|
|
|
128
130
|
onMessage: (message) => { /* hydrated Message */ },
|
|
129
131
|
onRequest: (request) => { /* hydrated Request */ },
|
|
130
132
|
onEvent: (liveEvent) => { /* every raw event: {entityType, event, data} */ },
|
|
131
|
-
onInvalidEvent: (payload) => { /* malformed payloads (default: console.warn) */ },
|
|
133
|
+
onInvalidEvent: (payload, error) => { /* malformed or out-of-contract payloads (default: console.warn) */ },
|
|
132
134
|
onStatusChange: (status) => { /* connecting | open | error | closed */ },
|
|
133
135
|
});
|
|
134
136
|
|
|
@@ -149,6 +151,25 @@ By default the promise resolves on the first `Message.isReply` message; pass `is
|
|
|
149
151
|
|
|
150
152
|
To bypass the automatic JWT flow, pass `mercureHubUrl`/`mercureJwt` to the client constructor (static hub configuration), or inject a `liveUpdatesDriver` (any `LiveUpdatesDriverInterface` from `@wexample/js-api/Common/LiveUpdates/LiveUpdatesDriver`) for a custom transport. Both take precedence over the subscribe-info flow. `fetchSubscribeInfo(sessionSecureId)` is also available directly on the repository.
|
|
151
153
|
|
|
154
|
+
### Connection status (widgets)
|
|
155
|
+
|
|
156
|
+
Every connection opened through `subscribe()` is tracked by a client-wide registry, for status widgets and monitoring:
|
|
157
|
+
|
|
158
|
+
```typescript
|
|
159
|
+
const registry = client.getLiveUpdatesRegistry();
|
|
160
|
+
|
|
161
|
+
registry.getAggregatedStatus();
|
|
162
|
+
// { total, connecting, reconnecting, open, error, reconnectStopped, hasActiveConnection }
|
|
163
|
+
|
|
164
|
+
const unsubscribe = registry.onEvent((event) => {
|
|
165
|
+
// event.type: 'connection-registered' | 'connection-status'
|
|
166
|
+
// | 'connection-message' | 'connection-unregistered'
|
|
167
|
+
// event.aggregated: fresh aggregated status
|
|
168
|
+
});
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Connection statuses are `connecting | open | error | reconnecting | reconnect-stopped | closed`; a successful reconnection is observable as `reconnecting` → `open`, and closed connections leave the registry on their own.
|
|
172
|
+
|
|
152
173
|
## Fetching history
|
|
153
174
|
|
|
154
175
|
```typescript
|
|
@@ -190,7 +211,9 @@ try {
|
|
|
190
211
|
}
|
|
191
212
|
```
|
|
192
213
|
|
|
193
|
-
Hydration is strict by design: a response key absent from the entity schema, a read-only write, a malformed API item or an unregistered relationship type throws an `ApiSchemaError` (`@wexample/js-api/Common/Errors/ApiSchemaError`, codes `ERR_SCHEMA_*`, carrying `entityName` and `field`). A contract drift is caught at the boundary instead of silently losing data.
|
|
214
|
+
Hydration is strict by design: a response key absent from the entity schema, a read-only write, a malformed API item or an unregistered relationship type throws an `ApiSchemaError` (`@wexample/js-api/Common/Errors/ApiSchemaError`, codes `ERR_SCHEMA_*`, carrying `entityName` and `field`). A contract drift is caught at the boundary instead of silently losing data. Live updates go through the same gate: an event whose hydration fails is reported through `onInvalidEvent` (never silently) and dropped, keeping the subscription alive.
|
|
215
|
+
|
|
216
|
+
An API item's `type` is the entity name, camelCase like the whole 2026 contract (`message`, `messageStamp`, `userConfig`) — the same identifier keys the repository registry, so there is no translation anywhere. Routes derive from it in kebab-case (`messageStamp` → `message-stamp/...`).
|
|
194
217
|
|
|
195
218
|
To unwrap a raw call yourself:
|
|
196
219
|
|
package/package.json
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "
|
|
2
|
+
"version": "7.0.1",
|
|
3
3
|
"type": "module",
|
|
4
4
|
"name": "@syrtis-ai/syrtis-javascript-client",
|
|
5
5
|
"scripts": {
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
"access": "public"
|
|
14
14
|
},
|
|
15
15
|
"dependencies": {
|
|
16
|
-
"@wexample/js-api": "^
|
|
16
|
+
"@wexample/js-api": "^7.0.0"
|
|
17
17
|
},
|
|
18
18
|
"files": [
|
|
19
19
|
"src"
|
|
@@ -2,6 +2,7 @@ import type { ApiClientOptions } from '@wexample/js-api/Common/AbstractApiClient
|
|
|
2
2
|
import AbstractApiEntitiesClient from '@wexample/js-api/Common/AbstractApiEntitiesClient';
|
|
3
3
|
import type { RepositoryClass } from '@wexample/js-api/Common/ApiEntityManager';
|
|
4
4
|
import LiveUpdatesError from '@wexample/js-api/Common/Errors/LiveUpdatesError';
|
|
5
|
+
import LiveUpdatesConnectionRegistry from '@wexample/js-api/Common/LiveUpdates/LiveUpdatesConnectionRegistry';
|
|
5
6
|
import type { LiveUpdatesDriverInterface } from '@wexample/js-api/Common/LiveUpdates/LiveUpdatesDriver';
|
|
6
7
|
import MercureLiveUpdatesDriver from '@wexample/js-api/Common/LiveUpdates/MercureLiveUpdatesDriver';
|
|
7
8
|
import getEntitySchemas from './entitySchemas.js';
|
|
@@ -23,6 +24,8 @@ export default class SyrtisClient extends AbstractApiEntitiesClient {
|
|
|
23
24
|
static readonly API_VERSION_DEFAULT = SyrtisClient.API_VERSION_2026_1;
|
|
24
25
|
|
|
25
26
|
private liveUpdatesDriver: LiveUpdatesDriverInterface | null;
|
|
27
|
+
private readonly liveUpdatesRegistry = new LiveUpdatesConnectionRegistry();
|
|
28
|
+
private readonly apiVersion: string;
|
|
26
29
|
|
|
27
30
|
constructor(options: SyrtisClientOptions) {
|
|
28
31
|
const { host, apiVersion, mercureHubUrl, mercureJwt, liveUpdatesDriver, ...rest } = options;
|
|
@@ -33,6 +36,7 @@ export default class SyrtisClient extends AbstractApiEntitiesClient {
|
|
|
33
36
|
baseUrl: `${normalizedHost}api/${version}/`,
|
|
34
37
|
});
|
|
35
38
|
|
|
39
|
+
this.apiVersion = version;
|
|
36
40
|
this.liveUpdatesDriver =
|
|
37
41
|
liveUpdatesDriver ??
|
|
38
42
|
(mercureHubUrl
|
|
@@ -43,6 +47,19 @@ export default class SyrtisClient extends AbstractApiEntitiesClient {
|
|
|
43
47
|
: null);
|
|
44
48
|
}
|
|
45
49
|
|
|
50
|
+
// Version segment of every API path — also prefixes Mercure topics
|
|
51
|
+
// (2026-1/entity/session/event/{secureId}).
|
|
52
|
+
getApiVersion(): string {
|
|
53
|
+
return this.apiVersion;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
// Aggregated status and lifecycle events of every live connection opened
|
|
57
|
+
// through this client (subscribe() registers them) — meant for status
|
|
58
|
+
// widgets: getAggregatedStatus() + onEvent(listener).
|
|
59
|
+
getLiveUpdatesRegistry(): LiveUpdatesConnectionRegistry {
|
|
60
|
+
return this.liveUpdatesRegistry;
|
|
61
|
+
}
|
|
62
|
+
|
|
46
63
|
setLiveUpdatesDriver(driver: LiveUpdatesDriverInterface): void {
|
|
47
64
|
this.liveUpdatesDriver = driver;
|
|
48
65
|
}
|
|
@@ -10,6 +10,7 @@ import Message from '../Entity/Message.js';
|
|
|
10
10
|
import Request from '../Entity/Request.js';
|
|
11
11
|
import Session from '../Entity/Session.js';
|
|
12
12
|
import type MessageRepository from './MessageRepository.js';
|
|
13
|
+
import type RequestRepository from './RequestRepository.js';
|
|
13
14
|
|
|
14
15
|
export type SessionMessagePayload = {
|
|
15
16
|
content: string;
|
|
@@ -41,8 +42,11 @@ export type SessionSendMessageOptions = {
|
|
|
41
42
|
sync?: boolean;
|
|
42
43
|
};
|
|
43
44
|
|
|
44
|
-
// Payload published by the API on the session Mercure topic
|
|
45
|
-
// {
|
|
45
|
+
// Payload published by the API on the versioned session Mercure topic
|
|
46
|
+
// ({apiVersion}/entity/session/event/{secureId}): { event, data } where
|
|
47
|
+
// data is the standard 2026 API item {type, entity, metadata, relationships},
|
|
48
|
+
// identical to REST responses. entityType is data.type, i.e. the entity name
|
|
49
|
+
// (Message.entityName, Request.entityName, ...).
|
|
46
50
|
export type SessionLiveEvent = {
|
|
47
51
|
entityType: string;
|
|
48
52
|
event: string;
|
|
@@ -63,10 +67,12 @@ export type SessionSubscribeOptions = {
|
|
|
63
67
|
onRequest?: (request: Request, liveEvent: SessionLiveEvent) => void;
|
|
64
68
|
// Called for every event, including entity types without a dedicated handler.
|
|
65
69
|
onEvent?: (liveEvent: SessionLiveEvent) => void;
|
|
66
|
-
// Called when a live payload does not match the expected event shape
|
|
67
|
-
//
|
|
68
|
-
//
|
|
69
|
-
|
|
70
|
+
// Called when a live payload does not match the expected event shape, or
|
|
71
|
+
// when its strict hydration fails (contract drift — error is then an
|
|
72
|
+
// ApiSchemaError). Without a handler the payload is reported via
|
|
73
|
+
// console.warn — a bad event is dropped, never silently, and the
|
|
74
|
+
// subscription stays alive.
|
|
75
|
+
onInvalidEvent?: (payload: unknown, error?: unknown) => void;
|
|
70
76
|
onStatusChange?: (
|
|
71
77
|
status: LiveUpdatesConnectionStatus,
|
|
72
78
|
previousStatus: LiveUpdatesConnectionStatus
|
|
@@ -225,42 +231,62 @@ export default class SessionRepository extends AbstractApiRepository<Session> {
|
|
|
225
231
|
subscribe(options: SessionSubscribeOptions): LiveUpdatesConnection {
|
|
226
232
|
const client = this.client as SyrtisClient;
|
|
227
233
|
|
|
228
|
-
|
|
234
|
+
const connection = new LiveUpdatesConnection({
|
|
229
235
|
driver: client.hasLiveUpdatesDriver()
|
|
230
236
|
? client.getLiveUpdatesDriver()
|
|
231
237
|
: new SessionSubscribeInfoDriver(this, options.sessionSecureId),
|
|
232
238
|
topics: [this.buildLiveTopic(options.sessionSecureId)],
|
|
233
239
|
onStatusChange: options.onStatusChange,
|
|
234
240
|
onMessage: (payload) => {
|
|
235
|
-
const
|
|
236
|
-
if (!liveEvent) {
|
|
241
|
+
const reportInvalid = (error?: unknown) => {
|
|
237
242
|
if (options.onInvalidEvent) {
|
|
238
|
-
options.onInvalidEvent(payload);
|
|
243
|
+
options.onInvalidEvent(payload, error);
|
|
244
|
+
} else if (error === undefined) {
|
|
245
|
+
console.warn('[syrtis] invalid live event dropped:', payload);
|
|
239
246
|
} else {
|
|
240
|
-
console.warn('[syrtis]
|
|
247
|
+
console.warn('[syrtis] invalid live event dropped:', payload, error);
|
|
241
248
|
}
|
|
249
|
+
};
|
|
250
|
+
|
|
251
|
+
const liveEvent = this.parseLiveEvent(payload);
|
|
252
|
+
if (!liveEvent) {
|
|
253
|
+
reportInvalid();
|
|
242
254
|
return;
|
|
243
255
|
}
|
|
244
256
|
|
|
245
257
|
options.onEvent?.(liveEvent);
|
|
246
258
|
|
|
247
|
-
//
|
|
248
|
-
//
|
|
249
|
-
//
|
|
250
|
-
//
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
259
|
+
// data is a standard API item: same strict hydration gate as REST.
|
|
260
|
+
// Types without a dedicated callback (e.g. artifact) are only
|
|
261
|
+
// delivered through onEvent. A hydration failure means the live
|
|
262
|
+
// contract drifted: reported, dropped, subscription kept alive.
|
|
263
|
+
try {
|
|
264
|
+
if (liveEvent.entityType === Message.entityName) {
|
|
265
|
+
options.onMessage?.(
|
|
266
|
+
(this.client.getRepository(Message) as MessageRepository).hydrateApiItem(
|
|
267
|
+
liveEvent.data
|
|
268
|
+
),
|
|
269
|
+
liveEvent
|
|
270
|
+
);
|
|
271
|
+
} else if (liveEvent.entityType === Request.entityName) {
|
|
272
|
+
options.onRequest?.(
|
|
273
|
+
(this.client.getRepository(Request) as RequestRepository).hydrateApiItem(
|
|
274
|
+
liveEvent.data
|
|
275
|
+
),
|
|
276
|
+
liveEvent
|
|
277
|
+
);
|
|
278
|
+
}
|
|
279
|
+
} catch (error) {
|
|
280
|
+
reportInvalid(error);
|
|
261
281
|
}
|
|
262
282
|
},
|
|
263
283
|
});
|
|
284
|
+
|
|
285
|
+
// Feeds the client-wide aggregated status (status widgets); the
|
|
286
|
+
// registry drops the connection by itself once closed.
|
|
287
|
+
client.getLiveUpdatesRegistry().register(connection);
|
|
288
|
+
|
|
289
|
+
return connection;
|
|
264
290
|
}
|
|
265
291
|
|
|
266
292
|
// Sends a message without holding the HTTP response, then resolves with
|
|
@@ -313,7 +339,8 @@ export default class SessionRepository extends AbstractApiRepository<Session> {
|
|
|
313
339
|
}
|
|
314
340
|
|
|
315
341
|
protected buildLiveTopic(sessionSecureId: string): string {
|
|
316
|
-
|
|
342
|
+
const client = this.client as SyrtisClient;
|
|
343
|
+
return `${client.getApiVersion()}/entity/session/event/${sessionSecureId}`;
|
|
317
344
|
}
|
|
318
345
|
|
|
319
346
|
protected parseLiveEvent(payload: unknown): SessionLiveEvent | null {
|
|
@@ -322,10 +349,14 @@ export default class SessionRepository extends AbstractApiRepository<Session> {
|
|
|
322
349
|
}
|
|
323
350
|
|
|
324
351
|
const record = payload as Record<string, unknown>;
|
|
325
|
-
const entityType = record.entity_type;
|
|
326
352
|
const data = record.data;
|
|
327
353
|
|
|
328
|
-
if (
|
|
354
|
+
if (!data || typeof data !== 'object' || Array.isArray(data)) {
|
|
355
|
+
return null;
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
const entityType = (data as Record<string, unknown>).type;
|
|
359
|
+
if (typeof entityType !== 'string' || !entityType) {
|
|
329
360
|
return null;
|
|
330
361
|
}
|
|
331
362
|
|