@sentry/api 0.132.0 → 0.133.0

package/dist/sentry-pagination.d.ts

@@ -21,24 +21,84 @@ export type UnwrappedResult<TData> = {
 };
 export type PaginatedResponse<T> = {
     data: T;
+    /** Cursor for the next page. `undefined` when there are no more pages. */
     nextCursor?: string;
+    /** Cursor for the previous page. `undefined` on the first page. */
+    prevCursor?: string;
 };
 export type PaginateAllOptions = {
+    /** Hard cap on the number of pages fetched. Default: 50. */
     maxPages?: number;
 };
+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. */
+    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>>;
 /**
- * Parse Sentry's Link header to extract the next page cursor.
+ * Parse Sentry's Link header to extract pagination cursors.
  *
  * Sentry returns Link headers in the format:
- *   <url>; rel="previous"; results="false"; cursor="...";,
+ *   <url>; rel="previous"; results="true"; cursor="abc:0:1";,
  *   <url>; rel="next"; results="true"; cursor="1234:0:0";
  *
- * Returns `{ nextCursor }` if there is a next page, or `{}` if not.
+ * Returns `{ nextCursor?, prevCursor? }`:
+ *   - `nextCursor` set when there is a next page.
+ *   - `prevCursor` set when there is a previous page.
+ *
+ * The `results="true"` qualifier is required — Sentry includes a
+ * `previous` rel even on the first page, but with `results="false"`.
+ * We honor that signal so first-page callers don't see a bogus `prevCursor`.
  */
 export declare const parseSentryLinkHeader: (header: string | null) => {
     nextCursor?: string;
+    prevCursor?: string;
 };
+/**
+ * Internal: merge a managed `cursor` into an SDK call's `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`
+ * (one call per wrapper kind, one `_withCursor` invocation per page).
+ * Centralizes the cast chain — every wrapper used to inline its own
+ * `as unknown as ...` quartet, which meant the same logic was repeated
+ * once per generated wrapper (~115 places). This helper makes that
+ * exactly one place.
+ *
+ * Type-erasure rationale: each SDK operation has its own `Options<TData>`
+ * shape with operation-specific `query`, `path`, and `body` types. We
+ * can't write a generic that's tight enough to satisfy all 200+ SDK
+ * functions structurally without committing to a discriminated-union
+ * encoding of every operation. The `_` prefix marks this as internal —
+ * the typed wrappers in `pagination.gen.ts` are the supported public API.
+ *
+ * @internal
+ */
+export declare const _withCursor: <TOptions>(options: {
+    query?: unknown;
+    [k: string]: unknown;
+}, cursor: string | undefined) => TOptions;
 /**
  * Unwrap an SDK result, throwing on error.
  *
@@ -47,13 +107,36 @@ export declare const parseSentryLinkHeader: (header: string | null) => {
  */
 export declare const unwrapResult: <TData>(result: SdkResult<TData>, context: string) => UnwrappedResult<TData>;
 /**
- * Unwrap an SDK result and extract the next-page cursor from the
+ * Unwrap an SDK result and extract pagination cursors from the
  * Link header. Throws on error.
  *
- * Returns `{ data, nextCursor? }` — if `nextCursor` is undefined,
- * there are no more pages.
+ * Returns `{ data, nextCursor?, prevCursor? }`. Each cursor is
+ * `undefined` when the corresponding rel does not exist or has
+ * `results="false"`.
  */
 export declare const unwrapPaginatedResult: <TData>(result: SdkResult<TData>, context: string) => PaginatedResponse<TData>;
+/**
+ * Fetch a single page from a Sentry list endpoint and return both
+ * the data and the pagination cursors.
+ *
+ * Thin wrapper over an SDK function call: invokes the fetcher with
+ * an optional cursor, unwraps the result, and parses the Link header.
+ *
+ * Useful when you want manual control over pagination (e.g. exposing
+ * a "next page" button in a UI) instead of fetching all pages eagerly.
+ *
+ * @example
+ * ```ts
+ * const { data, nextCursor } = await fetchPage(
+ *   (cursor) => listAnOrganization_sRepositories({
+ *     path: { organization_id_or_slug: 'my-org' },
+ *     query: { cursor },
+ *   }),
+ *   'listRepos',
+ * );
+ * ```
+ */
+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.
  *
@@ -72,4 +155,31 @@ export declare const unwrapPaginatedResult: <TData>(result: SdkResult<TData>, co
  * ```
  */
 export declare const paginateAll: <TItem, TError = unknown>(fetcher: PageFetcher<Array<TItem>, TError>, context: string, options?: PaginateAllOptions) => Promise<Array<TItem>>;
+/**
+ * Paginate up to a hard limit of items, suppressing the next-cursor
+ * if the last fetched page had to be trimmed to fit.
+ *
+ * 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',
+ * );
+ * ```
+ */
+export declare const paginateUpTo: <TItem, TError = unknown>(fetcher: PageFetcher<Array<TItem>, TError>, options: PaginateUpToOptions, context: string) => Promise<{
+    data: Array<TItem>;
+    nextCursor?: string;
+}>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/api",
-  "version": "0.132.0",
+  "version": "0.133.0",
   "description": "Official auto-generated TypeScript client for the Sentry public REST API",
   "keywords": [
     "sentry",
@@ -17,7 +17,9 @@
     "dist"
   ],
   "scripts": {
-    "build": "node build.mjs"
+    "build": "node build.mjs",
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.test.json"
   },
   "exports": {
     "import": "./dist/index.js",
@@ -36,6 +38,7 @@
   },
   "devDependencies": {
     "@hey-api/openapi-ts": "0.91.1",
+    "@types/bun": "^1.3.13",
     "@types/node": "^22",
     "typescript": "^5.9.3"
   },