@analyticscli/sdk 0.1.0-preview.4 → 0.1.0-preview.5

package/dist/index.cjs

@@ -37,6 +37,8 @@ __export(index_exports, {
   init: () => init,
   initAsync: () => initAsync,
   initBrowserFromEnv: () => initBrowserFromEnv,
+  initConsentFirst: () => initConsentFirst,
+  initConsentFirstAsync: () => initConsentFirstAsync,
   initFromEnv: () => initFromEnv,
   initReactNativeFromEnv: () => initReactNativeFromEnv
 });
@@ -137,6 +139,9 @@ var validateEvent = (event, index) => {
   if (!isOptionalStringMax(event.platform, 64)) {
     return { success: false, reason: `events[${index}].platform is invalid` };
   }
+  if (!isOptionalStringMax(event.projectSurface, 64)) {
+    return { success: false, reason: `events[${index}].projectSurface is invalid` };
+  }
   if (!isOptionalStringMax(event.appVersion, 64)) {
     return { success: false, reason: `events[${index}].appVersion is invalid` };
   }
@@ -565,6 +570,7 @@ var sanitizeSurveyResponseInput = (input) => {
 };
 
 // src/analytics-client.ts
+var DEFAULT_CONSENT_STORAGE_KEY = "analyticscli:consent:v1";
 var AnalyticsClient = class {
   apiKey;
   hasIngestConfig;
@@ -574,10 +580,17 @@ var AnalyticsClient = class {
   maxRetries;
   debug;
   platform;
+  projectSurface;
   appVersion;
+  identityTrackingMode;
   context;
+  configuredStorage;
   storage;
   storageReadsAreAsync;
+  persistConsentState;
+  consentStorageKey;
+  hasExplicitInitialConsent;
+  hasExplicitInitialFullTrackingConsent;
   sessionTimeoutMs;
   dedupeOnboardingStepViewsPerSession;
   runtimeEnv;
@@ -588,6 +601,7 @@ var AnalyticsClient = class {
   flushTimer = null;
   isFlushing = false;
   consentGranted = true;
+  fullTrackingConsentGranted = false;
   userId = null;
   anonId;
   sessionId;
@@ -610,34 +624,46 @@ var AnalyticsClient = class {
     this.maxRetries = normalizedOptions.maxRetries ?? 4;
     this.debug = normalizedOptions.debug ?? false;
     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 ?? {} };
     this.runtimeEnv = detectRuntimeEnv();
-    const useCookieStorage = normalizedOptions.useCookieStorage ?? Boolean(normalizedOptions.cookieDomain);
-    const cookieStorage = resolveCookieStorageAdapter(
-      useCookieStorage,
-      normalizedOptions.cookieDomain,
-      normalizedOptions.cookieMaxAgeSeconds ?? DEFAULT_COOKIE_MAX_AGE_SECONDS
-    );
-    const browserStorage = resolveBrowserStorageAdapter();
-    this.storage = normalizedOptions.storage ?? (cookieStorage && browserStorage ? combineStorageAdapters(cookieStorage, browserStorage) : cookieStorage ?? browserStorage);
-    this.storageReadsAreAsync = this.detectAsyncStorageReads();
+    this.persistConsentState = normalizedOptions.persistConsentState ?? false;
+    this.consentStorageKey = this.readRequiredStringOption(normalizedOptions.consentStorageKey) || DEFAULT_CONSENT_STORAGE_KEY;
+    this.hasExplicitInitialConsent = typeof normalizedOptions.initialConsentGranted === "boolean";
+    this.hasExplicitInitialFullTrackingConsent = typeof normalizedOptions.initialFullTrackingConsentGranted === "boolean";
     this.sessionTimeoutMs = normalizedOptions.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
-    this.dedupeOnboardingStepViewsPerSession = normalizedOptions.dedupeOnboardingStepViewsPerSession ?? false;
-    const providedAnonId = normalizedOptions.anonId?.trim();
-    const providedSessionId = normalizedOptions.sessionId?.trim();
+    this.dedupeOnboardingStepViewsPerSession = normalizedOptions.dedupeOnboardingStepViewsPerSession ?? true;
+    this.configuredStorage = this.resolveConfiguredStorage(normalizedOptions);
+    const persistedFullTrackingConsent = this.readPersistedConsentSync(this.configuredStorage);
+    const configuredFullTrackingConsent = normalizedOptions.initialFullTrackingConsentGranted;
+    const initialFullTrackingConsentGranted = typeof configuredFullTrackingConsent === "boolean" ? configuredFullTrackingConsent : persistedFullTrackingConsent ?? false;
+    this.fullTrackingConsentGranted = this.identityTrackingMode === "always_on" || initialFullTrackingConsentGranted;
+    this.storage = this.isFullTrackingActive() ? this.configuredStorage : null;
+    this.storageReadsAreAsync = this.detectAsyncStorageReads();
+    const providedAnonId = this.isFullTrackingActive() ? this.readRequiredStringOption(normalizedOptions.anonId) : "";
+    const providedSessionId = this.isFullTrackingActive() ? this.readRequiredStringOption(normalizedOptions.sessionId) : "";
     this.hasExplicitAnonId = Boolean(providedAnonId);
     this.hasExplicitSessionId = Boolean(providedSessionId);
     this.anonId = providedAnonId || this.ensureDeviceId();
     this.sessionId = providedSessionId || this.ensureSessionId();
     this.sessionEventSeq = this.readSessionEventSeq(this.sessionId);
-    this.consentGranted = this.hasIngestConfig;
+    const persistedConsent = this.readPersistedConsentSync(this.storage);
+    const configuredConsent = normalizedOptions.initialConsentGranted;
+    const initialConsentGranted = typeof configuredConsent === "boolean" ? configuredConsent : persistedConsent ?? this.hasIngestConfig;
+    this.consentGranted = this.hasIngestConfig && initialConsentGranted;
+    if (this.hasExplicitInitialConsent && this.persistConsentState) {
+      this.writePersistedConsent(this.storage, this.consentGranted);
+    }
+    if (this.hasExplicitInitialFullTrackingConsent && this.persistConsentState) {
+      this.writePersistedConsent(this.configuredStorage, this.fullTrackingConsentGranted);
+    }
     this.hydrationPromise = this.hydrateIdentityFromStorage();
     this.startAutoFlush();
   }
   /**
-   * Resolves once any async storage adapter hydration completes.
-   * Useful in React Native when using async persistence (for example AsyncStorage).
+   * Resolves once client initialization work completes.
    */
   async ready() {
     await this.hydrationPromise;
@@ -646,22 +672,41 @@ var AnalyticsClient = class {
    * Enables or disables event collection.
    * When disabled, queued events are dropped immediately.
    */
-  setConsent(granted) {
+  setConsent(granted, options = {}) {
     if (granted && !this.hasIngestConfig) {
       this.log("Ignoring consent opt-in because `apiKey` is missing");
       return;
     }
     this.consentGranted = granted;
+    if ((options.persist ?? true) && this.persistConsentState) {
+      this.writePersistedConsent(this.storage, granted);
+    }
+    if (this.identityTrackingMode === "consent_gated") {
+      this.setFullTrackingConsent(granted, options);
+    }
     if (!granted) {
       this.queue = [];
       this.deferredEventsBeforeHydration = [];
     }
   }
-  optIn() {
-    this.setConsent(true);
+  optIn(options) {
+    this.setConsent(true, options);
   }
-  optOut() {
-    this.setConsent(false);
+  optOut(options) {
+    this.setConsent(false, options);
+  }
+  getConsent() {
+    return this.consentGranted;
+  }
+  getConsentState() {
+    const persisted = this.readPersistedConsentSync(this.storage);
+    if (persisted === true) {
+      return "granted";
+    }
+    if (persisted === false) {
+      return "denied";
+    }
+    return this.consentGranted ? "granted" : "unknown";
   }
   /**
    * Sets or updates shared event context fields (useful for mobile device/app metadata).
@@ -677,22 +722,25 @@ var AnalyticsClient = class {
    * Anonymous history remains linked by anonId/sessionId.
    */
   identify(userId, traits) {
-    if (!this.consentGranted) {
-      return;
-    }
     const normalizedUserId = this.readRequiredStringOption(userId);
     if (!normalizedUserId) {
-      this.log("Dropping identify call without required `userId`");
       return;
     }
+    if (!this.isFullTrackingActive()) {
+      this.log("Ignoring identify() because identity persistence is not enabled");
+      return;
+    }
+    this.userId = normalizedUserId;
+    if (!this.consentGranted) {
+      return;
+    }
+    const normalizedTraits = this.cloneProperties(traits);
     if (this.shouldDeferEventsUntilHydrated()) {
-      const deferredTraits = this.cloneProperties(traits);
       this.deferEventUntilHydrated(() => {
-        this.identify(normalizedUserId, deferredTraits);
+        this.identify(normalizedUserId, normalizedTraits);
       });
       return;
     }
-    this.userId = normalizedUserId;
     const sessionId = this.getSessionId();
     this.enqueue({
       eventId: randomId(),
@@ -701,8 +749,9 @@ var AnalyticsClient = class {
       sessionId,
       anonId: this.anonId,
       userId: normalizedUserId,
-      properties: this.withRuntimeMetadata(traits, sessionId),
+      properties: this.withRuntimeMetadata(normalizedTraits, sessionId),
       platform: this.platform,
+      projectSurface: this.projectSurface,
       appVersion: this.appVersion,
       ...this.withEventContext(),
       type: "identify"
@@ -714,13 +763,39 @@ var AnalyticsClient = class {
    * - pass null/undefined/empty string to clear user linkage
    */
   setUser(userId, traits) {
-    const normalizedUserId = typeof userId === "string" ? this.readRequiredStringOption(userId) : "";
+    const normalizedUserId = this.readRequiredStringOption(userId);
     if (!normalizedUserId) {
       this.clearUser();
       return;
     }
     this.identify(normalizedUserId, traits);
   }
+  /**
+   * Sets consent specifically for persistent identity tracking.
+   * In `consent_gated` mode this toggles strict-vs-full identity behavior while generic event tracking can stay enabled.
+   */
+  setFullTrackingConsent(granted, options = {}) {
+    if (this.identityTrackingMode === "strict") {
+      return;
+    }
+    if (this.identityTrackingMode === "always_on") {
+      return;
+    }
+    this.fullTrackingConsentGranted = granted;
+    if ((options.persist ?? true) && this.persistConsentState) {
+      this.writePersistedConsent(this.configuredStorage, granted);
+    }
+    this.applyIdentityTrackingState();
+  }
+  optInFullTracking(options) {
+    this.setFullTrackingConsent(true, options);
+  }
+  optOutFullTracking(options) {
+    this.setFullTrackingConsent(false, options);
+  }
+  isFullTrackingEnabled() {
+    return this.isFullTrackingActive();
+  }
   /**
    * Clears the current identified user from in-memory SDK state.
    */
@@ -751,9 +826,10 @@ var AnalyticsClient = class {
       ts: nowIso(),
       sessionId,
       anonId: this.anonId,
-      userId: this.userId,
+      userId: this.getEventUserId(),
       properties: this.withRuntimeMetadata(properties, sessionId),
       platform: this.platform,
+      projectSurface: this.projectSurface,
       appVersion: this.appVersion,
       ...this.withEventContext(),
       type: "track"
@@ -850,6 +926,8 @@ var AnalyticsClient = class {
   /**
    * Creates a scoped paywall tracker that applies shared paywall defaults to every journey event.
    * Useful when a flow has a stable `source`, `paywallId`, `offering`, or experiment metadata.
+   * Reuse the returned tracker for that flow context; creating a new tracker per event resets
+   * paywall entry correlation.
    */
   createPaywallTracker(defaults) {
     const { source: rawDefaultSource, ...defaultProperties } = defaults;
@@ -953,9 +1031,10 @@ var AnalyticsClient = class {
       ts: nowIso(),
       sessionId,
       anonId: this.anonId,
-      userId: this.userId,
+      userId: this.getEventUserId(),
       properties: this.withRuntimeMetadata(properties, sessionId),
       platform: this.platform,
+      projectSurface: this.projectSurface,
       appVersion: this.appVersion,
       ...this.withEventContext(),
       type: "screen"
@@ -988,9 +1067,10 @@ var AnalyticsClient = class {
       ts: nowIso(),
       sessionId,
       anonId: this.anonId,
-      userId: this.userId,
+      userId: this.getEventUserId(),
       properties: this.withRuntimeMetadata({ message, rating, ...properties }, sessionId),
       platform: this.platform,
+      projectSurface: this.projectSurface,
       appVersion: this.appVersion,
       ...this.withEventContext(),
       type: "feedback"
@@ -1078,6 +1158,36 @@ var AnalyticsClient = class {
       }
     }
   }
+  parsePersistedConsent(raw) {
+    if (raw === "granted") {
+      return true;
+    }
+    if (raw === "denied") {
+      return false;
+    }
+    return null;
+  }
+  readPersistedConsentSync(storage) {
+    if (!this.persistConsentState) {
+      return null;
+    }
+    if (storage === this.storage && this.storageReadsAreAsync) {
+      return null;
+    }
+    return this.parsePersistedConsent(readStorageSync(storage, this.consentStorageKey));
+  }
+  async readPersistedConsentAsync(storage) {
+    if (!this.persistConsentState) {
+      return null;
+    }
+    return this.parsePersistedConsent(await readStorageAsync(storage, this.consentStorageKey));
+  }
+  writePersistedConsent(storage, granted) {
+    if (!this.persistConsentState) {
+      return;
+    }
+    writeStorageSync(storage, this.consentStorageKey, granted ? "granted" : "denied");
+  }
   startAutoFlush() {
     if (!this.hasIngestConfig) {
       return;
@@ -1169,10 +1279,11 @@ var AnalyticsClient = class {
       return;
     }
     try {
-      const [storedAnonId, storedSessionId, storedLastSeen] = await Promise.all([
+      const [storedAnonId, storedSessionId, storedLastSeen, storedConsent] = await Promise.all([
         readStorageAsync(this.storage, DEVICE_ID_KEY),
         readStorageAsync(this.storage, SESSION_ID_KEY),
-        readStorageAsync(this.storage, LAST_SEEN_KEY)
+        readStorageAsync(this.storage, LAST_SEEN_KEY),
+        this.readPersistedConsentAsync(this.storage)
       ]);
       if (!this.hasExplicitAnonId && storedAnonId) {
         this.anonId = storedAnonId;
@@ -1184,6 +1295,13 @@ var AnalyticsClient = class {
           this.inMemoryLastSeenMs = Date.now();
         }
       }
+      if (!this.hasExplicitInitialConsent && typeof storedConsent === "boolean") {
+        this.consentGranted = this.hasIngestConfig && storedConsent;
+        if (!this.consentGranted) {
+          this.queue = [];
+          this.deferredEventsBeforeHydration = [];
+        }
+      }
       this.sessionEventSeq = await this.readSessionEventSeqAsync(this.sessionId);
       await this.hydrateOnboardingStepViewState(this.sessionId);
       writeStorageSync(this.storage, DEVICE_ID_KEY, this.anonId);
@@ -1352,6 +1470,81 @@ var AnalyticsClient = class {
       return null;
     }
   }
+  resolveIdentityTrackingModeOption(options) {
+    const explicitMode = this.readRequiredStringOption(options.identityTrackingMode).toLowerCase();
+    if (explicitMode === "strict") {
+      return "strict";
+    }
+    if (explicitMode === "consent_gated") {
+      return "consent_gated";
+    }
+    if (explicitMode === "always_on") {
+      return "always_on";
+    }
+    if (options.enableFullTrackingWithoutConsent === true) {
+      return "always_on";
+    }
+    return "consent_gated";
+  }
+  resolveConfiguredStorage(options) {
+    if (this.identityTrackingMode === "strict") {
+      if (options.storage || options.useCookieStorage || options.cookieDomain) {
+        this.log("Ignoring storage/cookie configuration because identityTrackingMode=strict");
+      }
+      return null;
+    }
+    const customStorage = options.storage ?? null;
+    const browserStorage = resolveBrowserStorageAdapter();
+    const primaryStorage = customStorage ?? browserStorage;
+    const cookieStorage = resolveCookieStorageAdapter(
+      options.useCookieStorage === true,
+      this.readRequiredStringOption(options.cookieDomain) || void 0,
+      this.normalizeCookieMaxAgeSeconds(options.cookieMaxAgeSeconds)
+    );
+    if (primaryStorage && cookieStorage) {
+      return combineStorageAdapters(primaryStorage, cookieStorage);
+    }
+    return primaryStorage ?? cookieStorage;
+  }
+  normalizeCookieMaxAgeSeconds(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+      return DEFAULT_COOKIE_MAX_AGE_SECONDS;
+    }
+    return Math.floor(value);
+  }
+  isFullTrackingActive() {
+    if (!this.hasIngestConfig) {
+      return false;
+    }
+    if (this.identityTrackingMode === "always_on") {
+      return true;
+    }
+    if (this.identityTrackingMode === "strict") {
+      return false;
+    }
+    return this.fullTrackingConsentGranted;
+  }
+  applyIdentityTrackingState() {
+    if (!this.isFullTrackingActive()) {
+      this.storage = null;
+      this.storageReadsAreAsync = false;
+      this.userId = null;
+      return;
+    }
+    this.storage = this.configuredStorage;
+    this.storageReadsAreAsync = this.detectAsyncStorageReads();
+    this.sessionId = this.ensureSessionId();
+    this.sessionEventSeq = this.readSessionEventSeq(this.sessionId);
+    writeStorageSync(this.storage, DEVICE_ID_KEY, this.anonId);
+    writeStorageSync(this.storage, SESSION_ID_KEY, this.sessionId);
+    writeStorageSync(this.storage, LAST_SEEN_KEY, String(this.inMemoryLastSeenMs));
+  }
+  getEventUserId() {
+    if (!this.isFullTrackingActive()) {
+      return null;
+    }
+    return this.userId;
+  }
   withEventContext() {
     return {
       appBuild: this.context.appBuild,
@@ -1387,6 +1580,16 @@ var AnalyticsClient = class {
     }
     return void 0;
   }
+  normalizeProjectSurfaceOption(value) {
+    const normalized = this.readRequiredStringOption(value).toLowerCase();
+    if (!normalized) {
+      return void 0;
+    }
+    if (normalized.length > 64) {
+      return normalized.slice(0, 64);
+    }
+    return normalized;
+  }
   log(message, data) {
     if (!this.debug) {
       return;
@@ -1395,17 +1598,17 @@ var AnalyticsClient = class {
   }
   reportMissingApiKey() {
     console.error(
-      "[analyticscli-sdk] Missing required `apiKey`. Tracking is disabled (safe no-op). Pass your long write key."
+      "[analyticscli-sdk] Missing required `apiKey`. Tracking is disabled (safe no-op). Pass your publishable API key."
     );
   }
 };
 
 // src/bootstrap.ts
 var DEFAULT_API_KEY_ENV_KEYS = [
-  "ANALYTICSCLI_WRITE_KEY",
-  "NEXT_PUBLIC_ANALYTICSCLI_WRITE_KEY",
-  "EXPO_PUBLIC_ANALYTICSCLI_WRITE_KEY",
-  "VITE_ANALYTICSCLI_WRITE_KEY"
+  "ANALYTICSCLI_PUBLISHABLE_API_KEY",
+  "NEXT_PUBLIC_ANALYTICSCLI_PUBLISHABLE_API_KEY",
+  "EXPO_PUBLIC_ANALYTICSCLI_PUBLISHABLE_API_KEY",
+  "VITE_ANALYTICSCLI_PUBLISHABLE_API_KEY"
 ];
 var readTrimmedString2 = (value) => {
   if (typeof value === "string") {
@@ -1472,26 +1675,41 @@ var normalizeInitInput = (input) => {
   if (typeof input === "string") {
     return { apiKey: input };
   }
+  if (input === null || input === void 0) {
+    return {};
+  }
   return input;
 };
 var init = (input = {}) => {
   return new AnalyticsClient(normalizeInitInput(input));
 };
+var initConsentFirst = (input = {}) => {
+  const normalized = normalizeInitInput(input);
+  return new AnalyticsClient({
+    ...normalized,
+    initialConsentGranted: false
+  });
+};
 var initAsync = async (input = {}) => {
   const client = new AnalyticsClient(normalizeInitInput(input));
   await client.ready();
   return client;
 };
+var initConsentFirstAsync = async (input = {}) => {
+  const client = initConsentFirst(input);
+  await client.ready();
+  return client;
+};
 var BROWSER_API_KEY_ENV_KEYS = [
-  "ANALYTICSCLI_WRITE_KEY",
-  "NEXT_PUBLIC_ANALYTICSCLI_WRITE_KEY",
-  "PUBLIC_ANALYTICSCLI_WRITE_KEY",
-  "VITE_ANALYTICSCLI_WRITE_KEY",
-  "EXPO_PUBLIC_ANALYTICSCLI_WRITE_KEY"
+  "ANALYTICSCLI_PUBLISHABLE_API_KEY",
+  "NEXT_PUBLIC_ANALYTICSCLI_PUBLISHABLE_API_KEY",
+  "PUBLIC_ANALYTICSCLI_PUBLISHABLE_API_KEY",
+  "VITE_ANALYTICSCLI_PUBLISHABLE_API_KEY",
+  "EXPO_PUBLIC_ANALYTICSCLI_PUBLISHABLE_API_KEY"
 ];
 var REACT_NATIVE_API_KEY_ENV_KEYS = [
-  "ANALYTICSCLI_WRITE_KEY",
-  "EXPO_PUBLIC_ANALYTICSCLI_WRITE_KEY"
+  "ANALYTICSCLI_PUBLISHABLE_API_KEY",
+  "EXPO_PUBLIC_ANALYTICSCLI_PUBLISHABLE_API_KEY"
 ];
 var initBrowserFromEnv = (options = {}) => {
   const { apiKeyEnvKeys, ...rest } = options;
@@ -1526,6 +1744,8 @@ var initReactNativeFromEnv = (options = {}) => {
   init,
   initAsync,
   initBrowserFromEnv,
+  initConsentFirst,
+  initConsentFirstAsync,
   initFromEnv,
   initReactNativeFromEnv
 });