Marko (Hermes Implementer)
6dac5d225e
Add TrelloClient for Trello REST API interaction with env-var-based credential management (TRELLO_API_KEY, TRELLO_TOKEN). Implements: - trello_verify_credentials — verify API key/token against Trello API - trello_list_boards — list accessible Trello boards - trello_disconnect — clear in-memory credentials Includes full test suite (18 tests), spec document, and plugin metadata. Issue: #1
111 lines
3.6 KiB
Markdown
111 lines
3.6 KiB
Markdown
# Trello Plugin — Authentication & Connection
|
|
|
|
**Feature:** US: Authenticate and Connect to Trello Account
|
|
**Issue:** #1
|
|
**Branch:** `feature/trello-auth`
|
|
|
|
## 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. 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. Set TRELLO_API_KEY and TRELLO_TOKEN again to reconnect."
|
|
}
|
|
```
|
|
|
|
## API Contract
|
|
|
|
### Internal: `TrelloClient`
|
|
|
|
```python
|
|
class TrelloClient:
|
|
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
|
|
```
|
|
|
|
### 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 |