# @kody/sentry

## Intent

Headless Sentry utilities for Kody workflows — organizations, projects, issue
search, event summaries, and agent-ready triage using a user-scoped
`sentryAuthToken` secret. The low-level REST layer is a thin OpenAPI-scaffolded
client (`listorganizations`, `listorganizationprojects`,
`listorganizationissues`) plus a small escape-hatch `request` helper for
endpoints missing from Sentry's public OpenAPI inventory (for example latest
issue event). Writes through `request` default to dry-run.

This listing is meant to be forked. The live `@kody/sentry` package does not
talk to a shared Sentry org. After you fork, save your own auth token and call
the helpers in your account.

This official API-token package is the **preferred** invoke path. Setup is
harder: save a user-scoped `sentryAuthToken`. For a faster first win, connect
Sentry MCP in Get started and use
[`@kody/sentry-mcp`](https://kody.codes/@kody/sentry-mcp).

## What it does

- List organizations or projects before querying issues
- Search unresolved issues with optional latest-event summaries for triage
- Inspect a specific issue, its events, or build a full triage bundle
- Call uncommon Sentry REST endpoints via `request` (mutating calls default to `dryRun`)

## Prerequisites / setup

Auth is a **bearer auth token** (personal token, organization token, or
internal-integration token). This is not OAuth by default and not a bot token.
Do not paste the token into chat.

1. Create a token in Sentry: [User settings → Personal Tokens](https://sentry.io/settings/account/api/auth-tokens/)
   or an [internal integration](https://docs.sentry.io/api/auth/).
2. Grant at least `org:read`, `project:read`, and `event:read`. Add
   `event:write` only if you will call mutating `request` paths.
3. Save it as `sentryAuthToken`:

https://kody.codes/account/secrets/new?name=sentryAuthToken&description=Sentry%20auth%20token%20for%20organizations%2C%20projects%2C%20issues%2C%20and%20events&allowedHosts=sentry.io,us.sentry.io,de.sentry.io&scope=user

4. Approve hosts `sentry.io`, `us.sentry.io`, and `de.sentry.io` on that
   secret. Saving the secret does not approve hosts by itself.

### Optional BYO OAuth

Only if you already have a Sentry OAuth application. Redirect URI must be
exactly `https://kody.codes/connect/oauth`. Do not register a new platform
OAuth app for Kody.

https://kody.codes/connect/oauth?provider=sentry&authorizeUrl=https://sentry.io/oauth/authorize/&tokenUrl=https://sentry.io/oauth/token/&flow=confidential&pkce=true&scopes=org:read%20project:read%20event:read&allowedHosts=sentry.io,us.sentry.io,de.sentry.io&apiBaseUrl=https://sentry.io/api/0/&dashboardUrl=https://sentry.io/settings/account/api/applications/

After connect, pass `integration: 'sentry'` (or another saved integration
name) on every call.

### Multi-account

There are no hard-coded account aliases:

- Token lane: pass `secretName` (default `sentryAuthToken`). Save a second
  token as `sentryAuthTokenWork` and pass `secretName: 'sentryAuthTokenWork'`.
- OAuth lane: pass `integration` (for example `'sentry'` or `'sentry-work'`).

### Scopes and 403s

| Scope | Used for |
| --- | --- |
| `org:read` | `list-organizations` and org-scoped reads |
| `project:read` | `list-projects`, `resolve-project` |
| `event:read` | issues and events |
| `event:write` | mutating `request` paths (resolve/ignore/assign) |

A `403` from this package names the missing likely scope and the next setup
step (recreate the token with that scope, then update the secret). A `401`
means the token is missing or invalid — reopen the secrets URL above.

### Hosts

Default API host is `sentry.io`. Approve the host(s) you will call on that
secret:

| Host | When to approve |
| --- | --- |
| `sentry.io` | Default SaaS API host (start here) |
| `us.sentry.io` | US data-storage region |
| `de.sentry.io` | EU data-storage region |

Pass `host` on any export to target a region or self-hosted instance
(`host: "us.sentry.io"` or `host: "sentry.example.com"`). Self-hosted hosts
must be added to the secret's allowed hosts after save. Requests are always
HTTPS.

Docs: [Choosing the API base domain](https://docs.sentry.io/api/) ·
[Authentication](https://docs.sentry.io/api/auth/)

Agents: import paths, smoke checks, dry-run write snippets, and edge cases live
in [`AGENTS.md`](./AGENTS.md).

## Done when

- `sentryAuthToken` is saved and needed hosts are approved (or OAuth connected)
- Smoke test returns live org list (or clear setup when the secret is missing)
- Issue search / get-issue / triage-issue succeed against a known issue id
- Mutating `request` paths preview with dry-run until you pass `dryRun: false`

## Forking

Community listings are snapshots. Fork this listing into your account, review
the source, publish your copy, then save `sentryAuthToken`. Do not treat the
live `@kody/sentry` package as bound to your org.

One-click listing URL after publish: `https://kody.codes/@kody/sentry`

## Branding

The community icon is Sentry's official glyph from the public
[Sentry branding page](https://sentry.io/branding/) (glyph, light-on-dark).
The path is unmodified. Sentry® and the Sentry glyph are trademarks of
Functional Software, Inc. This package is not affiliated with or endorsed by
Functional Software, Inc. (Sentry).