@sentry/api 0.445.0 → 0.446.0

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

@@ -0,0 +1,156 @@
+/**
+ * Authenticated fetch for Sentry API requests, shared by the CLI and MCP.
+ * Standard Web APIs only, so it runs in Node and Cloudflare Workers.
+ *
+ * Per request it sets the Authorization header, refreshes the credential once
+ * after a 401 (any method), times out each attempt, retries through
+ * `retry`, replays request bodies, optionally follows redirects only to
+ * trusted origins, and serves and invalidates cached GETs through an injected
+ * cache. The host supplies credentials, header rules, error classes, logging,
+ * and spans.
+ */
+import { type RetryPolicy } from "./retry.js";
+import type { CacheLookup } from "./response-cache/policy.js";
+type FetchInput = Request | string | URL;
+/** The fields the transport reads; hosts extend it with their own. */
+export type TransportCredential = {
+    token: string;
+    /** Stable hash of the login, for cache scoping; never a raw token. */
+    identity: string;
+};
+export type CredentialProvider<C extends TransportCredential> = {
+    /** The credential for a new request, before any refresh. Cache lookups use it. */
+    current(): C | Promise<C>;
+    /** Called after a cache miss, before the first attempt, to refresh ahead of expiry. */
+    prepare?(credential: C): Promise<C>;
+    /** After a 401: the refreshed credential, or undefined when it cannot refresh. */
+    refresh?(credential: C): Promise<C | undefined>;
+    /** The Authorization value. Throws for a malformed token. */
+    authorization?(credential: C): string;
+};
+/** How the caller reads a successful body; see {@link ApiTransportRequestOptions.responseBody}. */
+export type ResponseBodyMode = "auto" | "buffer" | "stream";
+/** The GET cache, keyed by the host. `CacheLookup` comes from `response-cache`. */
+export type TransportCache = {
+    lookup(request: CachedRequest): Promise<CacheLookup | undefined>;
+    /** Store a successful GET; `response` is a clone the cache may consume. */
+    store(request: CachedRequest, response: Response): Promise<void>;
+    /** Drop entries a successful write to `url` made stale. */
+    invalidate(url: string, identity: string): Promise<void>;
+};
+export type CachedRequest = {
+    url: string;
+    /** For `Vary` matching. */
+    requestHeaders: Record<string, string>;
+    identity: string;
+};
+type TransportLogger = {
+    debug(message: string, ...args: unknown[]): void;
+};
+export type ApiTransportOptions<C extends TransportCredential> = {
+    /**
+     * Without credentials the transport leaves Authorization to the request,
+     * does not refresh, and does not cache, since entries are scoped to the
+     * credential's identity.
+     */
+    credentials?: CredentialProvider<C>;
+    retry: RetryPolicy;
+    /** Per-attempt timeout, or a function of the request URL. Default: none. */
+    timeoutMs?: number | ((url: string) => number);
+    /** Underlying fetch, read on each call. Defaults to `globalThis.fetch`. */
+    fetch?: (input: FetchInput, init?: RequestInit) => Promise<Response>;
+    /** Sent when the request sets no `User-Agent`. */
+    userAgent?: string;
+    /**
+     * Add host headers, such as tracing or proxy headers, before Authorization
+     * is set. Throw to reject the request, for example for an untrusted host.
+     */
+    prepareHeaders?(headers: Headers, request: {
+        input: FetchInput;
+        credential: C;
+    }): void;
+    /** Writes the host knows are safe to replay, such as a catalog of idempotent operations. */
+    isIdempotent?(method: string, url: string): boolean;
+    /** Set to `1` on the request replayed after a credential refresh. */
+    refreshedRequestHeader?: string;
+    /** Which origins may receive the credential when following redirects. */
+    origins?: {
+        trusts(url: URL, credential: C): boolean;
+        /** The error for an untrusted or unusable redirect destination. */
+        reject(destination: string, credential: C): Error;
+    };
+    /** Host error classes. Without them the transport throws its own. */
+    errors?: {
+        /**
+         * The final attempt timed out. `idempotent` is false when a write may
+         * have been applied.
+         */
+        timeout?(info: {
+            timeoutMs: number;
+            idempotent: boolean;
+        }): Error;
+        /** A fetch error to throw at once, without retrying, such as a TLS failure. */
+        fatal?(error: unknown): Error | undefined;
+        /** A 429 that is not retried. Undefined returns the response. */
+        rateLimited?(response: Response, info: {
+            path: string;
+            retryAfterMs: number | undefined;
+        }): Promise<Error | undefined>;
+    };
+    cache?: TransportCache;
+    /**
+     * Whether the current scope skips cache reads, such as a tool call with
+     * `fresh: true`. Hosts back it with request-scoped state like
+     * `AsyncLocalStorage`. The response is still stored, replacing the entry.
+     */
+    fresh?(): boolean;
+    logger?: TransportLogger;
+    /** Wrap each request, including cache lookups, in a host span. */
+    span?(request: {
+        method: string;
+        path: string;
+    }, run: () => Promise<Response>): Promise<Response>;
+};
+export type ApiTransportRequestOptions = {
+    /**
+     * Replaying the request is harmless, so 5xx, timeouts, and network errors
+     * retry for any method. For writes the server dedupes, such as
+     * content-addressed chunk uploads.
+     */
+    idempotent?: boolean;
+    /**
+     * `buffer` reads a successful body within the attempt's timeout and retry
+     * budget; `auto` does so only when it has a `Content-Type`, as the
+     * `@sentry/api` auto parser returns a stream otherwise. Default `stream`.
+     */
+    responseBody?: ResponseBodyMode;
+    /**
+     * Follow redirects manually, checking each destination with `origins`
+     * and recording where the response came from; see
+     * {@link getValidatedResponseSource}. Skips the cache.
+     */
+    validateRedirects?: boolean;
+};
+export type ApiTransport = {
+    request(input: FetchInput, init?: RequestInit, options?: ApiTransportRequestOptions): Promise<Response>;
+};
+/** The request's last attempt hit the transport's own timeout. */
+export declare class ApiTimeoutError extends Error {
+    readonly timeoutMs: number;
+    readonly idempotent: boolean;
+    constructor(timeoutMs: number, idempotent: boolean);
+}
+/** Where a response fetched with `validateRedirects` came from. */
+export type ValidatedResponseSource = {
+    origin: string;
+    identity: string;
+};
+/** The final origin and credential identity of a `validateRedirects` response. */
+export declare function getValidatedResponseSource(response: Response): ValidatedResponseSource | undefined;
+/** Extract the full URL from a fetch input; `String(request)` is not its URL. */
+export declare function extractInputUrl(input: FetchInput): string;
+/** The URL pathname for logs and spans, or the raw input when it does not parse. */
+export declare function extractUrlPath(input: FetchInput): string;
+/** Create a transport; see {@link ApiTransportOptions}. */
+export declare function createApiTransport<C extends TransportCredential>(config: ApiTransportOptions<C>): ApiTransport;
+export {};

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

@@ -0,0 +1,22 @@
+/**
+ * Response validation through the Standard Schema interface, so the shared
+ * client works with any validator that implements it. The MCP passes Zod
+ * schemas and the CLI valibot ones; this module depends on neither.
+ */
+import type { StandardSchemaV1 } from "./standard-schema.js";
+/** A schema the host supplies to check a response body. */
+export type ResponseSchema<Output = unknown> = StandardSchemaV1<unknown, Output>;
+/** A response did not match the schema the caller validated it with. */
+export declare class ApiResponseValidationError extends Error {
+    readonly issues: readonly StandardSchemaV1.Issue[];
+    constructor(issues: readonly StandardSchemaV1.Issue[]);
+}
+/**
+ * Validate `data` with `schema` and return the schema's output.
+ *
+ * Responses are validated synchronously, as every caller does today, so a
+ * schema with async refinements is rejected rather than awaited.
+ *
+ * @throws {ApiResponseValidationError} When `data` does not match
+ */
+export declare function validateResponse<Schema extends StandardSchemaV1>(schema: Schema, data: unknown): StandardSchemaV1.InferOutput<Schema>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/api",
-  "version": "0.445.0",
+  "version": "0.446.0",
   "description": "Official auto-generated TypeScript client for the Sentry public REST API",
   "keywords": [
     "sentry",
@@ -21,7 +21,7 @@
     "build": "node build.mjs",
     "test": "bun test",
     "test:node": "node --test test/node-cancellation.mjs",
-    "typecheck": "tsc -p tsconfig.test.json"
+    "typecheck": "tsc -p tsconfig.test.json && tsc -p tsconfig.browser.json"
   },
   "exports": {
     ".": {
@@ -40,6 +40,14 @@
       "import": "./dist/browser.js",
       "types": "./dist/browser.d.ts"
     },
+    "./client": {
+      "types": "./dist/api-client/index.d.ts",
+      "import": "./dist/api-client/index.js"
+    },
+    "./client/endpoints": {
+      "types": "./dist/api-client/endpoints/index.d.ts",
+      "import": "./dist/api-client/endpoints/index.js"
+    },
     "./operations": {
       "types": "./dist/operations.d.ts",
       "import": "./dist/operations.js"
@@ -60,6 +68,9 @@
   "bugs": {
     "url": "https://github.com/getsentry/sentry-api-schema/issues"
   },
+  "dependencies": {
+    "http-cache-semantics": "^4.2.0"
+  },
   "peerDependencies": {
     "typescript": "*",
     "valibot": "*",
@@ -79,7 +90,9 @@
   "devDependencies": {
     "@hey-api/openapi-ts": "0.98.0",
     "@types/bun": "^1.3.13",
+    "@types/http-cache-semantics": "^4.2.0",
     "@types/node": "^22",
+    "fast-check": "^4.8.0",
     "typescript": "^5.9.3",
     "valibot": "^1.4.2",
     "zod": "^3.24.0"