@galhardoalex/telegram-logger 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Galhardo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,204 @@
-# Temporary Holding Version
+# telegram-logger
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![JSR](https://jsr.io/badges/@galhardoalex/telegram-logger)](https://jsr.io/@galhardoalex/telegram-logger)
+[![JSR Score](https://jsr.io/badges/@galhardoalex/telegram-logger/score)](https://jsr.io/@galhardoalex/telegram-logger)
+[![npm](https://img.shields.io/npm/v/@galhardoalex/telegram-logger)](https://www.npmjs.com/package/@galhardoalex/telegram-logger)
+[![CI](https://github.com/AlexGalhardo/telegram-logger/actions/workflows/ci.yml/badge.svg)](https://github.com/AlexGalhardo/telegram-logger/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Send errors, warnings, events and contact-form submissions to your **Telegram** chats and channels.
+
+- **Zero dependencies**: uses the native `fetch`.
+- **Runs anywhere**: Node.js 18+, Bun, Deno, Next.js (Node and Edge), Cloudflare Workers.
+- **Never throws**: a failed delivery never crashes your app or your `catch` block.
+- **Fully typed**: written in TypeScript, ships ESM, CommonJS and type declarations.
+- **Readable messages**: emoji levels, app name, environment, metadata, stack traces and causes.
+- **Safe**: user content is HTML-escaped and every message is kept under Telegram's 4096-character limit.
+
+```text
+🔴 ERROR · my-site · production
+TypeError: Cannot read properties of undefined (reading 'id')
+
+route: /api/checkout
+userId: 42
+
+at POST (app/api/checkout/route.ts:12:20)
+...
+🕒 2026-10-15T14:40:00.000Z
+```
+
+## Install
+
+**npm**
+
+```bash
+npm install @galhardoalex/telegram-logger
+```
+
+**pnpm**
+
+```bash
+pnpm add @galhardoalex/telegram-logger
+```
+
+**yarn**
+
+```bash
+yarn add @galhardoalex/telegram-logger
+```
+
+**bun**
+
+```bash
+bun add @galhardoalex/telegram-logger
+```
+
+**deno**
+
+```bash
+deno add jsr:@galhardoalex/telegram-logger
+```
+
+**From JSR, with any package manager**
+
+```bash
+npx jsr add @galhardoalex/telegram-logger
+```
+
+## Get a bot token and a chat id
+
+1. Open [@BotFather](https://t.me/BotFather), send `/newbot`, and copy the **token**.
+2. Add the bot to your channel or group. In a channel, make it an **admin** so it can post.
+3. Send any message in that chat, then open `https://api.telegram.org/bot<TOKEN>/getUpdates` and copy `chat.id`.
+   Channel and supergroup ids start with `-100`.
+4. Put both values in your environment:
+
+```bash
+TELEGRAM_BOT_TOKEN=123456789:AAH...
+TELEGRAM_CHAT_ID=-1001234567890
+```
+
+> ⚠️ Keep the token on the **server**. Never expose it to the browser (no `NEXT_PUBLIC_` prefix).
+
+## Usage
+
+```ts
+import { createTelegramLogger } from "@galhardoalex/telegram-logger";
+
+export const logger = createTelegramLogger({
+  botToken: process.env.TELEGRAM_BOT_TOKEN, // optional: falls back to TELEGRAM_BOT_TOKEN
+  chatId: process.env.TELEGRAM_CHAT_ID, // optional: falls back to TELEGRAM_CHAT_ID
+  appName: "my-site",
+  environment: process.env.NODE_ENV,
+});
+
+// Errors: pass whatever you caught. Error objects include their stack and cause.
+try {
+  await chargeCustomer();
+} catch (err) {
+  await logger.error(err, { route: "/api/checkout", userId: 42 });
+}
+
+// Other levels
+await logger.debug("Cache miss", { key: "home" });
+await logger.info("Cron job finished", { durationMs: 1234 });
+await logger.success("New subscription 🎉", { plan: "pro" });
+await logger.warn("404 Not Found", { path: "/old-page" });
+await logger.fatal(new Error("Database unreachable"));
+
+// Contact forms
+await logger.contact({
+  name: "Ana",
+  email: "ana@example.com",
+  phone: "+55 11 99999-9999",
+  message: "I'd like a quote for a new website.",
+  budget: "R$ 5.000", // any extra field is listed too
+});
+```
+
+> In serverless functions (Vercel, Netlify, AWS Lambda...) always **`await`** the call. Otherwise the function may be frozen before the message is sent.
+
+## Different chats per message type
+
+```ts
+const logger = createTelegramLogger({
+  chatId: "-100111", // default chat
+  chatIds: {
+    error: "-100222", // errors and fatals go to #alerts
+    fatal: "-100222",
+    contact: "-100333", // leads go to #leads
+  },
+});
+
+await logger.info("Goes to -100111");
+await logger.error("Goes to -100222");
+await logger.warn("Goes to -100444", {}, { chatId: "-100444" }); // per-call override
+```
+
+## Options
+
+| Option                 | Type                               | Default                    | Description                                                                          |
+| ---------------------- | ---------------------------------- | -------------------------- | ------------------------------------------------------------------------------------ |
+| `botToken`             | `string`                           | `env.TELEGRAM_BOT_TOKEN`   | Bot token from @BotFather.                                                           |
+| `chatId`               | `string \| number`                 | `env.TELEGRAM_CHAT_ID`     | Default chat.                                                                        |
+| `chatIds`              | `{ [kind]: chatId }`               | `{}`                       | Per-kind chats (`debug`, `info`, `success`, `warn`, `error`, `fatal`, `contact`).    |
+| `appName`              | `string`                           | none                       | Shown in the message header.                                                         |
+| `environment`          | `string`                           | none                       | Shown in the message header.                                                         |
+| `enabled`              | `boolean`                          | `true`                     | `false` turns every method into a no-op.                                             |
+| `minLevel`             | `LogLevel`                         | `"debug"`                  | Skip lower levels. `contact` is never skipped.                                       |
+| `timeoutMs`            | `number`                           | `5000`                     | Timeout of each request to Telegram.                                                 |
+| `maxRetryAfterSeconds` | `number`                           | `5`                        | On HTTP 429, wait `retry_after` and retry once if it is at most this. `0` disables.  |
+| `disableNotification`  | `boolean`                          | `false`                    | Send silently.                                                                       |
+| `messageThreadId`      | `number`                           | none                       | Topic id in forum supergroups.                                                       |
+| `onError`              | `(error: TelegramLoggerError) => void` | none                   | Called when a message fails to send.                                                 |
+| `fetch`                | `(url, init) => Promise<Response>` | `globalThis.fetch`         | Custom fetch (proxies, tests).                                                       |
+| `apiBaseUrl`           | `string`                           | `https://api.telegram.org` | Custom Bot API server.                                                               |
+
+Every method also accepts per-call options as its last argument: `{ chatId, title, disableNotification, messageThreadId }`.
+
+## Methods
+
+| Method                                        | Description                                         |
+| --------------------------------------------- | --------------------------------------------------- |
+| `debug` / `info` / `success` / `warn` / `error` / `fatal` `(input, meta?, options?)` | Log at that level. `input` can be an `Error`, a string or any value. |
+| `log(level, input, meta?, options?)`          | Log with a dynamic level.                           |
+| `contact(data, options?)`                     | Format a contact-form submission.                   |
+| `send(html, options?)`                        | Send your own [Telegram HTML](https://core.telegram.org/bots/api#html-style) as is. Escape user input with `escapeHtml`. |
+
+All methods return `Promise<SendResult>` and **never reject**:
+
+```ts
+const result = await logger.error(err);
+if (!result.ok) {
+  // result.reason: "disabled" | "below_min_level" | "missing_config" | "telegram_error" | "network_error" | "timeout"
+  console.warn("Telegram delivery failed:", result.reason, result.error?.message);
+}
+```
+
+The formatters are exported too (`formatLog`, `formatContact`, `escapeHtml`), in case you want to build messages yourself.
+
+## Recipes
+
+- **Disable in development:** `enabled: process.env.NODE_ENV === "production"`.
+- **Only important stuff:** `minLevel: "warn"`.
+- **Custom title:** `logger.error(err, meta, { title: "💳 Checkout failed" })`.
+
+## Documentation
+
+| Guide                                                        | 🇺🇸 English                                                                                                                 | 🇧🇷 Português                                                                                                                  |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| **Usage guide**: Next.js, React, Express, Hono, Workers, Deno... | [docs/en/setup.md](https://github.com/AlexGalhardo/telegram-logger/blob/main/docs/en/setup.md)                           | [docs/pt-br/setup.md](https://github.com/AlexGalhardo/telegram-logger/blob/main/docs/pt-br/setup.md)                           |
+| **Releasing**: publishing and updating on npm and JSR        | [docs/en/how-to-deploy-and-update-this-package.md](https://github.com/AlexGalhardo/telegram-logger/blob/main/docs/en/how-to-deploy-and-update-this-package.md) | [docs/pt-br/how-to-deploy-and-update-this-package.md](https://github.com/AlexGalhardo/telegram-logger/blob/main/docs/pt-br/how-to-deploy-and-update-this-package.md) |
+
+## Contributing
+
+```bash
+bun install
+bun run check   # lint + typecheck + tests + build + package validation
+```
+
+See [CONTRIBUTING.md](https://github.com/AlexGalhardo/telegram-logger/blob/main/CONTRIBUTING.md). To report a vulnerability, see [SECURITY.md](https://github.com/AlexGalhardo/telegram-logger/blob/main/SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © Alex Galhardo

package/dist/format.d.cts

@@ -0,0 +1,39 @@
+import type { ContactData, LogMeta, MessageKind } from "./types.cjs";
+/** Telegram rejects messages longer than this (after entity parsing). */
+export declare const MAX_MESSAGE_LENGTH = 4096;
+/**
+ * Escape text for Telegram's HTML parse mode.
+ *
+ * @param text Untrusted text.
+ * @returns The text with `&`, `<` and `>` escaped.
+ */
+export declare function escapeHtml(text: string): string;
+/** Options used by the formatters. */
+export interface FormatContext {
+    /** App name shown in the header. */
+    appName?: string;
+    /** Environment shown in the header. */
+    environment?: string;
+    /** Replaces the default title (first bold line). */
+    title?: string;
+    /** Clock used for the timestamp. Defaults to `new Date()`. */
+    now?: Date;
+}
+/**
+ * Build the Telegram-HTML text for a log message.
+ *
+ * @param kind Message kind (log level).
+ * @param input The value being logged: an `Error`, a string or anything JSON-serializable.
+ * @param meta Extra key/value context.
+ * @param ctx App name, environment, title override and clock.
+ * @returns Text ready to send with `parse_mode: "HTML"`, at most 4096 characters long.
+ */
+export declare function formatLog(kind: MessageKind, input: unknown, meta?: LogMeta, ctx?: FormatContext): string;
+/**
+ * Build the Telegram-HTML text for a contact form submission.
+ *
+ * @param data Form fields.
+ * @param ctx App name, environment, title override and clock.
+ * @returns Text ready to send with `parse_mode: "HTML"`, at most 4096 characters long.
+ */
+export declare function formatContact(data: ContactData, ctx?: FormatContext): string;

package/dist/format.d.ts

@@ -0,0 +1,39 @@
+import type { ContactData, LogMeta, MessageKind } from "./types.js";
+/** Telegram rejects messages longer than this (after entity parsing). */
+export declare const MAX_MESSAGE_LENGTH = 4096;
+/**
+ * Escape text for Telegram's HTML parse mode.
+ *
+ * @param text Untrusted text.
+ * @returns The text with `&`, `<` and `>` escaped.
+ */
+export declare function escapeHtml(text: string): string;
+/** Options used by the formatters. */
+export interface FormatContext {
+    /** App name shown in the header. */
+    appName?: string;
+    /** Environment shown in the header. */
+    environment?: string;
+    /** Replaces the default title (first bold line). */
+    title?: string;
+    /** Clock used for the timestamp. Defaults to `new Date()`. */
+    now?: Date;
+}
+/**
+ * Build the Telegram-HTML text for a log message.
+ *
+ * @param kind Message kind (log level).
+ * @param input The value being logged: an `Error`, a string or anything JSON-serializable.
+ * @param meta Extra key/value context.
+ * @param ctx App name, environment, title override and clock.
+ * @returns Text ready to send with `parse_mode: "HTML"`, at most 4096 characters long.
+ */
+export declare function formatLog(kind: MessageKind, input: unknown, meta?: LogMeta, ctx?: FormatContext): string;
+/**
+ * Build the Telegram-HTML text for a contact form submission.
+ *
+ * @param data Form fields.
+ * @param ctx App name, environment, title override and clock.
+ * @returns Text ready to send with `parse_mode: "HTML"`, at most 4096 characters long.
+ */
+export declare function formatContact(data: ContactData, ctx?: FormatContext): string;

package/dist/logger.d.cts

@@ -0,0 +1,29 @@
+import { type TelegramLogger, type TelegramLoggerOptions } from "./types.cjs";
+/**
+ * Create a Telegram logger.
+ *
+ * Every method returns a promise that always resolves (never rejects) with a {@linkcode SendResult}.
+ * In serverless functions, `await` the call so the request finishes before the function is frozen.
+ *
+ * @example
+ * ```ts
+ * import { createTelegramLogger } from "@galhardoalex/telegram-logger";
+ *
+ * const logger = createTelegramLogger({
+ *   botToken: process.env.TELEGRAM_BOT_TOKEN,
+ *   chatId: process.env.TELEGRAM_CHAT_ID,
+ *   appName: "my-site",
+ * });
+ *
+ * try {
+ *   await checkout();
+ * } catch (err) {
+ *   await logger.error(err, { route: "/api/checkout" });
+ * }
+ * ```
+ *
+ * @param options Logger configuration. `botToken` and `chatId` fall back to the
+ * `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` environment variables.
+ * @returns A {@linkcode TelegramLogger}.
+ */
+export declare function createTelegramLogger(options?: TelegramLoggerOptions): TelegramLogger;

package/dist/logger.d.ts

@@ -0,0 +1,29 @@
+import { type TelegramLogger, type TelegramLoggerOptions } from "./types.js";
+/**
+ * Create a Telegram logger.
+ *
+ * Every method returns a promise that always resolves (never rejects) with a {@linkcode SendResult}.
+ * In serverless functions, `await` the call so the request finishes before the function is frozen.
+ *
+ * @example
+ * ```ts
+ * import { createTelegramLogger } from "@galhardoalex/telegram-logger";
+ *
+ * const logger = createTelegramLogger({
+ *   botToken: process.env.TELEGRAM_BOT_TOKEN,
+ *   chatId: process.env.TELEGRAM_CHAT_ID,
+ *   appName: "my-site",
+ * });
+ *
+ * try {
+ *   await checkout();
+ * } catch (err) {
+ *   await logger.error(err, { route: "/api/checkout" });
+ * }
+ * ```
+ *
+ * @param options Logger configuration. `botToken` and `chatId` fall back to the
+ * `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` environment variables.
+ * @returns A {@linkcode TelegramLogger}.
+ */
+export declare function createTelegramLogger(options?: TelegramLoggerOptions): TelegramLogger;

package/dist/mod.cjs

@@ -0,0 +1,312 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/mod.ts
+var exports_mod = {};
+__export(exports_mod, {
+  MAX_MESSAGE_LENGTH: () => MAX_MESSAGE_LENGTH,
+  TelegramLoggerError: () => TelegramLoggerError,
+  createTelegramLogger: () => createTelegramLogger,
+  escapeHtml: () => escapeHtml,
+  formatContact: () => formatContact,
+  formatLog: () => formatLog
+});
+module.exports = __toCommonJS(exports_mod);
+
+// src/format.ts
+var MAX_MESSAGE_LENGTH = 4096;
+var ICONS = {
+  debug: "⚪",
+  info: "\uD83D\uDD35",
+  success: "\uD83D\uDFE2",
+  warn: "\uD83D\uDFE1",
+  error: "\uD83D\uDD34",
+  fatal: "\uD83D\uDC80",
+  contact: "\uD83D\uDCE9"
+};
+var LABELS = {
+  debug: "DEBUG",
+  info: "INFO",
+  success: "SUCCESS",
+  warn: "WARNING",
+  error: "ERROR",
+  fatal: "FATAL",
+  contact: "NEW CONTACT"
+};
+var CONTACT_FIELDS = ["name", "email", "phone", "subject"];
+function escapeHtml(text) {
+  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function truncate(text, max) {
+  if (text.length <= max)
+    return text;
+  return `${text.slice(0, Math.max(0, max - 1))}…`;
+}
+function stringify(value) {
+  if (typeof value === "string")
+    return value;
+  if (value instanceof Error)
+    return `${value.name}: ${value.message}`;
+  if (value === null || typeof value !== "object") {
+    return String(value);
+  }
+  try {
+    const json = JSON.stringify(value, (_key, v) => typeof v === "bigint" ? v.toString() : v);
+    return json ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+function describeInput(input) {
+  if (input instanceof Error) {
+    const stackLines = (input.stack ?? "").split(`
+`);
+    const frames = stackLines[0]?.includes(input.message) ? stackLines.slice(1) : stackLines;
+    let block = frames.map((l) => l.trim()).filter(Boolean).join(`
+`);
+    let cause = input.cause;
+    for (let depth = 0;cause !== undefined && depth < 3; depth++) {
+      block += `${block ? `
+` : ""}Caused by: ${stringify(cause)}`;
+      cause = cause instanceof Error ? cause.cause : undefined;
+    }
+    return { title: `${input.name}: ${input.message}`, block: block || undefined };
+  }
+  if (typeof input === "string") {
+    const [first = "", ...rest] = input.split(`
+`);
+    return { title: first, body: rest.join(`
+`).trim() || undefined };
+  }
+  return { title: stringify(input) };
+}
+function header(kind, appName, environment) {
+  return [`${ICONS[kind]} <b>${LABELS[kind]}</b>`, appName, environment].filter(Boolean).map((part, i) => i === 0 ? part : escapeHtml(part)).join(" · ");
+}
+function render(head, parts, budget, timestamp) {
+  const lines = [head, `<b>${escapeHtml(truncate(parts.title, budget))}</b>`];
+  if (parts.body)
+    lines.push("", escapeHtml(truncate(parts.body, budget * 2)));
+  if (parts.fields.length > 0) {
+    lines.push("");
+    for (const [key, value] of parts.fields) {
+      lines.push(`<b>${escapeHtml(truncate(key, 64))}:</b> ${escapeHtml(truncate(value, budget))}`);
+    }
+  }
+  if (parts.block) {
+    const tag = parts.blockIsQuote ? "blockquote" : "pre";
+    lines.push("", `<${tag}>${escapeHtml(truncate(parts.block, budget * 3))}</${tag}>`);
+  }
+  lines.push("", `\uD83D\uDD52 ${timestamp}`);
+  return lines.join(`
+`);
+}
+function fit(head, parts, timestamp) {
+  for (let budget = 1200;budget >= 16; budget = Math.floor(budget / 2)) {
+    const text = render(head, parts, budget, timestamp);
+    if (text.length <= MAX_MESSAGE_LENGTH)
+      return text;
+  }
+  return render(head, { title: parts.title, fields: [] }, 16, timestamp);
+}
+function formatLog(kind, input, meta = {}, ctx = {}) {
+  const described = describeInput(input);
+  const parts = {
+    ...described,
+    title: ctx.title ?? described.title,
+    body: ctx.title !== undefined && described.title !== ctx.title ? [described.title, described.body].filter(Boolean).join(`
+`) : described.body,
+    fields: Object.entries(meta).filter(([, v]) => v !== undefined).map(([k, v]) => [k, stringify(v)])
+  };
+  const timestamp = (ctx.now ?? new Date).toISOString();
+  return fit(header(kind, ctx.appName, ctx.environment), parts, timestamp);
+}
+function formatContact(data, ctx = {}) {
+  const { message, ...rest } = data;
+  const known = CONTACT_FIELDS.filter((f) => rest[f] !== undefined && rest[f] !== "");
+  const extra = Object.keys(rest).filter((k) => !CONTACT_FIELDS.includes(k) && rest[k] !== undefined);
+  const parts = {
+    title: ctx.title ?? (typeof data.name === "string" && data.name ? `From ${data.name}` : "New message"),
+    fields: [...known, ...extra].map((k) => [k, stringify(rest[k])]),
+    block: message === undefined || message === "" ? undefined : stringify(message),
+    blockIsQuote: true
+  };
+  const timestamp = (ctx.now ?? new Date).toISOString();
+  return fit(header("contact", ctx.appName, ctx.environment), parts, timestamp);
+}
+// src/types.ts
+class TelegramLoggerError extends Error {
+  reason;
+  status;
+  constructor(reason, message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = "TelegramLoggerError";
+    this.reason = reason;
+    this.status = options.status;
+  }
+}
+
+// src/logger.ts
+var LEVEL_RANK = {
+  debug: 10,
+  info: 20,
+  success: 20,
+  warn: 30,
+  error: 40,
+  fatal: 50
+};
+var DEFAULT_TIMEOUT_MS = 5000;
+var DEFAULT_MAX_RETRY_AFTER_SECONDS = 5;
+var DEFAULT_API_BASE_URL = "https://api.telegram.org";
+function readEnv(name) {
+  try {
+    const g = globalThis;
+    return g.process?.env?.[name] ?? g.Deno?.env?.get(name) ?? undefined;
+  } catch {
+    return;
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function createTelegramLogger(options = {}) {
+  const {
+    appName,
+    environment,
+    enabled = true,
+    minLevel = "debug",
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    maxRetryAfterSeconds = DEFAULT_MAX_RETRY_AFTER_SECONDS,
+    disableNotification = false,
+    messageThreadId,
+    onError,
+    apiBaseUrl = DEFAULT_API_BASE_URL
+  } = options;
+  function fail(result) {
+    if (result.error && onError) {
+      try {
+        onError(result.error);
+      } catch {}
+    }
+    return result;
+  }
+  async function deliver(kind, text, sendOptions) {
+    const botToken = options.botToken ?? readEnv("TELEGRAM_BOT_TOKEN");
+    const chatId = sendOptions.chatId ?? options.chatIds?.[kind] ?? options.chatId ?? readEnv("TELEGRAM_CHAT_ID");
+    if (!botToken || chatId === undefined || chatId === "") {
+      return fail({
+        ok: false,
+        reason: "missing_config",
+        error: new TelegramLoggerError("missing_config", "Missing botToken or chatId. Pass them to createTelegramLogger() or set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID.")
+      });
+    }
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const threadId = sendOptions.messageThreadId ?? messageThreadId;
+    const body = JSON.stringify({
+      chat_id: chatId,
+      text,
+      parse_mode: "HTML",
+      link_preview_options: { is_disabled: true },
+      disable_notification: sendOptions.disableNotification ?? disableNotification,
+      ...threadId === undefined ? {} : { message_thread_id: threadId }
+    });
+    for (let attempt = 0;; attempt++) {
+      let response;
+      try {
+        response = await doFetch(`${apiBaseUrl}/bot${botToken}/sendMessage`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body,
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+      } catch (cause) {
+        const isTimeout = cause instanceof Error && (cause.name === "TimeoutError" || cause.name === "AbortError");
+        const reason = isTimeout ? "timeout" : "network_error";
+        const message = isTimeout ? `Telegram did not answer within ${timeoutMs}ms` : "Could not reach Telegram";
+        return fail({ ok: false, reason, error: new TelegramLoggerError(reason, message, { cause }) });
+      }
+      let data;
+      try {
+        data = await response.json();
+      } catch {
+        data = undefined;
+      }
+      if (response.ok && data?.ok && data.result) {
+        return { ok: true, messageId: data.result.message_id };
+      }
+      const retryAfter = data?.parameters?.retry_after;
+      if (response.status === 429 && attempt === 0 && retryAfter !== undefined && retryAfter <= maxRetryAfterSeconds) {
+        await sleep(retryAfter * 1000);
+        continue;
+      }
+      return fail({
+        ok: false,
+        reason: "telegram_error",
+        error: new TelegramLoggerError("telegram_error", `Telegram API error ${response.status}: ${data?.description ?? response.statusText}`, { status: response.status })
+      });
+    }
+  }
+  function log(level, input, meta, sendOptions = {}) {
+    if (!enabled)
+      return Promise.resolve({ ok: false, reason: "disabled" });
+    if (LEVEL_RANK[level] < LEVEL_RANK[minLevel])
+      return Promise.resolve({ ok: false, reason: "below_min_level" });
+    const text = formatLog(level, input, meta, { appName, environment, title: sendOptions.title });
+    return deliver(level, text, sendOptions);
+  }
+  return {
+    log,
+    debug: (input, meta, opts) => log("debug", input, meta, opts),
+    info: (input, meta, opts) => log("info", input, meta, opts),
+    success: (input, meta, opts) => log("success", input, meta, opts),
+    warn: (input, meta, opts) => log("warn", input, meta, opts),
+    error: (input, meta, opts) => log("error", input, meta, opts),
+    fatal: (input, meta, opts) => log("fatal", input, meta, opts),
+    contact(data, sendOptions = {}) {
+      if (!enabled)
+        return Promise.resolve({ ok: false, reason: "disabled" });
+      const text = formatContact(data, { appName, environment, title: sendOptions.title });
+      return deliver("contact", text, sendOptions);
+    },
+    send(html, sendOptions = {}) {
+      if (!enabled)
+        return Promise.resolve({ ok: false, reason: "disabled" });
+      return deliver("info", html, sendOptions);
+    }
+  };
+}

package/dist/mod.d.cts

@@ -0,0 +1,26 @@
+/**
+ * Zero-dependency logger that sends errors, warnings, events and contact-form
+ * submissions to your Telegram chats and channels.
+ *
+ * Works on Node.js 18+, Bun, Deno, Cloudflare Workers and Vercel/Next.js Edge.
+ *
+ * @example
+ * ```ts
+ * import { createTelegramLogger } from "@galhardoalex/telegram-logger";
+ *
+ * const logger = createTelegramLogger({
+ *   botToken: process.env.TELEGRAM_BOT_TOKEN,
+ *   chatId: process.env.TELEGRAM_CHAT_ID,
+ *   appName: "my-site",
+ *   environment: "production",
+ * });
+ *
+ * await logger.error(new Error("Payment failed"), { orderId: 42 });
+ * await logger.contact({ name: "Ana", email: "ana@example.com", message: "Hi!" });
+ * ```
+ *
+ * @module
+ */
+export { escapeHtml, type FormatContext, formatContact, formatLog, MAX_MESSAGE_LENGTH } from "./format.cjs";
+export { createTelegramLogger } from "./logger.cjs";
+export { type ChatId, type ContactData, type FailureReason, type LogLevel, type LogMeta, type MessageKind, type SendOptions, type SendResult, type TelegramLogger, TelegramLoggerError, type TelegramLoggerOptions, } from "./types.cjs";

package/dist/mod.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Zero-dependency logger that sends errors, warnings, events and contact-form
+ * submissions to your Telegram chats and channels.
+ *
+ * Works on Node.js 18+, Bun, Deno, Cloudflare Workers and Vercel/Next.js Edge.
+ *
+ * @example
+ * ```ts
+ * import { createTelegramLogger } from "@galhardoalex/telegram-logger";
+ *
+ * const logger = createTelegramLogger({
+ *   botToken: process.env.TELEGRAM_BOT_TOKEN,
+ *   chatId: process.env.TELEGRAM_CHAT_ID,
+ *   appName: "my-site",
+ *   environment: "production",
+ * });
+ *
+ * await logger.error(new Error("Payment failed"), { orderId: 42 });
+ * await logger.contact({ name: "Ana", email: "ana@example.com", message: "Hi!" });
+ * ```
+ *
+ * @module
+ */
+export { escapeHtml, type FormatContext, formatContact, formatLog, MAX_MESSAGE_LENGTH } from "./format.js";
+export { createTelegramLogger } from "./logger.js";
+export { type ChatId, type ContactData, type FailureReason, type LogLevel, type LogMeta, type MessageKind, type SendOptions, type SendResult, type TelegramLogger, TelegramLoggerError, type TelegramLoggerOptions, } from "./types.js";

package/dist/mod.js

@@ -0,0 +1,270 @@
+// src/format.ts
+var MAX_MESSAGE_LENGTH = 4096;
+var ICONS = {
+  debug: "⚪",
+  info: "\uD83D\uDD35",
+  success: "\uD83D\uDFE2",
+  warn: "\uD83D\uDFE1",
+  error: "\uD83D\uDD34",
+  fatal: "\uD83D\uDC80",
+  contact: "\uD83D\uDCE9"
+};
+var LABELS = {
+  debug: "DEBUG",
+  info: "INFO",
+  success: "SUCCESS",
+  warn: "WARNING",
+  error: "ERROR",
+  fatal: "FATAL",
+  contact: "NEW CONTACT"
+};
+var CONTACT_FIELDS = ["name", "email", "phone", "subject"];
+function escapeHtml(text) {
+  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function truncate(text, max) {
+  if (text.length <= max)
+    return text;
+  return `${text.slice(0, Math.max(0, max - 1))}…`;
+}
+function stringify(value) {
+  if (typeof value === "string")
+    return value;
+  if (value instanceof Error)
+    return `${value.name}: ${value.message}`;
+  if (value === null || typeof value !== "object") {
+    return String(value);
+  }
+  try {
+    const json = JSON.stringify(value, (_key, v) => typeof v === "bigint" ? v.toString() : v);
+    return json ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+function describeInput(input) {
+  if (input instanceof Error) {
+    const stackLines = (input.stack ?? "").split(`
+`);
+    const frames = stackLines[0]?.includes(input.message) ? stackLines.slice(1) : stackLines;
+    let block = frames.map((l) => l.trim()).filter(Boolean).join(`
+`);
+    let cause = input.cause;
+    for (let depth = 0;cause !== undefined && depth < 3; depth++) {
+      block += `${block ? `
+` : ""}Caused by: ${stringify(cause)}`;
+      cause = cause instanceof Error ? cause.cause : undefined;
+    }
+    return { title: `${input.name}: ${input.message}`, block: block || undefined };
+  }
+  if (typeof input === "string") {
+    const [first = "", ...rest] = input.split(`
+`);
+    return { title: first, body: rest.join(`
+`).trim() || undefined };
+  }
+  return { title: stringify(input) };
+}
+function header(kind, appName, environment) {
+  return [`${ICONS[kind]} <b>${LABELS[kind]}</b>`, appName, environment].filter(Boolean).map((part, i) => i === 0 ? part : escapeHtml(part)).join(" · ");
+}
+function render(head, parts, budget, timestamp) {
+  const lines = [head, `<b>${escapeHtml(truncate(parts.title, budget))}</b>`];
+  if (parts.body)
+    lines.push("", escapeHtml(truncate(parts.body, budget * 2)));
+  if (parts.fields.length > 0) {
+    lines.push("");
+    for (const [key, value] of parts.fields) {
+      lines.push(`<b>${escapeHtml(truncate(key, 64))}:</b> ${escapeHtml(truncate(value, budget))}`);
+    }
+  }
+  if (parts.block) {
+    const tag = parts.blockIsQuote ? "blockquote" : "pre";
+    lines.push("", `<${tag}>${escapeHtml(truncate(parts.block, budget * 3))}</${tag}>`);
+  }
+  lines.push("", `\uD83D\uDD52 ${timestamp}`);
+  return lines.join(`
+`);
+}
+function fit(head, parts, timestamp) {
+  for (let budget = 1200;budget >= 16; budget = Math.floor(budget / 2)) {
+    const text = render(head, parts, budget, timestamp);
+    if (text.length <= MAX_MESSAGE_LENGTH)
+      return text;
+  }
+  return render(head, { title: parts.title, fields: [] }, 16, timestamp);
+}
+function formatLog(kind, input, meta = {}, ctx = {}) {
+  const described = describeInput(input);
+  const parts = {
+    ...described,
+    title: ctx.title ?? described.title,
+    body: ctx.title !== undefined && described.title !== ctx.title ? [described.title, described.body].filter(Boolean).join(`
+`) : described.body,
+    fields: Object.entries(meta).filter(([, v]) => v !== undefined).map(([k, v]) => [k, stringify(v)])
+  };
+  const timestamp = (ctx.now ?? new Date).toISOString();
+  return fit(header(kind, ctx.appName, ctx.environment), parts, timestamp);
+}
+function formatContact(data, ctx = {}) {
+  const { message, ...rest } = data;
+  const known = CONTACT_FIELDS.filter((f) => rest[f] !== undefined && rest[f] !== "");
+  const extra = Object.keys(rest).filter((k) => !CONTACT_FIELDS.includes(k) && rest[k] !== undefined);
+  const parts = {
+    title: ctx.title ?? (typeof data.name === "string" && data.name ? `From ${data.name}` : "New message"),
+    fields: [...known, ...extra].map((k) => [k, stringify(rest[k])]),
+    block: message === undefined || message === "" ? undefined : stringify(message),
+    blockIsQuote: true
+  };
+  const timestamp = (ctx.now ?? new Date).toISOString();
+  return fit(header("contact", ctx.appName, ctx.environment), parts, timestamp);
+}
+// src/types.ts
+class TelegramLoggerError extends Error {
+  reason;
+  status;
+  constructor(reason, message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = "TelegramLoggerError";
+    this.reason = reason;
+    this.status = options.status;
+  }
+}
+
+// src/logger.ts
+var LEVEL_RANK = {
+  debug: 10,
+  info: 20,
+  success: 20,
+  warn: 30,
+  error: 40,
+  fatal: 50
+};
+var DEFAULT_TIMEOUT_MS = 5000;
+var DEFAULT_MAX_RETRY_AFTER_SECONDS = 5;
+var DEFAULT_API_BASE_URL = "https://api.telegram.org";
+function readEnv(name) {
+  try {
+    const g = globalThis;
+    return g.process?.env?.[name] ?? g.Deno?.env?.get(name) ?? undefined;
+  } catch {
+    return;
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function createTelegramLogger(options = {}) {
+  const {
+    appName,
+    environment,
+    enabled = true,
+    minLevel = "debug",
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    maxRetryAfterSeconds = DEFAULT_MAX_RETRY_AFTER_SECONDS,
+    disableNotification = false,
+    messageThreadId,
+    onError,
+    apiBaseUrl = DEFAULT_API_BASE_URL
+  } = options;
+  function fail(result) {
+    if (result.error && onError) {
+      try {
+        onError(result.error);
+      } catch {}
+    }
+    return result;
+  }
+  async function deliver(kind, text, sendOptions) {
+    const botToken = options.botToken ?? readEnv("TELEGRAM_BOT_TOKEN");
+    const chatId = sendOptions.chatId ?? options.chatIds?.[kind] ?? options.chatId ?? readEnv("TELEGRAM_CHAT_ID");
+    if (!botToken || chatId === undefined || chatId === "") {
+      return fail({
+        ok: false,
+        reason: "missing_config",
+        error: new TelegramLoggerError("missing_config", "Missing botToken or chatId. Pass them to createTelegramLogger() or set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID.")
+      });
+    }
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const threadId = sendOptions.messageThreadId ?? messageThreadId;
+    const body = JSON.stringify({
+      chat_id: chatId,
+      text,
+      parse_mode: "HTML",
+      link_preview_options: { is_disabled: true },
+      disable_notification: sendOptions.disableNotification ?? disableNotification,
+      ...threadId === undefined ? {} : { message_thread_id: threadId }
+    });
+    for (let attempt = 0;; attempt++) {
+      let response;
+      try {
+        response = await doFetch(`${apiBaseUrl}/bot${botToken}/sendMessage`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body,
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+      } catch (cause) {
+        const isTimeout = cause instanceof Error && (cause.name === "TimeoutError" || cause.name === "AbortError");
+        const reason = isTimeout ? "timeout" : "network_error";
+        const message = isTimeout ? `Telegram did not answer within ${timeoutMs}ms` : "Could not reach Telegram";
+        return fail({ ok: false, reason, error: new TelegramLoggerError(reason, message, { cause }) });
+      }
+      let data;
+      try {
+        data = await response.json();
+      } catch {
+        data = undefined;
+      }
+      if (response.ok && data?.ok && data.result) {
+        return { ok: true, messageId: data.result.message_id };
+      }
+      const retryAfter = data?.parameters?.retry_after;
+      if (response.status === 429 && attempt === 0 && retryAfter !== undefined && retryAfter <= maxRetryAfterSeconds) {
+        await sleep(retryAfter * 1000);
+        continue;
+      }
+      return fail({
+        ok: false,
+        reason: "telegram_error",
+        error: new TelegramLoggerError("telegram_error", `Telegram API error ${response.status}: ${data?.description ?? response.statusText}`, { status: response.status })
+      });
+    }
+  }
+  function log(level, input, meta, sendOptions = {}) {
+    if (!enabled)
+      return Promise.resolve({ ok: false, reason: "disabled" });
+    if (LEVEL_RANK[level] < LEVEL_RANK[minLevel])
+      return Promise.resolve({ ok: false, reason: "below_min_level" });
+    const text = formatLog(level, input, meta, { appName, environment, title: sendOptions.title });
+    return deliver(level, text, sendOptions);
+  }
+  return {
+    log,
+    debug: (input, meta, opts) => log("debug", input, meta, opts),
+    info: (input, meta, opts) => log("info", input, meta, opts),
+    success: (input, meta, opts) => log("success", input, meta, opts),
+    warn: (input, meta, opts) => log("warn", input, meta, opts),
+    error: (input, meta, opts) => log("error", input, meta, opts),
+    fatal: (input, meta, opts) => log("fatal", input, meta, opts),
+    contact(data, sendOptions = {}) {
+      if (!enabled)
+        return Promise.resolve({ ok: false, reason: "disabled" });
+      const text = formatContact(data, { appName, environment, title: sendOptions.title });
+      return deliver("contact", text, sendOptions);
+    },
+    send(html, sendOptions = {}) {
+      if (!enabled)
+        return Promise.resolve({ ok: false, reason: "disabled" });
+      return deliver("info", html, sendOptions);
+    }
+  };
+}
+export {
+  MAX_MESSAGE_LENGTH,
+  TelegramLoggerError,
+  createTelegramLogger,
+  escapeHtml,
+  formatContact,
+  formatLog
+};

package/dist/types.d.cts

@@ -0,0 +1,134 @@
+/** Severity levels, from least to most severe. */
+export type LogLevel = "debug" | "info" | "success" | "warn" | "error" | "fatal";
+/** Every kind of message the logger can send: the log levels plus `contact`. */
+export type MessageKind = LogLevel | "contact";
+/** A Telegram chat identifier: a numeric id (e.g. `-1001234567890`) or a public `@channelusername`. */
+export type ChatId = string | number;
+/** Arbitrary key/value context attached to a message (route, userId, request id, ...). */
+export type LogMeta = Record<string, unknown>;
+/** Configuration for {@linkcode createTelegramLogger}. */
+export interface TelegramLoggerOptions {
+    /**
+     * Bot token from [@BotFather](https://t.me/BotFather).
+     * Falls back to the `TELEGRAM_BOT_TOKEN` environment variable.
+     */
+    botToken?: string;
+    /**
+     * Default chat that receives every message.
+     * Falls back to the `TELEGRAM_CHAT_ID` environment variable.
+     */
+    chatId?: ChatId;
+    /**
+     * Per-kind chat overrides. Kinds without an entry use {@linkcode TelegramLoggerOptions.chatId}.
+     *
+     * @example
+     * ```ts
+     * chatIds: { error: "-100111", fatal: "-100111", contact: "-100222" }
+     * ```
+     */
+    chatIds?: Partial<Record<MessageKind, ChatId>>;
+    /** App name shown in the header of every message (e.g. `"my-site"`). */
+    appName?: string;
+    /** Environment shown in the header of every message (e.g. `"production"`). */
+    environment?: string;
+    /** Set to `false` to turn the logger into a no-op (e.g. in local development). Defaults to `true`. */
+    enabled?: boolean;
+    /** Log levels below this one are skipped. `contact` messages are never filtered. Defaults to `"debug"`. */
+    minLevel?: LogLevel;
+    /** Timeout in milliseconds for each request to the Telegram API. Defaults to `5000`. */
+    timeoutMs?: number;
+    /**
+     * When Telegram answers `429 Too Many Requests`, wait for `retry_after` and try once more,
+     * as long as the wait is at most this many seconds. Set to `0` to disable. Defaults to `5`.
+     */
+    maxRetryAfterSeconds?: number;
+    /** Send messages silently (no notification sound). Defaults to `false`. */
+    disableNotification?: boolean;
+    /** Topic (thread) id when the target chat is a forum supergroup. */
+    messageThreadId?: number;
+    /** Called whenever a message fails to send. The logger itself never throws. */
+    onError?: (error: TelegramLoggerError) => void;
+    /** Custom `fetch` implementation. Defaults to `globalThis.fetch`. */
+    fetch?: (url: string, init: RequestInit) => Promise<Response>;
+    /** Telegram Bot API base URL. Defaults to `"https://api.telegram.org"`. */
+    apiBaseUrl?: string;
+}
+/** Per-call overrides accepted by every logger method. */
+export interface SendOptions {
+    /** Send this message to a different chat. */
+    chatId?: ChatId;
+    /** Replace the default title (first bold line) of the message. */
+    title?: string;
+    /** Send this message silently. */
+    disableNotification?: boolean;
+    /** Topic (thread) id when the target chat is a forum supergroup. */
+    messageThreadId?: number;
+}
+/** Data captured by a typical contact form. Extra fields are listed below the known ones. */
+export interface ContactData {
+    /** Name of the person who submitted the form. */
+    name?: string;
+    /** E-mail address. */
+    email?: string;
+    /** Phone number. */
+    phone?: string;
+    /** Subject line. */
+    subject?: string;
+    /** Free-text message. */
+    message?: string;
+    /** Any other form field. */
+    [field: string]: unknown;
+}
+/** Why a message was not delivered. */
+export type FailureReason = "disabled" | "below_min_level" | "missing_config" | "telegram_error" | "network_error" | "timeout";
+/** Outcome of a send. Logger methods always resolve, never reject. */
+export type SendResult = {
+    /** The message was delivered. */
+    ok: true;
+    /** Id of the message created in the chat. */
+    messageId: number;
+} | {
+    /** The message was not delivered. */
+    ok: false;
+    /** Why it was not delivered. */
+    reason: FailureReason;
+    /** Details of the failure, when there is an error behind it. */
+    error?: TelegramLoggerError;
+};
+/** Error describing a failed delivery. Passed to `onError` and returned in {@linkcode SendResult}. */
+export declare class TelegramLoggerError extends Error {
+    /** Machine-readable failure category. */
+    readonly reason: FailureReason;
+    /** HTTP status code returned by Telegram, when there was a response. */
+    readonly status?: number;
+    /**
+     * @param reason Machine-readable failure category.
+     * @param message Human-readable description.
+     * @param options Optional HTTP status and underlying cause.
+     */
+    constructor(reason: FailureReason, message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+/** The object returned by {@linkcode createTelegramLogger}. */
+export interface TelegramLogger {
+    /** Send a message with an explicit level. */
+    log(level: LogLevel, input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** ⚪ Debug message. */
+    debug(input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** 🔵 Informational message. */
+    info(input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** 🟢 Something good happened (a sale, a deploy, a sign-up). */
+    success(input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** 🟡 Warning. */
+    warn(input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** 🔴 Error. Pass the caught value directly: `Error` objects include their stack and cause. */
+    error(input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** 💀 Fatal error. */
+    fatal(input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** 📩 Contact form submission. Never filtered by `minLevel`. */
+    contact(data: ContactData, options?: SendOptions): Promise<SendResult>;
+    /** Send raw Telegram-HTML text as is, without header or formatting. You must escape user input yourself (see `escapeHtml`). */
+    send(html: string, options?: SendOptions): Promise<SendResult>;
+}

package/dist/types.d.ts

@@ -0,0 +1,134 @@
+/** Severity levels, from least to most severe. */
+export type LogLevel = "debug" | "info" | "success" | "warn" | "error" | "fatal";
+/** Every kind of message the logger can send: the log levels plus `contact`. */
+export type MessageKind = LogLevel | "contact";
+/** A Telegram chat identifier: a numeric id (e.g. `-1001234567890`) or a public `@channelusername`. */
+export type ChatId = string | number;
+/** Arbitrary key/value context attached to a message (route, userId, request id, ...). */
+export type LogMeta = Record<string, unknown>;
+/** Configuration for {@linkcode createTelegramLogger}. */
+export interface TelegramLoggerOptions {
+    /**
+     * Bot token from [@BotFather](https://t.me/BotFather).
+     * Falls back to the `TELEGRAM_BOT_TOKEN` environment variable.
+     */
+    botToken?: string;
+    /**
+     * Default chat that receives every message.
+     * Falls back to the `TELEGRAM_CHAT_ID` environment variable.
+     */
+    chatId?: ChatId;
+    /**
+     * Per-kind chat overrides. Kinds without an entry use {@linkcode TelegramLoggerOptions.chatId}.
+     *
+     * @example
+     * ```ts
+     * chatIds: { error: "-100111", fatal: "-100111", contact: "-100222" }
+     * ```
+     */
+    chatIds?: Partial<Record<MessageKind, ChatId>>;
+    /** App name shown in the header of every message (e.g. `"my-site"`). */
+    appName?: string;
+    /** Environment shown in the header of every message (e.g. `"production"`). */
+    environment?: string;
+    /** Set to `false` to turn the logger into a no-op (e.g. in local development). Defaults to `true`. */
+    enabled?: boolean;
+    /** Log levels below this one are skipped. `contact` messages are never filtered. Defaults to `"debug"`. */
+    minLevel?: LogLevel;
+    /** Timeout in milliseconds for each request to the Telegram API. Defaults to `5000`. */
+    timeoutMs?: number;
+    /**
+     * When Telegram answers `429 Too Many Requests`, wait for `retry_after` and try once more,
+     * as long as the wait is at most this many seconds. Set to `0` to disable. Defaults to `5`.
+     */
+    maxRetryAfterSeconds?: number;
+    /** Send messages silently (no notification sound). Defaults to `false`. */
+    disableNotification?: boolean;
+    /** Topic (thread) id when the target chat is a forum supergroup. */
+    messageThreadId?: number;
+    /** Called whenever a message fails to send. The logger itself never throws. */
+    onError?: (error: TelegramLoggerError) => void;
+    /** Custom `fetch` implementation. Defaults to `globalThis.fetch`. */
+    fetch?: (url: string, init: RequestInit) => Promise<Response>;
+    /** Telegram Bot API base URL. Defaults to `"https://api.telegram.org"`. */
+    apiBaseUrl?: string;
+}
+/** Per-call overrides accepted by every logger method. */
+export interface SendOptions {
+    /** Send this message to a different chat. */
+    chatId?: ChatId;
+    /** Replace the default title (first bold line) of the message. */
+    title?: string;
+    /** Send this message silently. */
+    disableNotification?: boolean;
+    /** Topic (thread) id when the target chat is a forum supergroup. */
+    messageThreadId?: number;
+}
+/** Data captured by a typical contact form. Extra fields are listed below the known ones. */
+export interface ContactData {
+    /** Name of the person who submitted the form. */
+    name?: string;
+    /** E-mail address. */
+    email?: string;
+    /** Phone number. */
+    phone?: string;
+    /** Subject line. */
+    subject?: string;
+    /** Free-text message. */
+    message?: string;
+    /** Any other form field. */
+    [field: string]: unknown;
+}
+/** Why a message was not delivered. */
+export type FailureReason = "disabled" | "below_min_level" | "missing_config" | "telegram_error" | "network_error" | "timeout";
+/** Outcome of a send. Logger methods always resolve, never reject. */
+export type SendResult = {
+    /** The message was delivered. */
+    ok: true;
+    /** Id of the message created in the chat. */
+    messageId: number;
+} | {
+    /** The message was not delivered. */
+    ok: false;
+    /** Why it was not delivered. */
+    reason: FailureReason;
+    /** Details of the failure, when there is an error behind it. */
+    error?: TelegramLoggerError;
+};
+/** Error describing a failed delivery. Passed to `onError` and returned in {@linkcode SendResult}. */
+export declare class TelegramLoggerError extends Error {
+    /** Machine-readable failure category. */
+    readonly reason: FailureReason;
+    /** HTTP status code returned by Telegram, when there was a response. */
+    readonly status?: number;
+    /**
+     * @param reason Machine-readable failure category.
+     * @param message Human-readable description.
+     * @param options Optional HTTP status and underlying cause.
+     */
+    constructor(reason: FailureReason, message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+/** The object returned by {@linkcode createTelegramLogger}. */
+export interface TelegramLogger {
+    /** Send a message with an explicit level. */
+    log(level: LogLevel, input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** ⚪ Debug message. */
+    debug(input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** 🔵 Informational message. */
+    info(input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** 🟢 Something good happened (a sale, a deploy, a sign-up). */
+    success(input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** 🟡 Warning. */
+    warn(input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** 🔴 Error. Pass the caught value directly: `Error` objects include their stack and cause. */
+    error(input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** 💀 Fatal error. */
+    fatal(input: unknown, meta?: LogMeta, options?: SendOptions): Promise<SendResult>;
+    /** 📩 Contact form submission. Never filtered by `minLevel`. */
+    contact(data: ContactData, options?: SendOptions): Promise<SendResult>;
+    /** Send raw Telegram-HTML text as is, without header or formatting. You must escape user input yourself (see `escapeHtml`). */
+    send(html: string, options?: SendOptions): Promise<SendResult>;
+}

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@galhardoalex/telegram-logger",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Zero-dependency logger that sends errors, warnings, events and contact-form submissions to your Telegram chats. Works on Node, Bun, Deno, Next.js and edge runtimes.",
+  "keywords": [
+    "telegram",
+    "logger",
+    "telegram-bot",
+    "notifications",
+    "alerts",
+    "error-reporting",
+    "contact-form",
+    "nextjs",
+    "edge",
+    "typescript"
+  ],
+  "author": "Alex Galhardo <aleexgvieira@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/AlexGalhardo/telegram-logger#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexGalhardo/telegram-logger.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AlexGalhardo/telegram-logger/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/mod.cjs",
+  "module": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/mod.d.ts",
+        "default": "./dist/mod.js"
+      },
+      "require": {
+        "types": "./dist/mod.d.cts",
+        "default": "./dist/mod.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "check:package": "publint --strict && attw --pack . --profile node16",
+    "check:jsr": "bunx jsr publish --dry-run --allow-dirty",
+    "check": "bun run lint && bun run typecheck && bun test && bun run build && bun run check:package",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@biomejs/biome": "^2.5.15",
+    "@types/bun": "latest",
+    "publint": "^0.3.25",
+    "typescript": "^7.0.2"
+  }
+}