Metadata-Version: 2.4
Name: matrix-biblebot
Version: 0.3.0
Summary: A simple Matrix bot that fetches Bible verses
Author-email: Jeremiah K <jeremiahk@gmx.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jeremiah-k/matrix-biblebot
Project-URL: Repository, https://github.com/jeremiah-k/matrix-biblebot
Project-URL: Issues, https://github.com/jeremiah-k/matrix-biblebot/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Communications
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mindroom-nio==0.40.0
Requires-Dist: PyYAML==6.0.3
Requires-Dist: python-dotenv==1.2.3
Requires-Dist: aiohttp==3.14.3
Requires-Dist: rich==15.0.0
Requires-Dist: packaging==26.3
Provides-Extra: e2e
Requires-Dist: mindroom-nio[e2e]==0.40.0; extra == "e2e"
Provides-Extra: test
Requires-Dist: pytest==9.1.1; extra == "test"
Requires-Dist: pytest-asyncio==1.4.0; extra == "test"
Requires-Dist: pytest-cov==7.1.0; extra == "test"
Requires-Dist: pytest-aiohttp==1.1.1; extra == "test"
Requires-Dist: coverage==7.16.0; extra == "test"
Dynamic: license-file

# Matrix BibleBot

A Matrix bot that fetches Bible verses and shares them in chat rooms. Simply send a Bible reference like "John 3:16" as a message and the bot will respond with the verse text.

## What it does

**Input:** `John 3:16 esv`
**Output:**

> For God so loved the world, that he gave his only Son, that whoever believes in him should not perish but have eternal life. - John 3:16 🕊️✝️

The bot supports both KJV (default) and ESV translations, works in encrypted rooms, and can split long passages into multiple messages.

## Quick Start

1. **Install the bot**

   ```bash
   pipx install matrix-biblebot
   ```

2. **Authenticate with Matrix**

   ```bash
   biblebot auth login
   ```

3. **Generate and edit config**

   ```bash
   biblebot config generate
   ```

   Then edit `~/.config/matrix-biblebot/config.yaml` to add your room IDs.

4. **Run the bot**

   ```bash
   biblebot
   ```

5. **Invite the bot to your Matrix rooms** and start sending Bible references!

## Features

- 📖 **Bible Translations**: KJV (default) and ESV support
- 🔒 **End-to-End Encryption**: Works in encrypted Matrix rooms
- ✂️ **Smart Message Splitting**: Long passages split intelligently
- 🚀 **Production Ready**: Rate limiting, error handling, systemd service
- 🎯 **Direct-Only Triggers**: Responds only when the entire message is a scripture reference

## Installation

### Recommended: pipx

```bash
# Basic installation
pipx install matrix-biblebot

# With end-to-end encryption support
pipx install 'matrix-biblebot[e2e]'
# Windows PowerShell: pipx install "matrix-biblebot[e2e]"
```

### Alternative: pip

```bash
pip install matrix-biblebot
# or with E2EE support
pip install 'matrix-biblebot[e2e]'
# Windows PowerShell: pip install "matrix-biblebot[e2e]"
```

### From Source

```bash
git clone https://github.com/jeremiah-k/matrix-biblebot.git
cd matrix-biblebot
pip install '.[e2e]'  # Includes E2EE support
```

## Usage

### Supported Reference Formats

The bot understands various Bible reference formats:

| Format               | Example                 | Description                  |
| -------------------- | ----------------------- | ---------------------------- |
| **Single verse**     | `John 3:16`             | Gets one verse (KJV default) |
| **Verse range**      | `1 Cor 15:1-4`          | Gets multiple verses         |
| **Whole chapter**    | `Psalm 23`              | Gets entire chapter          |
| **With translation** | `John 3:16 esv`         | Specify ESV or KJV           |
| **Abbreviations**    | `jn 3:16`, `1co 15:1-4` | Short book names work        |

### Supported Translations

- **KJV (King James Version)** - Default, no setup required
- **ESV (English Standard Version)** - Requires free API key from [api.esv.org](https://api.esv.org/)

### Book Abbreviations

The bot recognizes many abbreviations: `gen` (Genesis), `exo` (Exodus), `matt` (Matthew), `jn` (John), `1co` (1 Corinthians), `rev` (Revelation), and many more. See [full list](docs/CONFIGURATION.md#book-abbreviations).

### Reference Detection

The bot responds only when a message is **entirely** a scripture reference.

| Should trigger   | Example           |
| ---------------- | ----------------- |
| Single verse     | `John 3:16`       |
| Verse range      | `1 Cor 15:1-4`    |
| Whole chapter    | `Psalm 23`        |
| With translation | `Romans 8:28 ESV` |

| Should NOT trigger | Example            |
| ------------------ | ------------------ |
| Prefix command     | `!bible John 3:16` |
| Mention            | `@bot Psalm 23`    |
| Embedded in text   | `I like John 3:16` |

### Bot Response

When you send a Bible reference, the bot will:

1. Add a ✅ reaction to your message
2. Reply with the verse text formatted like: `"Verse text - Reference 🕊️✝️"`

## Configuration

### Basic Setup

1. **Authenticate with Matrix**

   ```bash
   biblebot auth login
   ```

2. **Generate configuration file**

   ```bash
   biblebot config generate
   ```

3. **Edit the config file** at `~/.config/matrix-biblebot/config.yaml`:

   ```yaml
   matrix:
     room_ids:
       - "!your_room_id:your_homeserver_domain"
       - "#room_alias:your_homeserver_domain" # Aliases work too
   ```

4. **Run the bot**
   ```bash
   biblebot
   ```

### Advanced Configuration

For detailed configuration options including:

- End-to-end encryption setup
- Message splitting configuration
- API key configuration for ESV
- Poetry formatting options
- Custom file locations

See the [Configuration Guide](docs/CONFIGURATION.md).

### Docker

The published image runs as a non-root user on amd64 and arm64 and keeps
configuration, credentials, and E2EE state under `/data`.

```bash
make setup
# Edit ~/.config/matrix-biblebot/config.yaml, then:
make auth-login
make run
```

Use `make use-source && make build` to build locally instead of pulling the
published image. See the [Docker guide](docs/DOCKER.md) for Compose, custom
runtime paths, and direct Docker commands.

## Running as a Service

For production use on Linux, install as a systemd user service:

```bash
biblebot service install
```

This creates a user service that starts automatically. Manage it with:

```bash
systemctl --user start biblebot.service     # Start
systemctl --user stop biblebot.service      # Stop
systemctl --user status biblebot.service    # Check status
```

## CLI Commands

```bash
# Configuration
biblebot config generate    # Create sample config
biblebot config check       # Validate config

# Authentication
biblebot auth login         # Login to Matrix
biblebot auth logout        # Clear credentials
biblebot auth status        # Show auth status
biblebot auth cross-sign    # Refresh an existing bot cross-signing identity

# Service management
biblebot service install    # Install systemd service

# Running
biblebot                    # Start the bot
biblebot --log-level debug  # Debug mode
```

### Bot self-cross-signing

Cross-signing is never run during login or bot startup. Back up the E2EE
store before using the explicit command. The default location is
`~/.local/state/matrix-biblebot/e2ee-store`. If you have set a non-default
state directory, the store lives at `$XDG_STATE_HOME/matrix-biblebot/e2ee-store`
(or, when `XDG_STATE_HOME` is unset, `~/.local/state/matrix-biblebot/e2ee-store`).
When `BIBLEBOT_HOME` is set, everything is under `<BIBLEBOT_HOME>/e2ee-store`
instead. Use `biblebot auth status` to confirm the resolved path on your
install before backing up. An
existing BibleBot-managed identity can be refreshed with
`biblebot auth cross-sign`; the Matrix password is prompted for and never saved.

The first run has no local `_cross_signing.json` sidecar and is refused by
default. Only after confirming the account has no Element-managed cross-signing
identity, run `biblebot auth cross-sign --bootstrap`. MindRoom nio cannot import
or reconcile an existing server-side identity, so bootstrapping can replace it.
Corrupt, unexpected, or multiple sidecars are refused rather than rotated.

The provider upgrade migrates the encrypted store schema from version 2 to 10
when first opened. Back up the complete store first. Recreate existing
environments rather than upgrading in place: `matrix-nio` and `mindroom-nio`
both own the `nio` import package and must not be co-installed.

## Troubleshooting

**Common issues:**

- **"No credentials found"** → Run `biblebot auth login` first
- **Bot doesn't respond** → Check room IDs in config, ensure bot is invited
- **E2EE issues** → Install with `[e2e]`; if your Matrix client withholds keys
  from unverified devices, verify/cross-sign the bot device

For detailed troubleshooting, see [Troubleshooting Guide](docs/TROUBLESHOOTING.md).

## Documentation

- [Configuration Guide](docs/CONFIGURATION.md) - Detailed setup, options, and E2EE setup
- [Docker Guide](docs/DOCKER.md) - Prebuilt and source container deployment
- [Development Guide](docs/DEVELOPMENT.md) - Contributing and development setup
- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions

## Contributing

Contributions welcome! Please see [Development Guide](docs/DEVELOPMENT.md) for setup instructions, project structure, and the [Testing Guide](docs/dev/TESTING.md) for test conventions.

## License

MIT License - see [LICENSE](LICENSE) file for details.
