Telegram Better Auth Plugin

Common errors

• TypeError: Cannot read properties of undefined (reading 'telegram')

  cause The `telegram` plugin was not correctly registered in the `betterAuth` instance, or the `signIn.telegram` method was called on an `authClient` instance without `telegramClient` plugin.
  fix Ensure `telegram` plugin is added to the `plugins` array of `betterAuth` on the server and `telegramClient` plugin is added to `createAuthClient` on the client. Verify correct import paths.

• Error: Telegram login data verification failed: Invalid hash

  cause The `hash` provided by the Telegram Login Widget does not match the server-calculated hash, indicating tampered data or an incorrect bot token configuration.
  fix Verify that the `botToken` in your server-side `telegram` plugin configuration is correct and matches the token of the bot linked to your domain. Ensure no modifications occur to the data object received from Telegram before sending it to the server.

• Error: Telegram login data verification failed: Auth date out of range

  cause The `auth_date` from the Telegram Login Widget is too old (typically more than 24 hours ago), meaning the authentication session has expired.
  fix Ensure the user re-authenticates via the Telegram Login Widget to obtain fresh `auth_date` and `hash` values. This error is typically handled by guiding the user to try logging in again.

Warnings

• gotcha The Telegram bot used for authentication must be correctly configured with a domain via the @BotFather bot using the `/setdomain` command. Failure to do so will prevent the Telegram Login Widget from functioning correctly or lead to verification failures.
  Fix: Contact @BotFather on Telegram, use the `/setdomain` command, and link your bot to the exact domain(s) where your Telegram Login Widget will be hosted.
• gotcha The `botToken` passed to the `telegram` plugin on the server-side is crucial for verifying the authenticity of Telegram login data. Ensure this token is securely stored (e.g., in environment variables) and is valid. An invalid or missing token will lead to authentication failures.
  Fix: Obtain a valid bot token from @BotFather. Set it as an environment variable (e.g., `TELEGRAM_BOT_TOKEN`) and ensure it's correctly accessed in your server-side configuration, e.g., `process.env.TELEGRAM_BOT_TOKEN ?? ''`.
• gotcha As this package is currently in version `0.0.x`, its API surface may undergo breaking changes without a major version increment (e.g., 1.0.0). Developers should be aware of potential API instability and review changelogs for updates.
  Fix: Regularly review the package's GitHub repository and changelog before upgrading to new `0.0.x` versions. Consider pinning to exact versions to prevent unexpected breaking changes.
• gotcha This package, and its peer dependency `better-auth`, require Node.js version 20 or higher. Running on older Node.js versions will result in runtime errors related to unsupported syntax or APIs.
  Fix: Ensure your project's Node.js environment is updated to version 20 or newer. Check your `package.json` engines field to reflect this requirement.

Install

• npm install telegram-better-auth npm
• yarn add telegram-better-auth yarn
• pnpm add telegram-better-auth pnpm

Imports

• telegram
  wrong:

  const { telegram } = require('telegram-better-auth');

  correct:

  import { telegram } from 'telegram-better-auth';

  Used for configuring the server-side Telegram plugin within better-auth. This package is ESM-only since its inception.
• telegramClient
  wrong:

  const { telegramClient } = require('telegram-better-auth');

  correct:

  import { telegramClient } from 'telegram-better-auth';

  Used for configuring the client-side Telegram plugin within better-auth/client. Ensure consistency between server and client plugin configurations.

Quickstart

Demonstrates both server-side and client-side setup for Telegram authentication using `telegram-better-auth` with `better-auth`. It covers plugin configuration and an example of handling authentication data from the Telegram Login Widget.

import { betterAuth } from 'better-auth';
import { createAuthClient } from 'better-auth/client';
import { telegram, telegramClient } from 'telegram-better-auth';

// --- Server-side configuration (auth.ts) ---
export const auth = betterAuth({
  plugins: [
    telegram({
      botToken: process.env.TELEGRAM_BOT_TOKEN ?? '', // Ensure BOT_TOKEN is set in your environment
      getTempEmail: (id) => `${id}@t.me`, // Function to generate a temporary email for Telegram users
    }),
  ],
});

// --- Client-side configuration (auth-client.ts) ---
const authClient = createAuthClient({
  plugins: [telegramClient()],
});

interface TelegramUserAuthData {
  id: number;
  first_name: string;
  last_name?: string;
  username?: string;
  photo_url?: string;
  auth_date: number;
  hash: string;
}

// Example function to handle data from Telegram Login Widget callback
const onTelegramAuth = async (user: TelegramUserAuthData) => {
  try {
    console.log('Attempting Telegram sign-in for user:', user.username || user.id);
    const data = await authClient.signIn.telegram(user);
    console.log('Telegram sign-in successful:', data);
    // Implement session refetch, redirect, etc.
  } catch (error) {
    console.error('Telegram sign-in failed:', error);
    // Handle error (e.g., display message to user)
  }
};

// This function would typically be called from the Telegram Login Widget's callback
// For demonstration, a placeholder:
// For testing, mock a user object (replace with actual data from Telegram):
// const mockTelegramUser: TelegramUserAuthData = {
//   id: 123456789,
//   first_name: 'Test',
//   username: 'testuser',
//   auth_date: Math.floor(Date.now() / 1000),
//   hash: 'mockhash_for_dev_only' // This hash must be generated by Telegram, don't hardcode in production
// };
// onTelegramAuth(mockTelegramUser);