docs: rename spec docs to migration-style numbering
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.
This commit is contained in:
@@ -0,0 +1,119 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user