@mastra/client-js 1.59.0 → 1.60.0-alpha.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.
Files changed (33) hide show
  1. package/dist/client.d.ts +11 -4
  2. package/dist/client.d.ts.map +1 -1
  3. package/dist/docs/SKILL.md +5 -5
  4. package/dist/docs/assets/SOURCE_MAP.json +33 -2
  5. package/dist/docs/references/docs-harness-schedules.md +2 -0
  6. package/dist/docs/references/docs-signals-sending-signals.md +3 -1
  7. package/dist/docs/references/integrations-auth-clerk.md +46 -7
  8. package/dist/docs/references/integrations-auth-neon.md +217 -0
  9. package/dist/docs/references/integrations-auth-supabase.md +46 -7
  10. package/dist/docs/references/integrations-auth-workos.md +54 -15
  11. package/dist/docs/references/reference-client-js-agents.md +4 -4
  12. package/dist/docs/references/reference-client-js-observability.md +90 -3
  13. package/dist/docs/references/reference-observability-tracing-advanced-queries.md +47 -58
  14. package/dist/index.cjs +123 -26
  15. package/dist/index.cjs.map +1 -1
  16. package/dist/index.d.ts +2 -0
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/index.js +123 -26
  19. package/dist/index.js.map +1 -1
  20. package/dist/resources/agent.d.ts +16 -9
  21. package/dist/resources/agent.d.ts.map +1 -1
  22. package/dist/resources/observability-route-types.d.ts +7 -0
  23. package/dist/resources/observability-route-types.d.ts.map +1 -1
  24. package/dist/resources/observability.d.ts +13 -6
  25. package/dist/resources/observability.d.ts.map +1 -1
  26. package/dist/resources/signal-writes.d.ts +9 -0
  27. package/dist/resources/signal-writes.d.ts.map +1 -0
  28. package/dist/route-types.generated.d.ts +265 -217
  29. package/dist/route-types.generated.d.ts.map +1 -1
  30. package/dist/types.d.ts +3 -1
  31. package/dist/types.d.ts.map +1 -1
  32. package/package.json +2 -2
  33. package/dist/docs/references/reference-migrations-upgrade-to-v1-client.md +0 -341
package/dist/index.cjs CHANGED
@@ -2932,7 +2932,10 @@ var Agent = class extends BaseResource {
2932
2932
  toolCallId: toolCall.toolCallId,
2933
2933
  toolName: toolCall.toolName,
2934
2934
  input: toolCall.args,
2935
- result,
2935
+ output: {
2936
+ type: "json",
2937
+ value: result
2938
+ },
2936
2939
  ...modelOutput != null ? { providerOptions: { mastra: { modelOutput } } } : {},
2937
2940
  ...observability ? { __mastraObservability: observability } : {}
2938
2941
  });
@@ -3244,20 +3247,27 @@ var Agent = class extends BaseResource {
3244
3247
  * Use this to resume receiving events after a disconnection.
3245
3248
  *
3246
3249
  * @param params.runId - The run ID to observe
3247
- * @param params.offset - Optional position to resume from (0-based). If omitted, replays all events.
3250
+ * @param params.offset - Run-log position to resume from. Chunks from `observe()`, and from `stream()` on
3251
+ * durable and evented agents, carry an `index`; pass the `index + 1` of the last chunk that has one. Chunks without an `index`
3252
+ * (`abort` and structured-output `object` chunks) are skipped when choosing the offset. If omitted,
3253
+ * replays the chunks still cached for the run, or only live chunks if the server's transport can't replay.
3248
3254
  * @returns Promise containing a streaming Response
3249
3255
  *
3250
3256
  * @example
3251
3257
  * ```typescript
3252
- * // Reconnect to a stream from a specific position
3253
- * const response = await client.agents('my-agent').observe({
3254
- * runId: 'run-123',
3255
- * offset: 42, // Resume from event 42
3256
- * });
3258
+ * const agent = client.getAgent('my-agent');
3259
+ * let offset = 0;
3260
+ * const trackOffset = async (chunk: { index?: number }) => {
3261
+ * if (chunk.index === undefined) return;
3262
+ * offset = chunk.index + 1;
3263
+ * };
3257
3264
  *
3258
- * await response.processDataStream({
3259
- * onChunk: (chunk) => console.log('Received:', chunk),
3260
- * });
3265
+ * const stream = await agent.stream(messages, { runId: 'run-123' });
3266
+ * await stream.processDataStream({ onChunk: trackOffset });
3267
+ *
3268
+ * // After a dropped connection, resume where the last indexed chunk left off
3269
+ * const response = await agent.observe({ runId: 'run-123', offset });
3270
+ * await response.processDataStream({ onChunk: trackOffset });
3261
3271
  * ```
3262
3272
  */
3263
3273
  async observe(params) {
@@ -5350,6 +5360,59 @@ var AgentBuilder = class extends BaseResource {
5350
5360
  return this.request(url, { method: "POST" });
5351
5361
  }
5352
5362
  };
5363
+ // src/resources/signal-writes.ts
5364
+ function isMissingAnchor(error) {
5365
+ if (!(error instanceof MastraClientError) || error.status !== 404) return false;
5366
+ const code = error.body?.code;
5367
+ return code === "TRACE_NOT_FOUND" || code === "SPAN_NOT_FOUND";
5368
+ }
5369
+ /** Adds bounded anchor retries to the normal transport retries, with one immutable payload. */
5370
+ async function writeSignal(resource, path, method, body, options = {}) {
5371
+ const { anchorRetryTimeoutMs = 3e4, ...requestOptions } = options;
5372
+ if (!Number.isSafeInteger(anchorRetryTimeoutMs) || anchorRetryTimeoutMs < 0 || anchorRetryTimeoutMs > 3e4) throw new RangeError("anchorRetryTimeoutMs must be an integer between 0 and 30000");
5373
+ const payload = JSON.parse(JSON.stringify(body));
5374
+ const deadline = new AbortController();
5375
+ const signal = mergeAbortSignals(resource.options.abortSignal, options.signal, deadline.signal);
5376
+ let timer;
5377
+ let lastAnchorError;
5378
+ let delay = Math.max(1, resource.options.backoffMs ?? 100);
5379
+ try {
5380
+ for (;;) {
5381
+ try {
5382
+ return await resource.request(path, {
5383
+ ...requestOptions,
5384
+ method,
5385
+ body: payload,
5386
+ signal
5387
+ });
5388
+ } catch (error) {
5389
+ if (signal.aborted) throw error;
5390
+ if (!isMissingAnchor(error) || anchorRetryTimeoutMs === 0) throw error;
5391
+ lastAnchorError = error;
5392
+ timer ??= setTimeout(() => deadline.abort(), anchorRetryTimeoutMs);
5393
+ }
5394
+ await new Promise((resolve, reject) => {
5395
+ const onAbort = () => {
5396
+ clearTimeout(wait);
5397
+ reject(signal.reason);
5398
+ };
5399
+ const wait = setTimeout(() => {
5400
+ signal.removeEventListener("abort", onAbort);
5401
+ resolve();
5402
+ }, delay);
5403
+ signal.addEventListener("abort", onAbort, { once: true });
5404
+ if (signal.aborted) onAbort();
5405
+ });
5406
+ delay = Math.max(1, Math.min(delay * 2, resource.options.maxBackoffMs ?? 1e3));
5407
+ }
5408
+ } catch (error) {
5409
+ if (deadline.signal.aborted && !options.signal?.aborted && !resource.options.abortSignal?.aborted && (error === deadline.signal.reason || error instanceof Error && error.name === "AbortError")) throw lastAnchorError ?? error;
5410
+ throw error;
5411
+ } finally {
5412
+ clearTimeout(timer);
5413
+ deadline.abort();
5414
+ }
5415
+ }
5353
5416
  // src/resources/observability.ts
5354
5417
  /** Client resource for interacting with the Mastra observability API (traces, logs, scores, feedback, and metrics). */
5355
5418
  var Observability = class extends BaseResource {
@@ -5608,6 +5671,10 @@ var Observability = class extends BaseResource {
5608
5671
  ]);
5609
5672
  return this.request(`/observability/logs${queryString ? `?${queryString}` : ""}`);
5610
5673
  }
5674
+ /** Retrieves one score by ID; the response contains null when it is missing. */
5675
+ getScore(id) {
5676
+ return this.request(`/observability/scores/${encodeURIComponent(id)}`);
5677
+ }
5611
5678
  /**
5612
5679
  * Retrieves a paginated list of scores with optional filtering and sorting.
5613
5680
  */
@@ -5621,13 +5688,18 @@ var Observability = class extends BaseResource {
5621
5688
  }
5622
5689
  /**
5623
5690
  * Creates a single score record in the observability store.
5624
- * Timestamp is set server-side.
5691
+ * Missing IDs and timestamps are generated once, before retries.
5625
5692
  */
5626
- createScore(params) {
5627
- return this.request(`/observability/scores`, {
5628
- method: "POST",
5629
- body: params
5630
- });
5693
+ createScore(params, options) {
5694
+ const body = {
5695
+ ...params,
5696
+ ...params?.score && { score: {
5697
+ ...params.score,
5698
+ scoreId: params.score.scoreId ?? (0, _lukeed_uuid.v4)(),
5699
+ timestamp: params.score.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
5700
+ } }
5701
+ };
5702
+ return writeSignal(this, "/observability/scores", "POST", body, options);
5631
5703
  }
5632
5704
  /**
5633
5705
  * Deletes score records by scoreId, optionally scoped to a tenant.
@@ -5676,6 +5748,10 @@ var Observability = class extends BaseResource {
5676
5748
  body: params
5677
5749
  });
5678
5750
  }
5751
+ /** Retrieves one feedback by ID; the response contains null when it is missing. */
5752
+ getFeedback(id) {
5753
+ return this.request(`/observability/feedback/${encodeURIComponent(id)}`);
5754
+ }
5679
5755
  /**
5680
5756
  * Retrieves a paginated list of feedback with optional filtering and sorting.
5681
5757
  */
@@ -5689,13 +5765,22 @@ var Observability = class extends BaseResource {
5689
5765
  }
5690
5766
  /**
5691
5767
  * Creates a single feedback record in the observability store.
5692
- * Timestamp is set server-side.
5768
+ * Missing IDs and timestamps are generated once, before retries.
5693
5769
  */
5694
- createFeedback(params) {
5695
- return this.request(`/observability/feedback`, {
5696
- method: "POST",
5697
- body: params
5698
- });
5770
+ createFeedback(params, options) {
5771
+ const body = {
5772
+ ...params,
5773
+ ...params?.feedback && { feedback: {
5774
+ ...params.feedback,
5775
+ feedbackId: params.feedback.feedbackId ?? (0, _lukeed_uuid.v4)(),
5776
+ timestamp: params.feedback.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
5777
+ } }
5778
+ };
5779
+ return writeSignal(this, "/observability/feedback", "POST", body, options);
5780
+ }
5781
+ /** Replaces Platform feedback using its original identity and timestamp. Each accepted PUT retry is a new replacement. */
5782
+ replaceFeedback(params, options) {
5783
+ return writeSignal(this, `/observability/feedback/${encodeURIComponent(params.feedback.feedbackId)}`, "PUT", params, options);
5699
5784
  }
5700
5785
  /** Updates a feedback record's review workflow status. */
5701
5786
  updateFeedbackReviewStatus(params) {
@@ -8454,13 +8539,17 @@ var MastraClient = class extends BaseResource {
8454
8539
  listLogsVNext(params = {}) {
8455
8540
  return this.observability.listLogs(params);
8456
8541
  }
8542
+ /** Retrieves one score by ID; the response contains null when it is missing. */
8543
+ getScore(id) {
8544
+ return this.observability.getScore(id);
8545
+ }
8457
8546
  /** Retrieves a paginated list of observability scores. */
8458
8547
  listScores(params = {}) {
8459
8548
  return this.observability.listScores(params);
8460
8549
  }
8461
8550
  /** Creates a single score record in the observability store. */
8462
- createScore(params) {
8463
- return this.observability.createScore(params);
8551
+ createScore(params, options) {
8552
+ return this.observability.createScore(params, options);
8464
8553
  }
8465
8554
  /** Deletes score records by scoreId, optionally scoped to a tenant. */
8466
8555
  deleteScores(params) {
@@ -8482,13 +8571,21 @@ var MastraClient = class extends BaseResource {
8482
8571
  getScorePercentiles(params) {
8483
8572
  return this.observability.getScorePercentiles(params);
8484
8573
  }
8574
+ /** Retrieves one feedback by ID; the response contains null when it is missing. */
8575
+ getFeedback(id) {
8576
+ return this.observability.getFeedback(id);
8577
+ }
8485
8578
  /** Retrieves a paginated list of feedback records. */
8486
8579
  listFeedback(params = {}) {
8487
8580
  return this.observability.listFeedback(params);
8488
8581
  }
8489
8582
  /** Creates a single feedback record in the observability store. */
8490
- createFeedback(params) {
8491
- return this.observability.createFeedback(params);
8583
+ createFeedback(params, options) {
8584
+ return this.observability.createFeedback(params, options);
8585
+ }
8586
+ /** Full replacement on Platform. Preserve the original identity/timestamp; each accepted retry is a new replacement. */
8587
+ replaceFeedback(params, options) {
8588
+ return this.observability.replaceFeedback(params, options);
8492
8589
  }
8493
8590
  /** Deletes feedback records by feedbackId, optionally scoped to a tenant. */
8494
8591
  deleteFeedback(params) {