@analyticscli/sdk 0.1.0-preview.6 → 0.1.0-preview.8

package/dist/browser.cjs

@@ -237,7 +237,28 @@ var randomId = () => {
   if (globalThis.crypto?.randomUUID) {
     return globalThis.crypto.randomUUID();
   }
-  return `${Date.now()}-${Math.random().toString(16).slice(2, 12)}`;
+  const bytes = new Uint8Array(16);
+  if (globalThis.crypto?.getRandomValues) {
+    globalThis.crypto.getRandomValues(bytes);
+  } else {
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(Math.random() * 256);
+    }
+  }
+  const byte6 = bytes[6] ?? 0;
+  const byte8 = bytes[8] ?? 0;
+  bytes[6] = byte6 & 15 | 64;
+  bytes[8] = byte8 & 63 | 128;
+  let output = "";
+  for (let index = 0; index < bytes.length; index += 1) {
+    const byte = bytes[index] ?? 0;
+    const hex = byte.toString(16).padStart(2, "0");
+    output += hex;
+    if (index === 3 || index === 5 || index === 7 || index === 9) {
+      output += "-";
+    }
+  }
+  return output;
 };
 var readStorageSync = (storage, key) => {
   if (!storage) {
@@ -566,6 +587,28 @@ var sanitizeSurveyResponseInput = (input) => {
 
 // src/analytics-client.ts
 var DEFAULT_CONSENT_STORAGE_KEY = "analyticscli:consent:v1";
+var AUTH_FAILURE_FLUSH_PAUSE_MS = 6e4;
+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;
@@ -574,6 +617,7 @@ var AnalyticsClient = class {
   flushIntervalMs;
   maxRetries;
   debug;
+  onIngestError;
   platform;
   projectSurface;
   appVersion;
@@ -606,6 +650,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);
@@ -618,6 +663,7 @@ 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();
@@ -1081,6 +1127,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 = {
@@ -1095,9 +1144,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;
     }
@@ -1126,9 +1186,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",
@@ -1140,19 +1199,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-RGEYDN6A.js";
+} from "./chunk-S3MLRL5U.js";
 export {
   AnalyticsClient,
   ONBOARDING_EVENTS,

package/dist/{chunk-RGEYDN6A.js → chunk-S3MLRL5U.js}

@@ -196,7 +196,28 @@ var randomId = () => {
   if (globalThis.crypto?.randomUUID) {
     return globalThis.crypto.randomUUID();
   }
-  return `${Date.now()}-${Math.random().toString(16).slice(2, 12)}`;
+  const bytes = new Uint8Array(16);
+  if (globalThis.crypto?.getRandomValues) {
+    globalThis.crypto.getRandomValues(bytes);
+  } else {
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(Math.random() * 256);
+    }
+  }
+  const byte6 = bytes[6] ?? 0;
+  const byte8 = bytes[8] ?? 0;
+  bytes[6] = byte6 & 15 | 64;
+  bytes[8] = byte8 & 63 | 128;
+  let output = "";
+  for (let index = 0; index < bytes.length; index += 1) {
+    const byte = bytes[index] ?? 0;
+    const hex = byte.toString(16).padStart(2, "0");
+    output += hex;
+    if (index === 3 || index === 5 || index === 7 || index === 9) {
+      output += "-";
+    }
+  }
+  return output;
 };
 var readStorageSync = (storage, key) => {
   if (!storage) {
@@ -525,6 +546,28 @@ var sanitizeSurveyResponseInput = (input) => {
 
 // src/analytics-client.ts
 var DEFAULT_CONSENT_STORAGE_KEY = "analyticscli:consent:v1";
+var AUTH_FAILURE_FLUSH_PAUSE_MS = 6e4;
+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;
@@ -533,6 +576,7 @@ var AnalyticsClient = class {
   flushIntervalMs;
   maxRetries;
   debug;
+  onIngestError;
   platform;
   projectSurface;
   appVersion;
@@ -565,6 +609,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);
@@ -577,6 +622,7 @@ 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();
@@ -1040,6 +1086,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 = {
@@ -1054,9 +1103,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;
     }
@@ -1085,9 +1145,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",
@@ -1099,19 +1158,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/index.cjs

@@ -237,7 +237,28 @@ var randomId = () => {
   if (globalThis.crypto?.randomUUID) {
     return globalThis.crypto.randomUUID();
   }
-  return `${Date.now()}-${Math.random().toString(16).slice(2, 12)}`;
+  const bytes = new Uint8Array(16);
+  if (globalThis.crypto?.getRandomValues) {
+    globalThis.crypto.getRandomValues(bytes);
+  } else {
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(Math.random() * 256);
+    }
+  }
+  const byte6 = bytes[6] ?? 0;
+  const byte8 = bytes[8] ?? 0;
+  bytes[6] = byte6 & 15 | 64;
+  bytes[8] = byte8 & 63 | 128;
+  let output = "";
+  for (let index = 0; index < bytes.length; index += 1) {
+    const byte = bytes[index] ?? 0;
+    const hex = byte.toString(16).padStart(2, "0");
+    output += hex;
+    if (index === 3 || index === 5 || index === 7 || index === 9) {
+      output += "-";
+    }
+  }
+  return output;
 };
 var readStorageSync = (storage, key) => {
   if (!storage) {
@@ -566,6 +587,28 @@ var sanitizeSurveyResponseInput = (input) => {
 
 // src/analytics-client.ts
 var DEFAULT_CONSENT_STORAGE_KEY = "analyticscli:consent:v1";
+var AUTH_FAILURE_FLUSH_PAUSE_MS = 6e4;
+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;
@@ -574,6 +617,7 @@ var AnalyticsClient = class {
   flushIntervalMs;
   maxRetries;
   debug;
+  onIngestError;
   platform;
   projectSurface;
   appVersion;
@@ -606,6 +650,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);
@@ -618,6 +663,7 @@ 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();
@@ -1081,6 +1127,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 = {
@@ -1095,9 +1144,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;
     }
@@ -1126,9 +1186,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",
@@ -1140,19 +1199,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/index.d.cts

@@ -130,6 +130,65 @@ type PaywallTracker = {
 };
 type AnalyticsConsentState = 'granted' | 'denied' | 'unknown';
 type IdentityTrackingMode = 'strict' | 'consent_gated' | 'always_on';
+type AnalyticsIngestError = {
+    /**
+     * Stable error name for host-app monitoring.
+     */
+    name: 'AnalyticsIngestError';
+    /**
+     * Human-readable summary of the ingest failure.
+     */
+    message: string;
+    /**
+     * Collector endpoint base URL configured in the SDK client.
+     */
+    endpoint: string;
+    /**
+     * Collector path that failed.
+     */
+    path: '/v1/collect';
+    /**
+     * HTTP status when available.
+     */
+    status?: number;
+    /**
+     * Structured server error code when available.
+     */
+    errorCode?: string;
+    /**
+     * Structured server message when available.
+     */
+    serverMessage?: string;
+    /**
+     * Request correlation id when exposed by the collector response.
+     */
+    requestId?: string;
+    /**
+     * Whether retrying can help (`true` for network/5xx/429 class failures).
+     */
+    retryable: boolean;
+    /**
+     * Number of attempts that were made for this batch.
+     */
+    attempts: number;
+    /**
+     * SDK max retries configured on the client.
+     */
+    maxRetries: number;
+    /**
+     * Number of events in the failed batch.
+     */
+    batchSize: number;
+    /**
+     * Current queue size after requeue.
+     */
+    queueSize: number;
+    /**
+     * ISO timestamp when the failure was surfaced to host-app callbacks.
+     */
+    timestamp: string;
+};
+type AnalyticsIngestErrorHandler = (error: AnalyticsIngestError) => void;
 type SetConsentOptions = {
     /**
      * Whether consent state should be persisted to storage when enabled.
@@ -158,6 +217,14 @@ type AnalyticsClientOptions = {
      * `debug: __DEV__`
      */
     debug?: boolean | null;
+    /**
+     * Optional host-app hook for ingest delivery failures.
+     * Use this to forward operational diagnostics to your own monitoring stack.
+     *
+     * GDPR recommendation:
+     * forward this structured metadata only and avoid attaching event payloads or raw identifiers.
+     */
+    onIngestError?: AnalyticsIngestErrorHandler | null;
     /**
      * Optional platform hint.
      * React Native/Expo: passing `Platform.OS` directly is supported.
@@ -246,6 +313,7 @@ declare class AnalyticsClient {
     private readonly flushIntervalMs;
     private readonly maxRetries;
     private readonly debug;
+    private readonly onIngestError;
     private readonly platform;
     private readonly projectSurface;
     private readonly appVersion;
@@ -278,6 +346,7 @@ declare class AnalyticsClient {
     private deferredEventsBeforeHydration;
     private onboardingStepViewStateSessionId;
     private onboardingStepViewsSeen;
+    private flushPausedUntilMs;
     constructor(options: AnalyticsClientOptions);
     /**
      * Resolves once client initialization work completes.
@@ -373,6 +442,11 @@ declare class AnalyticsClient {
     private enqueue;
     private scheduleFlush;
     private sendWithRetry;
+    private createHttpIngestSendError;
+    private shouldRetryHttpStatus;
+    private toIngestSendError;
+    private createIngestDiagnostics;
+    private reportIngestError;
     private parsePersistedConsent;
     private readPersistedConsentSync;
     private readPersistedConsentAsync;
@@ -489,4 +563,4 @@ declare const initConsentFirst: (input?: InitInput) => AnalyticsClient;
 declare const initAsync: (input?: InitInput) => Promise<AnalyticsClient>;
 declare const initConsentFirstAsync: (input?: InitInput) => Promise<AnalyticsClient>;
 
-export { AnalyticsClient, type AnalyticsClientOptions, type AnalyticsConsentState, type AnalyticsContext, type AnalyticsContextConsentControls, type AnalyticsContextUserControls, type AnalyticsStorageAdapter, type CreateAnalyticsContextOptions, type EventContext, type EventProperties, type IdentityTrackingMode, type InitInput, type InitOptions, ONBOARDING_EVENTS, ONBOARDING_PROGRESS_EVENT_ORDER, ONBOARDING_SCREEN_EVENT_PREFIXES, ONBOARDING_SURVEY_EVENTS, type OnboardingEventName, type OnboardingEventProperties, type OnboardingStepTracker, type OnboardingSurveyAnswerType, type OnboardingSurveyEventName, type OnboardingSurveyResponseInput, type OnboardingTracker, type OnboardingTrackerDefaults, type OnboardingTrackerSurveyInput, PAYWALL_ANCHOR_EVENT_CANDIDATES, PAYWALL_EVENTS, PAYWALL_JOURNEY_EVENT_ORDER, PAYWALL_SKIP_EVENT_CANDIDATES, PURCHASE_EVENTS, PURCHASE_SUCCESS_EVENT_CANDIDATES, type PaywallEventName, type PaywallEventProperties, type PaywallJourneyEventName, type PaywallTracker, type PaywallTrackerDefaults, type PaywallTrackerProperties, type PurchaseEventName, type SetConsentOptions, createAnalyticsContext, init, initAsync, initConsentFirst, initConsentFirstAsync };
+export { AnalyticsClient, type AnalyticsClientOptions, type AnalyticsConsentState, type AnalyticsContext, type AnalyticsContextConsentControls, type AnalyticsContextUserControls, type AnalyticsIngestError, type AnalyticsIngestErrorHandler, type AnalyticsStorageAdapter, type CreateAnalyticsContextOptions, type EventContext, type EventProperties, type IdentityTrackingMode, type InitInput, type InitOptions, ONBOARDING_EVENTS, ONBOARDING_PROGRESS_EVENT_ORDER, ONBOARDING_SCREEN_EVENT_PREFIXES, ONBOARDING_SURVEY_EVENTS, type OnboardingEventName, type OnboardingEventProperties, type OnboardingStepTracker, type OnboardingSurveyAnswerType, type OnboardingSurveyEventName, type OnboardingSurveyResponseInput, type OnboardingTracker, type OnboardingTrackerDefaults, type OnboardingTrackerSurveyInput, PAYWALL_ANCHOR_EVENT_CANDIDATES, PAYWALL_EVENTS, PAYWALL_JOURNEY_EVENT_ORDER, PAYWALL_SKIP_EVENT_CANDIDATES, PURCHASE_EVENTS, PURCHASE_SUCCESS_EVENT_CANDIDATES, type PaywallEventName, type PaywallEventProperties, type PaywallJourneyEventName, type PaywallTracker, type PaywallTrackerDefaults, type PaywallTrackerProperties, type PurchaseEventName, type SetConsentOptions, createAnalyticsContext, init, initAsync, initConsentFirst, initConsentFirstAsync };

package/dist/index.d.ts

@@ -130,6 +130,65 @@ type PaywallTracker = {
 };
 type AnalyticsConsentState = 'granted' | 'denied' | 'unknown';
 type IdentityTrackingMode = 'strict' | 'consent_gated' | 'always_on';
+type AnalyticsIngestError = {
+    /**
+     * Stable error name for host-app monitoring.
+     */
+    name: 'AnalyticsIngestError';
+    /**
+     * Human-readable summary of the ingest failure.
+     */
+    message: string;
+    /**
+     * Collector endpoint base URL configured in the SDK client.
+     */
+    endpoint: string;
+    /**
+     * Collector path that failed.
+     */
+    path: '/v1/collect';
+    /**
+     * HTTP status when available.
+     */
+    status?: number;
+    /**
+     * Structured server error code when available.
+     */
+    errorCode?: string;
+    /**
+     * Structured server message when available.
+     */
+    serverMessage?: string;
+    /**
+     * Request correlation id when exposed by the collector response.
+     */
+    requestId?: string;
+    /**
+     * Whether retrying can help (`true` for network/5xx/429 class failures).
+     */
+    retryable: boolean;
+    /**
+     * Number of attempts that were made for this batch.
+     */
+    attempts: number;
+    /**
+     * SDK max retries configured on the client.
+     */
+    maxRetries: number;
+    /**
+     * Number of events in the failed batch.
+     */
+    batchSize: number;
+    /**
+     * Current queue size after requeue.
+     */
+    queueSize: number;
+    /**
+     * ISO timestamp when the failure was surfaced to host-app callbacks.
+     */
+    timestamp: string;
+};
+type AnalyticsIngestErrorHandler = (error: AnalyticsIngestError) => void;
 type SetConsentOptions = {
     /**
      * Whether consent state should be persisted to storage when enabled.
@@ -158,6 +217,14 @@ type AnalyticsClientOptions = {
      * `debug: __DEV__`
      */
     debug?: boolean | null;
+    /**
+     * Optional host-app hook for ingest delivery failures.
+     * Use this to forward operational diagnostics to your own monitoring stack.
+     *
+     * GDPR recommendation:
+     * forward this structured metadata only and avoid attaching event payloads or raw identifiers.
+     */
+    onIngestError?: AnalyticsIngestErrorHandler | null;
     /**
      * Optional platform hint.
      * React Native/Expo: passing `Platform.OS` directly is supported.
@@ -246,6 +313,7 @@ declare class AnalyticsClient {
     private readonly flushIntervalMs;
     private readonly maxRetries;
     private readonly debug;
+    private readonly onIngestError;
     private readonly platform;
     private readonly projectSurface;
     private readonly appVersion;
@@ -278,6 +346,7 @@ declare class AnalyticsClient {
     private deferredEventsBeforeHydration;
     private onboardingStepViewStateSessionId;
     private onboardingStepViewsSeen;
+    private flushPausedUntilMs;
     constructor(options: AnalyticsClientOptions);
     /**
      * Resolves once client initialization work completes.
@@ -373,6 +442,11 @@ declare class AnalyticsClient {
     private enqueue;
     private scheduleFlush;
     private sendWithRetry;
+    private createHttpIngestSendError;
+    private shouldRetryHttpStatus;
+    private toIngestSendError;
+    private createIngestDiagnostics;
+    private reportIngestError;
     private parsePersistedConsent;
     private readPersistedConsentSync;
     private readPersistedConsentAsync;
@@ -489,4 +563,4 @@ declare const initConsentFirst: (input?: InitInput) => AnalyticsClient;
 declare const initAsync: (input?: InitInput) => Promise<AnalyticsClient>;
 declare const initConsentFirstAsync: (input?: InitInput) => Promise<AnalyticsClient>;
 
-export { AnalyticsClient, type AnalyticsClientOptions, type AnalyticsConsentState, type AnalyticsContext, type AnalyticsContextConsentControls, type AnalyticsContextUserControls, type AnalyticsStorageAdapter, type CreateAnalyticsContextOptions, type EventContext, type EventProperties, type IdentityTrackingMode, type InitInput, type InitOptions, ONBOARDING_EVENTS, ONBOARDING_PROGRESS_EVENT_ORDER, ONBOARDING_SCREEN_EVENT_PREFIXES, ONBOARDING_SURVEY_EVENTS, type OnboardingEventName, type OnboardingEventProperties, type OnboardingStepTracker, type OnboardingSurveyAnswerType, type OnboardingSurveyEventName, type OnboardingSurveyResponseInput, type OnboardingTracker, type OnboardingTrackerDefaults, type OnboardingTrackerSurveyInput, PAYWALL_ANCHOR_EVENT_CANDIDATES, PAYWALL_EVENTS, PAYWALL_JOURNEY_EVENT_ORDER, PAYWALL_SKIP_EVENT_CANDIDATES, PURCHASE_EVENTS, PURCHASE_SUCCESS_EVENT_CANDIDATES, type PaywallEventName, type PaywallEventProperties, type PaywallJourneyEventName, type PaywallTracker, type PaywallTrackerDefaults, type PaywallTrackerProperties, type PurchaseEventName, type SetConsentOptions, createAnalyticsContext, init, initAsync, initConsentFirst, initConsentFirstAsync };
+export { AnalyticsClient, type AnalyticsClientOptions, type AnalyticsConsentState, type AnalyticsContext, type AnalyticsContextConsentControls, type AnalyticsContextUserControls, type AnalyticsIngestError, type AnalyticsIngestErrorHandler, type AnalyticsStorageAdapter, type CreateAnalyticsContextOptions, type EventContext, type EventProperties, type IdentityTrackingMode, type InitInput, type InitOptions, ONBOARDING_EVENTS, ONBOARDING_PROGRESS_EVENT_ORDER, ONBOARDING_SCREEN_EVENT_PREFIXES, ONBOARDING_SURVEY_EVENTS, type OnboardingEventName, type OnboardingEventProperties, type OnboardingStepTracker, type OnboardingSurveyAnswerType, type OnboardingSurveyEventName, type OnboardingSurveyResponseInput, type OnboardingTracker, type OnboardingTrackerDefaults, type OnboardingTrackerSurveyInput, PAYWALL_ANCHOR_EVENT_CANDIDATES, PAYWALL_EVENTS, PAYWALL_JOURNEY_EVENT_ORDER, PAYWALL_SKIP_EVENT_CANDIDATES, PURCHASE_EVENTS, PURCHASE_SUCCESS_EVENT_CANDIDATES, type PaywallEventName, type PaywallEventProperties, type PaywallJourneyEventName, type PaywallTracker, type PaywallTrackerDefaults, type PaywallTrackerProperties, type PurchaseEventName, type SetConsentOptions, createAnalyticsContext, init, initAsync, initConsentFirst, initConsentFirstAsync };

package/dist/index.js

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

package/dist/react-native.cjs

@@ -237,7 +237,28 @@ var randomId = () => {
   if (globalThis.crypto?.randomUUID) {
     return globalThis.crypto.randomUUID();
   }
-  return `${Date.now()}-${Math.random().toString(16).slice(2, 12)}`;
+  const bytes = new Uint8Array(16);
+  if (globalThis.crypto?.getRandomValues) {
+    globalThis.crypto.getRandomValues(bytes);
+  } else {
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(Math.random() * 256);
+    }
+  }
+  const byte6 = bytes[6] ?? 0;
+  const byte8 = bytes[8] ?? 0;
+  bytes[6] = byte6 & 15 | 64;
+  bytes[8] = byte8 & 63 | 128;
+  let output = "";
+  for (let index = 0; index < bytes.length; index += 1) {
+    const byte = bytes[index] ?? 0;
+    const hex = byte.toString(16).padStart(2, "0");
+    output += hex;
+    if (index === 3 || index === 5 || index === 7 || index === 9) {
+      output += "-";
+    }
+  }
+  return output;
 };
 var readStorageSync = (storage, key) => {
   if (!storage) {
@@ -566,6 +587,28 @@ var sanitizeSurveyResponseInput = (input) => {
 
 // src/analytics-client.ts
 var DEFAULT_CONSENT_STORAGE_KEY = "analyticscli:consent:v1";
+var AUTH_FAILURE_FLUSH_PAUSE_MS = 6e4;
+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;
@@ -574,6 +617,7 @@ var AnalyticsClient = class {
   flushIntervalMs;
   maxRetries;
   debug;
+  onIngestError;
   platform;
   projectSurface;
   appVersion;
@@ -606,6 +650,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);
@@ -618,6 +663,7 @@ 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();
@@ -1081,6 +1127,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 = {
@@ -1095,9 +1144,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;
     }
@@ -1126,9 +1186,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",
@@ -1140,19 +1199,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/react-native.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/react-native.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/react-native.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@analyticscli/sdk",
-  "version": "0.1.0-preview.6",
+  "version": "0.1.0-preview.8",
   "description": "TypeScript SDK for sending onboarding, paywall, purchase and survey analytics events to AnalyticsCLI.",
   "license": "MIT",
   "type": "module",