@a14y/telemetry 0.1.0 → 0.1.1

package/dist/cjs/core/types.d.ts

@@ -1,6 +1,6 @@
 import type { Adapter } from '../adapters/types';
 export type AppName = 'cli' | 'extension' | 'docs';
-export type EventName = 'cli_command_invoked' | 'cli_run_completed' | 'cli_error' | 'cli_telemetry_disabled' | 'ext_installed' | 'ext_audit_started' | 'ext_audit_completed' | 'ext_audit_error' | 'ext_settings_changed' | 'docs_section_view' | 'outbound_click';
+export type EventName = 'cli_command_invoked' | 'cli_run_completed' | 'cli_error' | 'cli_telemetry_disabled' | 'ext_installed' | 'ext_audit_started' | 'ext_audit_completed' | 'ext_audit_error' | 'ext_settings_changed' | 'docs_section_view' | 'outbound_click' | 'scorecard_check_result';
 export type EventParamValue = string | number | boolean;
 export interface TelemetryEvent {
     name: string;

package/dist/cjs/index.d.ts

@@ -5,3 +5,4 @@ export type { AppName, EventName, EventParamValue, TelemetryEvent, ConfigProvide
 export { noopAdapter } from './adapters/noop';
 export { createGa4MpAdapter, type Ga4MpAdapterOptions } from './adapters/ga4-mp';
 export type { Adapter, AdapterPayload } from './adapters/types';
+export { generateRunId, rollupPageStatuses, trackScorecardCheckResult, emitScorecardChecksFromRun, type ScorecardCheckStatus, type TelemetrySurface, type PageStatusRollup, type ScorecardCheckResultParams, type ScorecardRunLike, type EmitScorecardChecksFromRunOptions, } from './scorecard';

package/dist/cjs/index.js

@@ -6,7 +6,7 @@
 // Splitting them out keeps the extension bundle from pulling in `fs`/`os`
 // and the Node consumers from pulling in the chrome.* type surface.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createGa4MpAdapter = exports.noopAdapter = exports.isValidEventName = exports.errorClassName = exports.sanitizeProps = exports.bucketDurationMs = exports.bucketIssueCount = exports.bucketPageCount = exports.bucketScore = exports.shutdown = exports.flush = exports.isEnabled = exports.setEnabled = exports.track = exports.init = void 0;
+exports.emitScorecardChecksFromRun = exports.trackScorecardCheckResult = exports.rollupPageStatuses = exports.generateRunId = exports.createGa4MpAdapter = exports.noopAdapter = exports.isValidEventName = exports.errorClassName = exports.sanitizeProps = exports.bucketDurationMs = exports.bucketIssueCount = exports.bucketPageCount = exports.bucketScore = exports.shutdown = exports.flush = exports.isEnabled = exports.setEnabled = exports.track = exports.init = void 0;
 var tracker_1 = require("./core/tracker");
 Object.defineProperty(exports, "init", { enumerable: true, get: function () { return tracker_1.init; } });
 Object.defineProperty(exports, "track", { enumerable: true, get: function () { return tracker_1.track; } });
@@ -27,3 +27,8 @@ var noop_1 = require("./adapters/noop");
 Object.defineProperty(exports, "noopAdapter", { enumerable: true, get: function () { return noop_1.noopAdapter; } });
 var ga4_mp_1 = require("./adapters/ga4-mp");
 Object.defineProperty(exports, "createGa4MpAdapter", { enumerable: true, get: function () { return ga4_mp_1.createGa4MpAdapter; } });
+var scorecard_1 = require("./scorecard");
+Object.defineProperty(exports, "generateRunId", { enumerable: true, get: function () { return scorecard_1.generateRunId; } });
+Object.defineProperty(exports, "rollupPageStatuses", { enumerable: true, get: function () { return scorecard_1.rollupPageStatuses; } });
+Object.defineProperty(exports, "trackScorecardCheckResult", { enumerable: true, get: function () { return scorecard_1.trackScorecardCheckResult; } });
+Object.defineProperty(exports, "emitScorecardChecksFromRun", { enumerable: true, get: function () { return scorecard_1.emitScorecardChecksFromRun; } });

package/dist/cjs/scorecard.d.ts

@@ -0,0 +1,69 @@
+export type ScorecardCheckStatus = 'pass' | 'fail' | 'warn' | 'error' | 'na';
+export type TelemetrySurface = 'cli' | 'ext';
+/**
+ * Generate a per-run identifier. 8 hex chars (32 bits) is plenty — runs are
+ * scoped to a single GA4 property and at any realistic volume the collision
+ * probability inside a query window is negligible. We deliberately keep it
+ * short so the GA4 param-length budget stays generous for other dimensions.
+ */
+export declare function generateRunId(): string;
+export interface PageStatusRollup {
+    status: ScorecardCheckStatus;
+    failedPages: number;
+    totalPages: number;
+}
+/**
+ * Roll up a page-level check's per-page outcomes into one run-level outcome.
+ * Precedence is fail > error > warn > pass > na: any page failing wins, then
+ * any page erroring, etc. `na` only wins when every page returned `na`. The
+ * returned shape also exposes failed_pages / total_pages so analytics can
+ * distinguish "1 of 50 pages failed" from "all 50 failed".
+ */
+export declare function rollupPageStatuses(statuses: ScorecardCheckStatus[]): PageStatusRollup;
+export interface ScorecardCheckResultParams {
+    runId: string;
+    checkId: string;
+    status: ScorecardCheckStatus;
+    scorecardVersion: string;
+    surface: TelemetrySurface;
+    /** Page-level checks: number of pages that returned `fail`. */
+    failedPages?: number;
+    /** Page-level checks: total number of pages this check ran against. */
+    totalPages?: number;
+}
+/**
+ * Emit one `scorecard_check_result` event. Wraps the underlying tracker so
+ * callers don't reach for the GA4 event name directly and so the payload
+ * shape is type-checked.
+ */
+export declare function trackScorecardCheckResult(p: ScorecardCheckResultParams): void;
+/**
+ * Duck-typed shape of a scorecard run. Defined locally so this package
+ * doesn't take a dependency on @a14y/core; callers pass the relevant slice
+ * of their own SiteRun. `status` accepts any string and is narrowed to a
+ * `ScorecardCheckStatus` at emit time.
+ */
+export interface ScorecardRunLike {
+    scorecardVersion: string;
+    siteChecks: ReadonlyArray<{
+        id: string;
+        status: string;
+    }>;
+    pages: ReadonlyArray<{
+        checks: ReadonlyArray<{
+            id: string;
+            status: string;
+        }>;
+    }>;
+}
+export interface EmitScorecardChecksFromRunOptions {
+    run: ScorecardRunLike;
+    runId: string;
+    surface: TelemetrySurface;
+}
+/**
+ * Emit one `scorecard_check_result` per stable check id in `run`. Site-level
+ * checks pass through their status verbatim; page-level checks are rolled up
+ * across pages. Returns the number of events emitted (mostly for tests).
+ */
+export declare function emitScorecardChecksFromRun(opts: EmitScorecardChecksFromRunOptions): number;

package/dist/cjs/scorecard.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRunId = generateRunId;
+exports.rollupPageStatuses = rollupPageStatuses;
+exports.trackScorecardCheckResult = trackScorecardCheckResult;
+exports.emitScorecardChecksFromRun = emitScorecardChecksFromRun;
+const tracker_1 = require("./core/tracker");
+const HEX = '0123456789abcdef';
+/**
+ * Generate a per-run identifier. 8 hex chars (32 bits) is plenty — runs are
+ * scoped to a single GA4 property and at any realistic volume the collision
+ * probability inside a query window is negligible. We deliberately keep it
+ * short so the GA4 param-length budget stays generous for other dimensions.
+ */
+function generateRunId() {
+    const bytes = new Uint8Array(4);
+    const g = globalThis;
+    if (g.crypto?.getRandomValues) {
+        g.crypto.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    }
+    let out = '';
+    for (let i = 0; i < bytes.length; i++) {
+        out += HEX[(bytes[i] >> 4) & 0xf] + HEX[bytes[i] & 0xf];
+    }
+    return out;
+}
+/**
+ * Roll up a page-level check's per-page outcomes into one run-level outcome.
+ * Precedence is fail > error > warn > pass > na: any page failing wins, then
+ * any page erroring, etc. `na` only wins when every page returned `na`. The
+ * returned shape also exposes failed_pages / total_pages so analytics can
+ * distinguish "1 of 50 pages failed" from "all 50 failed".
+ */
+function rollupPageStatuses(statuses) {
+    let failed = 0;
+    let errored = 0;
+    let warned = 0;
+    let passed = 0;
+    for (const s of statuses) {
+        if (s === 'fail')
+            failed++;
+        else if (s === 'error')
+            errored++;
+        else if (s === 'warn')
+            warned++;
+        else if (s === 'pass')
+            passed++;
+    }
+    let status;
+    if (failed > 0)
+        status = 'fail';
+    else if (errored > 0)
+        status = 'error';
+    else if (warned > 0)
+        status = 'warn';
+    else if (passed > 0)
+        status = 'pass';
+    else
+        status = 'na';
+    return { status, failedPages: failed, totalPages: statuses.length };
+}
+/**
+ * Emit one `scorecard_check_result` event. Wraps the underlying tracker so
+ * callers don't reach for the GA4 event name directly and so the payload
+ * shape is type-checked.
+ */
+function trackScorecardCheckResult(p) {
+    const params = {
+        run_id: p.runId,
+        check_id: p.checkId,
+        status: p.status,
+        scorecard_version: p.scorecardVersion,
+        surface: p.surface,
+    };
+    if (typeof p.failedPages === 'number')
+        params.failed_pages = p.failedPages;
+    if (typeof p.totalPages === 'number')
+        params.total_pages = p.totalPages;
+    (0, tracker_1.track)('scorecard_check_result', params);
+}
+/**
+ * Emit one `scorecard_check_result` per stable check id in `run`. Site-level
+ * checks pass through their status verbatim; page-level checks are rolled up
+ * across pages. Returns the number of events emitted (mostly for tests).
+ */
+function emitScorecardChecksFromRun(opts) {
+    const { run, runId, surface } = opts;
+    let count = 0;
+    for (const check of run.siteChecks) {
+        trackScorecardCheckResult({
+            runId,
+            checkId: check.id,
+            status: check.status,
+            scorecardVersion: run.scorecardVersion,
+            surface,
+        });
+        count++;
+    }
+    const byCheckId = new Map();
+    for (const page of run.pages) {
+        for (const check of page.checks) {
+            const arr = byCheckId.get(check.id);
+            if (arr)
+                arr.push(check.status);
+            else
+                byCheckId.set(check.id, [check.status]);
+        }
+    }
+    for (const [checkId, statuses] of byCheckId) {
+        const rollup = rollupPageStatuses(statuses);
+        trackScorecardCheckResult({
+            runId,
+            checkId,
+            status: rollup.status,
+            scorecardVersion: run.scorecardVersion,
+            surface,
+            failedPages: rollup.failedPages,
+            totalPages: rollup.totalPages,
+        });
+        count++;
+    }
+    return count;
+}

package/dist/esm/index.js

@@ -9,3 +9,4 @@ export { bucketScore, bucketPageCount, bucketIssueCount, bucketDurationMs, } fro
 export { sanitizeProps, errorClassName, isValidEventName } from './core/sanitize';
 export { noopAdapter } from './adapters/noop';
 export { createGa4MpAdapter } from './adapters/ga4-mp';
+export { generateRunId, rollupPageStatuses, trackScorecardCheckResult, emitScorecardChecksFromRun, } from './scorecard';

package/dist/esm/scorecard.js

@@ -0,0 +1,121 @@
+import { track } from './core/tracker';
+const HEX = '0123456789abcdef';
+/**
+ * Generate a per-run identifier. 8 hex chars (32 bits) is plenty — runs are
+ * scoped to a single GA4 property and at any realistic volume the collision
+ * probability inside a query window is negligible. We deliberately keep it
+ * short so the GA4 param-length budget stays generous for other dimensions.
+ */
+export function generateRunId() {
+    const bytes = new Uint8Array(4);
+    const g = globalThis;
+    if (g.crypto?.getRandomValues) {
+        g.crypto.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    }
+    let out = '';
+    for (let i = 0; i < bytes.length; i++) {
+        out += HEX[(bytes[i] >> 4) & 0xf] + HEX[bytes[i] & 0xf];
+    }
+    return out;
+}
+/**
+ * Roll up a page-level check's per-page outcomes into one run-level outcome.
+ * Precedence is fail > error > warn > pass > na: any page failing wins, then
+ * any page erroring, etc. `na` only wins when every page returned `na`. The
+ * returned shape also exposes failed_pages / total_pages so analytics can
+ * distinguish "1 of 50 pages failed" from "all 50 failed".
+ */
+export function rollupPageStatuses(statuses) {
+    let failed = 0;
+    let errored = 0;
+    let warned = 0;
+    let passed = 0;
+    for (const s of statuses) {
+        if (s === 'fail')
+            failed++;
+        else if (s === 'error')
+            errored++;
+        else if (s === 'warn')
+            warned++;
+        else if (s === 'pass')
+            passed++;
+    }
+    let status;
+    if (failed > 0)
+        status = 'fail';
+    else if (errored > 0)
+        status = 'error';
+    else if (warned > 0)
+        status = 'warn';
+    else if (passed > 0)
+        status = 'pass';
+    else
+        status = 'na';
+    return { status, failedPages: failed, totalPages: statuses.length };
+}
+/**
+ * Emit one `scorecard_check_result` event. Wraps the underlying tracker so
+ * callers don't reach for the GA4 event name directly and so the payload
+ * shape is type-checked.
+ */
+export function trackScorecardCheckResult(p) {
+    const params = {
+        run_id: p.runId,
+        check_id: p.checkId,
+        status: p.status,
+        scorecard_version: p.scorecardVersion,
+        surface: p.surface,
+    };
+    if (typeof p.failedPages === 'number')
+        params.failed_pages = p.failedPages;
+    if (typeof p.totalPages === 'number')
+        params.total_pages = p.totalPages;
+    track('scorecard_check_result', params);
+}
+/**
+ * Emit one `scorecard_check_result` per stable check id in `run`. Site-level
+ * checks pass through their status verbatim; page-level checks are rolled up
+ * across pages. Returns the number of events emitted (mostly for tests).
+ */
+export function emitScorecardChecksFromRun(opts) {
+    const { run, runId, surface } = opts;
+    let count = 0;
+    for (const check of run.siteChecks) {
+        trackScorecardCheckResult({
+            runId,
+            checkId: check.id,
+            status: check.status,
+            scorecardVersion: run.scorecardVersion,
+            surface,
+        });
+        count++;
+    }
+    const byCheckId = new Map();
+    for (const page of run.pages) {
+        for (const check of page.checks) {
+            const arr = byCheckId.get(check.id);
+            if (arr)
+                arr.push(check.status);
+            else
+                byCheckId.set(check.id, [check.status]);
+        }
+    }
+    for (const [checkId, statuses] of byCheckId) {
+        const rollup = rollupPageStatuses(statuses);
+        trackScorecardCheckResult({
+            runId,
+            checkId,
+            status: rollup.status,
+            scorecardVersion: run.scorecardVersion,
+            surface,
+            failedPages: rollup.failedPages,
+            totalPages: rollup.totalPages,
+        });
+        count++;
+    }
+    return count;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a14y/telemetry",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Anonymous, opt-out telemetry shim shared by the a14y CLI and Chrome extension. Provider-agnostic core with a built-in GA4 Measurement Protocol adapter.",
   "license": "Apache-2.0",
   "repository": {