@analyticscli/sdk 0.1.0-preview.4

package/dist/index.d.ts

@@ -0,0 +1,402 @@
+declare const ONBOARDING_EVENTS: {
+    readonly START: "onboarding:start";
+    readonly STEP_VIEW: "onboarding:step_view";
+    readonly STEP_COMPLETE: "onboarding:step_complete";
+    readonly COMPLETE: "onboarding:complete";
+    readonly SKIP: "onboarding:skip";
+};
+type OnboardingEventName = (typeof ONBOARDING_EVENTS)[keyof typeof ONBOARDING_EVENTS];
+declare const PAYWALL_EVENTS: {
+    readonly SHOWN: "paywall:shown";
+    readonly SKIP: "paywall:skip";
+};
+type PaywallEventName = (typeof PAYWALL_EVENTS)[keyof typeof PAYWALL_EVENTS];
+declare const PURCHASE_EVENTS: {
+    readonly STARTED: "purchase:started";
+    readonly SUCCESS: "purchase:success";
+    readonly FAILED: "purchase:failed";
+    readonly CANCEL: "purchase:cancel";
+};
+type PurchaseEventName = (typeof PURCHASE_EVENTS)[keyof typeof PURCHASE_EVENTS];
+type PaywallJourneyEventName = PaywallEventName | PurchaseEventName;
+declare const ONBOARDING_SURVEY_EVENTS: {
+    readonly RESPONSE: "onboarding:survey_response";
+};
+type OnboardingSurveyEventName = (typeof ONBOARDING_SURVEY_EVENTS)[keyof typeof ONBOARDING_SURVEY_EVENTS];
+declare const ONBOARDING_PROGRESS_EVENT_ORDER: readonly ["onboarding:complete", "onboarding:skip"];
+declare const PAYWALL_JOURNEY_EVENT_ORDER: readonly ["paywall:shown", "paywall:skip", "purchase:success", "purchase:failed"];
+declare const ONBOARDING_SCREEN_EVENT_PREFIXES: readonly ["screen:onboarding", "screen:onboarding_"];
+declare const PAYWALL_ANCHOR_EVENT_CANDIDATES: readonly ["paywall:shown"];
+declare const PAYWALL_SKIP_EVENT_CANDIDATES: readonly ["paywall:skip"];
+declare const PURCHASE_SUCCESS_EVENT_CANDIDATES: readonly ["purchase:success"];
+
+/**
+ * Arbitrary key/value payload sent with an event.
+ */
+type EventProperties = Record<string, unknown>;
+type AnalyticsStorageAdapter = {
+    /**
+     * Storage APIs can be sync or async.
+     * This allows plugging in AsyncStorage (React Native), MMKV wrappers, or custom secure stores.
+     */
+    getItem: (key: string) => string | null | Promise<string | null>;
+    setItem: (key: string, value: string) => void | Promise<void>;
+    removeItem?: (key: string) => 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;
+    onboardingFlowId?: string;
+    onboardingFlowVersion?: string | number;
+    onboardingExperimentId?: string;
+    stepKey?: string;
+    stepIndex?: number;
+    stepCount?: number;
+};
+type PaywallEventProperties = EventProperties & {
+    source: string;
+    fromScreen?: string;
+    paywallId?: string;
+    offering?: string;
+    paywallEntryId?: string;
+    packageId?: string;
+    price?: number;
+    currency?: string;
+    experimentVariant?: string;
+    entitlementKey?: string;
+};
+type OnboardingSurveyAnswerType = 'single_choice' | 'multiple_choice' | 'boolean' | 'numeric' | 'text' | 'unknown';
+type OnboardingSurveyResponseInput = {
+    surveyKey: string;
+    questionKey: string;
+    answerType: OnboardingSurveyAnswerType;
+    responseKey?: string;
+    responseKeys?: string[];
+    responseBoolean?: boolean;
+    responseNumber?: number;
+    responseText?: string;
+    appVersion?: string;
+    isNewUser?: boolean;
+    onboardingFlowId?: string;
+    onboardingFlowVersion?: string | number;
+    onboardingExperimentId?: string;
+    stepKey?: string;
+    stepIndex?: number;
+    stepCount?: number;
+    experimentVariant?: string;
+    paywallId?: string;
+    properties?: EventProperties;
+};
+type OnboardingTrackerDefaults = OnboardingEventProperties & {
+    surveyKey?: string;
+};
+type OnboardingTrackerSurveyInput = Omit<OnboardingSurveyResponseInput, 'surveyKey'> & {
+    surveyKey?: string;
+};
+type OnboardingStepTracker = {
+    view: (properties?: Omit<OnboardingEventProperties, 'stepKey' | 'stepIndex'>) => void;
+    complete: (properties?: Omit<OnboardingEventProperties, 'stepKey' | 'stepIndex'>) => void;
+    surveyResponse: (input: Omit<OnboardingTrackerSurveyInput, 'stepKey' | 'stepIndex'>) => void;
+};
+type OnboardingTracker = {
+    track: (eventName: OnboardingEventName, properties?: OnboardingEventProperties) => void;
+    start: (properties?: OnboardingEventProperties) => void;
+    stepView: (properties: OnboardingEventProperties) => void;
+    stepComplete: (properties: OnboardingEventProperties) => void;
+    complete: (properties?: OnboardingEventProperties) => void;
+    skip: (properties?: OnboardingEventProperties) => void;
+    surveyResponse: (input: OnboardingTrackerSurveyInput) => void;
+    step: (stepKey: string, stepIndex: number, properties?: Omit<OnboardingEventProperties, 'stepKey' | 'stepIndex'>) => OnboardingStepTracker;
+};
+type PaywallTrackerDefaults = PaywallEventProperties;
+type PaywallTrackerProperties = Partial<PaywallEventProperties>;
+type PaywallTracker = {
+    track: (eventName: PaywallJourneyEventName, properties?: PaywallTrackerProperties) => void;
+    shown: (properties?: PaywallTrackerProperties) => void;
+    skip: (properties?: PaywallTrackerProperties) => void;
+    purchaseStarted: (properties?: PaywallTrackerProperties) => void;
+    purchaseSuccess: (properties?: PaywallTrackerProperties) => void;
+    purchaseFailed: (properties?: PaywallTrackerProperties) => void;
+    purchaseCancel: (properties?: PaywallTrackerProperties) => void;
+};
+type AnalyticsClientOptions = {
+    /**
+     * Write key (long API key).
+     * If omitted, the client becomes a safe no-op until a valid key is provided.
+     */
+    apiKey?: string;
+    /**
+     * Optional collector override reserved for SDK/internal testing.
+     * Host app integrations should not set this option.
+     */
+    endpoint?: string;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    maxRetries?: number;
+    /**
+     * Enables SDK debug logs (`console.debug`).
+     * Defaults to `false`.
+     *
+     * React Native/Expo recommendation:
+     * `debug: typeof __DEV__ === 'boolean' ? __DEV__ : false`
+     */
+    debug?: boolean;
+    platform?: string;
+    appVersion?: string;
+    context?: EventContext;
+    /**
+     * Optional custom persistence adapter.
+     * If omitted, browser storage/cookies are used when available; otherwise in-memory IDs are used.
+     */
+    storage?: AnalyticsStorageAdapter;
+    anonId?: string;
+    sessionId?: string;
+    sessionTimeoutMs?: number;
+    /**
+     * 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.
+     */
+    dedupeOnboardingStepViewsPerSession?: boolean;
+    /**
+     * Optional cookie domain to persist device/session ids across subdomains.
+     * Example: `.analyticscli.com`
+     */
+    cookieDomain?: string;
+    cookieMaxAgeSeconds?: number;
+    /**
+     * Enables cookie-backed id/session persistence.
+     * Defaults to true when `cookieDomain` is provided, otherwise false.
+     */
+    useCookieStorage?: boolean;
+};
+type InitOptions = AnalyticsClientOptions;
+type InitFromEnvMissingConfigMode = 'noop' | 'throw';
+type InitFromEnvMissingConfig = {
+    missingApiKey: boolean;
+    searchedApiKeyEnvKeys: string[];
+};
+type InitFromEnvOptions = Omit<AnalyticsClientOptions, 'apiKey'> & {
+    /**
+     * Optional environment-like object.
+     * Defaults to `globalThis.process?.env` when available.
+     */
+    env?: Record<string, unknown>;
+    /**
+     * Explicit api key override.
+     */
+    apiKey?: string;
+    /**
+     * Candidate env keys resolved in order.
+     */
+    apiKeyEnvKeys?: string[];
+    /**
+     * How missing config is handled.
+     * - `noop` (default): returns a safe no-op client
+     * - `throw`: throws when required config is missing
+     */
+    missingConfigMode?: InitFromEnvMissingConfigMode;
+    /**
+     * Optional callback for custom logging when config is missing.
+     */
+    onMissingConfig?: (details: InitFromEnvMissingConfig) => void;
+};
+type InitInput = InitOptions | string;
+
+declare class AnalyticsClient {
+    private readonly apiKey;
+    private readonly hasIngestConfig;
+    private readonly endpoint;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private readonly maxRetries;
+    private readonly debug;
+    private readonly platform;
+    private readonly appVersion;
+    private context;
+    private readonly storage;
+    private readonly storageReadsAreAsync;
+    private readonly sessionTimeoutMs;
+    private readonly dedupeOnboardingStepViewsPerSession;
+    private readonly runtimeEnv;
+    private readonly hasExplicitAnonId;
+    private readonly hasExplicitSessionId;
+    private readonly hydrationPromise;
+    private queue;
+    private flushTimer;
+    private isFlushing;
+    private consentGranted;
+    private userId;
+    private anonId;
+    private sessionId;
+    private sessionEventSeq;
+    private inMemoryLastSeenMs;
+    private hydrationCompleted;
+    private deferredEventsBeforeHydration;
+    private onboardingStepViewStateSessionId;
+    private onboardingStepViewsSeen;
+    constructor(options: AnalyticsClientOptions);
+    /**
+     * Resolves once any async storage adapter hydration completes.
+     * Useful in React Native when using async persistence (for example AsyncStorage).
+     */
+    ready(): Promise<void>;
+    /**
+     * Enables or disables event collection.
+     * When disabled, queued events are dropped immediately.
+     */
+    setConsent(granted: boolean): void;
+    optIn(): void;
+    optOut(): void;
+    /**
+     * Sets or updates shared event context fields (useful for mobile device/app metadata).
+     */
+    setContext(context: EventContext): void;
+    /**
+     * Associates following events with a known user id.
+     * Anonymous history remains linked by anonId/sessionId.
+     */
+    identify(userId: string, traits?: EventProperties): void;
+    /**
+     * Convenience helper for login/logout boundaries.
+     * - pass a non-empty user id to emit an identify event
+     * - pass null/undefined/empty string to clear user linkage
+     */
+    setUser(userId: string | null | undefined, traits?: EventProperties): void;
+    /**
+     * Clears the current identified user from in-memory SDK state.
+     */
+    clearUser(): void;
+    /**
+     * Sends a generic product event.
+     */
+    track(eventName: string, properties?: EventProperties): void;
+    /**
+     * Sends a typed onboarding event with conventional onboarding metadata.
+     */
+    trackOnboardingEvent(eventName: OnboardingEventName, properties?: OnboardingEventProperties): void;
+    /**
+     * Creates a scoped onboarding tracker that applies shared flow properties to every onboarding event.
+     * This reduces app-side boilerplate while keeping each emitted event fully self-describing.
+     */
+    createOnboardingTracker(defaults: OnboardingTrackerDefaults): OnboardingTracker;
+    /**
+     * 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.
+     */
+    createPaywallTracker(defaults: PaywallTrackerDefaults): PaywallTracker;
+    /**
+     * Sends a typed paywall/purchase journey event.
+     * Direct calls ignore `paywallEntryId`; use `createPaywallTracker(...)` for entry correlation.
+     */
+    trackPaywallEvent(eventName: PaywallJourneyEventName, properties: PaywallEventProperties): void;
+    private sendPaywallEvent;
+    /**
+     * Sends anonymized onboarding survey responses using canonical event naming.
+     * Free text and raw numeric values are reduced to coarse buckets.
+     */
+    trackOnboardingSurveyResponse(input: OnboardingSurveyResponseInput, eventName?: OnboardingSurveyEventName): void;
+    /**
+     * Sends a screen-view style event using the `screen:<name>` convention.
+     */
+    screen(name: string, properties?: EventProperties): void;
+    /**
+     * Alias of `screen(...)` for web-style naming.
+     */
+    page(name: string, properties?: EventProperties): void;
+    /**
+     * Sends a feedback event.
+     */
+    feedback(message: string, rating?: number, properties?: EventProperties): void;
+    /**
+     * Flushes current event queue to the ingest endpoint.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stops internal timers and unload handlers.
+     */
+    shutdown(): void;
+    private enqueue;
+    private scheduleFlush;
+    private sendWithRetry;
+    private startAutoFlush;
+    private ensureDeviceId;
+    private ensureSessionId;
+    private getSessionId;
+    private readSessionEventSeq;
+    private readSessionEventSeqAsync;
+    private parseSessionEventSeq;
+    private writeSessionEventSeq;
+    private hydrateIdentityFromStorage;
+    private shouldDeferEventsUntilHydrated;
+    private deferEventUntilHydrated;
+    private drainDeferredEventsAfterHydration;
+    private cloneProperties;
+    private detectAsyncStorageReads;
+    private withRuntimeMetadata;
+    private shouldDropOnboardingStepView;
+    private getOnboardingStepViewDedupeKey;
+    private readPropertyAsString;
+    private readPropertyAsStepIndex;
+    private syncOnboardingStepViewState;
+    private hydrateOnboardingStepViewState;
+    private persistOnboardingStepViewState;
+    private parseOnboardingStepViewState;
+    private withEventContext;
+    private normalizeOptions;
+    private readRequiredStringOption;
+    private normalizePlatformOption;
+    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"];
+/**
+ * Minimal host-app bootstrap helper.
+ * Resolves `apiKey` (required) from explicit options or env-like objects.
+ */
+declare const initFromEnv: (options?: InitFromEnvOptions) => AnalyticsClient;
+
+/**
+ * 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.
+ */
+declare const initBrowserFromEnv: (options?: BrowserInitFromEnvOptions) => AnalyticsClient;
+/**
+ * React Native-focused env bootstrap.
+ * Defaults to native-friendly env keys while still allowing explicit overrides.
+ */
+declare const initReactNativeFromEnv: (options?: ReactNativeInitFromEnvOptions) => 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 };

package/dist/index.js

@@ -0,0 +1,42 @@
+import {
+  AnalyticsClient,
+  BROWSER_API_KEY_ENV_KEYS,
+  DEFAULT_API_KEY_ENV_KEYS,
+  ONBOARDING_EVENTS,
+  ONBOARDING_PROGRESS_EVENT_ORDER,
+  ONBOARDING_SCREEN_EVENT_PREFIXES,
+  ONBOARDING_SURVEY_EVENTS,
+  PAYWALL_ANCHOR_EVENT_CANDIDATES,
+  PAYWALL_EVENTS,
+  PAYWALL_JOURNEY_EVENT_ORDER,
+  PAYWALL_SKIP_EVENT_CANDIDATES,
+  PURCHASE_EVENTS,
+  PURCHASE_SUCCESS_EVENT_CANDIDATES,
+  REACT_NATIVE_API_KEY_ENV_KEYS,
+  init,
+  initAsync,
+  initBrowserFromEnv,
+  initFromEnv,
+  initReactNativeFromEnv
+} from "./chunk-UILQQPVJ.js";
+export {
+  AnalyticsClient,
+  BROWSER_API_KEY_ENV_KEYS,
+  DEFAULT_API_KEY_ENV_KEYS,
+  ONBOARDING_EVENTS,
+  ONBOARDING_PROGRESS_EVENT_ORDER,
+  ONBOARDING_SCREEN_EVENT_PREFIXES,
+  ONBOARDING_SURVEY_EVENTS,
+  PAYWALL_ANCHOR_EVENT_CANDIDATES,
+  PAYWALL_EVENTS,
+  PAYWALL_JOURNEY_EVENT_ORDER,
+  PAYWALL_SKIP_EVENT_CANDIDATES,
+  PURCHASE_EVENTS,
+  PURCHASE_SUCCESS_EVENT_CANDIDATES,
+  REACT_NATIVE_API_KEY_ENV_KEYS,
+  init,
+  initAsync,
+  initBrowserFromEnv,
+  initFromEnv,
+  initReactNativeFromEnv
+};