Metadata-Version: 2.4
Name: ki_mattermost
Version: 0.1.0
Summary: Typed Python client and CLI for self-hosted Mattermost (API v4)
Keywords: mattermost,mattermost-api,chat,httpx,cli,self-hosted
Author: aaraevskiy
Author-email: aaraevskiy <aaraevskiy@sberdevices.ru>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.13.5
Requires-Dist: pydantic-settings>=2.15.0
Requires-Dist: python-dotenv>=1.2.3
Requires-Python: >=3.14
Project-URL: Homepage, https://pypi.org/project/ki-mattermost/
Description-Content-Type: text/markdown

# ki_mattermost

Typed Python 3.14 client and CLI for self-hosted [Mattermost](https://mattermost.com/) (API v4).
Built with [uv](https://docs.astral.sh/uv/) and linted with [Ruff](https://docs.astral.sh/ruff/).

## Install

```bash
pip install ki_mattermost
# or
uv add ki_mattermost
```

## Features

- List teams and channels
- Read channel messages and threads
- Create new threads (root posts)
- Comment (reply) in threads
- Like / unlike posts via emoji reactions (`thumbsup` by default)

## Configuration

Set environment variables (or a local `.env`):

```bash
export MM_URL=https://mattermost.example.com
export MM_TOKEN=your-personal-access-token
# optional
export MM_TEAM_ID=
export MM_VERIFY_SSL=true
export MM_TIMEOUT=30
```

Create a **Personal Access Token** in Mattermost: *Profile → Security → Personal Access Tokens*
(or use a bot account token).

## CLI

After install, the `ki-mattermost` console script is available:

```bash
ki-mattermost whoami
ki-mattermost teams
ki-mattermost channels
ki-mattermost channels --team-id <TEAM_ID>

ki-mattermost posts <CHANNEL_ID> --flat
ki-mattermost thread <POST_ID> --flat

ki-mattermost create-thread <CHANNEL_ID> "Hello from API"
ki-mattermost comment <POST_ID> "Replying in thread"
ki-mattermost like <POST_ID>
ki-mattermost like <POST_ID> --emoji heart
ki-mattermost unlike <POST_ID>
ki-mattermost reactions <POST_ID>
```

## Library usage

```python
from ki_mattermost import MattermostClient, get_settings

with MattermostClient(get_settings()) as mm:
    channels = mm.list_channels()
    posts = mm.list_posts(channels[0].id)
    root = mm.create_thread(channels[0].id, "New thread")
    mm.comment(root.id, "First reply")
    mm.like(root.id)
```

## Environment

| Variable        | Required | Description                                 |
|-----------------|----------|---------------------------------------------|
| `MM_URL`        | yes      | Mattermost base URL                         |
| `MM_TOKEN`      | yes      | Bearer token                                |
| `MM_TEAM_ID`    | no       | Default team for channel listing            |
| `MM_VERIFY_SSL` | no       | TLS verify (`true`/`false`, default `true`) |
| `MM_TIMEOUT`    | no       | HTTP timeout seconds (default `30`)         |

## Development

```bash
uv sync
cp .env.example .env
uv run ruff check .
uv run ruff format .
uv run ki-mattermost --help
```

### Build & publish to PyPI

```bash
uv build
uv publish
# or with an explicit token:
# uv publish --token $UV_PUBLISH_TOKEN
```

Create an API token at <https://pypi.org/manage/account/token/>.
