/**
 * REST envelope helpers — unwrap `{ code, msg, data, request_id }` into either
 * a typed `data` or an `EnvelopeError` thrown by the caller.
 *
 * Mirrors `packages/kap-server/src/protocol/envelope.ts` so the server's wire
 * shape and this client's parsing stay in lockstep.
 */
import { type Envelope } from '@moonshot-ai/kap-server/protocol/envelope';
import { ErrorCode } from '@moonshot-ai/kap-server/protocol/error-codes';

/**
 * Thrown when an HTTP call lands but `envelope.code !== 0`.
 *
 * `data` is preserved separately because several server endpoints return
 * non-zero envelopes with a non-null `data` payload (REST §3.6 idempotent
 * re-resolve: `code: 40902 + data: { resolved: false }`).
 */
export class EnvelopeError<T = unknown> extends Error {
  readonly code: number;
  readonly reason: string;
  readonly requestId: string;
  readonly data: T | null;

  constructor(envelope: Envelope<T>) {
    const reason =
      Object.entries(ErrorCode)
        .find(([, value]) => value === envelope.code)?.[0]
        ?.toLowerCase()
        .replaceAll('_', '.') ?? 'unknown';
    super(`server returned code=${envelope.code} (${reason}): ${envelope.msg}`);
    this.name = 'EnvelopeError';
    this.code = envelope.code;
    this.reason = reason;
    this.requestId = envelope.request_id;
    this.data = envelope.data;
  }
}

/**
 * Unwrap a parsed envelope. On `code === 0` returns `data` (which may be
 * `null` — callers asking for a non-nullable type should narrow).
 */
export function unwrap<T>(envelope: Envelope<T>): T {
  if (envelope.code !== 0) throw new EnvelopeError(envelope);
  if (envelope.data === null) {
    // `code: 0 + data: null` is reserved for "no body" success envelopes; the
    // current server surface always returns a non-null data on success, so
    // surface this as a hard error rather than silently returning `null`.
    throw new EnvelopeError({ ...envelope, code: 50001, msg: 'success envelope had null data' });
  }
  return envelope.data;
}