import {
    defineCodes,
    SuaveplanError,
    type SuaveplanErrorOptions,
} from "@suaveplan/error";

/**
 * Stable error-code registry for `@suaveplan/telegram-client`.
 *
 * All codes are namespaced under `TELEGRAM_CLIENT` and registered via
 * `defineCodes`, producing deterministic literal-typed string identifiers
 * that survive tree-shaking and minification.
 *
 * Every code MUST be thrown by at least one production code path; see the
 * `error code registry` requirement in
 * `openspec/specs/telegram-client/spec.md`.
 */
export const TELEGRAM_CLIENT_CODES = defineCodes("TELEGRAM_CLIENT", [
    "API_ERROR",
    "AUTH_ERROR",
    "RATE_LIMITED",
    "CHAT_NOT_FOUND",
    "BOT_BLOCKED",
    "CONFIG_MISSING",
    "TIMEOUT",
    "FORBIDDEN",
] as const);

/** Literal union of every error code emitted by this package. */
export type TelegramClientCode =
    (typeof TELEGRAM_CLIENT_CODES)[keyof typeof TELEGRAM_CLIENT_CODES];

/**
 * Typed error class for all `@suaveplan/telegram-client` failures.
 *
 * Extends `SuaveplanError` so callers can use `instanceof TelegramClientError`
 * for narrow discrimination while the full error chain, context, redaction,
 * and OTel span-event adapter remain available through the base class.
 *
 * @example
 * ```ts
 * import {
 *   TelegramClientError,
 *   TELEGRAM_CLIENT_CODES,
 * } from "@suaveplan/telegram-client/errors";
 *
 * throw new TelegramClientError(
 *   TELEGRAM_CLIENT_CODES.RATE_LIMITED,
 *   "Telegram rate limit exceeded",
 *   { context: { retryAfterMs: 30000 } },
 * );
 * ```
 */
export class TelegramClientError extends SuaveplanError<TelegramClientCode> {
    public constructor(
        code: TelegramClientCode,
        messageKey: string,
        options?: SuaveplanErrorOptions
    ) {
        super(code, messageKey, options);
        this.name = "TelegramClientError";
    }
}