telegix 1.1.3-a1 → 1.1.4

package/index.d.ts

@@ -442,6 +442,15 @@ export class Telegix extends Composer {
   stop(reason?: string): Promise<void>;
   launch(options?: { polling?: boolean | object; webhook?: object; dropPendingUpdates?: boolean }): Promise<User>;
   webhookCallback(path?: string, options?: object): (req: any, res: any, next?: Function) => Promise<void>;
+  pagesWebhookHandler(options?: {
+    secretToken?: string | ((env: any) => string);
+    path?: string;
+    waitUntil?: boolean;
+    respondOnError?: number;
+    enableHealthCheck?: boolean;
+    onUpdate?: (update: any, context: any) => Promise<void> | void;
+    onError?: (err: Error, context: any) => any;
+  }): (context: any, env?: any, ctx?: any) => Promise<Response>;
 }
 
 export class MemorySessionStore {
@@ -656,4 +665,39 @@ export class TelegramError extends TelegixError {
 export class NetworkError extends TelegixError {}
 export class PollingError extends TelegixError {}
 
+export function createWebhookCallback(
+  bot: Telegix,
+  path?: string,
+  options?: { secretToken?: string }
+): (req: any, res: any, next?: Function) => Promise<void>;
+
+export function createPagesWebhookHandler(
+  botOrFactory?: Telegix | ((env: any, context?: any) => Telegix),
+  options?: {
+    secretToken?: string | ((env: any) => string);
+    path?: string;
+    waitUntil?: boolean;
+    respondOnError?: number;
+    enableHealthCheck?: boolean;
+    onUpdate?: (update: any, context: any) => Promise<void> | void;
+    onError?: (err: Error, context: any) => any;
+  }
+): (context: any, env?: any, ctx?: any) => Promise<Response>;
+
+export function createCloudflareWebhookCallback(
+  botOrFactory?: Telegix | ((env: any, context?: any) => Telegix),
+  options?: object
+): (context: any, env?: any, ctx?: any) => Promise<Response>;
+
+export function handleCloudflareWebhook(
+  context: any,
+  bot: Telegix,
+  options?: object
+): Promise<Response>;
+
+export function createPagesSetWebhookHandler(
+  botOrFactory?: Telegix | ((env: any) => Telegix),
+  options?: { webhookPath?: string; secretToken?: string }
+): (context: any) => Promise<Response>;
+
 export default Telegix;

package/index.js

@@ -11,7 +11,13 @@ export { Composer, compose } from './lib/composer.js';
 export { Markup, KeyboardBuilder } from './lib/markup.js';
 export { session, MemorySessionStore, FileSessionStore } from './lib/session.js';
 export { Polling } from './lib/polling.js';
-export { createWebhookCallback } from './lib/webhook.js';
+export {
+  createWebhookCallback,
+  createPagesWebhookHandler,
+  createCloudflareWebhookCallback,
+  handleCloudflareWebhook,
+  createPagesSetWebhookHandler,
+} from './lib/webhook.js';
 export { fmt, Format, escapeHtml, escapeMarkdown, html, markdown } from './lib/format.js';
 export { Table, InputRichBlockTable, RichBlockTable } from './lib/table.js';
 export { EphemeralMessageParameters, ReplyParameters, BotCommand } from './lib/ephemeral.js';

package/lib/api.js

@@ -30,7 +30,13 @@ export function isUploadableFile(value, key = '') {
   ) {
     return false;
   }
-  if (value instanceof Blob || value instanceof Uint8Array || Buffer.isBuffer(value)) return true;
+  if (
+    value instanceof Blob ||
+    value instanceof Uint8Array ||
+    (typeof Buffer !== 'undefined' && typeof Buffer.isBuffer === 'function' && Buffer.isBuffer(value))
+  ) {
+    return true;
+  }
   if (typeof value === 'object') {
     // If it's a LinkPreview or has link preview options properties, it's not a file
     if (
@@ -57,20 +63,24 @@ export function isUploadableFile(value, key = '') {
  */
 export async function normalizeFileSource(input, defaultFilename = 'file') {
   if (typeof input === 'string') {
-    // If it's a file path on local filesystem
-    if (fs.existsSync(input)) {
-      const buffer = await fs.promises.readFile(input);
-      const filename = path.basename(input) || defaultFilename;
-      return {
-        blob: new Blob([buffer]),
-        filename,
-      };
+    // If it's a file path on local filesystem (Node.js environment)
+    try {
+      if (fs && typeof fs.existsSync === 'function' && fs.existsSync(input)) {
+        const buffer = await fs.promises.readFile(input);
+        const filename = (path && typeof path.basename === 'function' && path.basename(input)) || defaultFilename;
+        return {
+          blob: new Blob([buffer]),
+          filename,
+        };
+      }
+    } catch {
+      // Ignored in non-filesystem/edge environments
     }
     // Otherwise it's a file_id or URL string
     return { blob: input };
   }
 
-  if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
+  if ((typeof Buffer !== 'undefined' && typeof Buffer.isBuffer === 'function' && Buffer.isBuffer(input)) || input instanceof Uint8Array) {
     return {
       blob: new Blob([input]),
       filename: defaultFilename,
@@ -93,16 +103,20 @@ export async function normalizeFileSource(input, defaultFilename = 'file') {
 
     if (input.source) {
       if (typeof input.source === 'string') {
-        if (fs.existsSync(input.source)) {
-          const buffer = await fs.promises.readFile(input.source);
-          return {
-            blob: new Blob([buffer]),
-            filename: input.filename || path.basename(input.source) || defaultFilename,
-          };
+        try {
+          if (fs && typeof fs.existsSync === 'function' && fs.existsSync(input.source)) {
+            const buffer = await fs.promises.readFile(input.source);
+            return {
+              blob: new Blob([buffer]),
+              filename: input.filename || (path && typeof path.basename === 'function' && path.basename(input.source)) || defaultFilename,
+            };
+          }
+        } catch {
+          // Ignored
         }
         return { blob: input.source };
       }
-      if (Buffer.isBuffer(input.source) || input.source instanceof Uint8Array) {
+      if ((typeof Buffer !== 'undefined' && typeof Buffer.isBuffer === 'function' && Buffer.isBuffer(input.source)) || input.source instanceof Uint8Array) {
         return {
           blob: new Blob([input.source]),
           filename,
@@ -1954,7 +1968,9 @@ export class Telegram {
   sendCardTables(chatId, tables, options = {}) {
     if (options.asImage || options.photo || options.image) {
       const svg = Table.multiCardSvg(tables, options);
-      const buffer = Buffer.from(svg, 'utf-8');
+      const buffer = typeof Buffer !== 'undefined' && typeof Buffer.from === 'function'
+        ? Buffer.from(svg, 'utf-8')
+        : new Blob([svg], { type: 'image/svg+xml' });
       return this.sendPhoto(chatId, {
         source: buffer,
         filename: 'tables-cards.svg',

package/lib/context.js

@@ -1019,7 +1019,7 @@ export class Context {
         rows = [
           ['Engine', data.engine || 'Telegix'],
           ['Runtime', data.runtime || '0h 19m 32s'],
-          ['Node', data.node || process.version || 'v23.11'],
+          ['Node', data.node || (typeof process !== 'undefined' && process.version ? process.version : 'Cloudflare Edge') || 'v23.11'],
           ['Features', data.features ?? 514],
           ['Groups', data.groups ?? 168],
           ['Users', data.users ?? 9528],

package/lib/telegix.js

@@ -7,7 +7,7 @@ import { Composer } from './composer.js';
 import { Telegram } from './api.js';
 import { Context } from './context.js';
 import { Polling } from './polling.js';
-import { createWebhookCallback } from './webhook.js';
+import { createWebhookCallback, createPagesWebhookHandler } from './webhook.js';
 import { TelegixError } from './errors.js';
 
 export class Telegix extends Composer {
@@ -173,4 +173,13 @@ export class Telegix extends Composer {
   webhookCallback(path = '/', options = {}) {
     return createWebhookCallback(this, path, options);
   }
+
+  /**
+   * Returns a Cloudflare Pages Functions / Cloudflare Workers / Fetch API webhook handler
+   * @param {object} [options]
+   * @returns {Function}
+   */
+  pagesWebhookHandler(options = {}) {
+    return createPagesWebhookHandler(this, options);
+  }
 }

package/lib/webhook.js

@@ -1,5 +1,7 @@
 /**
  * Telegix - Webhook Handler & Adapter
+ * Supports standard Node.js HTTP servers (Express, Fastify, Connect)
+ * AND Cloudflare Pages Functions, Cloudflare Workers, and Web Fetch API.
  * @module telegix/webhook
  */
 
@@ -55,7 +57,9 @@ export function createWebhookCallback(bot, path = '/', options = {}) {
         for await (const chunk of req) {
           chunks.push(chunk);
         }
-        const rawBody = Buffer.concat(chunks).toString('utf8');
+        const rawBody = (typeof Buffer !== 'undefined' && Buffer.concat)
+          ? Buffer.concat(chunks).toString('utf8')
+          : chunks.map((c) => (typeof c === 'string' ? c : new TextDecoder().decode(c))).join('');
         update = JSON.parse(rawBody);
       }
 
@@ -84,3 +88,403 @@ export function createWebhookCallback(bot, path = '/', options = {}) {
     }
   };
 }
+
+/**
+ * Creates a Cloudflare Pages Functions / Cloudflare Workers / Web Fetch API webhook handler.
+ * Compatible with:
+ *  - Cloudflare Pages Functions: `export const onRequest = createPagesWebhookHandler(bot, options);`
+ *  - Cloudflare Pages POST only: `export const onRequestPost = createPagesWebhookHandler(bot, options);`
+ *  - Cloudflare Workers: `export default { fetch: createPagesWebhookHandler(bot, options) };`
+ *
+ * @param {import('./telegix.js').Telegix | ((env: any, context: any) => import('./telegix.js').Telegix)} [botOrFactory]
+ * @param {object} [options]
+ * @param {string|((env: any) => string)} [options.secretToken] - Secret token for header verification or getter function
+ * @param {string} [options.path] - Optional path restriction (e.g. '/webhook')
+ * @param {boolean} [options.waitUntil=true] - Use context.waitUntil() to respond 200 OK instantly and process in background
+ * @param {number} [options.respondOnError=200] - Status to respond with on unhandled update error (default 200 prevents Telegram retry storm)
+ * @param {boolean} [options.enableHealthCheck=true] - If true, GET requests return a JSON health check status
+ * @param {Function} [options.onUpdate] - Optional callback when update is received
+ * @param {Function} [options.onError] - Custom error handler
+ * @returns {Function} Universal Cloudflare Pages / Workers handler
+ */
+export function createPagesWebhookHandler(botOrFactory, options = {}) {
+  const opts = {
+    waitUntil: true,
+    respondOnError: 200,
+    enableHealthCheck: true,
+    ...options,
+  };
+
+  // Cache for bot instance when initialized via factory
+  let cachedBot = typeof botOrFactory === 'object' && botOrFactory !== null ? botOrFactory : null;
+
+  return async function handlePagesRequest(arg1, arg2, arg3) {
+    let request;
+    let env = {};
+    let waitUntil = null;
+
+    // Detect Cloudflare Pages context vs Cloudflare Workers vs standard Fetch
+    if (arg1 && typeof arg1 === 'object' && 'request' in arg1) {
+      // Cloudflare Pages: context = { request, env, waitUntil, next, params, data }
+      request = arg1.request;
+      env = arg1.env || {};
+      if (typeof arg1.waitUntil === 'function') {
+        waitUntil = arg1.waitUntil.bind(arg1);
+      }
+    } else {
+      // Cloudflare Workers: (request, env, ctx) or Fetch: (request)
+      request = arg1;
+      env = arg2 || {};
+      if (arg3 && typeof arg3.waitUntil === 'function') {
+        waitUntil = arg3.waitUntil.bind(arg3);
+      }
+    }
+
+    if (!request || typeof request.method !== 'string') {
+      return new Response('Invalid Request Object', { status: 400 });
+    }
+
+    const method = request.method.toUpperCase();
+    const url = new URL(request.url);
+
+    // 1. CORS Preflight
+    if (method === 'OPTIONS') {
+      return new Response(null, {
+        status: 204,
+        headers: {
+          'Access-Control-Allow-Origin': '*',
+          'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+          'Access-Control-Allow-Headers': 'Content-Type, X-Telegram-Bot-Api-Secret-Token',
+        },
+      });
+    }
+
+    // 2. Path validation if specified
+    if (opts.path && opts.path !== '/' && url.pathname !== opts.path) {
+      return new Response('Not Found', { status: 404 });
+    }
+
+    // 3. GET Method: Health check & diagnostics
+    if (method === 'GET') {
+      if (opts.enableHealthCheck) {
+        const hasToken = Boolean(
+          (env && (env.BOT_TOKEN || env.TELEGRAM_BOT_TOKEN)) ||
+          cachedBot?.telegram?.token
+        );
+        const hasSecret = Boolean(
+          opts.secretToken ||
+          (env && (env.WEBHOOK_SECRET || env.SECRET_TOKEN))
+        );
+
+        return new Response(
+          JSON.stringify(
+            {
+              status: 'ok',
+              engine: 'Telegix',
+              runtime: 'Cloudflare Pages Functions / Workers',
+              service: 'Telegram Bot Webhook Endpoint',
+              timestamp: new Date().toISOString(),
+              endpoint: url.pathname,
+              configured: {
+                botToken: hasToken,
+                secretTokenVerification: hasSecret,
+                backgroundExecution: Boolean(opts.waitUntil && waitUntil),
+              },
+              hint: 'Send POST updates from Telegram to this URL.',
+            },
+            null,
+            2
+          ),
+          {
+            status: 200,
+            headers: {
+              'Content-Type': 'application/json; charset=utf-8',
+              'Access-Control-Allow-Origin': '*',
+            },
+          }
+        );
+      }
+      return new Response('Method Not Allowed', { status: 405 });
+    }
+
+    // 4. Webhook updates MUST be POST
+    if (method !== 'POST') {
+      return new Response('Method Not Allowed', { status: 405 });
+    }
+
+    // 5. Secret Token Verification
+    let secretToken = opts.secretToken;
+    if (typeof secretToken === 'function') {
+      secretToken = secretToken(env);
+    } else if (!secretToken && env) {
+      secretToken = env.WEBHOOK_SECRET || env.SECRET_TOKEN;
+    }
+
+    if (secretToken) {
+      const receivedToken = request.headers.get('x-telegram-bot-api-secret-token');
+      if (receivedToken !== secretToken) {
+        return new Response('Forbidden: Invalid Webhook Secret Token', {
+          status: 403,
+          headers: { 'Content-Type': 'text/plain' },
+        });
+      }
+    }
+
+    // 6. Resolve Bot Instance
+    let bot = cachedBot;
+    if (!bot) {
+      if (typeof botOrFactory === 'function') {
+        bot = botOrFactory(env, { request, env, waitUntil });
+        cachedBot = bot;
+      } else if (opts.getBot && typeof opts.getBot === 'function') {
+        bot = opts.getBot(env, { request, env, waitUntil });
+      } else if (env && (env.BOT_TOKEN || env.TELEGRAM_BOT_TOKEN)) {
+        const token = env.BOT_TOKEN || env.TELEGRAM_BOT_TOKEN;
+        const { Telegix } = await import('./telegix.js');
+        bot = new Telegix(token);
+        cachedBot = bot;
+      }
+    }
+
+    if (!bot) {
+      return new Response(
+        'Server Configuration Error: Telegix Bot instance or BOT_TOKEN is missing in Cloudflare environment.',
+        {
+          status: 500,
+          headers: { 'Content-Type': 'text/plain' },
+        }
+      );
+    }
+
+    // 7. Parse incoming Telegram Update JSON
+    let update = null;
+    try {
+      update = await request.json();
+    } catch {
+      return new Response('Bad Request: Invalid JSON Payload', {
+        status: 400,
+        headers: { 'Content-Type': 'text/plain' },
+      });
+    }
+
+    if (!update || typeof update !== 'object') {
+      return new Response('Bad Request: Expected Telegram update object', {
+        status: 400,
+        headers: { 'Content-Type': 'text/plain' },
+      });
+    }
+
+    // 8. Optional user hook before processing
+    if (typeof opts.onUpdate === 'function') {
+      try {
+        await opts.onUpdate(update, { request, env, waitUntil, bot });
+      } catch (hookErr) {
+        console.warn('[Telegix Webhook] onUpdate hook error:', hookErr);
+      }
+    }
+
+    // 9. Pipeline execution
+    const processTask = (async () => {
+      try {
+        await bot.handleUpdate(update);
+      } catch (err) {
+        console.error('[Telegix Webhook] Error processing update:', err);
+        if (typeof opts.onError === 'function') {
+          opts.onError(err, { update, request, env, bot });
+        } else if (bot.errorHandler) {
+          bot.errorHandler(err);
+        }
+      }
+    })();
+
+    // 10. If waitUntil is enabled and supported by Cloudflare, return 200 OK immediately
+    // to prevent Telegram webhook timeouts (< 5 seconds)!
+    if (opts.waitUntil && typeof waitUntil === 'function') {
+      waitUntil(processTask);
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/json',
+          'Access-Control-Allow-Origin': '*',
+        },
+      });
+    }
+
+    // Otherwise await synchronously
+    try {
+      await processTask;
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/json',
+          'Access-Control-Allow-Origin': '*',
+        },
+      });
+    } catch (err) {
+      const status = typeof opts.respondOnError === 'number' ? opts.respondOnError : 200;
+      return new Response(JSON.stringify({ ok: false, error: err.message }), {
+        status,
+        headers: {
+          'Content-Type': 'application/json',
+          'Access-Control-Allow-Origin': '*',
+        },
+      });
+    }
+  };
+}
+
+/**
+ * Direct function to handle a Cloudflare Pages or Workers request
+ * @param {object} context - Cloudflare Pages context or request
+ * @param {import('./telegix.js').Telegix} bot
+ * @param {object} [options]
+ * @returns {Promise<Response>}
+ */
+export async function handleCloudflareWebhook(context, bot, options = {}) {
+  const handler = createPagesWebhookHandler(bot, options);
+  return handler(context);
+}
+
+/**
+ * Alias for createPagesWebhookHandler for Cloudflare Workers / Edge environments
+ */
+export const createCloudflareWebhookCallback = createPagesWebhookHandler;
+
+/**
+ * Helper handler for Cloudflare Pages to set, check, or delete Telegram Webhook via HTTP
+ * Place in `functions/setWebhook.js` for instant webhook registration in your browser or curl.
+ *
+ * @param {import('./telegix.js').Telegix | ((env: any) => import('./telegix.js').Telegix)} [botOrFactory]
+ * @param {object} [options]
+ * @param {string} [options.webhookPath='/webhook']
+ * @returns {Function} Cloudflare Pages Request Handler
+ */
+export function createPagesSetWebhookHandler(botOrFactory, options = {}) {
+  const webhookPath = options.webhookPath || '/webhook';
+
+  return async function handleSetWebhook(context) {
+    const request = context.request || context;
+    const env = context.env || {};
+    const url = new URL(request.url);
+    const action = url.searchParams.get('action') || (request.method === 'POST' ? 'set' : 'info');
+
+    // Resolve bot instance
+    let bot = typeof botOrFactory === 'object' && botOrFactory !== null ? botOrFactory : null;
+    if (!bot) {
+      if (typeof botOrFactory === 'function') {
+        bot = botOrFactory(env);
+      } else if (env && (env.BOT_TOKEN || env.TELEGRAM_BOT_TOKEN)) {
+        const token = env.BOT_TOKEN || env.TELEGRAM_BOT_TOKEN;
+        const { Telegix } = await import('./telegix.js');
+        bot = new Telegix(token);
+      }
+    }
+
+    if (!bot) {
+      return new Response(
+        JSON.stringify(
+          {
+            ok: false,
+            error: 'BOT_TOKEN is not configured in Cloudflare environment variables.',
+          },
+          null,
+          2
+        ),
+        { status: 500, headers: { 'Content-Type': 'application/json' } }
+      );
+    }
+
+    const secretToken = options.secretToken || env.WEBHOOK_SECRET || env.SECRET_TOKEN || undefined;
+    const targetWebhookUrl = `${url.origin}${webhookPath}`;
+
+    try {
+      if (action === 'set') {
+        const dropPending = url.searchParams.get('drop_pending_updates') === 'true';
+        const result = await bot.telegram.setWebhook(targetWebhookUrl, {
+          secret_token: secretToken,
+          drop_pending_updates: dropPending,
+        });
+
+        const info = await bot.telegram.getWebhookInfo();
+
+        return new Response(
+          JSON.stringify(
+            {
+              ok: true,
+              action: 'setWebhook',
+              message: 'Telegram Webhook successfully set for Cloudflare Pages!',
+              webhookUrl: targetWebhookUrl,
+              secretTokenSet: Boolean(secretToken),
+              telegramResponse: result,
+              currentWebhookInfo: info,
+            },
+            null,
+            2
+          ),
+          { status: 200, headers: { 'Content-Type': 'application/json' } }
+        );
+      }
+
+      if (action === 'delete') {
+        const dropPending = url.searchParams.get('drop_pending_updates') === 'true';
+        const result = await bot.telegram.deleteWebhook({
+          drop_pending_updates: dropPending,
+        });
+
+        return new Response(
+          JSON.stringify(
+            {
+              ok: true,
+              action: 'deleteWebhook',
+              message: 'Telegram Webhook successfully deleted.',
+              telegramResponse: result,
+            },
+            null,
+            2
+          ),
+          { status: 200, headers: { 'Content-Type': 'application/json' } }
+        );
+      }
+
+      // Default: show current Webhook Info
+      const info = await bot.telegram.getWebhookInfo();
+      const me = await bot.telegram.getMe().catch(() => null);
+
+      return new Response(
+        JSON.stringify(
+          {
+            ok: true,
+            action: 'getWebhookInfo',
+            bot: me
+              ? { id: me.id, username: me.username, first_name: me.first_name }
+              : 'Unknown',
+            targetWebhookUrl,
+            currentWebhookInfo: info,
+            actions: {
+              setWebhook: `${url.origin}/setWebhook?action=set`,
+              deleteWebhook: `${url.origin}/setWebhook?action=delete`,
+              setWithDropUpdates: `${url.origin}/setWebhook?action=set&drop_pending_updates=true`,
+            },
+          },
+          null,
+          2
+        ),
+        { status: 200, headers: { 'Content-Type': 'application/json' } }
+      );
+    } catch (err) {
+      return new Response(
+        JSON.stringify(
+          {
+            ok: false,
+            error: err.message,
+            code: err.code || err.error_code,
+          },
+          null,
+          2
+        ),
+        { status: 500, headers: { 'Content-Type': 'application/json' } }
+      );
+    }
+  };
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telegix",
-  "version": "1.1.3-a1",
+  "version": "1.1.4",
   "description": "Lightweight Telegram Bot API framework for Node.js.",
   "type": "module",
   "main": "./index.cjs",
@@ -38,5 +38,11 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/KazeDevID/telegix.git"
+  },
+  "scripts": {
+    "dev": "node server.js",
+    "build": "node -e 'console.log(\"Telegix build complete\")'",
+    "start": "node server.js",
+    "lint": "node -c index.js server.js lib/*.js"
   }
 }