@stainlessdev/docs-xray 0.1.0

package/src/components/XRayTabBadge.tsx

@@ -0,0 +1,219 @@
+import { useState, useEffect, useRef } from 'react';
+import { loadSeenIdsFromStorage, loadPendingCountFromStorage } from '../utils';
+
+type XrayRequestLog = {
+  request_id: string;
+};
+
+const POLL_INTERVAL = 2000;
+
+type FetchResult = {
+  data: XrayRequestLog[];
+  status: 'ok' | 'unauthorized' | 'error';
+};
+
+async function fetchRecentRequests(xrayApi: string): Promise<FetchResult> {
+  try {
+    const response = await fetch(`${xrayApi}/v1/request_logs`, {
+      credentials: 'include',
+    });
+    if (response.status === 401) {
+      return { data: [], status: 'unauthorized' };
+    }
+    if (!response.ok) {
+      return { data: [], status: 'error' };
+    }
+    const json = await response.json();
+    return { data: json.data ?? [], status: 'ok' };
+  } catch {
+    return { data: [], status: 'error' };
+  }
+}
+
+export type XRayTabBadgeProps = {
+  xrayTabLink: string;
+};
+
+export default function XRayTabBadge({ xrayTabLink }: XRayTabBadgeProps) {
+  const [newCount, setNewCount] = useState(0);
+  const [pathname, setPathname] = useState(() =>
+    typeof window !== 'undefined' ? window.location.pathname : ''
+  );
+  const seenIdsRef = useRef<Set<string>>(loadSeenIdsFromStorage());
+  const badgeRef = useRef<HTMLSpanElement | null>(null);
+
+  // Listen for route changes (supports both popstate and Astro's client-side navigation)
+  useEffect(() => {
+    const updatePathname = () => setPathname(window.location.pathname);
+
+    // Standard browser navigation
+    window.addEventListener('popstate', updatePathname);
+    // Astro View Transitions
+    document.addEventListener('astro:page-load', updatePathname);
+    // Also check periodically in case other navigation methods are used
+    const intervalId = setInterval(updatePathname, 500);
+
+    return () => {
+      window.removeEventListener('popstate', updatePathname);
+      document.removeEventListener('astro:page-load', updatePathname);
+      clearInterval(intervalId);
+    };
+  }, []);
+
+  // Check if we're on the X-ray page
+  const normalizedXrayTabLink = xrayTabLink.replace(/\/$/, '');
+  const isOnXrayPage =
+    pathname === normalizedXrayTabLink ||
+    pathname === `${normalizedXrayTabLink}/` ||
+    pathname.startsWith(`${normalizedXrayTabLink}/`);
+
+  // When on X-ray page: read pending count from localStorage (set by XRayPage)
+  // When not on X-ray page: poll API for unseen requests
+  useEffect(() => {
+    if (isOnXrayPage) {
+      // On X-ray page: poll localStorage for pending count (set by XRayPage)
+      const checkPendingCount = () => {
+        const count = loadPendingCountFromStorage();
+        setNewCount(count);
+      };
+
+      checkPendingCount();
+      const intervalId = setInterval(checkPendingCount, 500);
+      return () => clearInterval(intervalId);
+    }
+
+    // Not on X-ray page: reload seen IDs from storage (XRayPage may have updated them)
+    seenIdsRef.current = loadSeenIdsFromStorage();
+
+    // Poll API for unseen requests
+    const xrayApi = window.__XRAY_API__;
+    if (!xrayApi) return;
+
+    let intervalId: ReturnType<typeof setInterval> | null = null;
+    let isUnauthorized = false;
+
+    const poll = async () => {
+      // Skip polling if tab is not visible
+      if (document.visibilityState !== 'visible') {
+        return;
+      }
+
+      const result = await fetchRecentRequests(xrayApi);
+
+      // Stop polling on 401 to avoid console errors
+      if (result.status === 'unauthorized') {
+        isUnauthorized = true;
+        if (intervalId) {
+          clearInterval(intervalId);
+          intervalId = null;
+        }
+        return;
+      }
+
+      // Count requests that haven't been seen yet
+      const unseenCount = result.data.filter(
+        (req) => !seenIdsRef.current.has(req.request_id)
+      ).length;
+
+      setNewCount(unseenCount);
+    };
+
+    // Poll immediately when tab becomes visible
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === 'visible' && !isUnauthorized) {
+        poll();
+      }
+    };
+
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+
+    poll();
+    intervalId = setInterval(poll, POLL_INTERVAL);
+    return () => {
+      if (intervalId) clearInterval(intervalId);
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+    };
+  }, [xrayTabLink, isOnXrayPage]);
+
+  // Find the X-ray tab button in the DOM
+  const findXrayTabButton = (): HTMLElement | null => {
+    // Find by href attribute - works across different header layouts
+    const link = document.querySelector(`a[href="${xrayTabLink}"].stl-ui-button`);
+    return link as HTMLElement | null;
+  };
+
+  // Find and update the X-ray tab badge in the DOM
+  useEffect(() => {
+    const xrayTabButton = findXrayTabButton();
+
+    if (newCount === 0) {
+      // Remove badge if it exists
+      if (badgeRef.current) {
+        badgeRef.current.remove();
+        badgeRef.current = null;
+      }
+      // Also remove any existing badge in DOM
+      if (xrayTabButton) {
+        const existingBadge = xrayTabButton.querySelector('.xray-tab-badge');
+        if (existingBadge) existingBadge.remove();
+      }
+      return;
+    }
+
+    const updateBadge = () => {
+      const xrayTabButton = findXrayTabButton();
+      if (!xrayTabButton) {
+        return false;
+      }
+
+      // Find or create badge
+      let badge = badgeRef.current;
+      if (!badge) {
+        // Check if badge already exists in DOM (from previous mount or inline script)
+        const existingBadge = xrayTabButton.querySelector('.xray-tab-badge');
+        if (existingBadge) {
+          badge = existingBadge as HTMLSpanElement;
+          badgeRef.current = badge;
+        } else {
+          badge = document.createElement('span');
+          badge.className = 'xray-tab-badge';
+          badgeRef.current = badge;
+
+          // Find the span inside the button and append badge after it
+          const labelSpan = xrayTabButton.querySelector('span');
+          if (labelSpan) {
+            labelSpan.insertAdjacentElement('afterend', badge);
+          } else {
+            xrayTabButton.appendChild(badge);
+          }
+        }
+      }
+
+      // Update badge text
+      badge.textContent = newCount > 99 ? '99+' : newCount.toString();
+      return true;
+    };
+
+    // Try immediately
+    if (updateBadge()) return;
+
+    // If not found, retry a few times with increasing delays
+    const retryDelays = [50, 100, 250, 500];
+    let retryIndex = 0;
+
+    const retry = () => {
+      if (retryIndex >= retryDelays.length) return;
+      setTimeout(() => {
+        if (!updateBadge()) {
+          retryIndex++;
+          retry();
+        }
+      }, retryDelays[retryIndex]);
+    };
+
+    retry();
+  }, [newCount, xrayTabLink]);
+
+  // This component doesn't render anything visible - it just manages the badge in the DOM
+  return null;
+}

package/src/components/index.ts

@@ -0,0 +1,5 @@
+export { default as XRayPage } from './XRayPage';
+export type { XRayPageProps } from './XRayPage';
+
+export { default as XRayTabBadge } from './XRayTabBadge';
+export type { XRayTabBadgeProps } from './XRayTabBadge';

package/src/index.ts

@@ -0,0 +1,49 @@
+// Components
+export { XRayPage, XRayTabBadge } from './components';
+export type { XRayPageProps, XRayTabBadgeProps } from './components';
+
+// Note: Astro components are exported separately via '@stainlessdev/docs-xray/astro'
+// to avoid issues with non-Astro contexts (like astro.config.ts)
+
+// Note: Use xrayIntegration from '@stainlessdev/docs-xray/integration' in astro.config.ts
+
+// Types
+export type {
+  XrayRequestLog,
+  XrayRequestLogDetail,
+  SessionUser,
+  FetchResult,
+  EndpointInfo,
+  EndpointMap,
+  ParsedUserAgent,
+  DetailTab,
+} from './types';
+
+// Utilities
+export {
+  parseUserAgent,
+  formatUserAgentSummary,
+  normalizeRouteParams,
+  getEndpointInfo,
+  getStatusText,
+  getStatusClass,
+  formatRelativeTime,
+  formatTime,
+  formatDate,
+  loadSeenIdsFromStorage,
+  saveSeenIdsToStorage,
+  savePendingCountToStorage,
+  loadPendingCountFromStorage,
+} from './utils';
+
+// Spec utilities
+export {
+  walkSpec,
+  generateRoute,
+  buildEndpointMap,
+} from './utils/spec';
+export type {
+  SpecMethod,
+  BuildEndpointMapOptions,
+  BuildEndpointMapResult,
+} from './utils/spec';

package/src/integration.ts

@@ -0,0 +1,53 @@
+import type { AstroIntegration } from 'astro';
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export type XrayIntegrationOptions = {
+  /**
+   * The X-ray API URL. If not provided, X-ray will be disabled.
+   */
+  xrayApi?: string | null;
+};
+
+/**
+ * Astro integration for X-ray badge functionality.
+ *
+ * This integration:
+ * - Injects the X-ray API URL into the page
+ * - Adds the badge script that shows new request counts
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'astro/config';
+ * import { xrayIntegration } from '@stainlessdev/docs-xray/integration';
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     xrayIntegration({ xrayApi: process.env.XRAY_API }),
+ *   ],
+ * });
+ * ```
+ */
+export function xrayIntegration(options: XrayIntegrationOptions = {}): AstroIntegration {
+  const { xrayApi } = options;
+
+  return {
+    name: '@stainlessdev/docs-xray',
+    hooks: {
+      'astro:config:setup': ({ injectScript }) => {
+        if (!xrayApi) return;
+
+        // Inject the API URL
+        injectScript('head-inline', `window.__XRAY_API__ = "${xrayApi}";`);
+
+        // Read and inject the badge script
+        const currentDir = dirname(fileURLToPath(import.meta.url));
+        const badgeScriptPath = join(currentDir, '..', 'public', 'xray-badge.js');
+        const badgeScript = readFileSync(badgeScriptPath, 'utf-8');
+
+        injectScript('head-inline', badgeScript);
+      },
+    },
+  };
+}