@drakkar.software/sunglasses-core 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1093 @@
+/**
+ * Platform-agnostic key-value storage interface.
+ * Implementations: LocalStorageAdapter (web), AsyncStorageAdapter (RN).
+ */
+interface IStorageAdapter {
+    read(key: string): Promise<string | null>;
+    write(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Optional: flush in-flight writes (useful for HTTP-backed stores). */
+    flush?(): Promise<void>;
+}
+/**
+ * Output destination that receives batches of sanitized, consented events.
+ * Implementations: HttpStorageAdapter, StarfishAnalyticsAdapter, console (debug).
+ */
+interface IAnalyticsAdapter {
+    /**
+     * Deliver a batch of events. Must NOT mutate the input array.
+     * The array is `ReadonlyArray` to enforce this at the type level;
+     * at runtime it is also `Object.freeze`'d by `SunglassesCore`.
+     */
+    send(batch: ReadonlyArray<SunglassesEvent>): Promise<void>;
+    /** Called on identity reset — adapter may clear remote session. */
+    reset?(): Promise<void>;
+    /** Called on SDK shutdown — adapter should flush pending work. */
+    shutdown?(): Promise<void>;
+    /**
+     * Called after a successful flush with the events that were delivered.
+     * Use this to archive or remove old events from the remote store.
+     * Implement this in adapters that accumulate data (e.g. StarfishAnalyticsAdapter).
+     */
+    cleanupAfterFlush?(delivered: ReadonlyArray<SunglassesEvent>, config: CleanupConfig): Promise<void>;
+}
+/**
+ * Controls what happens to delivered events in the remote store after a
+ * successful flush. Adapters that support `cleanupAfterFlush` will use this
+ * to decide which events to archive or remove.
+ */
+interface CleanupConfig {
+    /** Remove events older than this many milliseconds. Defaults to 30 days. */
+    maxAgeMs?: number;
+    /**
+     * Keep only the most recent N events per identity.
+     * Applied after `maxAgeMs`. Set to 0 to disable.
+     */
+    maxEventsPerIdentity?: number;
+}
+type MiddlewareNext = (event: SunglassesEvent) => Promise<SunglassesEvent | null>;
+/**
+ * Middleware that can transform or drop events before they are queued.
+ * Return `null` to silently drop the event. Must never throw.
+ */
+interface IMiddleware {
+    name: string;
+    process(event: SunglassesEvent, next: MiddlewareNext): Promise<SunglassesEvent | null>;
+}
+type EventType = 'capture' | 'screen' | 'identify' | 'alias' | 'group';
+interface EventContext {
+    library: {
+        name: string;
+        version: string;
+    };
+    platform: 'web' | 'react-native';
+    app?: {
+        name?: string;
+        version?: string;
+        build?: string;
+    };
+    device?: {
+        type?: string;
+        os?: string;
+    };
+    screen?: {
+        width?: number;
+        height?: number;
+    };
+    locale?: string;
+    /** Current session ID. Present when enableSessionTracking is true. */
+    sessionId?: string;
+    /** Persisted user traits set via identify(). Forwarded to backends for segmentation. */
+    traits?: Record<string, unknown>;
+    /** Group identity set via group(). Enables organization-level segmentation. */
+    group?: {
+        id: string;
+    };
+}
+/**
+ * Canonical event shape sent to IAnalyticsAdapter implementations.
+ */
+interface SunglassesEvent {
+    type: EventType;
+    /** Human-readable event name, e.g. 'Button Clicked', '$screen', '$identify'. */
+    event: string;
+    /** Resolved user ID (hashed if anonymizeUserId=true). Falls back to anonymousId. */
+    distinctId: string;
+    /** Stable device UUID — never contains PII, regenerated only on reset(). */
+    anonymousId: string;
+    /** ISO-8601 UTC timestamp. */
+    timestamp: string;
+    /** UUID v4 per event — used for de-duplication. */
+    messageId: string;
+    properties: Record<string, unknown>;
+    context: EventContext;
+}
+interface IdentityState {
+    anonymousId: string;
+    /** null until identify() is called */
+    distinctId: string | null;
+    isIdentified: boolean;
+}
+type ConsentStatus = 'opted-in' | 'opted-out' | 'unknown';
+/**
+ * A single entry in the consent audit trail.
+ */
+interface ConsentHistoryEntry {
+    status: ConsentStatus;
+    /** Privacy policy version in effect when this change was recorded. */
+    policyVersion?: string;
+    timestamp: string;
+}
+interface ConsentState {
+    status: ConsentStatus;
+    /** ISO-8601 timestamp of last status change, or null on first run. */
+    updatedAt: string | null;
+    /** Policy version when consent was last given/revoked. */
+    policyVersion?: string;
+    /** Audit trail of consent changes. Capped at 10 entries. */
+    history?: ConsentHistoryEntry[];
+}
+interface SunglassesConfig {
+    /** At least one output adapter is required. */
+    adapters: IAnalyticsAdapter[];
+    /** Local persistence adapter (platform-specific). */
+    storage: IStorageAdapter;
+    /**
+     * When false (default), the SDK starts in opted-out state.
+     * The user must explicitly call optIn() before any events are tracked.
+     * Set to true for analytics-first flows where consent is obtained externally.
+     */
+    defaultOptIn?: boolean;
+    /** If set, only these property keys are kept. All others are stripped. */
+    allowedProperties?: string[];
+    /** Property keys that are always stripped (lower precedence than allowedProperties). */
+    deniedProperties?: string[];
+    /**
+     * When true, distinctId is SHA-256 hashed before being included in events.
+     * The raw ID is never stored in the event payload.
+     */
+    anonymizeUserId?: boolean;
+    /**
+     * When true (default), the SDK checks `navigator.globalPrivacyControl` (GPC)
+     * and `navigator.doNotTrack` (DNT) during initialization. If either signal is
+     * detected and the user has not yet made an explicit in-app consent choice,
+     * the SDK automatically calls `optOut()`.
+     *
+     * GPC is legally binding under CPRA (California). DNT is advisory.
+     *
+     * Set to `false` to disable this behavior — for example, if your consent UI
+     * already handles opt-out separately.
+     *
+     * Only applies on the `'web'` platform. No-op on `'react-native'`.
+     */
+    respectDoNotTrack?: boolean;
+    /** Auto-flush interval in ms. Default: 30_000. */
+    flushInterval?: number;
+    /** Max events held in the in-memory + persisted queue. Default: 500. */
+    maxQueueSize?: number;
+    /** Max events per adapter.send() call. Default: 50. */
+    maxBatchSize?: number;
+    platform?: 'web' | 'react-native';
+    appName?: string;
+    appVersion?: string;
+    appBuild?: string;
+    /** Enables verbose console logging. Never enable in production. */
+    debug?: boolean;
+    /** Hard-disables all tracking (e.g. CI environments, test suites). */
+    disabled?: boolean;
+    /** Additional middleware appended after the built-in PiiSanitizer. */
+    middleware?: IMiddleware[];
+    /**
+     * When set, calls `adapter.cleanupAfterFlush()` after every successful flush.
+     * Only adapters that implement `cleanupAfterFlush` will respond.
+     * Useful for pruning old events from Starfish documents or remote stores.
+     */
+    cleanupAfterFlush?: CleanupConfig;
+    /**
+     * When true, event counts are tracked in storage (see EventCounter).
+     * The FrequencyMiddleware must be added to `middleware` to attach counts
+     * to events automatically.
+     */
+    enableEventCounting?: boolean;
+    /**
+     * When true, a session ID is generated and attached to every event's context.
+     * Sessions expire after `sessionIdleTimeoutMs` of inactivity.
+     */
+    enableSessionTracking?: boolean;
+    /** Idle timeout before a new session is started. Default: 1_800_000 (30 min). */
+    sessionIdleTimeoutMs?: number;
+    /**
+     * If provided, the SDK checks whether stored consent was given for this policy
+     * version. If the stored version differs, consent is reset to 'unknown' so the
+     * user is prompted again. Useful when your privacy policy changes.
+     */
+    consentPolicyVersion?: string;
+    /**
+     * If set, consent older than this many milliseconds is automatically reset to
+     * 'unknown', prompting the user to consent again. Useful for regulatory
+     * compliance that requires re-obtaining consent periodically.
+     *
+     * Example: `365 * 24 * 60 * 60 * 1000` re-asks every year.
+     *
+     * The expiry check runs on SDK initialization. It does not override an
+     * explicit in-session `optIn()` or `optOut()` call.
+     */
+    consentExpiryMs?: number;
+    /**
+     * When true, every event that passes the middleware pipeline is also written
+     * to a permanent local archive (`sunglasses:archive` in IStorageAdapter).
+     *
+     * Unlike the EventQueue, the archive is **never cleared automatically** after
+     * a flush — events persist until `client.clearLocalArchive()` is called.
+     *
+     * Use cases:
+     * - Keep a full local history for GDPR data portability
+     * - Re-sync a remote store from scratch after a failure
+     * - Offline-first: accumulate events even if all adapters are down
+     */
+    enableLocalArchive?: boolean;
+}
+/**
+ * The main SDK surface. Implemented by SunglassesCore.
+ * Both @drakkar.software/sunglasses-react and @drakkar.software/sunglasses-react-native expose this via Context.
+ */
+interface ISunglassesClient {
+    /**
+     * Track a custom event. Silently dropped when opted-out or disabled.
+     * @param options - Optional overrides for timestamp and messageId.
+     */
+    capture(eventName: string, properties?: Record<string, unknown>, options?: CaptureOptions): void;
+    /** Track a screen/page view. */
+    screen(screenName: string, properties?: Record<string, unknown>): void;
+    /** Link the current anonymous session to a known user. */
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    /** Create an alias between two identities (e.g. pre/post login merge). */
+    alias(newId: string, existingId: string): void;
+    /**
+     * Associate the current user with a group (e.g. organisation, workspace, team).
+     * Emits a `group` event and attaches the group ID to all subsequent events via
+     * `context.group`. Silently dropped when opted-out or disabled.
+     *
+     * Group identity is in-memory only and must be re-set after `reset()` or restart.
+     */
+    group(groupId: string, groupTraits?: Record<string, unknown>): void;
+    /** Clear identity and generate a fresh anonymous ID. */
+    reset(): Promise<void>;
+    /**
+     * Register properties that are automatically merged into every subsequent event.
+     * Per-event properties passed to `capture()` override registered properties with
+     * the same key. Use for non-PII session/environment metadata such as
+     * `{ environment: 'production', experiment_group: 'A' }`.
+     *
+     * Registered properties are in-memory only and must be re-registered on restart.
+     */
+    register(properties: Record<string, unknown>): void;
+    /**
+     * Remove specific keys from the registered super properties.
+     * If called with no arguments, all registered properties are cleared.
+     */
+    unregister(...keys: string[]): void;
+    /** Returns a snapshot of all currently registered super properties. */
+    getRegisteredProperties(): Record<string, unknown>;
+    optIn(): Promise<void>;
+    optOut(): Promise<void>;
+    hasOptedIn(): boolean;
+    hasOptedOut(): boolean;
+    getConsentStatus(): ConsentStatus;
+    /** Force-flush the event queue to all adapters immediately. */
+    flush(): Promise<void>;
+    /** Flush and tear down timers. Call on app/component unmount. */
+    shutdown(): Promise<void>;
+    /**
+     * Get the number of times an event has been fired in a given period.
+     * Returns 0 if event counting is disabled or no data exists.
+     */
+    getEventCount(eventName: string, period: EventCountPeriod, date?: Date): Promise<number>;
+    /**
+     * Reset the count for a specific event (or all events if omitted).
+     */
+    resetEventCount(eventName?: string): Promise<void>;
+    /** Access the underlying EventCounter for advanced usage. */
+    readonly eventCounter: IEventCounter | null;
+    /** Expose the current queue length (e.g. for UI indicators). */
+    getQueuedEventCount(): number;
+    /** Returns the audit trail of consent changes (most recent last). */
+    getConsentHistory(): ConsentHistoryEntry[];
+    /**
+     * Prune archived events by age / count, or clear them entirely.
+     * No-op if `enableLocalArchive` was not set in config.
+     *
+     * @param config — pass an empty object `{}` to clear everything
+     */
+    clearLocalArchive(config?: CleanupConfig): Promise<void>;
+    /**
+     * Export all locally held user data as a structured object.
+     * GDPR Article 20 — right to data portability.
+     * No network calls — reads only from in-memory subsystem state.
+     */
+    exportUserData(): Promise<UserDataExport>;
+    /**
+     * Erase all locally held user data.
+     * GDPR Article 17 — right to erasure.
+     *
+     * Clears: event queue, user traits, session, event counts, local archive.
+     * Resets identity to a fresh anonymous ID (new UUID, no distinctId).
+     * Clears in-memory super properties and group identity.
+     * Calls `adapter.reset()` on all adapters.
+     *
+     * @param options.resetConsent - When true, also resets consent status to
+     *   'unknown' so the user is prompted to consent again. Defaults to false
+     *   because the consent audit trail is evidence of past user choices and
+     *   may have regulatory significance.
+     */
+    deleteUserData(options?: {
+        resetConsent?: boolean;
+    }): Promise<void>;
+}
+/** Time granularity for event frequency tracking. */
+type EventCountPeriod = 'daily' | 'weekly' | 'monthly' | 'all-time';
+/**
+ * Tracks how many times each event has been fired, bucketed by time period.
+ * Counts are persisted to IStorageAdapter and survive app restarts.
+ */
+interface IEventCounter {
+    /**
+     * Increment the count for an event on a given date (defaults to now).
+     */
+    increment(eventName: string, date?: Date): Promise<void>;
+    /**
+     * Get the count for an event in a period.
+     * - 'daily': count for the calendar day containing `date`
+     * - 'weekly': count for the ISO week containing `date` (Mon–Sun)
+     * - 'monthly': count for the calendar month containing `date`
+     * - 'all-time': total count across all time
+     */
+    getCount(eventName: string, period: EventCountPeriod, date?: Date): Promise<number>;
+    /**
+     * Reset the count for a specific event, or all events if `eventName` is omitted.
+     */
+    reset(eventName?: string): Promise<void>;
+}
+interface HttpAdapterConfig {
+    /** Full URL of the ingest endpoint, e.g. https://analytics.example.com/batch */
+    endpoint: string;
+    /** Extra request headers, e.g. { 'X-API-Key': '...' } */
+    headers?: Record<string, string>;
+    /** Events per POST request. Default: 50. */
+    batchSize?: number;
+    /** Auto-flush interval in ms. Default: 30_000. */
+    flushIntervalMs?: number;
+    /** Maximum retry attempts before discarding a batch. Default: 3. */
+    maxRetries?: number;
+    /** Initial retry delay in ms (doubles each attempt). Default: 1_000. */
+    retryBaseDelayMs?: number;
+    /** Max retry delay cap in ms. Default: 30_000. */
+    retryMaxDelayMs?: number;
+    /** Request timeout in ms. Default: 10_000. */
+    timeout?: number;
+}
+interface StarfishAdapterConfig {
+    /** Base URL of the Starfish sync server, e.g. https://sync.example.com */
+    serverUrl: string;
+    /**
+     * Path template for the event document.
+     * Use `{identity}` as a placeholder — it is replaced with `distinctId ?? anonymousId`.
+     * Example: "analytics/{identity}/events"
+     */
+    storagePath: string;
+    /** Bearer token for Authorization header. */
+    authToken?: string;
+    /** Max retries on 409 Conflict (optimistic locking). Default: 3. */
+    maxRetries?: number;
+    /**
+     * When true, each successful push creates a **new** Starfish document using
+     * a rotating path suffix (e.g. `events-0001`, `events-0002`…).
+     *
+     * Benefits:
+     * - No pull step needed — each push is always a fresh document
+     * - No growing single document — each file stays small
+     * - Old documents accumulate on Starfish (combine with `cleanupAfterFlush` to prune)
+     *
+     * Requires `pathStorage` to persist the current path generation counter.
+     * Works best with `enableLocalArchive: true` in `SunglassesConfig` so the
+     * complete event history is kept locally even across many push generations.
+     */
+    rotatePathOnSuccess?: boolean;
+    /**
+     * Storage adapter used to persist the current path generation counter.
+     * Required when `rotatePathOnSuccess: true`.
+     * Can be the same adapter as `SunglassesConfig.storage`.
+     */
+    pathStorage?: IStorageAdapter;
+}
+/**
+ * In-memory + persisted session state.
+ * Session IDs are random UUIDs — they never contain PII.
+ */
+interface SessionState {
+    sessionId: string;
+    startedAt: string;
+    lastActiveAt: string;
+    eventCount: number;
+}
+/**
+ * Machine-readable snapshot of all user data held locally by the SDK.
+ * Returned by `client.exportUserData()`.
+ */
+interface UserDataExport {
+    exportedAt: string;
+    anonymousId: string;
+    distinctId: string | null;
+    consentStatus: ConsentStatus;
+    consentHistory: ConsentHistoryEntry[];
+    /** Persisted user traits set via identify(). */
+    traits: Record<string, unknown>;
+    /** Events that have been queued but not yet delivered to any adapter. */
+    queuedEvents: SunglassesEvent[];
+    /**
+     * All events in the local archive.
+     * Only populated when `enableLocalArchive: true`.
+     */
+    archivedEvents: SunglassesEvent[];
+    /**
+     * Summary of event counts per period.
+     * Only populated when `enableEventCounting: true`.
+     */
+    eventCountSummary: {
+        [eventName: string]: Partial<Record<EventCountPeriod, number>>;
+    };
+}
+/**
+ * Optional overrides for a single `capture()` call.
+ * Use sparingly — the defaults (auto timestamp, auto messageId) are correct
+ * for the vast majority of use cases.
+ */
+interface CaptureOptions {
+    /**
+     * Override the event timestamp (ISO-8601 UTC string).
+     * Useful for back-dating events captured offline or migrating historical data.
+     * Defaults to `Date.now()` at the time `capture()` is called.
+     */
+    timestamp?: string;
+    /**
+     * Override the deduplication ID (UUID v4).
+     * Useful when the event was originally generated server-side and you want
+     * to guarantee idempotent delivery even after retries.
+     * Defaults to a freshly generated UUID v4.
+     */
+    messageId?: string;
+}
+/**
+ * A map of event name → required properties shape.
+ * Use with `asTyped<MyEventMap>(client)` to get compile-time checked `capture()`.
+ *
+ * @example
+ * type MyEvents = {
+ *   button_clicked: { buttonId: string; screen: string };
+ *   purchase_completed: { itemId: string; amount: number };
+ *   page_viewed: undefined; // no required properties
+ * };
+ */
+type EventMap = Record<string, Record<string, unknown> | undefined>;
+/**
+ * Typed wrapper around ISunglassesClient.
+ * Provides compile-time checking of event names and their property shapes.
+ * Zero runtime cost — use `asTyped<T>(client)` to obtain one.
+ */
+interface ISunglassesTypedClient<T extends EventMap> extends ISunglassesClient {
+    capture<K extends keyof T & string>(eventName: K, ...args: T[K] extends undefined ? [properties?: Record<string, unknown>] : [properties: T[K]]): void;
+}
+interface ScreenTrackingOptions {
+    /** Web: listen to history.pushState / replaceState / popstate. Default: true. */
+    useHistoryApi?: boolean;
+    /** RN + Expo Router: auto-listen to usePathname changes. */
+    useExpoRouter?: boolean;
+    /** RN + React Navigation: pass the NavigationContainerRef. */
+    navigationRef?: unknown;
+    /** Transform raw pathname/route name → human-readable screen name. */
+    screenNameMapper?: (path: string) => string;
+}
+
+/**
+ * Core SDK engine. Platform-agnostic implementation of ISunglassesClient.
+ *
+ * Use SunglassesCore.create(config) to get an initialized instance.
+ * Do not construct directly — initialization is async and must complete
+ * before any events are captured.
+ */
+declare class SunglassesCore implements ISunglassesClient {
+    private readonly consent;
+    private readonly identity;
+    private readonly queue;
+    private readonly pipeline;
+    private readonly adapters;
+    private readonly _eventCounter;
+    private readonly cleanupConfig;
+    private readonly sessionManager;
+    private readonly traitManager;
+    private readonly localArchive;
+    private readonly config;
+    private flushTimer;
+    private isShutdown;
+    /** Guard against concurrent flushes — prevents double-send. */
+    private flushInFlight;
+    /** In-memory super properties merged into every event's properties. */
+    private readonly superProperties;
+    /** In-memory group ID attached to every event's context after group() is called. */
+    private groupId;
+    private constructor();
+    /**
+     * Create and initialize a SunglassesCore instance.
+     * This is the only way to construct the SDK.
+     */
+    static create(config: SunglassesConfig): Promise<SunglassesCore>;
+    capture(eventName: string, properties?: Record<string, unknown>, options?: CaptureOptions): void;
+    screen(screenName: string, properties?: Record<string, unknown>): void;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    alias(newId: string, existingId: string): void;
+    group(groupId: string, groupTraits?: Record<string, unknown>): void;
+    register(properties: Record<string, unknown>): void;
+    unregister(...keys: string[]): void;
+    getRegisteredProperties(): Record<string, unknown>;
+    reset(): Promise<void>;
+    optIn(): Promise<void>;
+    optOut(): Promise<void>;
+    hasOptedIn(): boolean;
+    hasOptedOut(): boolean;
+    getConsentStatus(): ConsentStatus;
+    getConsentHistory(): ConsentHistoryEntry[];
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    get eventCounter(): IEventCounter | null;
+    getEventCount(eventName: string, period: EventCountPeriod, date?: Date): Promise<number>;
+    resetEventCount(eventName?: string): Promise<void>;
+    getQueuedEventCount(): number;
+    /**
+     * Prune the local event archive by age/count, or clear it entirely.
+     * Pass `{}` to clear all archived events.
+     * No-op when `enableLocalArchive` was not set in config.
+     */
+    clearLocalArchive(config?: CleanupConfig): Promise<void>;
+    /**
+     * Export all locally held user data as a machine-readable object.
+     * GDPR Article 20 — right to data portability.
+     */
+    exportUserData(): Promise<UserDataExport>;
+    /**
+     * Erase all locally held user data. GDPR Article 17 — right to erasure.
+     */
+    deleteUserData(options?: {
+        resetConsent?: boolean;
+    }): Promise<void>;
+    private canCapture;
+    private enqueueEvent;
+    private emitSessionStart;
+    private buildContext;
+    /**
+     * Flush up to maxBatchSize events to every adapter.
+     *
+     * Guards:
+     * - If a flush is already in flight, returns immediately (no double-send).
+     * - If ALL adapters succeed, events are removed from the queue.
+     * - If ANY adapter fails, events stay in the queue for the next flush attempt.
+     *   The failed adapter's own retry logic handles re-delivery.
+     */
+    private flushOnce;
+    private startFlushTimer;
+    private stopFlushTimer;
+}
+
+/**
+ * Built-in middleware that sanitizes event properties before they are queued.
+ *
+ * Sanitization order (allowedProperties takes precedence over deniedProperties):
+ * 1. If allowedProperties is set: keep only those top-level keys.
+ * 2. Else if deniedProperties is set: remove those top-level keys.
+ * 3. Strip built-in PII key names (BUILTIN_DENIED_KEYS) at every nesting level.
+ * 4. Recursively traverse objects and arrays; redact string values matching PII_PATTERNS.
+ *
+ * This middleware is always prepended to the pipeline by SunglassesCore.
+ * It must never throw.
+ */
+declare class PiiSanitizer implements IMiddleware {
+    private readonly allowedProperties?;
+    private readonly deniedProperties?;
+    readonly name = "PiiSanitizer";
+    constructor(allowedProperties?: string[] | undefined, deniedProperties?: string[] | undefined);
+    process(event: SunglassesEvent, next: MiddlewareNext): Promise<SunglassesEvent | null>;
+    private sanitizeProperties;
+    /**
+     * Recursively traverse an object or array:
+     * - Remove keys in BUILTIN_DENIED_KEYS (case-insensitive)
+     * - Redact string values that contain PII
+     * - Recurse into nested objects and arrays
+     */
+    private deepSanitizeValues;
+    private containsPii;
+}
+
+interface Logger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/**
+ * Create a logger that respects the `debug` config flag.
+ * debug/info are no-ops when debug=false.
+ * warn/error always emit.
+ */
+declare function createLogger(debug: boolean): Logger;
+
+/**
+ * Executes an ordered chain of IMiddleware instances.
+ *
+ * - Middleware runs in array order.
+ * - If any middleware returns null, the event is dropped (no further processing).
+ * - Errors inside middleware are caught and treated as a drop (logged as error).
+ */
+declare class MiddlewarePipeline {
+    private readonly middleware;
+    private readonly logger;
+    constructor(middleware: IMiddleware[], logger: Logger);
+    run(event: SunglassesEvent): Promise<SunglassesEvent | null>;
+}
+
+/**
+ * Persists per-event counts bucketed by time period (daily, weekly, monthly, all-time).
+ *
+ * Storage key format:
+ *   `sunglasses:count:{period}:{bucket}:{eventName}`
+ *
+ * where `bucket` is:
+ *   - daily:    "2024-01-15"
+ *   - weekly:   "2024-W03"   (ISO week)
+ *   - monthly:  "2024-01"
+ *   - all-time: "all"
+ *
+ * Counts survive app restarts (persisted to IStorageAdapter).
+ * Designed to be written from the enqueue hot path — must not throw.
+ */
+declare class EventCounter implements IEventCounter {
+    private readonly storage;
+    private readonly logger;
+    /**
+     * In-memory cache of counts keyed by storage key.
+     * Updated synchronously on increment so getCount() can return immediately
+     * without waiting for storage writes to complete.
+     */
+    private readonly cache;
+    /**
+     * Tracks all storage keys written during this session.
+     * Used to reliably clear an event's timed buckets on reset(),
+     * even when they fall outside the 90-day sweep window.
+     */
+    private readonly writtenKeys;
+    constructor(storage: IStorageAdapter, logger: Logger);
+    /**
+     * Increment the count for `eventName` across all four periods for `date`.
+     */
+    increment(eventName: string, date?: Date): Promise<void>;
+    getCount(eventName: string, period: EventCountPeriod, date?: Date): Promise<number>;
+    /**
+     * Reset counts for a specific event (all periods), or all events if omitted.
+     *
+     * Note: resetting all events requires listing storage keys. This is a best-effort
+     * operation — adapters that don't support key enumeration will only clear
+     * the provided event name's keys.
+     */
+    reset(eventName?: string): Promise<void>;
+    private incrementPeriod;
+    private clearEvent;
+    /** Build the storage key for a given event, period, and date. */
+    storageKey(eventName: string, period: EventCountPeriod, date: Date): string;
+    /**
+     * Return the time-bucket string for a given period and date.
+     * - daily:    "2024-01-15"
+     * - weekly:   "2024-W03"
+     * - monthly:  "2024-01"
+     * - all-time: "all"
+     */
+    private bucketFor;
+}
+
+interface FrequencyMiddlewareOptions {
+    /**
+     * The EventCounter instance to read from.
+     * Obtain this from `SunglassesCore.eventCounter` after calling create()
+     * with `enableEventCounting: true`.
+     */
+    counter: EventCounter;
+    /**
+     * Which periods to attach to event properties. Default: ['daily', 'monthly'].
+     * Each selected period adds a property like `$count_daily` or `$count_monthly`.
+     */
+    periods?: EventCountPeriod[];
+    /**
+     * Only attach count properties for these event names.
+     * When omitted, counts are attached to all `capture` events.
+     */
+    onlyFor?: string[];
+}
+/**
+ * Optional middleware that reads event counts from EventCounter and attaches
+ * them to outgoing event properties.
+ *
+ * Properties added (example with periods: ['daily', 'monthly', 'all-time']):
+ * ```json
+ * {
+ *   "$count_daily":    3,
+ *   "$count_monthly":  12,
+ *   "$count_all_time": 47
+ * }
+ * ```
+ *
+ * Usage:
+ * ```ts
+ * const counter = core.eventCounter!;
+ * const freq = new FrequencyMiddleware({ counter, periods: ['daily', 'monthly'] });
+ *
+ * // Pass at creation time:
+ * const client = await SunglassesCore.create({
+ *   enableEventCounting: true,
+ *   middleware: [freq],
+ *   ...
+ * });
+ * ```
+ *
+ * Note: counts reflect the state BEFORE this event is counted. EventCounter.increment
+ * is called from SunglassesCore AFTER the middleware pipeline completes, so the
+ * attached count does NOT yet include the current event (e.g. a `$count_all_time`
+ * of 4 means this is the 5th occurrence — the counter will be 5 after enqueue).
+ */
+declare class FrequencyMiddleware implements IMiddleware {
+    readonly name = "FrequencyMiddleware";
+    private readonly counter;
+    private readonly periods;
+    private readonly onlyFor;
+    constructor(options: FrequencyMiddlewareOptions);
+    process(event: SunglassesEvent, next: MiddlewareNext): Promise<SunglassesEvent | null>;
+}
+
+interface SamplingMiddlewareOptions {
+    /**
+     * Fraction of events to keep, between 0 (drop all) and 1 (keep all).
+     * Example: 0.1 keeps ~10% of events.
+     */
+    sampleRate: number;
+    /**
+     * Only apply sampling to these event names.
+     * When omitted, all `capture` events are subject to sampling.
+     * `$screen`, `$identify`, and `$alias` events are never sampled (always kept).
+     */
+    onlyFor?: string[];
+    /**
+     * When true, the sampling decision is consistent per user session
+     * (based on anonymousId hash), so the same user is always included
+     * or always excluded. Default: false (random per event).
+     */
+    consistentSampling?: boolean;
+}
+/**
+ * Middleware that randomly drops a fraction of events to reduce analytics volume.
+ *
+ * Usage:
+ * ```ts
+ * const sampling = new SamplingMiddleware({ sampleRate: 0.1 }); // Keep 10%
+ *
+ * const client = await SunglassesCore.create({
+ *   middleware: [sampling],
+ *   ...
+ * });
+ * ```
+ *
+ * Privacy note: because sampling is done client-side, opted-out users are
+ * never sampled (they never reach this middleware).
+ */
+declare class SamplingMiddleware implements IMiddleware {
+    readonly name = "SamplingMiddleware";
+    private readonly sampleRate;
+    private readonly onlyFor;
+    private readonly consistentSampling;
+    constructor(options: SamplingMiddlewareOptions);
+    process(event: SunglassesEvent, next: MiddlewareNext): Promise<SunglassesEvent | null>;
+    /**
+     * Determine inclusion based on anonymousId hash.
+     * Produces a stable 0–1 value for the identity so the decision is consistent
+     * across all events in the same session.
+     */
+    private isIncludedByIdentity;
+}
+
+/**
+ * Manages user consent state.
+ *
+ * Consent is persisted via the same IStorageAdapter used by the rest of the SDK,
+ * so platform-correct storage is used automatically (localStorage on web,
+ * AsyncStorage on React Native).
+ *
+ * State machine:
+ *   unknown ──optIn()──▶ opted-in
+ *   unknown ──optOut()──▶ opted-out
+ *   opted-in ──optOut()──▶ opted-out
+ *   opted-out ──optIn()──▶ opted-in
+ *
+ * Policy versioning:
+ *   When `policyVersion` is provided to `initialize()` and differs from the
+ *   stored version, the consent status is reset to 'unknown' — prompting the
+ *   user to consent again under the new policy.
+ */
+declare class ConsentManager {
+    private readonly storage;
+    private readonly logger;
+    private state;
+    constructor(storage: IStorageAdapter, logger: Logger);
+    /**
+     * Load persisted consent state. Must be called once during SDK initialization.
+     * @param defaultOptIn — when no persisted state exists, opt-in (true) or opt-out (false)
+     * @param policyVersion — current policy version; if it differs from stored, consent resets
+     * @param expiryMs — if set, consent older than this resets to 'unknown'
+     */
+    initialize(defaultOptIn: boolean, policyVersion?: string, expiryMs?: number): Promise<void>;
+    get status(): ConsentStatus;
+    isOptedIn(): boolean;
+    isOptedOut(): boolean;
+    optIn(policyVersion?: string): Promise<void>;
+    optOut(policyVersion?: string): Promise<void>;
+    /** Returns a copy of the consent audit trail (oldest first). */
+    getHistory(): ConsentHistoryEntry[];
+    /**
+     * Reset consent status to 'unknown'.
+     * Used internally by consent expiry and deleteUserData().
+     * Appends a history entry so the reset is auditable.
+     */
+    resetToUnknown(policyVersion?: string): Promise<void>;
+    private appendHistory;
+    private persist;
+}
+
+/**
+ * Manages user identity.
+ *
+ * - anonymousId: stable UUID generated on first run, persisted, never PII.
+ *   Only regenerated when reset() is called.
+ * - distinctId: set by identify(). Optionally hashed with SHA-256.
+ *   null until identify() is called — events use anonymousId as distinctId.
+ */
+declare class IdentityManager {
+    private readonly storage;
+    private readonly logger;
+    private readonly anonymizeUserId;
+    private anonymousId;
+    private distinctId;
+    constructor(storage: IStorageAdapter, logger: Logger, anonymizeUserId: boolean);
+    /** Load persisted identity. Must be called once during SDK initialization. */
+    initialize(): Promise<void>;
+    getState(): IdentityState;
+    getAnonymousId(): string;
+    /**
+     * Resolved identity for use in events.
+     * Returns distinctId if set, otherwise anonymousId.
+     */
+    getEffectiveDistinctId(): string;
+    /**
+     * Link current session to a known user.
+     * @param userId — the raw user identifier (hashed if anonymizeUserId=true)
+     * @throws if userId is empty or whitespace-only
+     */
+    identify(userId: string): Promise<string>;
+    /**
+     * Clear identity and generate a fresh anonymous ID.
+     * Adapters should also call their own reset() if applicable.
+     */
+    reset(): Promise<void>;
+}
+
+/**
+ * In-memory event queue with persistence.
+ *
+ * - Events are held in memory and persisted to IStorageAdapter after every enqueue.
+ * - On initialize(), the queue is loaded from storage (survives app restarts).
+ * - When the queue exceeds maxSize, the oldest events are dropped (FIFO).
+ * - flush() pops up to batchSize events for delivery; callers remove them on success.
+ */
+declare class EventQueue {
+    private readonly storage;
+    private readonly logger;
+    private readonly maxSize;
+    private queue;
+    private persistTimer;
+    private persistPending;
+    constructor(storage: IStorageAdapter, logger: Logger, maxSize: number);
+    /** Load persisted queue. Call once during SDK initialization. */
+    initialize(): Promise<void>;
+    /** Add an event to the queue. Triggers async persistence (debounced). */
+    enqueue(event: SunglassesEvent): void;
+    /** Return up to `batchSize` events without removing them. */
+    peek(batchSize: number): SunglassesEvent[];
+    /** Remove the first `count` events (call after successful adapter.send). */
+    remove(count: number): void;
+    get size(): number;
+    /** Force-persist the queue immediately. */
+    persist(): Promise<void>;
+    /** Clear queue from memory and storage. */
+    clear(): Promise<void>;
+    private schedulePersist;
+}
+
+/**
+ * Manages a lightweight anonymous session.
+ *
+ * A session is a contiguous period of activity identified by a random UUID.
+ * Sessions expire when the user is idle for longer than `idleTimeoutMs`.
+ * Session IDs are never derived from PII — they are always fresh UUIDs.
+ *
+ * Usage:
+ *   const sm = new SessionManager(storage, logger, 30 * 60_000);
+ *   await sm.initialize();
+ *   const { sessionId } = sm.getOrCreate();
+ *   sm.touch(); // call on every event to reset the idle timer
+ */
+declare class SessionManager {
+    private readonly storage;
+    private readonly logger;
+    private readonly idleTimeoutMs;
+    private session;
+    private idleTimer;
+    constructor(storage: IStorageAdapter, logger: Logger, idleTimeoutMs?: number);
+    /**
+     * Load the previous session from storage. If it has already expired, it is
+     * discarded so that `getOrCreate()` will start a fresh one.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Return the current session, creating a new one if none exists.
+     * A `$session_start` event should be emitted by the caller whenever this
+     * method creates a new session (detectable by checking whether the returned
+     * `eventCount` is 0).
+     */
+    getOrCreate(): SessionState;
+    /**
+     * Record activity — resets the idle expiry timer and updates `lastActiveAt`.
+     * Call this after every event is successfully enqueued.
+     */
+    touch(now?: Date): void;
+    /**
+     * Explicitly end the current session (e.g. on sign-out or reset).
+     * Clears both in-memory state and storage.
+     */
+    end(): Promise<void>;
+    /** The current session ID, or null if no session is active. */
+    get sessionId(): string | null;
+    private resetIdleTimer;
+    private clearIdleTimer;
+    private persist;
+}
+
+/**
+ * Persists user traits set via `identify()` and makes them available for
+ * enriching every subsequent event's `context.traits`.
+ *
+ * Traits are merged (not replaced) on each `setTraits()` call. Keys whose
+ * names appear in the PII deny-list are stripped before storage.
+ *
+ * Traits are forwarded to analytics backends in `event.context.traits` — they
+ * do NOT appear in `event.properties` to avoid polluting per-event data.
+ */
+declare class TraitManager {
+    private readonly storage;
+    private readonly logger;
+    private traits;
+    constructor(storage: IStorageAdapter, logger: Logger);
+    /**
+     * Load persisted traits from storage. Call once during SDK initialization.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Merge new traits into the persisted set.
+     * Sensitive keys (email, phone, password, etc.) are stripped silently.
+     * Passing `null` as a value removes that key.
+     */
+    setTraits(traits: Record<string, unknown>): Promise<void>;
+    /** Return a shallow copy of the current traits object. */
+    getTraits(): Record<string, unknown>;
+    /** Remove all stored traits (called on reset()). */
+    clearTraits(): Promise<void>;
+    private sanitize;
+    private persist;
+}
+
+/**
+ * Append-only local event archive.
+ *
+ * Unlike the EventQueue (which removes events after a successful flush),
+ * the LocalEventArchive retains every event indefinitely — until the user
+ * explicitly calls `cleanup()` or `clear()`.
+ *
+ * Use cases:
+ * - Full audit trail of all captured events
+ * - Re-syncing a remote store (e.g. Starfish) after a failure
+ * - GDPR data portability export
+ * - Offline-first: accumulate events when a remote adapter is unreachable
+ *
+ * Enable via `SunglassesConfig.enableLocalArchive: true`.
+ */
+declare class LocalEventArchive {
+    private readonly storage;
+    private readonly logger;
+    private events;
+    constructor(storage: IStorageAdapter, logger: Logger);
+    /**
+     * Load all previously archived events from storage.
+     * Call once during SDK initialization.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Append events to the archive.
+     * Deduplicates by `messageId` — safe to call multiple times with the same batch.
+     */
+    append(events: SunglassesEvent[]): Promise<void>;
+    /** All archived events (oldest first). */
+    getAll(): SunglassesEvent[];
+    /** Number of archived events. */
+    get size(): number;
+    /**
+     * Prune archived events by age and/or count.
+     * `maxEventsPerIdentity` is applied **per distinctId** — each identity keeps its
+     * most recent N events independently. If neither option is set, nothing is removed.
+     */
+    cleanup(config?: CleanupConfig): Promise<void>;
+    /**
+     * Remove all archived events and clear storage.
+     * This is irreversible.
+     */
+    clear(): Promise<void>;
+    private persist;
+}
+
+/**
+ * Zero-cost cast that adds compile-time event typing to any ISunglassesClient.
+ *
+ * Define your event map once, then use it everywhere for type-safe `capture()` calls:
+ *
+ * ```typescript
+ * type MyEvents = {
+ *   button_clicked: { buttonId: string; screen: string };
+ *   purchase_completed: { itemId: string; amount: number };
+ *   page_viewed: undefined; // no required properties
+ * };
+ *
+ * const typed = asTyped<MyEvents>(client);
+ *
+ * // Compile-time checked:
+ * typed.capture('button_clicked', { buttonId: 'cta', screen: 'home' }); // ✓
+ * typed.capture('button_clicked', { wrong: 'key' });                    // ✗ type error
+ * typed.capture('unknown_event', {});                                   // ✗ type error
+ * ```
+ *
+ * This is a pure type-level operation — there is no runtime overhead.
+ * All other client methods (`screen`, `identify`, `flush`, etc.) remain unchanged.
+ */
+declare function asTyped<T extends EventMap>(client: ISunglassesClient): ISunglassesTypedClient<T>;
+
+/**
+ * Generate a UUID v4 using the Web Crypto API.
+ *
+ * Works in:
+ * - Browsers (native crypto.randomUUID)
+ * - Node.js 20+ (native crypto.randomUUID)
+ * - React Native with `react-native-get-random-values` polyfill installed
+ */
+declare function generateUUID(): string;
+/**
+ * SHA-256 hash a string and return the hex digest.
+ * Used to anonymize distinctId when anonymizeUserId=true.
+ */
+declare function sha256Hex(input: string): Promise<string>;
+
+/**
+ * Return the current time as an ISO-8601 UTC string.
+ */
+declare function nowISO(): string;
+
+export { type CleanupConfig, type ConsentHistoryEntry, ConsentManager, type ConsentState, type ConsentStatus, type EventContext, type EventCountPeriod, EventCounter, type EventMap, EventQueue, type EventType, FrequencyMiddleware, type FrequencyMiddlewareOptions, type HttpAdapterConfig, type IAnalyticsAdapter, type IEventCounter, type IMiddleware, type IStorageAdapter, type ISunglassesClient, type ISunglassesTypedClient, IdentityManager, type IdentityState, LocalEventArchive, type Logger, type MiddlewareNext, MiddlewarePipeline, PiiSanitizer, SamplingMiddleware, type SamplingMiddlewareOptions, type ScreenTrackingOptions, SessionManager, type SessionState, type StarfishAdapterConfig, type SunglassesConfig, SunglassesCore, type SunglassesEvent, TraitManager, type UserDataExport, asTyped, createLogger, generateUUID, nowISO, sha256Hex };