Backend: AI generation endpoints (Gemini nano-banana + Veo)

Server-side proxy so the Google API key (from Infisical) never reaches the
client. Behind an AiClient trait with a fake for headless tests.

- ai.rs: GeminiClient — refine prompt (gemini-2.5-flash), generate image
  (gemini-2.5-flash-image / "nano-banana"), and async video (veo-2.0:
  predictLongRunning → poll → proxy the redirecting download). DisabledAiClient
  when no key is configured.
- POST /v1/ai/refine, /v1/ai/image (rate-limited 60/h, 20/h)
- POST /v1/ai/video (submit, 5/h) + /v1/ai/video/status (poll → base64 mp4)
- config: GEMINI_API_KEY via SecretSource
- 5 endpoint/parse tests; full workspace gate green (114 tests)

Live-verified: refine + nano-banana return through the proxy; Veo submits,
polls to done in ~60s, and streams back a valid mp4.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

cardclaws-backend/crates/cardclaws-api/tests/ai_test.rs

@@ -0,0 +1,93 @@
+//! AI generator endpoints (PRD §21 Phase 5). Uses the fake AI client; a live
+//! Gemini/nano-banana run is exercised manually with a real key.
+
+mod common;
+
+use axum::http::StatusCode;
+use serde_json::json;
+
+#[tokio::test]
+async fn refine_returns_a_prompt() {
+    let app = require_app!();
+    let (status, body) = app
+        .request(
+            "POST",
+            "/v1/ai/refine",
+            None,
+            Some(json!({ "scene": "neon Tokyo street", "style": "Cinematic", "mood": "Bold" })),
+        )
+        .await;
+    assert_eq!(status, StatusCode::OK);
+    let prompt = body["prompt"].as_str().unwrap();
+    assert!(prompt.contains("neon Tokyo street"));
+}
+
+#[tokio::test]
+async fn refine_requires_a_scene() {
+    let app = require_app!();
+    let (status, body) = app
+        .request(
+            "POST",
+            "/v1/ai/refine",
+            None,
+            Some(json!({ "scene": "   " })),
+        )
+        .await;
+    assert_eq!(status, StatusCode::BAD_REQUEST);
+    assert_eq!(body["code"], "validation");
+}
+
+#[tokio::test]
+async fn image_returns_base64_png() {
+    let app = require_app!();
+    let (status, body) = app
+        .request(
+            "POST",
+            "/v1/ai/image",
+            None,
+            Some(json!({ "prompt": "a cinematic neon street" })),
+        )
+        .await;
+    assert_eq!(status, StatusCode::OK);
+    assert_eq!(body["mimeType"], "image/png");
+    assert!(!body["imageBase64"].as_str().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn video_submit_then_poll_returns_clip() {
+    let app = require_app!();
+    let (status, body) = app
+        .request(
+            "POST",
+            "/v1/ai/video",
+            None,
+            Some(json!({ "prompt": "a calm forest at dawn" })),
+        )
+        .await;
+    assert_eq!(status, StatusCode::OK);
+    let op = body["operationId"].as_str().unwrap().to_string();
+    assert!(!op.is_empty());
+
+    let (status, body) = app
+        .request(
+            "POST",
+            "/v1/ai/video/status",
+            None,
+            Some(json!({ "operationId": op })),
+        )
+        .await;
+    assert_eq!(status, StatusCode::OK);
+    assert_eq!(body["status"], "done");
+    assert_eq!(body["mimeType"], "video/mp4");
+    assert!(!body["videoBase64"].as_str().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn video_requires_a_prompt() {
+    let app = require_app!();
+    let (status, body) = app
+        .request("POST", "/v1/ai/video", None, Some(json!({ "prompt": "" })))
+        .await;
+    assert_eq!(status, StatusCode::BAD_REQUEST);
+    assert_eq!(body["code"], "validation");
+}

cardclaws-backend/crates/cardclaws-api/tests/common/mod.rs

@@ -18,6 +18,7 @@ use http_body_util::BodyExt;
 use serde_json::Value;
 use tower::ServiceExt;
 
+use cardclaws_api::ai::FakeAiClient;
 use cardclaws_api::assets::InMemoryStore;
 use cardclaws_api::cache::InMemoryCache;
 use cardclaws_api::email::CapturingEmailSender;
@@ -84,6 +85,7 @@ pub async fn try_setup() -> Option<TestApp> {
         email: email.clone(),
         assets: assets.clone(),
         geo: Arc::new(FakeGeo),
+        ai: Arc::new(FakeAiClient),
         jwt: JwtKeys::new("test-jwt-secret"),
         apple: Arc::new(NoopApple),
         apple_audience: "com.cardclaws.test".into(),