api.mts

/**
 * API utilities for Socket CLI.
 * Provides consistent API communication with error handling and permissions management.
 *
 * Key Functions:
 * - getDefaultApiBaseUrl: Get configured API endpoint
 * - getErrorMessageForHttpStatusCode: User-friendly HTTP error messages
 * - handleApiCall: Execute Socket SDK API calls with error handling
 * - handleApiCallNoSpinner: Execute API calls without UI spinner
 * - queryApi: Execute raw API queries with text response
 *
 * Error Handling:
 * - Automatic permission requirement logging for 403 errors
 * - Detailed error messages for common HTTP status codes
 * - Integration with debug helpers for API response logging
 *
 * Configuration:
 * - Respects SOCKET_CLI_API_BASE_URL environment variable
 * - Falls back to configured apiBaseUrl or default API_V0_URL
 */

import { messageWithCauses } from 'pony-cause'

import { debug, debugDir } from '@socketsecurity/lib/debug'
import { getSocketCliApiBaseUrl } from '@socketsecurity/lib/env/socket-cli'
import { httpRequest } from '@socketsecurity/lib/http-request'
import { getDefaultLogger } from '@socketsecurity/lib/logger'
import { getDefaultSpinner } from '@socketsecurity/lib/spinner'
import { isNonEmptyString } from '@socketsecurity/lib/strings'

import { getDefaultApiToken, getExtraCaCerts } from './sdk.mts'

import type { HttpRequestOptions, HttpResponse } from '@socketsecurity/lib/http-request'
import { CONFIG_KEY_API_BASE_URL } from '../../constants/config.mts'
import {
  HTTP_STATUS_BAD_REQUEST,
  HTTP_STATUS_FORBIDDEN,
  HTTP_STATUS_INTERNAL_SERVER_ERROR,
  HTTP_STATUS_NOT_FOUND,
  HTTP_STATUS_TOO_MANY_REQUESTS,
  HTTP_STATUS_UNAUTHORIZED,
} from '../../constants/http.mts'
import {
  API_V0_URL,
  SOCKET_CLI_ISSUES_URL,
  SOCKET_PRICING_URL,
  SOCKET_SETTINGS_API_TOKENS_URL,
  SOCKET_STATUS_URL,
} from '../../constants/socket.mts'
import { getConfigValueOrUndef } from '../config.mts'
import { debugApiResponse } from '../debug.mts'
import {
  getRequirements,
  getRequirementsKey,
} from '../ecosystem/requirements.mts'
import {
  buildErrorCause,
  getNetworkErrorDiagnostics,
} from '../error/errors.mts'

import type { CResult } from '../../types.mts'
import type { Spinner } from '@socketsecurity/lib/spinner'
import type {
  SocketSdkErrorResult,
  SocketSdkOperations,
  SocketSdkSuccessResult,
} from '@socketsecurity/sdk'

const logger = getDefaultLogger()

const NO_ERROR_MESSAGE = 'No error message returned'

// Wraps httpRequest with extra CA certificates from SSL_CERT_FILE.
export async function socketHttpRequest(
  url: string,
  options?: HttpRequestOptions | undefined,
): Promise<HttpResponse> {
  const ca = getExtraCaCerts()
  if (ca) {
    return await httpRequest(url, { ...(options ?? {}), ca })
  }
  return await httpRequest(url, options)
}

export type CommandRequirements = {
  permissions?: string[] | undefined
  quota?: number | undefined
}

/**
 * Get command requirements from requirements.json based on command path.
 */
function getCommandRequirements(
  cmdPath?: string | undefined,
): CommandRequirements | undefined {
  if (!cmdPath) {
    return undefined
  }

  const requirements = getRequirements()
  const key = getRequirementsKey(cmdPath)
  return (requirements.api as any)[key] || undefined
}

/**
 * Log required permissions for a command when encountering 403 errors with actionable guidance.
 *
 * @param cmdPath - Command path to look up requirements for (e.g., "socket fix", "socket scan:create")
 */
export function logPermissionsFor403(cmdPath?: string | undefined): void {
  const requirements = getCommandRequirements(cmdPath)

  logger.error('')
  if (requirements?.permissions?.length) {
    logger.group('🔐 Required API Permissions:')
    for (const permission of requirements.permissions) {
      logger.error(permission)
    }
    logger.groupEnd()
    logger.error('')
    logger.group('💡 To fix this:')
    logger.error(`Visit ${SOCKET_SETTINGS_API_TOKENS_URL}`)
    logger.error('Edit your API token to grant the permissions listed above')
    logger.error('Re-run your command')
    logger.groupEnd()
  } else {
    // No specific permissions found, provide general guidance.
    logger.group('🔐 Permission Requirements:')
    logger.error(
      'Your API token lacks the required permissions for this operation.',
    )
    logger.groupEnd()
    logger.error('')
    logger.group('💡 To fix this:')
    logger.error(`Visit ${SOCKET_SETTINGS_API_TOKENS_URL}`)
    logger.error('Check your API token has the necessary permissions')
    logger.error(
      `Run \`socket ${cmdPath?.replace(/^socket[: ]/, '') || 'help'} --help\` to see required permissions`,
    )
    logger.error('Re-run your command after updating permissions')
    logger.groupEnd()
  }
  logger.error('')
}

// The Socket API server that should be used for operations.
export function getDefaultApiBaseUrl(): string | undefined {
  const baseUrl =
    getSocketCliApiBaseUrl() || getConfigValueOrUndef(CONFIG_KEY_API_BASE_URL)
  if (isNonEmptyString(baseUrl)) {
    return baseUrl
  }
  return API_V0_URL
}

/**
 * Get user-friendly error message for HTTP status codes with actionable guidance.
 */
export async function getErrorMessageForHttpStatusCode(code: number) {
  if (code === HTTP_STATUS_BAD_REQUEST) {
    return (
      '❌ Invalid request: One of the options or parameters may be incorrect.\n' +
      '💡 Try: Check your command syntax and parameter values.'
    )
  }
  if (code === HTTP_STATUS_UNAUTHORIZED) {
    return (
      '❌ Authentication failed: Your Socket API token appears to be invalid, expired, or revoked.\n' +
      '💡 Try:\n' +
      '  • Run `socket whoami` to verify your current token\n' +
      '  • Run `socket login` to re-authenticate\n' +
      `  • Manage tokens at ${SOCKET_SETTINGS_API_TOKENS_URL}`
    )
  }
  if (code === HTTP_STATUS_FORBIDDEN) {
    return (
      '❌ Access denied: Your API token lacks required permissions or organization access.\n' +
      '💡 Try:\n' +
      '  • Run `socket whoami` to verify your account and organization\n' +
      `  • Check your API token permissions at ${SOCKET_SETTINGS_API_TOKENS_URL}\n` +
      "  • Ensure you're accessing the correct organization with `--org` flag\n" +
      `  • Verify your plan includes this feature at ${SOCKET_PRICING_URL}`
    )
  }
  if (code === HTTP_STATUS_NOT_FOUND) {
    return (
      "❌ Not found: The requested endpoint or resource doesn't exist.\n" +
      '💡 Try:\n' +
      '  • Verify resource names (package, repository, organization)\n' +
      '  • Check if the resource was deleted or moved\n' +
      '  • Update to the latest CLI version: `socket self-update` (SEA) or `npm update -g socket`\n' +
      `  • Report persistent issues at ${SOCKET_CLI_ISSUES_URL}`
    )
  }
  if (code === HTTP_STATUS_TOO_MANY_REQUESTS) {
    return (
      '❌ Rate limit exceeded: Too many API requests.\n' +
      '💡 Try:\n' +
      `  • Free plan: Wait a few minutes for quota reset or upgrade at ${SOCKET_PRICING_URL}\n` +
      '  • Paid plan: Contact support if rate limits seem incorrect\n' +
      '  • Check current quota: `socket organization quota`\n' +
      '  • Reduce request frequency or batch operations'
    )
  }
  if (code === HTTP_STATUS_INTERNAL_SERVER_ERROR) {
    return (
      '❌ Server error: Socket API encountered an internal problem (HTTP 500).\n' +
      '💡 Try:\n' +
      '  • Wait a few minutes and retry your command\n' +
      `  • Check Socket status: ${SOCKET_STATUS_URL}\n` +
      `  • Report persistent issues: ${SOCKET_CLI_ISSUES_URL}`
    )
  }
  return (
    `❌ HTTP ${code}: Server responded with unexpected status code.\n` +
    `💡 Try: Check Socket status at ${SOCKET_STATUS_URL} or report the issue.`
  )
}

export type HandleApiCallOptions = {
  description?: string | undefined
  spinner?: Spinner | undefined
  commandPath?: string | undefined
}

export type ApiCallResult<T extends SocketSdkOperations> = CResult<
  SocketSdkSuccessResult<T>['data']
>

/**
 * Handle Socket SDK API calls with error handling and permission logging.
 */
export async function handleApiCall<T extends SocketSdkOperations>(
  value: Promise<any>,
  options?: HandleApiCallOptions | undefined,
): Promise<ApiCallResult<T>> {
  const { commandPath, description, spinner } = {
    __proto__: null,
    ...options,
  } as HandleApiCallOptions

  if (description) {
    spinner?.start(`Requesting ${description} from API...`)
  } else {
    spinner?.start()
  }

  let sdkResult: any
  try {
    sdkResult = await value
    spinner?.stop()
    // Only log success messages if a spinner was provided (opt-in to output).
    if (description && spinner) {
      const message = `Received Socket API response (after requesting ${description}).`
      if (sdkResult.success) {
        logger.success(message)
      } else {
        logger.info(message)
      }
    }
  } catch (e) {
    spinner?.stop()
    const socketSdkErrorResult: ApiCallResult<T> = {
      ok: false,
      message: 'Socket API error',
      cause: messageWithCauses(e as Error),
    }
    if (description) {
      logger.fail(`An error was thrown while requesting ${description}`)
      debugApiResponse(description, undefined, e)
    } else {
      debugApiResponse('Socket API', undefined, e)
    }
    debugDir({ socketSdkErrorResult })
    return socketSdkErrorResult
  }

  // Note: TS can't narrow down the type of result due to generics.
  if (sdkResult.success === false) {
    const endpoint = description || 'Socket API'
    debugApiResponse(endpoint, sdkResult.status as number)
    debugDir({ sdkResult })

    const errCResult = sdkResult as SocketSdkErrorResult<T>
    const errStr = errCResult.error ? String(errCResult.error).trim() : ''
    const message = errStr || NO_ERROR_MESSAGE
    const reason = errCResult.cause || NO_ERROR_MESSAGE

    const cause = await buildErrorCause(
      sdkResult.status as number,
      message,
      reason,
    )

    const causeWithEndpoint = description
      ? `${cause} (endpoint: ${description})`
      : cause

    const socketSdkErrorResult: ApiCallResult<T> = {
      ok: false,
      message: 'Socket API error',
      cause: causeWithEndpoint,
      data: {
        code: sdkResult.status,
      },
    }

    // Log required permissions for 403 errors when in a command context.
    if (commandPath && sdkResult.status === 403) {
      logPermissionsFor403(commandPath)
    }

    return socketSdkErrorResult
  }
  const socketSdkSuccessResult: ApiCallResult<T> = {
    ok: true,
    data: (sdkResult as SocketSdkSuccessResult<T>).data,
  }
  return socketSdkSuccessResult
}

export async function handleApiCallNoSpinner<T extends SocketSdkOperations>(
  value: Promise<any>,
  description: string,
): Promise<CResult<SocketSdkSuccessResult<T>['data']>> {
  let sdkResult: any
  try {
    sdkResult = await value
  } catch (e) {
    debug(`API request failed: ${description}`)
    debugDir(e)

    const errStr = e ? String(e).trim() : ''
    const message = 'Socket API error'
    const rawCause = errStr || NO_ERROR_MESSAGE
    const cause = message !== rawCause ? rawCause : ''

    return {
      ok: false,
      message,
      ...(cause ? { cause } : {}),
    }
  }

  // Note: TS can't narrow down the type of result due to generics
  if (sdkResult.success === false) {
    debug(`fail: ${description} bad response`)
    debugDir({ sdkResult })

    const sdkErrorResult = sdkResult as SocketSdkErrorResult<T>
    const errStr = sdkErrorResult.error
      ? String(sdkErrorResult.error).trim()
      : ''
    const message = errStr || NO_ERROR_MESSAGE
    const reason = sdkErrorResult.cause || NO_ERROR_MESSAGE

    const cause = await buildErrorCause(
      sdkResult.status as number,
      message,
      reason,
    )

    const causeWithEndpoint = description
      ? `${cause} (endpoint: ${description})`
      : cause

    return {
      ok: false,
      message: 'Socket API error',
      cause: causeWithEndpoint,
      data: {
        code: sdkResult.status,
      },
    }
  }
  const sdkSuccessResult = sdkResult as SocketSdkSuccessResult<T>
  return {
    ok: true,
    data: sdkSuccessResult.data,
  }
}

export async function queryApi(path: string, apiToken: string) {
  const baseUrl = getDefaultApiBaseUrl()
  if (!baseUrl) {
    throw new Error('Socket API base URL is not configured.')
  }

  return await socketHttpRequest(
    `${baseUrl}${baseUrl.endsWith('/') ? '' : '/'}${path}`,
    {
      method: 'GET',
      headers: {
        Authorization: `Basic ${btoa(`${apiToken}:`)}`,
      },
      timeout: 30_000,
    },
  )
}

/**
 * Query Socket API endpoint and return text response with error handling.
 */
export async function queryApiSafeText(
  path: string,
  description?: string | undefined,
  commandPath?: string | undefined,
): Promise<CResult<string>> {
  const apiToken = getDefaultApiToken()
  if (!apiToken) {
    return {
      ok: false,
      message: 'Authentication Error',
      cause:
        'User must be authenticated to run this command. Run `socket login` and enter your Socket API token.',
    }
  }

  const spinner = getDefaultSpinner()

  if (description) {
    spinner?.start(`Requesting ${description} from API...`)
  }

  const baseUrl = getDefaultApiBaseUrl()
  const fullUrl = `${baseUrl}${baseUrl?.endsWith('/') ? '' : '/'}${path}`
  const startTime = Date.now()
  const requestedAt = new Date(startTime).toISOString()

  let result: any
  try {
    result = await queryApi(path, apiToken)
    const durationMs = Date.now() - startTime
    if (description) {
      spinner?.successAndStop(
        `Received Socket API response (after requesting ${description}).`,
      )
    }
    // Log success for debugging.
    debugApiResponse(description || 'Query API', result.status, undefined, {
      method: 'GET',
      url: fullUrl,
      durationMs,
      requestedAt,
      headers: { Authorization: '[REDACTED]' },
    })
  } catch (e) {
    const durationMs = Date.now() - startTime
    if (description) {
      spinner?.failAndStop(
        `An error was thrown while requesting ${description}.`,
      )
    }

    debug('Query API request failed')
    debugApiResponse(description || 'Query API', undefined, e, {
      method: 'GET',
      url: fullUrl,
      durationMs,
      requestedAt,
      headers: { Authorization: '[REDACTED]' },
    })

    // Provide detailed network diagnostics for fetch errors.
    const networkDiagnostics = getNetworkErrorDiagnostics(e, durationMs)
    const message = 'API request failed'

    return {
      ok: false,
      message,
      cause: `${networkDiagnostics} (path: ${path})`,
    }
  }

  if (!result.ok) {
    const { status } = result
    const durationMs = Date.now() - startTime
    // 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) {
      logPermissionsFor403(commandPath)
    }
    return {
      ok: false,
      message: 'Socket API error',
      cause: `${result.statusText} (reason: ${await getErrorMessageForHttpStatusCode(status)}) (path: ${path})`,
      data: {
        code: status,
      },
    }
  }

  try {
    const data = result.text()
    return {
      ok: true,
      data,
    }
  } catch (e) {
    debug('Failed to read API response text')
    debugDir(e)

    return {
      ok: false,
      message: 'API request failed',
      cause: `Unexpected error reading response text (path: ${path})`,
    }
  }
}

/**
 * Query Socket API endpoint and return parsed JSON response.
 */
export async function queryApiSafeJson<T>(
  path: string,
  description = '',
): Promise<CResult<T>> {
  const result = await queryApiSafeText(path, description)

  if (!result.ok) {
    return result
  }

  try {
    return {
      ok: true,
      data: JSON.parse(result.data) as T,
    }
  } catch (_e) {
    return {
      ok: false,
      message: 'Server returned invalid JSON',
      cause: `Please report this. JSON.parse threw an error over the following response: \`${(result.data?.slice?.(0, 100) || '').trim() + (result.data?.length > 100 ? '…' : '')}\``,
    }
  }
}

export type SendApiRequestOptions = {
  method: 'POST' | 'PUT'
  body?: unknown | undefined
  description?: string | undefined
  commandPath?: string | undefined
}

/**
 * Send POST/PUT request to Socket API with JSON response handling.
 */
export async function sendApiRequest<T>(
  path: string,
  options?: SendApiRequestOptions | undefined,
): Promise<CResult<T>> {
  const apiToken = getDefaultApiToken()
  if (!apiToken) {
    return {
      ok: false,
      message: 'Authentication Error',
      cause:
        'User must be authenticated to run this command. To log in, run the command `socket login` and enter your Socket API token.',
    }
  }

  const baseUrl = getDefaultApiBaseUrl()
  if (!baseUrl) {
    return {
      ok: false,
      message: 'Configuration Error',
      cause:
        'Socket API endpoint is not configured. Please check your environment configuration.',
    }
  }

  const { body, commandPath, description, method } = {
    __proto__: null,
    ...options,
  } as SendApiRequestOptions
  const spinner = getDefaultSpinner()

  if (description) {
    spinner?.start(`Requesting ${description} from API...`)
  }

  const fullUrl = `${baseUrl}${baseUrl.endsWith('/') ? '' : '/'}${path}`
  const startTime = Date.now()
  const requestedAt = new Date(startTime).toISOString()

  let result: any
  try {
    result = await socketHttpRequest(fullUrl, {
      body: body ? JSON.stringify(body) : undefined,
      headers: {
        Authorization: `Basic ${btoa(`${apiToken}:`)}`,
        'Content-Type': 'application/json',
      },
      method,
      timeout: 60_000,
    })
    const durationMs = Date.now() - startTime
    if (description) {
      spinner?.successAndStop(
        `Received Socket API response (after requesting ${description}).`,
      )
    }
    // Log success for debugging.
    debugApiResponse(
      description || 'Send API Request',
      result.status,
      undefined,
      {
        method,
        url: fullUrl,
        durationMs,
        requestedAt,
        headers: {
          Authorization: '[REDACTED]',
          'Content-Type': 'application/json',
        },
      },
    )
  } catch (e) {
    const durationMs = Date.now() - startTime
    if (description) {
      spinner?.failAndStop(
        `An error was thrown while requesting ${description}.`,
      )
    }

    debug(`API ${method} request failed`)
    debugApiResponse(description || 'Send API Request', undefined, e, {
      method,
      url: fullUrl,
      durationMs,
      requestedAt,
      headers: {
        Authorization: '[REDACTED]',
        'Content-Type': 'application/json',
      },
    })

    // Provide detailed network diagnostics for fetch errors.
    const networkDiagnostics = getNetworkErrorDiagnostics(e, durationMs)
    const message = 'API request failed'

    return {
      ok: false,
      message,
      cause: `${networkDiagnostics} (path: ${path})`,
    }
  }

  if (!result.ok) {
    const { status } = result
    const durationMs = Date.now() - startTime
    // 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) {
      logPermissionsFor403(commandPath)
    }
    return {
      ok: false,
      message: 'Socket API error',
      cause: `${result.statusText} (reason: ${await getErrorMessageForHttpStatusCode(status)}) (path: ${path})`,
      data: {
        code: status,
      },
    }
  }

  try {
    const data = result.json()
    return {
      ok: true,
      data: data as T,
    }
  } catch (e) {
    debug('Failed to parse API response JSON')
    debugDir(e)
    return {
      ok: false,
      message: 'API request failed',
      cause: `Unexpected error parsing response JSON (path: ${path})`,
    }
  }
}