@usefidel/contracts 0.7.0 → 0.9.0

package/dist/analytics.d.ts

@@ -112,7 +112,7 @@ export declare function errorPhaseFor(code: string | null | undefined): Validati
 /** 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"];
+export declare const GA_EVENT_NAMES: readonly ["signup_started", "signup_completed", "onboarding_started", "onboarding_completed", "figma_connected", "environment_connected", "web_validation_submitted", "web_validation_completed", "web_validation_failed", "web_validation_cancelled", "report_viewed", "report_share_created", "report_link_copied", "report_share_failed", "report_copy_failed", "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.
  *
@@ -125,7 +125,7 @@ export declare const GA_EVENT_NAMES: readonly ["signup_started", "signup_complet
  */
 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 declare const ANALYTICS_EVENT_NAMES: readonly ["signup_started", "signup_completed", "onboarding_started", "onboarding_completed", "figma_connected", "environment_connected", "web_validation_submitted", "web_validation_completed", "web_validation_failed", "web_validation_cancelled", "report_viewed", "report_share_created", "report_link_copied", "report_share_failed", "report_copy_failed", "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;
@@ -170,10 +170,51 @@ export interface ValidationEventProperties {
     run_id: string;
     validation_mode: ValidationMode;
 }
-export interface ValidationStartedProperties extends ValidationEventProperties {
+/**
+ * The backend ACCEPTED a validation request and issued a run id.
+ *
+ * Named `submitted`, not `started`, because the transition it records is the
+ * server's acceptance rather than the user's click. The predecessor fired
+ * before the request left the browser, which meant a run rejected at the
+ * upgrade wall still counted as started and no event could carry a `run_id`.
+ * This one cannot be emitted without one.
+ *
+ * NOT a terminal event: exactly one of completed / failed / cancelled follows.
+ */
+export interface ValidationSubmittedProperties extends ValidationEventProperties {
+    /**
+     * ABSENT where the surface has no viewport control. Absence is the honest
+     * encoding of "not applicable" — a default substituted here would be
+     * indistinguishable from a real user selection.
+     */
     viewport?: string;
     is_revalidation?: boolean;
 }
+/**
+ * A share link was created, or its URL was copied.
+ *
+ * `report_shared` was retired in 0.9.0 because it could not answer the only
+ * question it was asked. It fired on button CLICK, so it counted intents, not
+ * shares: a failed token mint and a successful copy were the same event, and a
+ * user who clicked three times and never got a URL looked like three shares.
+ * Creating a link and copying it are also genuinely different acts — a link
+ * created and never copied was never delivered to anyone.
+ */
+export interface ReportShareProperties {
+    run_id: string;
+    /** Which surface offered the control; the two share entry points differ. */
+    share_surface: 'report' | 'project';
+}
+/** Share-token creation failed, or the URL exists but the clipboard refused. */
+export interface ReportShareFailureProperties {
+    run_id: string;
+    share_surface: 'report' | 'project';
+    /**
+     * Bounded reason. Never the raw exception: clipboard and network errors
+     * carry browser-supplied text and, in the network case, the request URL.
+     */
+    error_code: string;
+}
 export interface WebValidationCompletedProperties extends ValidationEventProperties {
     duration_ms: number;
     /**
@@ -195,13 +236,27 @@ export interface WebValidationCompletedProperties extends ValidationEventPropert
      */
     result_completeness?: ResultCompleteness;
 }
-export interface ValidationFailedProperties extends ValidationEventProperties {
+/**
+ * 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 extends ValidationEventProperties {
+export interface ValidationCancelledProperties {
+    run_id: string | null;
+    validation_mode: ValidationMode;
     duration_ms: number;
     error_phase: ValidationErrorPhase;
 }
@@ -239,14 +294,15 @@ export interface AnalyticsEventProperties {
     environment_connected: {
         connection_type: string;
     };
-    web_validation_started: ValidationStartedProperties;
+    web_validation_submitted: ValidationSubmittedProperties;
     web_validation_completed: WebValidationCompletedProperties;
     web_validation_failed: ValidationFailedProperties;
     web_validation_cancelled: ValidationCancelledProperties;
     report_viewed: ReportViewedProperties;
-    report_shared: {
-        run_id: string;
-    };
+    report_share_created: ReportShareProperties;
+    report_link_copied: ReportShareProperties;
+    report_share_failed: ReportShareFailureProperties;
+    report_copy_failed: ReportShareFailureProperties;
     diff_mark_resolved: {
         run_id: string;
         review_action: string;
@@ -268,7 +324,7 @@ export interface AnalyticsEventProperties {
         validation_mode: ValidationMode;
     };
     /** The backend accepted the run and issued a run id. The GA "started" event. */
-    validation_accepted: ValidationStartedProperties;
+    validation_accepted: ValidationSubmittedProperties;
     validation_complete: WebValidationCompletedProperties;
     validation_error: ValidationFailedProperties;
     validation_cancel: ValidationCancelledProperties;

package/dist/analytics.js

@@ -116,12 +116,15 @@ export const GA_EVENT_NAMES = [
     'onboarding_completed',
     'figma_connected',
     'environment_connected',
-    'web_validation_started',
+    'web_validation_submitted',
     'web_validation_completed',
     'web_validation_failed',
     'web_validation_cancelled',
     'report_viewed',
-    'report_shared',
+    'report_share_created',
+    'report_link_copied',
+    'report_share_failed',
+    'report_copy_failed',
     'diff_mark_resolved',
     'upgrade_clicked',
     'checkout_started',

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export { RUN_ERROR_CODES, ERROR_CODE_META, mapSnapshotErrorToCode, mapFigmaError
 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';
+export type { AnalyticsSurface, AnalyticsEnvironment, AnalyticsContext, AnalyticsPersonProperties, AnalyticsEventName, GaEventName, SecondaryEventName, AnalyticsEventProperties, AnalyticsPayload, ValidationMode, ValidationErrorPhase, ResultCompleteness, ValidationEventProperties, ValidationSubmittedProperties, ReportShareProperties, ReportShareFailureProperties, WebValidationCompletedProperties, ValidationFailedProperties, ValidationCancelledProperties, ReportViewedProperties, } 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.7.0",
+  "version": "0.9.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,