@kitbase/events 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,726 @@
+/**
+ * Configuration options for offline event queueing
+ */
+interface OfflineConfig {
+    /**
+     * Enable offline queueing
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of events to store in the queue
+     * Oldest events are dropped when limit is reached
+     * @default 1000
+     */
+    maxQueueSize?: number;
+    /**
+     * Interval in milliseconds to flush queued events when online
+     * @default 30000 (30 seconds)
+     */
+    flushInterval?: number;
+    /**
+     * Number of events to send per batch when flushing
+     * @default 50
+     */
+    flushBatchSize?: number;
+    /**
+     * Maximum number of retry attempts for failed events
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Base delay in milliseconds for exponential backoff
+     * @default 1000 (1 second)
+     */
+    retryBaseDelay?: number;
+}
+/**
+ * A queued event stored in the database
+ */
+interface QueuedEvent {
+    /**
+     * Auto-incremented unique identifier
+     */
+    id?: number;
+    /**
+     * The event payload to send
+     */
+    payload: LogPayload;
+    /**
+     * Timestamp when the event was queued (ms since epoch)
+     */
+    timestamp: number;
+    /**
+     * Number of retry attempts made
+     */
+    retries: number;
+    /**
+     * Timestamp of the last retry attempt (ms since epoch)
+     */
+    lastAttempt?: number;
+}
+/**
+ * Statistics about the event queue
+ */
+interface QueueStats {
+    /**
+     * Number of events currently in the queue
+     */
+    size: number;
+    /**
+     * Oldest event timestamp in the queue
+     */
+    oldestEvent?: number;
+    /**
+     * Whether the queue is currently flushing
+     */
+    isFlushing: boolean;
+}
+
+/**
+ * Storage interface for anonymous ID persistence
+ */
+interface Storage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+
+/**
+ * Configuration options for the Kitbase client
+ */
+interface KitbaseConfig {
+    /**
+     * Your Kitbase API key
+     */
+    token: string;
+    /**
+     * Override the default API endpoint.
+     * @default 'https://api.kitbase.dev'
+     */
+    baseUrl?: string;
+    /**
+     * Custom storage for anonymous ID persistence.
+     * Defaults to localStorage in browser, in-memory storage otherwise.
+     * Set to null to disable anonymous ID persistence (will generate new ID each session).
+     */
+    storage?: Storage | null;
+    /**
+     * Storage key for the anonymous ID.
+     * @default 'kitbase_anonymous_id'
+     */
+    storageKey?: string;
+    /**
+     * Enable debug mode for console logging.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Offline queueing configuration.
+     * Events are queued locally when offline or when the API fails,
+     * and automatically sent when back online.
+     */
+    offline?: OfflineConfig;
+    /**
+     * Analytics tracking configuration.
+     * Enables session tracking, pageview tracking, and revenue tracking.
+     */
+    analytics?: AnalyticsConfig;
+}
+/**
+ * Tag values can be strings, numbers, or booleans
+ */
+type TagValue = string | number | boolean;
+/**
+ * Event tags for additional metadata
+ */
+type Tags = Record<string, TagValue>;
+/**
+ * Options for tracking an event
+ */
+interface TrackOptions {
+    /**
+     * The channel/category for the event
+     * @example 'payments', 'auth', 'users'
+     */
+    channel: string;
+    /**
+     * The name of the event
+     * @example 'New Subscription', 'User Signed Up'
+     */
+    event: string;
+    /**
+     * Optional user identifier (set when user is identified/logged in)
+     */
+    user_id?: string;
+    /**
+     * Icon for the event (emoji or icon name)
+     * @example '💰', 'money_bag'
+     */
+    icon?: string;
+    /**
+     * Whether to send a notification for this event
+     * @default false
+     */
+    notify?: boolean;
+    /**
+     * Optional description for the event
+     */
+    description?: string;
+    /**
+     * Additional metadata tags
+     */
+    tags?: Tags;
+    /**
+     * Whether to include the anonymous ID in this event.
+     * @default true
+     */
+    includeAnonymousId?: boolean;
+}
+/**
+ * Response from the track API
+ */
+interface TrackResponse {
+    /**
+     * Unique identifier for the logged event
+     */
+    id: string;
+    /**
+     * The event name
+     */
+    event: string;
+    /**
+     * Server timestamp when the event was recorded
+     */
+    timestamp: string;
+}
+/**
+ * Internal request payload sent to the API
+ */
+interface LogPayload {
+    channel: string;
+    event: string;
+    user_id?: string;
+    anonymous_id?: string;
+    icon?: string;
+    notify?: boolean;
+    description?: string;
+    tags?: Tags;
+    /**
+     * Client-side timestamp (ms since epoch) when the event occurred.
+     * Used for accurate session duration calculation, especially in offline mode.
+     */
+    timestamp?: number;
+}
+/**
+ * Session data for analytics tracking
+ */
+interface Session {
+    id: string;
+    startedAt: number;
+    lastActivityAt: number;
+    screenViewCount: number;
+    entryPath?: string;
+    entryReferrer?: string;
+}
+/**
+ * Configuration for analytics tracking
+ */
+interface AnalyticsConfig {
+    /**
+     * Enable automatic pageview tracking on route changes
+     * @default false
+     */
+    autoTrackPageViews?: boolean;
+    /**
+     * Enable automatic session tracking
+     * @default true
+     */
+    autoTrackSessions?: boolean;
+    /**
+     * Session timeout in milliseconds (default: 30 minutes)
+     * @default 1800000
+     */
+    sessionTimeout?: number;
+    /**
+     * Storage key for session data
+     * @default 'kitbase_session'
+     */
+    sessionStorageKey?: string;
+}
+/**
+ * Options for tracking a pageview
+ */
+interface PageViewOptions {
+    /**
+     * The page path (defaults to window.location.pathname)
+     */
+    path?: string;
+    /**
+     * The page title (defaults to document.title)
+     */
+    title?: string;
+    /**
+     * The referrer URL
+     */
+    referrer?: string;
+    /**
+     * Additional metadata tags
+     */
+    tags?: Tags;
+}
+/**
+ * Options for tracking revenue
+ */
+interface RevenueOptions {
+    /**
+     * Revenue amount in cents (e.g., 1999 for $19.99)
+     */
+    amount: number;
+    /**
+     * Currency code (e.g., 'USD', 'EUR')
+     * @default 'USD'
+     */
+    currency?: string;
+    /**
+     * Optional user identifier
+     */
+    user_id?: string;
+    /**
+     * Additional metadata tags
+     */
+    tags?: Tags;
+}
+/**
+ * Options for identifying a user
+ */
+interface IdentifyOptions {
+    /**
+     * The unique user identifier
+     */
+    userId: string;
+    /**
+     * User traits/properties
+     */
+    traits?: Tags;
+}
+
+/**
+ * Kitbase client for tracking events
+ *
+ * @example
+ * ```typescript
+ * import { Kitbase } from '@kitbase/sdk/events';
+ *
+ * const kitbase = new Kitbase({
+ *   token: '<YOUR_API_KEY>',
+ *   debug: true,
+ *   offline: { enabled: true },
+ * });
+ *
+ * // Register super properties (included in all events)
+ * kitbase.register({ app_version: '2.1.0', platform: 'web' });
+ *
+ * // Track anonymous events (anonymous_id is automatically included)
+ * await kitbase.track({
+ *   channel: 'payments',
+ *   event: 'Page Viewed',
+ *   icon: '👀',
+ * });
+ *
+ * // Time events for duration tracking
+ * kitbase.timeEvent('Video Watched');
+ * // ... later
+ * await kitbase.track({
+ *   channel: 'engagement',
+ *   event: 'Video Watched', // $duration automatically included
+ * });
+ *
+ * // Track events for a logged-in user (just pass user_id)
+ * await kitbase.track({
+ *   channel: 'payments',
+ *   event: 'New Subscription',
+ *   user_id: 'user-123',
+ *   icon: '💰',
+ *   notify: true,
+ *   tags: {
+ *     plan: 'premium',
+ *     cycle: 'monthly',
+ *   },
+ * });
+ * ```
+ */
+declare class Kitbase {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly storage;
+    private readonly storageKey;
+    private anonymousId;
+    private superProperties;
+    private timedEvents;
+    private debugMode;
+    private queue;
+    private offlineEnabled;
+    private session;
+    private sessionTimeout;
+    private sessionStorageKey;
+    private analyticsEnabled;
+    private autoTrackPageViews;
+    private userId;
+    private unloadListenerAdded;
+    constructor(config: KitbaseConfig);
+    /**
+     * Initialize the anonymous ID from storage or generate a new one
+     */
+    private initializeAnonymousId;
+    /**
+     * Get the current anonymous ID
+     */
+    getAnonymousId(): string | null;
+    /**
+     * Enable or disable debug mode
+     * When enabled, all SDK operations are logged to the console
+     *
+     * @param enabled - Whether to enable debug mode
+     *
+     * @example
+     * ```typescript
+     * kitbase.setDebugMode(true);
+     * // All events and operations will now be logged
+     * ```
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Check if debug mode is enabled
+     */
+    isDebugMode(): boolean;
+    /**
+     * Internal logging function
+     */
+    private log;
+    /**
+     * Register super properties that will be included with every event
+     * These properties are stored in memory only and reset on page reload
+     *
+     * @param properties - Properties to register
+     *
+     * @example
+     * ```typescript
+     * kitbase.register({
+     *   app_version: '2.1.0',
+     *   platform: 'web',
+     *   environment: 'production',
+     * });
+     * ```
+     */
+    register(properties: Tags): void;
+    /**
+     * Register super properties only if they haven't been set yet
+     * Useful for setting default values that shouldn't override existing ones
+     *
+     * @param properties - Properties to register if not already set
+     *
+     * @example
+     * ```typescript
+     * kitbase.registerOnce({ first_visit: new Date().toISOString() });
+     * ```
+     */
+    registerOnce(properties: Tags): void;
+    /**
+     * Remove a super property
+     *
+     * @param key - The property key to remove
+     *
+     * @example
+     * ```typescript
+     * kitbase.unregister('platform');
+     * ```
+     */
+    unregister(key: string): void;
+    /**
+     * Get all registered super properties
+     *
+     * @returns A copy of the current super properties
+     *
+     * @example
+     * ```typescript
+     * const props = kitbase.getSuperProperties();
+     * console.log(props); // { app_version: '2.1.0', platform: 'web' }
+     * ```
+     */
+    getSuperProperties(): Tags;
+    /**
+     * Clear all super properties
+     *
+     * @example
+     * ```typescript
+     * kitbase.clearSuperProperties();
+     * ```
+     */
+    clearSuperProperties(): void;
+    /**
+     * Start timing an event
+     * When the same event is tracked later, a $duration property (in seconds)
+     * will automatically be included
+     *
+     * @param eventName - The name of the event to time
+     *
+     * @example
+     * ```typescript
+     * kitbase.timeEvent('Video Watched');
+     * // ... user watches video ...
+     * await kitbase.track({
+     *   channel: 'engagement',
+     *   event: 'Video Watched',
+     *   tags: { video_id: '123' }
+     * });
+     * // Event will include $duration: 45.2 (seconds)
+     * ```
+     */
+    timeEvent(eventName: string): void;
+    /**
+     * Cancel a timed event without tracking it
+     *
+     * @param eventName - The name of the event to cancel timing for
+     *
+     * @example
+     * ```typescript
+     * kitbase.timeEvent('Checkout Flow');
+     * // User abandons checkout
+     * kitbase.cancelTimeEvent('Checkout Flow');
+     * ```
+     */
+    cancelTimeEvent(eventName: string): void;
+    /**
+     * Get all currently timed events
+     *
+     * @returns Array of event names that are currently being timed
+     *
+     * @example
+     * ```typescript
+     * const timedEvents = kitbase.getTimedEvents();
+     * console.log(timedEvents); // ['Video Watched', 'Checkout Flow']
+     * ```
+     */
+    getTimedEvents(): string[];
+    /**
+     * Get the duration of a timed event (without stopping it)
+     *
+     * @param eventName - The name of the event
+     * @returns Duration in seconds, or null if not being timed
+     */
+    getEventDuration(eventName: string): number | null;
+    /**
+     * Get offline queue statistics
+     *
+     * @returns Queue statistics including size and flush status
+     *
+     * @example
+     * ```typescript
+     * const stats = await kitbase.getQueueStats();
+     * console.log(stats); // { size: 5, isFlushing: false }
+     * ```
+     */
+    getQueueStats(): Promise<QueueStats | null>;
+    /**
+     * Manually flush the offline queue
+     * Events are automatically flushed on interval and when coming back online,
+     * but this method can be used to trigger an immediate flush
+     *
+     * @example
+     * ```typescript
+     * await kitbase.flushQueue();
+     * ```
+     */
+    flushQueue(): Promise<void>;
+    /**
+     * Clear all events from the offline queue
+     *
+     * @example
+     * ```typescript
+     * await kitbase.clearQueue();
+     * ```
+     */
+    clearQueue(): Promise<void>;
+    /**
+     * Callback for the queue to send batched events
+     */
+    private sendQueuedEvents;
+    /**
+     * Track an event
+     *
+     * When offline queueing is enabled, events are always written to the local
+     * database first (write-ahead), then sent to the server. This ensures no
+     * events are lost if the browser crashes or the network fails.
+     *
+     * @param options - Event tracking options
+     * @returns Promise resolving to the track response
+     * @throws {ValidationError} When required fields are missing
+     * @throws {AuthenticationError} When the API key is invalid (only when offline disabled)
+     * @throws {ApiError} When the API returns an error (only when offline disabled)
+     * @throws {TimeoutError} When the request times out (only when offline disabled)
+     */
+    track(options: TrackOptions): Promise<TrackResponse>;
+    private validateTrackOptions;
+    /**
+     * Send a request to the API
+     */
+    private sendRequest;
+    private parseResponseBody;
+    private getErrorMessage;
+    /**
+     * Load session from storage
+     */
+    private loadSession;
+    /**
+     * Save session to storage
+     */
+    private saveSession;
+    /**
+     * Get or create a session
+     */
+    private getOrCreateSession;
+    /**
+     * Get the current session ID (or null if no active session)
+     */
+    getSessionId(): string | null;
+    /**
+     * Get the current session data
+     */
+    getSession(): Session | null;
+    /**
+     * Track session start event
+     */
+    private trackSessionStart;
+    /**
+     * End the current session (clears local state only - server calculates metrics)
+     */
+    private endSession;
+    /**
+     * Setup listeners for session lifecycle management
+     */
+    private setupUnloadListener;
+    /**
+     * Get UTM parameters from URL
+     */
+    private getUtmParams;
+    /**
+     * Track a page view
+     *
+     * @param options - Page view options
+     * @returns Promise resolving to the track response
+     *
+     * @example
+     * ```typescript
+     * // Track current page
+     * await kitbase.trackPageView();
+     *
+     * // Track with custom path
+     * await kitbase.trackPageView({ path: '/products/123', title: 'Product Details' });
+     * ```
+     */
+    trackPageView(options?: PageViewOptions): Promise<TrackResponse>;
+    /**
+     * Enable automatic page view tracking
+     * Intercepts browser history changes (pushState, replaceState, popstate)
+     *
+     * @example
+     * ```typescript
+     * kitbase.enableAutoPageViews();
+     * // Now all route changes will automatically be tracked
+     * ```
+     */
+    enableAutoPageViews(): void;
+    /**
+     * Track a revenue event
+     *
+     * @param options - Revenue options
+     * @returns Promise resolving to the track response
+     *
+     * @example
+     * ```typescript
+     * // Track a $19.99 purchase
+     * await kitbase.trackRevenue({
+     *   amount: 1999,
+     *   currency: 'USD',
+     *   tags: { product_id: 'prod_123', plan: 'premium' },
+     * });
+     * ```
+     */
+    trackRevenue(options: RevenueOptions): Promise<TrackResponse>;
+    /**
+     * Identify a user
+     * Links the current anonymous ID to a user ID for future events
+     *
+     * @param options - Identify options
+     *
+     * @example
+     * ```typescript
+     * kitbase.identify({
+     *   userId: 'user_123',
+     *   traits: { email: 'user@example.com', plan: 'premium' },
+     * });
+     * ```
+     */
+    identify(options: IdentifyOptions): void;
+    /**
+     * Get the current user ID (set via identify)
+     */
+    getUserId(): string | null;
+    /**
+     * Reset the user identity and session
+     * Call this when a user logs out
+     *
+     * @example
+     * ```typescript
+     * kitbase.reset();
+     * ```
+     */
+    reset(): void;
+    /**
+     * Shutdown the client and cleanup resources
+     * Call this when you're done using the client to stop timers and close connections
+     *
+     * @example
+     * ```typescript
+     * await kitbase.shutdown();
+     * ```
+     */
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Base error class for Kitbase SDK errors
+ */
+declare class KitbaseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when API authentication fails
+ */
+declare class AuthenticationError extends KitbaseError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when the API request fails
+ */
+declare class ApiError extends KitbaseError {
+    readonly statusCode: number;
+    readonly response?: unknown;
+    constructor(message: string, statusCode: number, response?: unknown);
+}
+/**
+ * Error thrown when request validation fails
+ */
+declare class ValidationError extends KitbaseError {
+    readonly field?: string;
+    constructor(message: string, field?: string);
+}
+/**
+ * Error thrown when a request times out
+ */
+declare class TimeoutError extends KitbaseError {
+    constructor(message?: string);
+}
+
+export { type AnalyticsConfig, ApiError, AuthenticationError, type IdentifyOptions, Kitbase, type KitbaseConfig, KitbaseError, type OfflineConfig, type PageViewOptions, type QueueStats, type QueuedEvent, type RevenueOptions, type Session, type Storage, type TagValue, type Tags, TimeoutError, type TrackOptions, type TrackResponse, ValidationError };