Feat/ai jobs twitter drafts flags apikey audit

.env.example

@@ -152,6 +152,19 @@ MANIFEST_CACHE_TTL=300
 # Max allowed bytes for a single chunk upload (used by SongRoutes)
 CHUNK_UPLOAD_MAX_BYTES=8388608
 
+# ------------------ AI (see docs/AI_FEATURES.md, docs/adrs/007-ai-integration.md) ------------------
+# Concrete AI vendor behind the AiProvider interface. Only "noop" (default) is
+# implemented today — any other value logs a warning and falls back to noop.
+AI_PROVIDER=noop
+# Per-feature kill switches, independent of each other (default: all false/off)
+AI_FEATURE_TAGS_ENABLED=false
+AI_FEATURE_DESCRIPTIONS_ENABLED=false
+AI_FEATURE_COVER_ART_ENABLED=false
+AI_FEATURE_MODERATION_TRIAGE_ENABLED=false
+AI_FEATURE_SEARCH_ENABLED=false
+AI_FEATURE_PLAYLISTS_ENABLED=false
+AI_FEATURE_TWEET_DRAFTS_ENABLED=false
+
 # ------------------ Misc ------------------
 # Comma-separated list of allowed CORS origins for the API
 ALLOWED_ORIGINS=

docs/AI_FEATURES.md

@@ -43,6 +43,45 @@ and run on either the node process or the SQL database.
 ### 4. Recommendations / discovery
 - No collaborative-filtering or ML recommendation engine is present today.
 
+### 5. Async AI-assisted generation (cover art, descriptions)
+- **Where:** `src/services/ai/` (`AiProvider` interface, `NoopAiProvider`,
+  `AiGenerationService`), `src/workers/AiJobHandlers.ts`,
+  `POST /api/ai/songs/:songId/cover-art` and `/description`.
+- **What it does:** these routes queue a generation job via `JobQueueService`
+  instead of running it inline (cover art / description generation may be
+  slow), and announce completion via the existing webhook system as
+  `ai.generation.completed` (see `docs/WEBHOOK_IMPLEMENTATION_PLAN.md`).
+  The provider actually called is `NoopAiProvider` — a deterministic,
+  rule-based template, not a live model — until a real vendor is wired up
+  behind the `AiProvider` interface per ADR-007.
+- **Data sent:** none to third parties; the no-op provider makes no network
+  call. Only the song title (no audio, lyrics, or files) is used to build the
+  placeholder output, and only the generated output — never raw content — is
+  persisted, in `ai_generation_records`.
+- **Feature flags:** each AI feature is gated by its own env-var flag
+  (`src/config/aiFeatureFlags.ts`) rather than one global `AI_ENABLED` switch,
+  so a misbehaving feature can be disabled independently:
+  `AI_FEATURE_TAGS_ENABLED`, `AI_FEATURE_DESCRIPTIONS_ENABLED`,
+  `AI_FEATURE_COVER_ART_ENABLED`, `AI_FEATURE_MODERATION_TRIAGE_ENABLED`,
+  `AI_FEATURE_SEARCH_ENABLED`, `AI_FEATURE_PLAYLISTS_ENABLED`,
+  `AI_FEATURE_TWEET_DRAFTS_ENABLED`. All default OFF. `coverArt`,
+  `descriptions`, and `tweetDrafts` have a call site wired up today; the rest
+  are reserved for when those features are built.
+
+### 6. Release-announcement tweet drafts
+- **Where:** `src/services/TweetDraftService.ts`,
+  `POST /api/auth/twitter/draft`, `GET /api/auth/twitter/drafts`,
+  `POST /api/auth/twitter/draft/:id/approve`,
+  `DELETE /api/auth/twitter/draft/:id`.
+- **What it does:** drafts announcement text for a release via the same
+  `AiProvider` abstraction, stored as a `pending_review` `TweetDraft` for the
+  artist to review. Approving a draft only marks it reviewed — AudioBlock
+  does not post to Twitter on the artist's behalf, because `twitterRoutes.ts`
+  deliberately never persists a Twitter access/refresh token (see the
+  `/callback` handler there); the artist copies the approved text and posts
+  it themselves.
+- **Data sent:** none to third parties; gated by `AI_FEATURE_TWEET_DRAFTS_ENABLED`.
+
 ---
 
 ## What data is sent to third-party providers (non-AI)

docs/WEBHOOK_IMPLEMENTATION_PLAN.md

@@ -1,8 +1,17 @@
 # Webhook & Event System Implementation Plan
 
-## Status: NOT YET IMPLEMENTED ⚠️
-
-This document outlines the planned implementation for asynchronous event delivery to frontends. The webhook/event system is currently **not implemented** - frontends must use polling as a temporary workaround.
+## Status: Phase 3 (HTTP webhook delivery) implemented
+
+This document originally outlined the planned implementation for asynchronous
+event delivery to frontends. **Phase 3 — HTTP webhook delivery with
+HMAC-SHA256 signing and exponential-backoff retries — is now implemented**:
+see `WebhookService` (`src/services/WebhookService.ts`), its subscription
+routes (`src/routes/webhookRoutes.ts`, `POST /api/webhooks/register`), and
+`src/types/WebhookPayloads.ts` for the current payload shapes (including
+`ai.generation.completed`, emitted by the async AI generation jobs described
+in `docs/AI_FEATURES.md`). Phases 2 (WebSocket server) and 4 (event
+persistence/replay API) below remain **not implemented** — frontends without
+a registered webhook endpoint still need to poll for those event types.
 
 ## Current Workaround (Polling)