@kody/telegram

import { secretNameFrom, secretSetupUrl } from './validation.ts'
import { TELEGRAM_API_HOST } from './request.ts'

const DEFAULT_SECRET_NAME = 'telegramBotToken'

/** Agent-usable setup URLs and BotFather steps for this package. */
export default async function guide(params: Record<string, unknown> = {}) {
	const secretName = secretNameFrom(params)
	return {
		auth: 'bot-token',
		oauth: false,
		secretName,
		requiredHosts: [TELEGRAM_API_HOST],
		scopes: 'none — Telegram Bot API has no OAuth scopes. Access is chat membership, admin rights, and BotFather /setprivacy.',
		secretUrl: secretSetupUrl(secretName),
		doNotUseOAuthUrl:
			'https://kody.codes/connect/oauth?provider=telegram is Telegram Login Widget identity only. It cannot send or read Bot API messages. This package uses ' +
			secretName +
			' instead.',
		botFather: 'https://t.me/botfather',
		docs: 'https://core.telegram.org/bots/api',
		steps: [
			'Open Telegram and message @BotFather.',
			'Send /newbot and follow the prompts (or /token for an existing bot).',
			'Copy the bot token. Never paste it into chat.',
			'Save it at the secretUrl below and approve host api.telegram.org.',
			'In a private chat, send /start to the bot. For groups, add the bot; for channels, add it as an admin.',
			'To read all group messages, disable privacy mode with @BotFather /setprivacy or make the bot a group admin.',
			'Invoke kody:@kody/telegram/smoke-test to verify getMe.',
			'Mutations such as sendMessage take dryRun: true first, then confirm: true after explicit user approval.',
		],
		multiAccount:
			'Default secret is telegramBotToken. Additional bots use secretName telegramBotToken-<slug>, for example telegramBotToken-alerts.',
		defaultSecretName: DEFAULT_SECRET_NAME,
	}
}