fix(alerts): read metric alert rules from org-scoped /detectors/ (#1275)

Migrates the metric-alert **read** path (`list` / `view` / rule
resolution) off the legacy `/organizations/{org}/alert-rules/` endpoint
— which is being retired on **2026-08-17** and 410s during brownouts —
to the new org-scoped `/organizations/{org}/detectors/` endpoint
filtered to `type:metric_issue`. A `mapDetectorToMetricAlertRule` helper
flattens the nested detector payload into the existing `MetricAlertRule`
shape, so command formatters and resolvers work unchanged.

This mirrors the proven issue-alert read migration (#1215/#1216).
Metric-alert **mutations** (`create`/`edit`/`delete`) still use the
legacy endpoint pending the follow-up mutation migration tracked in
#1277 — same transitional state as issue alerts today.

## Testing
- `pnpm run typecheck` — clean
- `pnpm run lint` — clean
- `npx vitest run test/lib/api/alerts.test.ts test/commands/alert` — 150
passing (updated metric-list mocks to `/detectors/`; added list/get +
nested-`snubaQuery` mapping tests)

Refs #1274, #1182

<!--
## Plan
Scope: incremental slice of #1274, matching the established #1215/#1216
pattern
(migrate read path first, defer mutations).

Root cause: metric-alert list/view/get still hit the deprecated
/organizations/{org}/alert-rules/ endpoint, retired 2026-08-17.

Changes (src/lib/api/alerts.ts):
- Add MetricDetector type (only CLI-read fields typed;
dataSources/config opaque).
- Add mapDetectorToMetricAlertRule: id=String(detector.id),
status=enabled===false?1:0,
threshold fields from dataSources[0] with queryObj/snubaQuery fallback,
owner
  flattened, projects/dateCreated defaulted.
- listMetricAlertsPaginated -> GET
/organizations/{org}/detectors/?query=type:metric_issue&sortBy=-id then
map.
- getMetricAlertRule -> GET /organizations/{org}/detectors/{id}/ then
map.
- Leave
fetchMetricAlertRuleJson/getMetricAlertRuleDocument/put*/delete*/create*
on legacy /alert-rules/.

Tests updated: alerts.test.ts (fixture + list/get/snubaQuery mapping),
metrics/list.test.ts
(detector() builder; repoint mocks/regexes/endpoint assertions to
/detectors/).

Known transitional caveat (matches issue-alert precedent): edit resolves
via the migrated
detector read but still PUTs against legacy /alert-rules/{id}/; resolved
by the deferred
mutation migration.
-->

---------

Co-authored-by: jared-outpost[bot] <jared-outpost[bot]@users.noreply.github.com>

Author: jared-outpost[bot]

src/lib/api/alerts.ts

@@ -6,13 +6,20 @@
  * - Metric alerts: threshold-based rules that trigger on metric queries (org-wide)
  */
 
+import {
+  getOrganizationDetector,
+  listOrganizationDetectors,
+} from "@sentry/api";
 import { ApiError } from "../errors.js";
 import { resolveOrgRegion } from "../region.js";
 import {
   apiRequestToRegion,
   apiRequestToRegionNoContent,
+  getOrgSdkConfig,
   type PaginatedResponse,
   parseLinkHeader,
+  unwrapPaginatedResult,
+  unwrapResult,
 } from "./infrastructure.js";
 
 // Types
@@ -55,6 +62,152 @@ export type MetricAlertRule = {
   dateCreated: string;
 };
 
+/**
+ * A metric-issue detector as returned by the org-scoped `/detectors/` endpoint.
+ *
+ * The new detectors API replaces the legacy `/alert-rules/` endpoint. The
+ * threshold query fields (aggregate, dataset, query, timeWindow) live inside
+ * the first entry of `dataSources`, and the active/disabled state is the
+ * top-level `enabled` boolean. Only the fields the CLI reads are typed; the
+ * nested `dataSources`/`config` objects are otherwise opaque.
+ */
+type MetricDetector = {
+  id: string | number;
+  name: string;
+  /** Detector kind, e.g. `metric_issue`. Other kinds (uptime, cron) are rejected on read. */
+  type?: string;
+  enabled?: boolean;
+  environment?: string | null;
+  projectSlug?: string | null;
+  projects?: string[] | null;
+  owner?: { type: string; name?: string; id?: string } | string | null;
+  dateCreated?: string;
+  dataSources?: Record<string, unknown>[] | null;
+};
+
+/**
+ * Map a metric-issue detector onto the flat `MetricAlertRule` shape the CLI
+ * commands (list/view/resolve) already consume.
+ *
+ * The threshold query fields live in the first data source, possibly nested
+ * under `queryObj`, `snubaQuery`, or `queryObj.snubaQuery` — `resolveThresholdSource`
+ * picks the right container. `enabled === false` maps to the legacy disabled
+ * status (1); an enabled or absent flag maps to active (0), matching
+ * `metricAlertStatusLabel`.
+ */
+function pickDetectorString(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function pickDetectorNumber(value: unknown): number {
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : 0;
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+  }
+  return 0;
+}
+
+/**
+ * Resolve the project slug list for a detector.
+ *
+ * Detectors are project-scoped and expose a single `projectSlug`, not the
+ * legacy `projects` slug array; fall back to `projects` for deployments that
+ * still return it so metric alert view doesn't incorrectly show `(all)`.
+ */
+function pickDetectorProjects(detector: MetricDetector): string[] {
+  if (detector.projectSlug) {
+    return [detector.projectSlug];
+  }
+  return detector.projects ?? [];
+}
+
+/**
+ * Reduce a detector owner (object or bare string) to the flat actor identifier.
+ *
+ * Legacy `/alert-rules/` returned `owner` as an actor string like `user:123`
+ * or `team:456`, and the CLI formatters/JSON still treat it that way. Detectors
+ * expose the owner as `{ type, id, name }`, so reconstruct `type:id` to preserve
+ * that shape; fall back to a bare `id`/`name` when `type` is absent.
+ */
+function pickDetectorOwner(owner: MetricDetector["owner"]): string | null {
+  if (typeof owner === "string") {
+    return owner;
+  }
+  if (owner && typeof owner === "object") {
+    if (owner.type && owner.id) {
+      return `${owner.type}:${owner.id}`;
+    }
+    return owner.id ?? owner.name ?? null;
+  }
+  return null;
+}
+
+/**
+ * Locate the object holding the threshold query fields for a detector.
+ *
+ * Depending on deployment the `SnubaQuery` fields (aggregate/dataset/query/
+ * timeWindow) sit directly on `dataSources[0]`, under a `queryObj`, under a
+ * `snubaQuery`, or nested at `queryObj.snubaQuery`. Walk those candidates
+ * breadth-first and return the first that actually exposes an `aggregate` or
+ * `query`, so a wrapper object (e.g. a `queryObj` whose real fields live in a
+ * nested `snubaQuery`) doesn't flatten everything to empty.
+ */
+function resolveThresholdSource(
+  source: Record<string, unknown>
+): Record<string, unknown> {
+  const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+    value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : undefined;
+
+  const queryObj = asRecord(source.queryObj);
+  const snubaQuery = asRecord(source.snubaQuery);
+  const candidates = [
+    queryObj && asRecord(queryObj.snubaQuery),
+    queryObj,
+    snubaQuery,
+    source,
+  ];
+
+  for (const candidate of candidates) {
+    if (candidate && ("aggregate" in candidate || "query" in candidate)) {
+      return candidate;
+    }
+  }
+  return source;
+}
+
+function mapDetectorToMetricAlertRule(
+  detector: MetricDetector
+): MetricAlertRule {
+  const source = detector.dataSources?.[0] ?? {};
+  const nested = resolveThresholdSource(source);
+
+  const environment =
+    pickDetectorString(nested.environment) || detector.environment || null;
+
+  // The detector payload exposes timeWindow in seconds, but MetricAlertRule
+  // (and every CLI formatter, which appends "m") treats it as whole minutes.
+  const timeWindowSeconds = pickDetectorNumber(nested.timeWindow);
+
+  return {
+    id: String(detector.id),
+    name: detector.name,
+    status: detector.enabled === false ? 1 : 0,
+    query: pickDetectorString(nested.query),
+    aggregate: pickDetectorString(nested.aggregate),
+    dataset: pickDetectorString(nested.dataset),
+    timeWindow: timeWindowSeconds > 0 ? Math.round(timeWindowSeconds / 60) : 0,
+    environment,
+    owner: pickDetectorOwner(detector.owner),
+    projects: pickDetectorProjects(detector),
+    dateCreated: detector.dateCreated ?? "",
+  };
+}
+
 // Issue alerts
 //
 // Issue alert rules are read from the org-scoped `/organizations/{org}/workflows/`
@@ -164,10 +317,26 @@ export async function getIssueAlertRule(
 }
 
 // Metric alerts
+//
+// Metric alert rules are read from the org-scoped
+// `/organizations/{org}/detectors/` endpoint (filtered to `type:metric_issue`).
+// The legacy `/organizations/{org}/alert-rules/` endpoint is being retired on
+// 2026-08-17 (getsentry/cli#1274, #1182). Detectors return a nested shape, so
+// `mapDetectorToMetricAlertRule` flattens each detector into the existing
+// `MetricAlertRule` shape the commands already consume. Mutations
+// (create/update/delete) still use the legacy endpoint pending a follow-up
+// migration to the detectors/monitors + workflows write APIs.
+
+/** Search query that limits the detectors endpoint to metric alert rules. */
+const METRIC_DETECTOR_QUERY = "type:metric_issue";
 
 /**
  * List metric alert rules for an organization with cursor-based pagination.
  *
+ * Reads from the org-scoped `/detectors/` endpoint filtered to
+ * `type:metric_issue` and maps each detector onto the flat `MetricAlertRule`
+ * shape.
+ *
  * @param orgSlug - Organization slug
  * @param options - Pagination parameters (perPage, cursor)
  * @returns Paginated response with metric alert rules and optional next cursor
@@ -176,14 +345,27 @@ export async function listMetricAlertsPaginated(
   orgSlug: string,
   options: { perPage?: number; cursor?: string } = {}
 ): Promise<PaginatedResponse<MetricAlertRule[]>> {
-  const regionUrl = await resolveOrgRegion(orgSlug);
-  const { data, headers } = await apiRequestToRegion<MetricAlertRule[]>(
-    regionUrl,
-    `/organizations/${orgSlug}/alert-rules/`,
-    { params: { per_page: options.perPage, cursor: options.cursor } }
+  const config = await getOrgSdkConfig(orgSlug);
+  const result = await listOrganizationDetectors({
+    ...config,
+    path: { organization_id_or_slug: orgSlug },
+    query: {
+      query: METRIC_DETECTOR_QUERY,
+      sortBy: "-id",
+      cursor: options.cursor,
+      per_page: options.perPage,
+    } as {
+      query?: string;
+      sortBy?: string;
+      cursor?: string;
+      per_page?: number;
+    },
+  });
+  const { data, nextCursor } = unwrapPaginatedResult<MetricDetector[]>(
+    result,
+    "Failed to list metric alert rules"
   );
-  const { nextCursor } = parseLinkHeader(headers.get("link") ?? null);
-  return { data, nextCursor };
+  return { data: data.map(mapDetectorToMetricAlertRule), nextCursor };
 }
 
 /** Single GET for org metric alert rule (typed or full JSON for PUT). */
@@ -202,16 +384,48 @@ async function fetchMetricAlertRuleJson(
 /**
  * Get a single metric alert rule by ID.
  *
+ * Reads from the org-scoped `/detectors/{id}/` endpoint and maps the detector
+ * onto the flat `MetricAlertRule` shape.
+ *
+ * The `/detectors/{id}/` endpoint returns any detector kind (uptime, cron,
+ * error, …), unlike the `type:metric_issue`-filtered list. A non-metric id is
+ * rejected with a 404 so view/edit/delete don't silently render an unrelated
+ * detector as a metric alert with empty threshold fields.
+ *
  * @param orgSlug - Organization slug
- * @param ruleId - Alert rule ID
+ * @param ruleId - Detector (alert rule) ID
  * @returns The metric alert rule
  */
 export async function getMetricAlertRule(
   orgSlug: string,
   ruleId: string
 ): Promise<MetricAlertRule> {
-  const data = await fetchMetricAlertRuleJson(orgSlug, ruleId);
-  return data as MetricAlertRule;
+  const config = await getOrgSdkConfig(orgSlug);
+  const result = await getOrganizationDetector({
+    ...config,
+    // The SDK types detector_id as number, but detector IDs are opaque strings
+    // the API accepts verbatim; pass the string through the string-keyed path.
+    path: {
+      organization_id_or_slug: orgSlug,
+      detector_id: ruleId,
+    } as unknown as {
+      organization_id_or_slug: string;
+      detector_id: number;
+    },
+  });
+  const data = unwrapResult<MetricDetector>(
+    result,
+    `Failed to get metric alert rule '${ruleId}'`
+  );
+  if (data.type !== undefined && data.type !== "metric_issue") {
+    throw new ApiError(
+      `Metric alert rule '${ruleId}' not found`,
+      404,
+      `Detector '${ruleId}' is of type '${data.type}', not a metric alert.`,
+      `/organizations/${orgSlug}/detectors/${encodeURIComponent(ruleId)}/`
+    );
+  }
+  return mapDetectorToMetricAlertRule(data);
 }
 
 // Issue alert write operations