@sentry/api 0.353.0 → 0.356.0

package/README.md

@@ -23,10 +23,10 @@ const sentry = createSentryClient({
   headers: { Authorization: `Bearer ${process.env.SENTRY_AUTH_TOKEN}` },
 });
 
-const { data, error } = await sentry.listOrganizations();
+const result = await sentry.listOrganizations();
 
-if (error !== undefined) throw error;
-console.log(data);
+if ("error" in result) throw result.error;
+console.log(result.data);
 ```
 
 Operation methods retain the generated documentation, typed arguments, and response types. Per-call options include `path`, `query`, `headers`, `signal`, and `throwOnError`. Results preserve the underlying `request` and `response`, including response headers:
@@ -46,7 +46,9 @@ const { data: project, request, response } = await sentry.getProject({
 console.log(project, request.url, response.headers.get("content-type"));
 ```
 
-By default, operations return a `data`/`error` result. Set `throwOnError: true` to reject on errors, as above. Methods are bound to their instance and can be safely destructured, such as `const { getProject } = sentry`.
+Operations always return `fields`: `{ data, request, response }` on success, or `{ error, request, response }` on failure. A failure without an HTTP response has `response: undefined`. Check `"error" in result`, since a custom error can itself be `undefined`. Received headers are in `response.headers`; outgoing headers are in `request.headers`.
+
+Set `throwOnError: true` to reject on failures while keeping the same success fields. Methods are bound to their instance and can be safely destructured, such as `const { getProject } = sentry`. Types narrow to success when `true` is supplied **per call**; calls that inherit mutable client configuration conservatively retain the result union.
 
 Each `createSentryClient` call creates an independent transport configuration. The root entry also exports the `SentryClient` and `Config` types; `Config` is the underlying transport's configuration type. Access that transport as `sentry.client` for interceptors, configuration updates, or low-level requests.
 
@@ -82,6 +84,37 @@ const sentry = createSentryClient(
 const { data, error } = await sentry.listOrganizations();
 ```
 
+### Cancellation and custom fetch
+
+Reuse the client and supply an `AbortSignal` for each operation. The caller owns the signal, whether it comes from a command, an MCP tool call, or a query library:
+
+```ts
+const controller = new AbortController();
+const pending = sentry.listOrganizations({
+  signal: controller.signal,
+  throwOnError: true,
+});
+
+// When this operation is no longer needed:
+controller.abort();
+await pending; // Rejects with the cancellation reason by default.
+```
+
+Cancellation does not affect other calls sharing the client. Immediately before invoking `fetch`, the SDK checks the final request's signal, including changes made by request interceptors. An already-aborted signal prevents dispatch; authentication, validation, and request interceptors may still run before that check.
+
+A configured `fetch` receives a native `Request`; its method, body, headers, and signal need not appear in a separate `init` argument. Forward the request intact and preserve native `RequestInit` override semantics when wrapping another transport:
+
+```ts
+const sentry = createSentryClient({
+  baseUrl: "https://sentry.io",
+  fetch: (input, init) => fetch(input, init),
+});
+```
+
+Your transport must honor the signal while a request is in flight. The SDK cannot force an arbitrary custom fetch or asynchronous hook to stop, and cancellation does not undo a server mutation that has already completed.
+
+Cancellation follows the [error handling contract](#error-handling): before dispatch the SDK uses `signal.reason`; during fetch it preserves the transport's rejection, which may differ by runtime. By default this is returned as `{ error, request, response: undefined }`, or thrown with `throwOnError: true`. Error interceptors can intentionally map it. Cancellation during response body reading rejects unchanged, even in fields mode. There is no SDK-specific cancellation error class.
+
 ## Runtime validation
 
 The root `@sentry/api` entry has no runtime dependencies. It provides the API client and pure TypeScript types without installing a validation library.
@@ -115,7 +148,43 @@ const project = zGetProjectResponse.parse(input);
 
 ## Error handling
 
-Every operation with documented error responses has a generated `narrowError_<operation>` wrapper. It returns data or a `SentryApiError` that preserves the operation's status-to-body type map. These wrappers remain standalone functions; pass `sentry.client` to reuse the client configured above:
+HTTP failures use `SentryApiError`, whether returned in `result.error` or thrown with `throwOnError: true`. It preserves the status, parsed `body`, exact `rawBody` text, `request`, and `response` (including headers). The transport reads the error body once; consumers do not need to clone or reread the response. Error bodies without valid JSON remain strings.
+
+```ts
+import { SentryApiError } from "@sentry/api";
+
+const result = await sentry.listOrganizations();
+if ("error" in result) {
+  if (result.error instanceof SentryApiError) {
+    console.log(result.error.status, result.error.body, result.error.rawBody);
+    console.log(result.error.response?.headers.get("retry-after"));
+  }
+  throw result.error;
+}
+```
+
+`error` is typed as `unknown`: a custom `fetch` or error interceptor can supply its own error. Fetch rejections, including cancellation, keep their original identity and have no HTTP response. They are returned or thrown according to `throwOnError`. Exceptions from serialization, validation, interceptors, or response body reading/decoding reject unchanged, even with `throwOnError: false`; that setting does not make a request exception-free.
+
+### Custom errors
+
+HTTP errors are normalized **before** error interceptors run. Interceptors run in registration order, each receiving the preceding interceptor's result. Their returned or thrown value is preserved by operations and pagination; there is no second normalization pass.
+
+```ts
+sentry.client.interceptors.error.use((error, response, request) => {
+  if (error instanceof SentryApiError) {
+    // Return your application's existing error type here, if needed.
+    return new Error(`API ${error.status}: ${request.method} ${request.url}`, {
+      cause: error,
+    });
+  }
+  // No HTTP response for a rejected fetch. Preserve cancellation/custom errors.
+  return error;
+});
+```
+
+### Opt-in status narrowing
+
+Every operation with documented error responses has a generated `narrowError_<operation>` wrapper. It narrows the default HTTP `SentryApiError` to the operation's status-to-body type map, preserving its metadata. These wrappers remain standalone functions; pass `sentry.client` to reuse the client configured above:
 
 ```ts
 import { narrowError_getProject } from "@sentry/api";
@@ -130,7 +199,7 @@ const result = await narrowError_getProject({
 
 if (!result.ok) {
   if (!result.error.documented) {
-    // Unexpected HTTP status or a transport failure.
+    // Unexpected HTTP status.
     throw result.error;
   }
 
@@ -142,7 +211,17 @@ if (!result.ok) {
 }
 ```
 
-Checking `documented` first separates the operation's finite error union from unexpected statuses and transport failures. Within the documented branch, checking `status` narrows `body` to that response's schema. Error bodies remain `unknown` where the source OpenAPI response has no schema.
+Checking `documented` first separates the operation's finite HTTP error union from unexpected statuses. Within the documented branch, checking `status` narrows `body` to that response's schema. This is a schema-based type assertion, **not runtime payload validation**. Error bodies remain `unknown` where the source OpenAPI response has no schema. Ordinary operations set `documented: false`; only these opt-in helpers know the operation's status map.
+
+These helpers reclassify base `SentryApiError` instances belonging to the operation's response, including ones returned by an interceptor. Other errors—including custom classes/subclasses, fetch failures, cancellation, and decoding/validation exceptions—reject unchanged. They are not used implicitly by operations or pagination. Consumers that own their error model should use ordinary operations instead.
+
+### Migrating the 0.x response contract
+
+- `responseStyle: "data"` is no longer accepted, including at initialization, `setConfig`, and per call. JavaScript callers receive a `TypeError` before a request is sent. Read `result.data` from the stable fields result instead.
+- HTTP errors previously exposed a raw body; now read `error.body` after narrowing to `SentryApiError`. `error.rawBody` retains the original text.
+- Successful results omit `error`; failed results include it even when the error value is falsy. Manual result fixtures must follow that shape. Use `"error" in result` rather than a truthiness check.
+- Error interceptors receive normalized HTTP errors and chain their returned values. Pagination and `unwrapResult` no longer create another error or prepend a helper-specific message; their legacy `context` argument remains accepted.
+- `narrowError_*` and `callWithTypedErrors` now narrow HTTP failures only. Other failures reject unchanged instead of becoming a synthetic transport `SentryApiError`. `SentryApiTransportError` remains a deprecated type alias, but is no longer part of `NarrowedResult`.
 
 ## Pagination
 
@@ -151,14 +230,16 @@ Sentry uses cursor-based pagination via `Link` headers. Choose one of three help
 | Task | Method | Result |
 | --- | --- | --- |
 | Display one page, with previous/next navigation | `sentry.fetchPage.<operation>(options, cursor?)` | `{ data, response, nextCursor?, prevCursor? }` |
-| Collect up to an item limit | `sentry.paginateUpTo.<operation>(options, { limit, ... })` | `{ data, nextCursor? }` |
-| Explicitly collect pages eagerly | `sentry.paginateAll.<operation>(options, { maxPages? }?)` | Concatenated array; stops at `maxPages` (default 50) |
+| Collect up to an item limit | `sentry.paginateUpTo.<operation>(options, { limit, ... })` | `{ data, stopReason, nextCursor? }` |
+| Explicitly collect pages eagerly | `sentry.paginateAll.<operation>(options, { maxPages?, startCursor? }?)` | `{ data, stopReason, nextCursor? }` |
 
 `fetchPage` is available for operations whose schema declares a `cursor` query parameter. Collection helpers are available only when the operation's 200 response is an array. Compound response bodies remain intact. Ordinary operation methods such as `sentry.listOrganizations()` still make just one request.
 
 All helpers reuse the instance's configuration and interceptors and can be destructured. They manage `cursor` separately from `query`, retaining your path, filters, and `signal` while invoking the configured operation. The SDK does not own page history or a response cache: the consumer keeps cursors in its URL, query cache, or persistent storage.
 
-Pagination needs the transport's default `responseStyle: "fields"` to read HTTP headers; `responseStyle: "data"` is not supported. Helpers reject on failure: under the default error policy, they throw `SentryApiError`; if the transport is configured with `throwOnError: true`, its thrown error propagates directly.
+Pagination reads HTTP headers from the same fields contract. Helpers always reject on failure, preserving the exact error: `SentryApiError` for default HTTP failures, or the original custom error/cancellation. This is consistent whether `throwOnError` is enabled or disabled.
+
+Generated collection helpers pass the same signal to every page operation. If it aborts between pages, the next page is not dispatched and the collection rejects; no partial collection is returned.
 
 ### Single page
 
@@ -182,35 +263,67 @@ Each page preserves its own raw `Response`, including status and headers. The tr
 ### Bounded collection
 
 ```ts
-const batch = await sentry.paginateUpTo.listOrganizationProjects(
-  {
-    path: { organization_id_or_slug: "my-org" },
-    query: { per_page: 50 },
-  },
-  { limit: 250 },
-);
-
-console.log(batch.data, batch.nextCursor);
+const options = { path: { organization_id_or_slug: "my-org" } };
+const batch = await sentry.paginateUpTo.listOrganizationIssues(options, {
+  limit: 250,
+  maxPages: 5,
+});
+// Requests 100 + 100 + 50 when the server returns full pages.
+console.log(batch.data, batch.stopReason);
+
+if (batch.nextCursor !== undefined) {
+  const next = await sentry.paginateUpTo.listOrganizationIssues(options, {
+    limit: 250,
+    startCursor: batch.nextCursor,
+  });
+}
 ```
 
-The total item limit and the HTTP page size are separate. Currently the helper uses the same requested page size for each request. If the last page overshoots the item limit, it trims the data and suppresses `nextCursor` by default to avoid skipping the discarded rows. The example uses 50-item HTTP pages for a 250-item budget.
+Automatic sizing is deliberately limited to operations whose forward cursors have been verified to support changing page size:
+
+| Operation | HTTP size parameter | Maximum per request |
+| --- | --- | --- |
+| `listOrganizationIssues`, `listProjectIssues` | `limit` | 100 |
+| `listOrganizationIssueEvents` | `per_page` | 100; 10 with `full: true` |
+
+Each request uses the smallest of the remaining item budget, the caller's requested page size (if supplied), and the verified maximum. Other operations retain their query options unchanged. In particular, **projects do not use 100 + 100 + 50**: their backend `OffsetPaginator` includes the page size in its cursor, and resizing mid-traversal can skip rows. Declaring `per_page` in the schema is not enough to enable resizing.
+
+If a server ignores the size or an operation cannot be resized, the helper trims any excess rows and omits the unsafe cursor. It reports `stopReason: "limit"`, even if that was the server's last page. Use `fetchPage` when every row and each page's headers must be retained.
 
-### Eager collection
+### Eager collection and completion
 
 ```ts
 const projects = await sentry.paginateAll.listOrganizationProjects(
   { path: { organization_id_or_slug: "my-org" } },
   { maxPages: 50 },
 );
+console.log(projects.data, projects.stopReason);
+// If stopReason is "maxPages", projects.nextCursor resumes traversal.
 ```
 
-Collection results do not expose a single `response`: their data can come from several HTTP requests. Use `fetchPage` when you need each page's headers or incremental loading.
+Both collection helpers return `PaginatedCollection<TItem>`:
+
+| `stopReason` | Meaning | `nextCursor` |
+| --- | --- | --- |
+| `"exhausted"` | All fetched rows were returned and the server advertises no next page | Absent |
+| `"limit"` | The item budget stopped collection | Present only when no rows were discarded |
+| `"maxPages"` | The request cap stopped collection while more pages exist | Present |
 
-### Current collection limits
+Only `stopReason === "exhausted"` means complete. If the final server page exactly fills the item budget, exhaustion takes precedence. A missing cursor alone does not mean complete.
 
-The bound methods preserve the existing helpers' behavior. `paginateAll` can return an incomplete array when it reaches `maxPages`, without identifying that condition. `paginateUpTo` also drops `nextCursor` when that cap is reached, so its absence does not prove the collection is exhausted. Use explicit page traversal when you need reliable exhaustion detection today.
+`maxPages` defaults to 50 for both helpers. `limit` and `maxPages` must be positive safe integers. Resume forward from a returned `nextCursor`, keeping the same operation, filters, and page-size options; cursors stay opaque. SDK calls do not retain a history or snapshot the collection against concurrent server changes. Errors and cancellation reject the collection call, including after earlier pages succeeded.
 
-Operation-aware page sizing and explicit completion/continuation metadata are tracked in [#99](https://github.com/getsentry/sentry-api-schema/issues/99). Frontend query adapters and CLI navigation integration are also follow-up work. The existing `keepCursorOnOvershoot` escape hatch remains available for compatibility; its safety depends on the endpoint's cursor semantics.
+Collection results have no single `response`: their data may come from several HTTP requests. Frontend tables and infinite queries can keep using `fetchPage` with their own URL/cache state. CLI history, MCP output budgets, and TanStack adapters remain consumer integrations tracked in [#99](https://github.com/getsentry/sentry-api-schema/issues/99).
+
+### Migration from earlier 0.x helpers
+
+```ts
+// Before: const projects = await sentry.paginateAll.listOrganizationProjects(options);
+const { data: projects, stopReason, nextCursor } =
+  await sentry.paginateAll.listOrganizationProjects(options);
+```
+
+`paginateAll` now returns a collection object instead of an array, for bound, standalone, and generic helpers. `paginateUpTo` adds `stopReason` and preserves safe continuation at `maxPages`. The unsafe `keepCursorOnOvershoot` option has been removed; no cursor may skip discarded rows. Invalid item/request budgets now reject before fetching.
 
 ### Standalone pagination
 
@@ -237,6 +350,10 @@ The same low-level helpers used by the generated wrappers are also exported for
 - `unwrapPaginatedResult(sdkResult, context)` — same but with cursors
 - `fetchPage`, `paginateAll`, `paginateUpTo` — generic versions taking a fetcher thunk
 
+A generic `paginateUpTo` fetcher receives `(cursor, remaining)`. Existing cursor-only fetchers still work; use `remaining` only when your endpoint's cursor supports resizing. The generated wrappers apply the verified rules above for you.
+
+Generic helpers delegate cancellation to your fetcher. Pass its signal through to the operation or transport it invokes; the helper cannot cancel an arbitrary callback.
+
 ## Schema source
 
 The OpenAPI schema is synced from [`getsentry/sentry`](https://github.com/getsentry/sentry/tree/master/api-docs). Schema fixes belong there; build/tooling changes belong here.

package/dist/client/types.gen.d.ts

@@ -1,8 +1,9 @@
+import type { SdkResult } from '../sentry-errors';
 import type { Auth } from '../core/auth.gen';
 import type { ServerSentEventsOptions, ServerSentEventsResult } from '../core/serverSentEvents.gen';
 import type { Client as CoreClient, Config as CoreConfig } from '../core/types.gen';
 import type { Middleware } from './utils.gen';
-export type ResponseStyle = 'data' | 'fields';
+export type ResponseStyle = 'fields';
 export interface Config<T extends ClientOptions = ClientOptions> extends Omit<RequestInit, 'body' | 'headers' | 'method'>, CoreConfig {
     /**
      * Base URL for all requests made by this client.
@@ -32,7 +33,7 @@ export interface Config<T extends ClientOptions = ClientOptions> extends Omit<Re
      */
     parseAs?: 'arrayBuffer' | 'auto' | 'blob' | 'formData' | 'json' | 'stream' | 'text';
     /**
-     * Should we return only data or multiple fields (data, error, response, etc.)?
+     * Responses always include fields (data or error, request, response).
      *
      * @default 'fields'
      */
@@ -65,28 +66,19 @@ export interface RequestOptions<TData = unknown, TResponseStyle extends Response
 export interface ResolvedRequestOptions<TResponseStyle extends ResponseStyle = 'fields', ThrowOnError extends boolean = boolean, Url extends string = string> extends RequestOptions<unknown, TResponseStyle, ThrowOnError, Url> {
     serializedBody?: string;
 }
-export type RequestResult<TData = unknown, TError = unknown, ThrowOnError extends boolean = boolean, TResponseStyle extends ResponseStyle = 'fields'> = ThrowOnError extends true ? Promise<TResponseStyle extends 'data' ? TData extends Record<string, unknown> ? TData[keyof TData] : TData : {
+export type RequestResult<TData = unknown, TError = unknown, ThrowOnError extends boolean = boolean, TResponseStyle extends ResponseStyle = 'fields'> = Promise<ThrowOnError extends true ? {
     data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
     request: Request;
     response: Response;
-}> : Promise<TResponseStyle extends 'data' ? (TData extends Record<string, unknown> ? TData[keyof TData] : TData) | undefined : ({
-    data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
-    error: undefined;
-} | {
-    data: undefined;
-    error: TError extends Record<string, unknown> ? TError[keyof TError] : TError;
-}) & {
-    request: Request;
-    response: Response;
-}>;
+} : SdkResult<TData extends Record<string, unknown> ? TData[keyof TData] : TData>>;
 export interface ClientOptions {
     baseUrl?: string;
     responseStyle?: ResponseStyle;
     throwOnError?: boolean;
 }
-type MethodFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
+type MethodFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: (Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'>) & RequireThrowOnError<ThrowOnError>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
 type SseFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'>) => Promise<ServerSentEventsResult<TData, TError>>;
-type RequestFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'> & Pick<Required<RequestOptions<TData, TResponseStyle, ThrowOnError>>, 'method'>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
+type RequestFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: (Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'> & Pick<Required<RequestOptions<TData, TResponseStyle, ThrowOnError>>, 'method'>) & RequireThrowOnError<ThrowOnError>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
 type BuildUrlFn = <TData extends {
     body?: unknown;
     path?: Record<string, unknown>;
@@ -113,5 +105,11 @@ export interface TDataShape {
     url: string;
 }
 type OmitKeys<T, K> = Pick<T, Exclude<keyof T, K>>;
-export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown, TResponseStyle extends ResponseStyle = 'fields'> = OmitKeys<RequestOptions<TResponse, TResponseStyle, ThrowOnError>, 'body' | 'path' | 'query' | 'url'> & ([TData] extends [never] ? unknown : Omit<TData, 'url'>);
+export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown, TResponseStyle extends ResponseStyle = 'fields'> = (OmitKeys<RequestOptions<TResponse, TResponseStyle, ThrowOnError>, 'body' | 'path' | 'query' | 'url'> & ([TData] extends [never] ? unknown : Omit<TData, 'url'>)) & RequireThrowOnError<ThrowOnError>;
+/** Success-only types require a per-call runtime guarantee. */
+type RequireThrowOnError<ThrowOnError extends boolean> = [
+    ThrowOnError
+] extends [true] ? {
+    throwOnError: true;
+} : unknown;
 export {};

package/dist/client/utils.gen.d.ts

@@ -11,7 +11,7 @@ export declare const setAuthParams: ({ security, ...options }: Pick<Required<Req
 export declare const buildUrl: Client['buildUrl'];
 export declare const mergeConfigs: (a: Config, b: Config) => Config;
 export declare const mergeHeaders: (...headers: Array<Required<Config>["headers"] | undefined>) => Headers;
-type ErrInterceptor<Err, Res, Req, Options> = (error: Err, response: Res, request: Req, options: Options) => Err | Promise<Err>;
+type ErrInterceptor<Err, Res, Req, Options> = (error: Err, response: Res | undefined, request: Req, options: Options) => Err | Promise<Err>;
 type ReqInterceptor<Req, Options> = (request: Req, options: Options) => Req | Promise<Req>;
 type ResInterceptor<Res, Req, Options> = (response: Res, request: Req, options: Options) => Res | Promise<Res>;
 declare class Interceptors<Interceptor> {