Update README.md, add LICENSE

2026-03-11 13:58:29 +00:00 · 2026-03-11 13:58:29 +00:00 · 85fc508aa3
commit 85fc508aa3
parent 02cef12523
2 changed files with 185 additions and 26 deletions
--- a/README.md
+++ b/README.md
@ -1,50 +1,188 @@
-bsky2tg
-=======
+# bsky2tg

-**bsky2tg** will mirror posts from your Bluesky account to a Telegram channel through a bot. It supports creation and deletion of posts on Bluesky but not the other way.
+A real-time bridge that forwards Bluesky posts to Telegram. Monitor your Bluesky account and automatically send posts to a Telegram channel with full media support, quote posts, and more.

---
+## Features

-### Usage
+- 🦋 **Real-time sync** - Posts appear on Telegram seconds after posting on Bluesky
+- 📸 **Full media support** - Images, videos, GIFs (from Tenor)
+- 💬 **Quote posts** - Properly formatted with links to original posts
+- ✏️ **Edit support** - Updates Telegram message when you edit a Bluesky post
+- 🗑️ **Delete sync** - Removes from Telegram when you delete from Bluesky
+- 🔗 **Rich links** - @mentions, hashtags, and custom aliases converted to clickable links
+- ⏰ **Time filtering** - Ignore old posts and replies if desired
+- 🎬 **Video metadata** - Includes duration, dimensions, and thumbnail

-Create a `.env` file with the following:
+## Setup

-```properties
-TG_TOKEN=
-TG_CHANNEL_ID=
-BSKY_HANDLE=
-BSKY_PASSWORD=
-```
+### Prerequisites

-If you use a different Telegram bot endpoint, you can set it with
+- Go 1.21+
+- A Bluesky account
+- A Telegram bot and channel

-```properties
-TG_API_ENDPOINT=https://api.domain.com/bot%s/%s
-```
+### Installation

-# Podman
+1. **Clone the repository**
+   ```bash
+   git clone https://git.zio.sh/astra/bsky2tg
+   cd bsky2tg
+   ```

+2. **Build the project**
+   ```bash
+   go build
+   ```
+
+3. **Set environment variables**
+   ```bash
+   export BSKY_HANDLE="your.bsky.handle"
+   export BSKY_PASSWORD="your-app-password"  # NOT your main password
+   export TG_TOKEN="your-telegram-bot-token"
+   export TG_CHANNEL_ID="your-channel-id"
+   ```
+
+   **Optional:**
+   ```bash
+   export TG_API_ENDPOINT="https://api.telegram.org/bot%s/%s"  # Custom Telegram API endpoint
+   export OLDPOSTTIME="1"  # Ignore posts older than this many hours (default: 1)
+   ```
+
+4. **Run the daemon**
+   ```bash
+   ./bsky2tg
+   ```
+
+## Running with Podman
+
+Run the bot in a container using Podman:
+
+### With `.env` file
 ```bash
 podman run -it --name bsky2tg_<profile> \
  --env-file /path/to/.env \
  git.zio.sh/astra/bsky2tg:latest
 ```

-Or without `.env` file:
-
+### With environment variables
 ```bash
 podman run -it --name bsky2tg_<profile> \
-  --env TG_TOKEN= \
-  --env TG_CHANNEL_ID= \
-  --env BSKY_HANDLE= \
-  --env BSKY_PASSWORD= \
+  --env TG_TOKEN=<your-token> \
+  --env TG_CHANNEL_ID=<your-channel-id> \
+  --env BSKY_HANDLE=<your.handle> \
+  --env BSKY_PASSWORD=<your-app-password> \
  git.zio.sh/astra/bsky2tg:latest
 ```

+### Getting Your Credentials

-## Bash
+**Bluesky App Password:**
+- Go to Settings → Privacy and Security → App Passwords
+- Create a new app password (NOT your main Bluesky password)

+**Telegram Bot Token:**
+- Message [@BotFather](https://t.me/BotFather) on Telegram
+- Create a new bot with `/newbot`
+- Copy the token
+
+**Telegram Channel ID:**
+- Create a channel (can also be private)
+- Add your bot as an admin
+- Use `@userinfobot` to get the channel ID
+
+## Usage
+
+### Daemon Mode
+The bot runs continuously and syncs new posts in real-time:
 ```bash
-source .env
 ./bsky2tg
-```
+```
+
+### One-Shot Post Sync
+Send a specific post to Telegram:
+```bash
+./bsky2tg -post "https://bsky.app/profile/user.bsky/post/abc123"
+```
+
+### Delete a Post
+Remove a post from Telegram (delete from Bluesky first):
+```bash
+./bsky2tg -post "https://bsky.app/profile/user.bsky/post/abc123" -delete
+```
+
+### Ignore Old Posts
+Ignore posts created more than 2 hours ago:
+```bash
+./bsky2tg -oldposttime 2
+```
+
+## How It Works
+
+1. **Authentication** - Logs into Bluesky via ATProto and stores the session
+2. **Jetstream Connection** - Subscribes to real-time post events from your account
+3. **Post Processing** - Parses posts, extracts media, processes facets (links/mentions)
+4. **Telegram Delivery** - Sends formatted messages with media to your channel
+5. **Metadata Storage** - Records post mapping (Bluesky → Telegram) for edits/deletes
+
+## Configuration
+
+### Post Format
+
+Posts are sent with this format:
+```
+[Post text with @mentions and #hashtags]
+—
+🦋 @your.handle
+```
+
+Quote posts include the quoted post above in a blockquote.
+
+### Custom Aliases
+
+You can set up custom link replacements by creating entries in the `blue.zio.bsky2tg.alias` collection on your PDS.
+
+## Troubleshooting
+
+### Auth errors
+- Verify `BSKY_HANDLE` and `BSKY_PASSWORD` are correct
+- Use an app password, not your main Bluesky password
+- Check `auth-session.json` file permissions
+
+### Posts not syncing
+- Ensure the bot is admin in the channel
+- Check `TG_CHANNEL_ID` is correct
+- Verify Jetstream connection with logs
+
+### Video errors
+- FFmpeg must be installed for video processing
+- Check that video file can be read
+
+## Project Structure
+
+```
+.
+├── main.go              # Event handler, post processing, Telegram sender
+├── bsky/
+│   ├── client.go        # Bluesky session management, handle resolution
+│   ├── bluesky.go       # ATProto API calls (posts, records, sessions)
+│   └── parse.go         # Post parsing, facet processing
+├── auth-session.json    # Stored auth session (auto-created)
+└── README.md            # This file
+```
+
+## API Integration
+
+- **Bluesky ATProto** - Session creation, post fetching, record management
+- **Jetstream** - Real-time firehose subscription
+- **Telegram Bot API** - Message/media sending, editing, deleting
+
+## Notes
+
+- Auth sessions are persisted in `auth-session.json`
+- Tokens are automatically refreshed when expired
+- Posts are deduplicated to prevent duplicates on sync restart
+- Media is fetched from your PDS via blob endpoints
+
+## License
+
+See LICENSE file