@corbado/observe 1.8.0 → 1.9.1

package/dist/analysis/client.mjs

@@ -4,7 +4,8 @@ import {
   KeyRegistrationOperationFull
 } from "./utils/key-operation-full.mjs";
 import { reserveCaptureSeq } from "./low-events/capture-sequence.mjs";
-import { applySourcePathQuery } from "./utils/source-path.mjs";
+import { readSourcePath } from "./readers/page.mjs";
+import { readUserAgent } from "./readers/device.mjs";
 import { SharedWindowObserver, getCapturePageId } from "./low-events/shared-window-observer.mjs";
 import {
   AuthEventName
@@ -33,7 +34,7 @@ import { PasskeyLoginOperationFull } from "./utils/passkey-login-operation-full.
 import { EmailOtpOperationFull } from "./utils/email-otp-operation-full.mjs";
 import { SmsOtpOperationFull } from "./utils/sms-otp-operation-full.mjs";
 import { isBlockedUserAgent } from "./utils/blocked-user-agents.mjs";
-import { withWebLock } from "./utils/web-lock.mjs";
+import { hasWebLocks, withWebLock } from "./readers/web-lock.mjs";
 import { SDK_NAME, SDK_VERSION } from "./version.mjs";
 import {
   EmailLinkContinuationOperation,
@@ -507,7 +508,23 @@ var CorbadoTracker = class _CorbadoTracker {
     if (typeof navigator === "undefined") {
       return false;
     }
-    return isBlockedUserAgent(navigator.userAgent);
+    return isBlockedUserAgent(
+      readUserAgent({
+        key: "browser-api:sdk.blocked-user-agent",
+        title: "User agent check for crawlers and bots",
+        accessNote: "navigator.userAgent, matched against a list of crawler and bot patterns",
+        group: "Observe SDK state",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "result",
+            label: "Whether the browser looks like a bot",
+            exposure: "computed",
+            transform: { note: "matched against the blocked user-agent list; only the boolean is used (tracking off)" }
+          }
+        ]
+      })
+    );
   }
   resolveSessionId() {
     try {
@@ -678,27 +695,74 @@ var CorbadoTracker = class _CorbadoTracker {
       return current;
     };
     const timeoutMs = this.config.seqLockTimeoutMs;
-    if (timeoutMs === 0 || typeof navigator === "undefined" || !navigator.locks?.request) {
+    if (timeoutMs === 0 || !hasWebLocks({
+      key: "browser-api:sdk.web-locks",
+      title: "Coordination of Observe data across open tabs",
+      accessNote: "Web Locks API (navigator.locks) on Observe's own lock names",
+      group: "Observe SDK state",
+      origin: "observe-internal",
+      fields: [
+        {
+          path: "available",
+          label: "Whether the browser supports tab coordination",
+          exposure: "enum",
+          transform: { values: [true, false] }
+        }
+      ]
+    })) {
       return allocate();
     }
-    return withWebLock(this.seqLockName, allocate, {
-      timeoutMs,
-      onTimeout: () => {
-        this.logger.warn(`Sequence Web Lock acquisition timed out after ${timeoutMs}ms; using fallback`);
-        this.reportTelemetry("info", `seq web lock timeout; using fallback, ${timeoutMs}ms`);
+    return withWebLock(
+      {
+        key: "browser-api:sdk.web-locks",
+        title: "Coordination of Observe data across open tabs",
+        accessNote: "Web Locks API (navigator.locks) on Observe's own lock names",
+        group: "Observe SDK state",
+        origin: "observe-internal",
+        fields: [
+          {
+            path: "result",
+            label: "Coordination between open tabs",
+            exposure: "none",
+            transform: { note: "own cbo_* lock names; serializes the SDK's storage updates across tabs" }
+          }
+        ]
+      },
+      this.seqLockName,
+      allocate,
+      {
+        timeoutMs,
+        onTimeout: () => {
+          this.logger.warn(`Sequence Web Lock acquisition timed out after ${timeoutMs}ms; using fallback`);
+          this.reportTelemetry("info", `seq web lock timeout; using fallback, ${timeoutMs}ms`);
+        }
       }
-    });
+    );
   }
   resolveTrackingSourcePath() {
     if (typeof window === "undefined") {
       return void 0;
     }
-    const search = applySourcePathQuery(
-      window.location.search,
+    return readSourcePath(
+      {
+        key: "page:location.source-path",
+        title: "Page path and allowed query parameters",
+        accessNote: "location.pathname and location.search; the query is reduced by the sourcePathQuery policy inside the reader (trackingSourcePath)",
+        group: "Page",
+        origin: "observe-external",
+        fields: [
+          { path: "url.path", label: "Page path", exposure: "raw" },
+          {
+            path: "url.query",
+            label: "Page address parameters (allowed ones only)",
+            exposure: "redacted",
+            transform: { note: "sourcePathQuery 'allowlist': values of non-allowlisted keys become '*'; 'all': raw" }
+          }
+        ]
+      },
       this.config.sourcePathQuery,
       this.config.sourcePathQueryAllow
     );
-    return `${window.location.pathname}${search}`;
   }
   /**
    * Per-tab id for event meta, cached after the first successful resolution: the id is
@@ -1535,56 +1599,18 @@ var CorbadoTracker = class _CorbadoTracker {
   smsOtpOperationFull(config) {
     return new SmsOtpOperationFull(this, config);
   }
-  /**
-   * Track a code from an authenticator app (TOTP) through its verification.
-   *
-   * @param config - Optional code input field(s) and spec type (`totp-login` or `totp-enrollment`).
-   * @remarks
-   * There is no send step: the code comes from the user's authenticator, not from the application.
-   * Report the verification request on postResponse. Bind the code input to capture typing and
-   * autofill; use setInputFields when the input is rendered after the operation starts.
-   * @example
-   * ```ts
-   * const totp = tracker.totpOperationFull({ explicitSpecType: "totp-login", inputHtmlField: codeInput });
-   * totp.postResponse.start({});
-   * totp.postResponse.finished({});
-   * ```
-   */
   totpOperationFull(config) {
     return new TotpOperationFull(this, config);
   }
   provideIdentifierOperationFull(config) {
-    return new OperationFullProvideIdentifierWithCUI(this, config);
+    return new OperationFullProvideIdentifierWithCUI(
+      this,
+      config
+    );
   }
   provideDataOperationFull(config) {
     return new ProvideDataOperationFull(this, config);
   }
-  /**
-   * Track one form: a page, step or modal where the user provides one coherent set of data and submits
-   * it, typically as one step of a custom process flow such as an onboarding.
-   *
-   * @param config - The form's stable `name` (required); optionally the names of its `fields`, the
-   *   `inputHtmlFields` to collect interaction signals from, and `startedAt` when the form became
-   *   visible earlier than this call.
-   * @remarks
-   * Create the operation when the form is shown; one operation per visit, so going back to a form
-   * creates a new one with the same name. Report `submit` when the application accepted the form, or
-   * `skip` when the user left it forward without submitting (e.g. "Do it later"). A form that ends with
-   * neither counts as abandoned; one whose last submit failed counts as failed. Without a name the form
-   * is not counted. Send field names only, never values. A form spread over several pages stays one
-   * operation: bind each page's inputs with `setInputFields`.
-   * @example
-   * ```ts
-   * const form = tracker.formOperationFull({ name: "personal-details", fields: ["firstName", "lastName"] });
-   * form.submit.start({});
-   * try {
-   *   await savePersonalDetails(values);
-   *   form.submit.finished({});
-   * } catch (error) {
-   *   form.submit.error(error);
-   * }
-   * ```
-   */
   formOperationFull(config) {
     return new FormOperationFull(this, config);
   }
@@ -1829,7 +1855,7 @@ var PROBE_PAGE_ID_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwx
 function randomProbePageId() {
   const bytes = new Uint8Array(16);
   try {
-    globalThis.crypto.getRandomValues(bytes);
+    crypto.getRandomValues(bytes);
   } catch {
     for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
   }

package/dist/analysis/config-manager.mjs

@@ -1,46 +1,188 @@
 // src/config-manager.ts
-import { cacheConfig, loadCachedConfig, parseReliabilityConfig } from "./config.mjs";
+import {
+  cacheConfigRecord,
+  CONFIG_STORAGE_KEY,
+  loadCachedConfig,
+  loadConfigRecord,
+  parseReliabilityConfig
+} from "./config.mjs";
+import { sendFetch } from "./readers/network.mjs";
+import { listenWindow, readDocumentHidden } from "./readers/page.mjs";
 var CONFIG_FETCH_TIMEOUT_MS = 10 * 1e3;
-var CONFIG_REFRESH_INTERVAL_MS = 10 * 60 * 1e3;
+var CONFIG_MIN_ATTEMPT_GAP_MS = 60 * 1e3;
+var CONFIG_DEFAULT_TTL_MS = 60 * 60 * 1e3;
+var CONFIG_MIN_TTL_MS = 5 * 60 * 1e3;
+var CONFIG_MAX_TTL_MS = 24 * 60 * 60 * 1e3;
 var CONFIG_RETRY_DELAYS_MS = [1e3, 3e3];
+function configTtlMs(headers) {
+  const maxAge = /(?:^|[\s,])max-age\s*=\s*"?(\d+)"?/i.exec(headers?.get("Cache-Control") ?? "");
+  if (!maxAge) return CONFIG_DEFAULT_TTL_MS;
+  const age = Number(headers?.get("Age") ?? 0);
+  const ttlMs = (Number(maxAge[1]) - (Number.isFinite(age) && age > 0 ? age : 0)) * 1e3;
+  return Math.min(Math.max(ttlMs, CONFIG_MIN_TTL_MS), CONFIG_MAX_TTL_MS);
+}
 var ConfigManager = class {
   constructor(url, storage, logger) {
     this.url = url;
     this.storage = storage;
     this.logger = logger;
     this.initialConfig = loadCachedConfig(storage) ?? void 0;
+    this.appliedVersion = this.initialConfig?.version;
   }
   initialConfig;
-  refreshTimer;
   requestTimer;
   retryTimer;
   controller;
+  removers = [];
   fetching = false;
   stopped = false;
+  lastAttemptAt;
+  /** Version last handed to (or initially applied by) the tracker. */
+  appliedVersion;
   onConfig;
   start(onConfig) {
     if (this.stopped || this.onConfig) return;
     this.onConfig = onConfig;
-    void this.fetchConfig();
+    this.listen();
+    this.refresh();
   }
-  async fetchConfig(attempt = 0) {
-    if (this.stopped || this.fetching) return;
-    if (attempt === 0) {
-      clearTimeout(this.refreshTimer);
+  listen() {
+    if (typeof window === "undefined") return;
+    const onVisibilityChange = () => {
+      const hidden = typeof document === "undefined" || readDocumentHidden({
+        key: "page:lifecycle.visibility",
+        title: "Page visibility",
+        accessNote: "document.visibilityState",
+        group: "Page lifecycle",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "visibilityState",
+            label: "Whether the page is hidden",
+            exposure: "enum",
+            transform: { values: ["hidden", "other"] }
+          }
+        ]
+      });
+      if (!hidden) this.refresh();
+    };
+    this.removers.push(
+      listenWindow(
+        {
+          key: "page:lifecycle.visibilitychange",
+          title: "Page visibility changes",
+          accessNote: "visibilitychange event on document",
+          group: "Page lifecycle",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "event.visibilitychange",
+              label: "Page hidden or shown again",
+              exposure: "presence",
+              transform: { note: "checks whether Observe settings are due for a refresh when the page is shown" }
+            }
+          ]
+        },
+        "visibilitychange",
+        onVisibilityChange
+      ),
+      listenWindow(
+        {
+          key: "page:lifecycle.pageshow",
+          title: "Returning to the page",
+          accessNote: "pageshow event on window, its persisted flag",
+          group: "Page lifecycle",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "event.persisted",
+              label: "Page restored from the browser's back/forward cache",
+              exposure: "presence",
+              transform: { note: "checks whether Observe settings are due for a refresh" }
+            }
+          ]
+        },
+        "pageshow",
+        (event) => {
+          if (event.persisted) this.refresh();
+        }
+      )
+    );
+  }
+  /** Fetches when the cached config is stale; adopts a fresh config another tab stored meanwhile. */
+  refresh() {
+    try {
+      if (this.stopped || this.fetching) return;
+      const now = Date.now();
+      const record = loadConfigRecord(this.storage);
+      const { fetchedAt, expiresAt } = record ?? {};
+      if (record?.endpoint === this.url && typeof fetchedAt === "number" && typeof expiresAt === "number" && fetchedAt > 0 && expiresAt - fetchedAt <= CONFIG_MAX_TTL_MS && fetchedAt <= now && now < expiresAt) {
+        if (record.config.version !== this.appliedVersion) {
+          this.appliedVersion = record.config.version;
+          this.onConfig?.(record.config);
+        }
+        return;
+      }
+      const sinceAttempt = this.lastAttemptAt === void 0 ? Infinity : now - this.lastAttemptAt;
+      if (sinceAttempt >= 0 && sinceAttempt < CONFIG_MIN_ATTEMPT_GAP_MS) return;
+      this.lastAttemptAt = now;
       clearTimeout(this.retryTimer);
-      this.refreshTimer = setTimeout(() => void this.fetchConfig(), CONFIG_REFRESH_INTERVAL_MS);
+      void this.fetchConfig();
+    } catch (error) {
+      this.logger.error("Unexpected error in SDK config refresh", error);
     }
+  }
+  async fetchConfig(attempt = 0) {
+    if (this.stopped || this.fetching) return;
     this.fetching = true;
     const controller = typeof AbortController !== "undefined" ? new AbortController() : void 0;
     this.controller = controller;
     this.requestTimer = controller ? setTimeout(() => controller.abort(), CONFIG_FETCH_TIMEOUT_MS) : void 0;
     let retryable = true;
     try {
-      const response = await fetch(this.url, {
-        method: "GET",
-        cache: "no-store",
-        ...controller ? { signal: controller.signal } : {}
-      });
+      const response = await sendFetch(
+        {
+          key: "network:observe.sdk-config",
+          title: "Observe settings download",
+          accessNote: "fetch to the Observe API; the response is the SDK reliability config",
+          group: "Event delivery",
+          origin: "observe-internal",
+          fields: [
+            { path: "response.status", label: "Response code", exposure: "raw" },
+            {
+              path: "response.header.retry-after",
+              label: "Whether the server asked to retry later",
+              exposure: "presence"
+            },
+            {
+              path: "response.header.cache-control",
+              label: "How long the server allows reusing the settings",
+              exposure: "computed",
+              transform: { note: "max-age, reduced to the settings' expiry time" }
+            },
+            {
+              path: "response.header.age",
+              label: "How long the settings were already stored on the way",
+              exposure: "computed",
+              transform: { note: "subtracted from max-age for the settings' expiry time" }
+            },
+            {
+              path: "response.body",
+              label: "Observe settings",
+              exposure: "raw",
+              transform: { note: "SDK reliability config" }
+            }
+          ]
+        },
+        this.url,
+        {
+          method: "GET",
+          // Revalidates the browser's HTTP cache entry (If-None-Match once the server sends an ETag)
+          // without a custom header, which would add a CORS preflight.
+          cache: "no-cache",
+          ...controller ? { signal: controller.signal } : {}
+        }
+      );
       if (!response.ok) {
         retryable = (response.status === 408 || response.status === 429 || response.status >= 500) && !response.headers.has("Retry-After");
         throw new Error(`SDK config request failed (${response.status})`);
@@ -50,7 +192,15 @@ var ConfigManager = class {
       const config = parseReliabilityConfig(raw);
       if (!config) throw new Error("Invalid SDK config response");
       if (this.stopped || controller?.signal.aborted) return;
-      cacheConfig(this.storage, config);
+      const now = Date.now();
+      cacheConfigRecord(this.storage, {
+        endpoint: this.url,
+        fetchedAt: now,
+        expiresAt: now + configTtlMs(response.headers),
+        config
+      });
+      if (loadConfigRecord(this.storage)) this.storage.removeItem(CONFIG_STORAGE_KEY);
+      this.appliedVersion = config.version;
       this.onConfig?.(config);
     } catch (error) {
       if (!this.stopped) {
@@ -69,7 +219,7 @@ var ConfigManager = class {
   }
   destroy() {
     this.stopped = true;
-    clearTimeout(this.refreshTimer);
+    this.removers.splice(0).forEach((remove) => remove());
     clearTimeout(this.requestTimer);
     clearTimeout(this.retryTimer);
     this.controller?.abort();
@@ -77,7 +227,11 @@ var ConfigManager = class {
   }
 };
 export {
+  CONFIG_DEFAULT_TTL_MS,
   CONFIG_FETCH_TIMEOUT_MS,
-  CONFIG_REFRESH_INTERVAL_MS,
-  ConfigManager
+  CONFIG_MAX_TTL_MS,
+  CONFIG_MIN_ATTEMPT_GAP_MS,
+  CONFIG_MIN_TTL_MS,
+  ConfigManager,
+  configTtlMs
 };

package/dist/analysis/config.mjs

@@ -1,5 +1,6 @@
 // src/config.ts
 var CONFIG_STORAGE_KEY = "cbo_sdk_config";
+var CONFIG_CACHE_STORAGE_KEY = "cbo_sdk_config_cache";
 var CONFIG_REQUEST_HEADER = "X-Corbado-Observe-Config";
 var DEFAULT_FLUSH_INTERVAL_MS = 500;
 var DEFAULT_SEQ_LOCK_TIMEOUT_MS = 50;
@@ -193,14 +194,20 @@ function resolveFixedDataConfig(raw) {
     return void 0;
   }
 }
+function loadConfigRecord(storage) {
+  const record = storage.getItem(CONFIG_CACHE_STORAGE_KEY);
+  const config = record && typeof record === "object" ? parseReliabilityConfig(record.config) : null;
+  return config ? { ...record, config } : null;
+}
 function loadCachedConfig(storage) {
-  return parseReliabilityConfig(storage.getItem(CONFIG_STORAGE_KEY));
+  return loadConfigRecord(storage)?.config ?? parseReliabilityConfig(storage.getItem(CONFIG_STORAGE_KEY));
 }
-function cacheConfig(storage, config) {
-  storage.setItem(CONFIG_STORAGE_KEY, config);
+function cacheConfigRecord(storage, record) {
+  storage.setItem(CONFIG_CACHE_STORAGE_KEY, record);
 }
 export {
   CONFIG_BOUNDS,
+  CONFIG_CACHE_STORAGE_KEY,
   CONFIG_REQUEST_HEADER,
   CONFIG_STORAGE_KEY,
   DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS,
@@ -208,8 +215,9 @@ export {
   DEFAULT_RELIABILITY_CONFIG,
   DEFAULT_SEQ_LOCK_TIMEOUT_MS,
   DEFAULT_SESSION_INACTIVITY_MS,
-  cacheConfig,
+  cacheConfigRecord,
   loadCachedConfig,
+  loadConfigRecord,
   parseReliabilityConfig,
   resolveFixedDataConfig,
   resolveReliabilityConfig

package/dist/analysis/device-info-manager.mjs

@@ -1,6 +1,21 @@
 // src/device-info-manager.ts
+import { readDocumentHidden } from "./readers/page.mjs";
 function isDocumentHidden() {
-  return typeof document !== "undefined" && document.visibilityState === "hidden";
+  return typeof document !== "undefined" && readDocumentHidden({
+    key: "page:lifecycle.visibility",
+    title: "Page visibility",
+    accessNote: "document.visibilityState",
+    group: "Page lifecycle",
+    origin: "observe-external",
+    fields: [
+      {
+        path: "visibilityState",
+        label: "Whether the page is hidden",
+        exposure: "enum",
+        transform: { values: ["hidden", "other"] }
+      }
+    ]
+  });
 }
 var DeviceInfoManager = class {
   constructor(logger, source, refreshInterval, attachInterval, diagnostics, onUndelivered) {

package/dist/analysis/device.mjs

@@ -180,7 +180,18 @@ var DeviceCollector = class {
         "navigator.bluetooth.getAvailability",
         () => readBluetoothAvailability({
           key: "browser-api:device.bluetooth-availability",
-          fields: [{ path: "result", exposure: "enum", transform: { values: [true, false] } }]
+          title: "Bluetooth availability",
+          accessNote: "navigator.bluetooth.getAvailability()",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "result",
+              label: "Whether Bluetooth is available",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            }
+          ]
         })
       ),
       this.startField(
@@ -188,9 +199,14 @@ var DeviceCollector = class {
         "PublicKeyCredential.getClientCapabilities",
         () => readClientCapabilities({
           key: "browser-api:device.client-capabilities",
+          title: "Passkey features supported by the browser",
+          accessNote: "PublicKeyCredential.getClientCapabilities(), every returned key",
+          group: "Device information",
+          origin: "observe-external",
           fields: [
             {
               path: "result.<capability>",
+              label: "Supported passkey features",
               exposure: "enum",
               transform: { values: ["true", "false"], note: "open set of capability names, kept as reported" }
             }
@@ -202,7 +218,18 @@ var DeviceCollector = class {
         "PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable",
         () => readUserVerifyingPlatformAuthenticatorAvailable({
           key: "browser-api:device.uvpaa",
-          fields: [{ path: "result", exposure: "enum", transform: { values: [true, false] } }]
+          title: "Built-in passkey support on the device",
+          accessNote: "PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "result",
+              label: "Whether the device has a built-in passkey authenticator",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            }
+          ]
         })
       ),
       this.startField(
@@ -210,7 +237,18 @@ var DeviceCollector = class {
         "PublicKeyCredential.isConditionalMediationAvailable",
         () => readConditionalMediationAvailable({
           key: "browser-api:device.conditional-mediation",
-          fields: [{ path: "result", exposure: "enum", transform: { values: [true, false] } }]
+          title: "Passkey autofill availability",
+          accessNote: "PublicKeyCredential.isConditionalMediationAvailable()",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "result",
+              label: "Whether passkey autofill is available",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            }
+          ]
         })
       ),
       this.startField(
@@ -218,11 +256,20 @@ var DeviceCollector = class {
         "navigator.userAgentData.getHighEntropyValues",
         () => readJavaScriptHighEntropy({
           key: "browser-api:device.ua-high-entropy",
+          title: "Device platform, version and model reported by the browser",
+          accessNote: "User-Agent Client Hints: navigator.userAgentData.getHighEntropyValues()",
+          group: "Device information",
+          origin: "observe-external",
           fields: [
-            { path: "result.platform", exposure: "raw" },
-            { path: "result.mobile", exposure: "enum", transform: { values: [true, false] } },
-            { path: "result.platformVersion", exposure: "raw" },
-            { path: "result.model", exposure: "raw" }
+            { path: "result.platform", label: "Operating system", exposure: "raw" },
+            {
+              path: "result.mobile",
+              label: "Whether the device is a mobile device",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            },
+            { path: "result.platformVersion", label: "Operating system version", exposure: "raw" },
+            { path: "result.model", label: "Device model", exposure: "raw" }
           ]
         })
       ),
@@ -231,7 +278,18 @@ var DeviceCollector = class {
         "navigator.webdriver",
         () => readWebdriver({
           key: "browser-api:device.webdriver",
-          fields: [{ path: "result", exposure: "enum", transform: { values: [true, false] } }]
+          title: "Browser automation flag",
+          accessNote: "navigator.webdriver",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [
+            {
+              path: "result",
+              label: "Whether the browser is controlled by automation",
+              exposure: "enum",
+              transform: { values: [true, false] }
+            }
+          ]
         })
       ),
       this.startField(
@@ -239,7 +297,11 @@ var DeviceCollector = class {
         "navigator.maxTouchPoints",
         () => readMaxTouchPoints({
           key: "browser-api:device.max-touch-points",
-          fields: [{ path: "result", exposure: "raw" }]
+          title: "Touch screen support",
+          accessNote: "navigator.maxTouchPoints",
+          group: "Device information",
+          origin: "observe-external",
+          fields: [{ path: "result", label: "Number of touch points of the screen", exposure: "raw" }]
         })
       )
     ];
@@ -377,7 +439,18 @@ var DeviceCollector = class {
       source,
       () => typeof __CBO_DATA_PRIVATE_MODE__ === "boolean" && !__CBO_DATA_PRIVATE_MODE__ ? void 0 : readPrivateMode({
         key: "browser-api:device.private-mode",
-        fields: [{ path: "result.isPrivate", exposure: "enum", transform: { values: [true, false] } }],
+        title: "Private browsing mode",
+        accessNote: "detectincognitojs library (IndexedDB, storage quota and browser-specific probes)",
+        group: "Device information",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "result.isPrivate",
+            label: "Whether private browsing is on",
+            exposure: "enum",
+            transform: { values: [true, false] }
+          }
+        ],
         dataConfig: "privateMode"
       })
     );
@@ -456,9 +529,14 @@ var DeviceCollector = class {
   static getUserAgent() {
     return readUserAgent({
       key: "browser-api:device.user-agent",
+      title: "Browser and operating system",
+      accessNote: "navigator.userAgent",
+      group: "Device information",
+      origin: "observe-external",
       fields: [
         {
           path: "result",
+          label: "Browser and operating system",
           exposure: "class",
           transform: {
             classes: [

package/dist/analysis/handoff.mjs

@@ -0,0 +1,7 @@
+// src/handoff.ts
+function acceptHandoffs(step) {
+  return step;
+}
+export {
+  acceptHandoffs
+};