fix(debug): log structured HTTP error details instead of raw response

When an HTTP request fails, `debugApiResponse` now logs:

  * endpoint (description) — already was
  * status                 — already was
  * method, url, durationMs — already was
  * sanitized request headers (Authorization/api-keys redacted) — already was

And new fields that make support tickets actionable:

  * requestedAt — ISO-8601 timestamp of request start, for correlating
    with server-side logs.
  * cfRay       — Cloudflare trace id extracted as a top-level field
    from response headers (accepts `cf-ray` or `CF-Ray` casing).
  * responseHeaders — sanitized headers returned by the server.
  * responseBody   — string response body, truncated at 2_000 bytes
    so megabyte payloads don't balloon debug logs.

Wired into both the `queryApiSafeText` and `sendApiRequest` !ok
branches, which are the primary points where a non-thrown HTTP
error reaches a user. The success-path log includes the new
`requestedAt` timestamp too.

Added 5 new tests in `test/unit/utils/debug.test.mts` covering
requestedAt, cfRay (both casings), body passthrough, and body
truncation.

Existing debug-output shape preserved: callers that don't pass the
new fields (`responseHeaders`, `responseBody`, `requestedAt`) see
no change.

Author: jdalton

packages/cli/src/utils/debug.mts

@@ -33,8 +33,20 @@ export type ApiRequestDebugInfo = {
   url?: string | undefined
   headers?: Record<string, string> | undefined
   durationMs?: number | undefined
+  // ISO-8601 timestamp of when the request was initiated. Useful when
+  // correlating failures with server-side logs.
+  requestedAt?: string | undefined
+  // Response headers from the failed request. The helper extracts the
+  // cf-ray trace id as a first-class field so support can look it up in
+  // the Cloudflare dashboard without eyeballing the whole header dump.
+  responseHeaders?: Record<string, string> | undefined
+  // Response body string; truncated by the helper to a safe length so
+  // logs don't balloon on megabyte payloads.
+  responseBody?: string | undefined
 }
 
+const RESPONSE_BODY_TRUNCATE_LENGTH = 2_000
+
 /**
  * Sanitize headers to remove sensitive information.
  * Redacts Authorization and API key headers.
@@ -76,16 +88,70 @@ export function debugApiRequest(
   }
 }
 
+/**
+ * Build the structured debug payload shared by the error + failure-status
+ * branches of `debugApiResponse`. Extracted so both paths log the same
+ * shape.
+ */
+function buildApiDebugDetails(
+  base: Record<string, unknown>,
+  requestInfo?: ApiRequestDebugInfo | undefined,
+): Record<string, unknown> {
+  if (!requestInfo) {
+    return base
+  }
+  const details: Record<string, unknown> = { ...base }
+  if (requestInfo.requestedAt) {
+    details['requestedAt'] = requestInfo.requestedAt
+  }
+  if (requestInfo.method) {
+    details['method'] = requestInfo.method
+  }
+  if (requestInfo.url) {
+    details['url'] = requestInfo.url
+  }
+  if (requestInfo.durationMs !== undefined) {
+    details['durationMs'] = requestInfo.durationMs
+  }
+  if (requestInfo.headers) {
+    details['headers'] = sanitizeHeaders(requestInfo.headers)
+  }
+  if (requestInfo.responseHeaders) {
+    const cfRay =
+      requestInfo.responseHeaders['cf-ray'] ??
+      requestInfo.responseHeaders['CF-Ray']
+    if (cfRay) {
+      // First-class field so it's obvious when filing a support ticket
+      // that points at a Cloudflare trace.
+      details['cfRay'] = cfRay
+    }
+    details['responseHeaders'] = sanitizeHeaders(requestInfo.responseHeaders)
+  }
+  if (requestInfo.responseBody !== undefined) {
+    const body = requestInfo.responseBody
+    details['responseBody'] =
+      body.length > RESPONSE_BODY_TRUNCATE_LENGTH
+        ? `${body.slice(0, RESPONSE_BODY_TRUNCATE_LENGTH)}… (truncated, ${body.length} bytes)`
+        : body
+  }
+  return details
+}
+
 /**
  * Debug an API response with detailed request information.
- * Logs essential info without exposing sensitive data.
  *
- * For failed requests (status >= 400 or error), logs:
- * - HTTP method (GET, POST, etc.)
- * - Full URL
- * - Response status code
- * - Sanitized headers (Authorization redacted)
- * - Request duration in milliseconds
+ * For failed requests (status >= 400 or error), logs a structured
+ * object with:
+ *   - endpoint (human-readable description)
+ *   - requestedAt (ISO timestamp, if passed)
+ *   - method, url, durationMs
+ *   - sanitized request headers (Authorization redacted)
+ *   - cfRay (extracted from response headers if present)
+ *   - sanitized response headers
+ *   - responseBody (truncated)
+ *
+ * All request-headers are sanitized to redact Authorization and
+ * `*api-key*` values.
  */
 export function debugApiResponse(
   endpoint: string,
@@ -94,37 +160,19 @@ export function debugApiResponse(
   requestInfo?: ApiRequestDebugInfo | undefined,
 ): void {
   if (error) {
-    const errorDetails = {
-      __proto__: null,
-      endpoint,
-      error: error instanceof Error ? error.message : UNKNOWN_ERROR,
-      ...(requestInfo?.method ? { method: requestInfo.method } : {}),
-      ...(requestInfo?.url ? { url: requestInfo.url } : {}),
-      ...(requestInfo?.durationMs !== undefined
-        ? { durationMs: requestInfo.durationMs }
-        : {}),
-      ...(requestInfo?.headers
-        ? { headers: sanitizeHeaders(requestInfo.headers) }
-        : {}),
-    }
-    debugDir(errorDetails)
+    debugDir(
+      buildApiDebugDetails(
+        {
+          endpoint,
+          error: error instanceof Error ? error.message : UNKNOWN_ERROR,
+        },
+        requestInfo,
+      ),
+    )
   } else if (status && status >= 400) {
     // For failed requests, log detailed information.
     if (requestInfo) {
-      const failureDetails = {
-        __proto__: null,
-        endpoint,
-        status,
-        ...(requestInfo.method ? { method: requestInfo.method } : {}),
-        ...(requestInfo.url ? { url: requestInfo.url } : {}),
-        ...(requestInfo.durationMs !== undefined
-          ? { durationMs: requestInfo.durationMs }
-          : {}),
-        ...(requestInfo.headers
-          ? { headers: sanitizeHeaders(requestInfo.headers) }
-          : {}),
-      }
-      debugDir(failureDetails)
+      debugDir(buildApiDebugDetails({ endpoint, status }, requestInfo))
     } else {
       debug(`API ${endpoint}: HTTP ${status}`)
     }

packages/cli/src/utils/socket/api.mts

@@ -425,6 +425,7 @@ export async function queryApiSafeText(
   const baseUrl = getDefaultApiBaseUrl()
   const fullUrl = `${baseUrl}${baseUrl?.endsWith('/') ? '' : '/'}${path}`
   const startTime = Date.now()
+  const requestedAt = new Date(startTime).toISOString()
 
   let result: any
   try {
@@ -440,6 +441,7 @@ export async function queryApiSafeText(
       method: 'GET',
       url: fullUrl,
       durationMs,
+      requestedAt,
       headers: { Authorization: '[REDACTED]' },
     })
   } catch (e) {
@@ -455,6 +457,7 @@ export async function queryApiSafeText(
       method: 'GET',
       url: fullUrl,
       durationMs,
+      requestedAt,
       headers: { Authorization: '[REDACTED]' },
     })
 
@@ -472,12 +475,17 @@ export async function queryApiSafeText(
   if (!result.ok) {
     const { status } = result
     const durationMs = Date.now() - startTime
-    // Log detailed error information.
+    // Log detailed error information — include response headers (for
+    // cf-ray) and a truncated body so support tickets have everything
+    // needed to file against Cloudflare or backend teams.
     debugApiResponse(description || 'Query API', status, undefined, {
       method: 'GET',
       url: fullUrl,
       durationMs,
+      requestedAt,
       headers: { Authorization: '[REDACTED]' },
+      responseHeaders: result.headers,
+      responseBody: result.text?.(),
     })
     // Log required permissions for 403 errors when in a command context.
     if (commandPath && status === 403) {
@@ -584,6 +592,7 @@ export async function sendApiRequest<T>(
 
   const fullUrl = `${baseUrl}${baseUrl.endsWith('/') ? '' : '/'}${path}`
   const startTime = Date.now()
+  const requestedAt = new Date(startTime).toISOString()
 
   let result: any
   try {
@@ -611,6 +620,7 @@ export async function sendApiRequest<T>(
         method,
         url: fullUrl,
         durationMs,
+        requestedAt,
         headers: {
           Authorization: '[REDACTED]',
           'Content-Type': 'application/json',
@@ -630,6 +640,7 @@ export async function sendApiRequest<T>(
       method,
       url: fullUrl,
       durationMs,
+      requestedAt,
       headers: {
         Authorization: '[REDACTED]',
         'Content-Type': 'application/json',
@@ -650,15 +661,20 @@ export async function sendApiRequest<T>(
   if (!result.ok) {
     const { status } = result
     const durationMs = Date.now() - startTime
-    // Log detailed error information.
+    // Log detailed error information — include response headers (for
+    // cf-ray) and a truncated body so support tickets have everything
+    // needed to file against Cloudflare or backend teams.
     debugApiResponse(description || 'Send API Request', status, undefined, {
       method,
       url: fullUrl,
       durationMs,
+      requestedAt,
       headers: {
         Authorization: '[REDACTED]',
         'Content-Type': 'application/json',
       },
+      responseHeaders: result.headers,
+      responseBody: result.text?.(),
     })
     // Log required permissions for 403 errors when in a command context.
     if (commandPath && status === 403) {

packages/cli/test/unit/utils/debug.test.mts

@@ -188,6 +188,81 @@ describe('debug utilities', () => {
       expect(calledWith.url).toBeUndefined()
       expect(calledWith.headers).toBeUndefined()
     })
+
+    it('includes requestedAt timestamp when provided', () => {
+      const requestInfo = {
+        method: 'POST',
+        url: 'https://api.socket.dev/x',
+        requestedAt: '2026-04-18T00:00:00.000Z',
+      }
+
+      debugApiResponse('/api/x', 500, undefined, requestInfo)
+
+      const calledWith = mockDebugDir.mock.calls[0]?.[0]
+      expect(calledWith.requestedAt).toBe('2026-04-18T00:00:00.000Z')
+    })
+
+    it('extracts cf-ray as a top-level field and keeps responseHeaders', () => {
+      const requestInfo = {
+        method: 'GET',
+        url: 'https://api.socket.dev/y',
+        responseHeaders: {
+          'cf-ray': 'abc123-IAD',
+          'content-type': 'application/json',
+        },
+      }
+
+      debugApiResponse('/api/y', 500, undefined, requestInfo)
+
+      const calledWith = mockDebugDir.mock.calls[0]?.[0]
+      expect(calledWith.cfRay).toBe('abc123-IAD')
+      expect(calledWith.responseHeaders?.['cf-ray']).toBe('abc123-IAD')
+    })
+
+    it('tolerates CF-Ray header casing', () => {
+      const requestInfo = {
+        method: 'GET',
+        url: 'https://api.socket.dev/z',
+        responseHeaders: {
+          'CF-Ray': 'xyz789-SJC',
+        },
+      }
+
+      debugApiResponse('/api/z', 500, undefined, requestInfo)
+
+      const calledWith = mockDebugDir.mock.calls[0]?.[0]
+      expect(calledWith.cfRay).toBe('xyz789-SJC')
+    })
+
+    it('includes response body on error', () => {
+      const requestInfo = {
+        method: 'GET',
+        url: 'https://api.socket.dev/body',
+        responseBody: '{"error":"bad"}',
+      }
+
+      debugApiResponse('/api/body', 400, undefined, requestInfo)
+
+      const calledWith = mockDebugDir.mock.calls[0]?.[0]
+      expect(calledWith.responseBody).toBe('{"error":"bad"}')
+    })
+
+    it('truncates oversized response bodies', () => {
+      const bigBody = 'x'.repeat(5000)
+      const requestInfo = {
+        method: 'GET',
+        url: 'https://api.socket.dev/big',
+        responseBody: bigBody,
+      }
+
+      debugApiResponse('/api/big', 500, undefined, requestInfo)
+
+      const calledWith = mockDebugDir.mock.calls[0]?.[0]
+      expect(calledWith.responseBody).toMatch(/… \(truncated, 5000 bytes\)$/)
+      expect((calledWith.responseBody as string).length).toBeLessThan(
+        bigBody.length,
+      )
+    })
   })
 
   describe('debugFileOp', () => {