Recoup API Client

The Recoup API Client is a collection of specialized utility functions located in src/recoup/ designed to interface with Recoup's backend services. It serves as the primary data bridge for Trigger.dev background tasks, enabling the system to fetch task configurations, retrieve scraper results, and generate AI-driven chat responses.

The client is architected around the Single Responsibility Principle (SRP), with each file typically exporting a single function responsible for a specific API interaction. These functions handle authentication via API keys, validate response structures using Zod schemas, and provide structured logging via the Trigger.dev SDK.

Sources: AGENTS.md:21-25, src/recoup/fetchTask.ts:33-40

Architecture and Endpoints

The client interacts with two primary API environments:

• Recoup Chat API: https://chat.recoupable.com/api - Used for generating conversational AI content and managing chat rooms.
• Recoup API: https://recoup-api.vercel.app/api - Used for general administrative data, task management, and scraper integrations.

Sources: AGENTS.md:55-56, src/recoup/fetchTask.ts:41-41

Data Flow Overview

The following diagram illustrates how the API Client functions sit between the background workers and the external Recoup services.

The client facilitates a request-response flow where background tasks trigger specific client functions to synchronize state or perform AI actions.
Sources: src/tasks/customerPromptTask.ts:22-30, src/recoup/fetchTask.ts:41-45

Key Modules and Functions

Task Management (fetchTask.ts)

The fetchTask function retrieves specific task configurations using an externalId. This is critical for dynamic schedules where task parameters like the AI model and prompt are stored in the Recoup database.

Data Structure (Task Response):

• id: Task identifier.
• prompt: The system or user prompt for the AI.
• account_id: The owning account.
• model: Optional override for the LLM used.

Sources: src/recoup/fetchTask.ts:9-25, src/recoup/fetchTask.ts:33-45

Chat Generation (generateChat.ts)

Interacts with the Recoup Chat API to produce AI responses. It is used extensively by the customerPromptTask to automate customer engagement messages.

Scraper Integration (getScraperResults.ts)

This module provides a polling-capable interface for Apify scraper runs. It validates two distinct states: "in-progress" (containing a datasetId) and "completed" (containing a data array).

Sources: src/recoup/getScraperResults.ts:5-18

Schema Validation

The client utilizes Zod for rigorous runtime type checking of API responses. This ensures that background workers do not process malformed data, which could lead to silent failures in long-running tasks.

// Example validation for Scraper Results
const inProgressResponseSchema = z.object({
  status: z.string(),
  datasetId: z.string(),
});

const completedResponseSchema = inProgressResponseSchema.extend({
  data: z.array(z.unknown()),
});

Sources: src/recoup/getScraperResults.ts:5-15, src/recoup/fetchTask.ts:9-22

Implementation Patterns

• Error Handling: Functions are wrapped in try-catch blocks and use the Trigger.dev logger.error to provide context for debugging in the production dashboard.
• Environment Variables: The client relies on NEW_API_BASE_URL and RECOUP_API_KEY for configuration and authentication.
• Response Mapping: Functions often map raw database-centric API responses into cleaner, internal TypeScript interfaces (e.g., ChatConfig).

Sources: src/recoup/fetchTask.ts:41-80, src/recoup/getScraperResults.ts:31-78

Conclusion

The Recoup API Client serves as the essential infrastructure for the Recoup Tasks repository. By encapsulating complex HTTP logic, authentication, and validation into reusable functions, it allows background tasks to focus on business logic while maintaining high reliability and type safety across the distributed system.