/**
 * @module AnalyticsTypes
 * @package @geenius/analytics
 * @description Defines the shared analytics domain model used across the core
 * tracker, provider integrations, UI variants, and Convex support package.
 * These types establish the public contract that every variant builds on.
 */
/**
 * Analytics event category used by the shared tracker and validators.
 */
type EventType = "page_view" | "click" | "form_submit" | "custom";
/**
 * Browser and device metadata captured alongside analytics events.
 *
 * @property device Canonical device bucket derived from the client environment.
 */
interface DeviceInfo {
    browser: string;
    os: string;
    device: "desktop" | "tablet" | "mobile";
    screenWidth: number;
    screenHeight: number;
    language: string;
}
/**
 * Normalized analytics event payload tracked by the shared runtime.
 *
 * @property properties Optional event-specific metadata payload.
 * @property ipAddress Optional client IP address, truncated before storage when IP masking is enabled.
 * @property sessionId Session identifier associated with the event.
 */
interface AnalyticsEvent {
    id: string;
    type: EventType;
    name: string;
    properties?: Record<string, unknown>;
    url: string;
    referrer: string;
    ipAddress?: string;
    sessionId: string;
    userId?: string;
    traits?: UserTraits;
    device: DeviceInfo;
    timestamp: number;
}
/**
 * Normalized page-view payload tracked by the shared runtime.
 *
 * @property properties Optional page-view metadata such as campaign or route data.
 * @property duration Optional dwell time in milliseconds for the page.
 * @property ipAddress Optional client IP address, truncated before storage when IP masking is enabled.
 * @property sessionId Session identifier associated with the page view.
 */
interface PageView {
    url: string;
    title: string;
    referrer: string;
    properties?: Record<string, unknown>;
    duration?: number;
    ipAddress?: string;
    sessionId: string;
    userId?: string;
    timestamp: number;
}
/**
 * Consent payload controlling which categories of tracking are allowed.
 *
 * @property essential Required product and privacy operations that stay enabled.
 * @property personalization Product personalization and feature preference tracking.
 * @property functional Deprecated alias retained for existing integrations.
 * @property timestamp Time at which the consent decision was recorded.
 */
interface ConsentSettings {
    essential: boolean;
    analytics: boolean;
    marketing: boolean;
    personalization: boolean;
    functional?: boolean;
    timestamp: number;
}
/**
 * User traits forwarded to analytics providers during identification.
 */
interface UserTraits {
    email?: string;
    name?: string;
    plan?: string;
    company?: string;
    avatar?: string;
    [key: string]: unknown;
}

/**
 * @module GoogleAnalyticsProvider
 * @package @geenius/analytics
 * @description Implements the shared Google Analytics 4 provider using the
 * global `gtag.js` browser script. The provider injects the runtime script on
 * demand and adapts shared event/page payloads to GA4 conventions.
 */

declare global {
    interface Window {
        dataLayer: unknown[];
        gtag: (...args: unknown[]) => void;
    }
}

/**
 * @module CloudflareKVAnalyticsStore
 * @package @geenius/analytics/cloudflareKV
 * @description Cloudflare KV analytics provider for edge-friendly event,
 * page-view, consent, counter, and aggregate snapshot storage.
 */

/**
 * Minimal KV list response shape consumed by the analytics store.
 */
interface KVListResult {
    keys: Array<{
        name: string;
    }>;
    list_complete: boolean;
    cursor?: string;
}
/**
 * Cloudflare KV-compatible namespace contract required by the analytics store.
 */
interface AnalyticsKVNamespace {
    get(key: string): Promise<string | null>;
    put(key: string, value: string, options?: {
        expirationTtl?: number;
    }): Promise<void>;
    delete(key: string): Promise<void>;
    list(options?: {
        prefix?: string;
        cursor?: string;
        limit?: number;
    }): Promise<KVListResult>;
}
/**
 * Options used to bind analytics storage to a KV namespace.
 */
interface CloudflareKVAnalyticsStoreOptions {
    namespace: AnalyticsKVNamespace;
    keyPrefix?: string;
    /** Legacy short-lived record TTL applied only to events, page views, and sessions. */
    ttlSeconds?: number;
    /** Optional TTL for individual tracked event records. */
    eventsTtlSeconds?: number;
    /** Optional TTL for individual page-view records. */
    pageViewsTtlSeconds?: number;
    /** Optional TTL for session activity records. */
    sessionsTtlSeconds?: number;
    /** Optional TTL for counter records; counters are durable by default. */
    countersTtlSeconds?: number;
    /** Optional TTL for page-view aggregate records; aggregates are durable by default. */
    pageViewAggregatesTtlSeconds?: number;
    /** Optional TTL for generic aggregate snapshots; snapshots are durable by default. */
    aggregateSnapshotsTtlSeconds?: number;
}
/**
 * TTL-backed analytics session record stored in KV.
 */
interface CloudflareKVSessionRecord {
    sessionId: string;
    userId?: string;
    startedAt: number;
    lastSeenAt: number;
    metadata?: Record<string, unknown>;
}
/**
 * Counter value stored as a single KV key.
 */
interface CloudflareKVCounterRecord {
    name: string;
    value: number;
    updatedAt: number;
}
/**
 * Page-view aggregate snapshot maintained per URL.
 */
interface CloudflareKVPageViewAggregate {
    url: string;
    views: number;
    uniqueVisitors: number;
    lastViewedAt: number;
}
/**
 * Generic aggregate snapshot persisted for dashboard/realtime consumers.
 */
interface CloudflareKVAggregateSnapshot<TData = unknown> {
    id: string;
    kind: "dashboard" | "realtime" | "pageviews" | "custom";
    data: TData;
    generatedAt: number;
}
/**
 * Public Cloudflare KV analytics store contract for edge-friendly event storage.
 */
interface CloudflareKVAnalyticsStore {
    trackEvent(event: AnalyticsEvent): Promise<AnalyticsEvent>;
    trackPageView(pageView: PageView): Promise<PageView>;
    identifyUser(userId: string, traits?: UserTraits): Promise<void>;
    listEvents(limit?: number): Promise<AnalyticsEvent[]>;
    getEvent(id: string): Promise<AnalyticsEvent | null>;
    deleteEvent(id: string): Promise<boolean>;
    putConsentState(userId: string, consent: ConsentSettings): Promise<void>;
    getConsentState(userId: string): Promise<ConsentSettings | null>;
    upsertSession(session: CloudflareKVSessionRecord): Promise<CloudflareKVSessionRecord>;
    getSession(sessionId: string): Promise<CloudflareKVSessionRecord | null>;
    incrementCounter(name: string, delta?: number): Promise<CloudflareKVCounterRecord>;
    getCounter(name: string): Promise<CloudflareKVCounterRecord | null>;
    getPageViewAggregate(url: string): Promise<CloudflareKVPageViewAggregate | null>;
    listPageViewAggregates(limit?: number): Promise<CloudflareKVPageViewAggregate[]>;
    putAggregateSnapshot<TData>(snapshot: CloudflareKVAggregateSnapshot<TData>): Promise<CloudflareKVAggregateSnapshot<TData>>;
    getAggregateSnapshot<TData = unknown>(id: string): Promise<CloudflareKVAggregateSnapshot<TData> | null>;
    listAggregateSnapshots(kind?: CloudflareKVAggregateSnapshot["kind"], limit?: number): Promise<Array<CloudflareKVAggregateSnapshot<unknown>>>;
    deleteUserData(userId: string): Promise<void>;
    unsupportedRelationalQuery(operation: string): never;
}
/**
 * Creates an in-memory KV namespace compatible with the Cloudflare KV provider.
 *
 * @returns A deterministic KV namespace useful for tests and local demos.
 */
declare function createMemoryKVNamespace(): AnalyticsKVNamespace;
/**
 * Creates an analytics store backed by a Cloudflare KV-compatible namespace.
 *
 * @param options KV namespace, key prefix, and optional TTL settings.
 * @returns A Cloudflare KV analytics store implementation.
 */
declare function createCloudflareKVAnalyticsStore(options: CloudflareKVAnalyticsStoreOptions): CloudflareKVAnalyticsStore;

export { type AnalyticsKVNamespace, type CloudflareKVAggregateSnapshot, type CloudflareKVAnalyticsStore, type CloudflareKVAnalyticsStoreOptions, type CloudflareKVCounterRecord, type CloudflareKVPageViewAggregate, type CloudflareKVSessionRecord, type KVListResult, createCloudflareKVAnalyticsStore, createMemoryKVNamespace };