Marko (Hermes Implementer)
eec481c528
Rename docs/backend/*.md to Django-migration-style naming: trello-auth-spec.md → 001_trello_auth_spec.md (Issue #1) manage-boards-spec.md → 002_manage_boards_spec.md (Issue #2) manage-lists-spec.md → 003_manage_lists_spec.md (Issue #3) manage-cards-spec.md → 004_manage_cards_spec.md (Issue #4) Each doc now includes a **Doc:** field with its sequence number.
119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
# Trello Plugin — Authentication & Connection
|
|
|
|
**Feature:** US: Authenticate and Connect to Trello Account
|
|
**Issue:** #1
|
|
**Branch:** `feature/trello-auth`
|
|
**Doc:** 001
|
|
|
|
## Overview
|
|
|
|
This feature provides the authentication layer for the Trello plugin. Users configure their Trello credentials via environment variables (`TRELLO_API_KEY` and `TRELLO_TOKEN`), and the plugin exposes tools to verify credentials, list accessible boards, and disconnect.
|
|
|
|
## Design Decisions
|
|
|
|
- **No interactive credential input** — The Hermes Agent has no UI for prompting users. Credentials are set in the profile's `.env` or `config.yaml` as environment variables, which is the standard Hermes pattern.
|
|
- **Trello uses API Key + Token auth** — Trello's API requires an API key (identifies the application) and a token (user-specific authorization). Both are required for any API call.
|
|
- **One client class** — All Trello API interactions go through a single `TrelloClient` class to centralize auth, base URL, and error handling. Future features (boards, lists, cards) will extend this same client.
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Required | Description |
|
|
|----------|----------|-------------|
|
|
| `TRELLO_API_KEY` | Yes | Trello API application key |
|
|
| `TRELLO_TOKEN` | Yes | Trello user authorization token |
|
|
|
|
## Tools Exposed
|
|
|
|
### 1. `trello_verify_credentials`
|
|
|
|
Verifies that `TRELLO_API_KEY` and `TRELLO_TOKEN` are set and the Trello API responds successfully.
|
|
|
|
**Parameters:** None
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "✓ Trello credentials verified successfully (authenticated as user@example.com)"
|
|
}
|
|
```
|
|
|
|
On failure:
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "✗ Trello authentication failed: invalid key"
|
|
}
|
|
```
|
|
|
|
### 2. `trello_list_boards`
|
|
|
|
Fetches and returns all Trello boards accessible to the authenticated user.
|
|
|
|
**Parameters:** None
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"boards": [
|
|
{"id": "abc123", "name": "My Project Board", "url": "https://trello.com/b/abc123"},
|
|
{"id": "def456", "name": "Personal Tasks", "url": "https://trello.com/b/def456"}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 3. `trello_disconnect`
|
|
|
|
Clears the stored credentials from memory. Since credentials are stored in environment variables, the next tool call will automatically re-read them and reconnect. To fully disconnect, also unset ``TRELLO_API_KEY`` and ``TRELLO_TOKEN`` from the Hermes profile config.
|
|
|
|
Note: this does NOT revoke the Trello token — the user must invalidate it via Trello's settings if needed.
|
|
|
|
**Parameters:** None
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Trello credentials cleared from memory. Next tool call will re-read TRELLO_API_KEY and TRELLO_TOKEN from environment and reconnect automatically."
|
|
}
|
|
```
|
|
|
|
## API Contract
|
|
|
|
### Internal: `TrelloClient`
|
|
|
|
```python
|
|
class TrelloClient:
|
|
api_key: str
|
|
token: str
|
|
|
|
def __init__(self, api_key: str | None = None, token: str | None = None)
|
|
|
|
def verify_credentials(self) -> dict
|
|
def list_boards(self) -> list[dict]
|
|
def disconnect(self) -> dict
|
|
```
|
|
|
|
The client uses `TypedDict` response contracts (`SuccessResponse`/`ErrorResponse`) with a `TypeGuard` helper `_is_success()` for type-safe narrowing. Internal helpers include `_request()`, `_get()`, `_post()`, `_put()`, `_check_credentials()`, and `_handle_http_error()`.
|
|
|
|
### Trello API Endpoints Used
|
|
|
|
| Purpose | Method | Endpoint | Docs |
|
|
|---------|--------|----------|------|
|
|
| Verify credentials | GET | `/1/members/me` | https://developer.atlassian.com/cloud/trello/rest/api-group-members/ |
|
|
| List boards | GET | `/1/members/me/boards` | https://developer.atlassian.com/cloud/trello/rest/api-group-boards/ |
|
|
|
|
## Error Handling
|
|
|
|
- Missing env vars → return `{"success": false, "message": "TRELLO_API_KEY and TRELLO_TOKEN must be set"}` with env var name
|
|
- Network errors → catch `requests.exceptions.RequestException` and return descriptive message
|
|
- Auth failures (401/403) → clear message about invalid credentials
|
|
- Rate limiting → Trello returns 429; surface the retry-after header
|
|
|
|
## Testing
|
|
|
|
- Unit tests with mocked HTTP responses
|
|
- Test all error paths: missing creds, invalid creds, network error, rate limit
|
|
- Test successful verification via mock that returns member info
|
|
- Test board listing with mock JSON response |