@xbibzlibrary/telebibz 0.1.11 → 0.1.13

package/dist-cjs/src/queue/queue.js

@@ -42,10 +42,17 @@ class TaskQueue {
         return false; job.status = "cancelled"; this.controllers.get(id)?.abort(); return true; }
     async onIdle() { while (this.pending.some((job) => job.status === "queued") || this.active)
         await sleep(10); }
-    async close() { this.closed = true; this.draining = false; for (const id of this.controllers.keys())
-        this.cancel(id); for (const job of this.pending)
-        if (job.status === "queued")
-            job.status = "cancelled"; this.pending.length = 0; }
+    async close() {
+        this.closed = true;
+        this.draining = false;
+        for (const id of this.controllers.keys())
+            this.cancel(id);
+        for (const job of this.pending)
+            if (job.status === "queued")
+                job.status = "cancelled";
+        this.pending.length = 0;
+        await this.onIdle();
+    }
     async drain() {
         if (this.draining || this.closed)
             return;

package/dist-cjs/src/state/conversation.js

@@ -31,7 +31,13 @@ class ConversationManager {
     start(key, name, values = {}) {
         const state = { name, step: 0, values, status: "active", updatedAt: Date.now() };
         this.active.set(key, state);
-        void this.storage.set(key, state);
+        void this.storage.set(key, state).catch(() => undefined);
+        return state;
+    }
+    async startAsync(key, name, values = {}) {
+        const state = { name, step: 0, values, status: "active", updatedAt: Date.now() };
+        this.active.set(key, state);
+        await this.storage.set(key, state);
         return state;
     }
     get(key) { return this.active.get(key); }
@@ -50,7 +56,7 @@ class ConversationManager {
             return false;
         state.status = "cancelled";
         state.updatedAt = Date.now();
-        void this.storage.set(key, state);
+        void this.storage.set(key, state).catch(() => undefined);
         return true;
     }
     async cancelAsync(key) {
@@ -90,9 +96,12 @@ class ConversationManager {
         return removed;
     }
     async run(ctx, key, name, steps) {
-        const state = (await this.getAsync(key)) ?? this.start(key, name);
+        const existing = await this.getAsync(key);
+        const state = existing ?? await this.startAsync(key, name);
         if (state.name !== name)
             throw new Error(`Conversation ${key} belongs to ${state.name}, not ${name}`);
+        if (state.status !== "active")
+            return state;
         const flow = new ConversationFlow(ctx, state);
         const step = steps[state.step];
         if (!step)

package/dist-cjs/src/storage/storage.js

@@ -115,7 +115,7 @@ class RedisStorage {
     key(key) { return `${this.prefix}${key}`; }
     unkey(key) { return key.slice(this.prefix.length); }
     async get(key) { const value = await this.client.get(this.key(key)); return value === null ? undefined : JSON.parse(value); }
-    async set(key, value, options = {}) { const ttl = options.ttlMs; const redisOptions = ttl === undefined ? {} : ttl >= 1000 ? { PX: Math.max(1, Math.floor(ttl)) } : { PX: Math.max(1, Math.floor(ttl)) }; await this.client.set(this.key(key), JSON.stringify(value), redisOptions); }
+    async set(key, value, options = {}) { const ttl = options.ttlMs; const redisOptions = ttl === undefined ? {} : { PX: Math.max(1, Math.floor(ttl)) }; await this.client.set(this.key(key), JSON.stringify(value), redisOptions); }
     async delete(key) { return (await this.client.del(this.key(key))) > 0; }
     async has(key) { return (await this.client.exists(this.key(key))) > 0; }
     async clear() { const keys = await this.client.keys(`${this.prefix}*`); if (keys.length)

package/dist-cjs/src/telegram-features.js

@@ -48,6 +48,8 @@ function validateWebAppInitData(initData, botToken, maxAgeSeconds = 86_400, nowM
     if (!Number.isFinite(maxAgeSeconds) || maxAgeSeconds < 0)
         throw new RangeError("maxAgeSeconds must be non-negative");
     const parsed = parseWebAppInitData(initData);
+    if (!/^[0-9a-fA-F]{64}$/.test(parsed.hash))
+        throw new Error("Web App init data hash must be a 64-character hexadecimal string");
     const checkString = Object.entries(parsed.data).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}=${value}`).join("\n");
     const secret = (0, node_crypto_1.createHmac)("sha256", "WebAppData").update(botToken).digest();
     const expected = (0, node_crypto_1.createHmac)("sha256", secret).update(checkString).digest("hex");

package/dist-cjs/src/webhook/handler.js

@@ -1,13 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWebhookHandler = createWebhookHandler;
+const node_crypto_1 = require("node:crypto");
 function createWebhookHandler(bot, options = {}) {
     const maxBodyBytes = options.maxBodyBytes ?? 1_048_576;
     return async (request) => {
         if (request.method !== "POST")
             return new Response("Method Not Allowed", { status: 405, headers: { allow: "POST" } });
-        if (options.secretToken && request.headers.get("x-telegram-bot-api-secret-token") !== options.secretToken)
+        if (options.secretToken && !secureEqual(request.headers.get("x-telegram-bot-api-secret-token") ?? "", options.secretToken))
             return new Response("Unauthorized", { status: 401 });
+        const contentType = request.headers.get("content-type") ?? "";
+        if (!/^application\/json(?:\s*;|\s*$)/i.test(contentType))
+            return new Response("Unsupported Media Type", { status: 415 });
         const contentLength = Number(request.headers.get("content-length") ?? 0);
         if (contentLength > maxBodyBytes)
             return new Response("Payload Too Large", { status: 413 });
@@ -27,3 +31,8 @@ function createWebhookHandler(bot, options = {}) {
         }
     };
 }
+function secureEqual(left, right) {
+    const leftBuffer = Buffer.from(left, "utf8");
+    const rightBuffer = Buffer.from(right, "utf8");
+    return leftBuffer.length === rightBuffer.length && (0, node_crypto_1.timingSafeEqual)(leftBuffer, rightBuffer);
+}

package/docs/API.id.md

@@ -4,7 +4,7 @@
 
 ![telebibz overview](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@latest/assets/telebibz-readme-preview.png)
 
-Dokumen ini adalah referensi API untuk `@xbibzlibrary/telebibz@0.1.4`. Seluruh signature dan perilaku yang dijelaskan di sini dipetakan dari source TypeScript yang diekspor package. Jika suatu tipe Telegram belum memiliki pemetaan parameter/result khusus, package tetap menyediakan akses runtime melalui API dinamis, tetapi tipe parameternya masih generik.
+Dokumen ini adalah referensi API untuk rilis `@xbibzlibrary/telebibz` yang sedang dipublikasikan. Seluruh signature dan perilaku yang dijelaskan di sini dipetakan dari source TypeScript yang diekspor package. Jika suatu tipe Telegram belum memiliki pemetaan parameter/result khusus, package tetap menyediakan akses runtime melalui API dinamis, tetapi tipe parameternya masih generik.
 
 > **Status implementasi.** Dokumentasi ini menjelaskan kemampuan yang tersedia pada rilis saat ini. `JsonFileStorage`, storage Redis/SQL/Mongo berbasis driver, session/conversation berbasis Storage, cron lima field lengkap, `MenuController`, terminal status output branded, structured logging dengan redaction, validasi Web App, `PaymentsClient`, dan declaration `TelegramTypes` sudah tersedia. Core method map tetap khusus untuk inferensi request/result tertentu, sedangkan `api.raw()` tersedia untuk method Telegram berikutnya.
 
@@ -1239,8 +1239,8 @@ interface MenuItem {
   label: string;
   callbackData?: string;
   url?: string;
-  visible?: boolean | (() => boolean | Promise<boolean>);
-  permission?: string;
+  visible?: boolean | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
+  permission?: string | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
 }
 ```
 

package/docs/API.md

@@ -3,7 +3,7 @@
 
 ![telebibz overview](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@latest/assets/telebibz-readme-preview.png)
 
-This document is the API reference for `@xbibzlibrary/telebibz@0.1.4`. All signatures and behaviors described here are mapped from the package's exported TypeScript source. If a Telegram type does not have a specific parameter/result mapping, the package still provides runtime access via a dynamic API, but the parameter types remain generic.
+This document is the API reference for the current published `@xbibzlibrary/telebibz` release. All signatures and behaviors described here are mapped from the package's exported TypeScript source. If a Telegram type does not have a specific parameter/result mapping, the package still provides runtime access via a dynamic API, but the parameter types remain generic.
 
 > **Implementation status.** This documentation describes the capabilities available in the current release. `JsonFileStorage`, driver-based Redis/SQL/Mongo storage, storage-backed sessions/conversations, full five-field cron, `MenuController`, terminal branding, structured redacted logging, Web App validation, PaymentsClient, and vendored `TelegramTypes` declarations are included. The core method map remains specialized for selected request/result inference, while `api.raw()` remains available for future Telegram methods.
 
@@ -1001,7 +1001,7 @@ interface PluginApi<Context> {
 }
 ```
 
-In this release, `registerMiddleware` and `registerRoute` are available as API hooks but the implementation manager does not yet connect them automatically to the bot/router. Plugins may use `api.bot` and `api.services` directly.
+In this release, `registerMiddleware` connects plugin middleware to `bot.use()`, and `registerRoute` connects plugin routes to `bot.router.route()`. The bot lifecycle invokes plugin `onUpdate` and `onStop` hooks automatically.
 
 ### `ServiceContainer`
 
@@ -1032,7 +1032,7 @@ new PluginManager<Context>(bot: unknown): PluginManager<Context>
 | `dispose()` | Executes `dispose` in reverse registration order. |
 | `list()` | Returns a read-only list of plugins. |
 
-`Bot.handleUpdate()` in this release does not call `plugins.update()` automatically; call the manager explicitly if plugins require an update lifecycle.
+`Bot.handleUpdate()` calls `plugins.update()` automatically after the update is processed, and `Bot.stop()` invokes plugin stop hooks before disposal.
 
 ---
 
@@ -1257,8 +1257,8 @@ interface MenuItem {
   label: string;
   callbackData?: string;
   url?: string;
-  visible?: boolean | (() => boolean | Promise<boolean>);
-  permission?: string;
+  visible?: boolean | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
+  permission?: string | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
 }
 ```
 

package/docs/API.zh-CN.md

@@ -4,7 +4,7 @@
 
 ![telebibz 概览](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@latest/assets/telebibz-readme-preview.png)
 
-本文件是 `@xbibzlibrary/telebibz@0.1.4` 的 API 参考。此处描述的所有签名和行为均映射自该包导出的 TypeScript 源代码。如果某个 Telegram 类型尚未有特定的参数/结果映射，该包仍通过动态 API 提供运行时访问，但其参数类型仍为通用类型。
+本文件是当前发布的 `@xbibzlibrary/telebibz` API 参考。此处描述的所有签名和行为均映射自该包导出的 TypeScript 源代码。如果某个 Telegram 类型尚未有特定的参数/结果映射，该包仍通过动态 API 提供运行时访问，但其参数类型仍为通用类型。
 
 > **实现状态。** 本文档说明当前版本中可用的功能。`JsonFileStorage`、基于 driver 的 Redis/SQL/Mongo storage、基于 Storage 的 session/conversation、完整五字段 cron、`MenuController`、带 branding 的 terminal status output、带 redaction 的 structured logging、Web App 验证、`PaymentsClient` 和 `TelegramTypes` declaration 均已提供。core method map 仍主要为特定 request/result inference 提供类型，未来 Telegram method 可通过 `api.raw()` 访问。
 
@@ -1233,8 +1233,8 @@ interface MenuItem {
   label: string;
   callbackData?: string;
   url?: string;
-  visible?: boolean | (() => boolean | Promise<boolean>);
-  permission?: string;
+  visible?: boolean | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
+  permission?: string | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
 }
 ```
 

package/docs/GITHUB_PACKAGES.id.md

@@ -0,0 +1,82 @@
+# GitHub Packages
+
+`@xbibzlibrary/telebibz` dirilis ke [npmjs](https://www.npmjs.com/package/@xbibzlibrary/telebibz) dan registry npm GitHub Packages. Repository GitHub resminya adalah [XbibzOfficial777/telebibz](https://github.com/XbibzOfficial777/telebibz).
+
+## Registry
+
+URL registry GitHub Packages:
+
+```text
+https://npm.pkg.github.com
+```
+
+Mapping scope npm:
+
+```ini
+@xbibzlibrary:registry=https://npm.pkg.github.com
+```
+
+Workflow release mempublikasikan tarball yang sama ke npmjs dan GitHub Packages setelah typecheck, test, build, security audit, dan release check berhasil. Workflow menggunakan `GITHUB_TOKEN` dengan permission `packages: write`; personal access token GitHub tidak disimpan di repository atau workflow.
+
+## Instalasi package
+
+Untuk package public, tambahkan mapping berikut pada `.npmrc` project yang memakai package:
+
+```ini
+@xbibzlibrary:registry=https://npm.pkg.github.com
+```
+
+Jika package atau repository bersifat private, gunakan **personal access token (classic)** dengan minimal akses `read:packages`. Simpan token di luar repository, sebaiknya melalui environment variable reference pada konfigurasi npm user:
+
+```ini
+@xbibzlibrary:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
+```
+
+Kemudian jalankan:
+
+```bash
+export GITHUB_PACKAGES_TOKEN="<token-read-packages-kamu>"
+npm install @xbibzlibrary/telebibz
+```
+
+Jangan mengganti placeholder dengan token asli di file yang di-commit. Jangan commit `.npmrc` yang berisi kredensial literal, dan jangan memasukkan token ke issue, pull request, log, atau chat.
+
+## Publikasi lokal
+
+Cara yang direkomendasikan adalah workflow GitHub Actions yang telah dilindungi. Workflow memeriksa versi dan hanya publish setelah seluruh release gate berhasil. Publikasi lokal hanya untuk maintainer yang memiliki personal access token (classic) dengan `write:packages` serta permission repository:
+
+```bash
+export GITHUB_PACKAGES_TOKEN="<token-write-packages-kamu>"
+printf '@xbibzlibrary:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\n' > "$HOME/.npmrc"
+npm run build
+npm pack
+npm publish ./xbibzlibrary-telebibz-<version>.tgz --registry=https://npm.pkg.github.com --access public
+```
+
+Gunakan semantic version baru untuk setiap publikasi. Versi registry bersifat immutable dan tidak boleh ditimpa.
+
+## Permission GitHub Actions
+
+Workflow release menggunakan permission minimum berikut:
+
+```yaml
+permissions:
+  contents: write
+  packages: write
+```
+
+`NPM_TOKEN` tetap menjadi environment secret untuk publikasi ke npmjs. GitHub Packages menggunakan `GITHUB_TOKEN` otomatis, sehingga tidak memerlukan secret GitHub tambahan untuk package milik repository ini. Jika kebijakan organisasi menonaktifkan pewarisan akses package, hubungkan package ke repository dan berikan akses workflow melalui pengaturan package.
+
+## Troubleshooting
+
+Respons `401 Unauthorized` biasanya berarti token tidak ada, sudah kedaluwarsa, atau tidak mempunyai scope package yang benar. Respons `403 Forbidden` biasanya berarti akun atau workflow tidak memiliki permission package, atau kebijakan organisasi memblokir publikasi. Respons `404 Not Found` dapat muncul ketika package private diakses tanpa autentikasi atau scope belum diarahkan ke `https://npm.pkg.github.com`.
+
+Untuk instalasi dari npmjs, hapus mapping GitHub scope atau gunakan registry npm default. Kedua registry berisi nama package dan versi yang sama, tetapi autentikasi dan access control dikelola secara terpisah.
+
+## Referensi
+
+1. [Working with the npm registry — GitHub Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
+2. [About permissions for GitHub Packages — GitHub Docs](https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages)
+3. [Publishing and installing a package with GitHub Actions — GitHub Docs](https://docs.github.com/en/packages/quickstart)
+4. [npm package.json publishConfig — npm Docs](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#publishconfig)

package/docs/GITHUB_PACKAGES.md

@@ -0,0 +1,82 @@
+# GitHub Packages
+
+`@xbibzlibrary/telebibz` is released to both [npmjs](https://www.npmjs.com/package/@xbibzlibrary/telebibz) and the GitHub Packages npm registry. The canonical GitHub repository is [XbibzOfficial777/telebibz](https://github.com/XbibzOfficial777/telebibz).
+
+## Registry
+
+GitHub Packages uses the following npm registry URL:
+
+```text
+https://npm.pkg.github.com
+```
+
+The package scope is mapped to GitHub Packages with:
+
+```ini
+@xbibzlibrary:registry=https://npm.pkg.github.com
+```
+
+The release workflow publishes the same verified tarball to npmjs and GitHub Packages after the type checks, tests, build, security audit, and release checks pass. The workflow uses `GITHUB_TOKEN` with `packages: write`; no GitHub personal access token is stored in the repository or workflow file.
+
+## Installing the package
+
+For a public package, use a GitHub Packages-aware `.npmrc` in the consuming project:
+
+```ini
+@xbibzlibrary:registry=https://npm.pkg.github.com
+```
+
+If the package or repository is private, authenticate with a **personal access token (classic)** that has at least `read:packages` access. Store the token outside the repository, preferably in the user-level npm configuration or an environment-variable reference:
+
+```ini
+@xbibzlibrary:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
+```
+
+Then install the package:
+
+```bash
+export GITHUB_PACKAGES_TOKEN="<your-read-packages-token>"
+npm install @xbibzlibrary/telebibz
+```
+
+Do not replace the placeholder with a real token in a committed file. Do not commit `.npmrc` files containing literal credentials, and do not paste tokens into issues, pull requests, logs, or chat.
+
+## Publishing locally
+
+The recommended publishing path is the protected GitHub Actions workflow. It verifies the version and publishes only after all release gates succeed. Local publishing is intended for maintainers who have a classic personal access token with `write:packages` and repository permission to publish packages:
+
+```bash
+export GITHUB_PACKAGES_TOKEN="<your-write-packages-token>"
+printf '@xbibzlibrary:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\n' > "$HOME/.npmrc"
+npm run build
+npm pack
+npm publish ./xbibzlibrary-telebibz-<version>.tgz --registry=https://npm.pkg.github.com --access public
+```
+
+Use a new semantic version for every publication. Registry versions are immutable; an existing version must never be overwritten.
+
+## GitHub Actions permissions
+
+The release workflow declares the minimum package permission required for publication:
+
+```yaml
+permissions:
+  contents: write
+  packages: write
+```
+
+`NPM_TOKEN` remains an environment secret for npmjs publication. GitHub Packages uses the automatically provided `GITHUB_TOKEN`, so no additional GitHub token secret is required for the repository's own package. If organization policy disables automatic package access inheritance, connect the package to the repository and grant the workflow access under the package's settings.
+
+## Troubleshooting
+
+A `401 Unauthorized` response normally means the token is missing, expired, or lacks the required package scope. A `403 Forbidden` response usually means the account or workflow does not have permission to the package, or that organization policy blocks publication. A `404 Not Found` response can occur when a private package is queried without authentication or when the scope is not mapped to `https://npm.pkg.github.com`.
+
+For npmjs installation, omit the GitHub scope mapping or use the default npm registry. Both registries contain the same package name and release version, but authentication and access control are handled independently.
+
+## References
+
+1. [Working with the npm registry — GitHub Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
+2. [About permissions for GitHub Packages — GitHub Docs](https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages)
+3. [Publishing and installing a package with GitHub Actions — GitHub Docs](https://docs.github.com/en/packages/quickstart)
+4. [npm package.json publishConfig — npm Docs](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#publishconfig)

package/docs/GITHUB_PACKAGES.zh-CN.md

@@ -0,0 +1,82 @@
+# GitHub Packages
+
+`@xbibzlibrary/telebibz` 同时发布到 [npmjs](https://www.npmjs.com/package/@xbibzlibrary/telebibz) 和 GitHub Packages npm registry。官方 GitHub 仓库是 [XbibzOfficial777/telebibz](https://github.com/XbibzOfficial777/telebibz)。
+
+## Registry
+
+GitHub Packages 使用以下 npm registry 地址：
+
+```text
+https://npm.pkg.github.com
+```
+
+npm scope 映射如下：
+
+```ini
+@xbibzlibrary:registry=https://npm.pkg.github.com
+```
+
+release workflow 会在 typecheck、测试、构建、安全审计和 release check 全部通过后，将同一个经过验证的 tarball 发布到 npmjs 和 GitHub Packages。workflow 使用具有 `packages: write` 权限的 `GITHUB_TOKEN`，不会把 GitHub personal access token 存储在仓库或 workflow 文件中。
+
+## 安装 package
+
+对于 public package，可以在使用方项目的 `.npmrc` 中加入：
+
+```ini
+@xbibzlibrary:registry=https://npm.pkg.github.com
+```
+
+如果 package 或 repository 是 private，请使用具有至少 `read:packages` 权限的 **personal access token (classic)**。请将 token 保存在仓库之外，建议使用 npm 用户配置中的环境变量引用：
+
+```ini
+@xbibzlibrary:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
+```
+
+然后执行：
+
+```bash
+export GITHUB_PACKAGES_TOKEN="<your-read-packages-token>"
+npm install @xbibzlibrary/telebibz
+```
+
+不要把真实 token 写入已经提交的文件。不要提交包含明文凭据的 `.npmrc`，也不要在 issue、pull request、日志或聊天中粘贴 token。
+
+## 本地发布
+
+推荐使用受保护的 GitHub Actions workflow 发布。workflow 会检查版本，并且只有所有 release gate 成功后才会发布。本地发布仅适用于拥有 `write:packages` classic token 以及 repository 发布权限的 maintainer：
+
+```bash
+export GITHUB_PACKAGES_TOKEN="<your-write-packages-token>"
+printf '@xbibzlibrary:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\n' > "$HOME/.npmrc"
+npm run build
+npm pack
+npm publish ./xbibzlibrary-telebibz-<version>.tgz --registry=https://npm.pkg.github.com --access public
+```
+
+每次发布必须使用新的 semantic version。registry 中的版本是 immutable，不能覆盖已有版本。
+
+## GitHub Actions 权限
+
+release workflow 声明了发布所需的最小权限：
+
+```yaml
+permissions:
+  contents: write
+  packages: write
+```
+
+`NPM_TOKEN` 仍然作为 npmjs 发布所需的 environment secret。GitHub Packages 使用自动提供的 `GITHUB_TOKEN`，因此本仓库的 package 不需要额外的 GitHub token secret。如果组织策略关闭了 package 权限自动继承，请在 package 设置中连接 repository，并授予 workflow 访问权限。
+
+## 故障排查
+
+`401 Unauthorized` 通常表示 token 缺失、过期或没有正确的 package scope。`403 Forbidden` 通常表示账号或 workflow 没有 package 权限，或者组织策略禁止发布。访问 private package 时没有认证，或 scope 没有映射到 `https://npm.pkg.github.com`，也可能得到 `404 Not Found`。
+
+从 npmjs 安装时，请删除 GitHub scope mapping 或使用默认 npm registry。两个 registry 包含相同的 package 名称和版本，但认证和 access control 独立管理。
+
+## 参考资料
+
+1. [Working with the npm registry — GitHub Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
+2. [About permissions for GitHub Packages — GitHub Docs](https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages)
+3. [Publishing and installing a package with GitHub Actions — GitHub Docs](https://docs.github.com/en/packages/quickstart)
+4. [npm package.json publishConfig — npm Docs](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#publishconfig)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xbibzlibrary/telebibz",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Production-grade, strongly typed Telegram Bot API SDK and framework for Node.js and TypeScript.",
   "type": "module",
   "private": false,