openwaf.ts is one TypeScript file with no dependencies, built on fetch. Download it from https://dash.openwaf.dev/v1/sdk/openwaf.ts. It runs on Bun, on Node.js with type stripping (node --experimental-strip-types), on Deno and in browsers, or through your TypeScript toolchain.
import { OpenWAF, OpenWAFError, type Applied, type Zone } from "./openwaf.ts";new OpenWAF(options?)
| Option | Type | Default |
|---|---|---|
token | string | OPENWAF_TOKEN |
baseUrl | string | OPENWAF_API_URL; set it to https://dash.openwaf.dev |
org | string (organisation id) | OPENWAF_ORG, else the token's organisation |
fetch | typeof fetch | globalThis.fetch |
Environment variables are read in Node.js, Bun and Deno; elsewhere, pass the options.
| Member | Meaning |
|---|---|
baseUrl | The API address in use, without a trailing slash. |
orgId(): Promise<string> | The organisation the methods use by default (asked once when not configured). |
request<T>(req): Promise<T> | The generic call behind every method (below). |
Methods
Every API operation is a method named after its operation id, with this shape:
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>paramsholds the path and query parameters and, for operations with one,body.orgis always optional.optionsalways acceptssignal(anAbortSignal) andheaders(extra request headers). Write methods add the change options their operation supports.
| Option type | Field | Sent as |
|---|---|---|
RequiredReasonOption / ReasonOption | reason: string | X-Change-Reason |
RequiredIfMatchOption / IfMatchOption | ifMatch: number | string | If-Match: "<version>" |
DryRunOption | dryRun?: boolean | ?dry_run=1 |
A method that answers a simulation plan or a result is typed as their union; cast the answer of a dryRun call to Applied.
Commonly used methods:
| Task | Method |
|---|---|
| Zones | listZones, getZone, createZone, deleteZone |
| DNS records | listRecords, createRecord, updateRecord, deleteRecord, batchRecords |
| Edge settings and rules | getZoneEdge, updateZoneEdge, listRules, createRule, deleteRule |
| History | listZoneVersions, getZoneVersion, getZoneDiff, revertZone, getZonePropagation |
| Cache | purgeCache, listCachePurges |
| Audit log | listAudit |
The API reference lists every operation with its id, parameters and answers.
request(req)
Calls any route with the client's base URL, token and error handling:
const res = await owf.request<{ items: unknown[] }>({
method: "GET",
path: "/v1/orgs/" + (await owf.orgId()) + "/zones",
query: { include: "merged" },
});| Field | Meaning |
|---|---|
method, path | HTTP method and path below the base URL. |
query | Query parameters; undefined and null are left out. |
body, contentType | JSON value, or text with another contentType. |
reason, ifMatch, dryRun | Change options, as above. |
auth | false sends no token (public routes). |
signal, headers | As in every method. |
It answers the decoded body: JSON for JSON answers, text otherwise, undefined for an empty answer.
OpenWAFError
class OpenWAFError extends Error {
readonly status: number; // HTTP status; 0 when there was no answer from the API
readonly code: string; // e.g. not_found, invalid, version_conflict, reason_required
readonly field?: string; // the field of a validation error
readonly body: unknown; // the decoded error body, e.g. { current_version }
}Network failures and aborts are not wrapped: they are the errors fetch throws. See Error handling.
Types
The file exports an interface for every schema of the API (Zone, Record, RecordInput, ZoneEdgeSettings, ConfigVersion, Diff, DiffChange, Applied, AuditEntry, PurgeRequest, PurgeResult, Propagation…), one …Params interface per method and one …Result type for list answers. Field descriptions come from the API contract and are in Spanish.