Initial Commit

packages/communication/messaging/telegram-client/src/errors/telegram-client-error.ts

@@ -0,0 +1,63 @@
+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";
+    }
+}