Content Parsing Utilities

Relevant source files

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

• src/commands/content/parsePositiveInt.ts
• src/commands/content/createCommand.ts
• src/commands/content/templatesCommand.ts
• tests/commands/content.test.ts
• src/output.ts

Content Parsing Utilities represent the logic layer responsible for validating, sanitizing, and transforming user input before it is dispatched to the Recoup platform API. These utilities ensure that command-line arguments, such as batch counts, song slugs, and caption lengths, adhere to expected formats and constraints, thereby maintaining the integrity of the content creation pipeline.

These utilities are primarily utilized by the create and templates subcommands within the content module to handle complex flag parsing and error reporting. Sources: src/commands/content/createCommand.ts, src/commands/content/templatesCommand.ts

Input Validation and Sanitization

The core of the parsing logic resides in specialized functions that convert string-based CLI arguments into typed data structures required by the API.

Integer Parsing

The parsePositiveInt utility is used to validate numeric inputs like --batch. It ensures that the provided value is a valid number and greater than zero. If the input fails validation, it throws a descriptive error including the flag name to assist the user. Sources: src/commands/content/parsePositiveInt.ts, tests/commands/content.test.ts:114-122

String and Collection Parsing

For more complex inputs, such as song selections or caption settings, the utilities perform the following:

• Collection Splitting: The --songs flag accepts a comma-separated string, which is split, trimmed, and filtered for empty values to create an array of slugs. Sources: src/commands/content/createCommand.ts:25-27
• Enum Validation: Input for --caption-length is checked against a Set of allowed values (short, medium, long). Sources: src/commands/content/createCommand.ts:5, src/commands/content/createCommand.ts:21-23

Validation Workflow

The following diagram illustrates how user input is processed by the parsing utilities before reaching the API client.

The workflow ensures that the API only receives well-formatted data, reducing the likelihood of 400-level HTTP errors. Sources: src/commands/content/createCommand.ts:19-38

Data Transformation for API Requests

After parsing, the utilities structure the data into an object suitable for the /api/content/create endpoint. This includes type casting (e.g., boolean conversion for --upscale and --lipsync) and conditional inclusion of optional fields.

Argument	Logic	Output Type
--artist	Required input	string
--batch	Parsed via parsePositiveInt	number
--lipsync	Double negation cast	boolean
--upscale	Double negation cast	boolean
--songs	CSV split to Array	string[]

Sources: src/commands/content/createCommand.ts:15-38

Output Handling and Formatting

The parsing utilities also manage how the system interprets and displays the results of content operations. This includes handling both standard text output and structured JSON output via the --json flag.

Response Parsing

When creating content, the system parses the runIds from the API response. It handles multiple scenarios based on the number of IDs returned:

1. Single Run: Displays a "Run started" message with the specific ID.
2. Batch Run: Displays a "Batch started" message with the total count and a list of all IDs.
3. Empty Response: Throws an error if no IDs are present.

Sources: src/commands/content/createCommand.ts:45-59

Error Reporting

Errors encountered during parsing (e.g., invalid integers) or during the API request (e.g., network failure) are processed through getErrorMessage and displayed via printError. This standardizes the error format to "Error: [message]" and exits the process with code 1. Sources: src/output.ts:44-52, tests/commands/content.test.ts:98-103

Summary

Content Parsing Utilities provide a robust validation layer for the Recoup CLI. By centralizing logic for integer validation, string list processing, and enum checking, these utilities ensure that the content creation pipeline remains stable and provides meaningful feedback to the user during input errors. Sources: src/commands/content/createCommand.ts, src/commands/content/parsePositiveInt.ts