analyzer-analytics 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gonalc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# analyzer-analytics
+
+Lightweight analytics tracker for web applications. Under 3KB gzipped with support for older browsers and optimized for slow networks.
+
+## Features
+
+- **Tiny footprint** - Core bundle <3KB gzipped
+- **Auto pageview tracking** - Tracks pageviews on load
+- **Custom events** - Track any event with properties
+- **Offline support** - Events queued and sent when online
+- **sendBeacon** - Reliable delivery on page unload
+- **Bot filtering** - Automatically ignores known bots
+
+## Quick Start
+
+### Script Tag
+
+```html
+<script
+  src="/analytics.min.js"
+  data-api-key="your_api_key"
+  data-endpoint="https://your-server.com"
+></script>
+```
+
+### Track Events
+
+```javascript
+// Custom events
+analytics.track('signup', { plan: 'pro' });
+analytics.track('purchase', { product_id: 'abc', price: 99 });
+```
+
+## Installation
+
+### Option 1: Script Tag (recommended)
+
+```html
+<script
+  src="/path/to/analytics.min.js"
+  data-api-key="pk_test_abc123"
+  data-endpoint="http://localhost:8080"
+  data-debug="true"
+></script>
+```
+
+### Option 2: ES Module
+
+```javascript
+import analytics from 'analyzer-analytics';
+
+analytics.init('pk_test_abc123', {
+  endpoint: 'http://localhost:8080'
+});
+```
+
+## Configuration
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `data-api-key` | required | Your project API key |
+| `data-endpoint` | `http://localhost:8080` | Analytics server URL |
+| `data-debug` | `false` | Enable console logging |
+| `data-auto-track` | `true` | Auto-track pageviews |
+
+## API
+
+```javascript
+// Initialize
+analytics.init(apiKey, { endpoint, debug, autoTrack });
+
+// Track event
+analytics.track('event_name', { key: 'value' });
+
+// Force send queued events
+await analytics.flush();
+
+// Get visitor/session IDs
+analytics.instance.getVisitorId();
+analytics.instance.getSessionId();
+```
+
+## Documentation
+
+See the complete **[SDK Usage Guide](../../docs/SDK_USAGE.md)** for:
+- Framework integration (Astro, React, Vue, Next.js)
+- SPA route tracking
+- Event tracking examples
+- Troubleshooting
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) v1.0 or later
+
+### Setup
+
+```bash
+bun install
+```
+
+### Build
+
+```bash
+# Build all formats
+bun run build
+
+# Development mode (watch)
+bun run dev
+```
+
+### Build Output
+
+| File | Size | Description |
+|------|------|-------------|
+| `dist/analytics.min.js` | ~1.6KB gzip | Core build (recommended) |
+| `dist/analytics.esm.js` | ~10KB gzip | ES Module |
+| `dist/analytics.js` | ~10KB gzip | IIFE unminified |
+| `dist/analytics.full.min.js` | ~8KB gzip | Full features |
+
+### Testing
+
+```bash
+bun test
+bun test:watch
+```
+
+### Size Check
+
+```bash
+bun run size-check
+```
+
+Target: Core bundle <3KB gzipped
+
+## License
+
+MIT

package/dist/analytics.d.ts

@@ -0,0 +1,204 @@
+/**
+ * @youranalytics/web-sdk Analytics Class
+ * Core SDK class that orchestrates storage, network, and event tracking
+ */
+import type { AnalyticsConfig, ResolvedConfig, VisitorId, SessionId } from './types';
+/**
+ * Main Analytics SDK class.
+ * Manages event tracking, queue, and communication with the analytics server.
+ *
+ * @example
+ * ```typescript
+ * const analytics = new Analytics({ apiKey: 'pk_live_xxx' });
+ *
+ * // Track custom events
+ * analytics.track('signup', { plan: 'pro' });
+ *
+ * // Track page views (usually automatic)
+ * analytics.trackPageView();
+ *
+ * // Clean up when done
+ * analytics.destroy();
+ * ```
+ */
+export declare class Analytics {
+    private config;
+    private queue;
+    private visitorId;
+    private sessionId;
+    private flushTimer;
+    private isInitialized;
+    private lastPageUrl;
+    private boundHandlePageUnload;
+    private boundHandleOnline;
+    private boundHandleOffline;
+    private boundHandlePopstate;
+    private debouncedTrackPageView;
+    private originalPushState;
+    private originalReplaceState;
+    private adapter;
+    private adapterCleanup;
+    private useAdaptiveNetwork;
+    /**
+     * Create a new Analytics instance.
+     *
+     * @param config - Analytics configuration
+     * @throws Error if API key is missing
+     */
+    constructor(config: AnalyticsConfig);
+    /**
+     * Set up auto-tracking, timers, and event listeners.
+     */
+    private init;
+    /**
+     * Initialize the network adapter for adaptive behavior.
+     */
+    private initNetworkAdapter;
+    /**
+     * Apply adaptive settings based on network conditions.
+     */
+    private applyAdaptiveSettings;
+    /**
+     * Track a custom event.
+     *
+     * @param eventName - Name of the event (will be sanitized)
+     * @param properties - Optional event properties
+     *
+     * @example
+     * ```typescript
+     * analytics.track('purchase', {
+     *   product_id: '123',
+     *   price: 99.99,
+     *   currency: 'USD',
+     * });
+     * ```
+     */
+    track(eventName: string, properties?: Record<string, unknown>): void;
+    /**
+     * Track a page view event.
+     * Convenience method that calls track('pageview', {}).
+     */
+    trackPageView(): void;
+    /**
+     * Internal pageview tracking (not debounced).
+     */
+    private trackPageViewInternal;
+    /**
+     * Send all queued events to the server.
+     * Uses sendBeacon first, falls back to fetch.
+     *
+     * @returns Promise that resolves when flush is complete
+     */
+    flush(): Promise<void>;
+    /**
+     * Build RawEvents from QueuedEvents by adding context metadata.
+     */
+    private buildRawEvents;
+    /**
+     * Start periodic flush timer.
+     */
+    private startFlushTimer;
+    /**
+     * Stop flush timer.
+     */
+    private stopFlushTimer;
+    /**
+     * Set up automatic page view tracking for SPAs.
+     * Wraps history methods and listens to popstate.
+     */
+    private setupPageViewTracking;
+    /**
+     * Wrap history method to track navigation.
+     */
+    private wrapHistoryMethod;
+    /**
+     * Handle popstate event (back/forward navigation).
+     */
+    private handlePopstate;
+    /**
+     * Restore original history methods.
+     */
+    private restoreHistoryMethods;
+    /**
+     * Handle page unload - flush remaining events.
+     * Must use sendBeacon for reliability.
+     */
+    private handlePageUnload;
+    /**
+     * Handle coming back online.
+     * Send any queued offline events.
+     */
+    private handleOnline;
+    /**
+     * Handle going offline.
+     * Flush current queue to localStorage.
+     */
+    private handleOffline;
+    /**
+     * Send any queued offline events.
+     */
+    private sendOfflineEvents;
+    /**
+     * Update configuration at runtime.
+     *
+     * @param updates - Partial configuration to merge
+     */
+    setConfig(updates: Partial<AnalyticsConfig>): void;
+    /**
+     * Get current visitor ID.
+     * Useful for debugging or external tools.
+     *
+     * @returns Current visitor ID
+     */
+    getVisitorId(): VisitorId;
+    /**
+     * Get current session ID.
+     *
+     * @returns Current session ID
+     */
+    getSessionId(): SessionId;
+    /**
+     * Get current configuration.
+     *
+     * @returns Current resolved configuration
+     */
+    getConfig(): ResolvedConfig;
+    /**
+     * Get current queue length.
+     *
+     * @returns Number of events in queue
+     */
+    getQueueLength(): number;
+    /**
+     * Check if SDK is initialized.
+     *
+     * @returns true if initialized
+     */
+    isActive(): boolean;
+    /**
+     * Clean up SDK instance.
+     * Flushes remaining events and removes listeners.
+     */
+    destroy(): void;
+    /**
+     * Log to console if debug enabled.
+     */
+    private log;
+    /**
+     * Warn to console if debug enabled.
+     */
+    private warn;
+    /**
+     * Error to console if debug enabled.
+     */
+    private error;
+}
+/**
+ * Create a new Analytics instance.
+ * Convenience function that wraps the class constructor.
+ *
+ * @param config - Analytics configuration
+ * @returns New Analytics instance
+ */
+export declare function createAnalytics(config: AnalyticsConfig): Analytics;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,SAAS,EACT,SAAS,EAIV,MAAM,SAAS,CAAC;AAyCjB;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,WAAW,CAAM;IAGzB,OAAO,CAAC,qBAAqB,CAAa;IAC1C,OAAO,CAAC,iBAAiB,CAAa;IACtC,OAAO,CAAC,kBAAkB,CAAa;IACvC,OAAO,CAAC,mBAAmB,CAAa;IAGxC,OAAO,CAAC,sBAAsB,CAAa;IAG3C,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,oBAAoB,CAA4C;IAGxE,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,kBAAkB,CAAU;IAEpC;;;;;OAKG;gBACS,MAAM,EAAE,eAAe;IAmDnC;;OAEG;IACH,OAAO,CAAC,IAAI;IAoCZ;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAsB1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAuB7B;;;;;;;;;;;;;;OAcG;IACI,KAAK,CACV,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACvC,IAAI;IAkCP;;;OAGG;IACI,aAAa,IAAI,IAAI;IAI5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAmB7B;;;;;OAKG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoDnC;;OAEG;IACH,OAAO,CAAC,cAAc;IAwBtB;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAiB7B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAqCzB;;OAEG;IACH,OAAO,CAAC,cAAc,CAEpB;IAEF;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAoB7B;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAoBtB;IAEF;;;OAGG;IACH,OAAO,CAAC,YAAY,CAGlB;IAEF;;;OAGG;IACH,OAAO,CAAC,aAAa,CAOnB;IAEF;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAmCzB;;;;OAIG;IACI,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI;IAkCzD;;;;;OAKG;IACI,YAAY,IAAI,SAAS;IAIhC;;;;OAIG;IACI,YAAY,IAAI,SAAS;IAIhC;;;;OAIG;IACI,SAAS,IAAI,cAAc;IAIlC;;;;OAIG;IACI,cAAc,IAAI,MAAM;IAI/B;;;;OAIG;IACI,QAAQ,IAAI,OAAO;IAI1B;;;OAGG;IACI,OAAO,IAAI,IAAI;IA6CtB;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,OAAO,CAAC,IAAI;IAMZ;;OAEG;IACH,OAAO,CAAC,KAAK;CAKd;AAMD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAElE"}