# Phase 3: CommandConfig & CommandTracker CRUD API

**Status:** ⬜ Not Started
**Parent plan:** [PLAN.md](./PLAN.md)
**Domain:** backend

## Objective
Create full CRUD API routes for CommandConfig, CommandTracker, and CommandTrackerListener
management. These endpoints let users create command configurations (scoped to provider type),
create command trackers that link a provider to a command config, and attach/detach listeners
(telegram bots) to command trackers.

## Tasks

- [ ] Task 1: Create `api/command_configs.py` with CRUD routes:
  - `GET /api/command-configs` — list all for current user (+ system defaults with user_id=0)
  - `POST /api/command-configs` — create new (validate provider_type, enabled_commands against registry)
  - `GET /api/command-configs/{id}` — get single
  - `PUT /api/command-configs/{id}` — update (validate ownership)
  - `DELETE /api/command-configs/{id}` — delete (check not in use by any command tracker)
  - Response should include all fields: id, user_id, provider_type, name, icon, enabled_commands, locale, response_mode, default_count, rate_limits, created_at

- [ ] Task 2: Create `api/command_trackers.py` with CRUD routes:
  - `GET /api/command-trackers` — list all for current user, include linked listeners count
  - `POST /api/command-trackers` — create new (validate provider_id exists, command_config_id exists, provider_type matches between provider and config)
  - `GET /api/command-trackers/{id}` — get single with listeners
  - `PUT /api/command-trackers/{id}` — update (name, icon, enabled, command_config_id — validate provider_type match)
  - `DELETE /api/command-trackers/{id}` — delete (cascade delete listeners)
  - `POST /api/command-trackers/{id}/enable` — enable
  - `POST /api/command-trackers/{id}/disable` — disable

- [ ] Task 3: Add listener management endpoints to command_trackers.py:
  - `GET /api/command-trackers/{id}/listeners` — list listeners for a command tracker
  - `POST /api/command-trackers/{id}/listeners` — add listener (body: {listener_type, listener_id}). Validate: listener exists (e.g., TelegramBot with that ID), no duplicate (unique constraint), user owns the listener.
  - `DELETE /api/command-trackers/{id}/listeners/{listener_id}` — remove listener

- [ ] Task 4: Add validation helpers:
  - Validate `enabled_commands` against `commands/registry.py` known commands for the given provider_type
  - Validate `provider_type` match: CommandConfig.provider_type must match ServiceProvider.type of the CommandTracker's provider
  - Validate listener ownership: user must own the TelegramBot being attached

- [ ] Task 5: Register new routers in `main.py`

- [ ] Task 6: Update `api/telegram_bots.py` — remove the commands config endpoints (POST `/telegram-bots/{id}/commands`, GET `/telegram-bots/{id}/commands`) since commands config now lives in CommandConfig entity. Keep the sync-commands endpoint but update it to accept a command_config_id parameter or read from command trackers.

## Files to Modify/Create
- `packages/server/src/notify_bridge_server/api/command_configs.py` — new file
- `packages/server/src/notify_bridge_server/api/command_trackers.py` — new file
- `packages/server/src/notify_bridge_server/main.py` — register new routers
- `packages/server/src/notify_bridge_server/api/telegram_bots.py` — remove old commands config endpoints

## Acceptance Criteria
- Full CRUD for CommandConfig with provider_type validation
- Full CRUD for CommandTracker with provider↔config type matching
- Listener add/remove with ownership validation and uniqueness
- Old telegram bot commands config endpoints removed
- Server starts and all new endpoints respond correctly

## Notes
- The command registry currently defines commands globally. In future, commands could be provider-scoped. For now, validate enabled_commands against the flat registry list.
- CommandConfig with user_id=0 could serve as system defaults (like TemplateConfig), but this is optional for Phase 3.
- The sync-commands endpoint on TelegramBot may need to resolve which commands to sync from attached CommandTrackers — this is wired up in Phase 4.

## Review Checklist
- [ ] All tasks completed
- [ ] Code follows project conventions
- [ ] No unintended side effects
- [ ] Build passes
- [ ] Tests pass (new + existing)

## Handoff to Next Phase
<!-- Filled in by the implementation agent after completing this phase. -->