Diagnostics Module

The Diagnostics module provides utilities for managing analytics records, error reports, crash data, retention policies, and diagnostic export files.

It is designed to help your app collect diagnostic information in a structured way, while also giving you control over privacy settings and retention behavior.

Methods

Method	Description	Return Type
settings.set(settings?: PrivacySettings)	Updates the diagnostics privacy settings.	Promise<unknown>
settings.get()	Returns the current diagnostics privacy settings.	Promise<unknown>
newRecord(recordType: string, payload: AnalyticsPayload, env: string)	Creates a new analytics or diagnostic record for the specified environment.	Promise<unknown>
newError.js(payload: ErrorPayload)	Records a new JavaScript error entry.	Promise<unknown>
newError.native(payload: ErrorPayload)	Records a new native error entry.	Promise<unknown>
newError.generic(payload: ErrorPayload, env?: string)	Records a new generic error entry with an optional environment label.	Promise<unknown>
readRecordsFile(relPath: string, maxBytes?: number)	Reads a diagnostics file and returns its raw contents as bytes.	Promise<Uint8Array>
listRecordsFiles(area: "logs" | "crashes")	Lists available diagnostics record files in the given area.	Promise<unknown>
runRetention()	Runs retention cleanup for stored diagnostics data.	Promise<unknown>
export(targetZipPath: string)	Exports diagnostics data to a ZIP archive at the given target path.	Promise<unknown>

Test Methods

Method	Description	Return Type
test.testGenerateRecords(n?: number)	Generates a batch of test diagnostic records.	Promise<void>
test.testThrowJsError()	Triggers a JavaScript test error.	Promise<never>
test.testPanicRust()	Triggers a native Rust panic for testing purposes.	Promise<void>
test.testExportZip(path: string)	Generates a test diagnostics ZIP export.	Promise<void>
test.testForceRetention(area: "logs" | "analytics" | "crashes")	Forces retention cleanup for the specified diagnostics area.	Promise<void>

DiagnosticsInterface

interface DiagnosticsInterface {
  settings: {
      set: (settings?: PrivacySettings) => Promise<unknown>;
      get: () => Promise<unknown>;
  };
  newRecord: (recordType: string, payload: AnalyticsPayload, env: "js" | "native" | string) => Promise<unknown>;
  newError: {
      js: (payload: ErrorPayload) => Promise<unknown>;
      native: (payload: ErrorPayload) => Promise<unknown>;
      generic: (payload: ErrorPayload, env?: string) => Promise<unknown>;
  };
  readRecordsFile: (relPath: string, maxBytes?: number) => Promise<Uint8Array<ArrayBufferLike>>;
  listRecordsFiles: (area: "logs" | "crashes") => Promise<unknown>;
  runRetention: () => Promise<unknown>;
  export: (targetZipPath: string) => Promise<unknown>;
  test: DiagnosticsTestFunctions;
}

Types

DiagnosticsTestFunctions

type DiagnosticsTestFunctions = {
  testGenerateRecords: (n?: number) => Promise<void>;
  testThrowJsError: () => Promise<never>;
  testPanicRust: () => Promise<void>;
  testExportZip: (path: string) => Promise<void>;
  testForceRetention: (area: "logs" | "analytics" | "crashes") => Promise<void>;
}

ErrorPayload

type ErrorPayload = {
  message: string;
  filename?: string;
  lineno?: number;
  colno?: number;
  stack?: string;
};

AnalyticsPayload

type AnalyticsPayload = {
  name: string;
  props?: Record<string, unknown>;
};

ListedFile

type ListedFile = {
  relPath: string;
  bytes: number;
  modified_ms: number;
};

RecordPayload

type RecordPayload = ErrorPayload | AnalyticsPayload;

PrivacySettings

type PrivacySettings = {
  analyticsEnabled?: boolean;
  crashReportsEnabled?: boolean;
  retentionDaysAnalytics?: U32;
  retentionDaysLogs?: U32;
  retentionDaysCrashes?: U32;
}

Example Usage

Update privacy settings

await Desktopr.diagnostics.settings.set({
  analyticsEnabled: true,
  crashReportsEnabled: true,
  retentionDaysAnalytics: 30,
  retentionDaysLogs: 14,
  retentionDaysCrashes: 30
});

const settings = await Desktopr.diagnostics.settings.get();
console.log("Diagnostics settings:", settings);

Create a diagnostics record

await Desktopr.diagnostics.newRecord(
  "user-action",
  {
    name: "button_clicked",
    props: {
      section: "settings",
      button: "save"
    }
  },
  "js"
);

Record an error

await Desktopr.diagnostics.newError.js({
  message: "Something went wrong",
  filename: "app.js",
  lineno: 42,
  colno: 13,
  stack: "Error: Something went wrong..."
});

Export diagnostics data

await Desktopr.diagnostics.export("/tmp/diagnostics-export.zip");

Notes

• The settings API allows you to control whether analytics and crash reporting are enabled.
• The newRecord method is intended for structured analytics or diagnostic events.
• The newError helpers provide convenient ways to report JavaScript, native, or generic errors.
• The readRecordsFile method returns raw file bytes, which is useful when you need to inspect stored diagnostic data programmatically.
• The test API is intended for development and testing scenarios only.