@theokit/gateway-telegram 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.12.0
4
+
5
+ ### Minor Changes
6
+
7
+ - c395723: Accept an `apiBase` option (and `TELEGRAM_API_BASE` in the channel descriptor) for the Bot API root; voice-note downloads use the same root.
8
+
9
+ ## 0.11.0
10
+
11
+ ### Minor Changes
12
+
13
+ - 4a4c25d: Ship `ChannelDescriptor`s with env bindings for `configFromEnv`: `discordChannel` and `slackChannel` are new, and `telegramChannel` and `lineChannel` gain `env` names. `create` accepts comma-separated list strings and `"true"`/`"false"` strings.
14
+
3
15
  ## 0.10.0
4
16
 
5
17
  ### Minor Changes
package/README.md CHANGED
@@ -38,6 +38,7 @@ import { TelegramAdapter } from "@theokit/gateway-telegram";
38
38
  const adapter = new TelegramAdapter({
39
39
  token: process.env.TELEGRAM_BOT_TOKEN!,
40
40
  allowedUsers: ["7528967933"], // optional
41
+ // apiBase: "http://localhost:8081", // optional, see below
41
42
  });
42
43
 
43
44
  const runner = new GatewayRunner({
@@ -50,6 +51,13 @@ const runner = new GatewayRunner({
50
51
  await runner.start();
51
52
  ```
52
53
 
54
+ ## Bot API root: `apiBase`
55
+
56
+ `apiBase` sets the Bot API root, for a self-hosted Bot API server or a fake one in tests. It
57
+ defaults to `https://api.telegram.org`. Every Bot API call, and the voice-note file download
58
+ (`<apiBase>/file/bot<token>/<path>`), goes to that root. A trailing slash is ignored. The 20 MB
59
+ voice-read limit is unchanged.
60
+
53
61
  ## Sending an image
54
62
 
55
63
  `ctx.reply(text, { attachments })` sends each image through `sendPhoto`, one request per image, in
@@ -121,6 +129,19 @@ refuses a token that is not a string or is empty, and an `allowedUsers` that is
121
129
  strings, with this package's `ConfigurationError` (also a `GatewayConfigurationError`), so
122
130
  `createChannels` lists that channel in `rejected` too.
123
131
 
132
+ ### Environment variables
133
+
134
+ | Field | Variable | Required | Secret |
135
+ | -------------- | ------------------------ | -------- | ------ |
136
+ | `token` | `TELEGRAM_TOKEN` | yes | yes |
137
+ | `allowedUsers` | `TELEGRAM_ALLOWED_USERS` | no | no |
138
+ | `apiBase` | `TELEGRAM_API_BASE` | no | no |
139
+
140
+ `configFromEnv(telegramChannel, process.env, "APP_")` reads `APP_TELEGRAM_TOKEN` and the rest into
141
+ `config`, lists unset required variables in `missing`, and puts the secret values in `secrets`.
142
+ `create` accepts `allowedUsers` as an array or a comma-separated string, and `requireMention` as a
143
+ boolean or `"true"`/`"false"`.
144
+
124
145
  ## Capabilities
125
146
 
126
147
  `adapter.capabilities` reports `edit`, `typing` and `reactions` as `true` and
package/dist/index.cjs CHANGED
@@ -111,8 +111,9 @@ function parseInbound(payload) {
111
111
  // src/read-voice.ts
112
112
  var MAX_VOICE_BYTES = 20 * 1024 * 1024;
113
113
  var READ_TIMEOUT_MS = 3e4;
114
+ var DEFAULT_API_BASE = "https://api.telegram.org";
114
115
  var DEFAULT_MEDIA_TYPE = "audio/ogg";
115
- async function readVoice(ctx, token, fetchImpl = fetch) {
116
+ async function readVoice(ctx, token, fetchImpl = fetch, apiBase = DEFAULT_API_BASE) {
116
117
  const voice = ctx.message?.voice ?? {};
117
118
  if (typeof voice.file_id !== "string") return { reason: "no_file_id" };
118
119
  if (typeof voice.file_size === "number" && voice.file_size > MAX_VOICE_BYTES) {
@@ -123,7 +124,7 @@ async function readVoice(ctx, token, fetchImpl = fetch) {
123
124
  try {
124
125
  const path = await filePath(ctx, controller.signal);
125
126
  if (typeof path !== "string") return path;
126
- const url = `https://api.telegram.org/file/bot${token}/${path}`;
127
+ const url = `${apiBase}/file/bot${token}/${path}`;
127
128
  const bytes = await download(url, fetchImpl, controller.signal);
128
129
  if (!(bytes instanceof Uint8Array)) return bytes;
129
130
  return { audio: { data: bytes, ...voiceDetails(voice) } };
@@ -513,12 +514,17 @@ var TelegramAdapter = class extends gateway.BasePlatformAdapter {
513
514
  handler;
514
515
  inbound;
515
516
  requireMention;
517
+ apiBase;
516
518
  warnedNoIdentity = false;
517
519
  connected = false;
518
520
  startPromise;
519
521
  constructor(opts) {
520
522
  super();
521
- this.bot = new grammy.Bot(opts.token);
523
+ this.apiBase = opts.apiBase === void 0 ? void 0 : opts.apiBase.replace(/\/+$/, "");
524
+ this.bot = new grammy.Bot(
525
+ opts.token,
526
+ this.apiBase === void 0 ? void 0 : { client: { apiRoot: this.apiBase } }
527
+ );
522
528
  this.allowedUsers = new Set(opts.allowedUsers ?? []);
523
529
  this.inbound = opts.inbound ?? "polling";
524
530
  this.requireMention = opts.requireMention === true;
@@ -738,7 +744,7 @@ var TelegramAdapter = class extends gateway.BasePlatformAdapter {
738
744
  */
739
745
  async withVoice(ctx, event) {
740
746
  if (ctx.message?.voice === void 0) return event;
741
- const read = await readVoice(ctx, this.bot.token);
747
+ const read = await readVoice(ctx, this.bot.token, void 0, this.apiBase);
742
748
  if ("audio" in read) return { ...event, audio: read.audio };
743
749
  process.stderr.write(`[telegram] voice not read: ${read.reason}
744
750
  `);
@@ -835,30 +841,50 @@ function readToken(config) {
835
841
  function readAllowedUsers(config) {
836
842
  const value = config.allowedUsers;
837
843
  if (value === void 0 || value === null) return void 0;
838
- if (!Array.isArray(value) || !value.every((id) => typeof id === "string")) {
839
- throw invalid("allowedUsers", "an array of user id strings");
844
+ const expected = "an array of user id strings or a comma-separated string of user ids";
845
+ const ids = typeof value === "string" ? value.split(",").map((id) => id.trim()) : value;
846
+ if (!Array.isArray(ids) || !ids.every((id) => typeof id === "string" && id.length > 0)) {
847
+ throw invalid("allowedUsers", expected);
840
848
  }
841
- return value;
849
+ return ids;
842
850
  }
843
851
  function readRequireMention(config) {
844
852
  const value = config.requireMention;
845
- if (value === void 0 || value === null) return void 0;
853
+ if (value === void 0) return void 0;
854
+ if (value === "true") return true;
855
+ if (value === "false") return false;
846
856
  if (typeof value !== "boolean") throw invalid("requireMention", "a boolean");
847
857
  return value;
848
858
  }
859
+ function readApiBase(config) {
860
+ const value = config.apiBase;
861
+ if (value === void 0 || value === null) return void 0;
862
+ if (typeof value !== "string" || value.length === 0)
863
+ throw invalid("apiBase", "a non-empty URL string");
864
+ return value;
865
+ }
849
866
  var CONFIG = [
850
867
  {
851
868
  key: "token",
869
+ env: "TELEGRAM_TOKEN",
852
870
  required: true,
853
871
  secret: true,
854
872
  description: "The bot token BotFather issued for this bot."
855
873
  },
856
874
  {
857
875
  key: "allowedUsers",
876
+ env: "TELEGRAM_ALLOWED_USERS",
858
877
  required: false,
859
878
  secret: false,
860
879
  description: "Telegram user ids allowed to reach the handler; absent or empty allows everyone."
861
880
  },
881
+ {
882
+ key: "apiBase",
883
+ env: "TELEGRAM_API_BASE",
884
+ required: false,
885
+ secret: false,
886
+ description: "Bot API root, for a self-hosted Bot API server; default https://api.telegram.org."
887
+ },
862
888
  {
863
889
  key: "requireMention",
864
890
  required: false,
@@ -875,8 +901,10 @@ var telegramChannel = {
875
901
  const token = readToken(config);
876
902
  const allowedUsers = readAllowedUsers(config);
877
903
  const requireMention = readRequireMention(config);
904
+ const apiBase = readApiBase(config);
878
905
  return new TelegramAdapter({
879
906
  token,
907
+ ...apiBase === void 0 ? {} : { apiBase },
880
908
  ...allowedUsers === void 0 ? {} : { allowedUsers },
881
909
  ...requireMention === void 0 ? {} : { requireMention }
882
910
  });