@sentry/api 0.445.0 → 1.0.0

package/README.md

@@ -273,7 +273,7 @@ import { vGetProjectResponse } from "@sentry/api/valibot";
 const project = v.parse(vGetProjectResponse, input);
 ```
 
-The existing Zod 3 entry remains supported:
+Zod 4 runtime schemas are available through another optional entry point:
 
 ```bash
 npm install @sentry/api zod
@@ -285,7 +285,7 @@ import { zGetProjectResponse } from "@sentry/api/zod";
 const project = zGetProjectResponse.parse(input);
 ```
 
-`valibot` and `zod` are optional peer dependencies. Install neither when you only need the generated client and TypeScript types, or install the validator used by your application. The `@sentry/api/valibot` entry requires Valibot 1; its optional peer uses a wildcard because npm applies peer constraints to the whole package, including consumers that never import this entry.
+`valibot` and `zod` are optional peer dependencies. Install neither when you only need the generated client and TypeScript types, or install the validator used by your application. The `@sentry/api/valibot` entry requires Valibot 1; its optional peer uses a wildcard because npm applies peer constraints to the whole package, including consumers that never import this entry. The `@sentry/api/zod` entry requires Zod 4.6.6 or later.
 
 ## Error handling
 
@@ -547,6 +547,34 @@ A generic `paginateUpTo` fetcher receives `(cursor, remaining)`. Existing cursor
 
 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.
 
+## Shared client
+
+`@sentry/api/client` is the request layer the Sentry CLI and MCP servers share, built on the generated operations. It uses only web-standard APIs (`fetch`, `Request`, `Headers`, `URL`, `AbortSignal`, `crypto.subtle`), so it runs in Node, Cloudflare Workers, and browsers. Hosts inject what differs between them:
+
+- **Transport.** `createApiTransport` sets `Authorization` from a `CredentialProvider`, refreshes the credential once after a 401, times out each attempt, retries through the shared retry policy (429 for any method; 500, 502, 503, 504, timeouts, and network errors only for GET, HEAD, OPTIONS, or writes marked idempotent), follows redirects only to trusted origins, and serves and invalidates cached GETs. The host passes credentials, a `TransportCache`, the request-scoped `fresh` hook, a logger, a span hook, and its error classes.
+- **Request core.** `createApiClientCore` sends `<origin>/api/0<path>` through the transport and throws the status's `ApiError` subclass for an error response. `sdkClient` gives a generated operation a client that sends through the same path.
+- **Response cache.** The cache policy (`lookupResponse`, `storeResponse`, tiers, identity-scoped keys, invalidation) works on any `CacheStore` and `BodyCodec`. `createMemoryStore` is a byte-budgeted in-memory store. Compressing codecs need host APIs such as `node:zlib`, so hosts supply them.
+- **Validation.** Endpoint wrappers validate responses with any [Standard Schema](https://standardschema.dev) validator the host passes in, such as the `@sentry/api/zod` or `@sentry/api/valibot` schemas. The client depends on neither.
+- **Pagination.** `paginate` and `fetchAllPages` walk list endpoints on top of `paginateUpTo` and `consumePage`. Their cursors are Sentry cursors that also record rows already returned from a page, so a resumed walk neither repeats nor skips rows.
+
+`@sentry/api/client/endpoints` holds endpoint wrappers by domain. Each takes an `ApiTarget` (a core and an origin) and a response schema.
+
+Every API error the core throws (`ApiError`, `ApiNotFoundError`, `ApiRateLimitError`, and the rest) extends `SentryApiError`, so `instanceof SentryApiError` matches failures from both the generated operations and the core.
+
+In a browser, put the session fetch under the transport to keep cookie auth and CSRF injection:
+
+```ts
+import { createBrowserFetch } from "@sentry/api/browser";
+import { createApiClientCore, createApiTransport } from "@sentry/api/client";
+
+const transport = createApiTransport({
+  fetch: createBrowserFetch(),
+  retry: { maxRetries: 2, baseDelayMs: 500, maxDelayMs: 5000, maxTotalDelayMs: 10000 },
+});
+const core = createApiClientCore({ transport, headers: () => ({}), logger: console });
+const projects = await core.requestJson("https://sentry.example.com", "/organizations/acme/projects/");
+```
+
 ## 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/api-client/api-path.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Encode one Sentry API path identifier without letting it become a URL path.
+ *
+ * URL parsing collapses bare `.` and `..` segments even after
+ * `encodeURIComponent`, so callers must reject those identifiers before
+ * constructing a request. The caller owns its product-specific error type.
+ * A pre-encoded spelling such as `%2e%2e` is safe: encoding its percent signs
+ * prevents the URL parser from treating it as a dot segment.
+ */
+export declare function encodeApiPathSegment(value: string | number): string | null;
+/**
+ * Assemble an API URL from a product-validated base and a relative endpoint.
+ * This does not decide which host is trusted or which region an org uses.
+ */
+export declare function buildSentryApiUrl(baseUrl: string, endpoint: string): string;
+/**
+ * Builds an API request path, confining each interpolated value to one path segment.
+ *
+ * `fetch` resolves dot segments during URL parsing, so a raw value in a path can
+ * rewrite it above the org and project the server injected. Encoding stops separators
+ * but not `.` or `..`, which survive encoding and still collapse (the URL spec treats
+ * `%2e%2e` as a dot segment too), so those are rejected instead.
+ *
+ * Query strings go outside the template, since `URLSearchParams` has already encoded
+ * them and their separators must stay literal:
+ *
+ * ```typescript
+ * const path = apiPath`/organizations/${organizationSlug}/issues/`;
+ * await this.requestJSON(`${path}?${query}`);
+ * ```
+ */
+export declare function apiPath(strings: TemplateStringsArray, ...values: (string | number)[]): string;
+/** `path` with `query` appended, or `path` alone when `query` is empty. */
+export declare function withQuery(path: string, query: URLSearchParams): string;

package/dist/api-client/auth-token.d.ts

@@ -0,0 +1,6 @@
+/** Strip padding at the edges without changing bytes within the token. */
+export declare function trimAuthToken(token: string): string;
+/** Return null for invalid input so each caller can preserve its own error type. */
+export declare function normalizeAuthToken(token: string): string | null;
+/** Format a validated upstream credential; callers own their auth errors. */
+export declare function sentryBearerHeader(token: string): string | null;

package/dist/api-client/core.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The request core that endpoint wrappers build on. It sends a request
+ * through the host's transport, turns network failures and error responses
+ * into the shared errors, and reads JSON bodies. `@sentry/api` operations
+ * get a client that sends through the same path, and {@link listPage} walks
+ * their pages.
+ *
+ * The host supplies the transport (retries, caching), the per-request
+ * headers (credentials, user agent, attribution), and logging.
+ */
+import { type SentryClient } from "@sentry/api";
+import { type ResponseSchema } from "./validate.js";
+/** What the core needs from the host's transport. */
+export type ApiRequestTransport = {
+    request(url: string, init: RequestInit): Promise<Response>;
+};
+export type ApiClientLogger = {
+    warn(message: string, extra: Record<string, unknown>): void;
+};
+export type ApiClientCoreOptions = {
+    transport: ApiRequestTransport;
+    /**
+     * Headers for every request after `Content-Type`, such as Authorization
+     * and User-Agent. Called once per request; may throw for a bad credential.
+     * They replace any headers the caller passes.
+     */
+    headers: () => Record<string, string>;
+    logger: ApiClientLogger;
+};
+export type ApiRequestOptions = {
+    /** Error statuses returned as the response instead of thrown. */
+    allowStatuses?: number[];
+};
+export type ApiClientCore = {
+    /**
+     * Send a request to `origin` + `/api/0` + `path`.
+     *
+     * @throws {ApiError} For an error status not in `allowStatuses`
+     * @throws {ConfigurationError} When the host is unreachable or misconfigured
+     * @throws {Error} For other network failures, with a readable message
+     */
+    request(origin: string, path: string, init?: RequestInit, options?: ApiRequestOptions): Promise<Response>;
+    /** {@link ApiClientCore.request}, then the parsed JSON body. */
+    requestJson(origin: string, path: string, init?: RequestInit): Promise<unknown>;
+    /**
+     * A `@sentry/api` client for one GET to `expectedPath` on `origin`. The
+     * operation builds the path and query; the request goes through
+     * {@link ApiClientCore.request}. Any other target or method throws.
+     */
+    sdkClient(origin: string, expectedPath: string): SentryClient["client"];
+};
+/** Where an endpoint wrapper sends: the core, and the region or host origin. */
+export type ApiTarget = {
+    core: ApiClientCore;
+    origin: string;
+};
+/** Most pages {@link listPage} fetches for one call. */
+export declare const MAX_LIST_PAGES = 50;
+/** Rows from {@link listPage}, and the cursor for the next call. */
+export type ListPage<T> = {
+    items: T[];
+    nextCursor: string | null;
+};
+/** The cursor of the next page in a list response's `Link` header, if any. */
+export declare function nextPageCursor(response: Response): string | null;
+export declare function createApiClientCore({ transport, headers, logger, }: ApiClientCoreOptions): ApiClientCore;
+/**
+ * Fetch up to `limit` rows from a list endpoint, starting at `cursor`.
+ *
+ * Each page asks for exactly the rows still missing, up to
+ * {@link API_MAX_PER_PAGE}, and is validated with `schema`. The walk stops
+ * once it has `limit` rows or the server has no next page, and returns the
+ * server's cursor for the page after the last one fetched.
+ *
+ * @throws {ApiValidationError} When `limit` is not between 1 and
+ *   `API_MAX_PER_PAGE * MAX_LIST_PAGES`
+ * @throws {ApiResponseValidationError} When a page does not match `schema`
+ * @throws {Error} When a page has more rows than requested, a cursor
+ *   repeats, or the walk passes {@link MAX_LIST_PAGES}
+ */
+export declare function listPage<T>(fetchPage: (perPage: number, cursor: string | undefined) => Promise<{
+    data: unknown;
+    response: Response;
+}>, schema: ResponseSchema<T[]>, limit: number, initialCursor?: string | null): Promise<ListPage<T>>;

package/dist/api-client/endpoints/client-keys.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Client key (DSN) endpoints for a project. Each wrapper validates the
+ * response with the schema the host passes, so the host's schema decides the
+ * result type.
+ */
+import { type ApiTarget, type ResponseSchema } from "@sentry/api/client";
+export type ClientKeyProjectParams = {
+    organizationSlug: string;
+    projectSlug: string;
+};
+/** Every client key of a project. */
+export declare function listClientKeys<T>({ core, origin }: ApiTarget, { organizationSlug, projectSlug }: ClientKeyProjectParams, schema: ResponseSchema<T>): Promise<T>;
+/** Create a client key, optionally named. */
+export declare function createClientKey<T>({ core, origin }: ApiTarget, { organizationSlug, projectSlug, name, }: ClientKeyProjectParams & {
+    name?: string;
+}, schema: ResponseSchema<T>): Promise<T>;
+export type ClientKeyUpdate = {
+    name?: string;
+    isActive?: boolean;
+    /** Caps accepted errors per window; `null` removes the limit. */
+    rateLimit?: {
+        window: number;
+        count: number;
+    } | null;
+    browserSdkVersion?: string;
+    dynamicSdkLoaderOptions?: {
+        hasReplay?: boolean;
+        hasPerformance?: boolean;
+        hasDebug?: boolean;
+        hasFeedback?: boolean;
+        hasLogsAndMetrics?: boolean;
+    };
+};
+export type UpdateClientKeyParams = ClientKeyProjectParams & {
+    keyId: string | number;
+} & ClientKeyUpdate;
+/** Update a client key. Only the fields that are set are sent. */
+export declare function updateClientKey<T>({ core, origin }: ApiTarget, { organizationSlug, projectSlug, keyId, name, isActive, rateLimit, browserSdkVersion, dynamicSdkLoaderOptions, }: UpdateClientKeyParams, schema: ResponseSchema<T>): Promise<T>;

package/dist/api-client/endpoints/dashboards.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Dashboard endpoints. Each wrapper validates the response with the schema
+ * the host passes, so the host's schema decides the result type.
+ */
+import { type ApiTarget, type ListPage, type ResponseSchema } from "@sentry/api/client";
+export type ListDashboardsParams = {
+    organizationSlug: string;
+    /** Filters by title. */
+    query?: string | null;
+    sortBy?: "title" | "-title" | "dateCreated" | "-dateCreated";
+    /** Page size. Default: 10. */
+    limit?: number;
+    /** Resumes from a previous call's `nextCursor`. */
+    cursor?: string | null;
+};
+/** One page of the organization's dashboards. */
+export declare function listDashboards<T>({ core, origin }: ApiTarget, { organizationSlug, query, sortBy, limit, cursor }: ListDashboardsParams, schema: ResponseSchema<T[]>): Promise<ListPage<T>>;
+export type GetDashboardParams = {
+    organizationSlug: string;
+    dashboardId: string;
+};
+/** One dashboard with its widgets. */
+export declare function getDashboard<T>({ core, origin }: ApiTarget, { organizationSlug, dashboardId }: GetDashboardParams, schema: ResponseSchema<T>): Promise<T>;

package/dist/api-client/endpoints/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@sentry/api/client/endpoints`: endpoint wrappers by domain, on the
+ * generated operations where they exist and the request core otherwise. Each
+ * takes an `ApiTarget` and a host-supplied response schema.
+ */
+export * from "./client-keys.js";
+export * from "./dashboards.js";
+export * from "./monitors.js";
+export * from "./organizations.js";
+export * from "./profiling.js";
+export * from "./projects.js";
+export * from "./releases.js";
+export * from "./replays.js";
+export * from "./repositories.js";
+export * from "./snapshots.js";
+export * from "./teams.js";
+export * from "./traces.js";
+export * from "./uptime-monitors.js";