JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 14
  • Score
    100M100P100Q48173F
  • License MIT

Lightweight Telegram message relay — dev tool for notifications, crash alerts, deploy pings, and more

Package Exports

  • iris-relay

Readme

iris-relay

Lightweight Telegram relay dev tool — crash alerts, deploy notifications, heartbeats, and more. Zero-config, tree-shakeable, built-in .env loading.

Install

# pnpm
pnpm add iris-relay

# npm
npm install iris-relay

Setup

Run the interactive setup wizard:

# pnpm
pnpm dlx iris-relay init

# npm
npx iris-relay init

Or manually create a .env file:

XERO_BOT_TOKEN=your_bot_token_from_botfather
XERO_CHAT_ID=your_telegram_chat_id

Bot Token@BotFather · Chat ID@userinfobot

No dotenv import needed — iris-relay auto-loads your .env.


Quick Start

import { relay } from "iris-relay";

await relay("Hello from my server! 🚀");

Features

📨 Core Relay

import { relay, createRelay } from "iris-relay";

// One-off message
await relay("Server started");

// 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 ✅");

🚨 Error Relay

import { relayError } from "iris-relay";

try {
  dangerousOperation();
} catch (err) {
  await relayError(err); // sends formatted stack trace
}

📋 JSON Relay

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.

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):

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

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

import { relayFile } from "iris-relay";

await relayFile("./logs/error.log", "Latest error log");

💀 Process Crash Watcher

import { watchProcess } from "iris-relay";

watchProcess(); // done — uncaught exceptions & rejections get reported

💓 Heartbeat

import { startHeartbeat } from "iris-relay";

const stop = startHeartbeat({
  interval: 60_000,   // every minute
  app: "my-api",
});

// Later: stop();

🔌 Express Middleware

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

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");

🧪 Dry Run Mode

Set XERO_DRY_RUN=true in .env to log messages to console instead of sending to Telegram. Perfect for local development.


Getting Started

# pnpm
pnpm dlx iris-relay init

# npm
npx iris-relay init

The setup wizard will:

Step 1 — Credentials

  • Ask for your Bot Token (from @BotFather)
  • Ask for your Chat ID (from @userinfobot)

Step 2 — Features (auto-detects your framework & package manager)

  • 🛡️ Crash watcher — auto-report uncaught exceptions
  • 💓 Heartbeat — periodic alive pings with custom interval
  • 🔌 Express/Fastify middleware — slow request & error reporting (only if detected)
  • 🧪 Dry run mode — log to console instead of sending

Step 3 — Scaffolding

  • 📄 Generates iris.ts or iris.js starter file with selected features pre-wired
  • 🚀 GitHub Actions deploy notification workflow
  • 🐳 Docker Compose env var setup

Then → writes .env, updates .gitignore, sends a test message ✅


CLI

# Interactive setup
pnpm dlx iris-relay init   # or: npx iris-relay init

# Send a message
pnpm dlx iris-relay "Deploy complete ✅"   # or: npx iris-relay "..."

# Send with HTML
pnpm dlx iris-relay --html "<b>Bold</b> message"

# Send a file
pnpm dlx iris-relay --file ./logs/error.log "Error log attached"

# Silent (no notification sound)
pnpm dlx iris-relay --silent "Background update"

API Reference

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

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

License

MIT