Handle single vs. multi-file converters in ConvertAsync for simpler dynamic usage

[kostas-jonauskas]

Problem Description

Some converters accept a single input file, while others support multiple files. This makes it difficult to use the C# library dynamically when building flexible integrations - for example, when the number of uploaded files is unknown at runtime, and it’s not clear whether the target converter expects one or several files.

Currently, to handle this properly you need to:

1. Determine how many files the user is uploading.
2. Parse the OpenAPI schema to check whether the selected converter expects a single or multiple input files.
3. Branch your logic into multiple code paths:
   • Single file uploaded + single file converter: perform a regular conversion.
   • Multiple files uploaded + single file converter: loop through each file, run conversions one by one, and aggregate the results.
   • Multiple files uploaded + multi-file converter: pass all files at once.

This approach introduces unnecessary complexity. It forces developers to depend on external schema requests, parse OpenAPI responses, and manually implement branching logic - just to determine how many files a converter can accept.

---

Proposed Enhancement

The library should handle this logic internally. A developer should be able to pass one or multiple files to the ConvertAsync method, and the library would automatically decide whether to perform a single or multiple conversions under the hood.

The response should return a unified result structure, including aggregated output files and total conversion cost (if applicable).

Example Usage

stepParams.Add(new ConvertApiFileParam(file1));
stepParams.Add(new ConvertApiFileParam(file2));
stepParams.Add(new ConvertApiFileParam(file3));

var response = await convertApi.ConvertAsync(from, to, stepParams);

// Optional: check aggregated conversion cost
var cost = response.ConversionCost;

---

Expected Outcome

As a developer, I don’t need to worry about how many conversions are performed internally.
The goal is simplicity and clean integration.
If needed, the existing ConversionCost property can provide full transparency about the underlying cost structure.