sentry-urls.ts

/**
 * Sentry URL Utilities
 *
 * Utilities for constructing Sentry web URLs.
 * Supports self-hosted instances via SENTRY_URL environment variable.
 */

import {
  DEFAULT_SENTRY_HOST,
  DEFAULT_SENTRY_URL,
  getConfiguredSentryUrl,
} from "./constants.js";

/**
 * Get the Sentry web base URL.
 * Supports self-hosted instances via SENTRY_URL env var.
 */
export function getSentryBaseUrl(): string {
  return getConfiguredSentryUrl() ?? DEFAULT_SENTRY_URL;
}

/**
 * Build the org-scoped base URL using the subdomain pattern.
 * E.g. "https://sentry.io" + "my-org" → "https://my-org.sentry.io"
 *
 * @param orgSlug - Organization slug
 * @returns Origin URL with org as subdomain
 */
export function getOrgBaseUrl(orgSlug: string): string {
  const base = getSentryBaseUrl();
  if (!isSentrySaasUrl(base)) {
    return base;
  }
  const parsed = new URL(base);
  parsed.hostname = `${orgSlug}.${parsed.hostname}`;
  return parsed.origin;
}

function isSaaS(): boolean {
  return isSentrySaasUrl(getSentryBaseUrl());
}

/**
 * Check if a URL is a Sentry SaaS domain.
 *
 * Used to determine if multi-region support should be enabled and to
 * validate region URLs before sending authenticated requests.
 *
 * @param url - URL string to validate
 * @returns true if the hostname is sentry.io or a subdomain of sentry.io
 */
export function isSentrySaasUrl(url: string): boolean {
  try {
    const parsed = new URL(url);
    return (
      parsed.hostname === DEFAULT_SENTRY_HOST ||
      parsed.hostname.endsWith(`.${DEFAULT_SENTRY_HOST}`)
    );
  } catch {
    return false;
  }
}

/**
 * Build URL to view an organization in Sentry.
 *
 * @param orgSlug - Organization slug
 * @returns Full URL to the organization page
 */
export function buildOrgUrl(orgSlug: string): string {
  if (isSaaS()) {
    return `${getOrgBaseUrl(orgSlug)}/`;
  }
  return `${getSentryBaseUrl()}/organizations/${orgSlug}/`;
}

/**
 * Build URL to view a project in Sentry.
 *
 * @param orgSlug - Organization slug
 * @param projectSlug - Project slug
 * @returns Full URL to the project settings page
 */
export function buildProjectUrl(orgSlug: string, projectSlug: string): string {
  if (isSaaS()) {
    return `${getOrgBaseUrl(orgSlug)}/settings/projects/${projectSlug}/`;
  }
  return `${getSentryBaseUrl()}/settings/${orgSlug}/projects/${projectSlug}/`;
}

/**
 * Build URL to view an issue in Sentry.
 *
 * @param orgSlug - Organization slug
 * @param issueId - Numeric issue ID
 * @returns Full URL to the issue detail page
 */
export function buildIssueUrl(orgSlug: string, issueId: string): string {
  if (isSaaS()) {
    return `${getOrgBaseUrl(orgSlug)}/issues/${issueId}/`;
  }
  return `${getSentryBaseUrl()}/organizations/${orgSlug}/issues/${issueId}/`;
}

/**
 * Build URL to search for an event in Sentry.
 * Uses the issues search with event.id filter.
 *
 * @param orgSlug - Organization slug
 * @param eventId - Event ID (hexadecimal)
 * @returns Full URL to search results showing the event
 */
export function buildEventSearchUrl(orgSlug: string, eventId: string): string {
  if (isSaaS()) {
    return `${getOrgBaseUrl(orgSlug)}/issues/?query=event.id:${eventId}`;
  }
  return `${getSentryBaseUrl()}/organizations/${orgSlug}/issues/?query=event.id:${eventId}`;
}

// Settings URLs

/**
 * Build URL to organization settings page.
 *
 * @param orgSlug - Organization slug
 * @param hash - Optional anchor hash (e.g., "hideAiFeatures")
 * @returns Full URL to the organization settings page
 */
export function buildOrgSettingsUrl(orgSlug: string, hash?: string): string {
  const url = isSaaS()
    ? `${getOrgBaseUrl(orgSlug)}/settings/`
    : `${getSentryBaseUrl()}/settings/${orgSlug}/`;
  return hash ? `${url}#${hash}` : url;
}

/**
 * Build URL to Seer settings page.
 *
 * @param orgSlug - Organization slug
 * @returns Full URL to the Seer settings page
 */
export function buildSeerSettingsUrl(orgSlug: string): string {
  if (isSaaS()) {
    return `${getOrgBaseUrl(orgSlug)}/settings/seer/`;
  }
  return `${getSentryBaseUrl()}/settings/${orgSlug}/seer/`;
}

/**
 * Build URL to billing page with optional product filter.
 *
 * @param orgSlug - Organization slug
 * @param product - Optional product to highlight (e.g., "seer")
 * @returns Full URL to the billing overview page
 */
export function buildBillingUrl(orgSlug: string, product?: string): string {
  const base = isSaaS()
    ? `${getOrgBaseUrl(orgSlug)}/settings/billing/overview/`
    : `${getSentryBaseUrl()}/settings/${orgSlug}/billing/overview/`;
  return product ? `${base}?product=${product}` : base;
}

// Logs URLs

/**
 * Build URL to the Logs explorer, optionally filtered to a specific log entry.
 *
 * @param orgSlug - Organization slug
 * @param logId - Optional log item ID to filter to
 * @returns Full URL to the Logs explorer
 */
export function buildLogsUrl(orgSlug: string, logId?: string): string {
  const base = isSaaS()
    ? `${getOrgBaseUrl(orgSlug)}/explore/logs/`
    : `${getSentryBaseUrl()}/organizations/${orgSlug}/explore/logs/`;
  return logId ? `${base}?query=sentry.item_id:${logId}` : base;
}

// Dashboard URLs

/**
 * Build URL to the dashboards list page.
 *
 * @param orgSlug - Organization slug
 * @returns Full URL to the dashboards list page
 */
export function buildDashboardsListUrl(orgSlug: string): string {
  if (isSaaS()) {
    return `${getOrgBaseUrl(orgSlug)}/dashboards/`;
  }
  return `${getSentryBaseUrl()}/organizations/${orgSlug}/dashboards/`;
}

/**
 * Build URL to view a specific dashboard.
 *
 * @param orgSlug - Organization slug
 * @param dashboardId - Dashboard ID
 * @returns Full URL to the dashboard view page
 */
export function buildDashboardUrl(
  orgSlug: string,
  dashboardId: string
): string {
  if (isSaaS()) {
    return `${getOrgBaseUrl(orgSlug)}/dashboard/${dashboardId}/`;
  }
  return `${getSentryBaseUrl()}/organizations/${orgSlug}/dashboard/${dashboardId}/`;
}

/**
 * Build URL to view a trace in Sentry.
 *
 * @param orgSlug - Organization slug
 * @param traceId - Trace ID (32-character hex string)
 * @returns Full URL to the trace view
 */
export function buildTraceUrl(orgSlug: string, traceId: string): string {
  if (isSaaS()) {
    return `${getOrgBaseUrl(orgSlug)}/traces/${traceId}/`;
  }
  return `${getSentryBaseUrl()}/organizations/${orgSlug}/traces/${traceId}/`;
}