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.
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:
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>paramslleva los parámetros de ruta y de consulta y, en las operaciones que lo tienen,body.orgsiempre es opcional.optionssiempre admitesignal(unAbortSignal) yheaders(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 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:
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
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.
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.