feat: surface AIM log response via onResultsLogged callback

eslint.config.js

@@ -63,5 +63,11 @@ export default [
         'URLSearchParams'
       ]
     }
+  },
+  {
+    // Browser-compat checks apply to shipped library code (src), not tests,
+    // which run in Node + Vitest's Chromium.
+    files: ['tests/**/*.ts'],
+    rules: { 'compat/compat': 'off' }
   }
 ];

src/index.ts

@@ -12,7 +12,9 @@ import PacketLossEngine from './engines/PacketLossEngine';
 import ReachabilityEngine from './engines/ReachabilityEngine';
 
 import Results from './Results';
-import logFinalResults from './logging/logFinalResults';
+import logFinalResults, {
+  type AimLogResponse
+} from './logging/logFinalResults';
 
 const DEFAULT_OPTIMAL_DOWNLOAD_SIZE = 1e6;
 const DEFAULT_OPTIMAL_UPLOAD_SIZE = 1e6;
@@ -704,6 +706,7 @@ class MeasurementEngine {
  *
  * const engine = new SpeedTest();
  * engine.onFinish = results => console.log(results.getScores());
+ * engine.onResultsLogged = ({ requestId }) => console.log('Logged as', requestId);
  * ```
  */
 class SpeedTestEngine extends MeasurementEngine {
@@ -737,23 +740,39 @@ class SpeedTestEngine extends MeasurementEngine {
     };
   }
 
+  /**
+   * Called after the final results have been logged to the AIM API, with the
+   * endpoint's parsed response (e.g. the assigned `requestId`).
+   *
+   * Fires whenever logging is attempted (`logAimApiUrl` is set), after the log
+   * request completes — on success or failure. On failure, `requestId` is
+   * `undefined`. Because the log request completes after {@link onFinish}, this
+   * callback runs slightly later.
+   */
+  onResultsLogged: (response: AimLogResponse) => void = () => {};
+
   // Internal state
   readonly #logAimApiUrl: string | null;
   readonly #sessionId: string | undefined;
 
   // Internal methods
   #logFinalResults = (results: Results): void => {
-    this.#logAimApiUrl &&
-      logFinalResults(results, {
-        apiUrl: this.#logAimApiUrl,
-        sessionId: this.#sessionId
-      });
+    if (!this.#logAimApiUrl) {
+      return;
+    }
+    logFinalResults(results, {
+      apiUrl: this.#logAimApiUrl,
+      sessionId: this.#sessionId
+    }).then(response => {
+      this.onResultsLogged(response);
+    });
   };
 }
 
 export default SpeedTestEngine;
 
 export type { MeasurementType, PhaseChangePayload };
+export type { AimLogResponse };
 export { type default as Results } from './Results';
 export type {
   BandwidthPoint,

src/logging/logFinalResults.ts

@@ -37,6 +37,12 @@ interface LogData {
   [key: string]: unknown;
 }
 
+/** Response returned by the AIM logging endpoint. */
+export interface AimLogResponse {
+  /** Unique identifier assigned to this measurement, used to look it up later. */
+  requestId?: string;
+}
+
 type ParserFn = (val: unknown) => unknown;
 
 /** Rounds a number to a given number of decimal places. */
@@ -91,12 +97,16 @@ const scoreParser = (
 
 /**
  * Formats measurement results and AIM scores, then POSTs them to the
- * AIM logging endpoint. Fire-and-forget — errors are silently ignored.
+ * AIM logging endpoint. Best-effort — never throws.
+ *
+ * Always resolves with an {@link AimLogResponse}: the parsed response body on
+ * success (e.g. the assigned `requestId`), or `{ requestId: undefined }` if the
+ * request failed or returned no usable body.
  */
-const logAimResults = (
+const logAimResults = async (
   results: Results,
   { apiUrl, sessionId }: LogConfig
-): void => {
+): Promise<AimLogResponse> => {
   const logData: LogData = {
     sessionId
   };
@@ -118,10 +128,18 @@ const logAimResults = (
     );
   }
 
-  fetch(apiUrl, {
-    method: 'POST',
-    body: JSON.stringify(logData)
-  });
+  try {
+    const response = await fetch(apiUrl, {
+      method: 'POST',
+      body: JSON.stringify(logData)
+    });
+    if (!response.ok) {
+      return { requestId: undefined };
+    }
+    return (await response.json()) as AimLogResponse;
+  } catch {
+    return { requestId: undefined };
+  }
 };
 
 export default logAimResults;