@xbibzlibrary/telebibz 0.1.2 → 0.1.3

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 (117) hide show
  1. package/CHANGELOG.md +16 -1
  2. package/README.id.md +158 -0
  3. package/README.md +53 -33
  4. package/README.zh-CN.md +158 -0
  5. package/RELEASE_AUTOMATION.md +66 -0
  6. package/RELEASE_POLICY.md +2 -2
  7. package/assets/readme-preview.html +75 -0
  8. package/assets/telebibz-readme-preview.png +0 -0
  9. package/dist/src/api/index.d.ts +1 -0
  10. package/dist/src/api/index.d.ts.map +1 -1
  11. package/dist/src/api/index.js +1 -0
  12. package/dist/src/api/index.js.map +1 -1
  13. package/dist/src/api/telegram-types/LICENSE +21 -0
  14. package/dist/src/api/telegram-types/api.d.ts +22 -0
  15. package/dist/src/api/telegram-types/checklist.d.ts +72 -0
  16. package/dist/src/api/telegram-types/inline.d.ts +692 -0
  17. package/dist/src/api/telegram-types/langs.d.ts +193 -0
  18. package/dist/src/api/telegram-types/manage.d.ts +1144 -0
  19. package/dist/src/api/telegram-types/markup.d.ts +268 -0
  20. package/dist/src/api/telegram-types/message.d.ts +1537 -0
  21. package/dist/src/api/telegram-types/methods.d.ts +2870 -0
  22. package/dist/src/api/telegram-types/mod.d.ts +14 -0
  23. package/dist/src/api/telegram-types/passport.d.ts +163 -0
  24. package/dist/src/api/telegram-types/payment.d.ts +570 -0
  25. package/dist/src/api/telegram-types/rich.d.ts +1010 -0
  26. package/dist/src/api/telegram-types/settings.d.ts +120 -0
  27. package/dist/src/api/telegram-types/story.d.ts +89 -0
  28. package/dist/src/api/telegram-types/update.d.ts +84 -0
  29. package/dist/src/api/telegram.d.ts +7 -0
  30. package/dist/src/api/telegram.d.ts.map +1 -0
  31. package/dist/src/api/telegram.js +2 -0
  32. package/dist/src/api/telegram.js.map +1 -0
  33. package/dist/src/approval/approval.d.ts +8 -0
  34. package/dist/src/approval/approval.d.ts.map +1 -1
  35. package/dist/src/approval/approval.js +9 -0
  36. package/dist/src/approval/approval.js.map +1 -1
  37. package/dist/src/cache/cache.d.ts +6 -5
  38. package/dist/src/cache/cache.d.ts.map +1 -1
  39. package/dist/src/cache/cache.js +7 -3
  40. package/dist/src/cache/cache.js.map +1 -1
  41. package/dist/src/context/context.d.ts.map +1 -1
  42. package/dist/src/context/context.js +26 -3
  43. package/dist/src/context/context.js.map +1 -1
  44. package/dist/src/core/bot.d.ts +6 -4
  45. package/dist/src/core/bot.d.ts.map +1 -1
  46. package/dist/src/core/bot.js +48 -7
  47. package/dist/src/core/bot.js.map +1 -1
  48. package/dist/src/core/events.d.ts +4 -0
  49. package/dist/src/core/events.d.ts.map +1 -1
  50. package/dist/src/core/events.js.map +1 -1
  51. package/dist/src/index.d.ts +1 -0
  52. package/dist/src/index.d.ts.map +1 -1
  53. package/dist/src/index.js +1 -0
  54. package/dist/src/index.js.map +1 -1
  55. package/dist/src/queue/queue.d.ts +25 -0
  56. package/dist/src/queue/queue.d.ts.map +1 -1
  57. package/dist/src/queue/queue.js +175 -51
  58. package/dist/src/queue/queue.js.map +1 -1
  59. package/dist/src/router/router.d.ts +8 -1
  60. package/dist/src/router/router.d.ts.map +1 -1
  61. package/dist/src/router/router.js +75 -17
  62. package/dist/src/router/router.js.map +1 -1
  63. package/dist/src/state/conversation.d.ts +6 -0
  64. package/dist/src/state/conversation.d.ts.map +1 -1
  65. package/dist/src/state/conversation.js +79 -11
  66. package/dist/src/state/conversation.js.map +1 -1
  67. package/dist/src/state/menu.d.ts +53 -5
  68. package/dist/src/state/menu.d.ts.map +1 -1
  69. package/dist/src/state/menu.js +116 -17
  70. package/dist/src/state/menu.js.map +1 -1
  71. package/dist/src/storage/storage.d.ts +115 -12
  72. package/dist/src/storage/storage.d.ts.map +1 -1
  73. package/dist/src/storage/storage.js +130 -4
  74. package/dist/src/storage/storage.js.map +1 -1
  75. package/dist/src/telegram-features.d.ts +33 -0
  76. package/dist/src/telegram-features.d.ts.map +1 -0
  77. package/dist/src/telegram-features.js +69 -0
  78. package/dist/src/telegram-features.js.map +1 -0
  79. package/dist/src/testing.d.ts +1 -0
  80. package/dist/src/testing.d.ts.map +1 -1
  81. package/dist/src/testing.js +16 -0
  82. package/dist/src/testing.js.map +1 -1
  83. package/dist-cjs/src/api/index.js +1 -0
  84. package/dist-cjs/src/api/telegram-types/LICENSE +21 -0
  85. package/dist-cjs/src/api/telegram-types/api.d.ts +22 -0
  86. package/dist-cjs/src/api/telegram-types/checklist.d.ts +72 -0
  87. package/dist-cjs/src/api/telegram-types/inline.d.ts +692 -0
  88. package/dist-cjs/src/api/telegram-types/langs.d.ts +193 -0
  89. package/dist-cjs/src/api/telegram-types/manage.d.ts +1144 -0
  90. package/dist-cjs/src/api/telegram-types/markup.d.ts +268 -0
  91. package/dist-cjs/src/api/telegram-types/message.d.ts +1537 -0
  92. package/dist-cjs/src/api/telegram-types/methods.d.ts +2870 -0
  93. package/dist-cjs/src/api/telegram-types/mod.d.ts +14 -0
  94. package/dist-cjs/src/api/telegram-types/passport.d.ts +163 -0
  95. package/dist-cjs/src/api/telegram-types/payment.d.ts +570 -0
  96. package/dist-cjs/src/api/telegram-types/rich.d.ts +1010 -0
  97. package/dist-cjs/src/api/telegram-types/settings.d.ts +120 -0
  98. package/dist-cjs/src/api/telegram-types/story.d.ts +89 -0
  99. package/dist-cjs/src/api/telegram-types/update.d.ts +84 -0
  100. package/dist-cjs/src/api/telegram.js +2 -0
  101. package/dist-cjs/src/approval/approval.js +11 -1
  102. package/dist-cjs/src/cache/cache.js +7 -3
  103. package/dist-cjs/src/context/context.js +26 -3
  104. package/dist-cjs/src/core/bot.js +48 -7
  105. package/dist-cjs/src/index.js +1 -0
  106. package/dist-cjs/src/queue/queue.js +177 -51
  107. package/dist-cjs/src/router/router.js +75 -17
  108. package/dist-cjs/src/state/conversation.js +79 -11
  109. package/dist-cjs/src/state/menu.js +118 -18
  110. package/dist-cjs/src/storage/storage.js +135 -5
  111. package/dist-cjs/src/telegram-features.js +74 -0
  112. package/dist-cjs/src/testing.js +17 -0
  113. package/docs/API.id.md +1800 -0
  114. package/docs/API.md +1799 -0
  115. package/docs/API.zh-CN.md +1794 -0
  116. package/docs/README.md +26 -15
  117. package/package.json +13 -2
package/assets/readme-preview.html ADDED
@@ -0,0 +1,75 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>telebibz README preview</title>
6
+ <style>
7
+ :root { color-scheme: dark; --bg:#07111f; --panel:#0d1b2d; --panel2:#11243a; --line:#24415f; --text:#f1f7ff; --muted:#9db1c8; --cyan:#42d9ff; --blue:#668cff; --green:#72e1ad; --orange:#ffbd6b; }
8
+ * { box-sizing: border-box; }
9
+ body { margin:0; width:1600px; min-height:1000px; font-family: Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif; background: radial-gradient(circle at 10% 0%, #12345b 0, transparent 37%), linear-gradient(135deg,#06101d,#0a1728 55%,#071221); color:var(--text); }
10
+ .wrap { padding:58px 74px 64px; }
11
+ .top { display:flex; align-items:center; justify-content:space-between; margin-bottom:44px; }
12
+ .brand { display:flex; align-items:center; gap:20px; }
13
+ .mark { width:78px; height:78px; border-radius:22px; background:linear-gradient(145deg,#39d9ff,#637cff); display:grid; place-items:center; box-shadow:0 18px 45px #1e8bdc55; font-weight:900; font-size:31px; letter-spacing:-3px; color:#fff; }
14
+ h1 { font-size:48px; line-height:1; margin:0 0 10px; letter-spacing:-2px; }
15
+ .tag { color:var(--muted); font-size:20px; }
16
+ .lang { border:1px solid var(--line); background:#0b1b2d; color:#dcecff; padding:12px 18px; border-radius:12px; font-weight:700; }
17
+ .hero { display:grid; grid-template-columns: 1fr 1.15fr; gap:34px; align-items:stretch; }
18
+ .hero-copy { padding:30px 0 10px; }
19
+ .eyebrow { color:var(--cyan); text-transform:uppercase; letter-spacing:2px; font-size:13px; font-weight:800; }
20
+ h2 { font-size:42px; line-height:1.08; letter-spacing:-1.5px; margin:14px 0 18px; max-width:630px; }
21
+ .lead { color:#bfd0e4; font-size:20px; line-height:1.5; max-width:640px; }
22
+ .pill-row { display:flex; flex-wrap:wrap; gap:10px; margin-top:26px; }
23
+ .pill { border:1px solid #2d5277; background:#0c2035; color:#dcefff; padding:9px 13px; border-radius:999px; font-size:14px; }
24
+ .code { border:1px solid var(--line); background:#071525; border-radius:20px; overflow:hidden; box-shadow:0 22px 70px #0006; }
25
+ .code-head { display:flex; align-items:center; gap:8px; padding:15px 18px; background:#0d2137; border-bottom:1px solid var(--line); color:#91abc8; font-size:14px; }
26
+ .dot { width:10px; height:10px; border-radius:50%; background:#fb7185; } .dot:nth-child(2){background:#fbbf24}.dot:nth-child(3){background:#34d399}
27
+ pre { margin:0; padding:24px 28px 30px; font-family:"SFMono-Regular",Consolas,monospace; font-size:18px; line-height:1.62; color:#d9e8fa; white-space:pre-wrap; }
28
+ .kw { color:#9b9dff; }.fn { color:#74e7ff; }.str { color:#8de8ae; }.cm { color:#6f8ba8; }
29
+ .section-title { margin:56px 0 20px; display:flex; align-items:end; justify-content:space-between; }
30
+ .section-title h3 { margin:0; font-size:26px; letter-spacing:-.5px; }.section-title span { color:var(--muted); font-size:14px; }
31
+ .cards { display:grid; grid-template-columns:repeat(4,1fr); gap:16px; }
32
+ .card { min-height:150px; padding:21px; border:1px solid var(--line); background:linear-gradient(145deg,#0d2034,#0b1828); border-radius:16px; }
33
+ .icon { color:var(--cyan); font-size:22px; font-weight:900; }.card strong { display:block; margin:12px 0 8px; font-size:17px; }.card p { margin:0; color:var(--muted); line-height:1.45; font-size:14px; }
34
+ .footer { display:flex; justify-content:space-between; gap:20px; margin-top:40px; padding-top:20px; border-top:1px solid var(--line); color:var(--muted); font-size:14px; }
35
+ .status { color:var(--green); font-weight:800; }
36
+ </style>
37
+ </head>
38
+ <body>
39
+ <main class="wrap">
40
+ <header class="top">
41
+ <div class="brand"><div class="mark">tb</div><div><h1>telebibz</h1><div class="tag">Telegram Bot Framework for Node.js &amp; TypeScript</div></div></div>
42
+ <div class="lang">English &nbsp;·&nbsp; Bahasa Indonesia &nbsp;·&nbsp; 简体中文</div>
43
+ </header>
44
+ <section class="hero">
45
+ <div class="hero-copy">
46
+ <div class="eyebrow">Typed. Composable. Production-minded.</div>
47
+ <h2>Build serious Telegram bots without fighting the API.</h2>
48
+ <p class="lead">A full-scale framework with typed API access, routing, middleware, context helpers, keyboards, sessions, webhooks, queues, scheduling, plugins, approval gates, and test utilities.</p>
49
+ <div class="pill-row"><span class="pill">Node.js ≥ 20</span><span class="pill">ESM + CommonJS</span><span class="pill">Telegram Bot API 10.2</span><span class="pill">TypeScript strict</span></div>
50
+ </div>
51
+ <div class="code"><div class="code-head"><span class="dot"></span><span class="dot"></span><span class="dot"></span><span style="margin-left:8px">examples/minimal.ts</span></div><pre><span class="kw">import</span> { <span class="fn">Bot</span>, <span class="fn">InlineKeyboard</span> } <span class="kw">from</span> <span class="str">"@xbibzlibrary/telebibz"</span>;
52
+
53
+ <span class="kw">const</span> bot = <span class="kw">new</span> <span class="fn">Bot</span>(process.env.TELEGRAM_BOT_TOKEN!);
54
+
55
+ bot.<span class="fn">command</span>(<span class="str">"start"</span>, (ctx) =&gt;
56
+ ctx.<span class="fn">reply</span>(<span class="str">"Welcome to telebibz"</span>, {
57
+ reply_markup: <span class="kw">new</span> <span class="fn">InlineKeyboard</span>()
58
+ .<span class="fn">text</span>(<span class="str">"Explore API"</span>, <span class="str">"api"</span>)
59
+ .<span class="fn">build</span>(),
60
+ }),
61
+ );
62
+
63
+ <span class="kw">await</span> bot.<span class="fn">start</span>();</pre></div>
64
+ </section>
65
+ <div class="section-title"><h3>One framework, the whole bot lifecycle</h3><span>Designed around real Telegram primitives</span></div>
66
+ <section class="cards">
67
+ <article class="card"><div class="icon">01</div><strong>Typed API client</strong><p>Dynamic Telegram method access with typed core methods, errors, retry, timeout, JSON, multipart, and AbortSignal.</p></article>
68
+ <article class="card"><div class="icon">02</div><strong>Router + context</strong><p>Commands, exact text, regex, callbacks, predicates, nested routes, middleware composition, and ergonomic replies.</p></article>
69
+ <article class="card"><div class="icon">03</div><strong>Stateful workflows</strong><p>Sessions, forms, conversations, wizards, menus, pagination, queues, schedulers, caches, and plugins.</p></article>
70
+ <article class="card"><div class="icon">04</div><strong>Release hardening</strong><p>Approval gate, webhook secret verification, ESM/CommonJS builds, tests, security checks, and npm provenance.</p></article>
71
+ </section>
72
+ <footer class="footer"><span>xbibzlibrary/telebibz · documented in three languages</span><span class="status">● API surface documented</span></footer>
73
+ </main>
74
+ </body>
75
+ </html>
package/dist/src/api/index.d.ts CHANGED
@@ -2,4 +2,5 @@ export * from "./client.js";
2
2
  export * from "./errors.js";
3
3
  export * from "./transport.js";
4
4
  export * from "./types.js";
5
+ export * from "./telegram.js";
5
6
  //# sourceMappingURL=index.d.ts.map
package/dist/src/api/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC"}
package/dist/src/api/index.js CHANGED
@@ -2,4 +2,5 @@ export * from "./client.js";
2
2
  export * from "./errors.js";
3
3
  export * from "./transport.js";
4
4
  export * from "./types.js";
5
+ export * from "./telegram.js";
5
6
  //# sourceMappingURL=index.js.map
package/dist/src/api/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC"}
package/dist/src/api/telegram-types/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2021-2024 KnorpelSenf
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/dist/src/api/telegram-types/api.d.ts ADDED
@@ -0,0 +1,22 @@
1
+ export interface ApiError {
2
+ ok: false;
3
+ error_code: number;
4
+ description: string;
5
+ parameters?: ResponseParameters;
6
+ }
7
+ export interface ApiSuccess<T> {
8
+ ok: true;
9
+ result: T;
10
+ }
11
+ /** The response contains an object, which always has a Boolean field 'ok' and may have an optional String field 'description' with a human-readable description of the result. If 'ok' equals True, the request was successful and the result of the query can be found in the 'result' field. In case of an unsuccessful request, 'ok' equals False and the error is explained in the 'description'. An Integer 'error_code' field is also returned, but its contents are subject to change in the future. Some errors may also have an optional field 'parameters' of the type ResponseParameters, which can help to automatically handle the error.
12
+
13
+ - All methods in the Bot API are case-insensitive.
14
+ - All queries must be made using UTF-8. */
15
+ export type ApiResponse<T> = ApiError | ApiSuccess<T>;
16
+ /** Describes why a request was unsuccessful. */
17
+ export interface ResponseParameters {
18
+ /** The group has been migrated to a supergroup with the specified identifier. */
19
+ migrate_to_chat_id?: number;
20
+ /** In case of exceeding flood control, the number of seconds left to wait before the request can be repeated */
21
+ retry_after?: number;
22
+ }
package/dist/src/api/telegram-types/checklist.d.ts ADDED
@@ -0,0 +1,72 @@
1
+ import type { Chat, User } from "./manage.js";
2
+ import type { Message, MessageEntity, ParseMode } from "./message.js";
3
+ /** Describes a task in a checklist. */
4
+ export interface ChecklistTask {
5
+ /** Unique identifier of the task */
6
+ id: number;
7
+ /** Text of the task */
8
+ text: string;
9
+ /** Special entities that appear in the task text */
10
+ text_entities?: MessageEntity[];
11
+ /** User that completed the task; omitted if the task wasn't completed by a user */
12
+ completed_by_user?: User;
13
+ /** Chat that completed the task; omitted if the task wasn't completed by a chat */
14
+ completed_by_chat?: Chat;
15
+ /** Point in time (Unix timestamp) when the task was completed; 0 if the task wasn't completed */
16
+ completion_date?: number;
17
+ }
18
+ /** Describes a checklist. */
19
+ export interface Checklist {
20
+ /** Title of the checklist */
21
+ title: string;
22
+ /** Special entities that appear in the checklist title */
23
+ title_entities?: MessageEntity[];
24
+ /** List of tasks in the checklist */
25
+ tasks: ChecklistTask[];
26
+ /** True, if users other than the creator of the list can add tasks to the list */
27
+ others_can_add_tasks?: true;
28
+ /** True, if users other than the creator of the list can mark tasks as done or not done */
29
+ others_can_mark_tasks_as_done?: true;
30
+ }
31
+ /** Describes a task to add to a checklist. */
32
+ export interface InputChecklistTask {
33
+ /** Unique identifier of the task; must be positive and unique among all task identifiers currently present in the checklist */
34
+ id: number;
35
+ /** Text of the task; 1-100 characters after entities parsing */
36
+ text: string;
37
+ /** Mode for parsing entities in the text. See formatting options for more details. */
38
+ parse_mode?: ParseMode;
39
+ /** List of special entities that appear in the text, which can be specified instead of parse_mode. Currently, only bold, italic, underline, strikethrough, spoiler, custom_emoji, and date_time entities are allowed. */
40
+ text_entities?: MessageEntity[];
41
+ }
42
+ /** Describes a checklist to create. */
43
+ export interface InputChecklist {
44
+ /** Title of the checklist; 1-255 characters after entities parsing */
45
+ title: string;
46
+ /** Mode for parsing entities in the title. See formatting options for more details. */
47
+ parse_mode?: ParseMode;
48
+ /** List of special entities that appear in the title, which can be specified instead of parse_mode. Currently, only bold, italic, underline, strikethrough, spoiler, custom_emoji, and date_time entities are allowed. */
49
+ title_entities?: MessageEntity[];
50
+ /** List of 1-30 tasks in the checklist */
51
+ tasks: InputChecklistTask[];
52
+ /** Pass True if other users can add tasks to the checklist */
53
+ others_can_add_tasks?: boolean;
54
+ /** Pass True if other users can mark tasks as done or not done in the checklist */
55
+ others_can_mark_tasks_as_done?: true;
56
+ }
57
+ /** Describes a service message about checklist tasks marked as done or not done. */
58
+ export interface ChecklistTasksDone {
59
+ /** Message containing the checklist whose tasks were marked as done or not done. Note that the Message object in this field will not contain the reply_to_message field even if it itself is a reply. */
60
+ checklist_message?: Message;
61
+ /** Identifiers of the tasks that were marked as done */
62
+ marked_as_done_task_ids?: number[];
63
+ /** Identifiers of the tasks that were marked as not done */
64
+ marked_as_not_done_task_ids?: number[];
65
+ }
66
+ /** Describes a service message about tasks added to a checklist. */
67
+ export interface ChecklistTasksAdded {
68
+ /** Message containing the checklist to which the tasks were added. Note that the Message object in this field will not contain the reply_to_message field even if it itself is a reply. */
69
+ checklist_message?: Message;
70
+ /** List of tasks added to the checklist */
71
+ tasks: ChecklistTask[];
72
+ }