@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 +123 -0
- package/README.md +40 -0
- package/dist/index.cjs +416 -39
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +24 -0
- package/dist/index.d.ts +24 -0
- package/dist/index.js +417 -40
- package/dist/index.js.map +1 -1
- package/package.json +5 -2
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`:
|