telegram-private-logger 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,317 @@
+# Telegram Private Logger
+
+A lightweight, typed logger for sending logs directly to Telegram chats using the official Telegram Bot API with full TypeScript support.
+
+## Installation
+
+```bash
+npm install telegram-private-logger
+```
+
+## Quick Start
+
+```typescript
+import { init } from "telegram-private-logger";
+
+// Initialize the logger client
+const logger = init({
+  token: "your-telegram-bot-token",
+  chatId: "your-chat-id",
+});
+
+// Send a log message
+await logger.track({
+  title: "User Login",
+  icon: "🔐",
+  source: "auth-service",
+  content: "User successfully logged in",
+  tags: {
+    userId: "12345",
+    method: "email",
+  },
+});
+```
+
+## Usage
+
+### Basic Setup
+
+Create a logger client in your project:
+
+```typescript
+// logger.ts
+import { init } from "telegram-private-logger";
+
+export const telegramLogger = init({
+  token: process.env.PRIVATE_LOGGER_TOKEN!,
+  chatId: process.env.PRIVATE_LOGGER_CHAT_ID!,
+});
+```
+
+### Using the Logger
+
+```typescript
+// app.ts
+import { telegramLogger } from "./logger";
+
+// Track user actions
+await telegramLogger.track({
+  title: "Dashboard Loaded",
+  icon: "📊",
+  source: "dashboard-service",
+  content: "User dashboard loaded successfully",
+  tags: {
+    userId: "12345",
+    organizationId: "67890",
+  },
+});
+
+// Track errors
+await telegramLogger.track({
+  title: "API Error",
+  icon: "❌",
+  source: "api-service",
+  content: "Failed to fetch user data from database",
+  tags: {
+    endpoint: "/api/users",
+    statusCode: "500",
+    error: "database_connection_failed",
+  },
+});
+
+// Track simple events
+await telegramLogger.track({
+  title: "User Action",
+  icon: "👤",
+  source: "user-service",
+});
+```
+
+### Environment Variables
+
+```bash
+# .env
+PRIVATE_LOGGER_TOKEN=your_bot_token_here
+PRIVATE_LOGGER_CHAT_ID=your_chat_id_here
+```
+
+## API Reference
+
+### `init(config: TelegramPrivateLoggerConfig): TelegramPrivateLoggerClient`
+
+Initializes a new telegram logger client.
+
+#### Parameters
+
+- `config` (TelegramPrivateLoggerConfig): Configuration object
+  - `token` (string): Your Telegram bot authentication token
+  - `chatId` (string): The chat ID where logs will be sent
+
+#### Returns
+
+- `TelegramPrivateLoggerClient`: A client instance with tracking capabilities
+
+### `TelegramPrivateLoggerClient.track(options: LoggerOptions): Promise<void>`
+
+Sends a log entry to your Telegram chat.
+
+#### Parameters
+
+- `options` (LoggerOptions): Logging options object
+  - `title` (string): Title for the log entry
+  - `icon` (string): Emoji or icon (e.g., "🔐", "❌", "✅")
+  - `source` (string): Source identifier (e.g., "auth-service", "api-gateway")
+  - `content?` (string): Optional detailed content/message
+  - `tags?` (Record<string, string>): Optional key-value pairs for categorization
+
+#### Returns
+
+- `Promise<void>`: Resolves when the log is sent successfully
+
+## TypeScript Support
+
+This package is written in TypeScript and provides full type definitions. All parameters are properly typed and will show up in your IDE with autocomplete and type checking.
+
+```typescript
+import {
+  init,
+  LoggerOptions,
+  TelegramPrivateLoggerConfig,
+} from "telegram-private-logger";
+
+// Full type safety
+const config: TelegramPrivateLoggerConfig = {
+  token: process.env.PRIVATE_LOGGER_TOKEN!,
+  chatId: process.env.PRIVATE_LOGGER_CHAT_ID!,
+};
+
+const logData: LoggerOptions = {
+  title: "Database Connection",
+  icon: "💾",
+  source: "database-service",
+  content: "Successfully connected to PostgreSQL",
+  tags: {
+    database: "postgres",
+    connection: "pool",
+  },
+};
+
+const client = init(config);
+await client.track(logData);
+```
+
+## Examples
+
+### Error Tracking
+
+```typescript
+const logError = async (error: Error, context: Record<string, string>) => {
+  await telegramLogger.track({
+    title: "Application Error",
+    icon: "🚨",
+    source: "error-handler",
+    content: error.message,
+    tags: {
+      errorType: error.name,
+      stack: error.stack?.split("\n")[0] || "",
+      ...context,
+    },
+  });
+};
+```
+
+### User Activity Tracking
+
+```typescript
+const trackUserAction = async (
+  action: string,
+  userId: string,
+  details?: string
+) => {
+  await telegramLogger.track({
+    title: `User Action: ${action}`,
+    icon: "👤",
+    source: "user-service",
+    content: details,
+    tags: {
+      userId,
+      action,
+      timestamp: new Date().toISOString(),
+    },
+  });
+};
+```
+
+### API Request Logging
+
+```typescript
+const logApiRequest = async (
+  method: string,
+  endpoint: string,
+  statusCode: number
+) => {
+  await telegramLogger.track({
+    title: `API ${method} ${endpoint}`,
+    icon: statusCode >= 400 ? "❌" : "✅",
+    source: "api-gateway",
+    content: `HTTP ${method} ${endpoint} returned ${statusCode}`,
+    tags: {
+      method,
+      endpoint,
+      statusCode: statusCode.toString(),
+    },
+  });
+};
+```
+
+## Configuration
+
+### Required Parameters
+
+- **token**: Your Telegram bot token (get it from [@BotFather](https://t.me/botfather))
+- **chatId**: The chat ID where logs will be sent (can be a user chat, group, or channel)
+
+### Required Log Fields
+
+The following fields are required for each log entry:
+
+- **title**: The main title of the log entry
+- **icon**: An emoji or icon to represent the log type
+- **source**: The source/service identifier
+
+### Optional Log Fields
+
+- **content**: Detailed description of what happened
+- **tags**: Key-value pairs for additional context
+
+```typescript
+// Minimal required log
+await telegramLogger.track({
+  title: "Simple event",
+  icon: "🔔",
+  source: "service-name",
+});
+
+// Full log with all fields
+await telegramLogger.track({
+  title: "Complex event",
+  icon: "🎯",
+  source: "service-name",
+  content: "Detailed description of what happened",
+  tags: {
+    category: "user-action",
+    priority: "high",
+    environment: "production",
+  },
+});
+```
+
+## Getting Your Telegram Bot Token and Chat ID
+
+### 1. Create a Bot
+
+1. Message [@BotFather](https://t.me/botfather) on Telegram
+2. Send `/newbot` and follow the instructions
+3. Save the bot token you receive
+
+### 2. Get Your Chat ID
+
+1. Start a chat with your bot
+2. Send any message to the bot
+3. Visit: `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`
+4. Find your chat ID in the response
+
+## Error Handling
+
+The logger will automatically log errors to the console if the request fails:
+
+```typescript
+try {
+  await telegramLogger.track({
+    title: "Test log",
+    icon: "🧪",
+    source: "test-service",
+  });
+} catch (error) {
+  // The logger will automatically console.error the response
+  // You can also handle errors here if needed
+  console.error("Failed to send log:", error);
+}
+```
+
+## Message Format
+
+The logger sends formatted messages to Telegram using MarkdownV2 format:
+
+```
+🔐 User Login:
+Source: auth-service
+User successfully logged in
+
+userId: *12345*
+method: *email*
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telegram-private-logger",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "license": "MIT",
   "author": "",
   "type": "module",