# TypeScript SDK reference

> The OpenWAF TypeScript client: constructor options, method signatures, per-call options, request, errors and types.

`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.

```ts
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:

```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` holds the path and query parameters and, for operations with one, `body`. `org` is always optional.
- `options` always accepts `signal` (an `AbortSignal`) and `headers` (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](https://developers.openwaf.dev/api/) lists every operation with its id, parameters and answers.

## request(req)

Calls any route with the client's base URL, token and error handling:

```ts
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

```ts
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](https://developers.openwaf.dev/sdk/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.