@sentry/api 0.445.0 → 1.0.0

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

@@ -0,0 +1,119 @@
+/**
+ * Limit-bounded, resume-safe pagination over Sentry list endpoints. Pure
+ * logic with no I/O, so it runs in Node and Cloudflare Workers. Each product
+ * fetches pages, validates rows, logs, and maps failures to its own errors.
+ */
+/**
+ * Sentry API's maximum items per page. Some endpoints silently cap larger
+ * `per_page` values; others (org project list) return 400.
+ */
+export declare const API_MAX_PER_PAGE = 100;
+/** One fetched page: its rows and the server's next-page cursor. */
+export type Page<T> = {
+    data: T;
+    nextCursor?: string;
+};
+/**
+ * Where a {@link paginate} walk resumes: the server cursor that fetches the
+ * page, the page size it must be fetched with, and how many of that page's
+ * rows were already returned.
+ */
+export type CursorPosition = {
+    /** Server cursor to request; undefined starts at the first page. */
+    cursor: string | undefined;
+    /** Required page size in rows, when encoded in the cursor; otherwise unspecified. */
+    perPage?: number;
+    /** Number of rows already returned from this position; zero starts at its first row. */
+    skip: number;
+};
+/** Receives a message when a cursor is unreadable and the walk restarts. */
+type Warn = (message: string) => void;
+/**
+ * Decode a cursor from {@link paginate}, an older CLI, or an API response.
+ *
+ * A damaged `cli1~` cursor is ignored with a warning and the walk starts from
+ * the first page, so it never fails a call or reaches the API.
+ */
+export declare function decodePageCursor(raw: string | undefined, warn?: Warn): CursorPosition;
+/**
+ * Consume one fetched page from a decoded cursor position without making requests.
+ *
+ * Removes rows already delivered by a previous call. Sentry next-page cursors
+ * record any unconsumed rows or remaining skip; other cursor shapes are returned
+ * unchanged and may replay rows on resume.
+ *
+ * @param page - Server page fetched using the position's cursor and page size
+ * @param position - Decoded continuation for this page
+ * @param limit - Maximum rows to return, a non-negative integer; omitted means all remaining rows
+ * @returns Remaining rows and continuation metadata
+ */
+export declare function consumeCursorPage<T>(page: Page<T[]>, position: CursorPosition, limit?: number): Page<T[]>;
+/** Options for {@link paginate}. */
+export type PaginateOptions = {
+    /** Most rows to return. */
+    limit: number;
+    /** Cursor to resume from: one {@link paginate} returned, or a raw server cursor. */
+    cursor?: string;
+    /** Most pages to fetch before stopping with a resume cursor. */
+    maxPages: number;
+    /** Receives a message when `cursor` is unreadable and the walk restarts. */
+    warn?: Warn;
+};
+/** Rows from a {@link paginate} walk and where to resume. */
+export type PaginateResult<T> = {
+    data: T[];
+    /** Resumes at the first row not returned; absent once the server is exhausted. */
+    nextCursor?: string;
+    /** The walk hit `maxPages` before collecting `limit` rows. */
+    stoppedAtPageCap: boolean;
+};
+/**
+ * Fetch up to `limit` rows and a cursor that resumes after the last one.
+ *
+ * - A fresh walk splits `limit` evenly over the fewest requests
+ *   ({@link pageSizeForLimit}). Resuming a page-number cursor
+ *   (`OffsetPaginator`, used by projects, teams, members, repositories, and
+ *   dashboard revisions) reuses the page size the cursor encodes
+ *   (`<per_page>:<page>:<is_prev>`), whatever the new `limit`: pairing it with
+ *   another `per_page` reads the wrong window and silently skips rows.
+ * - The returned cursor always resumes at the first row the caller has not
+ *   received. When a walk stops inside a page (a smaller limit, or a server
+ *   that ignored `per_page`), the cursor refetches that page and skips the
+ *   rows already returned.
+ *
+ * Returned cursors are Sentry cursors, so older CLI versions and the API
+ * accept them too; mid-page cursors record the rows to skip in `is_prev`
+ * ({@link encodeSkip}), which a caller that does not know about them sees
+ * again rather than misses (given the page size a page-number cursor
+ * encodes). Pass cursors back through this function to resume exactly.
+ *
+ * Callers own region resolution and query building inside `fetchPage`, and
+ * must send `perPage` as the request's `per_page` unchanged.
+ *
+ * @param options - Limit, start cursor, page cap, and warning sink
+ * @param fetchPage - Fetches one page given the page size and a server cursor
+ */
+export declare function paginate<T>(options: PaginateOptions, fetchPage: (perPage: number, cursor: string | undefined) => Promise<Page<T[]>>): Promise<PaginateResult<T>>;
+/** Why {@link fetchAllPages} could not return every row. */
+export type FetchAllPagesFailure = "invalid-page" | "repeated-cursor" | "page-cap";
+/** Every row from {@link fetchAllPages}, or why the walk stopped. */
+export type FetchAllPagesResult<T> = {
+    ok: true;
+    items: T[];
+} | {
+    ok: false;
+    reason: FetchAllPagesFailure;
+};
+/**
+ * Fetch and validate every page of a list endpoint, or report why not.
+ *
+ * A partial result is a failure: use this when a missing page could hide the
+ * record a mutation depends on. Fails on an invalid page, a repeated cursor,
+ * or more than `maxPages` pages.
+ *
+ * @param fetchPage - Fetches one page given a cursor
+ * @param parse - Returns a page's validated rows, or `undefined` when invalid
+ * @param maxPages - Most pages to fetch
+ */
+export declare function fetchAllPages<T>(fetchPage: (cursor: string | undefined) => Promise<Page<unknown>>, parse: (data: unknown) => T[] | undefined, maxPages: number): Promise<FetchAllPagesResult<T>>;
+export {};

package/dist/api-client/response-cache/body.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The shape of a stored response body and of the codec that produces it.
+ * Hosts implement the codec, since compression needs host APIs such as
+ * `node:zlib`, so the cache policy and stores stay portable.
+ */
+/** How an entry's body bytes are encoded. */
+export type BodyEncoding = "zstd" | "br" | "identity";
+/** A body as stored: its bytes plus what is needed to decode them. */
+export type EncodedBody = {
+    bytes: Uint8Array;
+    encoding: BodyEncoding;
+    /**
+     * Compression dictionary the bytes need. Never set today; recorded so a
+     * later dictionary rollout can tell its entries apart from plain ones.
+     */
+    dictId?: string;
+    /** Size of the original body, which bounds decompression. */
+    rawSize: number;
+};
+/** Encodes and decodes cached bodies. */
+export type BodyCodec = {
+    /** Compress a body for storage. */
+    encode(raw: Uint8Array): Promise<EncodedBody>;
+    /**
+     * Restore a stored body. Returns `undefined` when this runtime cannot read
+     * the entry (zstd on Node < 22.15, or a dictionary it does not have), so the
+     * caller treats it as a miss. Throws when the bytes are corrupt or do not
+     * decode to `rawSize` bytes.
+     */
+    decode(body: EncodedBody): Promise<Uint8Array | undefined>;
+};

package/dist/api-client/response-cache/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Response cache shared by the CLI and MCP: fallback TTL tiers,
+ * identity-scoped keys, mutation invalidation prefixes, HTTP freshness and
+ * revalidation, the `CacheStore` interface, and a byte-budgeted memory
+ * store. No Node APIs or I/O; hosts with persistent storage implement
+ * `CacheStore` themselves.
+ */
+export type { BodyCodec, BodyEncoding, EncodedBody } from "./body.js";
+export { computeInvalidationPrefixes } from "./invalidation.js";
+export { buildCacheKey, normalizeUrl } from "./keys.js";
+export { createMemoryStore, type MemoryStore, type MemoryStoreOptions, } from "./memory-store.js";
+export { type CacheLookup, type LookupOptions, lookupResponse, REVALIDATION_WINDOW_MS, type StoreOptions, storeResponse, } from "./policy.js";
+export type { CacheEntry, CacheStore } from "./store.js";
+export { classifyUrl, FALLBACK_TTL_MS, type TtlTier } from "./tiers.js";

package/dist/api-client/response-cache/invalidation.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Compute cache-invalidation prefixes for a mutation URL.
+ *
+ * The host's HTTP layer calls {@link computeInvalidationPrefixes} after
+ * every successful non-GET request and deletes the requesting identity's
+ * cached entries whose URL starts with any returned prefix. Two rules
+ * apply:
+ *
+ * 1. **Hierarchy walk.** Sweep the URL's own path and every ancestor
+ *    up to `/api/0/`. A mutation on
+ *    `/organizations/{org}/releases/1.0.0/deploys/` sweeps itself,
+ *    `.../releases/1.0.0/`, and `.../releases/` — which catches the
+ *    detail, deploys-list, and releases-list GET caches in one pass.
+ *
+ * 2. **Cross-endpoint rules.** A small hardcoded table for mutations
+ *    whose effects cross URL trees. For example, creating a project
+ *    under a team hits `/organizations/{org}/teams/{team}/projects/`
+ *    but invalidates the org project list at
+ *    `/organizations/{org}/projects/`. The table is tiny today
+ *    (2 rules) and only grows when a new cross-tree relationship
+ *    appears in the API surface.
+ *
+ * Prefixes are identity-scoped at the sweep layer (the store checks each
+ * entry's identity before deleting it), so a slightly broader sweep is safe — it can only touch the current
+ * identity's entries. Query strings on the mutation URL are dropped
+ * from the prefix (a prefix sweep on the path naturally catches every
+ * query-param variant cached under that path).
+ */
+/**
+ * Compute the full set of cache-invalidation prefixes for a mutation
+ * URL.
+ *
+ * @param fullUrl - Fully-qualified URL of the mutation (absolute,
+ *   including base). Query string is ignored.
+ * @param apiBaseUrl - The host's non-region API base URL (used by rules
+ *   that need to clear caches under a different origin — e.g. the
+ *   legacy `/issues/{id}/` endpoint the CLI's `getIssue()` reads).
+ * @returns Full-URL prefixes to sweep. Returns `[]` if the URL is
+ *   not under `/api/0/` (e.g. sourcemap chunk upload to an arbitrary
+ *   endpoint) or can't be parsed.
+ */
+export declare function computeInvalidationPrefixes(fullUrl: string, apiBaseUrl: string): string[];

package/dist/api-client/response-cache/keys.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Identity-scoped cache keys for Sentry API responses. Uses WebCrypto, so it
+ * runs in Node, Cloudflare Workers, and browsers.
+ */
+/**
+ * Normalize method + URL into a stable string for cache key derivation.
+ * Keeps the host, so the same path on two Sentry servers gets two keys, and
+ * sorts query params by name so `?a=1&b=2` and `?b=2&a=1` match.
+ *
+ * @throws {TypeError} If the URL cannot be parsed
+ */
+export declare function normalizeUrl(method: string, url: string): string;
+/**
+ * Build a cache key from the requesting identity, method, and URL: the
+ * hex HMAC-SHA256 of {@link normalizeUrl} keyed by `identity`.
+ *
+ * `identity` scopes entries so one user never receives another's response.
+ * It must be a stable hash of who is asking, never a raw token, and should
+ * not change when an access token is refreshed for the same login. Keys
+ * match `node:crypto`'s `createHmac("sha256", identity)`, so entries written
+ * before this module moved here are still found.
+ *
+ * @throws {TypeError} If `identity` is empty or the URL cannot be parsed
+ */
+export declare function buildCacheKey(method: string, url: string, identity: string): Promise<string>;

package/dist/api-client/response-cache/memory-store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * In-memory {@link CacheStore} with a byte budget, for the hosted MCP and
+ * tests. Evicts least recently used entries first. Holds no timers: expired
+ * entries are dropped when read, or evicted like any other entry.
+ */
+import type { CacheStore } from "./store.js";
+/**
+ * Bytes charged per entry on top of its body, for the key, URL, headers,
+ * serialized policy, and bookkeeping. An estimate, so that many small
+ * entries (bodies under 256 bytes are stored raw) cannot outgrow the budget.
+ */
+export declare const ENTRY_OVERHEAD_BYTES = 1024;
+export type MemoryStoreOptions = {
+    /** Budget over all entries, in bytes. Defaults to 24 MiB. */
+    maxBytes?: number;
+    /** Largest stored (compressed) body, in bytes. Defaults to 1 MiB. */
+    maxEntryBytes?: number;
+    /**
+     * Largest original body, in bytes, which bounds memory while decoding.
+     * Defaults to 32 MiB.
+     */
+    maxRawBytes?: number;
+};
+export type MemoryStore = CacheStore & {
+    /** Current entry count and bytes charged against the budget. */
+    stats(): {
+        entries: number;
+        bytes: number;
+    };
+};
+/**
+ * Create an empty memory store. Entries are kept by reference; callers must
+ * not mutate an entry after storing it or one returned by `get`.
+ *
+ * @throws {RangeError} If a limit is not a positive number
+ */
+export declare function createMemoryStore(options?: MemoryStoreOptions): MemoryStore;

package/dist/api-client/response-cache/policy.d.ts

@@ -0,0 +1,81 @@
+/**
+ * HTTP caching decisions for Sentry API GET responses, through
+ * `http-cache-semantics` (RFC 9111). Server cache directives win; a response
+ * without them stays fresh for its URL's fallback tier. A stale entry with an
+ * `ETag` is kept for a revalidation window and renewed by a matching 304.
+ *
+ * Works on any `CacheStore` and `BodyCodec` the host passes in, with no Node
+ * APIs. The host derives the key, decides whether caching is enabled, and
+ * records telemetry around these calls.
+ */
+import type { BodyCodec } from "./body.js";
+import type { CacheStore } from "./store.js";
+/**
+ * How long a stale entry with an `ETag` is kept for revalidation. Bounded
+ * by the store's byte budget like any other entry.
+ */
+export declare const REVALIDATION_WINDOW_MS: number;
+/**
+ * Result of a lookup that found a usable entry.
+ *
+ * - `hit`: the entry is fresh; serve `response`. `createdAt` is when the
+ *   response was received, and `size` is the decoded body size in bytes.
+ * - `stale`: the entry is stale but has an `ETag`. Send the request with
+ *   `conditionalHeaders`, then pass the network response to `revalidate`.
+ *   On a matching 304 it renews the entry and returns the cached body;
+ *   otherwise it returns `undefined` and the network response stands (or,
+ *   for an unusable 304, the caller fetches again without the headers).
+ */
+export type CacheLookup = {
+    kind: "hit";
+    response: Response;
+    createdAt: number;
+    size: number;
+} | {
+    kind: "stale";
+    conditionalHeaders: Record<string, string>;
+    revalidate(response: Response): Promise<Response | undefined>;
+};
+export type LookupOptions = {
+    store: CacheStore;
+    codec: BodyCodec;
+    /** From `buildCacheKey`, so the entry is scoped to the identity. */
+    key: string;
+    url: string;
+    /** Headers of the new request, for `Vary` matching. */
+    requestHeaders: Record<string, string>;
+    /** Called when renewing a revalidated entry fails; the response stands. */
+    onRenewError?: (error: unknown) => void;
+};
+export type StoreOptions = {
+    store: CacheStore;
+    codec: BodyCodec;
+    /** From `buildCacheKey` for the same identity, method, and URL. */
+    key: string;
+    /** Recorded on the entry for identity-scoped invalidation. */
+    identity: string;
+    url: string;
+    /** Headers the request was sent with, for `Vary` matching. */
+    requestHeaders: Record<string, string>;
+    /** The response to cache; its body is consumed. */
+    response: Response;
+};
+/**
+ * Look up a GET request: a fresh entry is a `hit`, and a stale one with an
+ * `ETag` is returned for conditional revalidation.
+ *
+ * @returns The lookup, or `undefined` on a miss: no entry, a stale entry
+ *   without an `ETag`, or a body this runtime cannot decode
+ * @throws When the stored policy or body is corrupt; the host may drop the
+ *   entry and treat it as a miss
+ */
+export declare function lookupResponse(options: LookupOptions): Promise<CacheLookup | undefined>;
+/**
+ * Store a successful GET response when HTTP caching allows it: not for
+ * `no-store`, a non-2xx status, or a `no-cache` tier URL. The entry is kept
+ * for its freshness lifetime, plus the revalidation window with an `ETag`.
+ *
+ * @returns The stored (encoded) body size in bytes, or 0 when not stored
+ * @throws When the body is not JSON, the only kind cached
+ */
+export declare function storeResponse(options: StoreOptions): Promise<number>;

package/dist/api-client/response-cache/store.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Storage interface for cached Sentry API responses. Backends (memory, the
+ * CLI's filesystem, R2) store entries whose bodies are already encoded by
+ * the host's `BodyCodec`, and each enforces its own byte budget.
+ */
+import type { EncodedBody } from "./body.js";
+import type { TtlTier } from "./tiers.js";
+/** A cached response as a store holds it. */
+export type CacheEntry = {
+    /** Full request URL, matched by {@link CacheStore.deleteMatching}. */
+    url: string;
+    /** Hash of the login that owns the entry; never a raw token. */
+    identity: string;
+    /** Fallback tier the URL was classified into. */
+    tier: TtlTier;
+    /** HTTP status of the cached response. */
+    status: number;
+    /** Response headers kept for callers, such as `Link` for pagination. */
+    headers: Readonly<Record<string, string>>;
+    /** The response body, encoded by the codec. */
+    body: EncodedBody;
+    /**
+     * The serialized `http-cache-semantics` policy. Stores keep it as is and
+     * never read it; `lookupResponse` uses it to decide freshness and
+     * revalidation.
+     */
+    policy: unknown;
+    /** When the response was received (epoch ms). */
+    createdAt: number;
+};
+/**
+ * Where cached responses live. Keys come from `buildCacheKey`, so they are
+ * already scoped to an identity.
+ */
+export type CacheStore = {
+    /** The entry under `key`, or `undefined` if it is missing or expired. */
+    get(key: string): Promise<CacheEntry | undefined>;
+    /**
+     * Store `entry` under `key` for `ttlMs`, replacing any entry already
+     * there. `ttlMs` is how long the store keeps the entry, not how long it is
+     * fresh: a stale entry with an `ETag` is kept so it can be revalidated. An
+     * entry over the store's limits is not stored, and the one it would have
+     * replaced is removed, so a later read cannot return the older response.
+     */
+    set(key: string, entry: CacheEntry, ttlMs: number): Promise<void>;
+    /**
+     * Remove `identity`'s entries whose URL starts with `urlPrefix`, as
+     * returned by `computeInvalidationPrefixes`. Other identities' entries
+     * are kept.
+     */
+    deleteMatching(identity: string, urlPrefix: string): Promise<void>;
+};

package/dist/api-client/response-cache/tiers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Fallback TTL tiers for Sentry API GET responses that carry no HTTP caching
+ * headers. Responses with `Cache-Control`, `Expires`, or validators follow
+ * those headers instead; the host's cache decides which applies.
+ */
+/**
+ * TTL tier for a URL.
+ *
+ * - `stable`: data that changes infrequently (orgs, projects, teams,
+ *   organization event details, trace-item details)
+ * - `volatile`: data that changes often (issues and their events, project
+ *   event details, full traces, log and span queries)
+ * - `no-cache`: never cache (polling endpoints like autofix state)
+ *
+ * No tier treats a response as immutable. Event payloads embed mutable
+ * fields (`nextEventID`, user reports, release data), `latest`/`oldest`/
+ * `recommended` resolve to different events over time, and traces gain
+ * spans as they arrive (getsentry/sentry#128818).
+ */
+export type TtlTier = "stable" | "volatile" | "no-cache";
+/** Fallback TTL durations by tier (milliseconds). `no-cache` uses 0 as a sentinel. */
+export declare const FALLBACK_TTL_MS: Readonly<Record<TtlTier, number>>;
+/**
+ * Classify a URL into a TTL tier for fallback caching.
+ *
+ * @param url - Full URL string (with query params)
+ */
+export declare function classifyUrl(url: string): TtlTier;

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

@@ -0,0 +1,27 @@
+/**
+ * Reading Sentry API responses. Hosts map what these return to their own
+ * errors: the MCP to `ApiError` subclasses, the CLI to its exit-coded ones.
+ */
+/** What a failed response's body says, read once. */
+export type ErrorResponseBody = {
+    /** The raw body, or undefined when it could not be read. */
+    text: string | undefined;
+    /** The parsed body, when it is JSON. */
+    json?: unknown;
+    /** Why the body is not JSON, when it is not. */
+    parseError?: string;
+    /** The server's `detail` message, when the JSON body has a string one. */
+    detail?: string;
+    /** True when the body is an HTML page, usually from a proxy or a wrong URL. */
+    isHtml: boolean;
+    /** Server-requested wait before retrying, from the rate-limit headers. */
+    retryAfterMs?: number;
+};
+/** Read the body of a failed response, consuming it. */
+export declare function readErrorResponse(response: Response): Promise<ErrorResponseBody>;
+/**
+ * Parse a successful response as JSON, checking its Content-Type first.
+ *
+ * @throws {Error} When the body is HTML, another content type, or malformed
+ */
+export declare function readJsonResponse(response: Response): Promise<unknown>;

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

@@ -0,0 +1,57 @@
+/**
+ * Retry policy for Sentry API requests. Pure logic over standard Web APIs, so
+ * it runs in Node and Cloudflare Workers. Each product owns its request loop,
+ * error classes, and caps; this module decides whether to retry and how long
+ * to wait. A 401 credential refresh is not a retry here: the transport may
+ * replay any method once after refreshing, because the endpoint never ran.
+ */
+/** Caps for one logical request. All delays are in milliseconds. */
+export type RetryPolicy = {
+    /** Retries after the first attempt. */
+    maxRetries: number;
+    /** First fallback backoff step; it doubles on each retry. */
+    baseDelayMs: number;
+    /** Longest single wait. A server delay above this is not waited for. */
+    maxDelayMs: number;
+    /** Longest total wait across every retry of the request. */
+    maxTotalDelayMs: number;
+};
+type HeaderReader = Pick<Headers, "get">;
+/**
+ * Whether a request may be replayed after the endpoint may have run: a
+ * transient 5xx, a network error, or a timeout. True for GET, HEAD, and
+ * OPTIONS, or when the caller marks the request `idempotent`.
+ */
+export declare function isIdempotentRequest(method: string, idempotent?: boolean): boolean;
+/**
+ * Milliseconds the response asks the client to wait, or undefined when it
+ * gives no usable delay. `Retry-After` (seconds or HTTP-date) wins; a proxy
+ * may add it, but Sentry itself does not. Otherwise a 429 waits for
+ * `X-Sentry-Rate-Limit-Reset`, the Unix second the next window starts. A
+ * concurrency-limit 429 is not tied to the window, so it gets no delay here
+ * and the caller falls back to backoff.
+ */
+export declare function parseRetryDelayMs(status: number, headers: HeaderReader, now?: number): number | undefined;
+/**
+ * Delay before the next retry, or undefined to stop and surface the error.
+ * Stops when the method or status is not retryable, the retries are used up,
+ * the server delay exceeds `maxDelayMs`, or the wait would exceed
+ * `maxTotalDelayMs`.
+ */
+export declare function nextRetryDelayMs({ policy, method, idempotent, status, serverDelayMs, attempt, waitedMs, random, }: {
+    policy: RetryPolicy;
+    method: string;
+    idempotent?: boolean;
+    /** Failed response status, or undefined for a network error or timeout. */
+    status: number | undefined;
+    /** From `parseRetryDelayMs` for the failed response. */
+    serverDelayMs: number | undefined;
+    /** Retries already made for this request, starting at 0. */
+    attempt: number;
+    /** Total time already spent waiting for this request. */
+    waitedMs: number;
+    random?: () => number;
+}): number | undefined;
+/** Wait `ms`, or reject with the signal's reason as soon as it aborts. */
+export declare function sleep(ms: number, signal?: AbortSignal | null): Promise<void>;
+export {};

package/dist/api-client/standard-schema.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The Standard Schema V1 interface, copied from `@standard-schema/spec` 1.1.0
+ * (MIT, https://standardschema.dev) as the spec invites, so the client
+ * accepts Zod, valibot, or any other implementing validator without a
+ * dependency. Types only.
+ */
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown, options?: Options | undefined) => Result<Output> | Promise<Result<Output>>;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** A falsy value for `issues` indicates success. */
+        readonly issues?: undefined;
+    }
+    interface Options {
+        /** Explicit support for additional vendor-specific parameters, if needed. */
+        readonly libraryOptions?: Record<string, unknown> | undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}

package/dist/api-client/time-params.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Time range query parameters shared by the endpoints that take one:
+ * `statsPeriod` or a `start`/`end` pair, or the `since`/`until` seconds of
+ * Sentry's `StatsMixin` endpoints.
+ */
+/** A trimmed `statsPeriod`, or undefined when it is blank. */
+export declare function normalizeStatsPeriod(statsPeriod?: string): string | undefined;
+/**
+ * The relative period to query: the trimmed `statsPeriod`, or 24 hours when
+ * neither it nor an absolute `start` or `end` is given.
+ */
+export declare function defaultStatsPeriod({ statsPeriod, start, end, }: {
+    statsPeriod?: string;
+    start?: string;
+    end?: string;
+}): string | undefined;
+/**
+ * Split a relative period such as `24h` into its amount and unit.
+ *
+ * @throws {ApiValidationError} For any other format
+ */
+export declare function parseStatsPeriod(statsPeriod: string): {
+    amount: number;
+    unit: string;
+};
+/**
+ * Validates and applies time parameters to a URLSearchParams object.
+ *
+ * Enforces mutual exclusivity between relative (statsPeriod) and
+ * absolute (start/end) time ranges, and ensures start/end are paired.
+ *
+ * @param queryParams The URLSearchParams to modify
+ * @param statsPeriod Relative time period (e.g., "24h", "7d")
+ * @param start Absolute start time (ISO 8601)
+ * @param end Absolute end time (ISO 8601)
+ * @throws {ApiValidationError} If time parameters are invalid
+ */
+export declare function applyTimeParams(queryParams: URLSearchParams, statsPeriod?: string, start?: string, end?: string): void;
+/**
+ * Like {@link applyTimeParams}, but as the `since` and `until` Unix seconds
+ * that `StatsMixin` endpoints read, with an optional `resolution`. A missing
+ * range means the last 24 hours.
+ *
+ * @throws {ApiValidationError} If time parameters are invalid
+ */
+export declare function applyStatsMixinTimeParams(queryParams: URLSearchParams, statsPeriod?: string, start?: string, end?: string, resolutionSeconds?: number): void;