iris-relay 1.0.0

package/README.md

@@ -0,0 +1,85 @@
+# iris-relay
+
+Lightweight, zero-dependency Telegram message relay. Tree-shakeable ESM package with built-in `.env` loading — true plug-and-play.
+
+## Install
+
+```bash
+pnpm add iris-relay
+```
+
+## Setup
+
+Create a `.env` file in your project root:
+
+```env
+XERO_BOT_TOKEN=your_bot_token_from_botfather
+XERO_CHAT_ID=your_telegram_chat_id
+```
+
+> **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
+
+That's it. No dotenv import needed — `iris-relay` auto-loads your `.env` file.
+
+## Usage
+
+### One-off message
+
+```ts
+import { relay } from "iris-relay";
+
+await relay("Hello from my server! 🚀");
+```
+
+### Pre-configured sender
+
+```ts
+import { createRelay } from "iris-relay";
+
+const send = createRelay({
+  botToken: process.env.XERO_BOT_TOKEN,
+  chatId: process.env.XERO_CHAT_ID,
+});
+
+await send("Deploy successful ✅");
+await send("Build failed ❌");
+```
+
+### Options
+
+```ts
+await relay("Check this out", {
+  parseMode: "HTML",       // HTML | Markdown | MarkdownV2
+  disablePreview: true,    // no link previews
+  silent: true,            // no notification sound
+});
+```
+
+## API
+
+### `relay(message, config?): Promise<RelayResult>`
+
+Send a single message. Returns `{ success: boolean, messageId?: number, error?: string }`.
+
+| 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 |
+
+### `createRelay(config): (message, overrides?) => Promise<RelayResult>`
+
+Create a pre-configured sender function. Useful when sending multiple messages with the same config.
+
+## Requirements
+
+- Node.js ≥ 18 (uses native `fetch`)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { relay, createRelay } from "./relay.js";
+export type { RelayConfig, RelayResult, TelegramResponse } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAChD,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { relay, createRelay } from "./relay.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/relay.d.ts

@@ -0,0 +1,27 @@
+import type { RelayConfig, RelayResult } from "./types.js";
+/**
+ * Send a one-off message to your Telegram chat.
+ *
+ * Reads `IRIS_BOT_TOKEN` and `IRIS_CHAT_ID` from env, or accepts them via config.
+ *
+ * @example
+ * ```ts
+ * import { relay } from "iris";
+ * await relay("Hello from my server!");
+ * ```
+ */
+export declare function relay(message: string, config?: RelayConfig): Promise<RelayResult>;
+/**
+ * Create a pre-configured relay function with baked-in credentials.
+ *
+ * @example
+ * ```ts
+ * import { createRelay } from "iris";
+ *
+ * const send = createRelay({ botToken: "...", chatId: "..." });
+ * await send("Deploy successful ✅");
+ * await send("Build failed ❌");
+ * ```
+ */
+export declare function createRelay(config: RelayConfig): (message: string, overrides?: Partial<RelayConfig>) => Promise<RelayResult>;
+//# sourceMappingURL=relay.d.ts.map

package/dist/relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAoB,MAAM,YAAY,CAAC;AAkB7E;;;;;;;;;;GAUG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAsBvF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,IAEnC,SAAS,MAAM,EAAE,YAAY,OAAO,CAAC,WAAW,CAAC,KAAG,OAAO,CAAC,WAAW,CAAC,CAEnF"}

package/dist/relay.js

@@ -0,0 +1,62 @@
+import { config } from "dotenv";
+// Auto-load .env on import — true plug-and-play
+config();
+const TG_API = "https://api.telegram.org";
+function resolveConfig(overrides) {
+    const botToken = overrides?.botToken
+        ?? process.env.XERO_BOT_TOKEN;
+    const chatId = overrides?.chatId
+        ?? process.env.XERO_CHAT_ID;
+    if (!botToken)
+        throw new Error("iris: botToken is required — pass it in config or set XERO_BOT_TOKEN env var");
+    if (!chatId)
+        throw new Error("iris: chatId is required — pass it in config or set XERO_CHAT_ID env var");
+    return { botToken, chatId, ...overrides };
+}
+/**
+ * Send a one-off message to your Telegram chat.
+ *
+ * Reads `IRIS_BOT_TOKEN` and `IRIS_CHAT_ID` from env, or accepts them via config.
+ *
+ * @example
+ * ```ts
+ * import { relay } from "iris";
+ * await relay("Hello from my server!");
+ * ```
+ */
+export async function relay(message, config) {
+    const { botToken, chatId, parseMode, disablePreview, silent } = resolveConfig(config);
+    const res = await fetch(`${TG_API}/bot${botToken}/sendMessage`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            chat_id: chatId,
+            text: message,
+            ...(parseMode && { parse_mode: parseMode }),
+            ...(disablePreview && { disable_web_page_preview: true }),
+            ...(silent && { disable_notification: true }),
+        }),
+    });
+    const data = (await res.json());
+    if (!data.ok) {
+        return { success: false, error: data.description ?? `Telegram API error (${data.error_code})` };
+    }
+    return { success: true, messageId: data.result?.message_id };
+}
+/**
+ * Create a pre-configured relay function with baked-in credentials.
+ *
+ * @example
+ * ```ts
+ * import { createRelay } from "iris";
+ *
+ * const send = createRelay({ botToken: "...", chatId: "..." });
+ * await send("Deploy successful ✅");
+ * await send("Build failed ❌");
+ * ```
+ */
+export function createRelay(config) {
+    const resolved = resolveConfig(config);
+    return (message, overrides) => relay(message, { ...resolved, ...overrides });
+}
+//# sourceMappingURL=relay.js.map

package/dist/relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.js","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,gDAAgD;AAChD,MAAM,EAAE,CAAC;AAET,MAAM,MAAM,GAAG,0BAA0B,CAAC;AAE1C,SAAS,aAAa,CAAC,SAAuB;IAC1C,MAAM,QAAQ,GAAG,SAAS,EAAE,QAAQ;WAC7B,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAClC,MAAM,MAAM,GAAG,SAAS,EAAE,MAAM;WACzB,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IAChC,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;IAC/G,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,0EAA0E,CAAC,CAAC;IAEzG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,OAAe,EAAE,MAAoB;IAC7D,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAEtF,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,MAAM,OAAO,QAAQ,cAAc,EAAE;QAC5D,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;YACjB,OAAO,EAAE,MAAM;YACf,IAAI,EAAE,OAAO;YACb,GAAG,CAAC,SAAS,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;YAC3C,GAAG,CAAC,cAAc,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,CAAC;YACzD,GAAG,CAAC,MAAM,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC;SAChD,CAAC;KACL,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAqB,CAAC;IAEpD,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACX,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,WAAW,IAAI,uBAAuB,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;IACpG,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,MAAmB;IAC3C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,OAAO,CAAC,OAAe,EAAE,SAAgC,EAAwB,EAAE,CAC/E,KAAK,CAAC,OAAO,EAAE,EAAE,GAAG,QAAQ,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;AACtD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+export interface RelayConfig {
+    /** Telegram Bot API token from @BotFather */
+    botToken?: string;
+    /** Your Telegram chat ID */
+    chatId?: string;
+    /** Parse mode for messages: HTML, Markdown, or MarkdownV2 */
+    parseMode?: "HTML" | "Markdown" | "MarkdownV2";
+    /** Disable link previews in messages */
+    disablePreview?: boolean;
+    /** Send message silently (no notification sound) */
+    silent?: boolean;
+}
+export interface TelegramResponse {
+    ok: boolean;
+    result?: {
+        message_id: number;
+        chat: {
+            id: number;
+            type: string;
+        };
+        text: string;
+        date: number;
+    };
+    description?: string;
+    error_code?: number;
+}
+export interface RelayResult {
+    success: boolean;
+    messageId?: number;
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,YAAY,CAAC;IAC/C,wCAAwC;IACxC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE;QACL,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QACnC,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "iris-relay",
+  "version": "1.0.0",
+  "description": "Lightweight, zero-dependency Telegram message relay",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "telegram",
+    "relay",
+    "bot",
+    "message",
+    "notification"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "dotenv": "^17.3.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsx test.ts"
+  }
+}