@xbibzlibrary/telebibz 0.1.0 → 0.1.2

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 (5) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/README.md +68 -97
  3. package/RELEASE_POLICY.md +32 -0
  4. package/assets/telebibz-logo.png +0 -0
  5. package/package.json +3 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.2 — 2026-08-19
4
+
5
+ ### Changed
6
+
7
+ - README logo now uses the version-pinned jsDelivr CDN URL.
8
+
9
+ ## 0.1.1 — 2026-08-19
10
+
11
+ ### Changed
12
+
13
+ - Added the telebibz logo asset to the package.
14
+ - Rewrote the README around the actual public API and scoped installation path.
15
+ - Added concise documentation links for approval, security, and release policy.
16
+
3
17
  ## 0.1.0 — 2026-08-19
4
18
 
5
19
  ### Added
package/README.md CHANGED
@@ -1,10 +1,8 @@
1
1
  # telebibz
2
2
 
3
- `telebibz` adalah SDK dan framework Telegram Bot untuk Node.js dan TypeScript dengan low-level API access, typed context, router, middleware, sessions, keyboards, polling, webhook, storage, cache, queue, scheduler, plugins, CLI, serta testing utilities.
3
+ ![telebibz logo](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@0.1.2/assets/telebibz-logo.png)
4
4
 
5
- > **Status rilis saat ini: `PARTIAL` / development release.** Core transport, API runtime, lifecycle, polling, webhook handler, routing, middleware, keyboards, storage, queue, scheduler, plugins, tests, dan ESM/CommonJS build telah diimplementasikan dan diverifikasi. Full strongly typed schema untuk seluruh object Telegram, seluruh optional adapters, Mini App UI SDK, payments orchestration, conversations/scenes/wizard/forms, serta real Telegram E2E masih memerlukan milestone lanjutan. Package tidak mengklaim production-ready sebelum semua gate dan credentials eksternal tersedia.
6
-
7
- Target generated API mengikuti dokumentasi resmi Telegram Bot API yang tersedia saat build, saat ini Bot API **10.2**.[^telegram-api]
5
+ **`@xbibzlibrary/telebibz`** adalah SDK dan framework Telegram Bot untuk Node.js dan TypeScript. Package ini menyediakan API client, polling, router, middleware, context, keyboard builder, state/session, webhook handler, queue, scheduler, cache, plugin lifecycle, CLI, dan testing utilities.
8
6
 
9
7
  ## Instalasi
10
8
 
@@ -12,37 +10,22 @@ Target generated API mengikuti dokumentasi resmi Telegram Bot API yang tersedia
12
10
  npm install @xbibzlibrary/telebibz
13
11
  ```
14
12
 
15
- Package mendukung ESM:
13
+ Node.js **20 atau lebih baru** diperlukan.
14
+
15
+ ## Bot sederhana
16
16
 
17
17
  ```ts
18
- import { Bot, InlineKeyboard } from "@xbibzlibrary/telebibz";
18
+ import { Bot } from "@xbibzlibrary/telebibz";
19
19
 
20
20
  const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
21
- bot.command("start", (ctx) => ctx.reply("Halo dari telebibz", {
22
- reply_markup: new InlineKeyboard().text("Status", "status").build()
23
- }));
24
- await bot.start();
25
- ```
26
-
27
- dan CommonJS:
28
-
29
- ```js
30
- const { Bot } = require("@xbibzlibrary/telebibz");
31
- const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN);
32
- ```
33
-
34
- ## Low-level API
35
21
 
36
- Setiap method yang terdeteksi dari dokumentasi resmi tersedia melalui `bot.api.methods.<method>()`. API raw tetap tersedia untuk method baru sebelum convenience abstraction dibuat.
22
+ bot.command("start", (ctx) => ctx.reply("Bot aktif."));
23
+ bot.onText("ping", (ctx) => ctx.reply("pong"));
37
24
 
38
- ```ts
39
- await bot.api.methods.getMe();
40
- await bot.api.methods.sendMessage({ chat_id: 123, text: "hello" });
41
- await bot.api.call("sendMessage", { chat_id: 123, text: "hello" });
42
- await bot.api.raw("futureTelegramMethod", { value: true });
25
+ await bot.start();
43
26
  ```
44
27
 
45
- Transport default memakai HTTPS `fetch`, JSON untuk payload biasa, dan multipart untuk input file. Transport dapat diganti dengan implementasi custom melalui `BotOptions.transport`.
28
+ `Bot.start()` menjalankan long polling. Untuk lifecycle manual, gunakan `init()`, `launch({ mode: "polling" })`, `health()`, `stop()`, atau `restart()`.
46
29
 
47
30
  ## Router dan middleware
48
31
 
@@ -50,32 +33,47 @@ Transport default memakai HTTPS `fetch`, JSON untuk payload biasa, dan multipart
50
33
  bot.use(async (ctx, next) => {
51
34
  const started = Date.now();
52
35
  await next();
53
- console.log(`update processed in ${Date.now() - started}ms`);
36
+ console.log(`processed in ${Date.now() - started}ms`);
54
37
  });
55
38
 
56
- bot.command("help", (ctx) => ctx.reply("Help"));
57
- bot.onText("ping", (ctx) => ctx.reply("pong"));
58
- bot.onRegex(/^order:(\\d+)$/, (ctx) => ctx.reply("Order received"));
59
- bot.callback("user:*", async (ctx) => ctx.answerCallbackQuery("Opened"));
39
+ bot.command("help", (ctx) => ctx.reply("Bantuan tersedia."));
40
+ bot.onRegex(/^order:(\\d+)$/, (ctx) => ctx.reply("Order diterima."));
41
+ bot.callback("profile:", (ctx) => ctx.answerCallbackQuery("Dibuka."));
42
+ ```
43
+
44
+ Router mendukung command, text, regex, callback pattern, custom predicate, nested router, middleware per route, dan prioritas route.
45
+
46
+ ## Telegram API
47
+
48
+ Generated method access dan raw access tersedia melalui API client:
49
+
50
+ ```ts
51
+ await bot.api.methods.getMe();
52
+ await bot.api.methods.sendMessage({ chat_id: 123456789, text: "Halo." });
53
+ await bot.api.call("sendMessage", { chat_id: 123456789, text: "Halo." });
54
+ await bot.api.raw("futureTelegramMethod", { value: true });
60
55
  ```
61
56
 
62
- Middleware memakai komposisi async dengan `next()` dan mencegah pemanggilan `next()` ganda. Router menyediakan command, text, regex, callback prefix/exact, chat matcher, custom predicate, nested router, dan priority ordering.
57
+ Transport bawaan menggunakan `fetch`, timeout, retry, exponential backoff, JSON payload, dan multipart upload.
63
58
 
64
- ## Lifecycle dan health
59
+ ## Keyboard
65
60
 
66
61
  ```ts
67
- await bot.init();
68
- const health = await bot.health();
69
- await bot.start();
70
- await bot.stop();
71
- await bot.restart();
62
+ import { InlineKeyboard } from "@xbibzlibrary/telebibz";
63
+
64
+ const keyboard = new InlineKeyboard()
65
+ .text("Profil", "profile")
66
+ .url("Dokumentasi", "https://core.telegram.org/bots/api")
67
+ .build();
68
+
69
+ await ctx.reply("Pilih menu:", { reply_markup: keyboard });
72
70
  ```
73
71
 
74
- `start()` menggunakan long polling. Polling memiliki offset management, allowed updates, timeout, retry, exponential backoff, reconnect event, dan graceful shutdown. Webhook dapat digunakan melalui `createWebhookHandler(bot, options)` dan memverifikasi `X-Telegram-Bot-Api-Secret-Token`.
72
+ Builder hanya menghasilkan payload keyboard native Telegram. UI HTML/CSS memerlukan Mini App atau Web App terpisah.
75
73
 
76
- ## Approval owner sebelum bot aktif
74
+ ## Owner approval
77
75
 
78
- Jika library dipakai dalam mode approval, bot akan mengirim notifikasi ke `ownerChatId` dan menahan update biasa sampai owner menekan tombol **Izinkan**. Tombol **Tidak Diizinkan** menutup permintaan. Callback approval ditandatangani dengan nonce acak dan hanya diterima dari `ownerUserId`; callback dari user lain ditolak.
76
+ Approval gate menahan update biasa sampai owner menyetujui bot melalui tombol **Izinkan** atau **Tidak Diizinkan**.
79
77
 
80
78
  ```ts
81
79
  const bot = new Bot({
@@ -87,85 +85,58 @@ const bot = new Bot({
87
85
  requireApproval: true,
88
86
  },
89
87
  });
90
-
91
- bot.command("start", (ctx) => ctx.reply("Bot sudah diizinkan."));
92
- await bot.start();
93
88
  ```
94
89
 
95
- Pesan yang dikirim berbentuk:
90
+ Library mengirim notifikasi ke `ownerChatId`, sedangkan hanya `ownerUserId` yang dapat mengambil keputusan. Callback menggunakan nonce acak. Untuk deployment multi-instance, gunakan `ApprovalStore` persisten melalui database atau Redis; default-nya adalah memory store.
96
91
 
97
- > Haloo Dev Gantenggg, ada yang memakai library telebibz nihh
98
- >
99
- > Bot: @example_bot (ID: 123456)
100
- > Owner ID: 987654
101
- > Status: menunggu izin owner.
102
- >
103
- > `[Izinkan] [Tidak Diizinkan]`
104
-
105
- Mode ini bersifat **eksplisit dan configurable**. Library tidak mengirim identitas ke server pihak ketiga secara diam-diam; notifikasi dikirim melalui Telegram ke `ownerChatId` yang dikonfigurasi. Untuk production, gunakan `ApprovalStore` persisten dan jelaskan mekanisme ini kepada pengguna bot.
106
-
107
- ## Keyboard
108
-
109
- Builder hanya menghasilkan kemampuan native Telegram yang valid. Styling CSS bebas tidak dipalsukan pada native keyboard; gunakan Mini App/Web App untuk UI HTML/CSS.
92
+ ## Webhook
110
93
 
111
94
  ```ts
112
- const keyboard = new InlineKeyboard()
113
- .text("Profile", "profile")
114
- .url("Documentation", "https://core.telegram.org/bots/api")
115
- .row({ text: "Copy", copy_text: { text: "telebibz" } })
116
- .build();
117
- ```
118
-
119
- ## Storage, queue, scheduler, cache
120
-
121
- Core menyediakan `MemoryStorage` dengan TTL dan atomic update, `MemoryCache`, `TokenBucketLimiter`, `TaskQueue` dengan retry/backoff/concurrency/priority/delay/cancel, serta scheduler interval/one-shot dan limited simple cron adapter. Adapter distributed seperti Redis, PostgreSQL, MySQL, MongoDB, dan queue vendor harus ditambahkan sebagai package optional terpisah.
122
-
123
- ## Testing
124
-
125
- ```bash
126
- node_modules/.bin/tsc -p tsconfig.json --noEmit
127
- node_modules/.bin/tsc -p tests/tsconfig.json --noEmit
128
- node_modules/.bin/vitest run
129
- node_modules/.bin/eslint scripts/*.mjs bin/*.mjs
130
- ```
131
-
132
- Testing utilities tidak dipakai oleh production transport. `MockTransport`, `createTestBot`, `createMockUpdate`, dan `createMockContext` hanya berada pada export testing.
95
+ import { Bot, createWebhookHandler } from "@xbibzlibrary/telebibz";
133
96
 
134
- Real Telegram E2E hanya berjalan jika environment menyediakan:
135
-
136
- ```bash
137
- TELEGRAM_BOT_TOKEN=...
138
- TELEGRAM_TEST_CHAT_ID=...
97
+ const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
98
+ const handler = createWebhookHandler(bot, {
99
+ secretToken: process.env.TELEGRAM_WEBHOOK_SECRET,
100
+ });
139
101
  ```
140
102
 
141
- Tanpa credentials tersebut, test E2E berstatus skipped/blocked dan tidak boleh dianggap PASS.
103
+ `createWebhookHandler` menerima Web standard `Request` dan menghasilkan `Response`. Secret token, ukuran body, parsing JSON, dan duplicate update handling diverifikasi oleh handler.
142
104
 
143
- ## Generated API
105
+ ## State, queue, scheduler, dan cache
144
106
 
145
- ```bash
146
- node scripts/generate-api.mjs
147
- ```
148
-
149
- Generator membaca dokumentasi Telegram yang disimpan pada `schema/telegram-api.md`, menghasilkan `generated/api.ts`, dan menjaga generated method list terpisah dari handwritten framework code. Update source schema dan jalankan generator kembali ketika Bot API berubah.
107
+ Package menyediakan `MemoryStorage` dengan TTL dan atomic update, session pada context, conversation/form primitives, menu/pagination, `MemoryCache`, token-bucket limiter, task queue dengan retry/backoff/concurrency/delay/cancel, serta scheduler interval, one-shot, dan simple cron. Adapter Redis, SQL, MongoDB, dan queue vendor harus disediakan oleh aplikasi atau package optional.
150
108
 
151
109
  ## CLI
152
110
 
153
111
  ```bash
154
112
  npx telebibz init my-bot
155
113
  npx telebibz doctor
156
- npx telebibz generate
157
114
  npx telebibz build
158
115
  npx telebibz test
159
116
  ```
160
117
 
161
- `doctor` memeriksa Node version, keberadaan token, dan konektivitas API bila token tersedia.
118
+ ## Testing
119
+
120
+ ```bash
121
+ npm run typecheck
122
+ npm run test:types
123
+ npm run lint
124
+ npm test
125
+ npm run build
126
+ npm run security
127
+ npm run release:check
128
+ ```
129
+
130
+ Real Telegram E2E memerlukan `TELEGRAM_BOT_TOKEN` dan `TELEGRAM_TEST_CHAT_ID`. Tanpa credentials, E2E akan dilewati dan tidak dihitung sebagai lulus.
131
+
132
+ ## API target dan batasan
133
+
134
+ Method list dihasilkan dari dokumentasi Telegram Bot API saat schema diperbarui. Method access tersedia untuk method resmi yang terdeteksi, tetapi tidak semua object, union, enum, dan optional adapter memiliki typing tingkat lanjut penuh. Lihat [FEATURE_MATRIX.md](FEATURE_MATRIX.md) untuk status implementasi dan [APPROVAL_FEATURE.md](APPROVAL_FEATURE.md) untuk detail approval.
162
135
 
163
136
  ## Keamanan
164
137
 
165
- Token tidak ditulis ke log debug. Webhook secret dapat diverifikasi, body size dapat dibatasi, callback data dibatasi 64 byte, file upload tidak di-fetch dari URL arbitrer tanpa instruksi eksplisit, dan error Telegram dibedakan dari error network. Lihat [SECURITY.md](SECURITY.md).
138
+ Jangan commit token Telegram atau npm. Gunakan environment variable atau secret manager. Untuk kebijakan keamanan dan release hardening, lihat [SECURITY.md](SECURITY.md) dan [RELEASE_POLICY.md](RELEASE_POLICY.md).
166
139
 
167
140
  ## Lisensi
168
141
 
169
142
  MIT. Lihat [LICENSE](LICENSE).
170
-
171
- [^telegram-api]: [Telegram Bot API resmi](https://core.telegram.org/bots/api) dan [Bot API changelog](https://core.telegram.org/bots/api-changelog).
package/RELEASE_POLICY.md ADDED
@@ -0,0 +1,32 @@
1
+ # Release Policy
2
+
3
+ ## Scope and immutability
4
+
5
+ The published artifact is scoped as `@xbibzlibrary/telebibz`. npm package versions are immutable after publication: a released version must not be overwritten. Future changes require a new version and a new release candidate. Consumers can still fork or modify a locally installed copy; no npm package can technically prevent that. This project therefore protects the official release path rather than making local copies impossible to alter.
6
+
7
+ ## Hardening controls
8
+
9
+ Every release must pass strict TypeScript typechecking, type-level tests, lint, runtime tests, build for ESM and CommonJS, dependency audit, and `release:check`. The release checker rejects an incorrect scope, private package status, missing public publish configuration, missing provenance, install lifecycle scripts, credential patterns in tracked release content, and incomplete tarball contents.
10
+
11
+ The package uses npm provenance configuration and a protected GitHub Actions release workflow. The publish token must be stored only as a repository secret or temporary `NPM_TOKEN` environment variable with the smallest possible scope. Tokens must never be committed, placed in `.npmrc` inside the repository, or included in archives.
12
+
13
+ ## Release verification
14
+
15
+ Before publish, run:
16
+
17
+ ```bash
18
+ npm run typecheck
19
+ npm run test:types
20
+ npm run lint
21
+ npm test
22
+ npm run build
23
+ npm run security
24
+ npm run release:check
25
+ npm pack --dry-run
26
+ ```
27
+
28
+ After publish, verify the public registry metadata and tarball with `npm view @xbibzlibrary/telebibz version dist.integrity dist.tarball` and a clean install into a new directory. Record the tarball integrity value with the release notes.
29
+
30
+ ## Organization permissions
31
+
32
+ Only maintainers with publish permission in the `xbibzlibrary` organization may publish. Enable two-factor authentication or organization-level publish controls where available. Use granular access tokens and rotate them immediately if they are pasted into chat, logs, source, or any untrusted system.
package/assets/telebibz-logo.png ADDED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xbibzlibrary/telebibz",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Production-grade, strongly typed Telegram Bot API SDK and framework for Node.js and TypeScript.",
5
5
  "type": "module",
6
6
  "private": false,
@@ -66,6 +66,8 @@
66
66
  "CHANGELOG.md",
67
67
  "SECURITY.md",
68
68
  "APPROVAL_FEATURE.md",
69
+ "RELEASE_POLICY.md",
70
+ "assets",
69
71
  "docs"
70
72
  ],
71
73
  "devDependencies": {