@xbibzlibrary/telebibz 0.1.18 → 0.2.1

package/docs/GETTING_STARTED.md

@@ -0,0 +1,85 @@
+# Getting started with Telebibz
+
+This guide takes a new developer from installation to a working Telegram bot in a few minutes.
+
+## 1. Create a bot token
+
+Create a bot with Telegram's official bot management account and keep the token in your deployment environment. Never commit it to source control.
+
+## 2. Install Telebibz
+
+```bash
+mkdir my-telebibz-bot && cd my-telebibz-bot
+npm init -y
+npm install @xbibzlibrary/telebibz
+npm install --save-dev tsx typescript
+```
+
+Create `.env` through your secret manager or export the variable in the shell:
+
+```bash
+export TELEGRAM_BOT_TOKEN="<your-bot-token>"
+```
+
+## 3. Write the first bot
+
+Create `index.ts`:
+
+```ts
+import { Bot } from "@xbibzlibrary/telebibz";
+
+const token = process.env.TELEGRAM_BOT_TOKEN;
+if (!token) throw new Error("TELEGRAM_BOT_TOKEN is required.");
+
+const bot = new Bot(token);
+bot.command("start", async (ctx) => { await ctx.reply("Telebibz is working."); });
+bot.onText("ping", async (ctx) => { await ctx.reply("pong"); });
+
+await bot.start();
+```
+
+Run it with:
+
+```bash
+npx tsx index.ts
+```
+
+Send `/start` or `ping` to the bot. The terminal displays the Telebibz branding and structured logs. Set the logger format to `json` when a log collector consumes the output.
+
+## 4. Add a multi-step wizard
+
+Use `Wizard` and `bot.useWizard()` when replies should continue through active steps. Start the flow explicitly with `wizard.run(ctx)`:
+
+```ts
+const wizard = new Wizard()
+  .step({ id: "name", run: async (flow) => {
+    flow.set("name", flow.ctx.message?.text?.trim()).next();
+    await flow.ctx.reply("How old are you?");
+  }})
+  .step({ id: "age", run: async (flow) => {
+    const age = Number(flow.ctx.message?.text?.trim());
+    if (!Number.isInteger(age)) { await flow.ctx.reply("Send a whole number."); return; }
+    flow.set("age", age).next();
+    await flow.ctx.reply("Registration complete.");
+  }});
+
+bot.useWizard(wizard);
+bot.command("register", async (ctx) => {
+  await wizard.run(ctx);
+  await ctx.reply("What is your name?");
+});
+```
+
+The default conversation manager persists for the lifetime of the wizard instance, and the key is derived from chat and sender identity. `/cancel` cancels the active flow by default.
+
+## 5. Production checklist
+
+Use HTTPS for webhooks, verify the Telegram webhook secret, keep tokens in a secret manager, configure structured JSON logs, add health checks, use persistent storage for sessions that must survive restarts, and run `npm run typecheck`, `npm run test:types`, `npm run test:examples`, `npm test`, `npm run build`, and `npm run security` before deployment.
+
+## Next steps
+
+- [Runnable examples](../examples/README.md)
+- [Complete API reference](API.md)
+- [Webhook API](API.md#10-webhook)
+- [Conversations and wizards](API.md#8-state-session-and-conversations)
+- [Contribution guide](../CONTRIBUTING.md)

package/docs/GETTING_STARTED.zh-CN.md

@@ -0,0 +1,85 @@
+# Telebibz 入门
+
+本指南帮助新开发者在几分钟内完成安装并运行 Telegram bot。
+
+## 1. 创建 bot token
+
+通过 Telegram 官方 bot 管理账号创建 bot，并将 token 保存在部署环境中。不要把 token 提交到 source control。
+
+## 2. 安装 Telebibz
+
+```bash
+mkdir my-telebibz-bot && cd my-telebibz-bot
+npm init -y
+npm install @xbibzlibrary/telebibz
+npm install --save-dev tsx typescript
+```
+
+请使用 secret manager，或在 shell 中设置变量：
+
+```bash
+export TELEGRAM_BOT_TOKEN="<your-bot-token>"
+```
+
+## 3. 编写第一个 bot
+
+创建 `index.ts`：
+
+```ts
+import { Bot } from "@xbibzlibrary/telebibz";
+
+const token = process.env.TELEGRAM_BOT_TOKEN;
+if (!token) throw new Error("TELEGRAM_BOT_TOKEN is required.");
+
+const bot = new Bot(token);
+bot.command("start", async (ctx) => { await ctx.reply("Telebibz is working."); });
+bot.onText("ping", async (ctx) => { await ctx.reply("pong"); });
+
+await bot.start();
+```
+
+运行：
+
+```bash
+npx tsx index.ts
+```
+
+向 bot 发送 `/start` 或 `ping`。终端会显示 Telebibz branding 和 structured logs。如果日志会被 log collector 读取，请将 logger format 设置为 `json`。
+
+## 4. 添加多步骤 wizard
+
+当回复需要继续处理 active step 时，使用 `Wizard` 和 `bot.useWizard()`。使用 `wizard.run(ctx)` 显式开始 flow：
+
+```ts
+const wizard = new Wizard()
+  .step({ id: "name", run: async (flow) => {
+    flow.set("name", flow.ctx.message?.text?.trim()).next();
+    await flow.ctx.reply("How old are you?");
+  }})
+  .step({ id: "age", run: async (flow) => {
+    const age = Number(flow.ctx.message?.text?.trim());
+    if (!Number.isInteger(age)) { await flow.ctx.reply("Send a whole number."); return; }
+    flow.set("age", age).next();
+    await flow.ctx.reply("Registration complete.");
+  }});
+
+bot.useWizard(wizard);
+bot.command("register", async (ctx) => {
+  await wizard.run(ctx);
+  await ctx.reply("What is your name?");
+});
+```
+
+default conversation manager 会在 wizard instance 生命周期内持续使用，key 会根据 chat 和 sender identity 生成。默认情况下，`/cancel` 会取消 active flow。
+
+## 5. Production checklist
+
+Webhook 使用 HTTPS，验证 Telegram webhook secret，将 token 保存到 secret manager，配置 structured JSON logs，添加 health checks；如果 session 必须跨重启保留，请使用 persistent storage。部署前运行 `npm run typecheck`、`npm run test:types`、`npm run test:examples`、`npm test`、`npm run build` 和 `npm run security`。
+
+## 下一步
+
+- [Runnable examples](../examples/README.md)
+- [完整 API 参考](API.zh-CN.md)
+- [Webhook API](API.zh-CN.md#10-webhook)
+- [Conversation 和 wizard](API.zh-CN.md#8-state-session-and-conversations)
+- [贡献指南](../CONTRIBUTING.md)

package/docs/README.md

@@ -10,11 +10,19 @@ The default documentation language is **English**. Translated README and API ref
 
 ![telebibz overview](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@latest/assets/telebibz-readme-preview.png)
 
-The API references are organized by lifecycle: bot startup and shutdown, API client and transport, update routing, middleware and context, state/session, interaction UI, background work, deployment, testing, and migration boundaries.
+The documentation covers the complete lifecycle: onboarding, bot startup and shutdown, API client and transport, update routing, middleware and context, state/session, interaction UI, background work, deployment, testing, and migration boundaries.
+
+| Resource | Purpose |
+|---|---|
+| [`GETTING_STARTED.md`](GETTING_STARTED.md) | Five-minute English onboarding from installation to a working bot. |
+| [`GETTING_STARTED.id.md`](GETTING_STARTED.id.md) | Indonesian onboarding guide. |
+| [`GETTING_STARTED.zh-CN.md`](GETTING_STARTED.zh-CN.md) | Simplified Chinese onboarding guide. |
+| [`../examples/README.md`](../examples/README.md) | Runnable minimal, wizard, and webhook starters. |
+| [`../SHOWCASE.md`](../SHOWCASE.md) | Community project showcase and submission format. |
 
 | Area | Status |
 |---|---|
-| Getting started | Available in all three README files |
+| Getting started | Dedicated guides are available in English, Indonesian, and Simplified Chinese, with runnable examples. |
 | Complete API reference | Available in English, Indonesian, and Simplified Chinese |
 | Bot lifecycle, polling, webhook | Core implementation, per-update error isolation, reconnect backoff, and tests available |
 | API client and generated method list | Available; full vendored Telegram declarations are exposed through `TelegramTypes` |
@@ -25,8 +33,8 @@ The API references are organized by lifecycle: bot startup and shutdown, API cli
 | Plugins, services, observability | Lifecycle/plugin/service hooks available |
 | Mini Apps, payments, business features | Web App signature validation and PaymentsClient wrappers available; UI is application-owned |
 | Testing and security | Unit, integration, type-level, gated E2E, CI, and security policy available |
-| Deployment and migration | Release automation is documented in `RELEASE_AUTOMATION.md` |
-| Governance and community | `CODE_OF_CONDUCT.md`, `GOVERNANCE.md`, `CONTRIBUTING.md`, and `CONTRIBUTION_RULES.md` |
+| Deployment and migration | Release automation is documented in `RELEASE_AUTOMATION.md`; webhook and deployment onboarding is in `GETTING_STARTED.md` |
+| Governance and community | `CODE_OF_CONDUCT.md`, `GOVERNANCE.md`, `CONTRIBUTING.md`, `CONTRIBUTION_RULES.md`, and `SHOWCASE.md` |
 | Security and support | `SECURITY.md` and `SUPPORT.md` |
 | Third-party notices | `NOTICE.md` and `LICENSE` |
 | GitHub contribution templates | Bug, feature, documentation, question/support, security notice, and pull request templates under `.github/` |

package/examples/README.md

@@ -0,0 +1,37 @@
+# Telebibz examples
+
+These examples are intentionally small, runnable starting points for developers evaluating Telebibz. They use environment variables for secrets and do not contain real Telegram credentials.
+
+## Run the examples
+
+From the repository root:
+
+```bash
+npm install
+export TELEGRAM_BOT_TOKEN="<your-bot-token>"
+npx tsx examples/minimal.ts
+```
+
+The official npm package can be used from a separate project by replacing the local import path with `@xbibzlibrary/telebibz` and installing the package from npm.
+
+## Available starters
+
+| Example | Demonstrates | Start command |
+|---|---|---|
+| `minimal.ts` | Commands, text routing, and a minimal long-polling bot. | `npx tsx examples/minimal.ts` |
+| `wizard-registration.ts` | A two-step name/age conversation with automatic continuation across messages. | `npx tsx examples/wizard-registration.ts` |
+| `webhook.ts` | A Node.js HTTP server, webhook secret validation, and Telegram update handling. | `TELEGRAM_WEBHOOK_SECRET=<secret> npx tsx examples/webhook.ts` |
+
+The wizard example starts the flow with `/register`, asks for a name, then asks for an age. Send `/cancel` to cancel an active flow. The webhook example requires both `TELEGRAM_BOT_TOKEN` and `TELEGRAM_WEBHOOK_SECRET`; expose the server through HTTPS in a deployment environment and configure the matching Telegram webhook secret.
+
+## Production checklist
+
+Use a secret manager or deployment environment for `TELEGRAM_BOT_TOKEN` and `TELEGRAM_WEBHOOK_SECRET`. Do not commit `.env` files or literal credentials. Run `npm run test:examples` before submitting changes. For production deployments, prefer a managed HTTPS endpoint, structured JSON logs, health checks, graceful shutdown, and a persistent storage adapter when conversations or sessions must survive restarts.
+
+## More documentation
+
+- [English API reference](../docs/API.md)
+- [Bahasa Indonesia API reference](../docs/API.id.md)
+- [简体中文 API reference](../docs/API.zh-CN.md)
+- [GitHub Packages guide](../docs/GITHUB_PACKAGES.md)
+- [Contributing guide](../CONTRIBUTING.md)

package/examples/minimal.ts

@@ -0,0 +1,12 @@
+import { Bot } from "@xbibzlibrary/telebibz";
+
+const token = process.env.TELEGRAM_BOT_TOKEN;
+if (!token) throw new Error("Set TELEGRAM_BOT_TOKEN before starting the example.");
+
+const bot = new Bot(token);
+
+bot.command("start", async (ctx) => { await ctx.reply("Hello from Telebibz. Send /help to see what I can do."); });
+bot.command("help", async (ctx) => { await ctx.reply("Commands:\n/start — welcome message\n/help — show this help"); });
+bot.onText("ping", async (ctx) => { await ctx.reply("pong"); });
+
+await bot.start();

package/examples/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": ".."
+  },
+  "include": ["./**/*.ts"],
+  "exclude": ["node_modules", "dist", "dist-cjs"]
+}

package/examples/webhook.ts

@@ -0,0 +1,42 @@
+import { createServer } from "node:http";
+import { Bot, createWebhookHandler } from "@xbibzlibrary/telebibz";
+
+const token = process.env.TELEGRAM_BOT_TOKEN;
+const webhookSecret = process.env.TELEGRAM_WEBHOOK_SECRET;
+const port = Number(process.env.PORT ?? 3000);
+
+if (!token) throw new Error("Set TELEGRAM_BOT_TOKEN before starting the example.");
+if (!webhookSecret) throw new Error("Set TELEGRAM_WEBHOOK_SECRET before starting the example.");
+if (!Number.isInteger(port) || port < 1 || port > 65_535) throw new Error("PORT must be a valid TCP port.");
+
+const bot = new Bot(token);
+bot.command("start", async (ctx) => { await ctx.reply("Webhook bot is active."); });
+
+const webhook = createWebhookHandler(bot, {
+  secretToken: webhookSecret,
+  onError: (error) => console.error("Webhook update failed", error),
+});
+
+const server = createServer(async (request, response) => {
+  try {
+    const body = await new Promise<Buffer>((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      request.on("data", (chunk: Buffer | string) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+      request.on("end", () => resolve(Buffer.concat(chunks)));
+      request.on("error", reject);
+    });
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(request.headers)) if (typeof value === "string") headers.set(key, value);
+    const requestInit: RequestInit = { method: request.method ?? "GET", headers };
+    if (request.method === "POST") requestInit.body = body.toString("utf8");
+    const result = await webhook(new Request(`http://${request.headers.host ?? "localhost"}${request.url ?? "/"}`, requestInit));
+    response.writeHead(result.status, Object.fromEntries(result.headers));
+    response.end(await result.text());
+  } catch (error) {
+    response.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+    response.end("Internal Server Error");
+    console.error("Webhook server failed", error);
+  }
+});
+
+server.listen(port, () => console.log(`Telebibz webhook listening on http://localhost:${port}`));

package/examples/wizard-registration.ts

@@ -0,0 +1,42 @@
+import { Bot, Wizard } from "@xbibzlibrary/telebibz";
+
+const token = process.env.TELEGRAM_BOT_TOKEN;
+if (!token) throw new Error("Set TELEGRAM_BOT_TOKEN before starting the example.");
+
+const bot = new Bot(token);
+const wizard = new Wizard();
+
+wizard
+  .step({
+    id: "name",
+    run: async (flow) => {
+      const name = flow.ctx.message?.text?.trim();
+      if (!name) {
+        await flow.ctx.reply("Please send your name as text.");
+        return;
+      }
+      flow.set("name", name).next();
+      await flow.ctx.reply("How old are you?");
+    },
+  })
+  .step({
+    id: "age",
+    run: async (flow) => {
+      const age = Number(flow.ctx.message?.text?.trim());
+      if (!Number.isInteger(age) || age < 1 || age > 120) {
+        await flow.ctx.reply("Please send a valid age between 1 and 120.");
+        return;
+      }
+      const name = flow.get<string>("name") ?? "there";
+      flow.set("age", age).next();
+      await flow.ctx.reply(`Thanks, ${name}. Your registration is complete.`);
+    },
+  });
+
+bot.useWizard(wizard);
+bot.command("register", async (ctx) => {
+  await wizard.run(ctx);
+  await ctx.reply("What is your name?");
+});
+
+await bot.start();

package/package.json

@@ -1,7 +1,21 @@
 {
   "name": "@xbibzlibrary/telebibz",
-  "version": "0.1.18",
-  "description": "Production-grade, strongly typed Telegram Bot API SDK and framework for Node.js and TypeScript.",
+  "version": "0.2.1",
+  "description": "Telegram Bot framework for Node.js and TypeScript with a typed API client, routing, middleware, webhooks, keyboards, conversations, plugins, queues, and a polished terminal experience.",
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "telegram-bot-api",
+    "telegram-bot-framework",
+    "nodejs",
+    "typescript",
+    "telegram-webhook",
+    "long-polling",
+    "conversation-wizard",
+    "inline-keyboard",
+    "telegram-mini-app",
+    "bot-framework"
+  ],
   "type": "module",
   "private": false,
   "publishConfig": {
@@ -18,7 +32,7 @@
     "url": "https://github.com/XbibzOfficial777/telebibz/issues"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "generate": "node scripts/generate-api.mjs",
@@ -31,6 +45,7 @@
     "test:integration": "vitest run tests/integration/**/*.test.ts",
     "test:e2e": "vitest run tests/e2e",
     "test:types": "tsc -p tests/tsconfig.json --noEmit",
+    "test:examples": "tsc -p examples/tsconfig.json --noEmit",
     "benchmark": "tsx tests/benchmark.ts",
     "package:check": "npm run build && npm pack --dry-run",
     "security": "npm audit --audit-level=high --package-lock-only",
@@ -39,7 +54,7 @@
     "start": "tsx src/cli.ts start",
     "dev": "tsx examples/minimal.ts",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run typecheck && npm run test:types && npm run lint && npm test && npm run build && npm run security && npm run release:check"
+    "prepublishOnly": "npm run typecheck && npm run test:types && npm run test:examples && npm run lint && npm test && npm run build && npm run security && npm run release:check"
   },
   "bin": {
     "telebibz": "./bin/telebibz.mjs"
@@ -84,8 +99,10 @@
     "NOTICE.md",
     "RELEASE_POLICY.md",
     "RELEASE_AUTOMATION.md",
+    "SHOWCASE.md",
     "assets",
-    "docs"
+    "docs",
+    "examples"
   ],
   "devDependencies": {
     "@types/node": "^22.10.0",