Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/iamelevich/pocketbase-plugin-telegram-auth
This plugin implements Telegram WebApp Auth and Telegram Login Widget for the pocketbase
https://github.com/iamelevich/pocketbase-plugin-telegram-auth
pocketbase pocketbase-plugins telegram telegram-bot
Last synced: 3 months ago
JSON representation
This plugin implements Telegram WebApp Auth and Telegram Login Widget for the pocketbase
- Host: GitHub
- URL: https://github.com/iamelevich/pocketbase-plugin-telegram-auth
- Owner: iamelevich
- License: mit
- Created: 2023-01-16T17:21:35.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2024-04-06T07:41:12.000Z (10 months ago)
- Last Synced: 2024-04-06T08:30:34.864Z (10 months ago)
- Topics: pocketbase, pocketbase-plugins, telegram, telegram-bot
- Language: Go
- Homepage:
- Size: 188 KB
- Stars: 15
- Watchers: 1
- Forks: 4
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-pocketbase - GitHub
- awesome-pocketbase - GitHub
- awesome-pocketbase - Telegram auth - Add Telegram auth (Widget button and WebApp).  (Go Plugins)
README
[](https://github.com/iamelevich/pocketbase-plugin-telegram-auth/actions/workflows/test.yml)
[](https://codecov.io/github/iamelevich/pocketbase-plugin-telegram-auth)
- [Overview](#overview)
- [Requirements](#requirements)
- [Installation](#installation)
- [Autofill fields](#autofill-fields)
- [Example](#example)
- [Usage](#usage)
- [pocketbase\_plugin\_telegram\_auth](#pocketbase_plugin_telegram_auth)
- [Index](#index)
- [type Options](#type-options)
- [type Plugin](#type-plugin)
- [func MustRegister](#func-mustregister)
- [func Register](#func-register)
- [func (\*Plugin) AuthByTelegramData](#func-plugin-authbytelegramdata)
- [func (\*Plugin) GetCollection](#func-plugin-getcollection)
- [func (\*Plugin) GetForm](#func-plugin-getform)
- [func (\*Plugin) Validate](#func-plugin-validate)
- [Contributing](#contributing)
- [Process](#process)
- [Development setup](#development-setup)
- [Testing](#testing)
- [Writing tests](#writing-tests)
- [Linting](#linting)
- [Docs update in README](#docs-update-in-readme)
# Overview
This plugin implements [Telegram WebApp Auth](https://core.telegram.org/bots/webapps#validating-data-received-via-the-web-app) and [Telegram Login Widget](https://core.telegram.org/widgets/login) for the [pocketbase](https://github.com/pocketbase/pocketbase)
## Requirements
- Go 1.18+
- [Pocketbase](https://github.com/pocketbase/pocketbase) 0.12+
## Installation
```bash
go get github.com/iamelevich/pocketbase-plugin-telegram-auth
```
## Autofill fields
Next fields will be filled from telegram in auth collection record if exists:
- `name` - string
- `first_name` - string
- `last_name` - string
- `telegram_username` - string
- `telegram_id` - string
- `language_code` - string
## Example
You can check examples in [examples folder](/examples)
```go
package main
import (
tgAuthPlugin "github.com/iamelevich/pocketbase-plugin-telegram-auth"
"log"
"github.com/pocketbase/pocketbase"
)
func main() {
app := pocketbase.New()
// Setup tg auth for users collection
tgAuthPlugin.MustRegister(app, &tgAuthPlugin.Options{
BotToken: "YOUR_SUPER_SECRET_BOT_TOKEN", // Better to use ENV variable for that
CollectionKey: "users",
})
if err := app.Start(); err != nil {
log.Fatal(err)
}
}
```
After that new route `POST /api/collections/users/auth-with-telegram` will be available.
### Usage
Simple usage with js. You can check react example [here](./examples/webapp-react)
```js
const pb = new PocketBase('http://127.0.0.1:8090');
pb.send('/api/collections/users/auth-with-telegram', {
method: 'POST',
body: {
data: window.Telegram.WebApp.initData
}
}).then(res => {
pb.authStore.save(res.token, res.record);
});
```
# pocketbase\_plugin\_telegram\_auth
```go
import "github.com/iamelevich/pocketbase-plugin-telegram-auth"
```
## Index
- [type Options](<#Options>)
- [type Plugin](<#Plugin>)
- [func MustRegister\(app core.App, options \*Options\) \*Plugin](<#MustRegister>)
- [func Register\(app core.App, options \*Options\) \(\*Plugin, error\)](<#Register>)
- [func \(p \*Plugin\) AuthByTelegramData\(tgData forms.TelegramData\) \(\*models.Record, \*auth.AuthUser, error\)](<#Plugin.AuthByTelegramData>)
- [func \(p \*Plugin\) GetCollection\(\) \(\*models.Collection, error\)](<#Plugin.GetCollection>)
- [func \(p \*Plugin\) GetForm\(optAuthRecord \*models.Record\) \(\*forms.RecordTelegramLogin, error\)](<#Plugin.GetForm>)
- [func \(p \*Plugin\) Validate\(\) error](<#Plugin.Validate>)
Options defines optional struct to customize the default plugin behavior.
```go
type Options struct {
// BotToken is a Telegram bot token.
// You can get it from @BotFather.
BotToken string
// CollectionKey is a collection key (name or id) for PocketBase auth collection.
CollectionKey string
}
```
```go
type Plugin struct {
// contains filtered or unexported fields
}
```
```go
func MustRegister(app core.App, options *Options) *Plugin
```
MustRegister is a helper function to register plugin and panic if error occurred.
```go
func Register(app core.App, options *Options) (*Plugin, error)
```
Register plugin in PocketBase app.
### func \(\*Plugin\) AuthByTelegramData
```go
func (p *Plugin) AuthByTelegramData(tgData forms.TelegramData) (*models.Record, *auth.AuthUser, error)
```
AuthByTelegramData returns auth record and auth user by Telegram data.
### func \(\*Plugin\) GetCollection
```go
func (p *Plugin) GetCollection() (*models.Collection, error)
```
GetCollection returns PocketBase collection object for collection with name or id from options.CollectionKey.
```go
func (p *Plugin) GetForm(optAuthRecord *models.Record) (*forms.RecordTelegramLogin, error)
```
GetForm returns Telegram login form for collection with name or id from options.CollectionKey.
### func \(\*Plugin\) Validate
```go
func (p *Plugin) Validate() error
```
Validate plugin options. Return error if some option is invalid.
Generated by [gomarkdoc]()
# Contributing
This pocketbase plugin is free and open source project licensed under the [MIT License](LICENSE.md).
You are free to do whatever you want with it, even offering it as a paid service.
## Process
- Fork the repo
- Create a new branch
- Make your changes
- Create a pull request
- Wait for review
- Make changes if needed
- Merge
- Celebrate :)
## Development setup
- Install [asdf](https://asdf-vm.com/#/core-manage-asdf-vm) and plugins for tools listed in [.tool-versions](.tool-versions) file.
- This repo also uses [asdf-direnv](https://github.com/asdf-community/asdf-direnv). Install it and run `direnv allow` in the repo root.
- Setup `pre-commit` hooks with `pre-commit install -t commit-msg -t pre-commit`
## Testing
- Run `task test` to run tests
- Run `task test:report` to run tests and get coverage report in `./coverage.html`
### Writing tests
- Check [PocketBase testing guide](https://pocketbase.io/docs/testing/) this will be used for API calls testing
- To run test server and update testdata run `task run:test-server`
- Go to admin panel http://localhost:8090/_/
- Login: `[email protected]`
- Password: `testpassword`
- Folder with sqlite db: `./test/test_pb_data`
## Linting
- Run `task lint` to run linters
## Docs update in README
- Run `task docs` to update docs in README (it will also install [gomarkdoc](https://github.com/princjef/gomarkdoc))