@sympoies/dsh-telegram 0.0.0-bootstrap.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.
Files changed (194) hide show
  1. package/LICENSE +1 -2
  2. package/NOTICE +19 -0
  3. package/README.md +589 -2
  4. package/cordis.patch.yml +14 -0
  5. package/lib/access.d.ts +76 -0
  6. package/lib/access.d.ts.map +1 -0
  7. package/lib/access.js +137 -0
  8. package/lib/access.js.map +1 -0
  9. package/lib/client.js +835 -0
  10. package/lib/commands.d.ts +51 -0
  11. package/lib/commands.d.ts.map +1 -0
  12. package/lib/commands.js +83 -0
  13. package/lib/commands.js.map +1 -0
  14. package/lib/config.d.ts +125 -0
  15. package/lib/config.d.ts.map +1 -0
  16. package/lib/config.js +97 -0
  17. package/lib/config.js.map +1 -0
  18. package/lib/diagnostics.d.ts +58 -0
  19. package/lib/diagnostics.d.ts.map +1 -0
  20. package/lib/diagnostics.js +59 -0
  21. package/lib/diagnostics.js.map +1 -0
  22. package/lib/failures.d.ts +71 -0
  23. package/lib/failures.d.ts.map +1 -0
  24. package/lib/failures.js +139 -0
  25. package/lib/failures.js.map +1 -0
  26. package/lib/harness/host.d.ts +106 -0
  27. package/lib/harness/host.d.ts.map +1 -0
  28. package/lib/harness/host.js +142 -0
  29. package/lib/harness/host.js.map +1 -0
  30. package/lib/harness/message.d.ts +45 -0
  31. package/lib/harness/message.d.ts.map +1 -0
  32. package/lib/harness/message.js +28 -0
  33. package/lib/harness/message.js.map +1 -0
  34. package/lib/harness/model-selection.d.ts +82 -0
  35. package/lib/harness/model-selection.d.ts.map +1 -0
  36. package/lib/harness/model-selection.js +103 -0
  37. package/lib/harness/model-selection.js.map +1 -0
  38. package/lib/harness/questions-seam.d.ts +34 -0
  39. package/lib/harness/questions-seam.d.ts.map +1 -0
  40. package/lib/harness/questions-seam.js +45 -0
  41. package/lib/harness/questions-seam.js.map +1 -0
  42. package/lib/harness/types.d.ts +108 -0
  43. package/lib/harness/types.d.ts.map +1 -0
  44. package/lib/harness/types.js +23 -0
  45. package/lib/harness/types.js.map +1 -0
  46. package/lib/index.d.ts +65 -0
  47. package/lib/index.d.ts.map +1 -0
  48. package/lib/index.js +977 -0
  49. package/lib/index.js.map +1 -0
  50. package/lib/interact/approvals.d.ts +59 -0
  51. package/lib/interact/approvals.d.ts.map +1 -0
  52. package/lib/interact/approvals.js +132 -0
  53. package/lib/interact/approvals.js.map +1 -0
  54. package/lib/interact/pending.d.ts +56 -0
  55. package/lib/interact/pending.d.ts.map +1 -0
  56. package/lib/interact/pending.js +89 -0
  57. package/lib/interact/pending.js.map +1 -0
  58. package/lib/interact/questions.d.ts +100 -0
  59. package/lib/interact/questions.d.ts.map +1 -0
  60. package/lib/interact/questions.js +255 -0
  61. package/lib/interact/questions.js.map +1 -0
  62. package/lib/interact/surface.d.ts +33 -0
  63. package/lib/interact/surface.d.ts.map +1 -0
  64. package/lib/interact/surface.js +39 -0
  65. package/lib/interact/surface.js.map +1 -0
  66. package/lib/interact/text-capture.d.ts +38 -0
  67. package/lib/interact/text-capture.d.ts.map +1 -0
  68. package/lib/interact/text-capture.js +75 -0
  69. package/lib/interact/text-capture.js.map +1 -0
  70. package/lib/media/collect.d.ts +157 -0
  71. package/lib/media/collect.d.ts.map +1 -0
  72. package/lib/media/collect.js +235 -0
  73. package/lib/media/collect.js.map +1 -0
  74. package/lib/media/extractor.d.ts +117 -0
  75. package/lib/media/extractor.d.ts.map +1 -0
  76. package/lib/media/extractor.js +207 -0
  77. package/lib/media/extractor.js.map +1 -0
  78. package/lib/media/intake.d.ts +57 -0
  79. package/lib/media/intake.d.ts.map +1 -0
  80. package/lib/media/intake.js +115 -0
  81. package/lib/media/intake.js.map +1 -0
  82. package/lib/media/limits.d.ts +69 -0
  83. package/lib/media/limits.d.ts.map +1 -0
  84. package/lib/media/limits.js +97 -0
  85. package/lib/media/limits.js.map +1 -0
  86. package/lib/media/ocr.d.ts +66 -0
  87. package/lib/media/ocr.d.ts.map +1 -0
  88. package/lib/media/ocr.js +131 -0
  89. package/lib/media/ocr.js.map +1 -0
  90. package/lib/media/screenshot.d.ts +57 -0
  91. package/lib/media/screenshot.d.ts.map +1 -0
  92. package/lib/media/screenshot.js +101 -0
  93. package/lib/media/screenshot.js.map +1 -0
  94. package/lib/media/vision.d.ts +60 -0
  95. package/lib/media/vision.d.ts.map +1 -0
  96. package/lib/media/vision.js +74 -0
  97. package/lib/media/vision.js.map +1 -0
  98. package/lib/render/clamp.d.ts +34 -0
  99. package/lib/render/clamp.d.ts.map +1 -0
  100. package/lib/render/clamp.js +65 -0
  101. package/lib/render/clamp.js.map +1 -0
  102. package/lib/render/escape.d.ts +15 -0
  103. package/lib/render/escape.d.ts.map +1 -0
  104. package/lib/render/escape.js +17 -0
  105. package/lib/render/escape.js.map +1 -0
  106. package/lib/reply/activity.d.ts +31 -0
  107. package/lib/reply/activity.d.ts.map +1 -0
  108. package/lib/reply/activity.js +88 -0
  109. package/lib/reply/activity.js.map +1 -0
  110. package/lib/reply/rich-stream.d.ts +173 -0
  111. package/lib/reply/rich-stream.d.ts.map +1 -0
  112. package/lib/reply/rich-stream.js +286 -0
  113. package/lib/reply/rich-stream.js.map +1 -0
  114. package/lib/reply/split-markdown.d.ts +21 -0
  115. package/lib/reply/split-markdown.d.ts.map +1 -0
  116. package/lib/reply/split-markdown.js +87 -0
  117. package/lib/reply/split-markdown.js.map +1 -0
  118. package/lib/reply/turn-bridge.d.ts +143 -0
  119. package/lib/reply/turn-bridge.d.ts.map +1 -0
  120. package/lib/reply/turn-bridge.js +182 -0
  121. package/lib/reply/turn-bridge.js.map +1 -0
  122. package/lib/router.d.ts +415 -0
  123. package/lib/router.d.ts.map +1 -0
  124. package/lib/router.js +663 -0
  125. package/lib/router.js.map +1 -0
  126. package/lib/secrets.d.ts +30 -0
  127. package/lib/secrets.d.ts.map +1 -0
  128. package/lib/secrets.js +51 -0
  129. package/lib/secrets.js.map +1 -0
  130. package/lib/session/bindings.d.ts +81 -0
  131. package/lib/session/bindings.d.ts.map +1 -0
  132. package/lib/session/bindings.js +170 -0
  133. package/lib/session/bindings.js.map +1 -0
  134. package/lib/session/history.d.ts +50 -0
  135. package/lib/session/history.d.ts.map +1 -0
  136. package/lib/session/history.js +127 -0
  137. package/lib/session/history.js.map +1 -0
  138. package/lib/session/models.d.ts +99 -0
  139. package/lib/session/models.d.ts.map +1 -0
  140. package/lib/session/models.js +123 -0
  141. package/lib/session/models.js.map +1 -0
  142. package/lib/session/permission.d.ts +83 -0
  143. package/lib/session/permission.d.ts.map +1 -0
  144. package/lib/session/permission.js +107 -0
  145. package/lib/session/permission.js.map +1 -0
  146. package/lib/session/picker.d.ts +49 -0
  147. package/lib/session/picker.d.ts.map +1 -0
  148. package/lib/session/picker.js +107 -0
  149. package/lib/session/picker.js.map +1 -0
  150. package/lib/session/preferences.d.ts +55 -0
  151. package/lib/session/preferences.d.ts.map +1 -0
  152. package/lib/session/preferences.js +102 -0
  153. package/lib/session/preferences.js.map +1 -0
  154. package/lib/session/recovery.d.ts +66 -0
  155. package/lib/session/recovery.d.ts.map +1 -0
  156. package/lib/session/recovery.js +112 -0
  157. package/lib/session/recovery.js.map +1 -0
  158. package/lib/session/runner.d.ts +223 -0
  159. package/lib/session/runner.d.ts.map +1 -0
  160. package/lib/session/runner.js +260 -0
  161. package/lib/session/runner.js.map +1 -0
  162. package/lib/session/workspaces.d.ts +28 -0
  163. package/lib/session/workspaces.d.ts.map +1 -0
  164. package/lib/session/workspaces.js +53 -0
  165. package/lib/session/workspaces.js.map +1 -0
  166. package/lib/telegram/addressing.d.ts +39 -0
  167. package/lib/telegram/addressing.d.ts.map +1 -0
  168. package/lib/telegram/addressing.js +81 -0
  169. package/lib/telegram/addressing.js.map +1 -0
  170. package/lib/telegram/albums.d.ts +46 -0
  171. package/lib/telegram/albums.d.ts.map +1 -0
  172. package/lib/telegram/albums.js +104 -0
  173. package/lib/telegram/albums.js.map +1 -0
  174. package/lib/telegram/api.d.ts +238 -0
  175. package/lib/telegram/api.d.ts.map +1 -0
  176. package/lib/telegram/api.js +518 -0
  177. package/lib/telegram/api.js.map +1 -0
  178. package/lib/telegram/poller.d.ts +59 -0
  179. package/lib/telegram/poller.d.ts.map +1 -0
  180. package/lib/telegram/poller.js +94 -0
  181. package/lib/telegram/poller.js.map +1 -0
  182. package/lib/telegram/types.d.ts +130 -0
  183. package/lib/telegram/types.d.ts.map +1 -0
  184. package/lib/telegram/types.js +9 -0
  185. package/lib/telegram/types.js.map +1 -0
  186. package/lib/telegram/typing.d.ts +47 -0
  187. package/lib/telegram/typing.d.ts.map +1 -0
  188. package/lib/telegram/typing.js +91 -0
  189. package/lib/telegram/typing.js.map +1 -0
  190. package/lib/versions.d.ts +63 -0
  191. package/lib/versions.d.ts.map +1 -0
  192. package/lib/versions.js +135 -0
  193. package/lib/versions.js.map +1 -0
  194. package/package.json +94 -10
@@ -0,0 +1 @@
1
+ {"version":3,"file":"albums.js","sourceRoot":"","sources":["../../src/telegram/albums.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,238 @@
1
+ /**
2
+ * Telegram Bot API client.
3
+ *
4
+ * Speaks the HTTP protocol directly — no SDK — because the surface this plugin
5
+ * needs is a dozen methods wide and an SDK would only add a dependency and a
6
+ * translation layer between us and the error messages that matter.
7
+ *
8
+ * Three behaviours are deliberate and are the reason this client exists rather
9
+ * than a thin fetch wrapper:
10
+ *
11
+ * - **Replies are sent as rich markdown.** Since Bot API 10.1 Telegram parses
12
+ * markdown itself, so the agent's tables, headings and lists arrive as real
13
+ * elements. The plugin's own prompts stay on plain HTML: they are short,
14
+ * built from escaped text, and carry the inline keyboards.
15
+ * - **Rate limits are waited out, not thrown.** A 429 carries `retry_after`;
16
+ * the client sleeps that long and retries, so a burst of streaming edits
17
+ * degrades into slower edits rather than a failed turn.
18
+ * - **The token never reaches a log.** It lives in the request path, so every
19
+ * error message is redacted before it escapes.
20
+ */
21
+ import type { BotUser, ChatAction, InlineKeyboard, TelegramFile, TelegramUpdate } from './types.js';
22
+ /** A Bot API call that failed, with the token stripped from every field. */
23
+ export declare class TelegramApiError extends Error {
24
+ readonly code: number | undefined;
25
+ readonly description: string | undefined;
26
+ /** Seconds Telegram asked us to wait, from a 429's `parameters.retry_after`. */
27
+ readonly retryAfterSeconds?: number | undefined;
28
+ constructor(message: string, code: number | undefined, description: string | undefined,
29
+ /** Seconds Telegram asked us to wait, from a 429's `parameters.retry_after`. */
30
+ retryAfterSeconds?: number | undefined);
31
+ /** Whether the failure means the bot token itself is not valid. */
32
+ get isAuthFailure(): boolean;
33
+ }
34
+ /** Construction options; `fetchImpl` and `sleep` exist so tests need no network. */
35
+ export interface TelegramApiOptions {
36
+ readonly token: string;
37
+ readonly baseUrl: string;
38
+ readonly timeoutMs: number;
39
+ /** Deadline for one file download; defaults to a minute. */
40
+ readonly downloadTimeoutMs?: number;
41
+ readonly fetchImpl?: typeof fetch;
42
+ readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
43
+ }
44
+ /** Arguments for sending one text message. */
45
+ export interface SendMessageOptions {
46
+ readonly chatId: string;
47
+ readonly html: string;
48
+ readonly keyboard?: InlineKeyboard;
49
+ readonly replyToMessageId?: number;
50
+ readonly threadId?: number;
51
+ readonly signal?: AbortSignal;
52
+ }
53
+ /** Arguments for editing one text message. */
54
+ export interface EditMessageOptions {
55
+ readonly chatId: string;
56
+ readonly messageId: number;
57
+ readonly html: string;
58
+ readonly keyboard?: InlineKeyboard;
59
+ readonly signal?: AbortSignal;
60
+ }
61
+ /** Outcome of an edit: Telegram treats a no-op edit as an error, we do not. */
62
+ export type EditOutcome = 'edited' | 'unchanged';
63
+ /** Arguments for sending one rich message. */
64
+ export interface SendRichOptions {
65
+ readonly chatId: string;
66
+ /** Rich Markdown, which Telegram parses and renders itself. */
67
+ readonly markdown: string;
68
+ readonly keyboard?: InlineKeyboard;
69
+ readonly replyToMessageId?: number;
70
+ readonly threadId?: number;
71
+ readonly signal?: AbortSignal;
72
+ }
73
+ /** Arguments for one frame of a streamed draft. */
74
+ export interface DraftOptions {
75
+ readonly chatId: string;
76
+ /** Stable across a turn: Telegram animates changes to the same draft id. */
77
+ readonly draftId: number;
78
+ readonly markdown: string;
79
+ readonly threadId?: number;
80
+ readonly signal?: AbortSignal;
81
+ }
82
+ export declare class TelegramApi {
83
+ private readonly options;
84
+ private readonly fetchImpl;
85
+ private readonly sleep;
86
+ private readonly downloadTimeoutMs;
87
+ constructor(options: TelegramApiOptions);
88
+ /** Verify the token and read the bot's own identity. */
89
+ getMe(): Promise<BotUser>;
90
+ /** Drop any webhook so long polling is the only delivery path. */
91
+ deleteWebhook(): Promise<void>;
92
+ /**
93
+ * Long-poll for updates.
94
+ *
95
+ * `allowed_updates` includes `callback_query`, which is what lets a button
96
+ * press reach the agent at all.
97
+ */
98
+ getUpdates(offset: number, timeoutSeconds: number, signal?: AbortSignal): Promise<TelegramUpdate[]>;
99
+ /**
100
+ * Send one HTML message, falling back to plain text if Telegram rejects the
101
+ * markup rather than letting the content vanish.
102
+ */
103
+ sendMessage(options: SendMessageOptions): Promise<{
104
+ messageId: number;
105
+ }>;
106
+ /**
107
+ * Edit one message in place — the mechanism behind streamed replies.
108
+ *
109
+ * Telegram answers 400 when the new text equals the old, which during
110
+ * streaming is an ordinary and frequent event, so it is reported rather than
111
+ * thrown.
112
+ */
113
+ editMessageText(options: EditMessageOptions): Promise<EditOutcome>;
114
+ /**
115
+ * Send one rich message.
116
+ *
117
+ * Telegram parses the Rich Markdown itself, so tables, headings, lists and
118
+ * task lists arrive as real elements rather than as an approximation of
119
+ * them — and the cap is 32768 characters rather than 4096.
120
+ */
121
+ sendRichMessage(options: SendRichOptions): Promise<{
122
+ messageId: number;
123
+ }>;
124
+ /**
125
+ * Stream one frame of a partial reply.
126
+ *
127
+ * The draft is a 30-second ephemeral preview, and Telegram animates changes
128
+ * carrying the same `draftId` — so a turn keeps one id throughout and the
129
+ * text grows in place. It must still be persisted with a real send when the
130
+ * turn ends, and it works in private chats only.
131
+ */
132
+ sendRichMessageDraft(options: DraftOptions): Promise<void>;
133
+ /** Replace a message's content with rich markdown. */
134
+ editRichMessage(options: {
135
+ chatId: string;
136
+ messageId: number;
137
+ markdown: string;
138
+ keyboard?: InlineKeyboard;
139
+ }): Promise<EditOutcome>;
140
+ /** Replace or clear a message's inline keyboard, leaving its text alone. */
141
+ editMessageReplyMarkup(options: {
142
+ chatId: string;
143
+ messageId: number;
144
+ keyboard: InlineKeyboard;
145
+ }): Promise<void>;
146
+ /**
147
+ * Acknowledge a button press. Telegram shows a spinner on the button until
148
+ * this lands, so it is sent before any slow work the press triggers.
149
+ */
150
+ answerCallbackQuery(id: string, text?: string): Promise<void>;
151
+ /**
152
+ * Upload one file to a chat.
153
+ *
154
+ * Multipart rather than the JSON path every other call uses, because
155
+ * Telegram takes file bytes no other way. Node builds the body: `FormData`
156
+ * and `Blob` are standard here, so there is no boundary to get wrong.
157
+ *
158
+ * Not retried. A retry would re-upload the whole file, and the failures that
159
+ * matter for one — too large, wrong type — do not pass on a second attempt.
160
+ *
161
+ * @param method - `sendPhoto` or `sendDocument`.
162
+ * @param field - the form field Telegram expects the bytes under.
163
+ * @param options - the chat, the bytes, and what to call them.
164
+ */
165
+ uploadFile(method: 'sendPhoto' | 'sendDocument', field: 'photo' | 'document', options: {
166
+ chatId: string;
167
+ data: Uint8Array;
168
+ filename: string;
169
+ contentType: string;
170
+ caption?: string;
171
+ threadId?: number;
172
+ }): Promise<{
173
+ messageId: number;
174
+ }>;
175
+ /**
176
+ * Publish the command menu Telegram offers when someone types `/`.
177
+ *
178
+ * Without this the bot answers every command correctly and advertises none
179
+ * of them, so they are discoverable only by reading the README. Best-effort:
180
+ * a bot that cannot publish its menu still works, it is only harder to find
181
+ * your way around.
182
+ *
183
+ * @param commands - name and one-line description, in menu order.
184
+ */
185
+ setMyCommands(commands: readonly {
186
+ command: string;
187
+ description: string;
188
+ }[]): Promise<void>;
189
+ /** Show a progress indicator in the chat. Best-effort by design. */
190
+ sendChatAction(chatId: string, action: ChatAction, threadId?: number): Promise<void>;
191
+ /** Resolve a file id to downloadable metadata. */
192
+ getFile(fileId: string): Promise<TelegramFile>;
193
+ /**
194
+ * Download a resolved file's bytes.
195
+ *
196
+ * The download URL carries the token in its path, and a transport failure
197
+ * quotes the URL it was given — so this fetch is wrapped like every other,
198
+ * or a dropped connection would hand the token to the caller's log.
199
+ */
200
+ downloadFile(filePath: string, signal?: AbortSignal): Promise<Uint8Array>;
201
+ /** Base url without a trailing slash. */
202
+ private base;
203
+ /**
204
+ * One Bot API call, with retries for transient failures.
205
+ *
206
+ * @throws {TelegramApiError} with the token redacted from every field.
207
+ */
208
+ private call;
209
+ /**
210
+ * Run one operation, backing off and repeating what is safe to repeat.
211
+ *
212
+ * Shared with the download path rather than living inside `call`: a download
213
+ * is the most retry-worthy request this client makes — a pure read of bytes
214
+ * — and leaving it outside the retry loop is what turned an intermittent
215
+ * connection into a screenshot the agent never saw.
216
+ */
217
+ private withRetries;
218
+ /** One attempt: build, send, validate, unwrap. */
219
+ private request;
220
+ /** Wrap any thrown value as a redacted TelegramApiError. */
221
+ private normalize;
222
+ /** Remove the bot token from any string bound for a log or an error. */
223
+ private redact;
224
+ }
225
+ /**
226
+ * One readable line from an error and everything underneath it.
227
+ *
228
+ * Node's fetch reports every transport failure as the same three words —
229
+ * `fetch failed` — and puts what actually happened in `cause`: a refused
230
+ * connection, an unresolved name, an expired certificate, a timeout. Reporting
231
+ * only the top layer turns four distinct problems into one unactionable
232
+ * sentence, which is exactly how far a diagnosis gets on it.
233
+ *
234
+ * @param error - any thrown value.
235
+ * @returns the message chain, outermost first.
236
+ */
237
+ export declare function describeCause(error: unknown): string;
238
+ //# sourceMappingURL=api.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/telegram/api.ts"],"names":[],"mappings":"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"}