@syrtis-ai/syrtis-javascript-client 6.0.3 → 7.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,6 +1,6 @@
1
1
  # @syrtis-ai/syrtis-javascript-client
2
2
 
3
- Version: 6.0.3
3
+ Version: 7.0.0
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. The only tolerated exception is live-update payloads, produced by the API's legacy normalizer.
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": "6.0.3",
2
+ "version": "7.0.0",
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": "^2.0.2"
16
+ "@wexample/js-api": "^3.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
- // { entity_type: 'Message'|'Request', event: 'message.save'|..., data: {...} }
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
- // Without a handler the payload is reported via console.warn — a
68
- // malformed event is dropped, never silently.
69
- onInvalidEvent?: (payload: unknown) => void;
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
- return new LiveUpdatesConnection({
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 liveEvent = this.parseLiveEvent(payload);
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] malformed live event dropped:', payload);
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
- // Mercure payloads come from the API's legacy normalizer, which
248
- // emits keys outside the schema (requestId, _formattedContent, ...):
249
- // tolerance is imposed here until the API publishes contract-clean
250
- // payloads — every other hydration path stays strict.
251
- if (liveEvent.entityType === 'Message') {
252
- options.onMessage?.(
253
- Message.fromApi<Message>(liveEvent.data, { tolerant: true }),
254
- liveEvent
255
- );
256
- } else if (liveEvent.entityType === 'Request') {
257
- options.onRequest?.(
258
- Request.fromApi<Request>(liveEvent.data, { tolerant: true }),
259
- liveEvent
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
- return `entity/session/event/${sessionSecureId}`;
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 (typeof entityType !== 'string' || !data || typeof data !== 'object') {
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