feat: add content-creation API endpoints and video persistence (#259)

* feat(content): add create-content API flow and run video hydration

* fix: address code review feedback on content-creation endpoints

- fix: z.coerce.boolean() treated 'false' as true in estimate query params
- fix: remove account_id from create content body (derive from auth only)
- fix: missing field now returns only required issues, not all issues
- fix: make video hydration best-effort so GET /tasks/runs doesn't crash
- refactor: derive DEFAULT_CONTENT_TEMPLATE from CONTENT_TEMPLATES array (DRY)
- refactor: export getContentValidateQuerySchema for reuse

* refactor: make config.json optional with sensible pipeline defaults

- config/content-creation/config.json is now 'recommended' not 'required'
- artists only need face-guide.png + at least one .mp3 to be ready
- pipeline will use default model/resolution settings if no config exists
- add test for config-optional readiness check

* feat: pass githubRepo to create-content task payload

- extend TriggerCreateContentPayload with githubRepo field
- getArtistContentReadiness now returns githubRepo
- createContentHandler passes githubRepo when triggering task

* feat: add caption_length param to content creation endpoint

- add caption_length (short/medium/long) to request schema, defaults to short
- pass through to task payload
- restore proper validation flow in handler
- update tests

* feat: add upscale param to content creation endpoint

* fix: validation now searches org submodule repos for artist files

- getArtistContentReadiness checks main repo first, falls back to org repos
- reads .gitmodules to discover org submodule URLs
- gatsby-grace now validates as ready=true

* feat: add batch mode — trigger N videos in parallel

- add batch param (1-30, default 1)
- batch mode returns { runIds: [...] } instead of { runId }
- each task runs independently with its own random selections

* refactor: extract getOrgRepoUrls to shared lib/github/ (DRY)

- move inline getOrgRepoUrls from getArtistContentReadiness into lib/github/
- reuse existing getRepoGitModules + parseGitModules instead of duplicating
- getArtistContentReadiness now imports the shared utility

* fix: address CodeRabbit review feedback (round 2)

- rename misleading 'missing_fields' to 'field' in validation error response
- don't expose internal error messages in 500 responses (security)
- log errors server-side, return generic message to clients

* fix: address all remaining CodeRabbit review comments

- distinguish 'no repo configured' vs 'query failed' in readiness check
- sanitize 500 error in validate handler (don't expose internals)
- make persistence idempotent (re-select on insert race condition)
- fix Zod .optional().default() ordering for correct behavior
- batch mode uses Promise.allSettled (partial failures return successful runIds)
- getOrgRepoUrls accepts configurable branch param

* fix: resolve TypeScript build error in batch mode filter

* refactor: always return runIds array (KISS — one response shape)

Per reviewer feedback: single mode and batch mode now both return
runIds array. Removes the runId/runIds split. Clients always handle
one shape.

* refactor: extract helpers into separate files for SRP

- getArtistRootPrefix → lib/content/getArtistRootPrefix.ts
- getArtistFileTree → lib/content/getArtistFileTree.ts
- isCompletedRun + TriggerRunLike → lib/content/isCompletedRun.ts
- booleanFromString → lib/content/booleanFromString.ts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add artist_account_id support to content endpoints

- POST /api/content/create accepts artist_account_id OR artist_slug
- GET /api/content/validate accepts artist_account_id OR artist_slug
- resolveArtistSlug looks up artist name from accounts table, converts to slug
- matches docs contract (either identifier works)
- 404 if artist_account_id not found, 400 if neither provided

* refactor: use artist_account_id only, remove artist_slug (KISS)

Per reviewer feedback: one ID system, not two.
- artist_account_id is the only accepted identifier
- API resolves account_id → name → slug internally
- removes artist_slug from create and validate schemas
- matches how the rest of the Recoup platform works

* fix: use GitHub Contents API for .gitmodules (works for private repos)

raw.githubusercontent.com returns 404 for private repos.
Switched to api.github.com/repos/.../contents/ which works with Bearer token.

* fix: make validation best-effort so submodule artists aren't blocked

Validation can't reliably see files in org submodule repos (private repo
GitHub API limitations). The task has its own submodule-aware file discovery.
Validation now warns but doesn't block — task fails with clear error if
files are actually missing.

* refactor: remove account_id, use artist_account_id in content responses

- Add artistAccountId to validated types and pass through handlers
- Replace artist_slug with artist_account_id in API responses
- artistSlug remains as internal impl detail for file system paths
- Update all content tests to match

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: top-level import for selectAccountSnapshots, install @chat-adapter/whatsapp

- Move dynamic import to static top-level import in createContentHandler
- Add proper mock in test instead of relying on dynamic import workaround
- Install missing @chat-adapter/whatsapp package (fixes pre-existing test failure)

All 1460 tests passing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: handle empty repo (409) gracefully in content validation

- Return ready=false instead of throwing when repo tree is null
- Add repo/branch context to GitHub API error logs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: strip internal githubRepo from content validate response

Prevents leaking the internal GitHub repository URL in the public API
response by destructuring it out before serializing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* revert: remove video hydration from getTaskRunHandler

Decouples run status checks from video storage uploads. Video
persistence will be handled separately in a future iteration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Sweets Sweetman <sweetmantech@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

app/api/content/create/route.ts

@@ -0,0 +1,32 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { createContentHandler } from "@/lib/content/createContentHandler";
+
+/**
+ * OPTIONS handler for CORS preflight requests.
+ *
+ * @returns Empty 204 response with CORS headers.
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 204,
+    headers: getCorsHeaders(),
+  });
+}
+
+/**
+ * POST /api/content/create
+ *
+ * Triggers the background content-creation pipeline and returns a run ID.
+ *
+ * @param request - Incoming API request.
+ * @returns Trigger response for the created task run.
+ */
+export async function POST(request: NextRequest): Promise<NextResponse> {
+  return createContentHandler(request);
+}
+
+export const dynamic = "force-dynamic";
+export const fetchCache = "force-no-store";
+export const revalidate = 0;
+

app/api/content/estimate/route.ts

@@ -0,0 +1,32 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getContentEstimateHandler } from "@/lib/content/getContentEstimateHandler";
+
+/**
+ * OPTIONS handler for CORS preflight requests.
+ *
+ * @returns Empty 204 response with CORS headers.
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 204,
+    headers: getCorsHeaders(),
+  });
+}
+
+/**
+ * GET /api/content/estimate
+ *
+ * Returns estimated content-creation costs.
+ *
+ * @param request - Incoming API request.
+ * @returns Cost estimate response.
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  return getContentEstimateHandler(request);
+}
+
+export const dynamic = "force-dynamic";
+export const fetchCache = "force-no-store";
+export const revalidate = 0;
+

app/api/content/templates/route.ts

@@ -0,0 +1,32 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getContentTemplatesHandler } from "@/lib/content/getContentTemplatesHandler";
+
+/**
+ * OPTIONS handler for CORS preflight requests.
+ *
+ * @returns Empty 204 response with CORS headers.
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 204,
+    headers: getCorsHeaders(),
+  });
+}
+
+/**
+ * GET /api/content/templates
+ *
+ * Lists available templates for the content-creation pipeline.
+ *
+ * @param request - Incoming API request.
+ * @returns Template list response.
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  return getContentTemplatesHandler(request);
+}
+
+export const dynamic = "force-dynamic";
+export const fetchCache = "force-no-store";
+export const revalidate = 0;
+

app/api/content/validate/route.ts

@@ -0,0 +1,32 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getContentValidateHandler } from "@/lib/content/getContentValidateHandler";
+
+/**
+ * OPTIONS handler for CORS preflight requests.
+ *
+ * @returns Empty 204 response with CORS headers.
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 204,
+    headers: getCorsHeaders(),
+  });
+}
+
+/**
+ * GET /api/content/validate
+ *
+ * Validates whether an artist is ready for content creation.
+ *
+ * @param request - Incoming API request.
+ * @returns Artist readiness response.
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  return getContentValidateHandler(request);
+}
+
+export const dynamic = "force-dynamic";
+export const fetchCache = "force-no-store";
+export const revalidate = 0;
+

lib/const.ts

@@ -22,6 +22,7 @@ export const OUTBOUND_EMAIL_DOMAIN = "@recoupable.com";
 export const RECOUP_FROM_EMAIL = `Agent by Recoup <agent${OUTBOUND_EMAIL_DOMAIN}>`;
 
 export const SUPABASE_STORAGE_BUCKET = "user-files";
+export const CREATE_CONTENT_TASK_ID = "create-content";
 
 /**
  * UUID of the Recoup admin organization.
@@ -41,10 +42,4 @@ export const SNAPSHOT_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000;
 // EVALS
 export const EVAL_ACCOUNT_ID = "fb678396-a68f-4294-ae50-b8cacf9ce77b";
 export const EVAL_ACCESS_TOKEN = process.env.EVAL_ACCESS_TOKEN || "";
-export const EVAL_ARTISTS = [
-  "Gliiico",
-  "Mac Miller",
-  "Wiz Khalifa",
-  "Mod Sun",
-  "Julius Black",
-];
+export const EVAL_ARTISTS = ["Gliiico", "Mac Miller", "Wiz Khalifa", "Mod Sun", "Julius Black"];

lib/content/__tests__/createContentHandler.test.ts

@@ -0,0 +1,131 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { NextRequest, NextResponse } from "next/server";
+import { createContentHandler } from "@/lib/content/createContentHandler";
+import { validateCreateContentBody } from "@/lib/content/validateCreateContentBody";
+import { triggerCreateContent } from "@/lib/trigger/triggerCreateContent";
+import { getArtistContentReadiness } from "@/lib/content/getArtistContentReadiness";
+
+vi.mock("@/lib/networking/getCorsHeaders", () => ({
+  getCorsHeaders: vi.fn(() => ({ "Access-Control-Allow-Origin": "*" })),
+}));
+
+vi.mock("@/lib/content/validateCreateContentBody", () => ({
+  validateCreateContentBody: vi.fn(),
+}));
+
+vi.mock("@/lib/trigger/triggerCreateContent", () => ({
+  triggerCreateContent: vi.fn(),
+}));
+
+vi.mock("@/lib/content/getArtistContentReadiness", () => ({
+  getArtistContentReadiness: vi.fn(),
+}));
+
+vi.mock("@/lib/supabase/account_snapshots/selectAccountSnapshots", () => ({
+  selectAccountSnapshots: vi.fn(),
+}));
+
+describe("createContentHandler", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(getArtistContentReadiness).mockResolvedValue({
+      artist_account_id: "art_456",
+      ready: true,
+      missing: [],
+      warnings: [],
+      githubRepo: "https://github.com/test/repo",
+    });
+  });
+
+  it("returns validation/auth error when validation fails", async () => {
+    const errorResponse = NextResponse.json(
+      { status: "error", error: "Unauthorized" },
+      { status: 401 },
+    );
+    vi.mocked(validateCreateContentBody).mockResolvedValue(errorResponse);
+    const request = new NextRequest("http://localhost/api/content/create", { method: "POST" });
+
+    const result = await createContentHandler(request);
+
+    expect(result).toBe(errorResponse);
+  });
+
+  it("returns 202 with runIds when trigger succeeds", async () => {
+    vi.mocked(validateCreateContentBody).mockResolvedValue({
+      accountId: "acc_123",
+      artistAccountId: "art_456",
+      artistSlug: "gatsby-grace",
+      template: "artist-caption-bedroom",
+      lipsync: false,
+      captionLength: "short",
+      upscale: false,
+      batch: 1,
+    });
+    vi.mocked(triggerCreateContent).mockResolvedValue({ id: "run_abc123" } as never);
+    const request = new NextRequest("http://localhost/api/content/create", { method: "POST" });
+
+    const result = await createContentHandler(request);
+    const body = await result.json();
+
+    expect(result.status).toBe(202);
+    expect(body.runIds).toEqual(["run_abc123"]);
+    expect(body.status).toBe("triggered");
+    expect(body.artist_account_id).toBe("art_456");
+  });
+
+  it("returns 202 with empty runIds and failed count when trigger fails", async () => {
+    vi.mocked(validateCreateContentBody).mockResolvedValue({
+      accountId: "acc_123",
+      artistAccountId: "art_456",
+      artistSlug: "gatsby-grace",
+      template: "artist-caption-bedroom",
+      lipsync: false,
+      captionLength: "short",
+      upscale: false,
+      batch: 1,
+    });
+    vi.mocked(triggerCreateContent).mockRejectedValue(new Error("Trigger unavailable"));
+    const request = new NextRequest("http://localhost/api/content/create", { method: "POST" });
+
+    const result = await createContentHandler(request);
+    const body = await result.json();
+
+    expect(result.status).toBe(202);
+    expect(body.runIds).toEqual([]);
+    expect(body.failed).toBe(1);
+  });
+
+  it("still triggers when readiness check finds missing files (best-effort)", async () => {
+    vi.mocked(validateCreateContentBody).mockResolvedValue({
+      accountId: "acc_123",
+      artistAccountId: "art_456",
+      artistSlug: "gatsby-grace",
+      template: "artist-caption-bedroom",
+      lipsync: false,
+      captionLength: "short",
+      upscale: false,
+      batch: 1,
+    });
+    vi.mocked(getArtistContentReadiness).mockResolvedValue({
+      artist_account_id: "art_456",
+      ready: false,
+      missing: [
+        {
+          file: "context/images/face-guide.png",
+          severity: "required",
+          fix: "Generate a face guide image before creating content.",
+        },
+      ],
+      warnings: [],
+    });
+    const request = new NextRequest("http://localhost/api/content/create", { method: "POST" });
+
+    const result = await createContentHandler(request);
+    const body = await result.json();
+
+    // Best-effort: validation doesn't block, task handles its own file discovery
+    expect(result.status).toBe(202);
+    expect(body.runIds).toBeDefined();
+  });
+});
+

lib/content/__tests__/getArtistContentReadiness.test.ts

@@ -0,0 +1,89 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getArtistContentReadiness } from "@/lib/content/getArtistContentReadiness";
+import { selectAccountSnapshots } from "@/lib/supabase/account_snapshots/selectAccountSnapshots";
+import { getRepoFileTree } from "@/lib/github/getRepoFileTree";
+
+vi.mock("@/lib/supabase/account_snapshots/selectAccountSnapshots", () => ({
+  selectAccountSnapshots: vi.fn(),
+}));
+
+vi.mock("@/lib/github/getRepoFileTree", () => ({
+  getRepoFileTree: vi.fn(),
+}));
+
+describe("getArtistContentReadiness", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(selectAccountSnapshots).mockResolvedValue([
+      {
+        github_repo: "https://github.com/test-org/test-repo",
+      },
+    ] as never);
+  });
+
+  it("returns ready=true when required files exist", async () => {
+    vi.mocked(getRepoFileTree).mockResolvedValue([
+      { path: "artists/gatsby-grace/context/images/face-guide.png", type: "blob", sha: "1" },
+      { path: "artists/gatsby-grace/config/content-creation/config.json", type: "blob", sha: "2" },
+      { path: "artists/gatsby-grace/songs/song-a.mp3", type: "blob", sha: "3" },
+      { path: "artists/gatsby-grace/context/artist.md", type: "blob", sha: "4" },
+      { path: "artists/gatsby-grace/context/audience.md", type: "blob", sha: "5" },
+      { path: "artists/gatsby-grace/context/era.json", type: "blob", sha: "6" },
+    ]);
+
+    const result = await getArtistContentReadiness({
+      accountId: "acc_123",
+      artistAccountId: "art_456",
+      artistSlug: "gatsby-grace",
+    });
+
+    expect(result.ready).toBe(true);
+    expect(result.missing).toEqual([]);
+  });
+
+  it("returns ready=false with required issues when core files are missing", async () => {
+    vi.mocked(getRepoFileTree).mockResolvedValue([
+      { path: "artists/gatsby-grace/context/artist.md", type: "blob", sha: "1" },
+    ]);
+
+    const result = await getArtistContentReadiness({
+      accountId: "acc_123",
+      artistAccountId: "art_456",
+      artistSlug: "gatsby-grace",
+    });
+
+    expect(result.ready).toBe(false);
+    expect(result.missing.some(item => item.file === "context/images/face-guide.png")).toBe(true);
+    expect(result.missing.some(item => item.file === "songs/*.mp3")).toBe(true);
+  });
+
+  it("returns ready=true when only face-guide and mp3 exist (config.json is optional)", async () => {
+    vi.mocked(getRepoFileTree).mockResolvedValue([
+      { path: "artists/gatsby-grace/context/images/face-guide.png", type: "blob", sha: "1" },
+      { path: "artists/gatsby-grace/songs/track.mp3", type: "blob", sha: "2" },
+    ]);
+
+    const result = await getArtistContentReadiness({
+      accountId: "acc_123",
+      artistAccountId: "art_456",
+      artistSlug: "gatsby-grace",
+    });
+
+    expect(result.ready).toBe(true);
+    expect(result.missing).toEqual([]);
+    // config.json appears as a warning, not a blocker
+    expect(result.warnings.some(item => item.file === "config/content-creation/config.json")).toBe(true);
+  });
+
+  it("throws when account has no github repo", async () => {
+    vi.mocked(selectAccountSnapshots).mockResolvedValue([] as never);
+
+    await expect(
+      getArtistContentReadiness({
+        accountId: "acc_123",
+        artistSlug: "gatsby-grace",
+      }),
+    ).rejects.toThrow("No GitHub repository configured for this account");
+  });
+});
+