Background Tasks (Trigger.dev)

Relevant source files

The following files were used as context for generating this wiki page:

• lib/trigger/triggerCreateContent.ts
• lib/trigger/tests/triggerCreateContent.test.ts
• lib/tasks/tests/enrichTaskWithTriggerInfo.test.ts
• lib/tasks/tests/deleteTask.test.ts
• lib/coding-agent/tests/handleGitHubWebhook.test.ts
• CLAUDE.md
• README.md

Background tasks in the Recoup API are managed using Trigger.dev, a platform for orchestrating long-running jobs, scheduled tasks, and complex workflows. This system offloads intensive operations—such as content generation, PR updates, and automated scheduled actions—from the main API request-response cycle to ensure high availability and performance.

The integration utilizes the @trigger.dev/sdk to trigger tasks, manage schedules, and poll for completion status. Tasks are typically initiated via domain-specific "trigger" functions located in the lib/trigger/ directory, which provide a typed interface for payload submission.

Sources: CLAUDE.md:18-24, README.md:130-145, lib/trigger/triggerCreateContent.ts

System Architecture

The background task architecture follows a producer-consumer pattern where the API acts as the producer, submitting task requests to Trigger.dev. Trigger.dev then executes the business logic and optionally communicates results back via callback URLs or status polling.

Core Task Types

The system handles several categories of background operations, categorized by their trigger mechanism and business domain.

Content Generation

One of the primary uses of background tasks is the CREATE_CONTENT_TASK. This task handles the computationally expensive process of generating media content, including optional lipsyncing and upscaling.

Field	Type	Description
accountId	string	The ID of the account initiating the request.
artistSlug	string	Unique identifier for the artist.
template	string	The content template to apply.
lipsync	boolean	Whether to enable lipsync processing.
upscale	boolean	Whether to upscale media for higher quality.
githubRepo	string	Repository URL for fetching artist context files.

Sources: lib/trigger/triggerCreateContent.ts:4-18, lib/trigger/tests/triggerCreateContent.test.ts:16-25

Coding Agent & GitHub Integration

The update-pr task is used by the coding agent to handle automated PR modifications. When a GitHub webhook (e.g., a comment mentioning the agent) is received, the system triggers a background task to process the feedback and update the code.

Task Life Cycle Management

Triggering Tasks

Tasks are triggered using specific helper functions that wrap the tasks.trigger method from the SDK. This ensures that the CREATE_CONTENT_TASK_ID and other constants are applied correctly.

// Example from lib/trigger/triggerCreateContent.ts
export async function triggerCreateContent(payload: TriggerCreateContentPayload) {
  const handle = await tasks.trigger(CREATE_CONTENT_TASK_ID, payload);
  return handle;
}

Sources: lib/trigger/triggerCreateContent.ts:25-28, lib/trigger/tests/triggerCreateContent.test.ts:27-29

Status Polling and Enrichment

For user-facing tasks, the API provides "enriched" task information by fetching metadata directly from Trigger.dev. This includes:

• Recent Runs: A list of the last 5 execution attempts, including status (COMPLETED, FAILED), start/finish times, and duration.
• Upcoming Runs: Future scheduled executions derived from the task payload.

Sources: lib/tasks/tests/enrichTaskWithTriggerInfo.test.ts:38-53

Deletion and Cleanup

When a scheduled action is deleted from the database, the system performs a parallel cleanup of the corresponding Trigger.dev schedule to prevent "orphaned" background jobs.

// Logic derived from lib/tasks/__tests__/deleteTask.test.ts
// 1. Fetch task to get trigger_schedule_id
// 2. Delete database record
// 3. Call deleteSchedule(trigger_schedule_id) via SDK

Sources: lib/tasks/tests/deleteTask.test.ts:47-65

Configuration and Environment

Background tasks require specific environment variables to communicate with the Trigger.dev service and handle callbacks.

Variable	Description
TRIGGER_API_KEY	Authentication key for the @trigger.dev/sdk.
TRIGGER_CALLBACK_URL	The endpoint Trigger.dev calls upon task completion (e.g., /api/coding-agent/callback).
CREATE_CONTENT_TASK_ID	Internal identifier for the content creation job.

Sources: README.md:160-165, lib/trigger/triggerCreateContent.ts:2

Summary

The Trigger.dev background task system provides a resilient infrastructure for the Recoup API's most demanding features. By decoupling long-running processes like media generation and automated coding from the main API thread, the system maintains responsiveness while providing detailed visibility into task status and history through run enrichment and callback mechanisms.