Collector API

The collector exports three functions. With npm, import them from @octetproof/collector. With the script tag, they are properties of the global octet.

import { start, ready, verify } from '@octetproof/collector';

`start(config)`

start(config: CollectorConfig): void

Begins a collection in the background and returns at once. Call it at page load. Calling start() again replaces the configuration, discards any stored result, and begins a new collection.

Throws at once if config.apiUrl is not a valid https:// URL, or if config.mode is not 'full', 'lite' or 'passive'. See CollectorConfig.

`ready()`

ready(): Promise<ReadyResult>

Resolves once your edge has passed the latest collection to Octet, which means your backend can fetch the verdict. Call it at the moment of action.

If the collection that start() began is still running, ready() waits for it.
If that collection finished less than 90 seconds ago, ready() resolves at once with its result.
Otherwise, ready() runs a new collection and waits for it.

Rejects if start() was never called, if the POST to your edge fails, or if the collection was aborted. A failed collection is not stored, so the next ready() call runs a new one.

`verify(config)`

verify(config: CollectorConfig): Promise<EdgeReply>

Runs one collection and resolves with your edge's reply. It stores nothing, so each call collects again. Use it where there is no separate moment of action. It rejects at once for an invalid apiUrl or mode, and later if the POST to your edge fails or the collection is aborted.

`CollectorConfig`

Field	Type	Required	Description
`apiUrl`	`string`	Yes	Your edge's origin, for example `https://octet.example.com`. Must be `https://`. `http://` is accepted only for `localhost`, `127.0.0.1` and `[::1]`.
`sessionRef`	`string`	Yes	The unguessable reference your backend created for this page view. Your backend fetches the verdict with it.
`mode`	`'full' \\| 'lite' \\| 'passive'`	No	How much network measurement to do. The default is `'full'`. See Modes.
`wsUrl`	`string`	No	The WebSocket URL for your edge. The default is `apiUrl` with `https` replaced by `wss`, plus `/v1/ws`. Set it only if your edge's WebSocket has a different address.
`signal`	`AbortSignal`	No	Cancels the collection. See Cancelling.

Modes

Mode	What it does	Network requests beyond your edge
`full`	Everything, for the strongest results	HTTPS and UDP 3478 to three Octet network hosts
`lite`	Skips the HTTPS timing requests	UDP 3478 to three Octet network hosts
`passive`	No network measurement and no WebRTC	None

No mode shows a permission prompt. The hosts are listed in Network and CSP.

`ReadyResult`

Field	Type	Description
`response`	`EdgeReply`	Your edge's reply to the POST.
`issuedAtMs`	`number`	When the edge replied, in milliseconds since the Unix epoch.
`expiresAtMs`	`number`	When `ready()` stops reusing this result, in milliseconds since the Unix epoch. `issuedAtMs` plus 90 seconds.
`elapsedMs`	`number`	Milliseconds from the start of collection to the edge's reply.

`EdgeReply`

In production your edge always replies with:

{ "ok": true }

The reply never contains the verdict. Your backend fetches it. See Fetch the Verdict. Only the testing setting EDGE_EXPOSE_VERDICT changes this reply. See Edge Configuration.

Cancelling

Pass an AbortSignal in the configuration. Aborting stops the collection and cancels the POST to your edge if it has started. ready() or verify() then rejects with the signal's abort reason, which is a DOMException named AbortError unless you pass your own reason to abort(). If the abort comes before the POST reaches your edge, no verdict is produced for that collection.

const controller = new AbortController();
octet.start({ apiUrl: 'https://octet.example.com', sessionRef, signal: controller.signal });
window.addEventListener('pagehide', () => controller.abort());

Errors

Thrown or rejected with	When
`Error: octet: invalid apiUrl "…"`	`apiUrl` is not a URL. Thrown by `start()`, rejected by `verify()`.
`Error: octet: apiUrl must be https://…`	`apiUrl` uses another scheme. Thrown by `start()`, rejected by `verify()`.
`Error: octet: unknown mode "…"`	`mode` is not `'full'`, `'lite'` or `'passive'`. Thrown by `start()`, rejected by `verify()`.
`Error: octet: call start() before ready()`	`ready()` was called before `start()`.
`Error: signal report failed: <status>`	Your edge answered the POST with an error status. See Errors.
`TypeError` from `fetch`	The POST to your edge failed at the network level, for example because of CORS or DNS.
`DOMException` named `AbortError`, or your own abort reason	The collection was aborted.

A measurement that fails or is blocked never causes an error. The collector leaves it out and sends the rest.