notify-bridge/plans/entity-relationship-refactor/phase-3-command-entities-api.md

Phase 3: CommandConfig & CommandTracker CRUD API

Status: ⬜ Not Started Parent plan: 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