@keystrokehq/sentry 0.0.1

package/README.md

@@ -0,0 +1,218 @@
+# @keystrokehq/sentry
+
+Official Keystroke integration for [Sentry](https://sentry.io).
+
+- **176 operations** across 21 resource domains (issues, releases, projects,
+  monitors, replays, dashboards, alerts, Discover, SCIM, …).
+- **27 direct-binding triggers**: 16 integration-platform webhooks (issue /
+  error / comment / alert lifecycle), 7 Seer Autofix events, 2 preprod-artifact
+  events, 1 legacy project service-hook, and 1 parameterised Discover polling
+  trigger.
+- **OAuth 2.0 (refreshable)** public connection with provider-specific
+  `exchangeCode` and `extractInstallationInfo` hooks. Bearer-token tenants
+  (user / organisation / internal-integration tokens) run through the same
+  runtime path — the token is resolved into the same `Authorization: Bearer`
+  header.
+- Built-in HMAC-SHA256 verification, region-URL override for
+  `us.sentry.io` / `de.sentry.io` / self-hosted deployments, RFC 5988
+  `Link`-header pagination, and DSN-vs-token guard-rails.
+
+## Install
+
+```bash
+pnpm add @keystrokehq/sentry
+```
+
+The package is ESM-only, side-effect free, and ships typed subpath exports.
+End-user authoring code imports from subpaths (`./connection`, `./issues`,
+`./triggers`, …) — never from the package root.
+
+## Credentials
+
+Most customers connect via OAuth. The platform persists the access token
+under `SENTRY_ACCESS_TOKEN`, the refresh token under `SENTRY_REFRESH_TOKEN`,
+and (when resolved at install time) the installed organisation slug plus
+region URL. Workflow authors receive the resolved `SentryIntegrationCredentials`
+shape:
+
+```ts
+import type { SentryIntegrationCredentials } from '@keystrokehq/sentry/connection';
+```
+
+| Field               | Required | Notes                                                  |
+| ------------------- | -------- | ------------------------------------------------------ |
+| `SENTRY_ACCESS_TOKEN` | ✅       | OAuth access token or long-lived auth token.           |
+| `SENTRY_REGION_URL`   | optional | Defaults to `https://sentry.io`. Set for `us.` / `de.` multi-region, or a self-hosted host. |
+| `SENTRY_ORG_SLUG`     | optional | Default organisation slug used when an operation omits `organization_slug`. |
+
+Platform operators supply the Sentry app credentials (`client_id`,
+`client_secret`, `webhook_secret`) through the environment keys
+`KEYSTROKE_PLATFORM_SENTRY_CLIENT_ID`, `_CLIENT_SECRET`, and `_WEBHOOK_SECRET`.
+These are internal — they never reach authored workflow code.
+
+### OAuth scope matrix
+
+| Capability                                   | Scopes you need                                  |
+| -------------------------------------------- | ------------------------------------------------ |
+| Read orgs, projects, teams, members, issues  | `org:read project:read event:read member:read team:read` |
+| Update issue status / assignee / archive     | `event:admin project:write`                      |
+| Manage alert rules (metric + issue)          | `alerts:read alerts:write`                       |
+| Create and update releases / deploys / files | `release:admin`                                  |
+| Manage project keys (DSN rotation)           | `project:admin`                                  |
+| SCIM user / group provisioning               | `member:write team:admin`                        |
+
+The default OAuth flow requests the superset above. Trim the scope list in
+your platform config if you only need a narrower subset.
+
+## Quickstart — Sentry → Linear + Slack fan-out
+
+```ts
+import { getOrganizationIssueDetails, updateIssueAttributesInOrganization } from '@keystrokehq/sentry/issues';
+import { on } from '@keystrokehq/sentry/triggers';
+import { createIssue } from '@keystrokehq/linear/issues';
+import { sendMessage } from '@keystrokehq/slack/platform/messages';
+import { Workflow } from '@keystrokehq/core';
+
+export const sentryFanOut = new Workflow({
+  id: 'sentry-fan-out',
+  name: 'Sentry → Linear + Slack',
+  triggers: [
+    on.issueCreated({
+      filter: (event) => event.data.issue.level !== 'info',
+      transform: (event) => ({
+        sentryIssueId: event.data.issue.id,
+        title: event.data.issue.title ?? 'Unknown Sentry issue',
+        url: event.data.issue.web_url ?? null,
+      }),
+    }),
+  ],
+  run: async ({ input, run }) => {
+    const issue = await run(getOrganizationIssueDetails, {
+      input: { issue_id: input.sentryIssueId },
+    });
+
+    const linearIssue = await run(createIssue, {
+      input: {
+        teamId: 'TEAM_UUID',
+        title: issue.title ?? input.title,
+        description: `Sentry: ${input.url ?? 'no url'}`,
+      },
+    });
+
+    await run(sendMessage, {
+      input: {
+        channel: '#oncall',
+        text: `:rotating_light: ${input.title}\nLinear: ${linearIssue.issue?.url ?? 'pending'}\nSentry: ${input.url ?? ''}`,
+      },
+    });
+
+    await run(updateIssueAttributesInOrganization, {
+      input: {
+        id: [input.sentryIssueId],
+        assignedTo: 'team:oncall',
+        statusDetails: { linear_url: linearIssue.issue?.url },
+      },
+    });
+  },
+});
+```
+
+## Public surface
+
+### End-user authoring (operations)
+
+| Subpath                                         | Domain                                                     |
+| ----------------------------------------------- | ---------------------------------------------------------- |
+| `@keystrokehq/sentry/organizations`   | 15 operations — orgs, stats, integrations                  |
+| `@keystrokehq/sentry/members`         | 7 operations — member CRUD + invites                       |
+| `@keystrokehq/sentry/teams`           | 14 operations — team CRUD + external-team links            |
+| `@keystrokehq/sentry/projects`        | 19 operations — project CRUD, filters, ownership, symbols  |
+| `@keystrokehq/sentry/project-keys`    | 5 operations — DSN / client key management                 |
+| `@keystrokehq/sentry/issues`          | 13 operations — issue lifecycle + external-issue links     |
+| `@keystrokehq/sentry/events-api`      | 7 operations — issue events, project events, Discover      |
+| `@keystrokehq/sentry/releases`        | 21 operations — releases, files, repos, commits            |
+| `@keystrokehq/sentry/deploys`         | 2 operations — record + list deploys per release           |
+| `@keystrokehq/sentry/environments`    | 3 operations — project environment management              |
+| `@keystrokehq/sentry/alerts`          | 11 operations — metric + issue alert rules                 |
+| `@keystrokehq/sentry/notifications`   | 5 operations — notification actions                        |
+| `@keystrokehq/sentry/monitors`        | 10 operations — cron monitors + check-ins                  |
+| `@keystrokehq/sentry/dashboards`      | 5 operations — organisation dashboards                     |
+| `@keystrokehq/sentry/discover`        | 5 operations — saved Discover queries                      |
+| `@keystrokehq/sentry/webhooks`        | 5 operations — legacy project service hook CRUD            |
+| `@keystrokehq/sentry/replays`         | 9 operations — Session Replay                              |
+| `@keystrokehq/sentry/feedback`        | 2 operations — user feedback                               |
+| `@keystrokehq/sentry/debug-files`     | 3 operations — DIF / dSYM upload                           |
+| `@keystrokehq/sentry/scim`            | 11 operations — SCIM + SAML + external users               |
+| `@keystrokehq/sentry/user-emails`     | 4 operations — account email management                    |
+
+### End-user authoring (triggers)
+
+```ts
+import { on, webhooks, polling } from '@keystrokehq/sentry/triggers';
+```
+
+- `on.<event>({ filter, transform, name, description })` — integration-platform
+  webhooks. Available events:
+  - `installationCreated`, `installationDeleted`
+  - `issueCreated`, `issueResolved`, `issueAssigned`, `issueUnresolved`,
+    `issueIgnored`, `issueArchived`
+  - `errorCreated`
+  - `commentCreated`, `commentUpdated`, `commentDeleted`
+  - `eventAlertTriggered`
+  - `metricAlertCritical`, `metricAlertWarning`, `metricAlertResolved`
+  - Seer: `seerRootCauseStarted`, `seerRootCauseCompleted`,
+    `seerSolutionStarted`, `seerSolutionCompleted`, `seerCodingStarted`,
+    `seerCodingCompleted`, `seerPrCreated`
+  - Preprod artifacts: `preprodSizeAnalysisCompleted`,
+    `preprodBuildDistributionCompleted`
+- `webhooks.serviceHookEventAlert({ filter, transform })` — legacy per-project
+  service-hook binding. Signs with the per-hook secret, not the integration
+  client secret.
+- `polling.discoverEvents(params, options?)` — parameterised polling over
+  `/api/0/organizations/{slug}/events/`. Supply `field`, `query`, `project`,
+  `environment`, `statsPeriod`, `dataset`, and optionally `schedule`.
+
+### Support surfaces
+
+```ts
+import { sentry, type SentryIntegrationCredentials } from '@keystrokehq/sentry/connection';
+import { createSentryClient, type SentryCredentials } from '@keystrokehq/sentry/client';
+import { sentryIssueSchema, sentryProjectSummarySchema } from '@keystrokehq/sentry/schemas';
+import { sentryIssueCreatedEventSchema } from '@keystrokehq/sentry/events';
+import { verifySentryWebhookRequest, verifySentryServiceHookRequest } from '@keystrokehq/sentry/verification';
+```
+
+### Internal (do not import from application code)
+
+- `@keystrokehq/sentry/_official` — bundle export used
+  by `@keystrokehq/official-integration-catalog`.
+- `@keystrokehq/sentry/_runtime` — reserved for hosted runtime
+  plumbing.
+
+## Caveats
+
+- **DSN ≠ auth token.** The client rejects any value that parses as a Sentry
+  DSN (a URL with a `user@host` component). DSNs are ingest-only.
+- **Region routing.** If a customer installs from `us.sentry.io` or
+  `de.sentry.io`, the OAuth hook captures the region URL at install time.
+  Self-hosted deployments must explicitly set `SENTRY_REGION_URL` on the
+  credentials or the client will default to `https://sentry.io`.
+- **Webhook timing.** Integration-platform webhooks must respond within one
+  second per Sentry's docs. Keep the transform path cheap and push work onto
+  `run` callbacks.
+- **Issue state migration.** Sentry is migrating from `ignored` → `archived`;
+  both triggers are exposed. Collapse them in `transform` if you want a
+  single "muted" state downstream.
+- **Service hooks are deprecated.** Prefer the integration-webhook path for
+  new installs. The service-hook operations + trigger remain for backward
+  compatibility.
+
+## Not yet supported
+
+- `seer.coding_completed` and preprod webhooks currently pass through raw
+  payloads. When the payload schemas stabilise upstream, we will upgrade
+  them to a strict shape.
+
+---
+
+License: MIT.

package/dist/_official/index.d.mts

@@ -0,0 +1,3 @@
+import { i as sentryOfficialIntegration, r as sentryBundle } from "../integration-C8KHkeNG.mjs";
+import { n as sentryAppCredentialSet, r as sentryPlatformProviderSeed, t as SentryAppCredentials } from "../provider-app-BANn4KOL.mjs";
+export { SentryAppCredentials, sentryAppCredentialSet, sentryBundle, sentryOfficialIntegration, sentryPlatformProviderSeed };

package/dist/_official/index.mjs

@@ -0,0 +1,3 @@
+import { a as sentryPlatformProviderSeed, i as sentryAppCredentialSet, n as sentryBundle, r as sentryOfficialIntegration } from "../integration-WwY95cWE.mjs";
+
+export { sentryAppCredentialSet, sentryBundle, sentryOfficialIntegration, sentryPlatformProviderSeed };

package/dist/_runtime/index.d.mts

@@ -0,0 +1,2 @@
+import { i as sentryOfficialIntegration, r as sentryBundle } from "../integration-C8KHkeNG.mjs";
+export { sentryBundle, sentryOfficialIntegration };

package/dist/_runtime/index.mjs

@@ -0,0 +1,3 @@
+import { n as sentryBundle, r as sentryOfficialIntegration } from "../integration-WwY95cWE.mjs";
+
+export { sentryBundle, sentryOfficialIntegration };