datafast 1.0.1

package/README.md

@@ -0,0 +1,140 @@
+# datafast
+
+DataFast analytics SDK for web apps. Use this if you prefer npm packages over the script tag.
+
+## Installation
+
+```bash
+npm install datafast
+```
+
+## Quick Start
+
+Same API as in the [DataFast docs](https://datafa.st/docs): use `initDataFast` once, then call `trackPageview()`, `track()`, `identify()`, and `trackPayment()`. All methods are async and return Promises.
+
+```ts
+import { initDataFast } from 'datafast';
+
+const datafast = await initDataFast({
+  websiteId: 'your-website-id',
+  domain: 'yourdomain.com', // optional, defaults to current hostname
+});
+
+// Track page views
+datafast.trackPageview();
+// Or pass a path (e.g. for SPAs)
+datafast.trackPageview('/pricing');
+
+// Track custom events
+datafast.track('button_click', { button: 'signup' });
+
+// Identify users
+datafast.identify('user_123', { email: 'user@example.com', plan: 'pro' });
+
+// Track payments (pass an object with at least email)
+datafast.trackPayment({ email: 'john@example.com', amount: 99, currency: 'USD' });
+
+// Reset visitor identity (e.g. on logout)
+datafast.reset();
+```
+
+## With React / Next.js
+
+```tsx
+// lib/analytics.ts
+import { initDataFast } from 'datafast';
+
+let datafast: Awaited<ReturnType<typeof initDataFast>> | null = null;
+
+export async function getAnalytics() {
+  if (!datafast) {
+    datafast = await initDataFast({
+      websiteId: process.env.NEXT_PUBLIC_DATAFAST_WEBSITE_ID!,
+      domain: process.env.NEXT_PUBLIC_DATAFAST_DOMAIN,
+    });
+  }
+  return datafast;
+}
+```
+
+Then in your app:
+
+```tsx
+import { getAnalytics } from '@/lib/analytics';
+
+export default function SignupButton() {
+  const handleSignup = async () => {
+    const analytics = await getAnalytics();
+    analytics.track('signup', { plan: 'free', source: 'homepage' });
+  };
+
+  return <button onClick={handleSignup}>Sign Up</button>;
+}
+```
+
+## API
+
+### `initDataFast(config)` → `Promise<DataFastWeb>`
+
+Initialize the SDK. Returns a client with `trackPageview`, `track`, `identify`, `trackPayment`, `reset`, and `flush`.
+
+### Config (`DataFastWebConfig`)
+
+```ts
+{
+  websiteId: string;        // Required: Your DataFast website ID
+  domain?: string;          // Optional: Defaults to current hostname
+  apiUrl?: string;          // Optional: Custom API endpoint
+  debug?: boolean;         // Optional: Enable debug logging
+  flushInterval?: number;   // Optional: ms between flushes (default: 5000)
+  maxQueueSize?: number;   // Optional: max events before flush (default: 10)
+}
+```
+
+### `datafast.trackPageview(path?)` → `Promise<void>`
+
+Track a page view. Omit `path` to use `window.location.pathname`. Call on route changes in SPAs.
+
+### `datafast.track(eventName, properties?)` → `Promise<void>`
+
+Track a custom event. `properties` is optional and must be `Record<string, string | number | boolean>`.
+
+```ts
+await datafast.track('purchase', { product: 'Pro Plan', price: 99 });
+```
+
+### `datafast.identify(userId, properties?)` → `Promise<void>`
+
+Identify a logged-in user.
+
+```ts
+await datafast.identify('user_123', { name: 'John', email: 'john@example.com' });
+```
+
+### `datafast.trackPayment(data)` → `Promise<void>`
+
+Track a payment. `data` must be an object with `email`; `amount` and `currency` are optional.
+
+```ts
+await datafast.trackPayment({ email: 'john@example.com', amount: 99, currency: 'USD' });
+```
+
+### `datafast.reset()` → `Promise<void>`
+
+Reset visitor identity (e.g. on logout). New visitor and session IDs are generated.
+
+### `datafast.flush()` → `Promise<void>`
+
+Flush all queued events immediately.
+
+## Script Tag Alternative
+
+If you prefer not to use npm, add the script tag instead:
+
+```html
+<script src="https://datafa.st/script.js" data-website-id="your-website-id" async defer></script>
+```
+
+## License
+
+MIT

package/dist/web/index.d.mts

@@ -0,0 +1,432 @@
+/**
+ * Storage adapter interface - implement this for your platform
+ */
+interface StorageAdapter {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/**
+ * Network status adapter interface - implement this for your platform
+ */
+interface NetworkAdapter {
+    isConnected(): Promise<boolean>;
+    onConnectionChange?(callback: (isConnected: boolean) => void): () => void;
+}
+/**
+ * Platform information
+ */
+type Platform = 'ios' | 'android' | 'web';
+/**
+ * Configuration options for initializing the SDK
+ */
+interface DataFastConfig {
+    /** Your DataFast app/website ID (required) */
+    appId: string;
+    /** App bundle identifier, e.g., "com.example.myapp" (required for mobile) */
+    domain: string;
+    /** Storage adapter for persisting visitor/session IDs */
+    storage: StorageAdapter;
+    /** Network adapter for checking connectivity */
+    network?: NetworkAdapter;
+    /** Platform: 'ios' | 'android' | 'web' */
+    platform: Platform;
+    /** App version string, e.g., "1.0.0" */
+    appVersion?: string;
+    /** Custom API endpoint (defaults to https://datafa.st/api/events) */
+    apiUrl?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Flush interval in milliseconds for queued events (default: 30000) */
+    flushInterval?: number;
+    /** Maximum events to queue before forcing flush (default: 20) */
+    maxQueueSize?: number;
+}
+/**
+ * Viewport dimensions
+ */
+interface Viewport {
+    width: number;
+    height: number;
+}
+/**
+ * Device information collected by the SDK
+ */
+interface DeviceInfo {
+    platform: Platform;
+    osVersion: string;
+    deviceModel: string;
+    appVersion: string;
+    screenWidth: number;
+    screenHeight: number;
+    viewport: Viewport;
+    language: string;
+    timezone: string;
+}
+/**
+ * Base event payload sent to the API
+ */
+interface BaseEventPayload {
+    websiteId: string;
+    domain: string;
+    visitorId: string;
+    sessionId: string;
+    href: string;
+    referrer: string | null;
+    type: EventType;
+    viewport: Viewport;
+    language: string;
+    timezone: string;
+    screenWidth: number;
+    screenHeight: number;
+    extraData?: Record<string, unknown>;
+}
+/**
+ * Event types supported by the API
+ */
+type EventType = 'pageview' | 'custom' | 'identify' | 'payment' | 'external_link';
+/**
+ * Custom event properties - max 10, keys max 64 chars, values max 255 chars
+ */
+type CustomProperties = Record<string, string | number | boolean>;
+/**
+ * User properties for identify calls
+ */
+interface UserProperties {
+    user_id: string;
+    name?: string;
+    email?: string;
+    image?: string;
+    [key: string]: unknown;
+}
+/**
+ * Payment event data
+ */
+interface PaymentData {
+    email: string;
+    amount?: number;
+    currency?: string;
+}
+/**
+ * Queued event with metadata
+ */
+interface QueuedEvent {
+    id: string;
+    payload: BaseEventPayload;
+    timestamp: number;
+    retries: number;
+}
+/**
+ * Internal state of the SDK
+ */
+interface SDKState {
+    initialized: boolean;
+    visitorId: string | null;
+    sessionId: string | null;
+    sessionStartTime: number | null;
+    lastScreenName: string | null;
+    config: DataFastConfig | null;
+    deviceInfo: DeviceInfo | null;
+}
+
+declare class DataFastClient {
+    private state;
+    private queue;
+    private logger;
+    /**
+     * Initialize the SDK with configuration
+     */
+    init(config: DataFastConfig): Promise<void>;
+    /**
+     * Track a screen view (equivalent to pageview)
+     */
+    trackScreen(screenName: string): Promise<void>;
+    /**
+     * Track a custom event
+     */
+    track(eventName: string, properties?: CustomProperties): Promise<void>;
+    /**
+     * Identify a user
+     */
+    identify(userId: string, properties?: Omit<UserProperties, 'user_id'>): Promise<void>;
+    /**
+     * Track a payment event
+     */
+    trackPayment(data: PaymentData): Promise<void>;
+    /**
+     * Track an external link click
+     */
+    trackExternalLink(url: string, text?: string): Promise<void>;
+    /**
+     * Flush all queued events immediately
+     */
+    flush(): Promise<void>;
+    /**
+     * Reset the session (start a new session)
+     */
+    resetSession(): Promise<void>;
+    /**
+     * Reset the visitor (new anonymous user)
+     */
+    reset(): Promise<void>;
+    /**
+     * Opt out of tracking
+     */
+    optOut(): Promise<void>;
+    /**
+     * Opt back into tracking
+     */
+    optIn(): Promise<void>;
+    /**
+     * Set device info (call this when device info becomes available)
+     */
+    setDeviceInfo(info: Partial<DeviceInfo>): void;
+    /**
+     * Get current visitor ID
+     */
+    getVisitorId(): string | null;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string | null;
+    /**
+     * Check if SDK is initialized and ready
+     */
+    isInitialized(): boolean;
+    /**
+     * Shutdown the SDK
+     */
+    shutdown(): Promise<void>;
+    private isReady;
+    private initVisitorId;
+    private initSessionId;
+    private buildBasePayload;
+}
+/**
+ * Get the singleton DataFast client instance
+ */
+declare function getDataFastClient(): DataFastClient;
+/**
+ * Create a new DataFast client (for cases where you need multiple instances)
+ */
+declare function createDataFastClient(): DataFastClient;
+
+declare class EventQueue {
+    private queue;
+    private storage;
+    private network?;
+    private apiUrl;
+    private userAgent;
+    private flushInterval;
+    private maxQueueSize;
+    private flushTimer;
+    private isFlushing;
+    private onFlushError?;
+    constructor(options: {
+        storage: StorageAdapter;
+        network?: NetworkAdapter;
+        apiUrl: string;
+        userAgent: string;
+        flushInterval?: number;
+        maxQueueSize?: number;
+        onFlushError?: (error: Error, event: QueuedEvent) => void;
+    });
+    /**
+     * Initialize the queue - load persisted events from storage
+     */
+    init(): Promise<void>;
+    /**
+     * Add an event to the queue
+     */
+    enqueue(payload: BaseEventPayload): Promise<void>;
+    /**
+     * Flush all queued events to the server
+     */
+    flush(): Promise<void>;
+    /**
+     * Send a single event to the API
+     */
+    private sendEvent;
+    /**
+     * Persist queue to storage
+     */
+    private persistQueue;
+    /**
+     * Start the periodic flush timer
+     */
+    private startFlushTimer;
+    /**
+     * Stop the flush timer and flush remaining events
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get current queue size
+     */
+    get size(): number;
+    /**
+     * Clear all queued events
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * Generate a UUID v4 for visitor ID
+ * Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (36 chars)
+ */
+declare function generateVisitorId(): string;
+/**
+ * Generate a session ID
+ * Format: sxxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (37 chars, starts with 's')
+ */
+declare function generateSessionId(): string;
+/**
+ * Validate visitor ID format (UUID v4)
+ */
+declare function isValidVisitorId(id: string): boolean;
+/**
+ * Validate session ID format (s + UUID v4)
+ */
+declare function isValidSessionId(id: string): boolean;
+/**
+ * Build the href for a screen view
+ * Format: datafast://platform/ScreenName
+ */
+declare function buildScreenHref(platform: Platform, screenName: string): string;
+/**
+ * Build User-Agent header for mobile SDK
+ * Format: DataFast/version (OS version; Device)
+ */
+declare function buildUserAgent(sdkVersion: string, platform: Platform, osVersion: string, deviceModel: string): string;
+/**
+ * Validate custom event name
+ * - Lowercase alphanumeric + underscore/hyphen
+ * - Max 64 characters
+ */
+declare function isValidEventName(name: string): boolean;
+/**
+ * Validate and sanitize custom properties
+ * - Max 10 properties
+ * - Property names: lowercase alphanumeric + underscore/hyphen, max 64 chars
+ * - Property values: max 255 chars
+ */
+declare function sanitizeCustomProperties(properties: Record<string, unknown>): Record<string, string> | null;
+/**
+ * Generate a unique event ID for queue management
+ */
+declare function generateEventId(): string;
+/**
+ * Check if session has expired (24 hours)
+ */
+declare function isSessionExpired(sessionStartTime: number): boolean;
+/**
+ * Simple logger that respects debug mode
+ */
+declare function createLogger(debug: boolean): {
+    log: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};
+
+/**
+ * Browser localStorage adapter for DataFast
+ */
+declare function createLocalStorageAdapter(): StorageAdapter;
+/**
+ * In-memory storage adapter (fallback when localStorage is not available)
+ */
+declare function createMemoryStorageAdapter(): StorageAdapter;
+
+/**
+ * Browser fetch-based network adapter for DataFast
+ */
+declare function createFetchNetworkAdapter(): NetworkAdapter;
+
+/**
+ * Get device info for web browsers
+ */
+declare function getDeviceInfo(): Partial<DeviceInfo>;
+/**
+ * Listen for viewport changes (resize events)
+ */
+declare function onViewportChange(callback: (viewport: {
+    width: number;
+    height: number;
+}) => void): () => void;
+
+/**
+ * Simplified configuration for web apps
+ */
+interface DataFastWebConfig {
+    /** Your DataFast website ID */
+    websiteId: string;
+    /** Domain (defaults to current hostname) */
+    domain?: string;
+    /** Custom API endpoint */
+    apiUrl?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Flush interval in ms (default: 5000) */
+    flushInterval?: number;
+    /** Max queue size before flush (default: 10) */
+    maxQueueSize?: number;
+}
+/**
+ * Initialize DataFast for web apps
+ *
+ * This is the recommended way to use DataFast in browser environments.
+ * It automatically configures localStorage and fetch adapters and returns
+ * a client with trackPageview(), track(), identify(), trackPayment(), reset().
+ *
+ * Usage (matches docs):
+ * ```ts
+ * import { initDataFast } from 'datafast';
+ *
+ * const datafast = await initDataFast({
+ *   websiteId: 'your-website-id',
+ * });
+ *
+ * datafast.trackPageview();
+ * datafast.track('button_click', { button: 'signup' });
+ * datafast.identify('user_123', { name: 'John' });
+ * ```
+ */
+declare function initDataFast(config: DataFastWebConfig): Promise<DataFastWeb>;
+/**
+ * Create a DataFast client with manual configuration
+ *
+ * Use this for more control over adapters or for non-standard setups.
+ *
+ * Usage:
+ * ```ts
+ * import {
+ *   createDataFastWithAdapters,
+ *   createLocalStorageAdapter,
+ *   createFetchNetworkAdapter,
+ * } from 'datafast/web';
+ *
+ * const datafast = await createDataFastWithAdapters({
+ *   appId: 'your-website-id',
+ *   domain: 'example.com',
+ *   storage: createLocalStorageAdapter(),
+ *   network: createFetchNetworkAdapter(),
+ *   platform: 'web',
+ * });
+ * ```
+ */
+declare function createDataFastWithAdapters(config: DataFastConfig): Promise<DataFastClient>;
+interface DataFastWeb extends DataFastClient {
+    /** Track a page view (alias for trackScreen). Optional path defaults to current location. */
+    trackPageview(path?: string): Promise<void>;
+}
+/**
+ * Create a web-optimized DataFast client. Same as initDataFast (alias).
+ */
+declare function createDataFastWeb(config: DataFastWebConfig): Promise<DataFastWeb>;
+declare const dataFastWeb: {
+    init: typeof initDataFast;
+    createWeb: typeof createDataFastWeb;
+    getClient: typeof getDataFastClient;
+    createClient: typeof createDataFastClient;
+};
+
+export { type BaseEventPayload, type CustomProperties, DataFastClient, type DataFastConfig, type DataFastWeb, type DataFastWebConfig, type DeviceInfo, EventQueue, type EventType, type NetworkAdapter, type PaymentData, type Platform, type QueuedEvent, type SDKState, type StorageAdapter, type UserProperties, type Viewport, buildScreenHref, buildUserAgent, createDataFastClient, createDataFastWeb, createDataFastWithAdapters, createFetchNetworkAdapter, createLocalStorageAdapter, createLogger, createMemoryStorageAdapter, dataFastWeb as default, generateEventId, generateSessionId, generateVisitorId, getDataFastClient, getDeviceInfo, initDataFast, isSessionExpired, isValidEventName, isValidSessionId, isValidVisitorId, onViewportChange, sanitizeCustomProperties };