@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.d.ts CHANGED
@@ -15,4 +15,6 @@ export type { DashboardColumn, DashboardDefaults, DashboardDefinition, Dashboard
15
15
  export type { GetMetricTimeSeriesResponse } from './types.js';
16
16
  export type { AggregateTracesArgs, AggregateTracesResponse, AggregateSpansArgs, AggregateSpansResponse, TraceAggregateDiscovery, GetTraceQueryFieldsArgs, GetTraceQueryFieldsResponse, GetTraceQueryValuesArgs, GetTraceQueryValuesResponse, TraceQueryCanonicalFieldDescriptor, TraceQueryGroupResponse, TraceQueryKeysetTraceResponse, TraceQueryObservedFieldDescriptor, TraceQueryOperator, TraceQueryPredicateScope, TraceQueryResponse, TraceQueryTraceResponse, TraceQueryValueKind, } from './resources/observability-route-types.js';
17
17
  export type { Body, Client, ClientMethod, ClientPath, ClientRequest, ClientResponse, ClientResponseKind, ClientRoute, PathParams, QueryParams, RouteKey, RouteRequest, RouteResponse, RouteResponseType, RouteTypes, } from './route-types.generated.js';
18
+ export type { SignalWriteOptions } from './resources/signal-writes.js';
19
+ export type { CreateFeedbackBody, CreateFeedbackResponse, CreateScoreBody, CreateScoreResponse, ReplaceFeedbackBody, } from './resources/observability-route-types.js';
18
20
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EACnB,+BAA+B,GAChC,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,2BAA2B,EAC3B,0BAA0B,EAC1B,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AACvG,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,EAC7B,sCAAsC,EACtC,2BAA2B,EAC3B,UAAU,EACV,yBAAyB,EACzB,+BAA+B,GAChC,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAG9D,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,2BAA2B,EAC3B,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,0BAA0B,EAC1B,mBAAmB,EACnB,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AAC3D,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,2BAA2B,EAC3B,uBAAuB,EACvB,2BAA2B,EAC3B,kCAAkC,EAClC,uBAAuB,EACvB,6BAA6B,EAC7B,iCAAiC,EACjC,kBAAkB,EAClB,wBAAwB,EACxB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,uCAAuC,CAAC;AAC/C,YAAY,EACV,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,UAAU,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,UAAU,GACX,MAAM,4BAA4B,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EACnB,+BAA+B,GAChC,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,2BAA2B,EAC3B,0BAA0B,EAC1B,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AACvG,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,EAC7B,sCAAsC,EACtC,2BAA2B,EAC3B,UAAU,EACV,yBAAyB,EACzB,+BAA+B,GAChC,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAG9D,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,2BAA2B,EAC3B,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,0BAA0B,EAC1B,mBAAmB,EACnB,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AAC3D,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,2BAA2B,EAC3B,uBAAuB,EACvB,2BAA2B,EAC3B,kCAAkC,EAClC,uBAAuB,EACvB,6BAA6B,EAC7B,iCAAiC,EACjC,kBAAkB,EAClB,wBAAwB,EACxB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,uCAAuC,CAAC;AAC/C,YAAY,EACV,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,UAAU,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,UAAU,GACX,MAAM,4BAA4B,CAAC;AAEpC,YAAY,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,uCAAuC,CAAC"}
package/dist/index.js CHANGED
@@ -2909,7 +2909,10 @@ var Agent = class extends BaseResource {
2909
2909
  toolCallId: toolCall.toolCallId,
2910
2910
  toolName: toolCall.toolName,
2911
2911
  input: toolCall.args,
2912
- result,
2912
+ output: {
2913
+ type: "json",
2914
+ value: result
2915
+ },
2913
2916
  ...modelOutput != null ? { providerOptions: { mastra: { modelOutput } } } : {},
2914
2917
  ...observability ? { __mastraObservability: observability } : {}
2915
2918
  });
@@ -3221,20 +3224,27 @@ var Agent = class extends BaseResource {
3221
3224
  * Use this to resume receiving events after a disconnection.
3222
3225
  *
3223
3226
  * @param params.runId - The run ID to observe
3224
- * @param params.offset - Optional position to resume from (0-based). If omitted, replays all events.
3227
+ * @param params.offset - Run-log position to resume from. Chunks from `observe()`, and from `stream()` on
3228
+ * durable and evented agents, carry an `index`; pass the `index + 1` of the last chunk that has one. Chunks without an `index`
3229
+ * (`abort` and structured-output `object` chunks) are skipped when choosing the offset. If omitted,
3230
+ * replays the chunks still cached for the run, or only live chunks if the server's transport can't replay.
3225
3231
  * @returns Promise containing a streaming Response
3226
3232
  *
3227
3233
  * @example
3228
3234
  * ```typescript
3229
- * // Reconnect to a stream from a specific position
3230
- * const response = await client.agents('my-agent').observe({
3231
- * runId: 'run-123',
3232
- * offset: 42, // Resume from event 42
3233
- * });
3235
+ * const agent = client.getAgent('my-agent');
3236
+ * let offset = 0;
3237
+ * const trackOffset = async (chunk: { index?: number }) => {
3238
+ * if (chunk.index === undefined) return;
3239
+ * offset = chunk.index + 1;
3240
+ * };
3234
3241
  *
3235
- * await response.processDataStream({
3236
- * onChunk: (chunk) => console.log('Received:', chunk),
3237
- * });
3242
+ * const stream = await agent.stream(messages, { runId: 'run-123' });
3243
+ * await stream.processDataStream({ onChunk: trackOffset });
3244
+ *
3245
+ * // After a dropped connection, resume where the last indexed chunk left off
3246
+ * const response = await agent.observe({ runId: 'run-123', offset });
3247
+ * await response.processDataStream({ onChunk: trackOffset });
3238
3248
  * ```
3239
3249
  */
3240
3250
  async observe(params) {
@@ -5327,6 +5337,59 @@ var AgentBuilder = class extends BaseResource {
5327
5337
  return this.request(url, { method: "POST" });
5328
5338
  }
5329
5339
  };
5340
+ // src/resources/signal-writes.ts
5341
+ function isMissingAnchor(error) {
5342
+ if (!(error instanceof MastraClientError) || error.status !== 404) return false;
5343
+ const code = error.body?.code;
5344
+ return code === "TRACE_NOT_FOUND" || code === "SPAN_NOT_FOUND";
5345
+ }
5346
+ /** Adds bounded anchor retries to the normal transport retries, with one immutable payload. */
5347
+ async function writeSignal(resource, path, method, body, options = {}) {
5348
+ const { anchorRetryTimeoutMs = 3e4, ...requestOptions } = options;
5349
+ if (!Number.isSafeInteger(anchorRetryTimeoutMs) || anchorRetryTimeoutMs < 0 || anchorRetryTimeoutMs > 3e4) throw new RangeError("anchorRetryTimeoutMs must be an integer between 0 and 30000");
5350
+ const payload = JSON.parse(JSON.stringify(body));
5351
+ const deadline = new AbortController();
5352
+ const signal = mergeAbortSignals(resource.options.abortSignal, options.signal, deadline.signal);
5353
+ let timer;
5354
+ let lastAnchorError;
5355
+ let delay = Math.max(1, resource.options.backoffMs ?? 100);
5356
+ try {
5357
+ for (;;) {
5358
+ try {
5359
+ return await resource.request(path, {
5360
+ ...requestOptions,
5361
+ method,
5362
+ body: payload,
5363
+ signal
5364
+ });
5365
+ } catch (error) {
5366
+ if (signal.aborted) throw error;
5367
+ if (!isMissingAnchor(error) || anchorRetryTimeoutMs === 0) throw error;
5368
+ lastAnchorError = error;
5369
+ timer ??= setTimeout(() => deadline.abort(), anchorRetryTimeoutMs);
5370
+ }
5371
+ await new Promise((resolve, reject) => {
5372
+ const onAbort = () => {
5373
+ clearTimeout(wait);
5374
+ reject(signal.reason);
5375
+ };
5376
+ const wait = setTimeout(() => {
5377
+ signal.removeEventListener("abort", onAbort);
5378
+ resolve();
5379
+ }, delay);
5380
+ signal.addEventListener("abort", onAbort, { once: true });
5381
+ if (signal.aborted) onAbort();
5382
+ });
5383
+ delay = Math.max(1, Math.min(delay * 2, resource.options.maxBackoffMs ?? 1e3));
5384
+ }
5385
+ } catch (error) {
5386
+ if (deadline.signal.aborted && !options.signal?.aborted && !resource.options.abortSignal?.aborted && (error === deadline.signal.reason || error instanceof Error && error.name === "AbortError")) throw lastAnchorError ?? error;
5387
+ throw error;
5388
+ } finally {
5389
+ clearTimeout(timer);
5390
+ deadline.abort();
5391
+ }
5392
+ }
5330
5393
  // src/resources/observability.ts
5331
5394
  /** Client resource for interacting with the Mastra observability API (traces, logs, scores, feedback, and metrics). */
5332
5395
  var Observability = class extends BaseResource {
@@ -5585,6 +5648,10 @@ var Observability = class extends BaseResource {
5585
5648
  ]);
5586
5649
  return this.request(`/observability/logs${queryString ? `?${queryString}` : ""}`);
5587
5650
  }
5651
+ /** Retrieves one score by ID; the response contains null when it is missing. */
5652
+ getScore(id) {
5653
+ return this.request(`/observability/scores/${encodeURIComponent(id)}`);
5654
+ }
5588
5655
  /**
5589
5656
  * Retrieves a paginated list of scores with optional filtering and sorting.
5590
5657
  */
@@ -5598,13 +5665,18 @@ var Observability = class extends BaseResource {
5598
5665
  }
5599
5666
  /**
5600
5667
  * Creates a single score record in the observability store.
5601
- * Timestamp is set server-side.
5668
+ * Missing IDs and timestamps are generated once, before retries.
5602
5669
  */
5603
- createScore(params) {
5604
- return this.request(`/observability/scores`, {
5605
- method: "POST",
5606
- body: params
5607
- });
5670
+ createScore(params, options) {
5671
+ const body = {
5672
+ ...params,
5673
+ ...params?.score && { score: {
5674
+ ...params.score,
5675
+ scoreId: params.score.scoreId ?? v4(),
5676
+ timestamp: params.score.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
5677
+ } }
5678
+ };
5679
+ return writeSignal(this, "/observability/scores", "POST", body, options);
5608
5680
  }
5609
5681
  /**
5610
5682
  * Deletes score records by scoreId, optionally scoped to a tenant.
@@ -5653,6 +5725,10 @@ var Observability = class extends BaseResource {
5653
5725
  body: params
5654
5726
  });
5655
5727
  }
5728
+ /** Retrieves one feedback by ID; the response contains null when it is missing. */
5729
+ getFeedback(id) {
5730
+ return this.request(`/observability/feedback/${encodeURIComponent(id)}`);
5731
+ }
5656
5732
  /**
5657
5733
  * Retrieves a paginated list of feedback with optional filtering and sorting.
5658
5734
  */
@@ -5666,13 +5742,22 @@ var Observability = class extends BaseResource {
5666
5742
  }
5667
5743
  /**
5668
5744
  * Creates a single feedback record in the observability store.
5669
- * Timestamp is set server-side.
5745
+ * Missing IDs and timestamps are generated once, before retries.
5670
5746
  */
5671
- createFeedback(params) {
5672
- return this.request(`/observability/feedback`, {
5673
- method: "POST",
5674
- body: params
5675
- });
5747
+ createFeedback(params, options) {
5748
+ const body = {
5749
+ ...params,
5750
+ ...params?.feedback && { feedback: {
5751
+ ...params.feedback,
5752
+ feedbackId: params.feedback.feedbackId ?? v4(),
5753
+ timestamp: params.feedback.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
5754
+ } }
5755
+ };
5756
+ return writeSignal(this, "/observability/feedback", "POST", body, options);
5757
+ }
5758
+ /** Replaces Platform feedback using its original identity and timestamp. Each accepted PUT retry is a new replacement. */
5759
+ replaceFeedback(params, options) {
5760
+ return writeSignal(this, `/observability/feedback/${encodeURIComponent(params.feedback.feedbackId)}`, "PUT", params, options);
5676
5761
  }
5677
5762
  /** Updates a feedback record's review workflow status. */
5678
5763
  updateFeedbackReviewStatus(params) {
@@ -8431,13 +8516,17 @@ var MastraClient = class extends BaseResource {
8431
8516
  listLogsVNext(params = {}) {
8432
8517
  return this.observability.listLogs(params);
8433
8518
  }
8519
+ /** Retrieves one score by ID; the response contains null when it is missing. */
8520
+ getScore(id) {
8521
+ return this.observability.getScore(id);
8522
+ }
8434
8523
  /** Retrieves a paginated list of observability scores. */
8435
8524
  listScores(params = {}) {
8436
8525
  return this.observability.listScores(params);
8437
8526
  }
8438
8527
  /** Creates a single score record in the observability store. */
8439
- createScore(params) {
8440
- return this.observability.createScore(params);
8528
+ createScore(params, options) {
8529
+ return this.observability.createScore(params, options);
8441
8530
  }
8442
8531
  /** Deletes score records by scoreId, optionally scoped to a tenant. */
8443
8532
  deleteScores(params) {
@@ -8459,13 +8548,21 @@ var MastraClient = class extends BaseResource {
8459
8548
  getScorePercentiles(params) {
8460
8549
  return this.observability.getScorePercentiles(params);
8461
8550
  }
8551
+ /** Retrieves one feedback by ID; the response contains null when it is missing. */
8552
+ getFeedback(id) {
8553
+ return this.observability.getFeedback(id);
8554
+ }
8462
8555
  /** Retrieves a paginated list of feedback records. */
8463
8556
  listFeedback(params = {}) {
8464
8557
  return this.observability.listFeedback(params);
8465
8558
  }
8466
8559
  /** Creates a single feedback record in the observability store. */
8467
- createFeedback(params) {
8468
- return this.observability.createFeedback(params);
8560
+ createFeedback(params, options) {
8561
+ return this.observability.createFeedback(params, options);
8562
+ }
8563
+ /** Full replacement on Platform. Preserve the original identity/timestamp; each accepted retry is a new replacement. */
8564
+ replaceFeedback(params, options) {
8565
+ return this.observability.replaceFeedback(params, options);
8469
8566
  }
8470
8567
  /** Deletes feedback records by feedbackId, optionally scoped to a tenant. */
8471
8568
  deleteFeedback(params) {