# Referencia del SDK de TypeScript

> El cliente de TypeScript de OpenWAF: opciones del constructor, firmas de los métodos, opciones por llamada, request, errores y tipos.

`openwaf.ts` es un único fichero de TypeScript sin dependencias que usa `fetch`. Descárgalo de `https://dash.openwaf.dev/v1/sdk/openwaf.ts`. Funciona con Bun, con Node.js con eliminación de tipos (`node --experimental-strip-types`), con Deno y en navegadores, o a través de tu cadena de herramientas de TypeScript.

```ts
import { OpenWAF, OpenWAFError, type Applied, type Zone } from "./openwaf.ts";
```

## new OpenWAF(options?)

| Opción | Tipo | Por defecto |
|---|---|---|
| `token` | `string` | `OPENWAF_TOKEN` |
| `baseUrl` | `string` | `OPENWAF_API_URL`; ponla a `https://dash.openwaf.dev` |
| `org` | `string` (id de la organización) | `OPENWAF_ORG`; si no, la organización del token |
| `fetch` | `typeof fetch` | `globalThis.fetch` |

Las variables de entorno se leen en Node.js, Bun y Deno; en los demás casos, pasa las opciones.

| Miembro | Significado |
|---|---|
| `baseUrl` | La dirección de la API en uso, sin barra final. |
| `orgId(): Promise<string>` | La organización que usan los métodos por defecto (se pide una vez si no está configurada). |
| `request<T>(req): Promise<T>` | La llamada genérica que hay detrás de cada método (abajo). |

## Métodos

Cada operación de la API es un método con el nombre de su id de operación y esta forma:

```ts
owf.listZones(params?: ListZonesParams, options?: RequestOptions): Promise<ListZonesResult>
owf.createRecord(params: CreateRecordParams,
                 options: RequestOptions & RequiredReasonOption & IfMatchOption & DryRunOption): Promise<Applied | Record>
owf.revertZone(params: RevertZoneParams,
               options: RequestOptions & RequiredReasonOption & RequiredIfMatchOption & DryRunOption): Promise<RevertResult | Applied>
owf.purgeCache(params: PurgeCacheParams, options?: RequestOptions & ReasonOption & DryRunOption): Promise<PurgeResult>
```

- `params` lleva los parámetros de ruta y de consulta y, en las operaciones que lo tienen, `body`. `org` siempre es opcional.
- `options` siempre admite `signal` (un `AbortSignal`) y `headers` (cabeceras adicionales). Los métodos de escritura añaden las opciones de cambio que admite su operación.

| Tipo de opción | Campo | Se envía como |
|---|---|---|
| `RequiredReasonOption` / `ReasonOption` | `reason: string` | `X-Change-Reason` |
| `RequiredIfMatchOption` / `IfMatchOption` | `ifMatch: number \| string` | `If-Match: "<versión>"` |
| `DryRunOption` | `dryRun?: boolean` | `?dry_run=1` |

Un método que responde un plan de simulación o un resultado está tipado como su unión; convierte a `Applied` la respuesta de una llamada con `dryRun`.

Métodos de uso habitual:

| Tarea | Método |
|---|---|
| Zonas | `listZones`, `getZone`, `createZone`, `deleteZone` |
| Registros DNS | `listRecords`, `createRecord`, `updateRecord`, `deleteRecord`, `batchRecords` |
| Ajustes de borde y reglas | `getZoneEdge`, `updateZoneEdge`, `listRules`, `createRule`, `deleteRule` |
| Historial | `listZoneVersions`, `getZoneVersion`, `getZoneDiff`, `revertZone`, `getZonePropagation` |
| Caché | `purgeCache`, `listCachePurges` |
| Auditoría | `listAudit` |

La [referencia de la API](https://developers.openwaf.dev/es/api/) enumera todas las operaciones con su id, sus parámetros y sus respuestas.

## request(req)

Llama a cualquier ruta con la URL base, el token y la gestión de errores del cliente:

```ts
const res = await owf.request<{ items: unknown[] }>({
  method: "GET",
  path: "/v1/orgs/" + (await owf.orgId()) + "/zones",
  query: { include: "merged" },
});
```

| Campo | Significado |
|---|---|
| `method`, `path` | Método HTTP y ruta por debajo de la URL base. |
| `query` | Parámetros de consulta; `undefined` y `null` se omiten. |
| `body`, `contentType` | Valor JSON, o texto con otro `contentType`. |
| `reason`, `ifMatch`, `dryRun` | Opciones de cambio, como arriba. |
| `auth` | `false` no envía el token (rutas públicas). |
| `signal`, `headers` | Como en cualquier método. |

Devuelve el cuerpo decodificado: JSON en las respuestas JSON, texto en las demás, `undefined` en una respuesta vacía.

## OpenWAFError

```ts
class OpenWAFError extends Error {
  readonly status: number;   // estado HTTP; 0 si no hubo respuesta de la API
  readonly code: string;     // p. ej. not_found, invalid, version_conflict, reason_required
  readonly field?: string;   // el campo de un error de validación
  readonly body: unknown;    // el cuerpo del error decodificado, p. ej. { current_version }
}
```

Los fallos de red y las cancelaciones no se envuelven: son los errores que lanza `fetch`. Ver [Gestión de errores](https://developers.openwaf.dev/es/sdk/error-handling/).

## Tipos

El fichero exporta una interfaz por cada esquema de la API (`Zone`, `Record`, `RecordInput`, `ZoneEdgeSettings`, `ConfigVersion`, `Diff`, `DiffChange`, `Applied`, `AuditEntry`, `PurgeRequest`, `PurgeResult`, `Propagation`…), una interfaz `…Params` por método y un tipo `…Result` para las respuestas de listas. Las descripciones de los campos salen del contrato de la API y están en español.