feat: report update lifecycle events to the update server

Maps local report events (downloadSuccess/errorUpdate/errorSwitchVersion/
markSuccess/rollback) to the server's five aggregate types and fires a
single best-effort POST {endpoint}/report/{appKey} — no retry, no fallback
race, all failures swallowed, skipped in dev. An incremental patch that
failed before the full fallback succeeded is additionally reported as
patch_fail with the error detail. Opt out with disableTelemetry.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: sunnylqm

src/__tests__/telemetry.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  MAX_DETAIL_LENGTH,
+  resolveServerEventHash,
+  resolveServerEventType,
+  truncateDetail,
+} from '../telemetry';
+
+describe('resolveServerEventType', () => {
+  test('maps lifecycle events to server aggregate types', () => {
+    expect(resolveServerEventType('downloadSuccess')).toBe('download_success');
+    expect(resolveServerEventType('markSuccess')).toBe('mark_success');
+    expect(resolveServerEventType('rollback')).toBe('rollback');
+    expect(resolveServerEventType('errorSwitchVersion')).toBe('patch_fail');
+  });
+
+  test('splits errorUpdate by underlying native code', () => {
+    expect(resolveServerEventType('errorUpdate', 'DOWNLOAD_FAILED')).toBe(
+      'download_fail',
+    );
+    expect(resolveServerEventType('errorUpdate')).toBe('download_fail');
+    expect(resolveServerEventType('errorUpdate', 'PATCH_FAILED')).toBe(
+      'patch_fail',
+    );
+  });
+
+  test('returns undefined for local-only events', () => {
+    expect(resolveServerEventType('checking')).toBeUndefined();
+    expect(resolveServerEventType('downloading')).toBeUndefined();
+    expect(resolveServerEventType('errorChecking')).toBeUndefined();
+    expect(resolveServerEventType('errorMarkSuccess')).toBeUndefined();
+    expect(resolveServerEventType('downloadingApk')).toBeUndefined();
+  });
+});
+
+describe('resolveServerEventHash', () => {
+  test('rollback uses the rolled back version', () => {
+    expect(
+      resolveServerEventHash({
+        serverType: 'rollback',
+        data: { rolledBackVersion: 'abc' },
+        currentVersion: 'cur',
+      }),
+    ).toBe('abc');
+  });
+
+  test('mark_success falls back to the running version', () => {
+    expect(
+      resolveServerEventHash({
+        serverType: 'mark_success',
+        data: {},
+        currentVersion: 'cur',
+      }),
+    ).toBe('cur');
+  });
+
+  test('download events require the target hash', () => {
+    expect(
+      resolveServerEventHash({
+        serverType: 'download_fail',
+        data: { newVersion: 'xyz' },
+        currentVersion: 'cur',
+      }),
+    ).toBe('xyz');
+    expect(
+      resolveServerEventHash({
+        serverType: 'download_fail',
+        data: {},
+        currentVersion: 'cur',
+      }),
+    ).toBe('');
+  });
+});
+
+describe('truncateDetail', () => {
+  test('caps detail under the server column limit', () => {
+    expect(truncateDetail('x'.repeat(2000))?.length).toBe(MAX_DETAIL_LENGTH);
+    expect(truncateDetail('short')).toBe('short');
+    expect(truncateDetail('')).toBeUndefined();
+    expect(truncateDetail(undefined)).toBeUndefined();
+  });
+});

src/client.ts

@@ -41,6 +41,11 @@ import {
 import i18n from './i18n';
 import { toUpdateError, UpdateError, UpdateErrorCode } from './error';
 import { dedupeEndpoints, executeEndpointFallback } from './endpoint';
+import {
+  resolveServerEventHash,
+  resolveServerEventType,
+  truncateDetail,
+} from './telemetry';
 
 /**
  * Receives every error the client reports, alongside the report event type.
@@ -130,6 +135,9 @@ export class Pushy {
   clientType: 'Pushy' | 'Cresc' = 'Pushy';
   lastChecking?: number;
   lastRespJson?: Promise<CheckResult>;
+  // Endpoint that most recently served a successful checkUpdate; telemetry
+  // reuses it instead of re-running the fallback race.
+  private lastWorkingEndpoint?: string;
 
   version = cInfo.rnu;
   loggerPromise = (() => {
@@ -207,6 +215,8 @@ export class Pushy {
     data?: Record<string, string | number>;
   }) => {
     log(`${type} ${code ? `[${code}] ` : ''}${message}`);
+    // Fire-and-forget server telemetry; must not wait for the logger below.
+    this.reportToServer({ type, message, code, data });
     if (this.options.logger === noop) {
       // Wait briefly for a logger to arrive via setOptions (e.g. the rollback
       // report fires in the constructor before the user configures one), but
@@ -242,6 +252,72 @@ export class Pushy {
       log('logger error:', e?.message || e);
     }
   };
+  /**
+   * Best-effort lifecycle event reporting to the update server (aggregate
+   * counts + sampled failure details power the version health view and the
+   * rollback safety net server-side). Single POST to the last known working
+   * endpoint, no retry, no fallback race; any failure is swallowed — telemetry
+   * must never affect the update flow. Opt out with disableTelemetry.
+   */
+  private reportToServer = ({
+    type,
+    message = '',
+    code,
+    data = {},
+  }: {
+    type: EventType;
+    message?: string;
+    code?: UpdateErrorCode;
+    data?: Record<string, string | number>;
+  }) => {
+    try {
+      if (__DEV__ || this.options.disableTelemetry) {
+        return;
+      }
+      const serverType = resolveServerEventType(type, code);
+      if (!serverType) {
+        return;
+      }
+      const { appKey } = this.options;
+      const endpoint =
+        this.lastWorkingEndpoint || this.options.server?.main?.[0];
+      if (!appKey || !endpoint) {
+        return;
+      }
+      const hash = resolveServerEventHash({ serverType, data, currentVersion });
+      if (!hash) {
+        return;
+      }
+      const send = (payloadType: typeof serverType, detail?: string) =>
+        fetchWithTimeout(
+          `${endpoint}/report/${appKey}`,
+          {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              type: payloadType,
+              hash,
+              packageVersion:
+                this.options.overridePackageVersion || packageVersion,
+              cInfo,
+              detail: truncateDetail(detail),
+            }),
+          },
+          DEFAULT_FETCH_TIMEOUT_MS,
+        ).catch((e: any) => {
+          log('telemetry report failed:', e?.message || e);
+        });
+      send(serverType, message || undefined);
+      // A download that only succeeded after an incremental patch failed is
+      // still a patch_fail signal server-side (diff quality), carried in
+      // data.error alongside the downloadSuccess event.
+      if (serverType === 'download_success' && data.error) {
+        send('patch_fail', String(data.error));
+      }
+    } catch (e: any) {
+      log('telemetry error:', e?.message || e);
+    }
+  };
   throwIfEnabled = (e: Error) => {
     if (this.options.throwError) {
       throw e;
@@ -387,6 +463,7 @@ export class Pushy {
     });
 
     log('check endpoint success', endpoint);
+    this.lastWorkingEndpoint = endpoint;
     return value;
   };
   assertDebug = (matter: string) => {

src/telemetry.ts

@@ -0,0 +1,83 @@
+import type { UpdateErrorCode } from './error';
+import type { EventType } from './type';
+
+// Server-side lifecycle event intake (POST {endpoint}/report/{appKey}); the
+// enum must stay in sync with the server's client_event_type. Only these five
+// aggregate types exist server-side — everything else stays local-only.
+export type ServerEventType =
+  | 'download_success'
+  | 'download_fail'
+  | 'patch_fail'
+  | 'rollback'
+  | 'mark_success';
+
+// Failure detail is stored server-side in a VARCHAR(512); stay under it.
+export const MAX_DETAIL_LENGTH = 500;
+
+export interface ServerReportPayload {
+  type: ServerEventType;
+  hash: string;
+  packageVersion?: string;
+  cInfo?: {
+    rnu?: string;
+    rn?: string;
+    os?: string;
+    uuid?: string;
+  };
+  detail?: string;
+}
+
+/**
+ * Maps a local report event to the server-side aggregate type, or undefined
+ * for events the server does not collect. A DOWNLOAD_FAILED whose underlying
+ * native code was PATCH_FAILED counts as patch_fail (the download itself
+ * worked; applying it did not), same for switch-version failures.
+ */
+export const resolveServerEventType = (
+  type: EventType,
+  code?: UpdateErrorCode,
+): ServerEventType | undefined => {
+  switch (type) {
+    case 'downloadSuccess':
+      return 'download_success';
+    case 'errorUpdate':
+      return code === 'PATCH_FAILED' ? 'patch_fail' : 'download_fail';
+    case 'errorSwitchVersion':
+      return 'patch_fail';
+    case 'markSuccess':
+      return 'mark_success';
+    case 'rollback':
+      return 'rollback';
+    default:
+      return undefined;
+  }
+};
+
+/**
+ * The version hash a server event is about. Server-side rows key on it, so an
+ * event without one is not reportable (returns '').
+ */
+export const resolveServerEventHash = ({
+  serverType,
+  data,
+  currentVersion,
+}: {
+  serverType: ServerEventType;
+  data: Record<string, string | number>;
+  currentVersion: string;
+}): string => {
+  if (serverType === 'rollback') {
+    return String(data.rolledBackVersion || '');
+  }
+  if (serverType === 'mark_success') {
+    return String(data.newVersion || currentVersion || '');
+  }
+  return String(data.newVersion || '');
+};
+
+export const truncateDetail = (detail?: string) => {
+  if (!detail) {
+    return undefined;
+  }
+  return detail.slice(0, MAX_DETAIL_LENGTH);
+};

src/type.ts

@@ -129,6 +129,12 @@ export interface ClientOptions {
   overridePackageVersion?: string;
   /** Maximum number of retry attempts for failed downloads (default: 3) */
   maxRetries?: number;
+  /**
+   * Disable reporting update lifecycle events (download/patch failures,
+   * rollback, mark success) to the update server. These aggregate stats power
+   * the version health view in the console. Default: false (enabled).
+   */
+  disableTelemetry?: boolean;
 }
 
 export interface UpdateTestPayload {