@syrtis-ai/syrtis-javascript-client 5.0.3 → 6.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: 5.0.3
3
+ Version: 6.0.0
4
4
 
5
5
  ## Table of Contents
6
6
 
@@ -81,7 +81,7 @@ const messages = await sessionRepository.sendMessage({
81
81
  });
82
82
  ```
83
83
 
84
- Other supported options: `files`, `contentType`, `format`, `templateId`, `stamps`, `name`, `metadata`, `fileStamps`, `parentRequestSecureId`, `timeZone`.
84
+ Other supported options: `files`, `contentType`, `format`, `stamps`, `name`, `metadata`, `fileStamps`, `parentRequestSecureId`, `timeZone`.
85
85
 
86
86
  ### Sending several messages in one request
87
87
 
@@ -128,6 +128,7 @@ const connection = sessionRepository.subscribe({
128
128
  onMessage: (message) => { /* hydrated Message */ },
129
129
  onRequest: (request) => { /* hydrated Request */ },
130
130
  onEvent: (liveEvent) => { /* every raw event: {entityType, event, data} */ },
131
+ onInvalidEvent: (payload) => { /* malformed payloads (default: console.warn) */ },
131
132
  onStatusChange: (status) => { /* connecting | open | error | closed */ },
132
133
  });
133
134
 
@@ -189,6 +190,8 @@ try {
189
190
  }
190
191
  ```
191
192
 
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.
194
+
192
195
  To unwrap a raw call yourself:
193
196
 
194
197
  ```typescript
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "5.0.3",
2
+ "version": "6.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": "^1.0.0"
16
+ "@wexample/js-api": "^2.0.0"
17
17
  },
18
18
  "files": [
19
19
  "src"
@@ -6,9 +6,7 @@ export default class MessageRepository extends AbstractApiRepository<Message> {
6
6
  return Message;
7
7
  }
8
8
 
9
- hydrateFromApiCollection(
10
- items: Parameters<AbstractApiRepository<Message>['createFromApiCollection']>[0]
11
- ): Message[] {
12
- return this.createFromApiCollection(items);
9
+ hydrateFromApiCollection(items: unknown[]): Message[] {
10
+ return this.createFromApiCollection(items.map((item) => this.parseApiItem(item)));
13
11
  }
14
12
  }
@@ -1,4 +1,5 @@
1
1
  import AbstractApiRepository from '@wexample/js-api/Common/AbstractApiRepository';
2
+ import ApiEnvelopeError from '@wexample/js-api/Common/Errors/ApiEnvelopeError';
2
3
  import LiveUpdatesError from '@wexample/js-api/Common/Errors/LiveUpdatesError';
3
4
  import LiveUpdatesConnection, {
4
5
  type LiveUpdatesConnectionStatus,
@@ -62,6 +63,10 @@ export type SessionSubscribeOptions = {
62
63
  onRequest?: (request: Request, liveEvent: SessionLiveEvent) => void;
63
64
  // Called for every event, including entity types without a dedicated handler.
64
65
  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;
65
70
  onStatusChange?: (
66
71
  status: LiveUpdatesConnectionStatus,
67
72
  previousStatus: LiveUpdatesConnectionStatus
@@ -110,9 +115,7 @@ export default class SessionRepository extends AbstractApiRepository<Session> {
110
115
 
111
116
  const payload = this.extractPayload(data);
112
117
 
113
- return this.createFromApiItem(
114
- payload as Parameters<AbstractApiRepository<Session>['createFromApiItem']>[0]
115
- );
118
+ return this.createFromApiItem(this.parseApiItem(payload));
116
119
  }
117
120
 
118
121
  async sendMessage(options: SessionSendMessageOptions): Promise<Message[]> {
@@ -191,15 +194,26 @@ export default class SessionRepository extends AbstractApiRepository<Session> {
191
194
 
192
195
  const payload = this.extractPayload(data) as Record<string, unknown>;
193
196
 
194
- if (typeof payload.hubUrl !== 'string' || typeof payload.jwt !== 'string') {
195
- throw new Error('Invalid subscribe-info payload: missing "hubUrl" or "jwt".');
197
+ if (
198
+ typeof payload.hubUrl !== 'string' ||
199
+ typeof payload.jwt !== 'string' ||
200
+ !Array.isArray(payload.topics) ||
201
+ !payload.topics.every((topic) => typeof topic === 'string') ||
202
+ typeof payload.expiresAt !== 'string'
203
+ ) {
204
+ throw new LiveUpdatesError({
205
+ message:
206
+ '[syrtis] invalid subscribe-info payload: expected {hubUrl, jwt, topics[], expiresAt}.',
207
+ code: 'ERR_LIVE_UPDATES_INVALID_SUBSCRIBE_INFO',
208
+ context: { payload },
209
+ });
196
210
  }
197
211
 
198
212
  return {
199
213
  hubUrl: payload.hubUrl,
200
214
  jwt: payload.jwt,
201
- topics: Array.isArray(payload.topics) ? (payload.topics as string[]) : [],
202
- expiresAt: typeof payload.expiresAt === 'string' ? payload.expiresAt : '',
215
+ topics: payload.topics as string[],
216
+ expiresAt: payload.expiresAt,
203
217
  };
204
218
  }
205
219
 
@@ -220,15 +234,30 @@ export default class SessionRepository extends AbstractApiRepository<Session> {
220
234
  onMessage: (payload) => {
221
235
  const liveEvent = this.parseLiveEvent(payload);
222
236
  if (!liveEvent) {
237
+ if (options.onInvalidEvent) {
238
+ options.onInvalidEvent(payload);
239
+ } else {
240
+ console.warn('[syrtis] malformed live event dropped:', payload);
241
+ }
223
242
  return;
224
243
  }
225
244
 
226
245
  options.onEvent?.(liveEvent);
227
246
 
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.
228
251
  if (liveEvent.entityType === 'Message') {
229
- options.onMessage?.(Message.fromApi<Message>(liveEvent.data), liveEvent);
252
+ options.onMessage?.(
253
+ Message.fromApi<Message>(liveEvent.data, { tolerant: true }),
254
+ liveEvent
255
+ );
230
256
  } else if (liveEvent.entityType === 'Request') {
231
- options.onRequest?.(Request.fromApi<Request>(liveEvent.data), liveEvent);
257
+ options.onRequest?.(
258
+ Request.fromApi<Request>(liveEvent.data, { tolerant: true }),
259
+ liveEvent
260
+ );
232
261
  }
233
262
  },
234
263
  });
@@ -312,7 +341,10 @@ export default class SessionRepository extends AbstractApiRepository<Session> {
312
341
  const items = (payload as Record<string, unknown>).messages;
313
342
 
314
343
  if (!Array.isArray(items)) {
315
- throw new Error('Invalid API payload: missing "messages" array.');
344
+ throw new ApiEnvelopeError({
345
+ message: 'Invalid API payload: missing "messages" array.',
346
+ envelope: payload,
347
+ });
316
348
  }
317
349
 
318
350
  const messageRepository = this.client.getRepository(Message) as MessageRepository;