@hootlens/types

TypeScript types for the Hoot Lens script tag. They type the window.hootlens command queue, the window.Hootlens API, the status and diagnostics objects, and the data-hoot-* attributes, so editors and coding agents see the real command list and a mistyped command fails to compile.

The package contains declarations only and has no runtime code or dependencies.

Install

npm install --save-dev @hootlens/types

Include the types once, in a file your tsconfig covers (for example src/hootlens.d.ts):

import '@hootlens/types';

or list the package in compilerOptions.types:

{ "compilerOptions": { "types": ["@hootlens/types"] } }

The command queue

(window.hootlens = window.hootlens || []).push(['consent', true]);

window.hootlens.push(['pageVersion', 'pricing-v3']);
window.hootlens.push(['onStatus', (status) => { /* status: HootlensStatus */ }]);

window.hootlens.push(['nope']); // error: not a Hoot Lens command

HootlensCommand is the union of every command the tag runs: consent, consentSource, release, variant, pageVersion, stop, start, flush, onStatus, diagnostics, init and notice. Inside a callback pushed this way, annotate the parameter ((status: HootlensStatus) => ...), because TypeScript does not infer it through the union.

The API

import type { HootlensStatus } from '@hootlens/types';

const status: HootlensStatus | undefined = window.Hootlens?.status();

window.Hootlens is typed as HootlensApi: init, start, setConsent, setLabels, flush, stop, reset, getTracker, status, onStatus, diagnostics, createTracker and privacySignalPresent. The same types describe the exports of the tracker's ESM entry. Also exported: HootlensState, HootlensReason, HootlensDiagnostics, HootlensOptions, HootlensLabels, HootlensTracker and HootlensAttributes.

The data-hoot-* attributes

| Attribute | Value | Meaning | | --- | --- | --- | | data-hoot-id | string | Stable name for a control; the click selector and target. | | data-hoot-name | string | Readable name shown next to the selector. | | data-hoot-label | string | Older spelling of data-hoot-name. | | data-hoot-private | present | Replaces the element in replays; clicks inside are attributed to the region. | | data-hoot-dynamic | present | Leaves the content out of the page fingerprint. | | data-hoot-region | string | Public key for a meaningful region. | | data-hoot-version | string | The region's edition. |

React (add once, in any file your tsconfig covers):

import '@hootlens/types/react';

<section data-hoot-region="pricing" data-hoot-version="pricing-v2">
  <button data-hoot-id="pricing-start-trial">Start trial</button>
</section>

React already accepts any hyphenated attribute, so this adds editor completion and rejects wrong value types such as data-hoot-id={5}.

Vue 3 (import '@hootlens/types/vue';) and Svelte (/// <reference types="@hootlens/types/svelte" /> in src/app.d.ts) use the same attribute list. These two entries are small module augmentations that this repository does not compile against Vue or Svelte; the React entry and the global types are type-checked in CI.

Kept in step with the tracker

The command union, the status, diagnostics, option and tracker types, and the keys of window.Hootlens are checked against the tracker's source in the Hoot Lens repository. A command or field added to the tracker fails CI until it is added here.

License

MIT