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

package/dist/index.d.cts

@@ -34,30 +34,24 @@ declare const PURCHASE_SUCCESS_EVENT_CANDIDATES: readonly ["purchase:success"];
  * Arbitrary key/value payload sent with an event.
  */
 type EventProperties = Record<string, unknown>;
+type StorageGetItemCallback = (error?: Error | null, value?: string | null) => void;
+type StorageMutationCallback = (error?: Error | null) => void;
 type AnalyticsStorageAdapter = {
     /**
      * Storage APIs can be sync or async.
-     * This allows plugging in AsyncStorage (React Native), MMKV wrappers, or custom secure stores.
+     * This allows passing AsyncStorage/localStorage directly, or custom adapters.
      */
-    getItem: (key: string) => string | null | Promise<string | null>;
-    setItem: (key: string, value: string) => void | Promise<void>;
-    removeItem?: (key: string) => void | Promise<void>;
+    getItem: (key: string, callback?: StorageGetItemCallback) => string | null | Promise<string | null>;
+    setItem: (key: string, value: string, callback?: StorageMutationCallback) => void | Promise<void>;
+    removeItem?: (key: string, callback?: StorageMutationCallback) => void | Promise<void>;
 };
 type EventContext = {
     appBuild?: string;
     osName?: string;
     osVersion?: string;
-    deviceModel?: string;
-    deviceManufacturer?: string;
-    deviceType?: string;
-    locale?: string;
     country?: string;
     region?: string;
     city?: string;
-    timezone?: string;
-    networkType?: string;
-    carrier?: string;
-    installSource?: string;
 };
 type OnboardingEventProperties = EventProperties & {
     isNewUser?: boolean;
@@ -134,88 +128,115 @@ type PaywallTracker = {
     purchaseFailed: (properties?: PaywallTrackerProperties) => void;
     purchaseCancel: (properties?: PaywallTrackerProperties) => void;
 };
+type AnalyticsConsentState = 'granted' | 'denied' | 'unknown';
+type IdentityTrackingMode = 'strict' | 'consent_gated' | 'always_on';
+type SetConsentOptions = {
+    /**
+     * Whether consent state should be persisted to storage when enabled.
+     */
+    persist?: boolean;
+};
 type AnalyticsClientOptions = {
     /**
-     * Write key (long API key).
+     * Publishable ingest API key.
      * If omitted, the client becomes a safe no-op until a valid key is provided.
      */
-    apiKey?: string;
+    apiKey?: string | null;
     /**
      * Optional collector override reserved for SDK/internal testing.
      * Host app integrations should not set this option.
      */
-    endpoint?: string;
-    batchSize?: number;
-    flushIntervalMs?: number;
-    maxRetries?: number;
+    endpoint?: string | null;
+    batchSize?: number | null;
+    flushIntervalMs?: number | null;
+    maxRetries?: number | null;
     /**
      * Enables SDK debug logs (`console.debug`).
      * Defaults to `false`.
      *
      * React Native/Expo recommendation:
-     * `debug: typeof __DEV__ === 'boolean' ? __DEV__ : false`
+     * `debug: __DEV__`
      */
-    debug?: boolean;
-    platform?: string;
-    appVersion?: string;
-    context?: EventContext;
+    debug?: boolean | null;
     /**
-     * Optional custom persistence adapter.
-     * If omitted, browser storage/cookies are used when available; otherwise in-memory IDs are used.
+     * Optional platform hint.
+     * React Native/Expo: passing `Platform.OS` directly is supported.
      */
-    storage?: AnalyticsStorageAdapter;
-    anonId?: string;
-    sessionId?: string;
-    sessionTimeoutMs?: number;
+    platform?: string | null;
     /**
-     * Drops duplicate `onboarding:step_view` events for the same step within one session.
-     * This only affects the dedicated onboarding step-view event, not `screen(...)` or paywall events.
+     * Optional app version hint.
+     * Accepts nullable runtime values (for example Expo's `nativeApplicationVersion`).
      */
-    dedupeOnboardingStepViewsPerSession?: boolean;
+    appVersion?: string | null;
     /**
-     * Optional cookie domain to persist device/session ids across subdomains.
-     * Example: `.analyticscli.com`
+     * Optional project surface hint to separate product surfaces/channels
+     * (for example `landing`, `dashboard`, `app`) from runtime `platform`.
      */
-    cookieDomain?: string;
-    cookieMaxAgeSeconds?: number;
+    projectSurface?: string | null;
     /**
-     * Enables cookie-backed id/session persistence.
-     * Defaults to true when `cookieDomain` is provided, otherwise false.
+     * Initial event-collection consent state.
+     * Defaults to `true` when `apiKey` is present.
+     * Set to `false` to enforce explicit `optIn()` / `setConsent(true)` before event collection.
      */
-    useCookieStorage?: boolean;
-};
-type InitOptions = AnalyticsClientOptions;
-type InitFromEnvMissingConfigMode = 'noop' | 'throw';
-type InitFromEnvMissingConfig = {
-    missingApiKey: boolean;
-    searchedApiKeyEnvKeys: string[];
-};
-type InitFromEnvOptions = Omit<AnalyticsClientOptions, 'apiKey'> & {
+    initialConsentGranted?: boolean | null;
+    /**
+     * Controls identity persistence behavior.
+     * - `consent_gated` (default): starts in strict mode and enables persistence only after consent
+     * - `always_on`: enables persistence immediately
+     * - `strict`: disables persistence and identity linkage
+     */
+    identityTrackingMode?: IdentityTrackingMode | null;
     /**
-     * Optional environment-like object.
-     * Defaults to `globalThis.process?.env` when available.
+     * Boolean shortcut for `identityTrackingMode: 'always_on'`.
+     * Kept for host-app ergonomics.
      */
-    env?: Record<string, unknown>;
+    enableFullTrackingWithoutConsent?: boolean | null;
     /**
-     * Explicit api key override.
+     * Initial consent state for identity persistence when `identityTrackingMode='consent_gated'`.
+     * Defaults to `false`.
+     */
+    initialFullTrackingConsentGranted?: boolean | null;
+    /**
+     * Persist full-tracking consent in configured storage.
      */
-    apiKey?: string;
+    persistConsentState?: boolean | null;
     /**
-     * Candidate env keys resolved in order.
+     * Storage key for persisted full-tracking consent state.
+     * Defaults to `analyticscli:consent:v1`.
      */
-    apiKeyEnvKeys?: string[];
+    consentStorageKey?: string | null;
+    context?: EventContext | null;
     /**
-     * How missing config is handled.
-     * - `noop` (default): returns a safe no-op client
-     * - `throw`: throws when required config is missing
+     * Optional custom persistence adapter used when identity persistence is active.
+     */
+    storage?: AnalyticsStorageAdapter | null;
+    /**
+     * Optional explicit anonymous device id when identity persistence is active.
+     */
+    anonId?: string | null;
+    /**
+     * Optional explicit session id when identity persistence is active.
+     */
+    sessionId?: string | null;
+    sessionTimeoutMs?: number | null;
+    /**
+     * Drops duplicate `onboarding:step_view` events for the same step within one session.
+     * This only affects the dedicated onboarding step-view event, not `screen(...)` or paywall events.
+     * Defaults to `true`. Set to `false` to disable this behavior.
      */
-    missingConfigMode?: InitFromEnvMissingConfigMode;
+    dedupeOnboardingStepViewsPerSession?: boolean | null;
     /**
-     * Optional callback for custom logging when config is missing.
+     * Cookie domain for optional cookie-backed persistence.
      */
-    onMissingConfig?: (details: InitFromEnvMissingConfig) => void;
+    cookieDomain?: string | null;
+    cookieMaxAgeSeconds?: number | null;
+    /**
+     * Enables cookie-backed persistence in browsers.
+     */
+    useCookieStorage?: boolean | null;
 };
-type InitInput = InitOptions | string;
+type InitOptions = AnalyticsClientOptions;
+type InitInput = InitOptions | string | null | undefined;
 
 declare class AnalyticsClient {
     private readonly apiKey;
@@ -226,10 +247,17 @@ declare class AnalyticsClient {
     private readonly maxRetries;
     private readonly debug;
     private readonly platform;
+    private readonly projectSurface;
     private readonly appVersion;
+    private readonly identityTrackingMode;
     private context;
-    private readonly storage;
-    private readonly storageReadsAreAsync;
+    private readonly configuredStorage;
+    private storage;
+    private storageReadsAreAsync;
+    private readonly persistConsentState;
+    private readonly consentStorageKey;
+    private readonly hasExplicitInitialConsent;
+    private readonly hasExplicitInitialFullTrackingConsent;
     private readonly sessionTimeoutMs;
     private readonly dedupeOnboardingStepViewsPerSession;
     private readonly runtimeEnv;
@@ -240,6 +268,7 @@ declare class AnalyticsClient {
     private flushTimer;
     private isFlushing;
     private consentGranted;
+    private fullTrackingConsentGranted;
     private userId;
     private anonId;
     private sessionId;
@@ -251,17 +280,18 @@ declare class AnalyticsClient {
     private onboardingStepViewsSeen;
     constructor(options: AnalyticsClientOptions);
     /**
-     * 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.
      */
     ready(): Promise<void>;
     /**
      * Enables or disables event collection.
      * When disabled, queued events are dropped immediately.
      */
-    setConsent(granted: boolean): void;
-    optIn(): void;
-    optOut(): void;
+    setConsent(granted: boolean, options?: SetConsentOptions): void;
+    optIn(options?: SetConsentOptions): void;
+    optOut(options?: SetConsentOptions): void;
+    getConsent(): boolean;
+    getConsentState(): AnalyticsConsentState;
     /**
      * Sets or updates shared event context fields (useful for mobile device/app metadata).
      */
@@ -277,6 +307,14 @@ declare class AnalyticsClient {
      * - pass null/undefined/empty string to clear user linkage
      */
     setUser(userId: string | null | undefined, traits?: EventProperties): void;
+    /**
+     * 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: boolean, options?: SetConsentOptions): void;
+    optInFullTracking(options?: SetConsentOptions): void;
+    optOutFullTracking(options?: SetConsentOptions): void;
+    isFullTrackingEnabled(): boolean;
     /**
      * Clears the current identified user from in-memory SDK state.
      */
@@ -297,6 +335,8 @@ declare class AnalyticsClient {
     /**
      * 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: PaywallTrackerDefaults): PaywallTracker;
     /**
@@ -333,6 +373,10 @@ declare class AnalyticsClient {
     private enqueue;
     private scheduleFlush;
     private sendWithRetry;
+    private parsePersistedConsent;
+    private readPersistedConsentSync;
+    private readPersistedConsentAsync;
+    private writePersistedConsent;
     private startAutoFlush;
     private ensureDeviceId;
     private ensureSessionId;
@@ -356,47 +400,93 @@ declare class AnalyticsClient {
     private hydrateOnboardingStepViewState;
     private persistOnboardingStepViewState;
     private parseOnboardingStepViewState;
+    private resolveIdentityTrackingModeOption;
+    private resolveConfiguredStorage;
+    private normalizeCookieMaxAgeSeconds;
+    private isFullTrackingActive;
+    private applyIdentityTrackingState;
+    private getEventUserId;
     private withEventContext;
     private normalizeOptions;
     private readRequiredStringOption;
     private normalizePlatformOption;
+    private normalizeProjectSurfaceOption;
     private log;
     private reportMissingApiKey;
 }
 
-declare const DEFAULT_API_KEY_ENV_KEYS: readonly ["ANALYTICSCLI_WRITE_KEY", "NEXT_PUBLIC_ANALYTICSCLI_WRITE_KEY", "EXPO_PUBLIC_ANALYTICSCLI_WRITE_KEY", "VITE_ANALYTICSCLI_WRITE_KEY"];
+type ContextClientInput = InitInput | AnalyticsClient | null | undefined;
+type AnalyticsContextConsentControls = {
+    get: () => boolean;
+    getState: () => AnalyticsConsentState;
+    set: (granted: boolean, options?: SetConsentOptions) => void;
+    optIn: (options?: SetConsentOptions) => void;
+    optOut: (options?: SetConsentOptions) => void;
+    setFullTracking: (granted: boolean, options?: SetConsentOptions) => void;
+    optInFullTracking: (options?: SetConsentOptions) => void;
+    optOutFullTracking: (options?: SetConsentOptions) => void;
+    isFullTrackingEnabled: () => boolean;
+};
+type AnalyticsContextUserControls = {
+    identify: (userId: string, traits?: EventProperties) => void;
+    set: (userId: string | null | undefined, traits?: EventProperties) => void;
+    clear: () => void;
+};
+type AnalyticsContext = {
+    client: AnalyticsClient;
+    onboarding: OnboardingTracker;
+    paywall: PaywallTracker | null;
+    consent: AnalyticsContextConsentControls;
+    user: AnalyticsContextUserControls;
+    track: (eventName: string, properties?: EventProperties) => void;
+    trackOnboardingEvent: (eventName: OnboardingEventName, properties?: OnboardingEventProperties) => void;
+    trackOnboardingSurveyResponse: (input: OnboardingSurveyResponseInput, eventName?: OnboardingSurveyEventName) => void;
+    trackPaywallEvent: (eventName: PaywallJourneyEventName, properties: PaywallEventProperties) => void;
+    screen: (name: string, properties?: EventProperties) => void;
+    page: (name: string, properties?: EventProperties) => void;
+    feedback: (message: string, rating?: number, properties?: EventProperties) => void;
+    setContext: (context: EventContext) => void;
+    createOnboarding: (defaults: OnboardingTrackerDefaults) => OnboardingTracker;
+    createPaywall: (defaults: PaywallTrackerDefaults) => PaywallTracker;
+    configureOnboarding: (defaults: OnboardingTrackerDefaults) => OnboardingTracker;
+    configurePaywall: (defaults: PaywallTrackerDefaults) => PaywallTracker;
+    ready: () => Promise<void>;
+    flush: () => Promise<void>;
+    shutdown: () => void;
+};
+type CreateAnalyticsContextOptions = {
+    /**
+     * Either an existing client instance or standard `init(...)` input.
+     */
+    client?: ContextClientInput;
+    /**
+     * Defaults used for the exported `context.onboarding` tracker instance.
+     */
+    onboarding?: OnboardingTrackerDefaults | null;
+    /**
+     * Optional defaults used for the exported `context.paywall` tracker instance.
+     */
+    paywall?: PaywallTrackerDefaults | null;
+};
 /**
- * Minimal host-app bootstrap helper.
- * Resolves `apiKey` (required) from explicit options or env-like objects.
+ * Host-app friendly SDK context with low boilerplate and rich defaults.
+ * Provides pre-wired onboarding + consent/user controls and optional paywall tracker binding.
  */
-declare const initFromEnv: (options?: InitFromEnvOptions) => AnalyticsClient;
+declare const createAnalyticsContext: (options?: CreateAnalyticsContextOptions) => AnalyticsContext;
 
 /**
  * Creates a browser analytics client instance.
  */
 declare const init: (input?: InitInput) => AnalyticsClient;
 /**
- * Creates an analytics client and waits for async storage hydration.
- * Prefer this in React Native when using async persistence (for example AsyncStorage).
- */
-declare const initAsync: (input?: InitInput) => Promise<AnalyticsClient>;
-declare const BROWSER_API_KEY_ENV_KEYS: readonly ["ANALYTICSCLI_WRITE_KEY", "NEXT_PUBLIC_ANALYTICSCLI_WRITE_KEY", "PUBLIC_ANALYTICSCLI_WRITE_KEY", "VITE_ANALYTICSCLI_WRITE_KEY", "EXPO_PUBLIC_ANALYTICSCLI_WRITE_KEY"];
-declare const REACT_NATIVE_API_KEY_ENV_KEYS: readonly ["ANALYTICSCLI_WRITE_KEY", "EXPO_PUBLIC_ANALYTICSCLI_WRITE_KEY"];
-type BrowserInitFromEnvOptions = Omit<InitFromEnvOptions, 'apiKeyEnvKeys'> & {
-    apiKeyEnvKeys?: readonly string[];
-};
-type ReactNativeInitFromEnvOptions = Omit<InitFromEnvOptions, 'apiKeyEnvKeys'> & {
-    apiKeyEnvKeys?: readonly string[];
-};
-/**
- * Browser-focused env bootstrap.
- * Supports common env prefixes across Next.js, Astro/Vite and Expo web.
+ * Creates an analytics client with consent-first defaults.
+ * Tracking stays disabled until `optIn()` / `setConsent(true)` is called.
  */
-declare const initBrowserFromEnv: (options?: BrowserInitFromEnvOptions) => AnalyticsClient;
+declare const initConsentFirst: (input?: InitInput) => AnalyticsClient;
 /**
- * React Native-focused env bootstrap.
- * Defaults to native-friendly env keys while still allowing explicit overrides.
+ * Creates an analytics client and resolves once client initialization completes.
  */
-declare const initReactNativeFromEnv: (options?: ReactNativeInitFromEnvOptions) => AnalyticsClient;
+declare const initAsync: (input?: InitInput) => Promise<AnalyticsClient>;
+declare const initConsentFirstAsync: (input?: InitInput) => Promise<AnalyticsClient>;
 
-export { AnalyticsClient, type AnalyticsClientOptions, type AnalyticsStorageAdapter, BROWSER_API_KEY_ENV_KEYS, type BrowserInitFromEnvOptions, DEFAULT_API_KEY_ENV_KEYS, type EventContext, type EventProperties, type InitFromEnvMissingConfig, type InitFromEnvMissingConfigMode, type InitFromEnvOptions, 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, REACT_NATIVE_API_KEY_ENV_KEYS, type ReactNativeInitFromEnvOptions, init, initAsync, initBrowserFromEnv, initFromEnv, initReactNativeFromEnv };
+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 };