Metadata-Version: 2.4
Name: xmpp-utilities
Version: 1.1.0
Author-email: Telepath <development@telepath.im>
License-Expression: Unlicense
Project-URL: Homepage, https://telepath.im/projects/xmpp-utilities/
Project-URL: Repository, https://foundry.fsky.io/telepath/xmpp-utilities.git
Project-URL: Issues, https://foundry.fsky.io/telepath/xmpp-utilities/issues
Keywords: xmpp,xmpp bot,slixmpp,bot
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Communications
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet :: XMPP
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dnspython>=2.8.0
Requires-Dist: slixmpp>=1.12.0
Dynamic: license-file

# XMPP Utilities

XMPP Utilities is a simple XMPP bot that provides various diagnostic and informational tools for XMPP entities and domains. It can be used to check software versions, service items, contact information, uptime, and more.

## Features

The bot responds to commands prefixed with `!xmpp` in both direct messages and configured Multi-User Chats (MUCs).

### Available Commands

- `!xmpp help` - Displays the help message with all available commands.
- `!xmpp version <jid>` - Shows the software version of an XMPP entity (XEP-0092).
- `!xmpp items <jid>` - Lists the service items of an XMPP entity (XEP-0030).
- `!xmpp contact <jid>` - Displays contact information for an XMPP entity (XEP-0030).
- `!xmpp info <jid>` - Lists the identities and features of an XMPP entity (XEP-0030).
- `!xmpp ping <jid>` - Pings an XMPP entity and reports the round-trip time (XEP-0199).
- `!xmpp uptime <jid>` - Shows the uptime of an XMPP entity (XEP-0012).
- `!xmpp srv <domain>` - Performs DNS SRV lookups for XMPP services (`_xmpp-client`, `_xmpp-server`, etc.).
- `!xmpp compliance <domain>` - Shows the compliance score of a server from [compliance.conversations.im](https://compliance.conversations.im/).

## Configuration

The bot is configured using environment variables. You can copy `.env.example` to `.env` and fill in your details:

```sh
cp .env.example .env
# Edit .env with your credentials
```

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `XMPP_UTILS_JID` | The JID of the bot account (e.g., `bot@example.com`). | Yes | - |
| `XMPP_UTILS_PASSWORD` | The password for the bot account. | Yes | - |
| `XMPP_UTILS_MUCS` | A comma-separated list of MUC JIDs to join. | No | - |
| `XMPP_UTILS_NICK` | The nickname to use in MUCs. | No | `XMPP Utilities` |

## Requirements

- Python 3.13+
- slixmpp
- dnspython

## Installation

### pip/pipx (PyPI)

You can install XMPP Utilities from PyPI with pip:

```sh
pip install xmpp-utilities
```

Or with pipx for an isolated environment:

```sh
pipx install xmpp-utilities
```

### pip/pipx (FSKY Foundry)

To download the package from FSKY Foundry instead of PyPI:

```sh
pip install xmpp-utilities --pip-args="--index-url https://foundry.fsky.io/api/packages/telepath/pypi/simple --extra-index-url https://pypi.org/simple"
```

Or with pipx:

```sh
pipx install xmpp-utilities --pip-args="--index-url https://foundry.fsky.io/api/packages/telepath/pypi/simple --extra-index-url https://pypi.org/simple"
```

### From wheel

Download the wheel from the [releases page](https://foundry.fsky.io/telepath/xmpp-utilities/releases) and install with pip:

```sh
pip install xmpp_utilities-*.whl
```

## Running

### Installed package

After installing, set the environment variables and run the bot:

```sh
export XMPP_UTILS_JID="xmpp-utilities@telepath.im"
export XMPP_UTILS_PASSWORD="your-password"
xmpp-utilities
```

### Local development

Requires [uv](https://github.com/astral-sh/uv).

1. Clone the repository:
   ```sh
   git clone https://foundry.fsky.io/telepath/xmpp-utilities.git
   cd xmpp-utilities
   ```

2. Install dependencies:
   ```sh
   uv sync
   ```

3. Set the environment variables and run the bot:
   ```sh
   export XMPP_UTILS_JID="xmpp-utilities@telepath.im"
   export XMPP_UTILS_PASSWORD="your-password"
   uv run xmpp-utilities
   ```

### Container (Docker/Podman)

A container image is available for this project.

```sh
podman run -d \
  --name xmpp-utilities \
  -e XMPP_UTILS_JID="xmpp-utilities@telepath.im" \
  -e XMPP_UTILS_PASSWORD="your-password" \
  foundry.fsky.io/telepath/xmpp-utilities:latest
```

### Systemd Quadlet

A Quadlet file is available at `contrib/quadlet/xmpp-utilities.container`. You can use it to manage the container via systemd.

Edit the file to suit your needs, place it into `~/.config/containers/systemd/` or `/etc/containers/systemd/`, and run:

```sh
systemctl --user daemon-reload
systemctl --user start xmpp-utilities
```

## License

This project is released into the public domain under the [Unlicense](LICENSE).
