final client = MarkpdfClient(
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://api.markpdf.tech', // optional, production default
  timeout: const Duration(minutes: 5),  // default 5 minutos
  maxRetries: 2,                        // reintentos en 429/5xx
);

const ConvertOptions({
  InputFormat inputFormat = InputFormat.auto,
  ConversionMode mode = ConversionMode.fast,
  Engine engine = Engine.auto,
  bool clean = true,
  bool imageOcr = false,
  bool hybridOcr = false,
  ResponseFormat responseFormat = ResponseFormat.markdown,
  bool slim = true,
  String? pages,
  bool autoPoll = true,
  Duration pollInterval = const Duration(seconds: 5),
});

enum InputFormat { auto, pdf, docx, xlsx, pptx, csv, txt, zip }
enum ConversionMode { fast, ultraFast, balanced, quality, auto }
enum ResponseFormat { markdown, json }

Future<ConvertResult> convertFile(
  File file, {
  ConvertOptions options = const ConvertOptions(),
})

Future<ConvertResult> convertBytes(
  Uint8List data,
  String filename, {
  ConvertOptions options = const ConvertOptions(),
})

Future<ConvertResult> convertFromUrl(
  String url, {
  String? filename,
  ConvertOptions options = const ConvertOptions(),
})

Future<PdfSpine> pdfIndex(String url, {String? filename})

final spine = await client.pdfIndex('https://bucket.example.com/report.pdf?sig=...');
for (final section in spine.sections) {
  print('${section.page} ${section.level} ${section.text}');
}

Future<Job> getJob(String jobId)

Future<Job> waitForJob(
  String jobId, {
  Duration pollInterval = const Duration(seconds: 5),
  Duration? timeout,
})

sealed class ConvertResult {}

class MarkdownResult extends ConvertResult {
  final String markdown;
}

class JsonConvertResult extends ConvertResult {
  final JsonResult result;
}

class QueuedResult extends ConvertResult {
  final Job job; // ver Streaming y async
}

final result = await client.convertBytes(bytes, 'report.pdf');

switch (result) {
  case MarkdownResult(:final markdown):
    print(markdown);
  case JsonConvertResult(:final result):
    print(result.markdown);
  case QueuedResult(:final job):
    print('En cola: ${job.jobId}');
}

class JsonResult {
  final String markdown;
  final String filename;
  final String inputFormat;
  final String engine;
  final int sizeBytes;
  final int markdownBytes;
  final int tokenSavedEstimate;
  final Timings timings;
}

class Timings {
  final int convertMs;
  final int cleanMs;
  final int totalWorkerMs;
  final int uploadMs;
  final int totalRequestMs;
}

class PdfSpine {
  final int pageCount;
  final int inputBytes;
  final FontModel fontModel;
  final List<Section> sections;
  final List<String> repeatedHeadersFooters;
  final List<PageInfo> pages;
  final bool pagesTruncated;
  final int estimatedTokensFull;
  final int estimatedTokensSpineOnly;
}

class Section {
  final int page;
  final int level;
  final String text;
}

class Job {
  final String jobId;
  final JobStatus status; // queued | processing | completed | failed
  final dynamic body;
  final String? error;
}