@assemora/notifications 0.1.0

package/dist/telegram.js

@@ -0,0 +1,94 @@
+/**
+ * The Telegram driver (SPEC.md §81).
+ *
+ * A bot, a chat id and one method of the Bot API. It is the only file in this
+ * repository that knows Telegram exists, and it holds no state beyond its token — the
+ * same bargain `s3-storage.ts` makes with a bucket.
+ *
+ * There is deliberately no `parse_mode`. Telegram then reads the text literally, so a
+ * customer called `*Ада*` arrives as those characters and a comment holding an HTML
+ * tag cannot close one the message never opened. Formatting would have to be escaped
+ * value by value, and a missed escape is not a cosmetic bug: it is a stranger writing
+ * markup into a staff channel.
+ */
+import { ConfigurationError } from '@assemora/core';
+import { rejected, unreachable } from './channel.js';
+/**
+ * Telegram's own ceiling, in UTF-16 code units, and the message is cut to fit.
+ *
+ * Refusing instead would be defensible for a message a person wrote; this is a
+ * rendered notification, and half a kitchen order is worth more than none. The cut is
+ * visible in the message so nobody reads a truncated address as a complete one.
+ */
+const LIMIT = 4096;
+const CUT = '…';
+/**
+ * Whether Telegram's refusal is about this address or about this moment.
+ *
+ * 429 is the rate limit and 5xx is Telegram itself, and both mean "later". Everything
+ * else — a chat that does not exist, a bot nobody started, a revoked token — is the
+ * same answer however many times it is asked.
+ */
+const isMomentary = (status) => status === 429 || status >= 500;
+const bodyOf = async (response) => {
+    try {
+        return (await response.json());
+    }
+    catch {
+        return {};
+    }
+};
+export const telegram = (options) => {
+    if (options.token.trim() === '') {
+        throw new ConfigurationError('The Telegram channel was given an empty bot token. Set TELEGRAM_BOT_TOKEN, or leave the channel out until there is one.');
+    }
+    const api = (options.api ?? 'https://api.telegram.org').replace(/\/+$/, '');
+    const send = options.fetch ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    return {
+        name: 'telegram',
+        async send(address, message) {
+            const text = message.text.length > LIMIT
+                ? `${message.text.slice(0, LIMIT - CUT.length)}${CUT}`
+                : message.text;
+            let response;
+            try {
+                response = await send(`${api}/bot${options.token}/sendMessage`, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({
+                        chat_id: address,
+                        text,
+                        // A staff channel wants the order, not a preview card of whatever URL the
+                        // message happens to carry.
+                        disable_web_page_preview: true,
+                    }),
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+            }
+            catch (cause) {
+                // A refused connection, a DNS failure, the timeout above. None of them say
+                // anything about the address.
+                throw unreachable('Telegram could not be reached', {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                });
+            }
+            if (response.ok)
+                return;
+            const answer = await bodyOf(response);
+            // Telegram's own text, which names the reason: "chat not found", "bot was
+            // blocked by the user", "Unauthorized". It carries no token and no message body.
+            const description = answer.description ?? `HTTP ${response.status}`;
+            if (isMomentary(response.status)) {
+                throw unreachable(`Telegram refused for now: ${description}`, {
+                    status: response.status,
+                    ...(answer.parameters?.retry_after === undefined
+                        ? {}
+                        : { retryAfter: answer.parameters.retry_after }),
+                });
+            }
+            throw rejected(`Telegram refused this chat: ${description}`, { status: response.status });
+        },
+    };
+};
+//# sourceMappingURL=telegram.js.map

package/dist/telegram.js.map

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@assemora/notifications",
+  "version": "0.1.0",
+  "description": "Outbound notifications: what an application announces, to whom, and over which channel (SPEC.md §81)",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/assemora/assemora.git",
+    "directory": "packages/notifications"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@assemora/schema": "0.1.0",
+    "@assemora/data": "0.1.0",
+    "@assemora/core": "0.1.0",
+    "@assemora/resources": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "@assemora/database": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}