fix(region): resolve DSN org prefix at resolution layer (#316)

Move DSN org prefix normalization from arg-parsing (proactive strip)
to resolution layer (best-effort fallback). When an org identifier
like "o1081365" fails API resolution, resolveEffectiveOrg() strips
the "o" prefix and retries with the numeric ID.

- Add resolveEffectiveOrg() to src/lib/region.ts with cache-aware
  fast path and AuthError-safe fallback
- Move stripDsnOrgPrefix() to src/lib/dsn/parser.ts (co-located
  with DSN parsing logic)
- Remove normalization from arg-parsing.ts — parser preserves raw
  input unchanged
- Apply resolveEffectiveOrg() at 7 call sites across event/view,
  issue/utils, org-list, and resolve-target
- Update tests to expect raw "oNNNNN" values from parser

Author: BYK

AGENTS.md

@@ -21,6 +21,7 @@ import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
 import { ContextError, ResolutionError } from "../../lib/errors.js";
 import { formatEventDetails, writeJson } from "../../lib/formatters/index.js";
+import { resolveEffectiveOrg } from "../../lib/region.js";
 import {
   resolveOrgAndProject,
   resolveProjectBySlug,
@@ -168,13 +169,15 @@ export async function resolveEventTarget(
   const { parsed, eventId, cwd, stderr } = options;
 
   switch (parsed.type) {
-    case ProjectSpecificationType.Explicit:
+    case ProjectSpecificationType.Explicit: {
+      const org = await resolveEffectiveOrg(parsed.org);
       return {
-        org: parsed.org,
+        org,
         project: parsed.project,
         orgDisplay: parsed.org,
         projectDisplay: parsed.project,
       };
+    }
 
     case ProjectSpecificationType.ProjectSearch: {
       const resolved = await resolveProjectBySlug(
@@ -190,8 +193,10 @@ export async function resolveEventTarget(
       };
     }
 
-    case ProjectSpecificationType.OrgAll:
-      return resolveOrgAllTarget(parsed.org, eventId, cwd);
+    case ProjectSpecificationType.OrgAll: {
+      const org = await resolveEffectiveOrg(parsed.org);
+      return resolveOrgAllTarget(org, eventId, cwd);
+    }
 
     case ProjectSpecificationType.AutoDetect:
       return resolveAutoDetectTarget(eventId, cwd, stderr);

src/commands/event/view.ts

@@ -19,6 +19,7 @@ import { ApiError, ContextError, ResolutionError } from "../../lib/errors.js";
 import { getProgressMessage } from "../../lib/formatters/seer.js";
 import { expandToFullShortId, isShortSuffix } from "../../lib/issue-id.js";
 import { poll } from "../../lib/polling.js";
+import { resolveEffectiveOrg } from "../../lib/region.js";
 import { resolveOrg, resolveOrgAndProject } from "../../lib/resolve-target.js";
 import { parseSentryUrl } from "../../lib/sentry-url-parser.js";
 import { isAllDigits } from "../../lib/utils.js";
@@ -328,24 +329,26 @@ export async function resolveIssue(
 
     case "explicit": {
       // Full context: org + project + suffix
+      const org = await resolveEffectiveOrg(parsed.org);
       const fullShortId = expandToFullShortId(parsed.suffix, parsed.project);
-      const issue = await getIssueByShortId(parsed.org, fullShortId);
-      return { org: parsed.org, issue };
+      const issue = await getIssueByShortId(org, fullShortId);
+      return { org, issue };
     }
 
     case "explicit-org-numeric": {
       // Org + numeric ID — use org-scoped endpoint for proper region routing.
+      const org = await resolveEffectiveOrg(parsed.org);
       try {
-        const issue = await getIssueInOrg(parsed.org, parsed.numericId);
-        return { org: parsed.org, issue };
+        const issue = await getIssueInOrg(org, parsed.numericId);
+        return { org, issue };
       } catch (err) {
         if (err instanceof ApiError && err.status === 404) {
           throw new ResolutionError(
             `Issue ${parsed.numericId}`,
             "not found",
             commandHint,
             [
-              `No issue with numeric ID ${parsed.numericId} found in org '${parsed.org}' — you may not have access, or it may have been deleted.`,
+              `No issue with numeric ID ${parsed.numericId} found in org '${org}' — you may not have access, or it may have been deleted.`,
               `If this is a short ID suffix, try: sentry issue ${command} <project>-${parsed.numericId}`,
             ]
           );
@@ -354,9 +357,11 @@ export async function resolveIssue(
       }
     }
 
-    case "explicit-org-suffix":
+    case "explicit-org-suffix": {
       // Org + suffix only - ambiguous without project, always errors
-      return resolveExplicitOrgSuffix(parsed.org, parsed.suffix, commandHint);
+      const org = await resolveEffectiveOrg(parsed.org);
+      return resolveExplicitOrgSuffix(org, parsed.suffix, commandHint);
+    }
 
     case "project-search":
       // Project slug + suffix - search across orgs

src/commands/issue/utils.ts

@@ -51,6 +51,7 @@ export {
   inferPackagePath,
   isValidDsn,
   parseDsn,
+  stripDsnOrgPrefix,
 } from "./parser.js";
 // Project Root Detection
 export type { ProjectRootReason, ProjectRootResult } from "./project-root.js";

src/lib/dsn/index.ts

@@ -209,3 +209,35 @@ export function createDsnFingerprint(dsns: DetectedDsn[]): string {
   // Deduplicate (same DSN might be detected from multiple sources)
   return [...new Set(keys)].join(",");
 }
+
+/**
+ * Pattern matching bare DSN-style org identifiers: "o" followed by only digits.
+ *
+ * This is the bare-identifier counterpart of {@link ORG_ID_PATTERN} (which
+ * matches the full ingest host). Used to normalize org identifiers that
+ * were extracted from a DSN host and passed as CLI arguments.
+ */
+const DSN_ORG_PREFIX_PATTERN = /^o(\d+)$/;
+
+/**
+ * Normalize a DSN-style org identifier to a numeric org ID.
+ *
+ * DSN hosts encode org IDs as `oNNNNN` (e.g., `o1081365` from
+ * `o1081365.ingest.us.sentry.io`). The Sentry API accepts numeric IDs
+ * via `organization_id_or_slug` but not the `o`-prefixed DSN form.
+ *
+ * Only matches the exact pattern "o" + digits — normal slugs like
+ * `organic` or `o1abc` pass through unchanged.
+ *
+ * @param org - Raw org identifier
+ * @returns Numeric org ID if input matches `oNNNNN`, otherwise unchanged
+ *
+ * @example
+ * stripDsnOrgPrefix("o1081365")  // "1081365"
+ * stripDsnOrgPrefix("o123")      // "123"
+ * stripDsnOrgPrefix("sentry")    // "sentry"  (no change)
+ * stripDsnOrgPrefix("organic")   // "organic" (no change — not all digits after 'o')
+ */
+export function stripDsnOrgPrefix(org: string): string {
+  return org.replace(DSN_ORG_PREFIX_PATTERN, "$1");
+}

src/lib/dsn/parser.ts

@@ -39,6 +39,7 @@ import {
 } from "./db/pagination.js";
 import { AuthError, ContextError, ValidationError } from "./errors.js";
 import { writeFooter, writeJson } from "./formatters/index.js";
+import { resolveEffectiveOrg } from "./region.js";
 import { resolveOrgsForListing } from "./resolve-target.js";
 
 // ---------------------------------------------------------------------------
@@ -764,11 +765,26 @@ export async function dispatchOrgScopedList<TEntity, TWithOrg>(
     );
   }
 
+  // Normalize DSN-style org identifiers (e.g., "o1081365" → "1081365").
+  // Only fires as a fallback when the original org fails region resolution.
+  let effectiveParsed: ParsedOrgProject = parsed;
+  if (parsed.type === "explicit" || parsed.type === "org-all") {
+    const effectiveOrg = await resolveEffectiveOrg(parsed.org);
+    if (effectiveOrg !== parsed.org) {
+      effectiveParsed = { ...parsed, org: effectiveOrg };
+    }
+  }
+
   const defaults = buildDefaultHandlers(config);
   const handlers: ModeHandlerMap = { ...defaults, ...overrides };
-  const handler = handlers[parsed.type];
+  const handler = handlers[effectiveParsed.type];
 
-  const ctx: HandlerContext = { parsed, stdout, cwd, flags };
+  const ctx: HandlerContext = {
+    parsed: effectiveParsed,
+    stdout,
+    cwd,
+    flags,
+  };
 
   // TypeScript cannot prove that `parsed` narrows to `ParsedVariant<typeof parsed.type>`
   // through the dynamic handler lookup, but the handler map guarantees type safety.

src/lib/org-list.ts

@@ -7,6 +7,7 @@
 
 import { retrieveAnOrganization } from "@sentry/api";
 import { getOrgRegion, setOrgRegion } from "./db/regions.js";
+import { stripDsnOrgPrefix } from "./dsn/index.js";
 import { AuthError } from "./errors.js";
 import { getSdkConfig } from "./sentry-client.js";
 import { getSentryBaseUrl, isSentrySaasUrl } from "./sentry-urls.js";
@@ -78,3 +79,76 @@ export function isMultiRegionEnabled(): boolean {
   }
   return true;
 }
+
+/**
+ * Resolve the effective org slug for API calls, with DSN prefix fallback.
+ *
+ * When users or AI agents extract org identifiers from DSN hosts
+ * (e.g., `o1081365` from `o1081365.ingest.us.sentry.io`), the `o`-prefixed
+ * form isn't recognized by the Sentry API. This function validates the org
+ * via region resolution and falls back to stripping the DSN prefix only
+ * when the original identifier fails.
+ *
+ * The fallback triggers only when:
+ * 1. The org wasn't previously cached (first-time resolution)
+ * 2. Region resolution didn't cache a result (API didn't recognize the org)
+ * 3. The org matches the DSN `oNNNNN` pattern
+ *
+ * `resolveOrgRegion` caches on success but not on failure — this is the
+ * signal used to detect that an org wasn't found.
+ *
+ * @param orgSlug - Raw org identifier from user input
+ * @returns The org slug to use for API calls (may be normalized)
+ */
+export async function resolveEffectiveOrg(orgSlug: string): Promise<string> {
+  // Fast path: already cached from a previous successful resolution
+  const cached = await getOrgRegion(orgSlug);
+  if (cached) {
+    return orgSlug;
+  }
+
+  // Attempt to resolve — resolveOrgRegion caches on success, not on failure.
+  // Auth errors mean we can't validate — return as-is and let downstream
+  // API calls produce the proper auth error with context.
+  try {
+    await resolveOrgRegion(orgSlug);
+  } catch (error) {
+    if (error instanceof AuthError) {
+      return orgSlug;
+    }
+    throw error;
+  }
+
+  // Check if the resolution succeeded (was it cached?)
+  const afterResolve = await getOrgRegion(orgSlug);
+  if (afterResolve) {
+    return orgSlug;
+  }
+
+  // Resolution failed — try DSN prefix stripping as fallback
+  const stripped = stripDsnOrgPrefix(orgSlug);
+  if (stripped === orgSlug) {
+    // Not a DSN-style identifier — return as-is, let downstream fail naturally
+    return orgSlug;
+  }
+
+  // Try the stripped version
+  try {
+    await resolveOrgRegion(stripped);
+  } catch (error) {
+    if (error instanceof AuthError) {
+      return orgSlug;
+    }
+    throw error;
+  }
+
+  const strippedCached = await getOrgRegion(stripped);
+  if (strippedCached) {
+    // Cache under original key too so future calls are instant
+    await setOrgRegion(orgSlug, strippedCached);
+    return stripped;
+  }
+
+  // Neither worked — return original, let downstream produce the error
+  return orgSlug;
+}

src/lib/region.ts

@@ -45,6 +45,7 @@ import {
   ValidationError,
 } from "./errors.js";
 import { warning } from "./formatters/colors.js";
+import { resolveEffectiveOrg } from "./region.js";
 import { isAllDigits } from "./utils.js";
 
 /**
@@ -996,8 +997,10 @@ export async function resolveOrgProjectTarget(
   const usageHint = `sentry ${commandName} <org>/<project>`;
 
   switch (parsed.type) {
-    case "explicit":
-      return { org: parsed.org, project: parsed.project };
+    case "explicit": {
+      const org = await resolveEffectiveOrg(parsed.org);
+      return { org, project: parsed.project };
+    }
 
     case "org-all":
       throw new ContextError(