feat(api): Move the @sentry/api package into static/packages/api by sentry-junior[bot] · Pull Request #130472 · getsentry/sentry

sentry-junior · 2026-11-09T19:10:05Z

Moves @sentry/api, the generated TypeScript client for Sentry's public API, from getsentry/sentry-api-schema (at 1.54.0, 9774a3d) to static/packages/api. It now builds from tests/apidocs/openapi-derefed.json, the spec this repository generates. The npm name stays @sentry/api, so getsentry/toolkit and other consumers don't change. This PR replaces the pre-merge check from #130450, which was closed.

This PR doesn't change npm publishing. Releases from here stay off until a person cuts the first api@ tag (see the cutover section below).

Package

Uses TypeScript 6 through the same @typescript/typescript6 alias as the rest of the repo. zod is 4.6.7, the version static/app, gsApp, gsAdmin and scraps already pin, so sentry itself needs no zod bump. The other dev tools (hey-api, esbuild, vitest, valibot, fast-check, @types/*) are pinned to exact versions inside the package workspace.
Built from 1.54.0's spec, the moved sources produced a dist/ byte-identical to the published 1.54.0, so the toolchain upgrade doesn't change the output.
The only source changes address the two CodeQL alerts the move raised. source-analysis now uses a path-parameter pattern that can't backtrack on runs of {: 50,000 { characters took 2.1 s before and 1 ms after. In one build script, a template literal that CodeQL misread as a regex became a plain string; the generated output is unchanged.
The test script is test:vitest, not test. The repo's test-ci and test-all pass Jest flags to every workspace's test script, and these tests also need the spec build first.

Spec files on GitHub releases

Each api@x.y.z GitHub release gets the files that version was built from as assets. The pack job adds them to the release artifact; craft's github target attaches every file in it, and its npm target publishes only the tarball:

openapi-derefed.json, the dereferenced OpenAPI spec.
api_ownership_stats_dont_modify.json, for eng-pipes. make build-api-docs generates this file; it isn't committed.
rpc_method_schema.json, for the openapi-diff/RPC check. It comes from a new make build-rpc-schema target.

For example: https://github.com/getsentry/sentry/releases/download/api@x.y.z/openapi-derefed.json.

The npm package doesn't include them. Its unpacked size stays at the 1.54.0 baseline (34.1 MB).

CI: `api client` is a required check

The new api-client job in backend.yml builds, typechecks and tests the client against the PR's own spec. It is part of backend-required-check. A spec change that broke the client caused a 2-day stall in releases, and nothing caught it before merge; this check catches that class of change.

It reuses the spec from the api-docs job (shared as a workflow artifact), so the spec isn't built twice.
Both jobs run only when the new api_client filter matches: the existing api_docs paths plus static/packages/api/**. On other PRs both jobs are skipped, and backend-required-check counts skipped jobs as passing.

Releases

Pack: package-pack.yml sets up the Python env for api, then builds the spec, the RPC schema and the package before pnpm pack.
Release on change: a new release-api-package job in openapi.yml runs after the master spec build, whenever the spec or the package might have changed. It runs .github/workflows/scripts/api-package-release-preflight.sh, then craft prepare with getsentry/publish. The preflight skips the release when:
- there is no api@ tag yet, so the job stays inert until the first release is cut by hand;
- an api/release/* branch is still pending. When that release merges back, its own run releases whatever landed in the meantime;
- HEAD predates the newest api@ tag;
- the spec files and the package are unchanged since the last release. It compares the files against the last release's GitHub release assets. A release without them counts as changed.
Version bump: a spec change is a minor release, as it was in sentry-api-schema. A package change uses craft's automatic bump. A change to only the ownership or RPC files is a patch.
Concurrency: releases use a concurrency group with cancel-in-progress: false, so a burst of merges produces one release.
The release-branch and stale-HEAD guards reuse the logic from getsentry/sentry-api-schemaBuild MySQL Log Parser Client #137. That PR isn't merged yet, so this ports its logic instead of depending on it.
There is no cron. Manual releases go through the Release workflow, which gets a new static/packages/api option.
The mirror push to getsentry/sentry-api-schema is unchanged, except that it now runs on the same api_client filter. It copies the same spec/ files, and the release doesn't wait for it.

Cutover (separate PRs, in this order)

Merge this PR. sentry-api-schema keeps receiving the spec and keeps releasing, so nothing changes for consumers yet.
Let sentry-api-schema cut its last release. Then disable its Release and cascade workflows in a sentry-api-schema PR, so only one repo can publish. If both ever try to publish the same version, npm rejects the second upload, so nothing gets overwritten. The order above avoids that case.
In getsentry/publish auto-approve-repos.txt, replace the getsentry/sentry-api-schema line with this repo's static/packages/api entry (a one-line change).
Cut the first release from here: run the Release workflow with workspace static/packages/api and the next minor version after sentry-api-schema's last. From then on, openapi.yml releases on change.

Retiring sentry-api-schema after the cutover

eng-pipes and the openapi-diff/RPC check read their files from releases/download/api@x.y.z/… for a pinned version, or from the newest api@ release. GitHub's releases/latest points at sentry's calver release, so "newest api@" means listing releases and taking the first api@ tag.
sentry-docs stops pinning a sentry-api-schema SHA. Two options are being looked at: read openapi-derefed.json from the release, or build the API reference from @sentry/api itself.
Remove the mirror steps from openapi.yml and archive getsentry/sentry-api-schema.

static/packages/api/ is owned by @getsentry/owners-api and @getsentry/ocpo in CODEOWNERS.

This PR touches static/ as well as backend CI files. The package is a standalone npm package and isn't part of either deploy, so splitting it wouldn't change what gets deployed.

No UI change.

via @BYK.

--

View Session in Sentry

github-actions · 2026-11-09T19:10:22Z

🚨 Warning: This pull request contains Frontend and Backend changes!

It's discouraged to make changes to Sentry's Frontend and Backend in a single pull request. The Frontend and Backend are not atomically deployed. If the changes are interdependent of each other, they must be separated into two pull requests and be made forward or backwards compatible, such that the Backend or Frontend can be safely deployed independently.

Have questions? Please ask in the #discuss-dev-infra channel.

sentry · 2026-11-09T19:14:22Z

Sentry Snapshot Testing

Name	Added	Removed	Changed	Renamed	Unchanged	Skipped	Status
sentry-frontend `sentry-frontend`	0	0	0	0	824	0	✅ Unchanged

⚙️ sentry-frontend Snapshot Settings

cursor

Stale Bugbot comment from a previous run.

cursor

Stale Bugbot comment from a previous run.

cursor

Stale Bugbot comment from a previous run.

Move the generated TypeScript client for Sentry's public API from getsentry/sentry-api-schema into this repository, next to the spec it is built from. - Build it from tests/apidocs/openapi-derefed.json, upgraded to TypeScript 6 with exact dev tool pins and zod 4.6.7. - Ship the spec, the API ownership stats and the RPC method schema under @sentry/api/spec/ so consumers can read them from npm. - Add a required api-client job to backend.yml that builds, typechecks and tests the client on spec or package changes. - Pack it in package-pack.yml and release it from openapi.yml when what it ships changes. Releases stay off until the first api@ tag is cut by hand. Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>

Stop the path parameter pattern from backtracking on runs of '{', and write the generated-code match in build step generate-request-preparation as a plain string so CodeQL does not read its template escapes as regex escapes. Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>

Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>

Keep the npm package at its 1.54.0 size. The pack job adds the spec, API ownership stats and RPC schema to the release artifact, so craft's github target attaches them to each api@ release while npm takes only the tarball. The release preflight now compares against those release assets. Also make ocpo a code owner of static/packages/api alongside owners-api. Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>

…c files Treating a release without its spec files as "everything changed" would cut a minor release with nothing in it. Craft attaches the files before it merges the release branch, so this only happens when something went wrong, and a failed run is easier to notice than an empty release.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 74efdbf. Configure here.}

@BYK

Ported from getsentry/sentry#130518, per @BYK's request there: get the docs aligned here first, then move `@sentry/api` into getsentry/sentry. The commit applied cleanly on top of 2.0.0. Cursor Bugbot found the bug while reviewing the move ([thread](getsentry/sentry#130472 (comment))). It ships in the published `@sentry/api` 2.0.0. ## Bug `listPage` asked each later page for only the rows still missing: `per_page = min(100, limit - items.length)`. `listProjects`, `listTeams` and `listOrganizations` are served by Sentry's `OffsetPaginator`. Its cursor is `<page size>:<page>:<is_prev>`. When `per_page` doesn't match the cursor's page size, it reads the cursor's window and keeps only the last `per_page` rows (`src/sentry/api/paginator.py` in getsentry/sentry). So `100:1:0` with `per_page=50` returns rows 150–199, and rows 100–149 are lost. Any `limit` above 100 dropped rows without an error. ## Fix `listPage` now walks through the package's existing `paginate`, which: - uses one `per_page` for the whole walk. A fresh walk splits `limit` evenly: 150 becomes 2 × 75. - reuses the page size that an offset cursor encodes when resuming, whatever the new `limit` is. - returns a cursor that resumes at the first row not returned, including partway through a page. `listPage` still validates each page with the schema, and still rejects a page with more rows than requested or a repeated cursor. One behavior changes: if a walk reaches `MAX_LIST_PAGES`, it now returns the rows it has and a resume cursor instead of throwing. Before this change, a stable page size couldn't hit that cap in a normal walk. Now a resumed small-page cursor can, for example `25:1:0` with `limit: 5000`. ## Tests - `test/api-client/core.test.ts` models `OffsetPaginator`. It confirms that `100:1:0` with `per_page=50` reads rows 150–199. Then it checks two things: - a 150-row walk and its resume return rows 0–299 in order, all with `per_page=75`; - resuming `100:1:0` with `limit: 50` returns rows 100–149, then 150–199, both requested with `per_page=100`. - The `listOrganizations` test now expects `per_page` to stay at 3 on the second request. It was 1, which was the bug. `pnpm build`, `pnpm typecheck` and `pnpm test` pass locally (53 files, 675 tests). No UI change. Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>   -- [View Session](https://junior-prod.sentry.dev/conversations/agent%3A69da19b385017e68b7f9eace56e9477f) [[Sentry]](https://sentry.sentry.io/explore/conversations/agent%3A69da19b385017e68b7f9eace56e9477f/?project=4510944073809921)  Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> Co-authored-by: BYK <126780+BYK@users.noreply.github.com>

sentry-junior Bot requested review from a team as code owners November 9, 2026 19:10

sentry-junior Bot assigned BYK Nov 9, 2026

sentry-junior Bot requested review from a team as code owners November 9, 2026 19:10

github-actions Bot added Scope: Frontend Automatically applied to PRs that change frontend components Scope: Backend Automatically applied to PRs that change backend components labels Nov 9, 2026

vercel Bot deployed to Preview November 9, 2026 19:12

View deployment

cursor Bot reviewed Nov 9, 2026

View reviewed changes

Comment thread static/packages/api/lib/api-client/core.ts Resolved

github-advanced-security Bot found potential problems Nov 9, 2026

View reviewed changes

Comment thread static/packages/api/lib/source-analysis.ts Fixed

Comment thread static/packages/api/scripts/generate-request-preparation.mjs Fixed

vercel Bot deployed to Preview November 9, 2026 19:31

View deployment

vercel Bot deployed to Preview November 9, 2026 21:30

View deployment

sentry-junior Bot mentioned this pull request Nov 9, 2026

fix(api): Keep per_page stable when listPage walks offset cursors #130518

Closed

sentry-junior Bot added this pull request to stack #130519 November 9, 2026 21:37

This was referenced Nov 9, 2026

feat(api): Export API reference data as @sentry/api/docs #130538

Closed

ci(openapi-diff): Compare API schemas with the PR's merge-base #130541

Open

sentry-junior Bot force-pushed the feat/api-package branch from 68de88b to 6470e77 Compare November 12, 2026 21:36

vercel Bot deployed to Preview November 12, 2026 21:39

View deployment

cursor Bot reviewed Nov 12, 2026

View reviewed changes

Comment thread static/packages/api/lib/source-analysis.ts Resolved

sentry-junior Bot force-pushed the feat/api-package branch from 6470e77 to 21b537f Compare November 13, 2026 07:24

vercel Bot deployed to Preview November 13, 2026 07:26

View deployment

cursor Bot reviewed Nov 13, 2026

View reviewed changes

Comment thread .github/workflows/scripts/api-package-release-preflight.sh Resolved

sentry-junior Bot and others added 3 commits November 13, 2026 07:32

🛠️ apply pre-commit fixes

185cc83

sentry-junior Bot and others added 3 commits November 13, 2026 07:32

chore(api): Make owners-api the code owner of static/packages/api

005a1fd

Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>

sentry-junior Bot force-pushed the feat/api-package branch from 21b537f to 74efdbf Compare November 13, 2026 07:32

cursor Bot reviewed Nov 13, 2026

View reviewed changes

Comment thread knip.config.ts Resolved

sentry-junior Bot mentioned this pull request Nov 13, 2026

fix(api): Keep per_page stable when listPage walks offset cursors getsentry/sentry-api-schema#149

Merged

Navigation Menu

Repository navigation

feat(api): Move the @sentry/api package into static/packages/api - #130472

feat(api): Move the @sentry/api package into static/packages/api#130472
sentry-junior[bot] wants to merge 6 commits into
masterfrom
feat/api-package

sentry-junior Bot commented Nov 9, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Nov 9, 2026

Uh oh!

sentry Bot commented Nov 9, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

sentry-junior Bot commented Nov 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Package

Spec files on GitHub releases

CI: api client is a required check

Releases

Cutover (separate PRs, in this order)

Retiring sentry-api-schema after the cutover

Uh oh!

github-actions Bot commented Nov 9, 2026

Uh oh!

sentry Bot commented Nov 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Sentry Snapshot Testing

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sentry-junior Bot commented Nov 9, 2026 •

edited

Loading

CI: `api client` is a required check

sentry Bot commented Nov 9, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading