Metadata-Version: 2.4
Name: errbot-backend-matrix
Version: 0.0.1
Summary: Matrix backend plugin for Errbot
Author: Errbot Matrix Contributors
License-Expression: GPL-3.0-only
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matrix-nio>=0.24.0
Requires-Dist: errbot>=6.2.0
Dynamic: license-file

# Errbot Matrix Backend

A fully functional, modern Matrix backend for Errbot built using `matrix-nio`.

## Features
- Connection to any Matrix homeserver via username/password or access token.
- Automatic acceptance of room invitations.
- Formatted messages (HTML/xhtml and markdown) sent and received natively.
- Full support for threaded replies using standard Matrix relations.
- Support for End-to-End Encryption (E2EE) using `matrix-nio`'s database storage.

## Requirements
- Python 3.11 - 3.14
- `errbot` >= 6.2.0
- `matrix-nio` >= 0.24.0

## Installation

### Local Installation for Development

You can install the backend locally inside your Errbot virtual environment:

```bash
pip install -e .
```

## Creating a Bot Account on Matrix

Errbot connects to the Matrix network using a standard Matrix user account. To set up an account for your bot:

1. **Register the User Account**:
   * Open a Matrix client such as [Element](https://app.element.io/).
   * Register a new account on your desired homeserver (e.g., `matrix.org` or a self-hosted instance).
   * Save the bot's full User ID (MXID, e.g., `@my_errbot:matrix.org`) and password.

2. **(Optional) Obtain an Access Token**:
   * If you prefer to authenticate using a login token rather than storing a plaintext password in `config.py`:
     * Log in to Element using the bot account.
     * Open **Settings** -> **Help & About** -> scroll down to the **Advanced** section and copy the **Access Token**.
     * Paste this token into the `BOT_IDENTITY` dictionary under the `token` key.

3. **Invite the Bot**:
   * Start a chat with the bot's MXID or invite the bot to a room. The backend is configured to automatically accept invites by default.

## Configuration

To use the Matrix backend, update your Errbot `config.py` file with the following settings:

```python
# Set the backend to 'Matrix'
BACKEND = 'Matrix'

# Provide connection credentials and settings
BOT_IDENTITY = {
    # The Matrix homeserver URL
    'homeserver': 'https://matrix.org',
    
    # The full Matrix user ID (MXID) of the bot
    'username': '@my_errbot:matrix.org',
    
    # Authentication (use either password OR token)
    'password': 'my-secure-password',
    # 'token': 'syt_your_access_token_here...',
    
    # Optional settings:
    # 'device_id': 'ERRBOT_DEVICE',
    # 'ssl': True,
    # 'proxy': 'http://proxy.example.com:8080',
    # 'auto_join_on_invite': True,
    
    # To enable End-to-End Encryption (E2EE), provide a path for the database store:
    # 'store_path': '/path/to/errbot/matrix_store'
}
```

### End-to-End Encryption (E2EE) Support
To use End-to-End Encryption in rooms, you must:
1. Ensure the `libolm` system library is installed (on macOS, `brew install libolm`; on Debian/Ubuntu, `apt-get install libolm-dev`).
2. Specify a `'store_path'` inside `BOT_IDENTITY` in `config.py` where `matrix-nio` can store its encryption keys.

## Running the Bot

Start Errbot normally:

```bash
errbot
```

## Publishing to PyPI

This project uses modern PEP 517/518 build standards. To publish the package to PyPI:

1. **Install build and upload tools**:
   ```bash
   pip install build twine
   ```

2. **Build the package distribution files**:
   ```bash
   python -m build
   ```
   This will generate a `.tar.gz` source archive and a `.whl` wheel file inside the `dist/` directory.

3. **Verify the built packages**:
   ```bash
   twine check dist/*
   ```

4. **Upload to PyPI**:
   ```bash
   twine upload dist/*
   ```
   *(Note: You will be prompted to enter your PyPI API token. Use `__token__` as the username and your token string starting with `pypi-` as the password).*
