{"id":27918225,"url":"https://github.com/simplisticated/telegraf-starter","last_synced_at":"2025-07-16T06:36:07.136Z","repository":{"id":284939949,"uuid":"956511120","full_name":"simplisticated/telegraf-starter","owner":"simplisticated","description":"Telegram bot starter with Telegraf.js and TypeScript","archived":false,"fork":false,"pushed_at":"2025-04-19T15:41:57.000Z","size":203,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-19T19:17:50.858Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simplisticated.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-28T11:27:36.000Z","updated_at":"2025-04-19T15:42:00.000Z","dependencies_parsed_at":"2025-03-28T14:23:19.739Z","dependency_job_id":"567cf93b-d498-4c5a-aed9-408398e63420","html_url":"https://github.com/simplisticated/telegraf-starter","commit_stats":null,"previous_names":["simplisticated/telegraf-starter"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplisticated%2Ftelegraf-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplisticated%2Ftelegraf-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplisticated%2Ftelegraf-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplisticated%2Ftelegraf-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simplisticated","download_url":"https://codeload.github.com/simplisticated/telegraf-starter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252741571,"owners_count":21797049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-06T18:20:03.116Z","updated_at":"2025-05-06T18:20:03.705Z","avatar_url":"https://github.com/simplisticated.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegraf.js Starter\n\nTelegram bot starter with Telegraf.js and TypeScript. Includes the following\nfeatures and tools:\n\n-   TypeScript\n-   Jest\n-   Prettier\n-   ESLint with Airbnb style\n-   TypeORM\n-   100% automatic user management with SQLite database\n\n## How to Get Started\n\nTo begin, open your terminal and run the following command to install the\nrequired dependencies:\n\n```\nnpm install\n```\n\nFor starting the server in development mode, use the following command:\n\n```\nnpm run start:dev\n```\n\nTo run the server in production mode, follow these steps:\n\n```\nnpm run build\nnpm run start\n```\n\n## Environment Variables\n\nThis project relies on various environment variables for configuration. You can\nset these variables either in a local `.env` file or through your hosting\nenvironment, depending on your deployment method.\n\nHere are the essential environment variables and their purposes:\n\n-   `TELEGRAM_TOKEN`: Specifies the token that is used for Telegram bot.\n-   `APP_ENVIRONMENT`: `production`, `test`, or `local`. See more information\n    [here](#app-environment).\n\nYou should create a `.env` file in the root of your project and define these\nvariables with their respective values.\n\nHere is an example `.env` file:\n\n```\nTELEGRAM_TOKEN=1234567890\nAPP_ENVIRONMENT=local\n```\n\n## Scripts\n\nThe [package.json](./package.json) includes several useful scripts to manage,\nbuild, and run the project efficiently. Below is a description of each script:\n\n### Build and Run\n\n-   `build`\n\nDeletes the existing `dist` folder and compiles TypeScript files based on the\n`tsconfig.json` configuration.\n\n```\nnpm run build\n```\n\n-   `start`\n\nRuns the compiled JavaScript app from the `dist` directory. This should be used\nafter running the `build` command.\n\n```\nnpm run start\n```\n\n-   `start:dev`\n\nRuns the app in development mode using `ts-node` directly with the TypeScript\nsource files. Useful for quick development without building.\n\n```\nnpm run start:dev\n```\n\n---\n\n### Linting and Formatting\n\n-   `lint`\n\nRuns ESLint and Prettier to check for code quality and formatting issues.\n\n-   `lint:fix`\n\nAutomatically fixes linting issues where possible.\n\n```\nnpm run lint:fix\n```\n\n-   `format`\n\nFormats the code using Prettier.\n\n```\nnpm run format\n```\n\n---\n\n### Testing\n\n-   `test`\n\nRuns tests using Jest.\n\n```\nnpm run test\n```\n\n---\n\n### Combined Checks\n\n-   `check`\n\nRuns a series of checks, including building the project, running lint checks,\nand executing tests.\n\n```\nnpm run check\n```\n\n---\n\n## App Environment\n\nThe `AppEnvironment` type defines the environment in which the app is running.\nIt allows you to write conditional algorithm based on whether the app is in\ndevelopment, testing, or production.\n\nThere are three environment types:\n\n-   `production` - the environment used in production deployments;\n-   `test` - internal test environment, similar to `production` but not publicly\n    available;\n-   `local` - local development, where more relaxed rules may apply: logging,\n    test features, etc.\n\nThe current environment is defined by the `APP_ENVIRONMENT` value in the `.env`\nfile. If the value is not set, it defaults to `local`. You can get the current\nenvironment value anywhere in the project using `CURRENT_ENVIRONMENT`.\n\nExample usage:\n\n```typescript\nimport { AppEnvironment, CURRENT_ENVIRONMENT } from \"./app/environment\";\n\nif (CURRENT_ENVIRONMENT === AppEnvironment.production) {\n    // The bot is in production mode\n}\n```\n\nYou can also define environment-specific values:\n\n```typescript\nimport { getValueForCurrentEnvironment } from \"./app/environment\";\n\nconst apiUrl = getValueForCurrentEnvironment({\n    production: \"https://api.server.com\",\n    test: \"https://api-test.server.com\",\n    local: \"http://localhost:3000\",\n});\n```\n\n## Database\n\nThis project uses SQLite as its database engine, managed through TypeORM. The\ndatabase file is located at\n\n```\ndata/\u003cAPP_ENVIRONMENT\u003e/database.sqlite\n```\n\nFor instance, if the `APP_ENVIRONMENT` is set to `production`, the database path\nwould be\n\n```\ndata/production/database.sqlite\n```\n\nDatabase interactions are facilitated by the [STORE](./src/data/store/store.ts)\nobject, which offers essential methods for reading and writing data models.\n\n## User Management\n\nThis project uses two main models to manage users: [UserModel](#usermodel) and\n[TelegramProfileModel](#telegramprofilemodel).\n\n### `UserModel`\n\nRepresents a platform user. Key fields include:\n\n-   `id` - unique user identifier;\n-   `is_administrator` - flag indicating whether the user is an administrator\n    (default is `false`);\n-   `is_blocked` - user block flag (default is `false`).\n\nTo make a user an administrator: set `is_administrator = true` in the database.\n\nTo check if the user is administrator, use:\n\n```typescript\nconst isAdministrator = await STORE.isAdministrator(telegramId);\n```\n\nTo block a user: set `is_blocked = true` in the database.\n\nTo check if the user is blocked, use:\n\n```typescript\nconst isBlocked = await STORE.isBlocked(telegramId);\n```\n\n### `TelegramProfileModel`\n\nAssociated with `UserModel`, this model stores Telegram-specific data:\n\n-   `telegram_id` - the user’s Telegram ID;\n-   `username` - Telegram username;\n-   other data received from the Telegram Bot API.\n\nThe data in `TelegramProfileModel` is automatically updated every time the user\nsends a message, keeping the profile information in the database up to date.\n\n## Contributing\n\nYour input is welcome! If you have any interesting ideas, suggestions, or would\nlike to contribute through pull requests, feel free to do so.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplisticated%2Ftelegraf-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimplisticated%2Ftelegraf-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplisticated%2Ftelegraf-starter/lists"}