@stainlessdev/docs-xray 0.1.0

package/src/types.ts

@@ -0,0 +1,56 @@
+export type XrayRequestLog = {
+  request_id: string;
+  request_method: string;
+  request_path: string;
+  request_route: string;
+  response_status_code: number;
+  timestamp: string;
+  service: string;
+};
+
+export type XrayRequestLogDetail = XrayRequestLog & {
+  duration_us: number;
+  ip: string | null;
+  request_body: string;
+  request_body_encoding: string;
+  request_body_truncated: boolean | null;
+  request_headers: Record<string, string[]> | null;
+  response_body: string;
+  response_body_encoding: string;
+  response_body_truncated: boolean | null;
+  response_headers: Record<string, string[]> | null;
+  user_id: string | null;
+};
+
+export type SessionUser = {
+  user: {
+    name: string;
+    ip: string;
+  };
+};
+
+export type FetchResult<T> = {
+  data: T;
+  status: 'ok' | 'unauthorized' | 'error';
+};
+
+export type EndpointInfo = { title: string; href: string };
+export type EndpointMap = Record<string, EndpointInfo>;
+
+export type ParsedUserAgent = {
+  type: 'curl' | 'sdk' | 'browser' | 'unknown';
+  name: string;
+  version?: string;
+  language?: string;
+};
+
+export type DetailTab = 'response' | 'request';
+
+declare global {
+  interface Window {
+    __XRAY_API__?: string;
+    __XRAY_TAB_LINK__?: string;
+    __XRAY_ENDPOINT_MAP__?: EndpointMap;
+    __XRAY_SERVER_BASE_PATHS__?: string[];
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,218 @@
+import type { ParsedUserAgent, EndpointInfo, EndpointMap } from '../types';
+
+export function parseUserAgent(ua: string | undefined | null): ParsedUserAgent {
+  if (!ua || typeof ua !== 'string') return { type: 'unknown', name: 'Unknown' };
+
+  if (ua.toLowerCase().includes('curl')) {
+    const match = ua.match(/curl\/([\d.]+)/i);
+    return { type: 'curl', name: 'curl', version: match?.[1] };
+  }
+
+  const sdkPatterns: { pattern: RegExp; language: string }[] = [
+    { pattern: /(\w+)\/JS\s+([\d.]+)/i, language: 'TypeScript' },
+    { pattern: /(\w+)\/Python\s+([\d.]+)/i, language: 'Python' },
+    { pattern: /(\w+)\/Go\s+([\d.]+)/i, language: 'Go' },
+    { pattern: /(\w+)\/Java\s+([\d.]+)/i, language: 'Java' },
+    { pattern: /(\w+)\/Kotlin\s+([\d.]+)/i, language: 'Kotlin' },
+    { pattern: /(\w+)\/Ruby\s+([\d.]+)/i, language: 'Ruby' },
+    { pattern: /(\w+)\/CSharp\s+([\d.]+)/i, language: 'C#' },
+    { pattern: /(\w+)\/PHP\s+([\d.]+)/i, language: 'PHP' },
+  ];
+
+  for (const { pattern, language } of sdkPatterns) {
+    const match = ua.match(pattern);
+    if (match) {
+      return { type: 'sdk', name: match[1], version: match[2], language };
+    }
+  }
+
+  if (ua.includes('Chrome') && !ua.includes('Edg')) {
+    const match = ua.match(/Chrome\/([\d.]+)/);
+    return { type: 'browser', name: 'Chrome', version: match?.[1] };
+  }
+  if (ua.includes('Firefox')) {
+    const match = ua.match(/Firefox\/([\d.]+)/);
+    return { type: 'browser', name: 'Firefox', version: match?.[1] };
+  }
+  if (ua.includes('Safari') && !ua.includes('Chrome')) {
+    const match = ua.match(/Version\/([\d.]+)/);
+    return { type: 'browser', name: 'Safari', version: match?.[1] };
+  }
+  if (ua.includes('Edg')) {
+    const match = ua.match(/Edg\/([\d.]+)/);
+    return { type: 'browser', name: 'Edge', version: match?.[1] };
+  }
+
+  return { type: 'unknown', name: 'Unknown' };
+}
+
+export function formatUserAgentSummary(parsed: ParsedUserAgent): string {
+  if (parsed.type === 'sdk' && parsed.language) {
+    return `${parsed.language} SDK${parsed.version ? ` v${parsed.version}` : ''}`;
+  }
+  if (parsed.version) {
+    return `${parsed.name} ${parsed.version}`;
+  }
+  return parsed.name;
+}
+
+export function normalizeRouteParams(route: string): string {
+  return route.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, '{$1}');
+}
+
+export function getEndpointInfo(
+  method: string,
+  route: string | null,
+  endpointMap: EndpointMap | undefined,
+  serverBasePaths: string[] | undefined,
+): EndpointInfo | null {
+  if (!endpointMap || !route) return null;
+
+  const normalizedRoute = normalizeRouteParams(route);
+  const lowerMethod = method.toLowerCase();
+
+  const exactKey = `${lowerMethod} ${normalizedRoute}`;
+  if (endpointMap[exactKey]) {
+    return endpointMap[exactKey];
+  }
+
+  if (serverBasePaths) {
+    for (const basePath of serverBasePaths) {
+      if (normalizedRoute.startsWith(basePath)) {
+        const withoutPrefix = normalizedRoute.slice(basePath.length) || '/';
+        const withoutPrefixKey = `${lowerMethod} ${withoutPrefix}`;
+        if (endpointMap[withoutPrefixKey]) {
+          return endpointMap[withoutPrefixKey];
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+export function getStatusText(code: number): string {
+  const statusTexts: Record<number, string> = {
+    200: 'OK',
+    201: 'Created',
+    202: 'Accepted',
+    204: 'No Content',
+    206: 'Partial Content',
+    301: 'Moved Permanently',
+    302: 'Found',
+    303: 'See Other',
+    304: 'Not Modified',
+    307: 'Temporary Redirect',
+    308: 'Permanent Redirect',
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    405: 'Method Not Allowed',
+    408: 'Request Timeout',
+    409: 'Conflict',
+    410: 'Gone',
+    413: 'Payload Too Large',
+    415: 'Unsupported Media Type',
+    422: 'Unprocessable Entity',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    501: 'Not Implemented',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout',
+  };
+  return statusTexts[code] || '';
+}
+
+export function formatRelativeTime(timestamp: string): string {
+  const date = new Date(timestamp);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffSec = Math.floor(diffMs / 1000);
+  const diffMin = Math.floor(diffSec / 60);
+  const diffHour = Math.floor(diffMin / 60);
+
+  if (diffSec < 10) return 'just now';
+  if (diffSec < 60) return `${diffSec}s ago`;
+  if (diffMin < 60) return `${diffMin}m ago`;
+  if (diffHour < 24) return `${diffHour}h ago`;
+
+  return date.toLocaleDateString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+export function formatTime(timestamp: string): string {
+  const date = new Date(timestamp);
+  return date.toLocaleTimeString('en-US', {
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+}
+
+export function formatDate(timestamp: string): string {
+  const date = new Date(timestamp);
+  return date.toLocaleDateString('en-US', {
+    month: 'short',
+    day: 'numeric',
+  });
+}
+
+export function getStatusClass(status: number): string {
+  if (status >= 500) return 'xray-page__status--error';
+  if (status >= 400) return 'xray-page__status--warning';
+  return 'xray-page__status--success';
+}
+
+// Storage utilities
+const STORAGE_KEY = 'xray-badge-data';
+const PENDING_COUNT_KEY = 'xray-pending-count';
+
+export function loadSeenIdsFromStorage(): Set<string> {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored) {
+      const data = JSON.parse(stored);
+      if (Array.isArray(data.seenIds)) {
+        return new Set(data.seenIds);
+      }
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return new Set();
+}
+
+export function saveSeenIdsToStorage(seenIds: Set<string>): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify({ seenIds: Array.from(seenIds) }));
+  } catch {
+    // Ignore storage errors
+  }
+}
+
+export function savePendingCountToStorage(count: number): void {
+  try {
+    localStorage.setItem(PENDING_COUNT_KEY, JSON.stringify({ count }));
+  } catch {
+    // Ignore storage errors
+  }
+}
+
+export function loadPendingCountFromStorage(): number {
+  try {
+    const stored = localStorage.getItem(PENDING_COUNT_KEY);
+    if (stored) {
+      const data = JSON.parse(stored);
+      return data.count ?? 0;
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return 0;
+}

package/src/utils/spec.ts

@@ -0,0 +1,120 @@
+import type { EndpointMap } from '../types';
+
+export type SpecMethod = {
+  endpoint: string;
+  title: string;
+  stainlessPath: string;
+};
+
+/**
+ * Walk a Stainless spec tree and extract all HTTP methods.
+ */
+export function* walkSpec(spec: any): Generator<SpecMethod> {
+  function* walkResource(resource: any, parentPath: string): Generator<SpecMethod> {
+    const resourcePath = parentPath ? `${parentPath}.${resource.name}` : resource.name;
+    const stainlessResourcePath = `(resource) ${resourcePath}`;
+
+    // Yield methods
+    if (resource.methods) {
+      for (const method of Object.values(resource.methods) as any[]) {
+        yield {
+          endpoint: method.endpoint,
+          title: method.summary || method.title || method.name,
+          stainlessPath: `${stainlessResourcePath} > (method) ${method.name}`,
+        };
+      }
+    }
+
+    // Recurse into subresources
+    if (resource.subresources) {
+      for (const subresource of Object.values(resource.subresources) as any[]) {
+        yield* walkResource(subresource, resourcePath);
+      }
+    }
+  }
+
+  if (spec.resources) {
+    for (const resource of Object.values(spec.resources) as any[]) {
+      yield* walkResource(resource, '');
+    }
+  }
+}
+
+/**
+ * Generate a documentation route from a Stainless path.
+ *
+ * @param basePath - The base path for the docs (e.g., '/')
+ * @param stainlessPath - A path like "(resource) pets > (method) list"
+ * @returns The documentation href or null if the path couldn't be parsed
+ */
+export function generateRoute(basePath: string, stainlessPath: string): string | null {
+  // Parse stainless path like "(resource) pets > (method) list"
+  const match = stainlessPath.match(/\(resource\) ([^\s>]+)( > \(method\) ([^\s]+))?/);
+  if (!match) return null;
+
+  const resourceParts = match[1].split('.');
+  const method = match[3];
+
+  const path = [basePath.endsWith('/') ? basePath.slice(0, -1) : basePath];
+  path.push('resources', ...resourceParts.flatMap((part, i) => i > 0 ? ['subresources', part] : [part]));
+  if (method) path.push('methods', method);
+
+  return path.join('/');
+}
+
+export type BuildEndpointMapOptions = {
+  /** The CMS port to fetch the spec from */
+  cmsPort: number | string;
+  /** The base path for documentation links */
+  basePath: string;
+  /** Default server base paths if not returned by the CMS */
+  defaultServerBasePaths?: string[];
+};
+
+export type BuildEndpointMapResult = {
+  endpointMap: EndpointMap;
+  serverBasePaths: string[];
+};
+
+/**
+ * Fetch the spec from the CMS and build an endpoint map for matching
+ * X-ray requests to documentation links.
+ */
+export async function buildEndpointMap(
+  options: BuildEndpointMapOptions
+): Promise<BuildEndpointMapResult> {
+  const { cmsPort, basePath, defaultServerBasePaths = ['/api/v3'] } = options;
+
+  const endpointMap: EndpointMap = {};
+  let serverBasePaths: string[] = [];
+
+  try {
+    const response = await fetch(`http://localhost:${cmsPort}/retrieve_spec`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    const specResp = await response.json();
+
+    if (specResp.data) {
+      // Server base paths are needed to match X-ray routes (e.g., /api/v3/pet)
+      // to spec endpoints (e.g., /pet). The CMS should return these from the
+      // OpenAPI spec's servers field, but currently doesn't pass them through.
+      serverBasePaths = specResp.servers ?? defaultServerBasePaths;
+
+      for (const method of walkSpec(specResp.data)) {
+        const href = generateRoute(basePath, method.stainlessPath);
+        if (href) {
+          endpointMap[method.endpoint] = {
+            title: method.title,
+            href,
+          };
+        }
+      }
+    }
+  } catch {
+    // Spec not available
+  }
+
+  return { endpointMap, serverBasePaths };
+}