@theokit/gateway-telegram 0.4.0 → 0.6.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,128 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.6.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 458c34c: Wire channels from descriptors, and keep the channels that connect when another cannot.
8
+
9
+ `@theokit/gateway` exports `createChannels` and the types `ChannelDescriptor`,
10
+ `ChannelConfigField`, `ChannelWebhook`, `WebhookRequest`, `IngestResult`, `ChannelEntry`,
11
+ `ChannelRejection` and `CreateChannelsResult`. `createChannels(entries)` builds an adapter per
12
+ entry and returns `{ adapters, rejected }`: an entry whose required field is absent, `null` or
13
+ `""` is rejected with a `GatewayConfigurationError` coded `missing_required_config` naming the
14
+ keys, and a configuration error thrown by the descriptor's `create` is rejected the same way. Any
15
+ other error propagates. It connects nothing and makes no network call.
16
+
17
+ `GatewayRunner` accepts `connectFailure: "rollback" | "isolate"` (exported as `ConnectFailure`),
18
+ and `StartResult` is exported.
19
+ The default, `"rollback"`, is unchanged: one failed connect disconnects the adapters that did
20
+ connect and rejects `start()`. Under `"isolate"`, `start()` connects every adapter, wires inbound
21
+ only for the ones that connected, and reports the rest with a redacted reason.
22
+
23
+ `start()` now resolves a `StartResult` (`{ connected, failed }`) instead of `void`, under both
24
+ values. This is a type change: code that awaits `start()` and ignores the value is unaffected,
25
+ but a structural type declaring `start(): Promise<void>` that a `GatewayRunner` is assigned to
26
+ fails with TS2322, and a subclass overriding `start()` with that signature fails with TS2416.
27
+
28
+ `@theokit/gateway-telegram` exports `telegramChannel`, a socket channel whose config has a
29
+ required, secret `token` and an optional `allowedUsers`, and a `ConfigurationError` (a
30
+ `GatewayConfigurationError` with the `gateway-telegram` prefix). Called directly,
31
+ `telegramChannel.create` refuses a token that is not a string or is empty, and an `allowedUsers`
32
+ that is not an array of strings; through `createChannels`, an absent or empty token is rejected
33
+ first, as `missing_required_config`.
34
+
35
+ `@theokit/gateway-line` exports `lineChannel`, a webhook channel whose `webhook.verify` checks the
36
+ `x-line-signature` header against the raw body and whose `webhook.ingest` dispatches a verified
37
+ payload through `dispatchWebhookBody`, so a reply uses the cached reply token, or answers
38
+ `"malformed"` without dispatching. It answers `"no_handler"` (a member of `IngestResult`) when the
39
+ payload holds a text message for the handler and none is subscribed: before the runner started,
40
+ after it stopped, or when LINE's connect failed under `"isolate"`. Before, such a request answered
41
+ `"delivered"`, a route acknowledged it, and LINE did not redeliver the lost message.
42
+ `lineChannel.create` checks field types before the adapter's constructor.
43
+
44
+ `LineAdapter.dispatchWebhookBody` now resolves `"ok" | "no_handler"` instead of `void`. It answers
45
+ `"no_handler"`, dispatching nothing and caching no reply token, for a batch holding a text message
46
+ that passes the mention guard while no handler is subscribed; an empty or follow-only batch still
47
+ answers `"ok"`. It reads the handler once per batch, so a handler that unsubscribes while handling
48
+ one event still receives the rest of the batch. Code that ignores the value is unaffected; a
49
+ subclass overriding the method with `Promise<void>` fails with TS2416. `createWebhookServer` is
50
+ unchanged and still answers 200 before it dispatches.
51
+
52
+ Both descriptors are typed locally and import nothing `@theokit/gateway` 0.9.0 lacks, so the peer
53
+ range stays `>=0.9.0 <1.0.0`.
54
+
55
+ - 3f1788d: Send an image from a gateway handler, and refuse it wherever a platform cannot show one.
56
+
57
+ `@theokit/gateway` exports `OutboundAttachment` (`kind: "image"`, `mediaType`, `data`, optional
58
+ `filename`). `OutboundMessage` gains an optional `attachments` list, `ctx.reply(text, { attachments })`
59
+ carries it to the adapter (an empty list is left out), and `BasePlatformAdapter` declares
60
+ `supportsAttachments`, `false` by default. `DeliveryRouter.send` takes the same `attachments`
61
+ field. The runner and the router refuse an outbound carrying attachments as
62
+ `attachments_unsupported`, with no `sendMessage` call, when the adapter does not declare
63
+ `supportsAttachments`.
64
+
65
+ `@theokit/gateway-telegram` reports `supportsAttachments: true` and sends each image through
66
+ `sendPhoto`, the text as the first photo's caption up to 1024 UTF-16 units and after the photos
67
+ when longer. A non-image kind is refused as `attachments_unsupported`; a missing image, more
68
+ than 10 images or an image over 10 MiB as `invalid_attachment`; all with no request.
69
+
70
+ Every other adapter, and every adapter's `editMessage`, refuses an outbound carrying attachments
71
+ with `attachments_unsupported` and makes no platform call, instead of sending the text and
72
+ dropping the image.
73
+
74
+ The runner's auto-reply to a blocking `pre_inbound` hook no longer discards a `sendMessage` that
75
+ throws: the error reaches the `on_error` hooks with the event and is written to stderr, redacted,
76
+ as a handler error is. Dispatch still does not throw.
77
+
78
+ - 782e448: Carry voice in both directions. The inbound event gains an optional `audio` field, an
79
+ `InboundAudio` with the voice note's bytes, media type and duration in seconds, and
80
+ `OutboundAttachment` gains an `audio` member beside `image`. The Telegram adapter reads a polled
81
+ voice note through `getFile` and a download bounded at 20 MiB and 30 seconds, delivering the
82
+ message without `audio` and one stderr line when it cannot, and sends an audio attachment through
83
+ `sendVoice` with the reply text as its caption. Every other adapter refuses audio as it refuses an
84
+ image. Code that switches exhaustively on `OutboundAttachment["kind"]` gains a case.
85
+
86
+ ### Patch Changes
87
+
88
+ - 17c0713: Keep Markdown table rows whole when Discord, Slack, Teams, Telegram, WhatsApp and Mattermost split a long reply. A cut that fell inside a table row now moves back to the start of that row when the row fits in a part, so each row reaches the platform byte-identical. `chunkText` gains the opt-in `keepTableRows` option; text with no table row splits into the same chunks as before.
89
+
90
+ ## 0.5.0
91
+
92
+ ### Minor Changes
93
+
94
+ - 05e7fdd: Edit a message an adapter sent, so a reply can stream as a preview that the final text replaces.
95
+
96
+ `BasePlatformAdapter` gains `supportsEdit` (`false` by default) and
97
+ `editMessage(messageId, out)`, whose default refuses with `edit_unsupported`, makes no platform
98
+ call and never throws. A third-party subclass that already declares a member with either name and
99
+ a different type no longer compiles against this release, and under `noImplicitOverride` one
100
+ that declares it without `override` does not either.
101
+
102
+ Telegram (`editMessageText`), Discord (one REST `PATCH` of the message, without fetching the
103
+ channel), Slack (`chat.update`), Mattermost (`patchPost`), Matrix (an `m.replace` event) and Teams
104
+ (`updateActivity`, or `activities(conversationId).update` on `@microsoft/teams.api` below 2.0.14)
105
+ set `supportsEdit` to `true` and replace the text of a message they sent, honouring `format` as
106
+ `sendMessage` does (Slack's `chat.update` takes no `mrkdwn` argument, so its edit sends the text
107
+ as it is for every format), and return `{ ok: true, messageId }` with the same id. E-mail, SMS, LINE and
108
+ WhatsApp keep the default.
109
+
110
+ An edit is refused with no request as `edit_too_long` when the text would need more than one
111
+ platform message (Matrix has no length check), as `invalid_message_id` for an empty id (and on
112
+ Telegram one that is not a safe positive integer), and as `empty_text` and `not_connected` where
113
+ `sendMessage` answers those. Telegram answers its "message is not modified" refusal as a success.
114
+ On Discord an unknown channel is answered by the platform, as `discord_10003`. On Matrix a
115
+ `#alias` the adapter never resolved costs one lookup before the edit. Teams and Matrix do not
116
+ retry a refused markup as plain text on an edit, as they do on a send.
117
+
118
+ The six adapters keep `>=0.9.0` as their peer range on `@theokit/gateway` in this release. At run
119
+ time they work against any core in that range, since no adapter calls the base `editMessage`. Their
120
+ sources declare both members with `override`, so building them against a core older than this one
121
+ reports TS4113. The floor rises to this core in the next release, once it is on npm
122
+ (`docs/adr/0008-edit-capable-adapters-raise-their-core-floor-after-the-core-ships.md`). A
123
+ consumer's own typecheck reads the published declarations, which carry no `override`, and passes
124
+ on an older core.
125
+
3
126
  ## 0.4.0
4
127
 
5
128
  ### Minor Changes
package/README.md CHANGED
@@ -41,6 +41,46 @@ const runner = new GatewayRunner({
41
41
  await runner.start();
42
42
  ```
43
43
 
44
+ ## Sending an image
45
+
46
+ `ctx.reply(text, { attachments })` sends each image through `sendPhoto`, one request per image, in
47
+ order, and the adapter reports `supportsAttachments` as `true`. The text becomes the first photo's
48
+ caption when it is 1 to 1024 UTF-16 units long, Telegram's caption limit. A longer text gets no
49
+ caption and is sent after the last photo, split as any text send is, in the same topic and without
50
+ the reply target, so none of it is cut. An empty text sends the photos alone.
51
+
52
+ Every attachment is checked before the first request: an `attachments` value that is not a list,
53
+ more than 10 images, or an image with no bytes or over 10 MiB (Telegram's photo limit) is refused
54
+ as `invalid_attachment`, and a `kind` other than `image` as `attachments_unsupported`, with no
55
+ request. On success the returned `messageId` is the last message sent. A photo Telegram refuses
56
+ ends the send with the mapped error and no `messageId`, and the photos before it stay delivered,
57
+ so retrying the whole send after a `rate_limited` or `network_error` sends those photos again.
58
+ An edit carrying attachments is refused as `attachments_unsupported`.
59
+
60
+ ## Voice notes
61
+
62
+ **Reading.** A voice note that arrives by polling reaches the handler with `event.audio` set: the
63
+ adapter calls `getFile` for its path and downloads it from Telegram's file server with the bot
64
+ token. The download is bounded at 20 MiB (Telegram's `getFile` limit; a voice whose declared
65
+ `file_size` is larger is not fetched at all), and the whole read, `getFile` and download with its
66
+ body, at 30 seconds. `mediaType` is the
67
+ voice's `mime_type`, `audio/ogg` when it has none, and `durationSeconds` its `duration`, 0 when it
68
+ is not a number. A blocked sender or a message without a voice triggers no request. A voice that
69
+ cannot be read (`getFile` fails, the download answers an error status, times out, passes 20 MiB,
70
+ or the voice has no `file_id`) is delivered without `audio`, as before this release, with one
71
+ stderr line `[telegram] voice not read: <reason>`; the line never carries the download URL, which
72
+ holds the token. A voice delivered through a webhook (`parseInbound`) is not read.
73
+
74
+ **Sending.** An attachment with `kind: "audio"` goes out through `sendVoice`, in the same path and
75
+ order as images: the text is the caption of the first attachment whatever its kind, under the
76
+ same 1024-unit rule, and an audio-only reply with empty text sends the clip alone. Audio must have
77
+ bytes, be at most 50 MiB (the Bot API upload limit) and declare an `audio/*` media type (any case,
78
+ parameters allowed), or the send is refused as `invalid_attachment` before any request. Telegram
79
+ shows OGG/Opus, MP3 and M4A as a voice bubble; other audio is delivered as a file.
80
+
81
+ Attachments need `@theokit/gateway` 0.13.0 or later: an older core's `ctx.reply` does not carry
82
+ them to the adapter, so install both together.
83
+
44
84
  ## Channel descriptor
45
85
 
46
86
  `telegramChannel` describes this channel as data, for `createChannels` in `@theokit/gateway`: