HTTP Client Integration

Relevant source files

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

• src/client.ts
• tests/client.test.ts
• README.md
• CLAUDE.md
• src/bin.ts
• src/commands/songs.ts
• src/commands/chats.ts

The HTTP Client Integration serves as the central communication layer between the Recoup CLI and the Recoup platform's REST API. It abstracts the complexities of network requests, authentication headers, and response parsing into a simple interface used by all command modules within the application.

Built on the native fetch API (Node 22+), the integration handles base URL configuration, API key injection via custom headers, and consistent error handling for both network-level failures and API-defined error states.
Sources: CLAUDE.md:12, src/client.ts:1-45

Core Architecture

The integration follows a Singleton-like pattern where utility functions are exported to perform standardized GET and POST operations. This ensures that every request made by the CLI adheres to the same security and formatting standards.

Data Flow Overview

The following diagram illustrates how a command initiates a request through the client to reach the Recoup API.

The client acts as a bridge, transforming internal command logic into standardized HTTP requests.
Sources: src/client.ts:8-45, CLAUDE.md:14-20

Authentication and Configuration

The client relies on environment variables to configure its connection parameters. Every request includes an x-api-key header for authentication and defaults to a production API endpoint unless overridden.

Configuration Element	Source	Default Value	Description
RECOUP_API_KEY	Environment	(Required)	Used for the x-api-key header.
RECOUP_API_URL	Environment	https://recoup-api.vercel.app	The base URL for all API requests.
Content-Type	Static	application/json	Header included in all requests.

Sources: CLAUDE.md:18-22, README.md:65-71, src/client.ts:25-27

Request Handling Logic

The integration provides two primary methods for interacting with the API: get and post.

GET Requests

The get function handles path concatenation and query parameter serialization. It specifically filters out undefined or empty string values to ensure clean URLs.
Sources: src/client.ts:12-23

POST Requests

The post function handles JSON serialization of the request body and executes a POST method call.
Sources: src/client.ts:44-58

Error Handling Sequence

The client implements a strict validation gate. A request is considered successful only if the HTTP response code is in the 200-299 range AND the JSON body does not contain a status: "error" field.

Integration with Commands

Commands utilize the client by importing the get or post functions. The client returns an ApiResponse interface, which is a flexible structure allowing for dynamic keys while providing optional fields for common API metadata.

Example: Song Analysis Integration

The songs command uses the client to post audio URLs and prompts to the /api/songs/analyze endpoint.

// src/commands/songs.ts:26
const data = await post("/api/songs/analyze", body);

// src/client.ts:5-10
export interface ApiResponse {
  status?: string;
  error?: string;
  message?: string;
  [key: string]: unknown;
}

Sources: src/commands/songs.ts:26, src/client.ts:5-10

Implementation Summary

The client is used across various modules to manage platform resources:

• Chats: GET /api/chats and POST /api/chats for management.
• Sandboxes: GET /api/sandboxes and POST /api/sandboxes for environment control.
• Content: GET /api/content/templates and POST /api/content/create for pipeline triggers.
  Sources: src/commands/chats.ts:10-38, src/commands/sandboxes.ts:10-39, src/commands/content/templatesCommand.ts:12

Summary

The HTTP Client Integration in @recoupable/cli provides a robust, standardized gateway for API communication. By centralizing authentication, base configuration, and error validation in src/client.ts, the architecture ensures that individual command modules remain focused on user interaction and data presentation rather than network protocol details.