@jhb0430/telegram 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jhb0430
+
+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

@@ -0,0 +1,139 @@
+# @jhb0430/telegram
+
+텔레그램 봇으로 **텍스트 한 통**을 보내는 클라이언트입니다.
+
+봇 토큰과 채팅방 ID를 넣고 `sendMessage`를 호출하면 끝입니다. 사진, 답장, 토픽, 로그 릴레이 서버는 없습니다.
+
+## 설치
+
+```bash
+npm install @jhb0430/telegram
+```
+
+NestJS는 선택입니다. Nest를 쓰지 않으면 `@nestjs/common`이 없어도 됩니다.
+
+## 환경 변수
+
+프로세스에 아래 세 값이 있으면 됩니다.
+
+| 변수 | 값 |
+|------|-----|
+| `TELEGRAM_ENABLED` | `true` 또는 `1` 이면 전송. `false` / `0` 이면 보내지 않음 |
+| `TELEGRAM_BOT_TOKEN` | BotFather가 준 토큰 |
+| `TELEGRAM_CHAT_ID` | 메시지를 받을 채팅방 ID |
+
+채팅방 ID는 봇에게 `/start`를 보낸 뒤 `https://api.telegram.org/bot<토큰>/getUpdates`의 `message.chat.id`입니다.
+
+프로젝트마다 키 이름이 다르면 `envKeys`로 넘깁니다. 아래 「다른 키 이름」을 보세요.
+
+## 보내기
+
+```typescript
+import { TelegramBotClient } from '@jhb0430/telegram';
+
+const telegram = new TelegramBotClient();
+
+const result = await telegram.sendMessage('서버가 시작되었습니다.');
+if (result.delivered) {
+  // 채팅방에 도착함
+} else {
+  // result.reason, result.status 를 로그에 남기면 됩니다.
+}
+```
+
+`sendMessage`는 예외를 던지지 않습니다. 알림 실패가 요청 처리를 막지 않게 하기 위해서입니다.
+
+| `result` | 의미 |
+|----------|------|
+| `delivered: true` | Bot API가 성공으로 응답함 |
+| `delivered: false`, `reason: 'not_configured'` | 꺼져 있거나 토큰·채팅방 ID가 없음 |
+| `delivered: false`, `reason: 'http_error'`, `status: 401` | 토큰이 틀리거나 봇이 그 방에 없음 |
+| `delivered: false`, `reason: 'request_failed'` | 타임아웃·네트워크 오류. `status`는 없음 |
+
+토큰 문자열은 결과와 로그에 넣지 않습니다.
+
+설정만 확인할 때는 `telegram.isConfigured()`를 쓰면 됩니다.
+
+## 굵은 글씨
+
+전송은 항상 텔레그램 HTML 모드입니다. 호출자가 넣은 `<b>`, `<i>`, `<code>`, `<pre>`, `<a href="https://...">` 는 태그로 두고, 그 사이 본문의 `<`, `>`, `&` 만 이스케이프합니다.
+
+```typescript
+const text = telegram.formatHtml([
+  '🚨 <b>[prod] API 500</b>',
+  '<b>GET</b> /health',
+  'detail: a < b & c',
+]);
+await telegram.sendMessage(text);
+```
+
+채팅에는 제목과 `GET`이 굵게 나오고, `a < b & c`는 글자로 보입니다. `<script>`처럼 허용되지 않은 태그는 글자 그대로 이스케이프됩니다.
+
+빈 줄과 `null`은 빠집니다.
+
+## 코드로 토큰 넘기기
+
+env 대신 파일·설정 객체에 토큰이 있으면 `fileFallback`에 넣습니다. env가 있으면 env가 우선입니다.
+
+```typescript
+const telegram = new TelegramBotClient({
+  fileFallback: {
+    enabled: true,
+    botToken: config.telegram.botToken,
+    chatId: config.telegram.chatId,
+  },
+});
+```
+
+## 다른 키 이름
+
+기본 키를 쓰지 않는 프로젝트는 이름을 지정합니다.
+
+```typescript
+const telegram = new TelegramBotClient({
+  envKeys: {
+    enabled: 'TELEGRAM_DEV_ALERTS_ENABLED',
+    botToken: 'TELEGRAM_DEV_BOT_TOKEN',
+    chatId: 'TELEGRAM_DEV_CHAT_ID',
+  },
+});
+```
+
+## NestJS
+
+```typescript
+import { Module } from '@nestjs/common';
+import { TelegramModule, TelegramBotService } from '@jhb0430/telegram';
+
+@Module({
+  imports: [
+    TelegramModule.forRoot({
+      fileFallback: {
+        enabled: true,
+        botToken: process.env.TELEGRAM_BOT_TOKEN,
+        chatId: process.env.TELEGRAM_CHAT_ID,
+      },
+    }),
+  ],
+})
+export class AppModule {}
+
+// 다른 서비스에서 주입
+constructor(private readonly telegram: TelegramBotService) {}
+
+await this.telegram.sendMessage('안녕하세요');
+```
+
+`TelegramBotService.sendMessage`의 반환값은 `TelegramBotClient`와 같습니다.
+
+## 부팅 전에 env 파일 읽기
+
+`.env` 파일을 프로세스에 올린 뒤 앱을 띄울 때 씁니다. `TELEGRAM_`으로 시작하는 키만 읽습니다.
+
+```bash
+TELEGRAM_ENV_FILE=/path/to/telegram.env node -r @jhb0430/telegram/preload dist/main.js
+```
+
+이 preload는 `CONFIG_SOURCE` 같은 다른 설정을 바꾸지 않습니다. 파일이 없으면 아무 것도 하지 않습니다.
+
+예시 파일은 패키지 안의 `config/telegram.env.example`입니다.

package/config/telegram.env.example

@@ -0,0 +1,19 @@
+# Telegram Bot API — 공통 env 예시
+# 사용법:
+#   cp config/telegram.env.example telegram.dev.env
+#   vi telegram.dev.env
+#
+# Nest API 등에서 부트 전 로드:
+#   TELEGRAM_ENV_FILE=/path/to/telegram.dev.env node -r @jhb0430/telegram/preload dist/main.js
+#
+# 기본 키는 TELEGRAM_ENABLED / TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID 다.
+# kcpg-wallet 개발팀 알림은 TELEGRAM_DEV_* 를 쓰고, 앱이 envKeys 로 넘긴다.
+#
+# chat_id 확인 (봇에게 /start 보낸 뒤):
+#   https://api.telegram.org/bot<TOKEN>/getUpdates  → message.chat.id
+#
+# 이 파일은 git에 올리지 마세요. 실제 비밀값은 telegram.dev.env 만 로컬/서버에 둡니다.
+
+TELEGRAM_ENABLED=true
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+import type { ResolveTelegramConfigOptions, ResolvedTelegramConfig, TelegramLogger, TelegramSendResult } from './types';
+export declare class TelegramBotClient {
+    private readonly options;
+    private readonly logger;
+    constructor(options?: ResolveTelegramConfigOptions, logger?: TelegramLogger);
+    getConfig(): ResolvedTelegramConfig;
+    isConfigured(): boolean;
+    formatHtml(lines: Array<string | undefined | null>): string;
+    /**
+     * Telegram Bot API `sendMessage`.
+     * 예외는 던지지 않고 `delivered`로 알린다. 알림 실패가 요청 처리를 막지 않게 하기 위해서다.
+     * 토큰이 틀리면 `delivered: false`와 HTTP status가 돌아간다.
+     */
+    sendMessage(text: string): Promise<TelegramSendResult>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,4BAA4B,EAC5B,sBAAsB,EACtB,cAAc,EACd,kBAAkB,EACnB,MAAM,SAAS,CAAC;AASjB,qBAAa,iBAAiB;IAI1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;gBAGrB,OAAO,GAAE,4BAAiC,EAC3D,MAAM,CAAC,EAAE,cAAc;IAKzB,SAAS,IAAI,sBAAsB;IAInC,YAAY,IAAI,OAAO;IAIvB,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,MAAM;IAI3D;;;;OAIG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAsC7D"}

package/dist/client.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelegramBotClient = void 0;
+const html_1 = require("./html");
+const config_1 = require("./config");
+const TELEGRAM_MESSAGE_MAX = 4096;
+const TELEGRAM_API_TIMEOUT_MS = 8000;
+const noopLogger = {
+    warn: () => undefined,
+};
+class TelegramBotClient {
+    constructor(options = {}, logger) {
+        this.options = options;
+        this.logger = logger ?? noopLogger;
+    }
+    getConfig() {
+        return (0, config_1.resolveTelegramConfig)(this.options);
+    }
+    isConfigured() {
+        return (0, config_1.isTelegramConfigured)(this.getConfig());
+    }
+    formatHtml(lines) {
+        return (0, html_1.formatTelegramHtml)(lines);
+    }
+    /**
+     * Telegram Bot API `sendMessage`.
+     * 예외는 던지지 않고 `delivered`로 알린다. 알림 실패가 요청 처리를 막지 않게 하기 위해서다.
+     * 토큰이 틀리면 `delivered: false`와 HTTP status가 돌아간다.
+     */
+    async sendMessage(text) {
+        if (!this.isConfigured()) {
+            return { delivered: false, reason: 'not_configured' };
+        }
+        const { botToken, chatId } = this.getConfig();
+        const body = (0, html_1.trimTelegramText)(text, TELEGRAM_MESSAGE_MAX);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), TELEGRAM_API_TIMEOUT_MS);
+        try {
+            const res = await fetch(`https://api.telegram.org/bot${botToken}/sendMessage`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    chat_id: chatId,
+                    text: body,
+                    parse_mode: 'HTML',
+                    disable_web_page_preview: true,
+                }),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const raw = await res.text().catch(() => '');
+                this.logger.warn(`Telegram sendMessage failed status=${res.status} body=${(0, html_1.trimTelegramText)(raw, 300)}`);
+                return { delivered: false, status: res.status, reason: 'http_error' };
+            }
+            return { delivered: true, status: res.status };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.logger.warn(`Telegram sendMessage error: ${message}`);
+            return { delivered: false, reason: 'request_failed' };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+exports.TelegramBotClient = TelegramBotClient;

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+import { type ResolveTelegramConfigOptions, type ResolvedTelegramConfig } from './types';
+/**
+ * env `TELEGRAM_*` 우선 — `telegram.dev.env` 등으로 켠 경우 YAML `enabled:false` 를 덮는다.
+ */
+export declare function resolveTelegramConfig(options?: ResolveTelegramConfigOptions): ResolvedTelegramConfig;
+export declare function isTelegramConfigured(config: ResolvedTelegramConfig): boolean;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC5B,MAAM,SAAS,CAAC;AASjB;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,4BAAiC,GAAG,sBAAsB,CAWxG;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAG5E"}

package/dist/config.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTelegramConfig = resolveTelegramConfig;
+exports.isTelegramConfigured = isTelegramConfigured;
+const types_1 = require("./types");
+function parseEnabledFlag(raw) {
+    const envFlag = String(raw ?? '').trim().toLowerCase();
+    if (envFlag === 'true' || envFlag === '1')
+        return true;
+    if (envFlag === 'false' || envFlag === '0')
+        return false;
+    return undefined;
+}
+/**
+ * env `TELEGRAM_*` 우선 — `telegram.dev.env` 등으로 켠 경우 YAML `enabled:false` 를 덮는다.
+ */
+function resolveTelegramConfig(options = {}) {
+    const keys = options.envKeys ?? types_1.DEFAULT_TELEGRAM_ENV_KEYS;
+    const fallback = options.fileFallback ?? {};
+    const envEnabled = parseEnabledFlag(process.env[keys.enabled]);
+    const enabled = envEnabled ?? fallback.enabled === true;
+    const botToken = String(process.env[keys.botToken] ?? fallback.botToken ?? '').trim();
+    const chatId = String(process.env[keys.chatId] ?? fallback.chatId ?? '').trim();
+    return { enabled, botToken, chatId };
+}
+function isTelegramConfigured(config) {
+    if (!config.enabled)
+        return false;
+    return config.botToken.length > 0 && config.chatId.length > 0;
+}

package/dist/env-file.d.ts

@@ -0,0 +1,7 @@
+import type { LoadEnvFileOptions } from './types';
+/**
+ * `.env` 형식 파일을 process.env 에 올린다.
+ * Nest 부트스트랩 전 preload·YAML sync 이후 재적용 모두 동일 함수로 처리한다.
+ */
+export declare function loadEnvFileIntoProcess(filePath: string, options?: LoadEnvFileOptions): number;
+//# sourceMappingURL=env-file.d.ts.map

package/dist/env-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-file.d.ts","sourceRoot":"","sources":["../src/env-file.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAalD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,CA0BjG"}

package/dist/env-file.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadEnvFileIntoProcess = loadEnvFileIntoProcess;
+const node_fs_1 = require("node:fs");
+function stripQuotes(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"'))
+        || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+/**
+ * `.env` 형식 파일을 process.env 에 올린다.
+ * Nest 부트스트랩 전 preload·YAML sync 이후 재적용 모두 동일 함수로 처리한다.
+ */
+function loadEnvFileIntoProcess(filePath, options = {}) {
+    const keyPrefix = options.keyPrefix ?? 'TELEGRAM_';
+    if (!(0, node_fs_1.existsSync)(filePath))
+        return 0;
+    const text = (0, node_fs_1.readFileSync)(filePath, 'utf8');
+    let loaded = 0;
+    for (const rawLine of text.split('\n')) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (!key.startsWith(keyPrefix))
+            continue;
+        process.env[key] = stripQuotes(line.slice(eq + 1));
+        loaded += 1;
+    }
+    if (loaded > 0 && options.setConfigSourceOnLoad && !process.env.CONFIG_SOURCE) {
+        process.env.CONFIG_SOURCE = 'yamlWithEnvOverrides';
+    }
+    return loaded;
+}

package/dist/html.d.ts

@@ -0,0 +1,6 @@
+export declare function escapeTelegramHtml(value: string): string;
+export declare function escapeTelegramHtmlPreservingTags(value: string): string;
+export declare function trimTelegramText(value: string, max: number): string;
+/** HTML parse_mode 용 — 빈 줄은 버리고, 허용 태그는 유지한 채 본문만 escape 한다. */
+export declare function formatTelegramHtml(lines: Array<string | undefined | null>): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAAA,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKxD;AASD,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYtE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAInE;AAED,gEAAgE;AAChE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,MAAM,CAKlF"}

package/dist/html.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeTelegramHtml = escapeTelegramHtml;
+exports.escapeTelegramHtmlPreservingTags = escapeTelegramHtmlPreservingTags;
+exports.trimTelegramText = trimTelegramText;
+exports.formatTelegramHtml = formatTelegramHtml;
+function escapeTelegramHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+/**
+ * Bot API HTML에서 허용하는 태그만 그대로 두고, 그 사이 본문은 escape 한다.
+ * `<b>` 같은 호출자 마크업은 유지하고, `<script>`·본문의 `<`는 이스케이프한다.
+ */
+const TELEGRAM_HTML_TAG = /<\/?(?:b|strong|i|em|u|ins|s|strike|del|code|pre|blockquote|tg-spoiler)>|<a\s+href="(?:https?:\/\/|tg:\/\/)[^"]*">|<\/a>|<span\s+class="tg-spoiler">|<\/span>/gi;
+function escapeTelegramHtmlPreservingTags(value) {
+    const tags = new RegExp(TELEGRAM_HTML_TAG.source, 'gi');
+    let out = '';
+    let last = 0;
+    for (const match of value.matchAll(tags)) {
+        const index = match.index ?? 0;
+        out += escapeTelegramHtml(value.slice(last, index));
+        out += match[0];
+        last = index + match[0].length;
+    }
+    out += escapeTelegramHtml(value.slice(last));
+    return out;
+}
+function trimTelegramText(value, max) {
+    const trimmed = value.trim();
+    if (trimmed.length <= max)
+        return trimmed;
+    return `${trimmed.slice(0, Math.max(0, max - 3))}...`;
+}
+/** HTML parse_mode 용 — 빈 줄은 버리고, 허용 태그는 유지한 채 본문만 escape 한다. */
+function formatTelegramHtml(lines) {
+    return lines
+        .filter((line) => typeof line === 'string' && line.trim().length > 0)
+        .map((line) => escapeTelegramHtmlPreservingTags(line))
+        .join('\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { TelegramBotClient } from './client';
+export { resolveTelegramConfig, isTelegramConfigured } from './config';
+export { loadEnvFileIntoProcess } from './env-file';
+export { escapeTelegramHtml, escapeTelegramHtmlPreservingTags, trimTelegramText, formatTelegramHtml } from './html';
+export { DEFAULT_TELEGRAM_ENV_KEYS, type LoadEnvFileOptions, type ResolveTelegramConfigOptions, type ResolvedTelegramConfig, type TelegramBotFileConfig, type TelegramEnvKeyNames, type TelegramLogger, type TelegramSendResult, } from './types';
+export { TelegramBotService, TelegramModule, TELEGRAM_BOT_OPTIONS, type TelegramBotModuleOptions, } from './nest';
+//# 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,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,gCAAgC,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AACpH,OAAO,EACL,yBAAyB,EACzB,KAAK,kBAAkB,EACvB,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,KAAK,wBAAwB,GAC9B,MAAM,QAAQ,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEGRAM_BOT_OPTIONS = exports.TelegramModule = exports.TelegramBotService = exports.DEFAULT_TELEGRAM_ENV_KEYS = exports.formatTelegramHtml = exports.trimTelegramText = exports.escapeTelegramHtmlPreservingTags = exports.escapeTelegramHtml = exports.loadEnvFileIntoProcess = exports.isTelegramConfigured = exports.resolveTelegramConfig = exports.TelegramBotClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "TelegramBotClient", { enumerable: true, get: function () { return client_1.TelegramBotClient; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "resolveTelegramConfig", { enumerable: true, get: function () { return config_1.resolveTelegramConfig; } });
+Object.defineProperty(exports, "isTelegramConfigured", { enumerable: true, get: function () { return config_1.isTelegramConfigured; } });
+var env_file_1 = require("./env-file");
+Object.defineProperty(exports, "loadEnvFileIntoProcess", { enumerable: true, get: function () { return env_file_1.loadEnvFileIntoProcess; } });
+var html_1 = require("./html");
+Object.defineProperty(exports, "escapeTelegramHtml", { enumerable: true, get: function () { return html_1.escapeTelegramHtml; } });
+Object.defineProperty(exports, "escapeTelegramHtmlPreservingTags", { enumerable: true, get: function () { return html_1.escapeTelegramHtmlPreservingTags; } });
+Object.defineProperty(exports, "trimTelegramText", { enumerable: true, get: function () { return html_1.trimTelegramText; } });
+Object.defineProperty(exports, "formatTelegramHtml", { enumerable: true, get: function () { return html_1.formatTelegramHtml; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "DEFAULT_TELEGRAM_ENV_KEYS", { enumerable: true, get: function () { return types_1.DEFAULT_TELEGRAM_ENV_KEYS; } });
+var nest_1 = require("./nest");
+Object.defineProperty(exports, "TelegramBotService", { enumerable: true, get: function () { return nest_1.TelegramBotService; } });
+Object.defineProperty(exports, "TelegramModule", { enumerable: true, get: function () { return nest_1.TelegramModule; } });
+Object.defineProperty(exports, "TELEGRAM_BOT_OPTIONS", { enumerable: true, get: function () { return nest_1.TELEGRAM_BOT_OPTIONS; } });

package/dist/nest/index.d.ts

@@ -0,0 +1,4 @@
+export { TelegramBotService } from './telegram-bot.service';
+export { TelegramModule } from './telegram.module';
+export { TELEGRAM_BOT_OPTIONS, type TelegramBotModuleOptions } from './telegram.tokens';
+//# sourceMappingURL=index.d.ts.map

package/dist/nest/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/nest/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/nest/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEGRAM_BOT_OPTIONS = exports.TelegramModule = exports.TelegramBotService = void 0;
+var telegram_bot_service_1 = require("./telegram-bot.service");
+Object.defineProperty(exports, "TelegramBotService", { enumerable: true, get: function () { return telegram_bot_service_1.TelegramBotService; } });
+var telegram_module_1 = require("./telegram.module");
+Object.defineProperty(exports, "TelegramModule", { enumerable: true, get: function () { return telegram_module_1.TelegramModule; } });
+var telegram_tokens_1 = require("./telegram.tokens");
+Object.defineProperty(exports, "TELEGRAM_BOT_OPTIONS", { enumerable: true, get: function () { return telegram_tokens_1.TELEGRAM_BOT_OPTIONS; } });

package/dist/nest/telegram-bot.service.d.ts

@@ -0,0 +1,10 @@
+import type { ResolveTelegramConfigOptions, TelegramSendResult } from '../types';
+export declare class TelegramBotService {
+    private readonly client;
+    private readonly logger;
+    constructor(options?: ResolveTelegramConfigOptions);
+    isConfigured(): boolean;
+    formatHtml(lines: Array<string | undefined | null>): string;
+    sendMessage(text: string): Promise<TelegramSendResult>;
+}
+//# sourceMappingURL=telegram-bot.service.d.ts.map

package/dist/nest/telegram-bot.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-bot.service.d.ts","sourceRoot":"","sources":["../../src/nest/telegram-bot.service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,4BAA4B,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAGjF,qBACa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;gBAGlB,OAAO,CAAC,EAAE,4BAA4B;IAKlF,YAAY,IAAI,OAAO;IAIvB,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,MAAM;IAIrD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAG7D"}

package/dist/nest/telegram-bot.service.js

@@ -0,0 +1,41 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var TelegramBotService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelegramBotService = void 0;
+const common_1 = require("@nestjs/common");
+const client_1 = require("../client");
+const telegram_tokens_1 = require("./telegram.tokens");
+let TelegramBotService = TelegramBotService_1 = class TelegramBotService {
+    constructor(options) {
+        this.logger = new common_1.Logger(TelegramBotService_1.name);
+        this.client = new client_1.TelegramBotClient(options ?? {}, this.logger);
+    }
+    isConfigured() {
+        return this.client.isConfigured();
+    }
+    formatHtml(lines) {
+        return this.client.formatHtml(lines);
+    }
+    async sendMessage(text) {
+        return this.client.sendMessage(text);
+    }
+};
+exports.TelegramBotService = TelegramBotService;
+exports.TelegramBotService = TelegramBotService = TelegramBotService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(telegram_tokens_1.TELEGRAM_BOT_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], TelegramBotService);

package/dist/nest/telegram.module.d.ts

@@ -0,0 +1,6 @@
+import { DynamicModule } from '@nestjs/common';
+import { type TelegramBotModuleOptions } from './telegram.tokens';
+export declare class TelegramModule {
+    static forRoot(options?: TelegramBotModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=telegram.module.d.ts.map

package/dist/nest/telegram.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.module.d.ts","sourceRoot":"","sources":["../../src/nest/telegram.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAU,MAAM,gBAAgB,CAAC;AAGvD,OAAO,EAAwB,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAExF,qBACa,cAAc;IACzB,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,wBAA6B,GAAG,aAAa;CAatE"}

package/dist/nest/telegram.module.js

@@ -0,0 +1,32 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var TelegramModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelegramModule = void 0;
+const common_1 = require("@nestjs/common");
+const telegram_bot_service_1 = require("./telegram-bot.service");
+const telegram_tokens_1 = require("./telegram.tokens");
+let TelegramModule = TelegramModule_1 = class TelegramModule {
+    static forRoot(options = {}) {
+        return {
+            module: TelegramModule_1,
+            providers: [
+                {
+                    provide: telegram_tokens_1.TELEGRAM_BOT_OPTIONS,
+                    useValue: options,
+                },
+                telegram_bot_service_1.TelegramBotService,
+            ],
+            exports: [telegram_bot_service_1.TelegramBotService],
+        };
+    }
+};
+exports.TelegramModule = TelegramModule;
+exports.TelegramModule = TelegramModule = TelegramModule_1 = __decorate([
+    (0, common_1.Module)({})
+], TelegramModule);

package/dist/nest/telegram.tokens.d.ts

@@ -0,0 +1,4 @@
+import type { ResolveTelegramConfigOptions } from '../types';
+export declare const TELEGRAM_BOT_OPTIONS: unique symbol;
+export type TelegramBotModuleOptions = ResolveTelegramConfigOptions;
+//# sourceMappingURL=telegram.tokens.d.ts.map

package/dist/nest/telegram.tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.tokens.d.ts","sourceRoot":"","sources":["../../src/nest/telegram.tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC;AAE7D,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE,MAAM,MAAM,wBAAwB,GAAG,4BAA4B,CAAC"}

package/dist/nest/telegram.tokens.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEGRAM_BOT_OPTIONS = void 0;
+exports.TELEGRAM_BOT_OPTIONS = Symbol('TELEGRAM_BOT_OPTIONS');

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+/** env·YAML 등에서 읽은 Bot 설정 (프로젝트별 fallback) */
+export type TelegramBotFileConfig = {
+    enabled?: boolean;
+    botToken?: string;
+    chatId?: string;
+};
+export type TelegramEnvKeyNames = {
+    enabled: string;
+    botToken: string;
+    chatId: string;
+};
+/** 패키지 기본 env. 프로젝트별 키는 `envKeys`로 넘긴다. */
+export declare const DEFAULT_TELEGRAM_ENV_KEYS: TelegramEnvKeyNames;
+export type TelegramSendResult = {
+    delivered: boolean;
+    /** Bot API가 응답한 HTTP status. 네트워크 실패면 없다. */
+    status?: number;
+    /** `not_configured` | `http_error` | `request_failed`. 토큰은 넣지 않는다. */
+    reason?: 'not_configured' | 'http_error' | 'request_failed';
+};
+export type ResolveTelegramConfigOptions = {
+    /** process.env 키 이름. 기본은 `TELEGRAM_ENABLED` / `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID`. */
+    envKeys?: TelegramEnvKeyNames;
+    /** YAML 등 파일 기반 fallback */
+    fileFallback?: TelegramBotFileConfig;
+};
+export type ResolvedTelegramConfig = {
+    enabled: boolean;
+    botToken: string;
+    chatId: string;
+};
+export type TelegramLogger = {
+    warn(message: string): void;
+    log?(message: string): void;
+    debug?(message: string): void;
+};
+export type LoadEnvFileOptions = {
+    /** 이 prefix 로 시작하는 키만 process.env 에 올린다 */
+    keyPrefix?: string;
+    /** 로드된 키가 있고 CONFIG_SOURCE 가 비어 있으면 yamlWithEnvOverrides 로 설정 */
+    setConfigSourceOnLoad?: boolean;
+};
+//# 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,8CAA8C;AAC9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,2CAA2C;AAC3C,eAAO,MAAM,yBAAyB,EAAE,mBAIvC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,gBAAgB,GAAG,YAAY,GAAG,gBAAgB,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,4FAA4F;IAC5F,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,4BAA4B;IAC5B,YAAY,CAAC,EAAE,qBAAqB,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC"}

package/dist/types.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TELEGRAM_ENV_KEYS = void 0;
+/** 패키지 기본 env. 프로젝트별 키는 `envKeys`로 넘긴다. */
+exports.DEFAULT_TELEGRAM_ENV_KEYS = {
+    enabled: 'TELEGRAM_ENABLED',
+    botToken: 'TELEGRAM_BOT_TOKEN',
+    chatId: 'TELEGRAM_CHAT_ID',
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@jhb0430/telegram",
+  "version": "0.1.0",
+  "description": "Telegram Bot API client — reusable across projects",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "scripts",
+    "config"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./nest": {
+      "types": "./dist/nest/index.d.ts",
+      "require": "./dist/nest/index.js",
+      "default": "./dist/nest/index.js"
+    },
+    "./preload": "./scripts/preload-env.cjs"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "test": "yarn build && node --test test/*.test.cjs"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.0.0",
+    "@types/node": "^20.0.0",
+    "typescript": "~5.9.2"
+  }
+}

package/scripts/preload-env.cjs

@@ -0,0 +1,18 @@
+/**
+ * 프로세스 부트스트랩 전에 Telegram env 파일을 process.env 에 올린다.
+ *
+ * 사용:
+ *   node -r @jhb0430/telegram/preload dist/main.js
+ *   TELEGRAM_ENV_FILE=/path/to/telegram.dev.env node -r @jhb0430/telegram/preload dist/main.js
+ */
+const path = require('node:path');
+
+const { loadEnvFileIntoProcess } = require('../dist/env-file');
+
+const envFile =
+  process.env.TELEGRAM_ENV_FILE
+  || path.resolve(process.cwd(), 'telegram.dev.env');
+
+loadEnvFileIntoProcess(envFile, {
+  keyPrefix: process.env.TELEGRAM_ENV_KEY_PREFIX || 'TELEGRAM_',
+});