Collector API

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

import { start, ready, settled, 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.challenge is missing, 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() needs a new collection. The challenge from start() has already been sent, so ready() rejects with octet: this challenge was already used. Get a new challenge from your backend and call start() with it.

With the early verdict, ready() resolves once the first of the collection's two reports is in, and your backend can fetch the provisional verdict. Call settled() before the page navigates away.

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. If the collection finished, its challenge counts as used, even if the POST never started, so call start() with a new challenge before the next ready().

settled()

settled(): Promise<void>

Resolves once the collector has finished sending the latest collection, whether it succeeded or failed, or at once if it already finished. It carries no result and starts nothing. Using it is optional. If your page navigates away soon after a collection, for example when the login form submits, await settled() first so the browser doesn't cancel a report still on its way. It matters most for a license with the early verdict, where the second report is sent after ready() resolves. Since v1.9.1.

Rejects with octet: call start() before settled() if start() was never called. verify() resolves after everything is sent, so it doesn't need settled().

verify(config)

verify(config: CollectorConfig): Promise<EdgeReply>

Runs one collection and resolves with your edge's reply. With the early verdict, it resolves after both reports. It stores nothing, so each call collects again and needs a new challenge. Use it where there is no separate moment of action. It rejects at once for a missing challenge or an invalid apiUrl or mode, and later if the challenge was already used, if the POST to your edge fails, or if the collection is aborted.

CollectorConfig

Modes

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

ReadyResult

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, challenge, signal: controller.signal });
window.addEventListener('pagehide', () => controller.abort());

Errors

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