iris-relay 1.0.0 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # iris-relay
 
-Lightweight, zero-dependency Telegram message relay. Tree-shakeable ESM package with built-in `.env` loading — true plug-and-play.
+Lightweight Telegram relay dev tool — crash alerts, deploy notifications, heartbeats, and more. Zero-config, tree-shakeable, built-in `.env` loading.
 
 ## Install
 
@@ -15,17 +15,16 @@ Create a `.env` file in your project root:
 ```env
 XERO_BOT_TOKEN=your_bot_token_from_botfather
 XERO_CHAT_ID=your_telegram_chat_id
+XERO_DRY_RUN=false
 ```
 
-> **How to get these:**
-> - **Bot Token** — message [@BotFather](https://t.me/BotFather) on Telegram to create a bot
-> - **Chat ID** — message [@userinfobot](https://t.me/userinfobot) on Telegram to get your chat ID
+> **Bot Token** → [@BotFather](https://t.me/BotFather) · **Chat ID** → [@userinfobot](https://t.me/userinfobot)
 
-That's it. No dotenv import needed — `iris-relay` auto-loads your `.env` file.
+No dotenv import needed — `iris-relay` auto-loads your `.env`.
 
-## Usage
+---
 
-### One-off message
+## Quick Start
 
 ```ts
 import { relay } from "iris-relay";
@@ -33,52 +32,250 @@ import { relay } from "iris-relay";
 await relay("Hello from my server! 🚀");
 ```
 
-### Pre-configured sender
+---
+
+## Features
+
+### 📨 Core Relay
 
 ```ts
-import { createRelay } from "iris-relay";
+import { relay, createRelay } from "iris-relay";
+
+// One-off message
+await relay("Server started");
 
-const send = createRelay({
-  botToken: process.env.XERO_BOT_TOKEN,
-  chatId: process.env.XERO_CHAT_ID,
+// With options
+await relay("Check this out", {
+  parseMode: "HTML",
+  disablePreview: true,
+  silent: true,
+  retries: 3,          // retry with exponential backoff
+  retryDelay: 1000,    // base delay in ms
 });
 
+// Pre-configured sender
+const send = createRelay({ botToken: "...", chatId: "..." });
 await send("Deploy successful ✅");
-await send("Build failed ❌");
 ```
 
-### Options
+### 🚨 Error Relay
 
 ```ts
-await relay("Check this out", {
-  parseMode: "HTML",       // HTML | Markdown | MarkdownV2
-  disablePreview: true,    // no link previews
-  silent: true,            // no notification sound
+import { relayError } from "iris-relay";
+
+try {
+  dangerousOperation();
+} catch (err) {
+  await relayError(err); // sends formatted stack trace
+}
+```
+
+### 📋 JSON Relay
+
+```ts
+import { relayJSON } from "iris-relay";
+
+await relayJSON({ users: 42, status: "healthy" }, "Server Stats");
+```
+
+### 🚀 Deploy Notifications
+
+Sends a formatted deploy summary to Telegram. **Git info is auto-detected** — no config needed if you're in a git repo.
+
+```ts
+import { relayDeploy } from "iris-relay";
+
+// Minimal — auto-reads git branch, commit hash, and commit message
+await relayDeploy();
+
+// With app info
+await relayDeploy({ app: "my-api", env: "production", version: "1.2.3" });
+
+// Full example
+await relayDeploy({
+  app: "my-api",
+  env: "production",
+  version: "1.2.3",
+  by: "CI/CD Pipeline",
+  extra: { region: "us-east-1", duration: "45s" },
+});
+```
+
+**Example Telegram output:**
+```
+🚀 Deploy Notification
+
+📦 App: my-api
+🌍 Env: production
+🏷️ Version: 1.2.3
+🌿 Branch: main
+📝 Commit: a1b2c3d — fix: resolve login bug
+👤 By: CI/CD Pipeline
+⏰ Time: 2026-03-08T12:00:00.000Z
+• region: us-east-1
+• duration: 45s
+```
+
+**How auto-detection works:**
+
+| Field | Git command | Example output |
+|-------|-------------|---------------|
+| `branch` | `git rev-parse --abbrev-ref HEAD` | `main` |
+| `commit` | `git rev-parse --short HEAD` | `a1b2c3d` |
+| Commit message | `git log -1 --pretty=%s` | `fix: resolve login bug` |
+
+> All auto-detected values can be overridden by passing them in the `meta` object. If git is not installed or you're not in a repo, those fields are silently omitted.
+
+**CI/CD example (GitHub Actions):**
+```ts
+await relayDeploy({
+  app: "my-api",
+  env: "production",
+  version: process.env.npm_package_version,
+  by: `GitHub Actions (${process.env.GITHUB_ACTOR})`,
+  commit: process.env.GITHUB_SHA?.slice(0, 7),
+  branch: process.env.GITHUB_REF_NAME,
+});
+```
+
+### ✍️ Message Builder
+
+```ts
+import { message } from "iris-relay";
+
+await message()
+  .bold("Deploy")
+  .text(" ")
+  .code("v1.2.3")
+  .text(" to ")
+  .italic("production")
+  .br()
+  .separator()
+  .link("View Dashboard", "https://example.com")
+  .send();
+```
+
+Builder methods: `.bold()` `.italic()` `.code()` `.codeBlock()` `.strike()` `.underline()` `.link()` `.text()` `.br()` `.separator()`
+
+### 📎 File Relay
+
+```ts
+import { relayFile } from "iris-relay";
+
+await relayFile("./logs/error.log", "Latest error log");
+```
+
+### 💀 Process Crash Watcher
+
+```ts
+import { watchProcess } from "iris-relay";
+
+watchProcess(); // done — uncaught exceptions & rejections get reported
+```
+
+### 💓 Heartbeat
+
+```ts
+import { startHeartbeat } from "iris-relay";
+
+const stop = startHeartbeat({
+  interval: 60_000,   // every minute
+  app: "my-api",
 });
+
+// Later: stop();
+```
+
+### 🔌 Express Middleware
+
+```ts
+import express from "express";
+import { irisMiddleware, irisErrorHandler } from "iris-relay";
+
+const app = express();
+
+// Reports slow requests (>3s) and 5xx errors
+app.use(irisMiddleware({ slowThreshold: 3000 }));
+
+// Your routes...
+
+// Catches unhandled errors and sends to Telegram
+app.use(irisErrorHandler());
+```
+
+### 📡 Multi-Channel
+
+```ts
+import { createChannels } from "iris-relay";
+
+const channels = createChannels([
+  { name: "alerts", chatId: "-100123456" },
+  { name: "deploys", chatId: "-100789012", silent: true },
+  { name: "logs", chatId: "-100345678" },
+]);
+
+await channels.send("alerts", "🚨 Server is down!");
+await channels.send("deploys", "🚀 v1.2.3 deployed");
+await channels.broadcast("System maintenance in 5 minutes");
 ```
 
-## API
+### 🧪 Dry Run Mode
+
+Set `XERO_DRY_RUN=true` in `.env` to log messages to console instead of sending to Telegram. Perfect for local development.
+
+---
+
+## CLI
+
+```bash
+# Send a message
+npx iris-relay "Deploy complete ✅"
+
+# Send with HTML
+npx iris-relay --html "<b>Bold</b> message"
+
+# Send a file
+npx iris-relay --file ./logs/error.log "Error log attached"
+
+# Silent (no notification sound)
+npx iris-relay --silent "Background update"
+```
 
-### `relay(message, config?): Promise<RelayResult>`
+---
 
-Send a single message. Returns `{ success: boolean, messageId?: number, error?: string }`.
+## API Reference
 
-| Param | Type | Description |
-|-------|------|-------------|
-| `message` | `string` | The message text to send |
-| `config.botToken` | `string?` | Bot token (defaults to `XERO_BOT_TOKEN` env var) |
-| `config.chatId` | `string?` | Chat ID (defaults to `XERO_CHAT_ID` env var) |
-| `config.parseMode` | `"HTML" \| "Markdown" \| "MarkdownV2"` | Message formatting |
-| `config.disablePreview` | `boolean?` | Disable link previews |
-| `config.silent` | `boolean?` | Send without notification sound |
+| Export | Description |
+|--------|-------------|
+| `relay(msg, config?)` | Send a text message |
+| `createRelay(config)` | Create a pre-configured sender |
+| `relayError(err, config?)` | Send formatted error + stack trace |
+| `relayJSON(obj, label?, config?)` | Send pretty-printed JSON |
+| `relayDeploy(meta?, config?)` | Send deploy notification with git info |
+| `relayFile(path, caption?, config?)` | Send a file |
+| `message()` | Create a fluent message builder |
+| `watchProcess(config?)` | Auto-report crashes |
+| `startHeartbeat(opts?, config?)` | Periodic alive pings |
+| `irisMiddleware(opts?)` | Express middleware for slow/error reporting |
+| `irisErrorHandler(config?)` | Express error handler |
+| `createChannels(channels, config?)` | Multi-channel manager |
+| `isDryRun()` | Check if dry run mode is active |
 
-### `createRelay(config): (message, overrides?) => Promise<RelayResult>`
+## Config
 
-Create a pre-configured sender function. Useful when sending multiple messages with the same config.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `botToken` | `string` | `XERO_BOT_TOKEN` | Bot token |
+| `chatId` | `string` | `XERO_CHAT_ID` | Chat ID |
+| `parseMode` | `"HTML" \| "Markdown" \| "MarkdownV2"` | — | Message format |
+| `disablePreview` | `boolean` | `false` | Disable link previews |
+| `silent` | `boolean` | `false` | No notification sound |
+| `retries` | `number` | `0` | Retry count |
+| `retryDelay` | `number` | `1000` | Base retry delay (ms) |
 
 ## Requirements
 
-- Node.js ≥ 18 (uses native `fetch`)
+- Node.js ≥ 18
 
 ## License
 

package/dist/builder.d.ts

@@ -0,0 +1,50 @@
+import type { RelayConfig, RelayResult } from "./types.js";
+/**
+ * Fluent message builder for composing formatted Telegram messages.
+ *
+ * @example
+ * ```ts
+ * import { message } from "iris-relay";
+ *
+ * await message()
+ *   .bold("Deploy")
+ *   .text(" ")
+ *   .code("v1.2.3")
+ *   .text(" to ")
+ *   .italic("production")
+ *   .send();
+ * ```
+ */
+export declare class MessageBuilder {
+    private parts;
+    private config;
+    /** Add plain text */
+    text(content: string): this;
+    /** Add bold text */
+    bold(content: string): this;
+    /** Add italic text */
+    italic(content: string): this;
+    /** Add inline code */
+    code(content: string): this;
+    /** Add a code block with optional language */
+    codeBlock(content: string, lang?: string): this;
+    /** Add a strikethrough text */
+    strike(content: string): this;
+    /** Add underlined text */
+    underline(content: string): this;
+    /** Add a link */
+    link(text: string, url: string): this;
+    /** Add a newline */
+    br(): this;
+    /** Add a horizontal separator */
+    separator(): this;
+    /** Override relay config for this message */
+    withConfig(config: RelayConfig): this;
+    /** Build the message string without sending */
+    build(): string;
+    /** Send the composed message */
+    send(config?: RelayConfig): Promise<RelayResult>;
+}
+/** Create a new message builder */
+export declare function message(): MessageBuilder;
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAO3D;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,MAAM,CAAsC;IAEpD,qBAAqB;IACrB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK3B,oBAAoB;IACpB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK3B,sBAAsB;IACtB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK7B,sBAAsB;IACtB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK3B,8CAA8C;IAC9C,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAM/C,+BAA+B;IAC/B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK7B,0BAA0B;IAC1B,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKhC,iBAAiB;IACjB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAKrC,oBAAoB;IACpB,EAAE,IAAI,IAAI;IAKV,iCAAiC;IACjC,SAAS,IAAI,IAAI;IAKjB,6CAA6C;IAC7C,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAKrC,+CAA+C;IAC/C,KAAK,IAAI,MAAM;IAIf,gCAAgC;IAC1B,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;CAGzD;AAED,mCAAmC;AACnC,wBAAgB,OAAO,IAAI,cAAc,CAExC"}

package/dist/builder.js

@@ -0,0 +1,94 @@
+import { relay } from "./relay.js";
+/** Escape HTML special characters */
+function esc(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/**
+ * Fluent message builder for composing formatted Telegram messages.
+ *
+ * @example
+ * ```ts
+ * import { message } from "iris-relay";
+ *
+ * await message()
+ *   .bold("Deploy")
+ *   .text(" ")
+ *   .code("v1.2.3")
+ *   .text(" to ")
+ *   .italic("production")
+ *   .send();
+ * ```
+ */
+export class MessageBuilder {
+    parts = [];
+    config = { parseMode: "HTML" };
+    /** Add plain text */
+    text(content) {
+        this.parts.push(esc(content));
+        return this;
+    }
+    /** Add bold text */
+    bold(content) {
+        this.parts.push(`<b>${esc(content)}</b>`);
+        return this;
+    }
+    /** Add italic text */
+    italic(content) {
+        this.parts.push(`<i>${esc(content)}</i>`);
+        return this;
+    }
+    /** Add inline code */
+    code(content) {
+        this.parts.push(`<code>${esc(content)}</code>`);
+        return this;
+    }
+    /** Add a code block with optional language */
+    codeBlock(content, lang) {
+        const langAttr = lang ? ` class="language-${esc(lang)}"` : "";
+        this.parts.push(`<pre${langAttr}>${esc(content)}</pre>`);
+        return this;
+    }
+    /** Add a strikethrough text */
+    strike(content) {
+        this.parts.push(`<s>${esc(content)}</s>`);
+        return this;
+    }
+    /** Add underlined text */
+    underline(content) {
+        this.parts.push(`<u>${esc(content)}</u>`);
+        return this;
+    }
+    /** Add a link */
+    link(text, url) {
+        this.parts.push(`<a href="${esc(url)}">${esc(text)}</a>`);
+        return this;
+    }
+    /** Add a newline */
+    br() {
+        this.parts.push("\n");
+        return this;
+    }
+    /** Add a horizontal separator */
+    separator() {
+        this.parts.push("\n———————————\n");
+        return this;
+    }
+    /** Override relay config for this message */
+    withConfig(config) {
+        this.config = { ...this.config, ...config };
+        return this;
+    }
+    /** Build the message string without sending */
+    build() {
+        return this.parts.join("");
+    }
+    /** Send the composed message */
+    async send(config) {
+        return relay(this.build(), { ...this.config, ...config });
+    }
+}
+/** Create a new message builder */
+export function message() {
+    return new MessageBuilder();
+}
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}

package/dist/channels.d.ts

@@ -0,0 +1,28 @@
+import type { Channel, RelayConfig, RelayResult } from "./types.js";
+/**
+ * Multi-channel manager for sending to different Telegram chats.
+ *
+ * @example
+ * ```ts
+ * import { createChannels } from "iris-relay";
+ *
+ * const channels = createChannels([
+ *   { name: "alerts", chatId: "-100123456" },
+ *   { name: "deploys", chatId: "-100789012", silent: true },
+ *   { name: "logs", chatId: "-100345678" },
+ * ]);
+ *
+ * await channels.send("alerts", "🚨 Server is down!");
+ * await channels.send("deploys", "🚀 v1.2.3 deployed");
+ * await channels.broadcast("System maintenance in 5 minutes");
+ * ```
+ */
+export declare function createChannels(channels: Channel[], defaultConfig?: RelayConfig): {
+    /** Send a message to a specific channel */
+    send(channelName: string, message: string, config?: RelayConfig): Promise<RelayResult>;
+    /** Broadcast a message to all channels */
+    broadcast(message: string, config?: RelayConfig): Promise<Map<string, RelayResult>>;
+    /** Get list of registered channel names */
+    list(): string[];
+};
+//# sourceMappingURL=channels.d.ts.map

package/dist/channels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../src/channels.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,aAAa,CAAC,EAAE,WAAW;IASvE,2CAA2C;sBACnB,MAAM,WAAW,MAAM,WAAW,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAgB5F,0CAA0C;uBACjB,MAAM,WAAW,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAUzF,2CAA2C;YACnC,MAAM,EAAE;EAIvB"}

package/dist/channels.js

@@ -0,0 +1,56 @@
+import { relay, resolveConfig } from "./relay.js";
+/**
+ * Multi-channel manager for sending to different Telegram chats.
+ *
+ * @example
+ * ```ts
+ * import { createChannels } from "iris-relay";
+ *
+ * const channels = createChannels([
+ *   { name: "alerts", chatId: "-100123456" },
+ *   { name: "deploys", chatId: "-100789012", silent: true },
+ *   { name: "logs", chatId: "-100345678" },
+ * ]);
+ *
+ * await channels.send("alerts", "🚨 Server is down!");
+ * await channels.send("deploys", "🚀 v1.2.3 deployed");
+ * await channels.broadcast("System maintenance in 5 minutes");
+ * ```
+ */
+export function createChannels(channels, defaultConfig) {
+    const resolved = resolveConfig(defaultConfig);
+    const channelMap = new Map();
+    for (const ch of channels) {
+        channelMap.set(ch.name, ch);
+    }
+    return {
+        /** Send a message to a specific channel */
+        async send(channelName, message, config) {
+            const channel = channelMap.get(channelName);
+            if (!channel) {
+                return { success: false, error: `Channel "${channelName}" not found` };
+            }
+            return relay(message, {
+                ...resolved,
+                botToken: channel.botToken ?? resolved.botToken,
+                chatId: channel.chatId,
+                parseMode: channel.parseMode ?? resolved.parseMode,
+                silent: channel.silent ?? resolved.silent,
+                ...config,
+            });
+        },
+        /** Broadcast a message to all channels */
+        async broadcast(message, config) {
+            const results = new Map();
+            for (const [name] of channelMap) {
+                results.set(name, await this.send(name, message, config));
+            }
+            return results;
+        },
+        /** Get list of registered channel names */
+        list() {
+            return Array.from(channelMap.keys());
+        },
+    };
+}
+//# sourceMappingURL=channels.js.map

package/dist/channels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.js","sourceRoot":"","sources":["../src/channels.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGlD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,cAAc,CAAC,QAAmB,EAAE,aAA2B;IAC3E,MAAM,QAAQ,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAmB,CAAC;IAE9C,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QACxB,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAChC,CAAC;IAED,OAAO;QACH,2CAA2C;QAC3C,KAAK,CAAC,IAAI,CAAC,WAAmB,EAAE,OAAe,EAAE,MAAoB;YACjE,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;gBACX,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,WAAW,aAAa,EAAE,CAAC;YAC3E,CAAC;YAED,OAAO,KAAK,CAAC,OAAO,EAAE;gBAClB,GAAG,QAAQ;gBACX,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ;gBAC/C,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS;gBAClD,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM;gBACzC,GAAG,MAAM;aACZ,CAAC,CAAC;QACP,CAAC;QAED,0CAA0C;QAC1C,KAAK,CAAC,SAAS,CAAC,OAAe,EAAE,MAAoB;YACjD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;YAE/C,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,UAAU,EAAE,CAAC;gBAC9B,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;YAC9D,CAAC;YAED,OAAO,OAAO,CAAC;QACnB,CAAC;QAED,2CAA2C;QAC3C,IAAI;YACA,OAAO,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC;KACJ,CAAC;AACN,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { config } from "dotenv";
+import { relay } from "./relay.js";
+import { relayFile } from "./file.js";
+config();
+const args = process.argv.slice(2);
+function printHelp() {
+    console.log(`
+iris-relay — Send messages to Telegram from the CLI
+
+Usage:
+  iris-relay "Your message here"
+  iris-relay --file ./path/to/file.log "Optional caption"
+  iris-relay --silent "No notification sound"
+  iris-relay --html "<b>Bold</b> message"
+
+Options:
+  --file <path>    Send a file instead of a text message
+  --silent         Send without notification sound
+  --html           Parse message as HTML
+  --markdown       Parse message as Markdown
+  --help, -h       Show this help message
+
+Environment:
+  XERO_BOT_TOKEN   Your Telegram bot token
+  XERO_CHAT_ID     Your Telegram chat ID
+`);
+}
+async function main() {
+    if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+        printHelp();
+        process.exit(0);
+    }
+    const silent = args.includes("--silent");
+    const html = args.includes("--html");
+    const markdown = args.includes("--markdown");
+    const fileIdx = args.indexOf("--file");
+    // Filter out flags to get the message
+    const messageArgs = args.filter((a, i) => !a.startsWith("--") && !(i === fileIdx + 1 && fileIdx >= 0));
+    const message = messageArgs.join(" ");
+    const parseMode = html ? "HTML" : markdown ? "Markdown" : undefined;
+    try {
+        // File mode
+        if (fileIdx >= 0) {
+            const filePath = args[fileIdx + 1];
+            if (!filePath) {
+                console.error("Error: --file requires a path argument");
+                process.exit(1);
+            }
+            const result = await relayFile(filePath, message || undefined, {
+                silent,
+                parseMode,
+            });
+            if (result.success) {
+                console.log(`✅ File sent: ${filePath}`);
+            }
+            else {
+                console.error(`❌ Failed: ${result.error}`);
+                process.exit(1);
+            }
+            return;
+        }
+        // Message mode
+        if (!message) {
+            console.error("Error: No message provided");
+            printHelp();
+            process.exit(1);
+        }
+        const result = await relay(message, { silent, parseMode });
+        if (result.success) {
+            console.log(`✅ Message sent (ID: ${result.messageId})`);
+        }
+        else {
+            console.error(`❌ Failed: ${result.error}`);
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(`💥 ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/file.d.ts

@@ -0,0 +1,12 @@
+import type { RelayConfig, RelayResult } from "./types.js";
+/**
+ * Send a file to your Telegram chat via sendDocument API.
+ *
+ * @example
+ * ```ts
+ * import { relayFile } from "iris-relay";
+ * await relayFile("./logs/error.log", "Latest error log");
+ * ```
+ */
+export declare function relayFile(filePath: string, caption?: string, config?: RelayConfig): Promise<RelayResult>;
+//# sourceMappingURL=file.d.ts.map

package/dist/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../src/file.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAoB,MAAM,YAAY,CAAC;AAO7E;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,WAAW,CAAC,CAgDtB"}