# API reference

## Module forms

The CommonJS root returns the historical Promise-validator namespace:

```js
const validate = require('@stackline/har-validator')
```

ESM provides the same namespace as the default export and each validator as a
named export:

```js
import validate, { har, request, response } from '@stackline/har-validator'
```

The Node.js 6.17.1 compatibility floor applies to CommonJS. ESM entry points
are additive for runtimes and build tools that support ESM.

The root has exactly these enumerable keys, in order:

`afterRequest`, `beforeRequest`, `browser`, `cache`, `content`, `cookie`,
`creator`, `entry`, `har`, `header`, `log`, `page`, `pageTimings`, `postData`,
`query`, `request`, `response`, `timings`.

## Promise validators

Every root validator has the same call shape:

```ts
function validator<T>(data?: T): Promise<T>
```

On success, the Promise resolves to the exact input reference. On failure, it
rejects with `HARError`. As in `har-validator@5.1.5`, any falsy input is first
normalized to an empty object.

```js
const response = {
  status: 200,
  statusText: 'OK',
  httpVersion: 'HTTP/1.1',
  headers: [],
  cookies: [],
  content: { size: 0, mimeType: 'text/plain' },
  redirectURL: '',
  headersSize: -1,
  bodySize: 0
}

const sameResponse = await validate.response(response)
console.assert(sameResponse === response)
```

Validation uses the HAR 1.2 draft-06 schemas from `har-schema@2.0.0` and Ajv
6.15.0 with `allErrors: true`. The validator compiles the schema set lazily on
the first call.

## Historical boolean and callback API

The `lib/async` entry retains its historical name even though its no-callback
form returns a synchronous boolean:

```js
const sync = require('@stackline/har-validator/lib/async')

const valid = sync.response(response)
```

With a callback, validation and callback invocation are both synchronous. The
callback receives `(error, valid)`, and the validator returns the callback's
own return value:

```js
const result = sync.response(response, (error, valid) => {
  if (error) return error.errors
  return valid
})
```

The callback error is `null` on success and a `HARError` on failure.

## `HARError`

The constructor is available from `lib/error`, with or without `.js`:

```js
const HARError = require('@stackline/har-validator/lib/error')
```

A validation failure has:

- `name === 'HARError'`;
- `message === 'validation failed'`;
- `errors`, the complete Ajv 6 error array; and
- the upstream stack shape.

Each Ajv error record includes `keyword`, `dataPath`, `schemaPath`, `params`,
and usually `message`. The maintained constructor has its own prototype
derived from `Error.prototype`, so a `HARError` is an `Error` while an unrelated
`Error` no longer passes `instanceof HARError`.

## Validator catalog

| Validator | HAR object |
| --- | --- |
| `har` | Complete archive root containing `log`. |
| `log` | HAR log with version, creator, entries, and optional pages/browser. |
| `entry` | One request/response transaction and its timings. |
| `request` | Request method, URL, HTTP version, headers, query, cookies, and sizes. |
| `response` | Status, HTTP version, headers, cookies, content, redirect, and sizes. |
| `creator`, `browser` | Product name and version metadata. |
| `page`, `pageTimings` | Page identity and page-load timing metadata. |
| `cache`, `beforeRequest`, `afterRequest` | Cache state and request-bound cache records. |
| `content` | Response body metadata and optional text or encoding. |
| `postData` | Request entity MIME type, text, and optional parameters. |
| `cookie`, `header`, `query` | Individual name/value records and optional metadata. |
| `timings` | Request phase durations. |

The schemas preserve upstream extension-property behavior. Validation confirms
the HAR schema shape; it does not prove that an HTTP exchange is trustworthy,
that timing values agree, or that referenced content is safe to process.

## Historical deep imports

The three upstream entries remain available, with and without `.js`:

- `@stackline/har-validator/lib/promise` — the CommonJS Promise namespace and
  package root implementation;
- `@stackline/har-validator/lib/async` — synchronous boolean/callback
  validators; and
- `@stackline/har-validator/lib/error` — the `HARError` constructor.

Conditional exports also provide ESM facades for these paths.

## Browser builds

Browser bundlers should normally import the root and deep entries exactly as
Node consumers do. That keeps one module graph and therefore one shared
`HARError` constructor:

```js
import validate from '@stackline/har-validator'
import HARError from '@stackline/har-validator/lib/error'
```

The additive `@stackline/har-validator/browser` entry is a self-contained,
root-only bundle in both CommonJS and ESM forms. Use it when only the 18 Promise
validators are needed. It intentionally does not provide the historical deep
modules.

Ajv compiles schemas with `Function` at runtime. A browser policy that forbids
dynamic code generation may need a different precompiled validation design;
do not weaken a Content Security Policy without reviewing that tradeoff.

## TypeScript

CommonJS declarations support TypeScript 3.9. Modern ESM declarations provide
default and named validator exports plus `ValidationError` and
`PromiseValidator` types. The deep async declaration exposes `AsyncValidator`
and `ValidationCallback`.

```ts
import { response, type ValidationError } from '@stackline/har-validator'

const value = await response({
  status: 204,
  statusText: 'No Content',
  httpVersion: 'HTTP/1.1',
  headers: [],
  cookies: [],
  content: { size: 0, mimeType: 'text/plain' },
  redirectURL: '',
  headersSize: -1,
  bodySize: 0
})
```

See [COMPATIBILITY_CONTRACT.md](./COMPATIBILITY_CONTRACT.md) for the exact
preservation boundary, [MIGRATION.md](./MIGRATION.md) for adoption choices, and
[SECURITY.md](./SECURITY.md) for reporting and safe-use guidance.