@analyticscli/sdk 0.1.0-preview.7 → 0.1.0-preview.9

package/dist/browser.cjs

@@ -587,6 +587,49 @@ var sanitizeSurveyResponseInput = (input) => {
 
 // src/analytics-client.ts
 var DEFAULT_CONSENT_STORAGE_KEY = "analyticscli:consent:v1";
+var AUTH_FAILURE_FLUSH_PAUSE_MS = 6e4;
+var resolveDefaultOsNameFromPlatform = (platform) => {
+  if (!platform) {
+    return void 0;
+  }
+  if (platform === "ios") {
+    return "iOS";
+  }
+  if (platform === "android") {
+    return "Android";
+  }
+  if (platform === "web") {
+    return "Web";
+  }
+  if (platform === "mac") {
+    return "macOS";
+  }
+  if (platform === "windows") {
+    return "Windows";
+  }
+  return void 0;
+};
+var IngestSendError = class extends Error {
+  retryable;
+  attempts;
+  status;
+  errorCode;
+  serverMessage;
+  requestId;
+  constructor(input) {
+    super(input.message);
+    this.name = "IngestSendError";
+    this.retryable = input.retryable;
+    this.attempts = input.attempts;
+    this.status = input.status;
+    this.errorCode = input.errorCode;
+    this.serverMessage = input.serverMessage;
+    this.requestId = input.requestId;
+    if (input.cause !== void 0) {
+      this.cause = input.cause;
+    }
+  }
+};
 var AnalyticsClient = class {
   apiKey;
   hasIngestConfig;
@@ -595,6 +638,7 @@ var AnalyticsClient = class {
   flushIntervalMs;
   maxRetries;
   debug;
+  onIngestError;
   platform;
   projectSurface;
   appVersion;
@@ -627,6 +671,7 @@ var AnalyticsClient = class {
   deferredEventsBeforeHydration = [];
   onboardingStepViewStateSessionId = null;
   onboardingStepViewsSeen = /* @__PURE__ */ new Set();
+  flushPausedUntilMs = 0;
   constructor(options) {
     const normalizedOptions = this.normalizeOptions(options);
     this.apiKey = this.readRequiredStringOption(normalizedOptions.apiKey);
@@ -639,11 +684,17 @@ var AnalyticsClient = class {
     this.flushIntervalMs = normalizedOptions.flushIntervalMs ?? 5e3;
     this.maxRetries = normalizedOptions.maxRetries ?? 4;
     this.debug = normalizedOptions.debug ?? false;
+    this.onIngestError = typeof normalizedOptions.onIngestError === "function" ? normalizedOptions.onIngestError : null;
     this.platform = this.normalizePlatformOption(normalizedOptions.platform) ?? detectDefaultPlatform();
     this.projectSurface = this.normalizeProjectSurfaceOption(normalizedOptions.projectSurface);
     this.appVersion = this.readRequiredStringOption(normalizedOptions.appVersion) || detectDefaultAppVersion();
     this.identityTrackingMode = this.resolveIdentityTrackingModeOption(normalizedOptions);
-    this.context = { ...normalizedOptions.context ?? {} };
+    const initialContext = { ...normalizedOptions.context ?? {} };
+    const hasExplicitOsName = this.readRequiredStringOption(initialContext.osName).length > 0;
+    this.context = {
+      ...initialContext,
+      osName: hasExplicitOsName ? initialContext.osName : resolveDefaultOsNameFromPlatform(this.platform) ?? initialContext.osName
+    };
     this.runtimeEnv = detectRuntimeEnv();
     this.persistConsentState = normalizedOptions.persistConsentState ?? false;
     this.consentStorageKey = this.readRequiredStringOption(normalizedOptions.consentStorageKey) || DEFAULT_CONSENT_STORAGE_KEY;
@@ -676,6 +727,7 @@ var AnalyticsClient = class {
       this.writePersistedConsent(this.configuredStorage, this.fullTrackingConsentGranted);
     }
     this.hydrationPromise = this.hydrateIdentityFromStorage();
+    this.enqueueInitialSessionStart();
     this.startAutoFlush();
   }
   /**
@@ -733,6 +785,32 @@ var AnalyticsClient = class {
       ...context
     };
   }
+  enqueueInitialSessionStart() {
+    if (!this.consentGranted) {
+      return;
+    }
+    if (this.shouldDeferEventsUntilHydrated()) {
+      this.deferEventUntilHydrated(() => {
+        this.enqueueInitialSessionStart();
+      });
+      return;
+    }
+    const sessionId = this.getSessionId();
+    this.enqueue({
+      eventId: randomId(),
+      eventName: "session_start",
+      ts: nowIso(),
+      sessionId,
+      anonId: this.anonId,
+      userId: this.getEventUserId(),
+      properties: this.withRuntimeMetadata({ source: "sdk_mount" }, sessionId),
+      platform: this.platform,
+      projectSurface: this.projectSurface,
+      appVersion: this.appVersion,
+      ...this.withEventContext(),
+      type: "track"
+    });
+  }
   /**
    * Associates following events with a known user id.
    * Anonymous history remains linked by anonId/sessionId.
@@ -1102,6 +1180,9 @@ var AnalyticsClient = class {
     if (this.queue.length === 0 || this.isFlushing || !this.consentGranted) {
       return;
     }
+    if (Date.now() < this.flushPausedUntilMs) {
+      return;
+    }
     this.isFlushing = true;
     const batch = this.queue.splice(0, this.batchSize);
     const payload = {
@@ -1116,9 +1197,20 @@ var AnalyticsClient = class {
     }
     try {
       await this.sendWithRetry(payload);
+      this.flushPausedUntilMs = 0;
     } catch (error) {
-      this.log("Send failed permanently, requeueing batch", error);
       this.queue = [...batch, ...this.queue];
+      const ingestError = this.toIngestSendError(error);
+      const diagnostics = this.createIngestDiagnostics(ingestError, batch.length, this.queue.length);
+      if (ingestError.status === 401 || ingestError.status === 403) {
+        this.flushPausedUntilMs = Date.now() + AUTH_FAILURE_FLUSH_PAUSE_MS;
+        this.log("Pausing ingest flush after auth failure", {
+          status: ingestError.status,
+          retryAfterMs: AUTH_FAILURE_FLUSH_PAUSE_MS
+        });
+      }
+      this.log("Send failed permanently, requeueing batch", diagnostics);
+      this.reportIngestError(diagnostics);
     } finally {
       this.isFlushing = false;
     }
@@ -1147,9 +1239,8 @@ var AnalyticsClient = class {
     });
   }
   async sendWithRetry(payload) {
-    let attempt = 0;
     let delay = 250;
-    while (attempt <= this.maxRetries) {
+    for (let attempt = 1; attempt <= this.maxRetries + 1; attempt += 1) {
       try {
         const response = await fetch(`${this.endpoint}/v1/collect`, {
           method: "POST",
@@ -1161,19 +1252,110 @@ var AnalyticsClient = class {
           keepalive: true
         });
         if (!response.ok) {
-          throw new Error(`ingest status=${response.status}`);
+          throw await this.createHttpIngestSendError(response, attempt);
         }
         return;
       } catch (error) {
-        attempt += 1;
-        if (attempt > this.maxRetries) {
-          throw error;
+        const normalized = this.toIngestSendError(error, attempt);
+        const finalAttempt = attempt >= this.maxRetries + 1;
+        this.log("Ingest attempt failed", {
+          attempt: normalized.attempts,
+          maxRetries: this.maxRetries,
+          retryable: normalized.retryable,
+          status: normalized.status,
+          errorCode: normalized.errorCode,
+          requestId: normalized.requestId,
+          nextRetryInMs: !finalAttempt && normalized.retryable ? delay : null
+        });
+        if (finalAttempt || !normalized.retryable) {
+          throw normalized;
         }
         await new Promise((resolve) => setTimeout(resolve, delay));
         delay *= 2;
       }
     }
   }
+  async createHttpIngestSendError(response, attempts) {
+    const requestId = response.headers.get("x-request-id") ?? response.headers.get("cf-ray") ?? void 0;
+    let errorCode;
+    let serverMessage;
+    try {
+      const parsed = await response.json();
+      const errorBody = parsed && typeof parsed === "object" && parsed.error && typeof parsed.error === "object" ? parsed.error : void 0;
+      if (typeof errorBody?.code === "string") {
+        errorCode = errorBody.code;
+      }
+      if (typeof errorBody?.message === "string") {
+        serverMessage = errorBody.message;
+      }
+    } catch {
+    }
+    const retryable = this.shouldRetryHttpStatus(response.status);
+    const statusSuffix = errorCode ? ` ${errorCode}` : "";
+    const message = `ingest status=${response.status}${statusSuffix}`;
+    return new IngestSendError({
+      message,
+      retryable,
+      attempts,
+      status: response.status,
+      errorCode,
+      serverMessage,
+      requestId
+    });
+  }
+  shouldRetryHttpStatus(status) {
+    return status === 408 || status === 425 || status === 429 || status >= 500;
+  }
+  toIngestSendError(error, attempts) {
+    if (error instanceof IngestSendError) {
+      const resolvedAttempts = attempts ?? error.attempts;
+      return new IngestSendError({
+        message: error.message,
+        retryable: error.retryable,
+        attempts: resolvedAttempts,
+        status: error.status,
+        errorCode: error.errorCode,
+        serverMessage: error.serverMessage,
+        requestId: error.requestId,
+        cause: error.cause
+      });
+    }
+    const fallbackMessage = error instanceof Error ? error.message : "ingest request failed";
+    return new IngestSendError({
+      message: fallbackMessage,
+      retryable: true,
+      attempts: attempts ?? 1,
+      cause: error
+    });
+  }
+  createIngestDiagnostics(error, batchSize, queueSize) {
+    return {
+      name: "AnalyticsIngestError",
+      message: error.message,
+      endpoint: this.endpoint,
+      path: "/v1/collect",
+      status: error.status,
+      errorCode: error.errorCode,
+      serverMessage: error.serverMessage,
+      requestId: error.requestId,
+      retryable: error.retryable,
+      attempts: error.attempts,
+      maxRetries: this.maxRetries,
+      batchSize,
+      queueSize,
+      timestamp: nowIso()
+    };
+  }
+  reportIngestError(error) {
+    if (!this.onIngestError) {
+      return;
+    }
+    try {
+      this.onIngestError(error);
+    } catch (callbackError) {
+      this.log("onIngestError callback threw", callbackError);
+    }
+  }
   parsePersistedConsent(raw) {
     if (raw === "granted") {
       return true;

package/dist/browser.d.cts

@@ -1 +1 @@
-export { AnalyticsClient, AnalyticsClientOptions, AnalyticsConsentState, AnalyticsContext, AnalyticsContextConsentControls, AnalyticsContextUserControls, AnalyticsStorageAdapter, CreateAnalyticsContextOptions, EventContext, EventProperties, IdentityTrackingMode, InitInput, InitOptions, ONBOARDING_EVENTS, ONBOARDING_PROGRESS_EVENT_ORDER, ONBOARDING_SCREEN_EVENT_PREFIXES, ONBOARDING_SURVEY_EVENTS, OnboardingEventName, OnboardingEventProperties, OnboardingStepTracker, OnboardingSurveyAnswerType, OnboardingSurveyEventName, OnboardingSurveyResponseInput, OnboardingTracker, OnboardingTrackerDefaults, OnboardingTrackerSurveyInput, PAYWALL_ANCHOR_EVENT_CANDIDATES, PAYWALL_EVENTS, PAYWALL_JOURNEY_EVENT_ORDER, PAYWALL_SKIP_EVENT_CANDIDATES, PURCHASE_EVENTS, PURCHASE_SUCCESS_EVENT_CANDIDATES, PaywallEventName, PaywallEventProperties, PaywallJourneyEventName, PaywallTracker, PaywallTrackerDefaults, PaywallTrackerProperties, PurchaseEventName, SetConsentOptions, createAnalyticsContext, init, initAsync, initConsentFirst, initConsentFirstAsync } from './index.cjs';
+export { AnalyticsClient, AnalyticsClientOptions, AnalyticsConsentState, AnalyticsContext, AnalyticsContextConsentControls, AnalyticsContextUserControls, AnalyticsIngestError, AnalyticsIngestErrorHandler, AnalyticsStorageAdapter, CreateAnalyticsContextOptions, EventContext, EventProperties, IdentityTrackingMode, InitInput, InitOptions, ONBOARDING_EVENTS, ONBOARDING_PROGRESS_EVENT_ORDER, ONBOARDING_SCREEN_EVENT_PREFIXES, ONBOARDING_SURVEY_EVENTS, OnboardingEventName, OnboardingEventProperties, OnboardingStepTracker, OnboardingSurveyAnswerType, OnboardingSurveyEventName, OnboardingSurveyResponseInput, OnboardingTracker, OnboardingTrackerDefaults, OnboardingTrackerSurveyInput, PAYWALL_ANCHOR_EVENT_CANDIDATES, PAYWALL_EVENTS, PAYWALL_JOURNEY_EVENT_ORDER, PAYWALL_SKIP_EVENT_CANDIDATES, PURCHASE_EVENTS, PURCHASE_SUCCESS_EVENT_CANDIDATES, PaywallEventName, PaywallEventProperties, PaywallJourneyEventName, PaywallTracker, PaywallTrackerDefaults, PaywallTrackerProperties, PurchaseEventName, SetConsentOptions, createAnalyticsContext, init, initAsync, initConsentFirst, initConsentFirstAsync } from './index.cjs';

package/dist/browser.d.ts

@@ -1 +1 @@
-export { AnalyticsClient, AnalyticsClientOptions, AnalyticsConsentState, AnalyticsContext, AnalyticsContextConsentControls, AnalyticsContextUserControls, AnalyticsStorageAdapter, CreateAnalyticsContextOptions, EventContext, EventProperties, IdentityTrackingMode, InitInput, InitOptions, ONBOARDING_EVENTS, ONBOARDING_PROGRESS_EVENT_ORDER, ONBOARDING_SCREEN_EVENT_PREFIXES, ONBOARDING_SURVEY_EVENTS, OnboardingEventName, OnboardingEventProperties, OnboardingStepTracker, OnboardingSurveyAnswerType, OnboardingSurveyEventName, OnboardingSurveyResponseInput, OnboardingTracker, OnboardingTrackerDefaults, OnboardingTrackerSurveyInput, PAYWALL_ANCHOR_EVENT_CANDIDATES, PAYWALL_EVENTS, PAYWALL_JOURNEY_EVENT_ORDER, PAYWALL_SKIP_EVENT_CANDIDATES, PURCHASE_EVENTS, PURCHASE_SUCCESS_EVENT_CANDIDATES, PaywallEventName, PaywallEventProperties, PaywallJourneyEventName, PaywallTracker, PaywallTrackerDefaults, PaywallTrackerProperties, PurchaseEventName, SetConsentOptions, createAnalyticsContext, init, initAsync, initConsentFirst, initConsentFirstAsync } from './index.js';
+export { AnalyticsClient, AnalyticsClientOptions, AnalyticsConsentState, AnalyticsContext, AnalyticsContextConsentControls, AnalyticsContextUserControls, AnalyticsIngestError, AnalyticsIngestErrorHandler, AnalyticsStorageAdapter, CreateAnalyticsContextOptions, EventContext, EventProperties, IdentityTrackingMode, InitInput, InitOptions, ONBOARDING_EVENTS, ONBOARDING_PROGRESS_EVENT_ORDER, ONBOARDING_SCREEN_EVENT_PREFIXES, ONBOARDING_SURVEY_EVENTS, OnboardingEventName, OnboardingEventProperties, OnboardingStepTracker, OnboardingSurveyAnswerType, OnboardingSurveyEventName, OnboardingSurveyResponseInput, OnboardingTracker, OnboardingTrackerDefaults, OnboardingTrackerSurveyInput, PAYWALL_ANCHOR_EVENT_CANDIDATES, PAYWALL_EVENTS, PAYWALL_JOURNEY_EVENT_ORDER, PAYWALL_SKIP_EVENT_CANDIDATES, PURCHASE_EVENTS, PURCHASE_SUCCESS_EVENT_CANDIDATES, PaywallEventName, PaywallEventProperties, PaywallJourneyEventName, PaywallTracker, PaywallTrackerDefaults, PaywallTrackerProperties, PurchaseEventName, SetConsentOptions, createAnalyticsContext, init, initAsync, initConsentFirst, initConsentFirstAsync } from './index.js';

package/dist/browser.js

@@ -15,7 +15,7 @@ import {
   initAsync,
   initConsentFirst,
   initConsentFirstAsync
-} from "./chunk-O4FIH647.js";
+} from "./chunk-FRXYHOBX.js";
 export {
   AnalyticsClient,
   ONBOARDING_EVENTS,

package/dist/{chunk-O4FIH647.js → chunk-FRXYHOBX.js}

@@ -546,6 +546,49 @@ var sanitizeSurveyResponseInput = (input) => {
 
 // src/analytics-client.ts
 var DEFAULT_CONSENT_STORAGE_KEY = "analyticscli:consent:v1";
+var AUTH_FAILURE_FLUSH_PAUSE_MS = 6e4;
+var resolveDefaultOsNameFromPlatform = (platform) => {
+  if (!platform) {
+    return void 0;
+  }
+  if (platform === "ios") {
+    return "iOS";
+  }
+  if (platform === "android") {
+    return "Android";
+  }
+  if (platform === "web") {
+    return "Web";
+  }
+  if (platform === "mac") {
+    return "macOS";
+  }
+  if (platform === "windows") {
+    return "Windows";
+  }
+  return void 0;
+};
+var IngestSendError = class extends Error {
+  retryable;
+  attempts;
+  status;
+  errorCode;
+  serverMessage;
+  requestId;
+  constructor(input) {
+    super(input.message);
+    this.name = "IngestSendError";
+    this.retryable = input.retryable;
+    this.attempts = input.attempts;
+    this.status = input.status;
+    this.errorCode = input.errorCode;
+    this.serverMessage = input.serverMessage;
+    this.requestId = input.requestId;
+    if (input.cause !== void 0) {
+      this.cause = input.cause;
+    }
+  }
+};
 var AnalyticsClient = class {
   apiKey;
   hasIngestConfig;
@@ -554,6 +597,7 @@ var AnalyticsClient = class {
   flushIntervalMs;
   maxRetries;
   debug;
+  onIngestError;
   platform;
   projectSurface;
   appVersion;
@@ -586,6 +630,7 @@ var AnalyticsClient = class {
   deferredEventsBeforeHydration = [];
   onboardingStepViewStateSessionId = null;
   onboardingStepViewsSeen = /* @__PURE__ */ new Set();
+  flushPausedUntilMs = 0;
   constructor(options) {
     const normalizedOptions = this.normalizeOptions(options);
     this.apiKey = this.readRequiredStringOption(normalizedOptions.apiKey);
@@ -598,11 +643,17 @@ var AnalyticsClient = class {
     this.flushIntervalMs = normalizedOptions.flushIntervalMs ?? 5e3;
     this.maxRetries = normalizedOptions.maxRetries ?? 4;
     this.debug = normalizedOptions.debug ?? false;
+    this.onIngestError = typeof normalizedOptions.onIngestError === "function" ? normalizedOptions.onIngestError : null;
     this.platform = this.normalizePlatformOption(normalizedOptions.platform) ?? detectDefaultPlatform();
     this.projectSurface = this.normalizeProjectSurfaceOption(normalizedOptions.projectSurface);
     this.appVersion = this.readRequiredStringOption(normalizedOptions.appVersion) || detectDefaultAppVersion();
     this.identityTrackingMode = this.resolveIdentityTrackingModeOption(normalizedOptions);
-    this.context = { ...normalizedOptions.context ?? {} };
+    const initialContext = { ...normalizedOptions.context ?? {} };
+    const hasExplicitOsName = this.readRequiredStringOption(initialContext.osName).length > 0;
+    this.context = {
+      ...initialContext,
+      osName: hasExplicitOsName ? initialContext.osName : resolveDefaultOsNameFromPlatform(this.platform) ?? initialContext.osName
+    };
     this.runtimeEnv = detectRuntimeEnv();
     this.persistConsentState = normalizedOptions.persistConsentState ?? false;
     this.consentStorageKey = this.readRequiredStringOption(normalizedOptions.consentStorageKey) || DEFAULT_CONSENT_STORAGE_KEY;
@@ -635,6 +686,7 @@ var AnalyticsClient = class {
       this.writePersistedConsent(this.configuredStorage, this.fullTrackingConsentGranted);
     }
     this.hydrationPromise = this.hydrateIdentityFromStorage();
+    this.enqueueInitialSessionStart();
     this.startAutoFlush();
   }
   /**
@@ -692,6 +744,32 @@ var AnalyticsClient = class {
       ...context
     };
   }
+  enqueueInitialSessionStart() {
+    if (!this.consentGranted) {
+      return;
+    }
+    if (this.shouldDeferEventsUntilHydrated()) {
+      this.deferEventUntilHydrated(() => {
+        this.enqueueInitialSessionStart();
+      });
+      return;
+    }
+    const sessionId = this.getSessionId();
+    this.enqueue({
+      eventId: randomId(),
+      eventName: "session_start",
+      ts: nowIso(),
+      sessionId,
+      anonId: this.anonId,
+      userId: this.getEventUserId(),
+      properties: this.withRuntimeMetadata({ source: "sdk_mount" }, sessionId),
+      platform: this.platform,
+      projectSurface: this.projectSurface,
+      appVersion: this.appVersion,
+      ...this.withEventContext(),
+      type: "track"
+    });
+  }
   /**
    * Associates following events with a known user id.
    * Anonymous history remains linked by anonId/sessionId.
@@ -1061,6 +1139,9 @@ var AnalyticsClient = class {
     if (this.queue.length === 0 || this.isFlushing || !this.consentGranted) {
       return;
     }
+    if (Date.now() < this.flushPausedUntilMs) {
+      return;
+    }
     this.isFlushing = true;
     const batch = this.queue.splice(0, this.batchSize);
     const payload = {
@@ -1075,9 +1156,20 @@ var AnalyticsClient = class {
     }
     try {
       await this.sendWithRetry(payload);
+      this.flushPausedUntilMs = 0;
     } catch (error) {
-      this.log("Send failed permanently, requeueing batch", error);
       this.queue = [...batch, ...this.queue];
+      const ingestError = this.toIngestSendError(error);
+      const diagnostics = this.createIngestDiagnostics(ingestError, batch.length, this.queue.length);
+      if (ingestError.status === 401 || ingestError.status === 403) {
+        this.flushPausedUntilMs = Date.now() + AUTH_FAILURE_FLUSH_PAUSE_MS;
+        this.log("Pausing ingest flush after auth failure", {
+          status: ingestError.status,
+          retryAfterMs: AUTH_FAILURE_FLUSH_PAUSE_MS
+        });
+      }
+      this.log("Send failed permanently, requeueing batch", diagnostics);
+      this.reportIngestError(diagnostics);
     } finally {
       this.isFlushing = false;
     }
@@ -1106,9 +1198,8 @@ var AnalyticsClient = class {
     });
   }
   async sendWithRetry(payload) {
-    let attempt = 0;
     let delay = 250;
-    while (attempt <= this.maxRetries) {
+    for (let attempt = 1; attempt <= this.maxRetries + 1; attempt += 1) {
       try {
         const response = await fetch(`${this.endpoint}/v1/collect`, {
           method: "POST",
@@ -1120,19 +1211,110 @@ var AnalyticsClient = class {
           keepalive: true
         });
         if (!response.ok) {
-          throw new Error(`ingest status=${response.status}`);
+          throw await this.createHttpIngestSendError(response, attempt);
         }
         return;
       } catch (error) {
-        attempt += 1;
-        if (attempt > this.maxRetries) {
-          throw error;
+        const normalized = this.toIngestSendError(error, attempt);
+        const finalAttempt = attempt >= this.maxRetries + 1;
+        this.log("Ingest attempt failed", {
+          attempt: normalized.attempts,
+          maxRetries: this.maxRetries,
+          retryable: normalized.retryable,
+          status: normalized.status,
+          errorCode: normalized.errorCode,
+          requestId: normalized.requestId,
+          nextRetryInMs: !finalAttempt && normalized.retryable ? delay : null
+        });
+        if (finalAttempt || !normalized.retryable) {
+          throw normalized;
         }
         await new Promise((resolve) => setTimeout(resolve, delay));
         delay *= 2;
       }
     }
   }
+  async createHttpIngestSendError(response, attempts) {
+    const requestId = response.headers.get("x-request-id") ?? response.headers.get("cf-ray") ?? void 0;
+    let errorCode;
+    let serverMessage;
+    try {
+      const parsed = await response.json();
+      const errorBody = parsed && typeof parsed === "object" && parsed.error && typeof parsed.error === "object" ? parsed.error : void 0;
+      if (typeof errorBody?.code === "string") {
+        errorCode = errorBody.code;
+      }
+      if (typeof errorBody?.message === "string") {
+        serverMessage = errorBody.message;
+      }
+    } catch {
+    }
+    const retryable = this.shouldRetryHttpStatus(response.status);
+    const statusSuffix = errorCode ? ` ${errorCode}` : "";
+    const message = `ingest status=${response.status}${statusSuffix}`;
+    return new IngestSendError({
+      message,
+      retryable,
+      attempts,
+      status: response.status,
+      errorCode,
+      serverMessage,
+      requestId
+    });
+  }
+  shouldRetryHttpStatus(status) {
+    return status === 408 || status === 425 || status === 429 || status >= 500;
+  }
+  toIngestSendError(error, attempts) {
+    if (error instanceof IngestSendError) {
+      const resolvedAttempts = attempts ?? error.attempts;
+      return new IngestSendError({
+        message: error.message,
+        retryable: error.retryable,
+        attempts: resolvedAttempts,
+        status: error.status,
+        errorCode: error.errorCode,
+        serverMessage: error.serverMessage,
+        requestId: error.requestId,
+        cause: error.cause
+      });
+    }
+    const fallbackMessage = error instanceof Error ? error.message : "ingest request failed";
+    return new IngestSendError({
+      message: fallbackMessage,
+      retryable: true,
+      attempts: attempts ?? 1,
+      cause: error
+    });
+  }
+  createIngestDiagnostics(error, batchSize, queueSize) {
+    return {
+      name: "AnalyticsIngestError",
+      message: error.message,
+      endpoint: this.endpoint,
+      path: "/v1/collect",
+      status: error.status,
+      errorCode: error.errorCode,
+      serverMessage: error.serverMessage,
+      requestId: error.requestId,
+      retryable: error.retryable,
+      attempts: error.attempts,
+      maxRetries: this.maxRetries,
+      batchSize,
+      queueSize,
+      timestamp: nowIso()
+    };
+  }
+  reportIngestError(error) {
+    if (!this.onIngestError) {
+      return;
+    }
+    try {
+      this.onIngestError(error);
+    } catch (callbackError) {
+      this.log("onIngestError callback threw", callbackError);
+    }
+  }
   parsePersistedConsent(raw) {
     if (raw === "granted") {
       return true;