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

package/dist/index.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/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.
@@ -296,6 +365,7 @@ declare class AnalyticsClient {
      * Sets or updates shared event context fields (useful for mobile device/app metadata).
      */
     setContext(context: EventContext): void;
+    private enqueueInitialSessionStart;
     /**
      * Associates following events with a known user id.
      * Anonymous history remains linked by anonId/sessionId.
@@ -373,6 +443,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 +564,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.
@@ -296,6 +365,7 @@ declare class AnalyticsClient {
      * Sets or updates shared event context fields (useful for mobile device/app metadata).
      */
     setContext(context: EventContext): void;
+    private enqueueInitialSessionStart;
     /**
      * Associates following events with a known user id.
      * Anonymous history remains linked by anonId/sessionId.
@@ -373,6 +443,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 +564,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-O4FIH647.js";
+} from "./chunk-FRXYHOBX.js";
 export {
   AnalyticsClient,
   ONBOARDING_EVENTS,