Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

26.3 KB
Raw Blame
// Centralized API client with authentication support
// This replaces the three separate auth utilities (api.ts, auth.ts, authInterceptor.ts)

import { logger } from '@/utils/logger';
import { STORAGE_KEYS } from '@/utils/localStorage';

const AUTH_STORAGE_KEY = STORAGE_KEYS.AUTH;
const AUTH_USER_STORAGE_KEY = STORAGE_KEYS.AUTH_USER;
const ORG_STORAGE_KEY = STORAGE_KEYS.ORG_ID;
const ORG_HEADER_NAME = 'X-Pulse-Org-ID';
const ORG_COOKIE_NAME = 'pulse_org_id';
const CONTROL_CHAR_PATTERN = /[\u0000-\u001F\u007F]/; // eslint-disable-line no-control-regex -- intentional sanitization
const MAX_ORG_ID_LENGTH = 128;
const MAX_API_TOKEN_LENGTH = 8 * 1024;
const MAX_AUTH_STORAGE_CHARS = 16 * 1024;
const MAX_API_ERROR_CODE_LENGTH = 128;
const MAX_API_ERROR_DETAIL_KEY_LENGTH = 128;
const MAX_API_ERROR_DETAIL_VALUE_LENGTH = 2048;
const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']);

const sanitizeBoundedText = (value: unknown, maxLength: number): string | null => {
  if (typeof value !== 'string') {
    return null;
  }

  const normalized = value.trim();
  if (!normalized || normalized.length > maxLength || CONTROL_CHAR_PATTERN.test(normalized)) {
    return null;
  }

  return normalized;
};

const sanitizeOrgID = (value: unknown): string | null => {
  return sanitizeBoundedText(value, MAX_ORG_ID_LENGTH);
};

const sanitizeApiToken = (value: unknown): string | null => {
  return sanitizeBoundedText(value, MAX_API_TOKEN_LENGTH);
};

const readOrgCookie = (): string | null => {
  if (typeof document === 'undefined') {
    return null;
  }

  const cookies = document.cookie.split(';');
  for (const cookie of cookies) {
    const [name, ...rest] = cookie.trim().split('=');
    if (name !== ORG_COOKIE_NAME) {
      continue;
    }
    try {
      return sanitizeOrgID(decodeURIComponent(rest.join('=') || ''));
    } catch {
      return null;
    }
  }

  return null;
};

const getSessionStorage = (): Storage | undefined => {
  if (typeof window === 'undefined') {
    return undefined;
  }
  try {
    return window.sessionStorage;
  } catch {
    return undefined;
  }
};

interface FetchOptions extends Omit<RequestInit, 'headers'> {
  headers?: Record<string, string>;
  preferSessionAuth?: boolean;
  skipAuth?: boolean;
  skipOrgContext?: boolean;
  // Reviewed destructive operations can opt out of auth/CSRF/rate-limit
  // retries and bind dispatch to the organisation whose data was confirmed.
  retry?: boolean;
  expectedOrgID?: string;
}

// A surface can retain its admitted workspace without exposing auth/header overrides.
export type APIContextOptions = Pick<FetchOptions, 'expectedOrgID' | 'retry' | 'signal' | 'cache'>;

type APIErrorDetails = Record<string, string>;

type APIErrorShape = Error & {
  code?: string;
  detail?: string;
  details?: APIErrorDetails;
  feature?: string;
  requiredScope?: string;
  upgrade_url?: string;
  status?: number;
};

const sanitizeAPIErrorDetails = (value: unknown): APIErrorDetails | undefined => {
  if (!value || typeof value !== 'object') {
    return undefined;
  }

  const details: APIErrorDetails = {};
  for (const [rawKey, rawValue] of Object.entries(value as Record<string, unknown>)) {
    const key = sanitizeBoundedText(rawKey, MAX_API_ERROR_DETAIL_KEY_LENGTH);
    const resolvedValue = sanitizeBoundedText(rawValue, MAX_API_ERROR_DETAIL_VALUE_LENGTH);
    if (!key || !resolvedValue) {
      continue;
    }
    details[key] = resolvedValue;
  }

  return Object.keys(details).length > 0 ? details : undefined;
};

async function createAPIErrorFromResponse(
  response: Response,
  fallbackMessage?: string,
): Promise<APIErrorShape> {
  const text = await response.text();
  // Never pre-seed the message with the raw body: a reverse proxy error page
  // is a full HTML document, and whatever lands here becomes Error.message
  // rendered directly in the UI (#1640).
  let errorMessage = fallbackMessage || '';

  let errorCode: string | undefined;
  let errorDetail: string | undefined;
  let errorDetails: APIErrorDetails | undefined;
  let errorFeature: string | undefined;
  let errorRequiredScope: string | undefined;
  let errorUpgradeUrl: string | undefined;
  try {
    const jsonError = JSON.parse(text);
    if (jsonError.message) {
      errorMessage = jsonError.message;
    } else if (jsonError.error && typeof jsonError.error === 'string') {
      errorMessage = jsonError.error;
    }
    if (typeof jsonError.detail === 'string') {
      errorDetail = jsonError.detail;
    }
    errorCode = sanitizeBoundedText(jsonError.code, MAX_API_ERROR_CODE_LENGTH) ?? undefined;
    errorDetails = sanitizeAPIErrorDetails(jsonError.details);
    errorRequiredScope = sanitizeBoundedText(jsonError.requiredScope, 128) ?? undefined;
    errorFeature = sanitizeBoundedText(jsonError.feature, 128) ?? undefined;
    errorUpgradeUrl = sanitizeBoundedText(jsonError.upgrade_url, 2048) ?? undefined;
  } catch {
    // Non-JSON body. Surface it only when it reads as a short plain-text
    // message; anything with markup or excessive length (proxy/gateway HTML
    // error pages) is dropped so it can never become Error.message (#1640).
    // A sane server-provided body outranks the caller's generic fallback —
    // that has always been the precedence here, and call sites rely on it to
    // surface server detail on retryable errors.
    let bodyMessage = '';
    if (text.includes('<pre>') && text.includes('</pre>')) {
      const match = text.match(/<pre>(.*?)<\/pre>/s);
      const extracted = match ? match[1].trim() : '';
      if (extracted && !extracted.includes('<') && extracted.length < 200) {
        bodyMessage = extracted;
      }
    } else if (!text.includes('<') && text.trim() && text.length < 200) {
      bodyMessage = text.trim();
    }

    errorMessage = bodyMessage || errorMessage || `Request failed with status ${response.status}`;
  }

  const err = new Error(
    errorMessage || `Request failed with status ${response.status}`,
  ) as APIErrorShape;
  err.status = response.status;
  if (errorCode) {
    err.code = errorCode;
  }
  if (errorDetail) {
    err.detail = errorDetail;
  }
  if (errorDetails) {
    err.details = errorDetails;
  }
  if (errorRequiredScope) {
    err.requiredScope = errorRequiredScope;
  }
  if (errorFeature) {
    err.feature = errorFeature;
  }
  if (errorUpgradeUrl) {
    err.upgrade_url = errorUpgradeUrl;
  }
  return err;
}

function createAbortError(): Error {
  if (typeof DOMException !== 'undefined') {
    return new DOMException('The operation was aborted.', 'AbortError');
  }
  const error = new Error('The operation was aborted.');
  error.name = 'AbortError';
  return error;
}

function waitWithSignal(ms: number, signal?: AbortSignal | null): Promise<void> {
  if (ms <= 0) {
    return Promise.resolve();
  }

  if (signal?.aborted) {
    return Promise.reject(createAbortError());
  }

  return new Promise((resolve, reject) => {
    let timeoutId: ReturnType<typeof setTimeout> | null = null;

    const cleanup = () => {
      if (timeoutId !== null) {
        clearTimeout(timeoutId);
        timeoutId = null;
      }
      signal?.removeEventListener('abort', onAbort);
    };

    const onAbort = () => {
      cleanup();
      reject(createAbortError());
    };

    timeoutId = setTimeout(() => {
      cleanup();
      resolve();
    }, ms);

    signal?.addEventListener('abort', onAbort, { once: true });
  });
}

class ApiClient {
  private apiToken: string | null = null;
  private csrfToken: string | null = null;
  private orgID: string | null = null;

  constructor() {
    // Check session storage for existing auth on page load
    this.loadStoredAuth();
    this.loadStoredOrgContext();
    // Load CSRF token from cookie
    this.loadCSRFToken();
  }

  private persistToken(token: string) {
    const sanitizedToken = sanitizeApiToken(token);
    if (!sanitizedToken) {
      this.apiToken = null;
      this.removeStoredToken();
      return;
    }

    const storage = getSessionStorage();
    this.apiToken = sanitizedToken;
    if (!storage) return;

    try {
      storage.setItem(
        STORAGE_KEYS.AUTH,
        JSON.stringify({
          type: 'token',
          value: sanitizedToken,
        }),
      );
    } catch {
      // Ignore storage quota errors
    }
  }

  private removeStoredToken() {
    const storage = getSessionStorage();
    if (!storage) return;

    try {
      storage.removeItem(AUTH_STORAGE_KEY);
    } catch {
      // Ignore storage quota errors
    }
  }

  private loadCSRFToken(): string | null {
    // Read CSRF token from cookie
    const cookies = document.cookie.split(';');
    for (const cookie of cookies) {
      const [name, ...rest] = cookie.trim().split('=');
      if (name !== 'pulse_csrf') continue;
      const value = rest.join('=');
      try {
        this.csrfToken = decodeURIComponent(value || '');
      } catch {
        this.csrfToken = null;
      }
      return this.csrfToken;
    }
    this.csrfToken = null;
    return null;
  }

  private loadStoredAuth() {
    // First, check for token in URL query parameter (for kiosk mode)
    // This allows visiting ?token=xxx to auto-authenticate without cookies
    try {
      if (typeof window !== 'undefined' && window.location?.search) {
        const params = new URLSearchParams(window.location.search);
        const urlToken = params.get('token');
        if (urlToken !== null) {
          const sanitizedToken = sanitizeApiToken(urlToken);
          // Clean the token from URL for security (don't expose in browser history),
          // regardless of whether the provided token is valid.
          params.delete('token');
          const newQuery = params.toString();
          const newUrl = `${window.location.pathname}${newQuery ? `?${newQuery}` : ''}`;
          window.history.replaceState({}, document.title, newUrl);
          if (sanitizedToken) {
            this.apiToken = sanitizedToken;
            this.persistToken(sanitizedToken);
          }
          return;
        }
      }
    } catch {
      // Ignore URL parsing/history errors.
    }

    const storage = getSessionStorage();
    if (!storage) return;

    try {
      const stored = storage.getItem(AUTH_STORAGE_KEY);
      if (stored) {
        if (stored.length > MAX_AUTH_STORAGE_CHARS) {
          storage.removeItem(AUTH_STORAGE_KEY);
          return;
        }

        const parsed = JSON.parse(stored);
        const token = parsed?.type === 'token' ? sanitizeApiToken(parsed?.value) : null;
        if (token) {
          this.apiToken = token;
          return;
        } else {
          storage.removeItem(AUTH_STORAGE_KEY);
        }
      }
    } catch {
      // Ignore parse failures.
    }
  }

  private loadStoredOrgContext() {
    const storage = getSessionStorage();
    let storageOrgID: string | null = null;

    if (storage) {
      try {
        const stored = storage.getItem(ORG_STORAGE_KEY);
        storageOrgID = sanitizeOrgID(stored);
        if (stored && !storageOrgID) {
          storage.removeItem(ORG_STORAGE_KEY);
        } else if (storageOrgID && stored !== storageOrgID) {
          storage.setItem(ORG_STORAGE_KEY, storageOrgID);
        }
      } catch {
        storageOrgID = null;
      }
    }

    const cookieOrgID = readOrgCookie();
    const resolvedOrgID = storageOrgID || cookieOrgID;
    this.orgID = resolvedOrgID;

    if (storage) {
      try {
        if (resolvedOrgID) {
          storage.setItem(ORG_STORAGE_KEY, resolvedOrgID);
        } else {
          storage.removeItem(ORG_STORAGE_KEY);
        }
      } catch {
        // Ignore storage errors.
      }
    }

    if (resolvedOrgID) {
      this.syncOrgCookie(resolvedOrgID);
    }
  }

  private syncOrgCookie(orgID: string | null) {
    if (typeof document === 'undefined') {
      return;
    }

    const normalizedOrgID = sanitizeOrgID(orgID);
    if (!normalizedOrgID) {
      document.cookie = `${ORG_COOKIE_NAME}=; Path=/; Max-Age=0; SameSite=Lax`;
      return;
    }

    const secureSuffix =
      typeof window !== 'undefined' && window.location?.protocol === 'https:' ? '; Secure' : '';
    document.cookie = `${ORG_COOKIE_NAME}=${encodeURIComponent(normalizedOrgID)}; Path=/; SameSite=Lax${secureSuffix}`;
  }

  private persistOrgContext(orgID: string | null) {
    const normalizedOrgID = sanitizeOrgID(orgID);
    const storage = getSessionStorage();

    if (storage) {
      try {
        if (normalizedOrgID) {
          storage.setItem(ORG_STORAGE_KEY, normalizedOrgID);
        } else {
          storage.removeItem(ORG_STORAGE_KEY);
        }
      } catch {
        // Ignore storage errors
      }
    }

    this.syncOrgCookie(normalizedOrgID);
  }

  setOrgID(orgID: string | null) {
    const normalized = sanitizeOrgID(orgID);
    this.orgID = normalized;
    this.persistOrgContext(normalized);
  }

  getOrgID(): string | null {
    const inMemoryOrgID = sanitizeOrgID(this.orgID);
    if (inMemoryOrgID) {
      this.orgID = inMemoryOrgID;
      return inMemoryOrgID;
    }
    this.orgID = null;

    const storage = getSessionStorage();
    if (!storage) {
      return null;
    }
    try {
      const stored = storage.getItem(ORG_STORAGE_KEY);
      const normalizedOrgID = sanitizeOrgID(stored);
      if (normalizedOrgID) {
        this.orgID = normalizedOrgID;
        if (stored !== normalizedOrgID) {
          storage.setItem(ORG_STORAGE_KEY, normalizedOrgID);
        }
        return this.orgID;
      }
      if (stored) {
        storage.removeItem(ORG_STORAGE_KEY);
      }
    } catch {
      // Ignore storage errors
    }

    const cookieOrgID = readOrgCookie();
    if (cookieOrgID) {
      this.orgID = cookieOrgID;
      if (storage) {
        try {
          storage.setItem(ORG_STORAGE_KEY, cookieOrgID);
        } catch {
          // Ignore storage errors.
        }
      }
      return cookieOrgID;
    }

    return null;
  }

  // Set API token
  setApiToken(token: string) {
    const sanitizedToken = sanitizeApiToken(token);
    if (!sanitizedToken) {
      this.clearApiToken();
      return;
    }

    this.apiToken = sanitizedToken;
    this.persistToken(sanitizedToken);
  }

  getApiToken(): string | null {
    if (this.apiToken) {
      return this.apiToken;
    }

    const storage = getSessionStorage();
    if (!storage) {
      return null;
    }

    const stored = storage.getItem(AUTH_STORAGE_KEY);
    if (stored) {
      try {
        if (stored.length <= MAX_AUTH_STORAGE_CHARS) {
          const parsed = JSON.parse(stored);
          const token = parsed?.type === 'token' ? sanitizeApiToken(parsed?.value) : null;
          if (token) {
            this.apiToken = token;
            return token;
          }
        }
      } catch {
        // Ignore parse failures and continue to fallback.
      }

      try {
        storage.removeItem(AUTH_STORAGE_KEY);
      } catch {
        // Ignore storage errors.
      }
    }

    return null;
  }

  // Clear all authentication
  clearAuth() {
    this.apiToken = null;
    this.orgID = null;
    this.removeStoredToken();
    this.persistOrgContext(null);

    const storage = getSessionStorage();
    if (!storage) return;
    try {
      storage.removeItem(AUTH_USER_STORAGE_KEY);
    } catch {
      // Ignore storage quota errors
    }
  }

  clearApiToken() {
    this.apiToken = null;
    this.removeStoredToken();
  }

  // Check if we have any auth configured
  hasAuth(): boolean {
    if (this.apiToken) {
      return true;
    }

    if (typeof document !== 'undefined') {
      const cookies = document.cookie.split(';');
      for (const cookie of cookies) {
        const [name] = cookie.trim().split('=');
        // Check both the plain and __Host- prefixed session cookie names.
        if (name === 'pulse_session' || name === '__Host-pulse_session') {
          return true;
        }
      }
    }

    return false;
  }

  // Ensure CSRF token is available by making a GET request if needed
  // The backend issues CSRF cookies on GET requests to /api/* endpoints
  private async ensureCSRFToken(): Promise<string | null> {
    // Unit tests run without a real backend and should not attempt network calls.
    // This avoids noisy warnings like "Failed to parse URL from /api/health" from Node's fetch.
    if (import.meta.env.MODE === 'test') {
      return null;
    }

    try {
      // Make a simple GET request to trigger CSRF cookie issuance
      const response = await fetch('/api/health', {
        method: 'GET',
        credentials: 'include',
      });

      // The response should have set the pulse_csrf cookie
      if (response.ok) {
        // Small delay to ensure cookie is set
        await waitWithSignal(10);
        return this.loadCSRFToken();
      }
    } catch (err) {
      logger.warn('Failed to fetch CSRF token', err);
    }
    return null;
  }

  // Main fetch wrapper that adds authentication
  async fetch(url: string, options: FetchOptions = {}): Promise<Response> {
    const {
      preferSessionAuth = false,
      skipAuth = false,
      skipOrgContext = false,
      retry = true,
      expectedOrgID,
      headers = {},
      ...fetchOptions
    } = options;

    // Build headers object
    const finalHeaders: Record<string, string> = { ...headers };
    const checkExpectedOrg = () => {
      if (expectedOrgID !== undefined && (this.getOrgID() || 'default') !== expectedOrgID) {
        throw new Error('Organisation changed. Reload before making changes.');
      }
    };
    checkExpectedOrg();
    if (expectedOrgID !== undefined) {
      finalHeaders[ORG_HEADER_NAME] = expectedOrgID;
    }

    // Always add headers to prevent browser auth popup for API calls
    if (url.startsWith('/api/')) {
      finalHeaders['X-Requested-With'] = 'XMLHttpRequest';
      if (!finalHeaders['Accept']) {
        finalHeaders['Accept'] = 'application/json';
      }

      if (skipOrgContext) {
        if (!finalHeaders[ORG_HEADER_NAME]) {
          finalHeaders[ORG_HEADER_NAME] = 'default';
        }
      } else if (!finalHeaders[ORG_HEADER_NAME]) {
        const orgID = this.getOrgID();
        if (orgID) {
          finalHeaders[ORG_HEADER_NAME] = orgID;
        }
      }
    }

    // Add authentication if available and not skipped
    if (!skipAuth) {
      if (this.apiToken && !preferSessionAuth) {
        finalHeaders['X-API-Token'] = this.apiToken;
      }
    }

    // Add CSRF token for state-changing requests
    const method = (fetchOptions.method || 'GET').toUpperCase();
    if (method !== 'GET' && method !== 'HEAD' && method !== 'OPTIONS') {
      // Try to get CSRF token, or fetch one if missing
      let token = this.loadCSRFToken();
      if (!token) {
        // No CSRF token available - try to get one by making a GET request
        token = await this.ensureCSRFToken();
      }
      if (token) {
        finalHeaders['X-CSRF-Token'] = token;
      }
    }

    // Always include credentials for cookies (WebSocket session support)
    const finalOptions: RequestInit = {
      ...fetchOptions,
      headers: finalHeaders,
      credentials: 'include', // Important for session cookies
    };

    // CSRF preparation may have awaited a request while the operator switched
    // organisations or left the view. Do not dispatch a stale confirmation.
    checkExpectedOrg();
    // Only strict confirmations opt into the extra pre-dispatch abort check;
    // ordinary callers retain native fetch's established abort behaviour.
    if (expectedOrgID !== undefined || !retry) fetchOptions.signal?.throwIfAborted();
    let response = await fetch(url, finalOptions);

    // Session-preferred reads intentionally omit the API token on their first
    // attempt because HttpOnly session cookies cannot be detected from browser
    // JavaScript. Token-only clients still retain scoped read access by
    // retrying an unauthenticated idempotent response once with their token.
    if (
      response.status === 401 &&
      retry &&
      preferSessionAuth &&
      !skipAuth &&
      this.apiToken &&
      IDEMPOTENT_METHODS.has(method)
    ) {
      response = await fetch(url, {
        ...finalOptions,
        headers: {
          ...finalHeaders,
          'X-API-Token': this.apiToken,
        },
      });
    }

    // Handle stale/invalid org context by clearing it and retrying once. The
    // server then resolves the organization: default where the user may use
    // it, otherwise the first organization they belong to. A refused default
    // selection is stale context too: multi-organization mode limits the
    // default organization to instance administrators and its members. Only
    // reads recover that way: retrying a write would silently apply it to the
    // organization the server picks instead of the one the user was viewing.
    const staleOrgStatus =
      (response.status === 400 &&
        !!finalHeaders[ORG_HEADER_NAME] &&
        finalHeaders[ORG_HEADER_NAME] !== 'default') ||
      (response.status === 403 && (method === 'GET' || method === 'HEAD'));
    if (
      staleOrgStatus &&
      retry &&
      expectedOrgID === undefined &&
      !skipOrgContext &&
      url.startsWith('/api/')
    ) {
      const text = await response.clone().text();
      let isInvalidOrg = false;
      try {
        const parsed = JSON.parse(text);
        isInvalidOrg =
          response.status === 400
            ? parsed?.error === 'invalid_org'
            : parsed?.error === 'default_org_access_denied';
      } catch {
        isInvalidOrg = false;
      }

      if (isInvalidOrg) {
        this.setOrgID(null);
        const retryHeaders: Record<string, string> = { ...finalHeaders };
        delete retryHeaders[ORG_HEADER_NAME];
        return await fetch(url, {
          ...fetchOptions,
          headers: retryHeaders,
          credentials: 'include',
        });
      }
    }

    // If we get a 401 on an API call (not during initial auth check), redirect to login
    // Skip redirect for specific auth-check endpoints and background data fetching to avoid loops
    const skipRedirectUrls = [
      '/api/security/status',
      '/api/state',
      '/api/settings/ai',
      '/api/charts',
      '/api/charts/infrastructure',
    ];
    const shouldSkipRedirect = skipRedirectUrls.some((path) => url.includes(path));
    // Sign-out owns its result: a rejected or lost withdrawal must remain
    // visible, not become a login redirect that looks like successful logout.
    if (response.status === 401 && !skipAuth && !shouldSkipRedirect && url !== '/api/logout') {
      logger.warn('Authentication expired - redirecting to login');
      // Clear auth and redirect to login
      if (typeof window !== 'undefined') {
        this.clearAuth();
        localStorage.setItem('just_logged_out', 'true');
        window.location.href = '/';
      }
      return response;
    }

    // Handle CSRF token failures - the 403 response should have set a new CSRF cookie
    if (response.status === 403 && retry) {
      // First try the response header (backend sends new token in X-CSRF-Token header)
      let refreshedToken = response.headers.get('X-CSRF-Token');

      // If not in header, reload from cookie (backend also sets pulse_csrf cookie on 403)
      if (!refreshedToken) {
        // Force reload from cookie - the 403 response just set it
        this.csrfToken = null;
        refreshedToken = this.loadCSRFToken();
      }

      if (refreshedToken) {
        this.csrfToken = refreshedToken;
        logger.debug(`[apiClient] Retrying ${method} ${url} with refreshed CSRF token`);
        finalHeaders['X-CSRF-Token'] = refreshedToken;
        const retryResponse = await fetch(url, {
          ...fetchOptions,
          headers: finalHeaders,
          credentials: 'include',
        });
        return retryResponse;
      }
    }

    // Handle rate limiting with automatic retry for idempotent requests only.
    if (response.status === 429 && retry) {
      if (!IDEMPOTENT_METHODS.has(method)) {
        return response;
      }

      const retryAfterHeader = response.headers.get('Retry-After');
      let waitTime = 1000; // Default: 1 second
      if (retryAfterHeader) {
        const normalized = retryAfterHeader.trim();
        if (normalized) {
          const parsed = Number(normalized);
          if (!Number.isNaN(parsed) && parsed > 0 && parsed <= 120) {
            waitTime = parsed * 1000;
          } else {
            const retryAt = Date.parse(normalized);
            if (!Number.isNaN(retryAt)) {
              const waitMs = retryAt - Date.now();
              if (waitMs > 0 && waitMs <= 120_000) {
                waitTime = waitMs;
              }
            }
          }
        }
      }
      logger.warn(`Rate limit hit, retrying ${method} after ${waitTime}ms`);

      try {
        await waitWithSignal(waitTime, fetchOptions.signal);
      } catch (err) {
        // If the caller aborts during the Retry-After delay, reject with AbortError and do not retry.
        if (err instanceof Error && err.name === 'AbortError') {
          throw err;
        }
        throw err;
      }

      return await fetch(url, {
        ...fetchOptions,
        headers: finalHeaders,
        credentials: 'include',
      });
    }

    return response;
  }

  // Convenience method for JSON requests
  async fetchJSON<T = unknown>(url: string, options: FetchOptions = {}): Promise<T> {
    const response = await this.fetch(url, {
      ...options,
      headers: {
        'Content-Type': 'application/json',
        ...options.headers,
      },
    });

    if (!response.ok) {
      throw await createAPIErrorFromResponse(response);
    }

    const text = await response.text();
    if (!text) return null as T;

    try {
      return JSON.parse(text) as T;
    } catch (_err) {
      logger.error('Failed to parse JSON response', text);
      throw new Error('Invalid JSON response from server');
    }
  }
}

// Create singleton instance
export const apiClient = new ApiClient();

// Export convenience functions
export const apiFetch = (url: string, options?: FetchOptions) => apiClient.fetch(url, options);
export const apiFetchJSON = <T = unknown>(url: string, options?: FetchOptions) =>
  apiClient.fetchJSON<T>(url, options);
export const apiErrorFromResponse = (response: Response, fallbackMessage?: string) =>
  createAPIErrorFromResponse(response, fallbackMessage);
export const setApiToken = (token: string) => apiClient.setApiToken(token);
export const getApiToken = () => apiClient.getApiToken();
export const clearAuth = () => apiClient.clearAuth();
export const clearApiToken = () => apiClient.clearApiToken();
export const hasAuth = () => apiClient.hasAuth();
export const setOrgID = (orgID: string | null) => apiClient.setOrgID(orgID);
export const getOrgID = () => apiClient.getOrgID();