> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markpdf.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia

> Clase MarkpdfClient, gancho useConvertFile y tipos @markpdf/react-native.

\#Referencia

## `MarkpdfClient`

```ts theme={null}
import { MarkpdfClient } from "@markpdf/react-native";

const client = new MarkpdfClient({
  apiKey: "YOUR_API_KEY",
  baseUrl: "https://api.markpdf.tech", // optional, production default
});
```

<ParamField body="apiKey" type="string" required>
  Tu tecla API.
</ParamField>

<ParamField body="baseUrl" type="string" default="https://api.markpdf.tech">
  URL base de API.
</ParamField>

A diferencia de SDK de Node.js, este cliente es independiente: no envuelve `@markpdf/sdk`, implementa las llamadas directamente en los globales `fetch`/`FormData` de React Native.

## Métodos

### `convertLocalFile`

```ts theme={null}
client.convertLocalFile(
  file: { uri: string; name: string; mimeType?: string },
  options?: ConvertOptions
): Promise<ConvertResult>
```

Cargue un archivo local (desde un selector) a través de `POST /convert` (multipart/form-data), usando el formato `{ uri, name, type }` que React Native reconoce en `FormData` para adjuntar archivos sin leerlos en JS.

<ParamField body="file.uri" type="string" required>
  URI local para el archivo (`file://...` o `content://...`), tal como lo devuelve el selector.
</ParamField>

<ParamField body="file.name" type="string" required>
  Nombre del archivo a enviar.
</ParamField>

<ParamField body="file.mimeType" type="string" default="application/octet-stream">
  Tipo de contenido del archivo.
</ParamField>

### `convertFromUrl`

```ts theme={null}
client.convertFromUrl(
  url: string,
  filename?: string,
  options?: ConvertOptions
): Promise<ConvertResult>
```

Llama a `POST /convert/from-url` con un cuerpo JSON: no carga ningún archivo, API descarga URL del lado del servidor.

<ParamField body="url" type="string" required>
  URL público (o firmado) del documento a convertir. El API se descarga directamente; No pasa por el dispositivo.
</ParamField>

<ParamField body="filename" type="string">
  Nombre del archivo para asociar con el resultado. Si se omite, API intenta inferirlo de URL.
</ParamField>

<ParamField body="options" type="ConvertOptions">
  Mismas opciones que `convertLocalFile`.
</ParamField>

### `pdfIndex`

```ts theme={null}
client.pdfIndex(url: string, filename?: string): Promise<Record<string, unknown>>
```

Llame a `POST /pdf/index`. Devuelve la columna vertebral de PDF sin convertirla; útil para que un agente decida qué rango de `pages` solicitar antes de realizar una conversión completa. Consulte [`POST /pdf/index`](/docs/public/es/api/pdf-index).

### `getJob` / `waitForJob`

```ts theme={null}
client.getJob(jobId: string): Promise<Job>

client.waitForJob(
  jobId: string,
  options?: { pollIntervalMs?: number; timeoutMs?: number }
): Promise<Job>
```

<ParamField body="jobId" type="string" required>
  Identificador de trabajo (`job_id`) devuelto por API cuando `202` responde.
</ParamField>

<ParamField body="options.pollIntervalMs" type="number" default="5000">
  Milisegundos entre cada `GET /jobs/{id}`.
</ParamField>

<ParamField body="options.timeoutMs" type="number">
  Si se especifica, `waitForJob` arroja un `Error` genérico al pasar sin que el trabajo haya terminado. Sin `timeoutMs`, sondea indefinidamente hasta `completed` o `failed`.
</ParamField>

`getJob` consulta `GET /jobs/{id}` solo una vez y devuelve `Job` tal como está (puede seguir a `"queued"` o `"processing"`). `waitForJob` realiza una encuesta repetida hasta que `status` sea `"completed"` o `"failed"`:

* Si `status === "failed"`, `waitForJob` inicia `JobFailedError` (no devuelve el trabajo fallido, inicia).
* Si `status === "completed"`, devuelve `Job` con `body` completado (`string` o `JsonResult` dependiendo de `responseFormat` del trabajo original).
* Si se excede `timeoutMs`, arroja un `Error` genérico (no `MarkpdfError`).

## `ConvertOptions`

```ts theme={null}
interface ConvertOptions {
  inputFormat?: "auto" | "pdf" | "docx" | "csv" | "txt" | "xlsx" | "pptx" | "zip";
  mode?: "fast" | "ultra_fast" | "balanced" | "quality" | "auto";
  clean?: boolean;              // default true
  imageOcr?: boolean;           // default false
  hybridOcr?: boolean;          // default false
  responseFormat?: "markdown" | "json"; // default "markdown"
  slim?: boolean;                // default false
  pages?: string;
  autoPoll?: boolean;            // default true
  pollIntervalMs?: number;       // default 5000
}
```

Todos los campos son opcionales; se aplican a `convertLocalFile`, `convertFromUrl` y `convert()` de `useConvertFile`.

<ParamField body="inputFormat" type="&#x22;auto&#x22; | &#x22;pdf&#x22; | &#x22;docx&#x22; | &#x22;csv&#x22; | &#x22;txt&#x22; | &#x22;xlsx&#x22; | &#x22;pptx&#x22; | &#x22;zip&#x22;" default="auto">
  Formato del archivo de entrada. `"auto"` lo detecta por extensión/contenido. Establezca esto explícitamente si carga un archivo sin una extensión confiable (por ejemplo, un Android `content://` URI sin un nombre claro).
</ParamField>

<ParamField body="mode" type="&#x22;fast&#x22; | &#x22;ultra_fast&#x22; | &#x22;balanced&#x22; | &#x22;quality&#x22; | &#x22;auto&#x22;" default="fast">
  Perfil de velocidad/calidad de conversión. `"ultra_fast"` prioriza la latencia, `"quality"` prioriza la fidelidad del Markdown resultante, `"auto"` permite que el backend decida en función del documento.
</ParamField>

<ParamField body="clean" type="boolean" default="true" />

<ParamField body="imageOcr" type="boolean" default="false" />

<ParamField body="hybridOcr" type="boolean" default="false" />

<ParamField body="responseFormat" type="&#x22;markdown&#x22; | &#x22;json&#x22;" default="markdown">
  Si es `"json"`, la respuesta resuelta es un objeto [`JsonResult`](#tipos) con metadatos (`engine`, `size_bytes`, `timings`, etc.) además del Markdown. Con `"markdown"` (predeterminado), la respuesta resuelta es directamente `string`.
</ParamField>

<ParamField body="slim" type="boolean" default="false">
  Reduce Markdown a una versión más compacta (menos espaciado/metadatos redundantes), destinada a minimizar los tokens en las canalizaciones RAG/LLM.
</ParamField>

<ParamField body="pages" type="string">
  Basado en el rango de páginas 1, solo se aplica a PDF. Ejemplos: `"1,3,5-10"`, `"120-145"`. Útil en dispositivos móviles para evitar cargar/procesar documentos completos de cientos de páginas cuando solo necesita una sección.
</ParamField>

<ParamField body="autoPoll" type="boolean" default="true">
  Si API responde `202` (backends saturados), `convertLocalFile`/`convertFromUrl` realiza un sondeo automático a través de `waitForJob` hasta que finaliza el trabajo. `useConvertFile` **no** respeta esta opción; siempre requiere el manejo manual de `202` porque usa `XMLHttpRequest` en lugar de `waitForJob`. Consulte [Trabajos en streaming y asincrónicos](/docs/public/es/sdks/react-native/streaming-and-async).
</ParamField>

<ParamField body="pollIntervalMs" type="number" default="5000">
  Intervalo entre cada sondeo para `GET /jobs/{id}` cuando `autoPoll` está activo.
</ParamField>

## `useConvertFile(client)`

```ts theme={null}
function useConvertFile(client: MarkpdfClient): {
  convert: (file: LocalFile, options?: ConvertOptions) => Promise<ConvertResult | undefined>;
  reset: () => void;
  status: "idle" | "uploading" | "converting" | "success" | "error";
  progress: number;
  markdown: string | null;
  json: JsonResult | null;
  error: MarkpdfError | null;
}
```

Igual que `convertLocalFile`, pero con progreso de carga a través de `XMLHttpRequest` (RN implementa `XMLHttpRequest` globalmente, a diferencia del navegador que solo tiene `fetch`). Toma el cliente como argumento; no utiliza contexto/Proveedor.

## Tipos

```ts theme={null}
import type {
  ConvertOptions,
  ConvertResult,
  Job,
  JsonResult,
  LocalFile,
  InputFormat,
  Mode,
  ResponseFormat,
  JobStatus,
} from "@markpdf/react-native";
```

```ts theme={null}
interface LocalFile {
  uri: string;
  name: string;
  mimeType?: string;
}

interface Job {
  job_id: string;
  status: "queued" | "processing" | "completed" | "failed";
  body?: string | JsonResult;
  error?: string;
}

type ConvertResult = string | JsonResult | Job;
```

`ConvertResult` es `Job` solo si `autoPoll: false` y API respondieron `202`; de lo contrario, `convertLocalFile`/`convertFromUrl` ya han resuelto el trabajo internamente.