telegram-inline-keyboard-builder 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neon Craft X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+### Inline Keyboard Builder
+
+Small inline button builder for Telegram, designed to be library-agnostic (Telegraf, node-telegram-bot-api, Aiogram, Pyrogram...).
+
+> Principle: a central logic core handles button creation and placement. Adapters transform the neutral structure into the format expected by the target API.
+
+
+
+
+---
+
+## 🚀 Key Features
+
+- Fluent, chainable API
+
+- Core independent of any Telegram library
+
+- Easy-to-write adapters (Telegraf, node-telegram-bot-api, Aiogram...)
+
+- Auto-wrap / control of buttons per row
+
+
+
+---
+
+##  Installation
+
+If the package is published on npm:
+
+```bash
+npm install telegram-inline-keyboard-builder
+```
+Then in your project:
+
+```js
+import { InlineKeyboardTelegraf } from "telegram-inline-keyboard-builder";
+```
+
+---
+
+## Quick Concepts
+
+- **Core**: InlineKeyboardBuilder (placement logic, chainable API). Does not know any Telegram library.
+
+- **Adapter**: object responsible for creating buttons (callback/url/pay/custom) and producing the final structure (reply_markup/Markup depending on the library).
+
+- **Facade Builder**: ready-to-use classes that inject an adapter (e.g., InlineKeyboardTelegraf, InlineKeyboardNodeTelegram).
+
+
+
+---
+
+## 🔧 Public Interface (API)
+
+### Constructors
+```js
+// Core (internal)
+
+new InlineKeyboardBuilder(adapter, buttonsPerRow = 2, autoWrapMaxChars = 0)
+
+// Facade (exposed to users, encapsulates core + adapter)
+new InlineKeyboardTelegraf({ buttonsPerRow = 2, autoWrapMaxChars = 0 })
+new InlineKeyboardNodeTelegram({ ... })
+
+Chainable Methods
+
+.addCallbackButton(text, callback_data, hide = false)
+.addUrlButton(text, url, hide = false)
+.addPayButton(text, options = {})
+.addCustomButton(btnObj)
+.addButtons(config) // array or { type, buttons: [...] }
+.setButtonsPerRow(n)
+.setAutoWrapMaxChars(n)
+.newRow() // forces a new row
+.build() // returns the keyboard formatted by the adapter
+```
+**Return of build()**: depends on the adapter.
+
+**Telegraf adapte** → Markup.inlineKeyboard(rows) (Markup object) 
+
+**Node‑Telegram adapt** → { reply_markup: { inline_keyboard: rows } }
+
+
+
+---
+
+## 🧩 Usage Example (Telegraf)
+
+```js
+import { Telegraf } from "telegraf";
+import { InlineKeyboardTelegraf } from "telegram-inline-keyboard-builder";
+
+const bot = new Telegraf(process.env.BOT_TOKEN);
+
+bot.start(ctx => {
+  const keyboard = new InlineKeyboardTelegraf({ buttonsPerRow: 2, autoWrapMaxChars: 24 })
+    .addCallbackButton("✅ OK", "OK_ACTION")
+    .addUrlButton("🌍 Site", "https://example.com")
+    .newRow()
+    .addCallbackButton("❌ Cancel", "CANCEL_ACTION")
+    .build();
+
+  ctx.reply("Welcome 👋\nChoose an action:", keyboard);
+});
+
+bot.launch();
+```
+
+## 🧾 Usage Example (node-telegram-bot-api)
+
+```js
+import TelegramBot from "node-telegram-bot-api";
+import { InlineKeyboardNodeTelegram } from "telegram-inline-keyboard-builder";
+
+const bot = new TelegramBot(TOKEN, { polling: true });
+
+bot.onText(/\/start/, (msg) => {
+  const kb = new InlineKeyboardNodeTelegram()
+    .addCallbackButton("OK", "OK")
+    .addUrlButton("Site", "https://example.com")
+    .build();
+
+  // kb === { reply_markup: { inline_keyboard: [...] } }
+  bot.sendMessage(msg.chat.id, "Hello", kb);
+});
+
+```
+---
+
+## 🛠️ Writing an Adapter (expected interface)
+
+A simple adapter must expose:
+
+```js
+// create a button
+adapter.createCallback(text, data, hide = false)
+adapter.createUrl(text, url, hide = false)
+adapter.createPay(text, hide = false)
+
+// build the final keyboard from rows (rows = array of array of buttons)
+adapter.buildKeyboard(rows)
+
+Minimal Example (node-telegram-bot-api)
+
+export class NodeTelegramInlineAdapter {
+  createCallback(text, data) {
+    return { text, callback_data: data };
+  }
+
+  createUrl(text, url) {
+    return { text, url };
+  }
+
+  createPay(text) {
+    return { text, pay: true };
+  }
+
+  buildKeyboard(rows) {
+    return { reply_markup: { inline_keyboard: rows } };
+  }
+}
+```
+
+---
+
+## 🧯 Common Errors & Debug
+
+**ReferenceError**: Markup is not defined → you are still using Markup in the core; move button creation into the adapter.
+
+**Missing adapter** → the core constructor must receive a valid adapter: new InlineKeyboardBuilder(adapter).
+
+**Library not installed** (e.g., telegraf missing) → adapter should detect and throw a clear error: npm install telegraf.
+
+
+---
+
+✍️ Contribution
+
+Everyone are welcome. Open an issue to discuss a feature before implementing major changes.
+
+
+---

package/adapters/node-telegram.adapter.js

@@ -0,0 +1,21 @@
+export class NodeTelegramInlineAdapter {
+	createCallback(text, data) {
+		return { text, callback_data: data };
+	}
+
+	createUrl(text, url) {
+		return { text, url };
+	}
+
+	createPay(text) {
+		return { text, pay: true };
+	}
+
+	buildKeyboard(rows) {
+		return {
+			reply_markup: {
+				inline_keyboard: rows
+			}
+		};
+	}
+}

package/adapters/telegraf.adapter.js

@@ -0,0 +1,19 @@
+import { Markup } from "telegraf";
+
+export class TelegrafInlineAdapter {
+	createCallback(text, data, hide = false) {
+		return Markup.button.callback(text, data, hide);
+	}
+
+	createUrl(text, url, hide = false) {
+		return Markup.button.url(text, url, hide);
+	}
+
+	createPay(text, hide = false) {
+		return Markup.button.pay(text, hide);
+	}
+
+	buildKeyboard(rows) {
+		return Markup.inlineKeyboard(rows);
+	}
+}

package/builders/InlineKeyboardNodeTelegram.js

@@ -0,0 +1,13 @@
+
+import { InlineKeyboardBuilder } from "../core/InlineKeyboardBuilder.js";
+import { NodeTelegramInlineAdapter } from "../adapters/node-telegram.adapter.js";
+
+export class InlineKeyboardNodeTelegram extends InlineKeyboardBuilder {
+	constructor(options = {}) {
+		super(
+			new NodeTelegramInlineAdapter(),
+			options.buttonsPerRow,
+			options.autoWrapMaxChars
+		);
+	}
+}

package/builders/InlineKeyboardTelegraf.js

@@ -0,0 +1,12 @@
+import { InlineKeyboardBuilder } from "../core/InlineKeyboardBuilder.js";
+import { TelegrafInlineAdapter } from "../adapters/telegraf.adapter.js";
+
+export class InlineKeyboardTelegraf extends InlineKeyboardBuilder {
+	constructor(options = {}) {
+		super(
+			new TelegrafInlineAdapter(),
+			options.buttonsPerRow,
+			options.autoWrapMaxChars
+		);
+	}
+}

package/core/InlineKeyboardBuilder.js

@@ -0,0 +1,89 @@
+export class InlineKeyboardBuilder {
+	constructor(adapter, buttonsPerRow = 2, autoWrapMaxChars = 0) {
+		if (!adapter) {
+			throw new Error("InlineKeyboardBuilder requires an adapter");
+		}
+		this.adapter = adapter;
+		this.buttonsPerRow = buttonsPerRow;
+		this.autoWrapMaxChars = autoWrapMaxChars;
+		this._buttons = [];
+	}
+
+	_pushButton(btn) {
+		this._buttons.push(btn);
+		return this;
+	}
+
+	addCallbackButton(text, callback_data, hide = false) {
+		return this._pushButton(
+			this.adapter.createCallback(text, callback_data, hide)
+		);
+	}
+
+	addUrlButton(text, url, hide = false) {
+		return this._pushButton(
+			this.adapter.createUrl(text, url, hide)
+		);
+	}
+
+	addPayButton(text, options = {}) {
+		const hide = options.hide ?? false;
+		return this._pushButton(
+			this.adapter.createPay(text, hide)
+		);
+	}
+
+	addCustomButton(btnObj) {
+		return this._pushButton(btnObj);
+	}
+
+	newRow() {
+		this._buttons.push({ __newRow: true });
+		return this;
+	}
+	_layoutButtons() {
+		const rows = [];
+		let row = [];
+		let rowChars = 0;
+
+		const pushRow = () => {
+			if (row.length > 0) {
+				rows.push(row);
+				row = [];
+				rowChars = 0;
+			}
+		};
+
+		for (const b of this._buttons) {
+			if (b && b.__newRow) {
+				pushRow();
+				continue;
+			}
+
+			const text = b?.text || "";
+			const len = String(text).length || 0;
+
+			if (
+				this.autoWrapMaxChars > 0 &&
+				row.length > 0 &&
+				rowChars + len > this.autoWrapMaxChars
+			) {
+				pushRow();
+			}
+
+			if (row.length >= this.buttonsPerRow) {
+				pushRow();
+			}
+
+			row.push(b);
+			rowChars += len;
+		}
+
+		pushRow();
+		return rows;
+	}
+
+	build() {
+		return this.adapter.buildKeyboard(this._layoutButtons());
+	}
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "telegram-inline-keyboard-builder",
+	"version": "1.0.0",
+	"description": "Universal inline keyboard builder for Telegram APIs",
+	"main": "builders/InlineKeyboardTelegraf.js",
+	"type": "module",
+	"keywords": [
+		"telegram",
+		"inline-keyboard",
+		"telegraf",
+		"aiogram",
+		"builder",
+		"python-telegram-bot",
+		"node-telegram-bot-api"
+	],
+	"author": "neoncraftx",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/neoncraftx/telegram-inline-keyboard-builder.git"
+	},
+	"bugs": {
+		"url": "https://github.com/neoncraftx/telegram-inline-keyboard-builder.git/issues"
+	},
+	"homepage": "https://github.com/neoncraftx/telegram-inline-keyboard-builder.git#readme",
+	"peerDependencies": {
+		"telegraf": "^4.0.0"
+	},
+	"dependencies": {
+		"telegram-inline-keyboard-builder": "file:telegram-inline-keyboard-builder-1.0.0.tgz"
+	}
+}