@usefidel/contracts 0.6.0 → 0.8.0

package/dist/analytics.d.ts

@@ -0,0 +1,354 @@
+/**
+ * Analytics contract — GA Phase 1.
+ *
+ * ONE vocabulary for client analytics event names and their property shapes,
+ * shared by `usefidel/usefidel` (extension, admin) and `usefidel/fidel-web`
+ * (webapp, landing).
+ *
+ * WHY THIS IS A PACKAGE AND NOT A LOCAL FILE PER SURFACE.
+ * The webapp and the extension each identified the same human under a
+ * different PostHog `distinct_id` — the webapp by Supabase UUID-or-email, the
+ * extension by email-or-Figma-handle. `extension/src/lib/posthog.ts` carried a
+ * comment asserting the two agreed. They did not. Nothing failed; retention
+ * cohorts were simply wrong, and stayed wrong, because the two "authoritative"
+ * definitions lived in two repositories with no gate between them.
+ *
+ * The package is the only mechanism that spans both repositories.
+ *
+ * WHAT THIS OWNS: event NAMES and property TYPES.
+ * WHAT IT DOES NOT OWN: SDK initialization, identity resolution, storage,
+ * environment detection, redaction, or any `posthog.*` call. Those stay in a
+ * per-surface wrapper, because they differ per surface in ways a shared module
+ * would have to branch on — and a shared module full of surface branches is
+ * how the last divergence started.
+ *
+ * NARROWNESS (see index.ts). This file adds runtime values — two frozen name
+ * arrays and one error-code-to-phase map. That is the same shape as
+ * `RUN_ERROR_CODES`, which this package already publishes. It carries no
+ * engine, no endpoint, no credential, and no backend logic. Event names
+ * describe which buttons exist, which a contractor installing the package can
+ * already observe by using the product.
+ */
+import { type RunErrorCode } from './run-errors.js';
+/**
+ * Schema version stamped on every event emitted by a contract-aware wrapper.
+ *
+ * Version 1 is everything emitted before the GA cutover: mixed identity,
+ * success events that fired before the operation succeeded, camelCase and
+ * snake_case properties side by side. Version 2 is this contract.
+ *
+ * The versions are NOT semantically comparable and must never be summed in one
+ * tile. Identity is preserved across the cutover by aliasing, so a person's
+ * history survives; the meaning of their events does not.
+ */
+export declare const ANALYTICS_SCHEMA_VERSION: 2;
+/** Which client emitted the event. Server-side surfaces do not emit at all. */
+export type AnalyticsSurface = 'landing' | 'webapp' | 'extension';
+/** Which deployment emitted the event. Drives the default dashboard filter. */
+export type AnalyticsEnvironment = 'production' | 'staging' | 'development';
+/**
+ * Validation mode.
+ *
+ * Mirrors the `validation_runs.validation_mode` CHECK constraint —
+ * migration 096 established `figma_vs_live` / `url_vs_url`, migration 098
+ * added `design_system_vs_live`. Kept in step by `check-canonical-sync.mjs`.
+ */
+export type ValidationMode = 'figma_vs_live' | 'url_vs_url' | 'design_system_vs_live';
+/**
+ * How much of the required scope Fidel actually inspected.
+ *
+ * STRUCTURAL COPY of `EvidenceState` in
+ * `supabase/functions/_shared/result-completeness.ts` (plan 051 P1-5), which
+ * is the canonical definition and is vendor-synced to the Lambda and the
+ * marketplace Action. `check-canonical-sync.mjs` asserts this union matches
+ * that one exactly.
+ *
+ * Present ONLY on `design_system_vs_live` runs. Absent on every other mode by
+ * design — see `WebValidationCompletedProperties.result_completeness`.
+ */
+export type ResultCompleteness = 'complete' | 'partial' | 'unverified' | 'configuration_required' | 'operational_failure';
+/**
+ * Which stage of a run failed.
+ *
+ * DERIVED, never stored. `validation_runs` has `error_code` but no
+ * `error_phase` column, so phase is computed from the code by
+ * `errorPhaseFor()` below. That keeps one source of truth (the taxonomy) and
+ * means admin can group failures by phase today without a migration.
+ */
+export type ValidationErrorPhase = 
+/** The submitted URLs were rejected before any work started. */
+'input_validation'
+/** Could not reach, load, or authenticate against the live target. */
+ | 'target_capture'
+/** Could not read the Figma file. */
+ | 'figma_fetch'
+/** The design system or brand context could not be resolved. */
+ | 'design_system_resolve'
+/** The matching pipeline ran and failed, or produced nothing usable. */
+ | 'pipeline'
+/** The run completed but the result could not be written. */
+ | 'persist'
+/** Unclassified. A growing count here means the taxonomy needs a code. */
+ | 'unknown';
+/**
+ * Every run error code, mapped to the phase it belongs to.
+ *
+ * EXHAUSTIVE BY CONSTRUCTION: the `Record<RunErrorCode, …>` type means adding
+ * a code to the taxonomy without assigning it a phase is a compile error in
+ * this package, which is a merge gate in both repositories. That is deliberate
+ * — the alternative is a default branch, and a default branch silently files
+ * every new code under `unknown`.
+ */
+export declare const ERROR_CODE_PHASE: Record<RunErrorCode, ValidationErrorPhase>;
+/**
+ * Phase for a code, tolerating values from outside the taxonomy.
+ *
+ * The admin dashboard reads `error_code` out of Postgres, where it is a bare
+ * TEXT column with no FK to the taxonomy. A row written by an older deploy can
+ * therefore hold a code this build has never heard of. Returning `'unknown'`
+ * for that is right; throwing would take down the tile.
+ */
+export declare function errorPhaseFor(code: string | null | undefined): ValidationErrorPhase;
+/** True when `code` is a member of the current taxonomy. */
+export declare function isKnownErrorCode(code: string | null | undefined): code is RunErrorCode;
+/** Events the GA dashboard is built on. Typed properties, specified triggers. */
+export declare const GA_EVENT_NAMES: readonly ["signup_started", "signup_completed", "onboarding_started", "onboarding_completed", "figma_connected", "environment_connected", "web_validation_started", "web_validation_completed", "web_validation_failed", "web_validation_cancelled", "report_viewed", "report_shared", "diff_mark_resolved", "upgrade_clicked", "checkout_started", "feedback_submitted", "extension_opened", "validation_start", "validation_accepted", "validation_complete", "validation_error", "validation_cancel", "review_saved", "figma_auth_success", "figma_auth_error", "extension_share_copied", "upgrade_modal_viewed", "upgrade_cta_clicked"];
+/**
+ * Events that exist but are NOT GA metrics.
+ *
+ * `checkout_completed` is here rather than in `GA_EVENT_NAMES` deliberately.
+ * It fires in the browser on return from Stripe, which is neither reliable
+ * (the tab can be closed) nor authoritative (the webhook is). Paid conversion
+ * comes from `teams.subscription_status` and Stripe. This event is a funnel
+ * diagnostic for "did the user come back", nothing more, and must be labelled
+ * as such wherever it appears.
+ */
+export declare const SECONDARY_EVENT_NAMES: readonly ["checkout_completed", "console_errors", "diff_expanded", "drawer_filter_changed", "review_save_error", "review_verdict", "review_verdict_all", "screenshot_exported", "ui_crash", "validation_resume", "validation_retry", "view_changed", "auth_refresh", "consensus_complete", "consensus_error", "extension_validation_failed", "idempotency_dedup_client", "pipeline_complete", "pipeline_phase", "pipeline_resume", "rate_limit_hit", "upgrade_wall_hit"];
+/** Every event name any Fidel client may emit. */
+export declare const ANALYTICS_EVENT_NAMES: readonly ["signup_started", "signup_completed", "onboarding_started", "onboarding_completed", "figma_connected", "environment_connected", "web_validation_started", "web_validation_completed", "web_validation_failed", "web_validation_cancelled", "report_viewed", "report_shared", "diff_mark_resolved", "upgrade_clicked", "checkout_started", "feedback_submitted", "extension_opened", "validation_start", "validation_accepted", "validation_complete", "validation_error", "validation_cancel", "review_saved", "figma_auth_success", "figma_auth_error", "extension_share_copied", "upgrade_modal_viewed", "upgrade_cta_clicked", "checkout_completed", "console_errors", "diff_expanded", "drawer_filter_changed", "review_save_error", "review_verdict", "review_verdict_all", "screenshot_exported", "ui_crash", "validation_resume", "validation_retry", "view_changed", "auth_refresh", "consensus_complete", "consensus_error", "extension_validation_failed", "idempotency_dedup_client", "pipeline_complete", "pipeline_phase", "pipeline_resume", "rate_limit_hit", "upgrade_wall_hit"];
+export type GaEventName = (typeof GA_EVENT_NAMES)[number];
+export type SecondaryEventName = (typeof SECONDARY_EVENT_NAMES)[number];
+export type AnalyticsEventName = GaEventName | SecondaryEventName;
+/**
+ * Stamped on every schema-2 event by the wrapper, not by call sites.
+ *
+ * `team_id` and `is_internal` are optional because the extension cannot get
+ * them without a network request it is not allowed to make: `team_id` lives in
+ * `profiles`, not in the Supabase JWT. Team-level analysis uses
+ * `validation_runs.team_id` in the database instead. The webapp has both and
+ * always sends them.
+ *
+ * There is no `user_id` field. The Supabase UUID is the `distinct_id`;
+ * duplicating it as a property invites two sources of truth for identity.
+ */
+export interface AnalyticsContext {
+    analytics_schema_version: typeof ANALYTICS_SCHEMA_VERSION;
+    environment: AnalyticsEnvironment;
+    surface: AnalyticsSurface;
+    /** Git SHA (webapp/landing) or `manifest.json` version (extension). */
+    release: string;
+    team_id?: string;
+    is_internal?: boolean;
+}
+/**
+ * Person properties. Set on identify, never sent as event properties.
+ *
+ * `email` is a person property and not a `distinct_id` — that distinction is
+ * the entire identity migration. See plan §3.
+ */
+export interface AnalyticsPersonProperties {
+    email?: string;
+    figma_handle?: string;
+    team_id?: string;
+    plan?: string;
+    subscription_status?: string;
+    is_internal?: boolean;
+}
+/** Properties common to every validation event, on both clients. */
+export interface ValidationEventProperties {
+    /** `validation_runs.id`. The join key across PostHog, Postgres and Sentry. */
+    run_id: string;
+    validation_mode: ValidationMode;
+}
+export interface ValidationStartedProperties extends ValidationEventProperties {
+    viewport?: string;
+    is_revalidation?: boolean;
+}
+export interface WebValidationCompletedProperties extends ValidationEventProperties {
+    duration_ms: number;
+    /**
+     * Confirmed violations, per the result contract.
+     *
+     * For `design_system_vs_live` this is `driftCount + offTokenCount` and is
+     * `null` when either half is unavailable. It is NEVER `diffs.length`:
+     * that array also holds `unused` and `scoped` findings, and printing it as a
+     * violation count is the exact defect plan 051 P1-5 was written to close.
+     *
+     * `null` means "the producer told us nothing", which is not zero.
+     */
+    violation_count: number | null;
+    /**
+     * ABSENT on `figma_vs_live` and `url_vs_url` runs — the pipeline only emits
+     * a completeness block for `design_system_vs_live`. Absence here is correct
+     * behaviour and not an instrumentation failure; any tile using it must be
+     * scoped to DS runs.
+     */
+    result_completeness?: ResultCompleteness;
+}
+/**
+ * A run that failed or was cancelled.
+ *
+ * `run_id` is NULLABLE here and required on the success events, and the
+ * asymmetry is the point: a run rejected BEFORE the backend accepted it — the
+ * upgrade wall, a rate limit, an invalid URL — never received an id. Requiring
+ * one would force those events to be dropped, and they are the failures most
+ * worth counting. `null` means "rejected before acceptance"; a string means
+ * "accepted, then failed".
+ */
+export interface ValidationFailedProperties {
+    run_id: string | null;
+    validation_mode: ValidationMode;
+    duration_ms: number;
+    error_code: string;
+    error_phase: ValidationErrorPhase;
+    retryable: boolean;
+}
+export interface ValidationCancelledProperties {
+    run_id: string | null;
+    validation_mode: ValidationMode;
+    duration_ms: number;
+    error_phase: ValidationErrorPhase;
+}
+export interface ReportViewedProperties {
+    run_id: string;
+    validation_mode: ValidationMode;
+    finding_count: number;
+}
+/**
+ * The exhaustive event-to-property mapping.
+ *
+ * Secondary events map to a permissive record: they predate this contract and
+ * typing their existing payloads would be a rename exercise with no consumer.
+ * They are still name-checked, which is what the drift gate needs.
+ */
+export interface AnalyticsEventProperties {
+    signup_started: {
+        plan?: string;
+    };
+    signup_completed: {
+        method: string;
+        confirmation_required: boolean;
+        plan?: string;
+    };
+    onboarding_started: Record<string, never>;
+    onboarding_completed: {
+        completion_path: string;
+        figma_connected: boolean;
+        environment_connected: boolean;
+    };
+    figma_connected: {
+        method: 'oauth' | 'pat';
+        is_first_connect: boolean;
+    };
+    environment_connected: {
+        connection_type: string;
+    };
+    web_validation_started: ValidationStartedProperties;
+    web_validation_completed: WebValidationCompletedProperties;
+    web_validation_failed: ValidationFailedProperties;
+    web_validation_cancelled: ValidationCancelledProperties;
+    report_viewed: ReportViewedProperties;
+    report_shared: {
+        run_id: string;
+    };
+    diff_mark_resolved: {
+        run_id: string;
+        review_action: string;
+    };
+    upgrade_clicked: {
+        plan: string;
+        location: string;
+    };
+    checkout_started: {
+        plan: string;
+        interval: 'monthly' | 'annual';
+    };
+    feedback_submitted: {
+        feedback_type: string;
+    };
+    extension_opened: Record<string, never>;
+    /** User intent — the Validate button was pressed. Not an accepted run. */
+    validation_start: {
+        validation_mode: ValidationMode;
+    };
+    /** The backend accepted the run and issued a run id. The GA "started" event. */
+    validation_accepted: ValidationStartedProperties;
+    validation_complete: WebValidationCompletedProperties;
+    validation_error: ValidationFailedProperties;
+    validation_cancel: ValidationCancelledProperties;
+    review_saved: {
+        run_id?: string;
+        review_action: string;
+    };
+    figma_auth_success: Record<string, never>;
+    figma_auth_error: {
+        error: string;
+    };
+    extension_share_copied: {
+        run_id?: string;
+    };
+    upgrade_modal_viewed: {
+        plan: string;
+    };
+    upgrade_cta_clicked: {
+        plan: string;
+        location: string;
+    };
+    checkout_completed: {
+        plan: string;
+        subscription_status: string;
+    };
+    console_errors: Record<string, unknown>;
+    diff_expanded: Record<string, unknown>;
+    drawer_filter_changed: Record<string, unknown>;
+    review_save_error: Record<string, unknown>;
+    review_verdict: Record<string, unknown>;
+    review_verdict_all: Record<string, unknown>;
+    screenshot_exported: Record<string, unknown>;
+    ui_crash: Record<string, unknown>;
+    validation_resume: Record<string, unknown>;
+    validation_retry: Record<string, unknown>;
+    view_changed: Record<string, unknown>;
+    auth_refresh: Record<string, unknown>;
+    consensus_complete: Record<string, unknown>;
+    consensus_error: Record<string, unknown>;
+    extension_validation_failed: Record<string, unknown>;
+    idempotency_dedup_client: Record<string, unknown>;
+    pipeline_complete: Record<string, unknown>;
+    pipeline_phase: Record<string, unknown>;
+    pipeline_resume: Record<string, unknown>;
+    rate_limit_hit: Record<string, unknown>;
+    upgrade_wall_hit: Record<string, unknown>;
+}
+/** Payload for one event: its own properties plus the wrapper's context. */
+export type AnalyticsPayload<E extends AnalyticsEventName> = AnalyticsEventProperties[E] & AnalyticsContext;
+/**
+ * Property names that must never reach an analytics backend, at any value.
+ *
+ * This is a NAME denylist and therefore a backstop, not the control. The
+ * control is that call sites do not pass these. It exists because the cost of
+ * one leaked token is unbounded and the cost of a `Set.has()` is not.
+ *
+ * Design-token names and CSS custom-property names are NOT credentials and are
+ * deliberately absent from this list — they are frequently the only useful
+ * debugging signal on a DS run.
+ */
+export declare const FORBIDDEN_PROPERTY_KEYS: readonly string[];
+/**
+ * Strip forbidden keys and `undefined` values from a property bag.
+ *
+ * `undefined` is dropped rather than sent because PostHog stores it as a real
+ * property value, which then shows up in the UI as an existing-but-empty
+ * property and makes "is not set" filters wrong.
+ */
+export declare function sanitizeProperties(props: Record<string, unknown> | undefined): Record<string, unknown>;

package/dist/analytics.js

@@ -0,0 +1,241 @@
+/**
+ * Analytics contract — GA Phase 1.
+ *
+ * ONE vocabulary for client analytics event names and their property shapes,
+ * shared by `usefidel/usefidel` (extension, admin) and `usefidel/fidel-web`
+ * (webapp, landing).
+ *
+ * WHY THIS IS A PACKAGE AND NOT A LOCAL FILE PER SURFACE.
+ * The webapp and the extension each identified the same human under a
+ * different PostHog `distinct_id` — the webapp by Supabase UUID-or-email, the
+ * extension by email-or-Figma-handle. `extension/src/lib/posthog.ts` carried a
+ * comment asserting the two agreed. They did not. Nothing failed; retention
+ * cohorts were simply wrong, and stayed wrong, because the two "authoritative"
+ * definitions lived in two repositories with no gate between them.
+ *
+ * The package is the only mechanism that spans both repositories.
+ *
+ * WHAT THIS OWNS: event NAMES and property TYPES.
+ * WHAT IT DOES NOT OWN: SDK initialization, identity resolution, storage,
+ * environment detection, redaction, or any `posthog.*` call. Those stay in a
+ * per-surface wrapper, because they differ per surface in ways a shared module
+ * would have to branch on — and a shared module full of surface branches is
+ * how the last divergence started.
+ *
+ * NARROWNESS (see index.ts). This file adds runtime values — two frozen name
+ * arrays and one error-code-to-phase map. That is the same shape as
+ * `RUN_ERROR_CODES`, which this package already publishes. It carries no
+ * engine, no endpoint, no credential, and no backend logic. Event names
+ * describe which buttons exist, which a contractor installing the package can
+ * already observe by using the product.
+ */
+import { RUN_ERROR_CODES } from './run-errors.js';
+/**
+ * Schema version stamped on every event emitted by a contract-aware wrapper.
+ *
+ * Version 1 is everything emitted before the GA cutover: mixed identity,
+ * success events that fired before the operation succeeded, camelCase and
+ * snake_case properties side by side. Version 2 is this contract.
+ *
+ * The versions are NOT semantically comparable and must never be summed in one
+ * tile. Identity is preserved across the cutover by aliasing, so a person's
+ * history survives; the meaning of their events does not.
+ */
+export const ANALYTICS_SCHEMA_VERSION = 2;
+/**
+ * Every run error code, mapped to the phase it belongs to.
+ *
+ * EXHAUSTIVE BY CONSTRUCTION: the `Record<RunErrorCode, …>` type means adding
+ * a code to the taxonomy without assigning it a phase is a compile error in
+ * this package, which is a merge gate in both repositories. That is deliberate
+ * — the alternative is a default branch, and a default branch silently files
+ * every new code under `unknown`.
+ */
+export const ERROR_CODE_PHASE = {
+    INVALID_REFERENCE_URL: 'input_validation',
+    INVALID_TARGET_URL: 'input_validation',
+    TARGET_AUTH_WALL: 'target_capture',
+    TARGET_UNREACHABLE: 'target_capture',
+    TARGET_TIMEOUT: 'target_capture',
+    TARGET_CSP_BLOCKED: 'target_capture',
+    SESSION_EXPIRED: 'target_capture',
+    CAPABILITY_UNAVAILABLE: 'target_capture',
+    PROVIDER_REQUEST_REJECTED: 'target_capture',
+    FIGMA_ACCESS_DENIED: 'figma_fetch',
+    FIGMA_TOKEN_EXPIRED: 'figma_fetch',
+    FIGMA_NOT_FOUND: 'figma_fetch',
+    FIGMA_RATE_LIMITED: 'figma_fetch',
+    DESIGN_SYSTEM_NOT_AVAILABLE: 'design_system_resolve',
+    DESIGN_SYSTEM_CONTEXT_NOT_AVAILABLE: 'design_system_resolve',
+    DESIGN_SYSTEM_INCOMPATIBLE: 'design_system_resolve',
+    PIPELINE_TIMEOUT: 'pipeline',
+    PIPELINE_ERROR: 'pipeline',
+    ZERO_ELEMENTS_MATCHED: 'pipeline',
+    FLOW_STEP_FAILED: 'pipeline',
+    PERSIST_FAILED: 'persist',
+    UNKNOWN_ERROR: 'unknown',
+};
+/**
+ * Phase for a code, tolerating values from outside the taxonomy.
+ *
+ * The admin dashboard reads `error_code` out of Postgres, where it is a bare
+ * TEXT column with no FK to the taxonomy. A row written by an older deploy can
+ * therefore hold a code this build has never heard of. Returning `'unknown'`
+ * for that is right; throwing would take down the tile.
+ */
+export function errorPhaseFor(code) {
+    if (!code)
+        return 'unknown';
+    return ERROR_CODE_PHASE[code] ?? 'unknown';
+}
+/** True when `code` is a member of the current taxonomy. */
+export function isKnownErrorCode(code) {
+    return !!code && RUN_ERROR_CODES.includes(code);
+}
+// ── Event names ──────────────────────────────────────────────────────────────
+//
+// TWO LISTS, ONE UNION.
+//
+// GA events are the ones the GA Command Center is built on. They have typed,
+// required properties and their firing conditions are specified in the plan.
+//
+// Secondary events already exist in the extension and keep flowing. They are
+// listed because the drift gate is exhaustive: an emitted name absent from
+// this file fails CI. Listing them is not an endorsement — several are
+// diagnostic and must stay out of GA tiles.
+//
+// The extension's raw names differ from the webapp's on purpose. Renaming them
+// would orphan existing history for no gain; PostHog *actions* combine the
+// pairs (see plan §13). What matters is that both are declared here.
+/** Events the GA dashboard is built on. Typed properties, specified triggers. */
+export const GA_EVENT_NAMES = [
+    // webapp
+    'signup_started',
+    'signup_completed',
+    'onboarding_started',
+    'onboarding_completed',
+    'figma_connected',
+    'environment_connected',
+    'web_validation_started',
+    'web_validation_completed',
+    'web_validation_failed',
+    'web_validation_cancelled',
+    'report_viewed',
+    'report_shared',
+    'diff_mark_resolved',
+    'upgrade_clicked',
+    'checkout_started',
+    'feedback_submitted',
+    // extension — existing names, corrected semantics
+    'extension_opened',
+    'validation_start',
+    'validation_accepted',
+    'validation_complete',
+    'validation_error',
+    'validation_cancel',
+    'review_saved',
+    'figma_auth_success',
+    'figma_auth_error',
+    'extension_share_copied',
+    'upgrade_modal_viewed',
+    'upgrade_cta_clicked',
+];
+/**
+ * Events that exist but are NOT GA metrics.
+ *
+ * `checkout_completed` is here rather than in `GA_EVENT_NAMES` deliberately.
+ * It fires in the browser on return from Stripe, which is neither reliable
+ * (the tab can be closed) nor authoritative (the webhook is). Paid conversion
+ * comes from `teams.subscription_status` and Stripe. This event is a funnel
+ * diagnostic for "did the user come back", nothing more, and must be labelled
+ * as such wherever it appears.
+ */
+export const SECONDARY_EVENT_NAMES = [
+    'checkout_completed',
+    // extension UI interaction + diagnostics
+    'console_errors',
+    'diff_expanded',
+    'drawer_filter_changed',
+    'review_save_error',
+    'review_verdict',
+    'review_verdict_all',
+    'screenshot_exported',
+    'ui_crash',
+    'validation_resume',
+    'validation_retry',
+    'view_changed',
+    // extension pipeline internals, emitted from static IIFEs (hp.js)
+    'auth_refresh',
+    'consensus_complete',
+    'consensus_error',
+    'extension_validation_failed',
+    'idempotency_dedup_client',
+    'pipeline_complete',
+    'pipeline_phase',
+    'pipeline_resume',
+    'rate_limit_hit',
+    'upgrade_wall_hit',
+];
+/** Every event name any Fidel client may emit. */
+export const ANALYTICS_EVENT_NAMES = [
+    ...GA_EVENT_NAMES,
+    ...SECONDARY_EVENT_NAMES,
+];
+// ── Redaction ────────────────────────────────────────────────────────────────
+/**
+ * Property names that must never reach an analytics backend, at any value.
+ *
+ * This is a NAME denylist and therefore a backstop, not the control. The
+ * control is that call sites do not pass these. It exists because the cost of
+ * one leaked token is unbounded and the cost of a `Set.has()` is not.
+ *
+ * Design-token names and CSS custom-property names are NOT credentials and are
+ * deliberately absent from this list — they are frequently the only useful
+ * debugging signal on a DS run.
+ */
+export const FORBIDDEN_PROPERTY_KEYS = [
+    'access_token',
+    'accessToken',
+    'refresh_token',
+    'refreshToken',
+    'authorization',
+    'Authorization',
+    'apikey',
+    'apiKey',
+    'api_key',
+    'anon_key',
+    'anonKey',
+    'cookie',
+    'Cookie',
+    'share_token',
+    'shareToken',
+    'figma_access_token',
+    'figma_token',
+    'figmaToken',
+    'pat',
+    'password',
+    'jwt',
+    'secret',
+    't', // the `?t=` share-token query parameter
+];
+/**
+ * Strip forbidden keys and `undefined` values from a property bag.
+ *
+ * `undefined` is dropped rather than sent because PostHog stores it as a real
+ * property value, which then shows up in the UI as an existing-but-empty
+ * property and makes "is not set" filters wrong.
+ */
+export function sanitizeProperties(props) {
+    if (!props)
+        return {};
+    const forbidden = new Set(FORBIDDEN_PROPERTY_KEYS.map((k) => k.toLowerCase()));
+    const out = {};
+    for (const [key, value] of Object.entries(props)) {
+        if (value === undefined)
+            continue;
+        if (forbidden.has(key.toLowerCase()))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { RUN_ERROR_CODES, ERROR_CODE_META, mapSnapshotErrorToCode, mapFigmaErrorToCode, resolveRunDisplay, } from './run-errors.js';
 export type { RunErrorCode, RunErrorMeta, ErrorMapping, RunDisplay, } from './run-errors.js';
 export type { IntakeFramework, UnsupportedStack, UnsupportedReason, UnresolvedReferenceSection, UnresolvedReferenceReason, UnresolvedReference, ParsedThemeColor, ParsedThemeTypography, ParsedThemeSize, ShadcnConfig, ParsedTheme, IntakeDetection, TokenSourceKind, TokenSource, PackageRole, PackageInfo, } from './theme-intake.js';
+export { ANALYTICS_SCHEMA_VERSION, ANALYTICS_EVENT_NAMES, GA_EVENT_NAMES, SECONDARY_EVENT_NAMES, ERROR_CODE_PHASE, FORBIDDEN_PROPERTY_KEYS, errorPhaseFor, isKnownErrorCode, sanitizeProperties, } from './analytics.js';
+export type { AnalyticsSurface, AnalyticsEnvironment, AnalyticsContext, AnalyticsPersonProperties, AnalyticsEventName, GaEventName, SecondaryEventName, AnalyticsEventProperties, AnalyticsPayload, ValidationMode, ValidationErrorPhase, ResultCompleteness, ValidationEventProperties, ValidationStartedProperties, WebValidationCompletedProperties, ValidationFailedProperties, ValidationCancelledProperties, ReportViewedProperties, } from './analytics.js';

package/dist/index.js

@@ -16,3 +16,21 @@
 // Adding an export here is an architectural change, not a convenience — it needs
 // the same review as any cross-surface contract.
 export { RUN_ERROR_CODES, ERROR_CODE_META, mapSnapshotErrorToCode, mapFigmaErrorToCode, resolveRunDisplay, } from './run-errors.js';
+// analytics — client event names and property shapes (GA Phase 1).
+//
+// WHY THIS BELONGS HERE, against the narrowness rule above: it is the only
+// mechanism that spans both repositories. The webapp and extension each held a
+// local, self-declared "authoritative" identity and event definition; they
+// disagreed, nothing failed, and retention cohorts were silently wrong for
+// months. A gate that lives in one repo cannot catch that.
+//
+// It carries two frozen string arrays, one error-code-to-phase map and one
+// pure sanitizer — the same runtime shape as RUN_ERROR_CODES above. No engine,
+// no endpoint, no credential, no backend logic. Event names describe which
+// buttons exist, which anyone using the product can already observe.
+//
+// What it deliberately does NOT carry are the SDK wrappers: initialization,
+// identity resolution, storage and environment detection stay per-surface,
+// because a shared module would have to branch on surface and a shared module
+// full of surface branches is how the divergence started.
+export { ANALYTICS_SCHEMA_VERSION, ANALYTICS_EVENT_NAMES, GA_EVENT_NAMES, SECONDARY_EVENT_NAMES, ERROR_CODE_PHASE, FORBIDDEN_PROPERTY_KEYS, errorPhaseFor, isKnownErrorCode, sanitizeProperties, } from './analytics.js';

package/package.json

@@ -7,7 +7,7 @@
     "The source of truth still lives in the monorepo at packages/contracts/."
   ],
   "name": "@usefidel/contracts",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Shared, code-free contracts between Fidel surfaces. Run-error taxonomy, theme-intake wire types, and the canonical fidel.config.json builders.",
   "license": "UNLICENSED",
   "private": false,
@@ -31,6 +31,10 @@
     "./onboarding-config": {
       "types": "./dist/onboarding-config.d.ts",
       "import": "./dist/onboarding-config.js"
+    },
+    "./analytics": {
+      "types": "./dist/analytics.d.ts",
+      "import": "./dist/analytics.js"
     }
   },
   "files": [