config.env.example

######################################### IMPORTANT ############################################
################## SET THE 🔴 REQUIRED 🔴 API KEYS BEFORE STARTING THE BOT ####################
## FIND THE VARIABLES THAT HAVE ✏️ EMOJI AND CHANGE THEM BEFORE DEPLOYING FOR PRODUCTION USE ##


######################### REQUIRED API KEYS ########################
#[🔴 REQUIRED 🔴 | FOR INTERACTING WITH THE BOT]
# Get your own API key from @BotFather on Telegram and place it here.
TELEGRAM_API_KEY=telegram-api-key # example: TELEGRAM_API_KEY=9973162614:AbJUdK6IoNVwtIh_hStPEr85Hb_d-Lnuzo4
TELEGRAM_BASE_URL=https://api.telegram.org


#[🔴 REQUIRED 🔴 | FOR GENERATING TAGS AND SUMMARY]
# Get your own API key from https://aistudio.google.com (free - no credit-card required) and place it here. 
# You can provide one or more API keys to distribute requests across multiple keys, which helps reduce the risk of hitting API rate limits.
# If you are using a single API key, wrap it in an array format like this:
# - single-key example: GEMINI_API_KEYS='["apikey1"]'
# For multiple API keys, place them within the same array to rotate through them, one of them will be selected randomly before each API call:
# - multi-keys example: GEMINI_API_KEYS='["apikey1", "apikey2", "apikey3"]'
GEMINI_API_KEYS='["apikey1"]' 
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/models


############################## NODE_ENV #############################
# Set NODE_ENV to 'production' if you want to deploy the bot on a server.
# In production, the following changes occur by default:
# 1. Polling interval increases from 1000ms to 3000ms.
# 2. Rate limit per day reduces from 100 requests to:
#    - 10 requests for private chats
#    - 10 requests for channel posts
# 3. Logging is adjusted:
#    - Logging to the output.log file is disabled.
#    - Fewer logs are printed in the console.

#[🟢 OPTIONAL - CHANGE TO NODE_ENV=production FOR PRODUCTION ENVIRONMENT]
NODE_ENV=development # ✏️ example: NODE_ENV=production

# Polling intervals in milliseconds for development and production environments.
POLLING_INTERVAL_DEV=1000
POLLING_INTERVAL_PROD=3000


##################### TAG GENERATION SETTINGS #####################
# Tag Generation is always turned ON and can't be turned off (After all this bot's whole existence is based on generating tags xD)
# By default, we're using Google Gemini API to generate tags, it's very accurate with high rate-limit (1500 requests/day for gemini-1.5-flash model | 2024/09) 
# But you are free to choose 2nd Method (OpenRouter through OpenAiCompatible) which has a lower rate limit (200 requests/day for free models | 2024/09),
# Or if you have a powerful server, choose the 3rd method (Ollama) and generate summaries locally without worrying about rate-limits, 
# Finally, you can also use the 4th method (TextRazor) which has a lower rate limit (500 requests/day for free plan | 2024/09).
# Text Razor is just a backup method and IMO should be used only when something is wrong with other methods such as:
# (e.g. not being available in certain regions, deprecating Endpoint (current Gemini API version: v1beta),
# sudden change of API structure, announcing lower rate-limits for free plan in future, etc.)

# There are a total of 4 methods to generate tags (see the methods and a complete description of each one in src/utils/tagGenerators.js)
# 1. googleGeminiTagGenerator() works by using google gemini's API Endpoint, fast, accurate, high rate-limit | API-KEY needed
# 2. openAiCompatibleTagGenerator() works by sending the request to a provider that has OpenAi-Compatible API (openRouter in this case) | API-KEY needed
# 3. ollamaTagGenerator() works by using a local-hosted LLM through Ollama | needs local setup but doesn't need any API-KEY
# 4. textRazorTagGenerator() works by using text Razor's API Endpoint, fast, semi-accurate, low rate-limit | API-KEY needed

# Use the method of your choice by typing its number in TAG_GENERATION_METHOD
# NOTE 1: setting TAG_GENERATION_METHOD=2, requires you to provide the API KEY for Open Router below.
# NOTE 2: setting TAG_GENERATION_METHOD=3, requires you to setup and host Ollama with an llm locally (more info can be found at src/utils/summaryGenerators.js).
# NOTE 3: setting TAG_GENERATION_METHOD=4, requires you to provide the API KEY for TEXT RAZOR below.
TAG_GENERATION_METHOD=1 # ✏️ example: TAG_GENERATION_METHOD=2 (which corresponds to openAiCompatibleTagGenerator())

#[🟢 OPTIONAL - METHOD 2 CONFIGURATION]
# Get your own API key from https://openRouter.ai (free - no credit-card required) and place it here. 
# You can provide one or more API keys to distribute requests across multiple keys, which helps reduce the risk of hitting API rate limits.
# If you are using a single API key, wrap it in an array format like this:
# - single-key example: OPENROUTER_API_KEYS='["apikey1"]'
# For multiple API keys, place them within the same array to rotate through them, one of them will be selected randomly before each API call:
# - multi-keys example: OPENROUTER_API_KEYS='["apikey1", "apikey2", "apikey3"]'
OPENROUTER_API_KEYS='["apikey1"]'
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1 

#[🟢 OPTIONAL - METHOD 4 CONFIGURATION]
# Get your own API key from https://www.textrazor.com/signup (select the free plan - no credit-card required) and place it here.
# You can provide one or more API keys to distribute requests across multiple keys, which helps reduce the risk of hitting API rate limits.
# If you are using a single API key, wrap it in an array format like this:
# - single-key example: TEXTRAZOR_API_KEYS='["apikey1"]'
# For multiple API keys, place them within the same array to rotate through them, one of them will be selected randomly before each API call:
# - multi-keys example: TEXTRAZOR_API_KEYS='["apikey1", "apikey2", "apikey3"]'
TEXTRAZOR_API_KEYS='["apikey1"]'
TEXTRAZOR_BASE_URL=https://api.textrazor.com 


##################### SUMMARIZATION SETTINGS ######################
# The summary will be generated from specifically the "FIRST URL" in a message, and only if that URL meets these conditions:
# 1. First it checks if it's a Youtube URL, and then fetches the captions (if available) using one of youtubeCaptionDownloader.js methods, and passes it to the LLM
# 2. If it's not a Youtube URL, then it's a regular URL and it get its text content using "only" PrimaryContextExtender.js (if possible), and passes it to the LLM
# 3. If for some reason, the captions can't be retrieved from a Youtube URL, or the text content can't be retrieved from a regular URL, no summary will be generated
# Summarized content will be displayed via bot replies, or edited posts in channels, alongside the generated tags.

# Set ENABLE_SUMMARIZATION to 'true' to allow the bot to summarize text content fetched from URLs 
ENABLE_SUMMARIZATION=true # ✏️ example: ENABLE_SUMMARIZATION=true


# There are a total of 3 methods to generate a summary (see the methods and a complete description of each one in src/utils/summaryGenerators.js)
# 1. googleGeminiSummaryGenerator() works by using google gemini's API Endpoint, fast, accurate, high rate-limit | API-KEY needed
# 2. openAiCompatibleSummaryGenerator() works by sending the request to a provider that has OpenAi-Compatible API (openRouter in this case) | API-KEY needed
# 3. ollamaSummaryGenerator() works by using a local-hosted LLM through Ollama | needs local setup but doesn't need any API-KEY
# By default, we're using Google Gemini API to generate summaries, it's accurate with high rate-limit (1500 requests/day for gemini-1.5-flash model | 2024/09) 
# But you are free to choose 2nd Method which has a lower rate limit (200 requests/day for free models | 2024/09),
# Or if you have a powerful server, choose the 3rd method and generate summaries locally without worrying about rate-limits.

# Use the method of your choice by typing its number in SUMMARIZATION_METHOD
# NOTE 1: setting SUMMARIZATION_METHOD=2, requires you to provide the API KEY for Open Router in the Tag Generation section above.
# NOTE 2: setting SUMMARIZATION_METHOD=3, requires you to setup and host Ollama with an llm locally (more info can be found at src/utils/summaryGenerators.js).
SUMMARIZATION_METHOD=1 # ✏️ example: SUMMARIZATION_METHOD=3 (which corresponds to ollamaSummaryGenerator())


########################### PROXY OPTIONS ##########################
#[🟢 OPTIONAL - CONFIGURING PROXY IS NOT MANDATORY]
# If you are in a region where internet censorship is present (e.g., Iran), or access to some services or sites is not available, we implemented a feature
# That routes requests through a Cloudflare worker to bypass these regional restrictions, note that you shouldn't have problem with accessing cloudflare itself. 
# Cloudflare workers can be used as a proxy or bridge between our client and the target url, and mask our IP and location to bypass some restrictions.
# This feature can be enabled for some of the services in this bot that make direct http/https requests. 

#[❌ REQUIRED, IF YOU PLAN TO USE FOLLOWING PROXY OPTIONS]
# PROXY_BASE_URL should be set to the URL of the cloudflare worker
# You can learn how to get your cloudflare worker url from the "Cloudflare_worker_proxy_setup.md" guide from /docs
PROXY_BASE_URL=https://example.example.workers.dev/?url=  # ✏️ example: PROXY_BASE_URL=https://example.example.workers.dev/?url= 


# set to true to re-fetch the URLs with proxy (for URLs that were previously failed while fetching directly without proxy) (used in src/utils/urlFetcher.js)
ENABLE_URL_PROXY=false

# set to true to send all of API requests to Telegram through proxy (used in src/utils/urlFetcher.js) (used in src/services/telegramServices.js)
ENABLE_TELEGRAM_PROXY=false

# set to true to send all of API requests to Gemini through proxy (used in src/utils/tagGenerators.js & src/utils/summaryGenerators.js)
ENABLE_GEMINI_PROXY=false

# set to true to send all of API requests to Open Router through proxy (used in src/utils/summaryGenerators.js)
ENABLE_OPENROUTER_PROXY=false

# set to true to send all of API requests to Text Razor through proxy (used in src/utils/tagGenerators.js)
ENABLE_TEXTRAZOR_PROXY=false

##################### ADMIN ACCOUNT & VIP USERS ####################
# [OPTIONAL] Admin Account Configuration
# To use the bot's broadcasting feature, you need to provide your Telegram user ID.
# Otherwise, the bot won't verify admin requests, and broadcasting won't work.
# Get your Telegram ID using @id_by_username_bot or @JsonDumpBot.
# To use broadcasting feature, type /broadcast with admin account in the bot and then type your message (example: /broadcast hello world!) 

BOT_ADMIN_USER_ID=123456789 # ✏️ example: BOT_ADMIN_USER_ID=123456789


# [OPTIONAL] VIP Users Configuration
# If you want certain users to have VIP status, list their Telegram IDs here.
# VIP users enjoy the following benefits in production mode: (These are default configuration and can be changed)
# 1. 50 daily tokens for private chats (vs. 10 for regular users).
# 2. Ability to connect up to 5 channels (vs. 1 for regular users).
# 3. 25 daily tokens per connected channel (vs. 10 for regular users).
# Separate IDs with commas (it doesn't matter to put an space character after comma or not), provide the IDs as it is structured in the below example.
 
VIP_USER_IDS='your-vip-users-ids-here' # ✏️ example: VIP_USER_IDS='[123456789, 543216789]'


########################## TEXT PLACEHOLDERS ##########################
# You can learn how to setup a bot from the "HyperTAG_bot_setup.md" guide from /docs
SUPPORT_ACCOUNT_HANDLE=@mostafa_abbac  # ✏️ example: SUPPORT_ACCOUNT_HANDLE=@mostafa_abbac

BOT_NAME=HyperTAG                      # ✏️ example: BOT_NAME=HyperTAG
BOT_HANDLE=@HyperTAG_bot               # ✏️ example: BOT_HANDLE=@HyperTAG_bot
BOT_LINK=t.me/HyperTAG_bot             # ✏️ example: BOT_LINK=t.me/HyperTAG_bot
BOT_SIGNATURE=@HyprTAG                 # ✏️ example: BOT_SIGNATURE=@HyprTAG - This will be added to messages edited by HyperTAG in Channels 
BOT_SUPPORT_CHANNEL=t.me/Falken_Devlog # ✏️ example: BOT_SUPPORT_CHANNEL=t.me/Falken_Devlog

BOT_GITHUB_LINK=github.com/Mostafa-Abbasi/HyperTAG # ✏️ example: BOT_GITHUB_LINK=github.com/Mostafa-Abbasi/HyperTAG


########################### RATE LIMITING ##########################
# [OPTIONAL] Max Connected Channels for Regualr & VIP Users
# Define the maximum number of channels that a user can connect to the bot.
MAX_CONNECTED_CHANNELS=1
MAX_CONNECTED_CHANNELS_VIP=5 


# Define request rate limits for different environments.
# These limits reset daily at 00:00 AM midnight.

## Private Chats Rate Limits
RATE_LIMIT_PRIVATE_DEV=10           # Development environment
RATE_LIMIT_PRIVATE_PROD=10          # Production environment
RATE_LIMIT_PRIVATE_VIP_DEV=100      # VIP users in development environment
RATE_LIMIT_PRIVATE_VIP_PROD=50      # VIP users in production environment

## Channel Posts Rate Limits
RATE_LIMIT_CHANNEL_DEV=10           # Development environment
RATE_LIMIT_CHANNEL_PROD=10          # Production environment
RATE_LIMIT_CHANNEL_VIP_DEV=100      # VIP users in development environment
RATE_LIMIT_CHANNEL_VIP_PROD=25      # VIP users in production environment


########################### BOT SETTINGS ##########################
## Translation Feature Configuration
# Set ENABLE_TRANSLATION to 'true' to allow the bot to generate tags for unsupported languages by the TextRazor API.
# Unsupported text is detected using the "eld" library and translated using "@vitalets/google-translate-api".
# Heavy usage of this feature might result in a "TooManyRequestsError (code 429)" due to unofficial access to Google Translate.
# TextRazor API's supported languages: textrazor.com/languages - 19 as of now | List below:
# [Arabic, English, Chinese, Danish, Dutch, Finnish, French, German, Greek, Italian,
# Japanese, Korean, Norwegian, Polish, Portuguese, Russian, Spanish, Swedish, Ukrainian]
ENABLE_TRANSLATION=true


## Tag Display Configuration
# Define the number of tags displayed per request in private chats and channels.
NUMBER_OF_TAGS_TO_DISPLAY_IN_PRIVATE_CHAT=10 # recommended range: 5-10
NUMBER_OF_TAGS_TO_DISPLAY_IN_CHANNEL=5       # recommended range: 3-7


## Context Analysis Settings
# Define the number of URLs and characters to retrieve for better context analysis.
# Higher numbers greatly increase the accuracy of the analysis but can also slow down the bot
# Set NUMBER_OF_URLS_TO_ANALYZE_FROM_EACH_REQUEST to 0 if you do not want to fetch any URLs at all
NUMBER_OF_URLS_TO_ANALYZE_FROM_EACH_REQUEST=2        # recommended range: 0-5
NUMBER_OF_CHARACTERS_TO_RETRIEVE_FROM_EACH_URL=15000 # recommended range: 5000-20000
# Set the maximum allowed size for a URL's content (in bytes) before terminating the fetch process.
# If the fetched content exceeds this limit, the process will be stopped to prevent excessive resource usage.
MAX_URL_SIZE=10485760 # 10 MB in bytes               # recommended range: 10*1024*1024 - 20*1024*1024 or (10MB - 20MB)


## Context Extension Settings
# Set ENABLE_SECONDARY_CONTEXT_EXTENSION to 'true' to use a secondary context extender as a fallback option.
# This option is less reliable and uses the cheerio library to select the main content.
ENABLE_SECONDARY_CONTEXT_EXTENSION=true


## Post Length Limitations
# Define the maximum allowed lengths for posts and captions to prevent issues with the Telegram API.
# Keeping the limits slightly lower than Telegram's maximum avoids "Bad Request: MESSAGE_TOO_LONG" or "MEDIA_CAPTION_TOO_LONG" errors.
# It is best to not mess with these values unless you know what you're doing
MAX_ALLOWED_POST_TEXT_LENGTH=3900   # recommended: 3900 (Telegram max: 4096)
MAX_ALLOWED_POST_CAPTION_LENGTH=828 # recommended: 828  (Telegram max: 1024)


## Sponsor Channel Configuration
# Set ENABLE_SPONSOR_CHANNEL to 'true' if you want users to join a specific
# channel before they can use the bot.
ENABLE_SPONSOR_CHANNEL=true                 # ✏️ example: ENABLE_SPONSOR_CHANNEL=true

# Set the ID of the sponsor channel here. Users must join this channel to use the bot.
# IMPORTANT - The bot should also be added to the sponsor channel to verify if the user has joined or not.
# To obtain the channel ID, forward one of its posts to @id_by_username_bot or @JsonDumpBot.
SPONSOR_CHANNEL_ID=-1001374364132           # ✏️ example: SPONSOR_CHANNEL_ID=-1001374364132

# Provide the link for users to join the sponsor channel. You can do this in one of two forms:
# 1. Use the direct link format, e.g., t.me/+0ifSLk5nQJ43ODY8
# 2. Or use the channel ID format, e.g., @HW_HUB
SPONSOR_CHANNEL_LINK=t.me/+0ifSLk5nQJ43ODY8 # ✏️ example: SPONSOR_CHANNEL_LINK=@HW_HUB