Function parseEnvelopeBody

src/lib/errors.ts:355–444

(raw: unknown, httpStatus?: number, apiUrl?: string)

}

function parseEnvelopeBody(raw: unknown, httpStatus?: number, apiUrl?: string): ErrorEnvelopeBody {
  if (typeof raw !== 'object' || raw === null) {
    const fallbackCode = codeFromHttpStatus(httpStatus);
    return {
      code: fallbackCode,
      message:
        fallbackCode === 'INTERNAL'
          ? 'Server returned a malformed error response.'
          : `Server returned ${httpStatus} without an error envelope.`,
      nextAction:
        fallbackCode === 'INTERNAL'
          ? 'Server error. Retry once; if it persists, report the `requestId` to support@testsprite.com.'
          : '',
      requestId: 'unknown',
      details: {},
    };
  }
  const obj = raw as Record<string, unknown>;

  // Raw Nest/Express 404 shape: `{ message, error: "Not Found", statusCode }`.
  // The current parser was matching `obj.error` (a string) and falling to
  // `Server error.` while losing the actual `message` from the body
  // (e.g. `Cannot POST /api/cli/v1/tests/{id}/runs`). Detect this shape
  // explicitly so the user sees something actionable like
  // "endpoint not deployed" instead of the generic CLI failure text.
  if (typeof obj.error === 'string' && typeof obj.message === 'string') {
    const message = obj.message;
    const cannotMethod = /^Cannot (GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS) /.exec(message);
    const isRouteMissing404 = (httpStatus === 404 || obj.statusCode === 404) && !!cannotMethod;
    return {
      code: codeFromHttpStatus(httpStatus),
      message: isRouteMissing404
        ? `${message} — endpoint not available on the current backend deployment.`
        : message,
      nextAction: isRouteMissing404
        ? 'Verify the CLI is targeting the right environment (check `testsprite auth status` for `env`), and confirm the backend has the corresponding M3.3 piece deployed.'
        : '',
      requestId: 'unknown',
      details: { statusCode: obj.statusCode },
    };
  }

  const errorObj = (obj.error ?? obj) as Record<string, unknown>;
  const rawCode = isErrorCode(errorObj.code) ? errorObj.code : codeFromHttpStatus(httpStatus);
  const message = typeof errorObj.message === 'string' ? errorObj.message : 'Server error.';
  const details =
    typeof errorObj.details === 'object' && errorObj.details !== null
      ? (errorObj.details as Record<string, unknown>)
      : {};
  const nextAction = typeof errorObj.nextAction === 'string' ? errorObj.nextAction : '';
  const requestId = typeof errorObj.requestId === 'string' ? errorObj.requestId : 'unknown';

  // Client-side re-map: RATE_LIMITED with credits signal -> INSUFFICIENT_CREDITS.
  // This makes the code non-retriable and sets exit 12 before the retry
  // decision in http.ts sees it, so BOTH retry and exit-code paths are correct.
  // A nextAction pointing to the billing page is synthesized when the backend
  // didn't supply one (older backend versions).
  if (isInsufficientCredits(rawCode, message, details)) {