@sentry/api 0.353.0 → 0.356.0

package/dist/sentry-errors.d.ts

@@ -5,11 +5,11 @@
  */
 export type SdkResult<TData = unknown, TError = unknown> = {
     data: TData;
-    error: undefined;
+    error?: never;
     request: Request;
     response: Response;
 } | {
-    data: undefined;
+    data?: never;
     error: TError;
     request: Request;
     response: Response | undefined;
@@ -21,9 +21,12 @@ export type DocumentedSentryApiError<TErrorMap> = {
 }[ErrorStatus<TErrorMap>];
 /** An API error returned under a status absent from the operation's schema. */
 export type UndocumentedSentryApiError = SentryApiError<number, unknown, false>;
-/** A request failure that happened before an HTTP response arrived. */
+/**
+ * @deprecated Non-HTTP failures propagate unchanged. Typed-error helpers only
+ * return HTTP failures and no longer produce this legacy wrapper.
+ */
 export type SentryApiTransportError = SentryApiError<undefined, unknown, false>;
-export type SentryApiResultError<TErrorMap> = DocumentedSentryApiError<TErrorMap> | UndocumentedSentryApiError | SentryApiTransportError;
+export type SentryApiResultError<TErrorMap> = DocumentedSentryApiError<TErrorMap> | UndocumentedSentryApiError;
 export type NarrowedResult<TData, TErrorMap> = {
     ok: true;
     data: TData;
@@ -38,18 +41,28 @@ export declare class SentryApiError<TStatus extends number | undefined = number
     readonly body: TBody;
     readonly response: Response | undefined;
     readonly documented: TDocumented;
-    constructor(status: TStatus, body: TBody, response: Response | undefined, documented: TDocumented, message?: string);
+    readonly request?: Request;
+    /** Original response text, captured during the same read as the parsed body. */
+    readonly rawBody?: string;
+    constructor(status: TStatus, body: TBody, response: Response | undefined, documented: TDocumented, message?: string, options?: ErrorOptions & {
+        request?: Request;
+        rawBody?: string;
+    });
 }
 /**
- * Convert an SDK result to a status-discriminated result.
+ * Convert an SDK result to a status-discriminated HTTP result.
  *
  * Prefer the generated `narrowError_<operation>` wrappers. They supply the
  * operation's complete error map and documented statuses automatically.
+ * Base SentryApiError instances for this response are reclassified, including
+ * ones supplied by an interceptor. Other errors (including subclasses) are
+ * thrown unchanged. Status narrowing does not validate the response body.
  */
-export declare const narrowError: <TData, TErrorMap>(result: SdkResult<TData, TErrorMap[ErrorStatus<TErrorMap>]>, documentedStatuses: ReadonlyArray<ErrorStatus<TErrorMap>>) => NarrowedResult<TData, TErrorMap>;
+export declare const narrowError: <TData, TErrorMap>(result: SdkResult<TData>, documentedStatuses: ReadonlyArray<ErrorStatus<TErrorMap>>) => NarrowedResult<TData, TErrorMap>;
 /**
- * Call an SDK operation and convert HTTP and transport failures to one result.
- * Generated operation wrappers use this helper.
+ * Call an SDK operation and narrow its default HTTP errors by status.
+ * Generated operation wrappers use this helper. Errors outside narrowError's
+ * HTTP contract reject without being relabeled or wrapped.
  */
-export declare const callWithTypedErrors: <TData, TErrorMap>(call: () => Promise<SdkResult<TData, TErrorMap[ErrorStatus<TErrorMap>]>>, documentedStatuses: ReadonlyArray<ErrorStatus<TErrorMap>>) => Promise<NarrowedResult<TData, TErrorMap>>;
+export declare const callWithTypedErrors: <TData, TErrorMap>(call: () => Promise<SdkResult<TData>>, documentedStatuses: ReadonlyArray<ErrorStatus<TErrorMap>>) => Promise<NarrowedResult<TData, TErrorMap>>;
 export {};

package/dist/sentry-pagination.d.ts

@@ -5,7 +5,7 @@
  * These helpers make it ergonomic to paginate through results
  * returned by the generated SDK functions.
  */
-import { type SdkResult } from "./sentry-errors";
+import type { SdkResult } from "./sentry-errors";
 export type UnwrappedResult<TData> = {
     data: TData;
     response: Response;
@@ -19,36 +19,32 @@ export type PaginatedResponse<T> = {
     /** Cursor for the previous page. `undefined` on the first page. */
     prevCursor?: string;
 };
+/** Aggregate data has no single HTTP response. Only `exhausted` means complete. */
+export type PaginatedCollection<TItem> = {
+    data: Array<TItem>;
+    stopReason: "exhausted" | "limit" | "maxPages";
+    /** Omitted when exhausted or when trimming a page makes continuation unsafe. */
+    nextCursor?: string;
+};
 export type PaginateAllOptions = {
     /** Hard cap on the number of pages fetched. Default: 50. */
     maxPages?: number;
+    /** Resume from a previous nextCursor, keeping the same filters and page size. */
+    startCursor?: string;
 };
 export type PaginateUpToOptions = {
     /** Hard cap on the number of items returned. Required. */
     limit: number;
     /** Safety cap on the number of pages fetched. Default: 50. */
     maxPages?: number;
-    /** Resume pagination from this cursor instead of starting from the beginning. */
+    /** Resume forward traversal from a previous nextCursor, keeping the same query. */
     startCursor?: string;
     /** Called after each page is fetched. Useful for progress indicators. */
     onPage?: (fetched: number, limit: number) => void;
-    /**
-     * When true, preserve `nextCursor` even when the last page was trimmed
-     * to fit `limit`. Default: false (the safe default — see body comment).
-     *
-     * Use this only for endpoints that have **no** server-side per-page
-     * control (so the trimmed tail items remain reachable via the same
-     * cursor on the next call). Sentry's `/issues/{id}/events/` is one
-     * such endpoint: it has no `per_page` param, so dropping the cursor
-     * on overshoot would orphan the items the helper trimmed.
-     *
-     * For endpoints that DO support `per_page` / `limit`, leave this
-     * `false` — returning a cursor that points past trimmed items would
-     * cause callers resuming pagination to skip records.
-     */
-    keepCursorOnOvershoot?: boolean;
 };
 export type PageFetcher<TData, TError> = (cursor: string | undefined) => Promise<SdkResult<TData, TError>>;
+/** The remaining item budget lets a custom fetcher reduce its HTTP page size. */
+export type BudgetedPageFetcher<TData, TError> = (cursor: string | undefined, remaining: number) => Promise<SdkResult<TData, TError>>;
 /**
  * Parse Sentry's Link header to extract pagination cursors.
  *
@@ -69,7 +65,7 @@ export declare const parseSentryLinkHeader: (header: string | null) => {
     prevCursor?: string;
 };
 /**
- * Internal: merge a managed `cursor` into an SDK call's `options.query`
+ * Internal: merge a managed cursor and verified page-size budget into `options.query`
  * and re-shape the result back to the SDK's `Options<TData>` type.
  *
  * Used exclusively by the auto-generated wrappers in `pagination.gen.ts`
@@ -91,17 +87,25 @@ export declare const parseSentryLinkHeader: (header: string | null) => {
 export declare const _withCursor: <TOptions>(options: {
     query?: unknown;
     [k: string]: unknown;
-}, cursor: string | undefined) => TOptions;
+}, cursor: string | undefined, pageSize?: {
+    parameter: "per_page" | "limit";
+    max: number;
+    remaining: number;
+}) => TOptions;
 /**
  * Unwrap an SDK result, throwing on error.
  *
  * Returns `{ data, response }` so callers retain access to the
  * raw Response (and its headers) for pagination or other needs.
  *
- * The thrown value is a {@link SentryApiError}, so a `catch` block can still
- * read `err.status` / `err.body` to decide how to handle the failure.
+ * Throws the exact error supplied by the operation, including custom mapped
+ * errors and failures without an HTTP response. The SDK normalizes default
+ * HTTP errors before this helper runs.
+ *
+ * The context argument remains accepted for compatibility. It no longer
+ * changes error messages or wraps errors.
  */
-export declare const unwrapResult: <TData, TError = unknown>(result: SdkResult<TData, TError>, context: string) => UnwrappedResult<TData>;
+export declare const unwrapResult: <TData, TError = unknown>(result: SdkResult<TData, TError>, _context: string) => UnwrappedResult<TData>;
 /**
  * Unwrap an SDK result and extract pagination cursors from the
  * Link header. Throws on error.
@@ -134,47 +138,16 @@ export declare const unwrapPaginatedResult: <TData>(result: SdkResult<TData>, co
  */
 export declare const fetchPage: <TData, TError = unknown>(fetcher: PageFetcher<TData, TError>, context: string, cursor?: string) => Promise<PaginatedResponse<TData>>;
 /**
- * Automatically paginate through all pages of a Sentry list endpoint.
- *
- * Fetches pages sequentially until there is no next cursor or
- * `maxPages` is reached (default: 50). Returns all items concatenated.
- *
- * @example
- * ```ts
- * const allRepos = await paginateAll(
- *   (cursor) => listAnOrganization_sRepositories({
- *     path: { organization_id_or_slug: 'my-org' },
- *     query: { cursor },
- *   }),
- *   'listRepos',
- * );
- * ```
+ * Collect pages until the collection is exhausted or `maxPages` is reached.
+ * A request cap returns `stopReason: "maxPages"` and a safe resume cursor.
  */
-export declare const paginateAll: <TItem, TError = unknown>(fetcher: PageFetcher<Array<TItem>, TError>, context: string, options?: PaginateAllOptions) => Promise<Array<TItem>>;
+export declare const paginateAll: <TItem, TError = unknown>(fetcher: PageFetcher<Array<TItem>, TError>, context: string, options?: PaginateAllOptions) => Promise<PaginatedCollection<TItem>>;
 /**
- * Paginate up to a hard limit of items, suppressing the next-cursor
- * if the last fetched page had to be trimmed to fit.
+ * Collect up to `limit` items, passing the remaining budget to the fetcher.
+ * Generated wrappers use it to reduce supported HTTP page sizes.
  *
- * The trim-and-suppress behavior is intentional: returning a cursor
- * that points past the trimmed items would cause callers resuming
- * pagination to skip records. When the requested limit is reached
- * mid-page, no `nextCursor` is returned and the caller should treat
- * the result as the final page they're going to fetch.
- *
- * @example
- * ```ts
- * // Fetch up to 250 issues, in pages of 100 (Sentry's API max)
- * const { data, nextCursor } = await paginateUpTo(
- *   (cursor) => listAnOrganization_sIssues({
- *     path: { organization_id_or_slug: 'my-org' },
- *     query: { cursor, limit: 100 },
- *   }),
- *   { limit: 250 },
- *   'listIssues',
- * );
- * ```
+ * If a server still returns more items than fit, trim the page and omit its
+ * cursor: resuming past discarded items would skip records. Such a result
+ * has `stopReason: "limit"`, even if the server has no further pages.
  */
-export declare const paginateUpTo: <TItem, TError = unknown>(fetcher: PageFetcher<Array<TItem>, TError>, options: PaginateUpToOptions, context: string) => Promise<{
-    data: Array<TItem>;
-    nextCursor?: string;
-}>;
+export declare const paginateUpTo: <TItem, TError = unknown>(fetcher: BudgetedPageFetcher<Array<TItem>, TError>, options: PaginateUpToOptions, context: string) => Promise<PaginatedCollection<TItem>>;