solo-analytics 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Céss White
+
+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

@@ -1,83 +1,92 @@
 # 📊 Solo Analytics
 
-Una biblioteca TypeScript ligera y completa para recopilar información del navegador y del dispositivo de una manera simple.
+A lightweight TypeScript library for comprehensive browser and device information collection with a clean API surface.
 
-## Características
+[![npm version](https://img.shields.io/npm/v/solo-analytics.svg?style=flat-square)](https://www.npmjs.com/package/solo-analytics)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?style=flat-square)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](https://github.com/cesswhite/solo-analytics/blob/main/LICENSE)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/solo-analytics?style=flat-square)](https://bundlephobia.com/package/solo-analytics)
 
-- 🔍 Detección completa del navegador, sistema operativo y dispositivo
-- 📱 Identificación de dispositivos móviles, tablets y escritorio
-- 🌐 Información de red y conectividad
-- 📏 Detalles de pantalla y orientación
-- ⚡ Métricas de rendimiento
-- 🌍 Información de ubicación y entorno
-- ⚙️ Detección de funcionalidades avanzadas (cámara, micrófono, batería, etc.)
-- 🔒 Detección de modo incógnito
-- 🔄 Actualización automática opcional de datos
+## Features
 
-## Instalación
+- 🔍 Extensive browser, OS, and device detection with full TypeScript support
+- 📱 Precise mobile, tablet, and desktop device classification
+- 🌐 Network connectivity and performance data
+- 📏 Screen and viewport dimensions with orientation detection
+- ⚡ Comprehensive performance metrics (navigation, timing, memory)
+- 🌍 Locale, timezone, and environment information
+- ⚙️ Advanced feature detection (camera, microphone, battery, etc.)
+- 🔒 Incognito/private mode detection
+- 🔄 Auto-refresh capability for dynamic metrics
+
+## Installation
 
 ```bash
 npm install solo-analytics
 ```
 
-## Uso básico
+## Basic Usage
 
 ```typescript
 import { useSoloAnalytics } from "solo-analytics";
 
-// Inicializar con opciones por defecto
+// Initialize with default options
 const analytics = useSoloAnalytics();
 
-// Obtener información básica
-console.log("¿Es móvil?", analytics.isMobile);
-console.log("Navegador:", analytics.browserName);
-console.log("Sistema operativo:", analytics.osName);
+// Access common properties
+console.log("Mobile device:", analytics.isMobile);
+console.log("Browser:", analytics.browserName);
+console.log("OS:", analytics.osName);
 
-// Obtener todos los datos completos
-console.log("Datos completos:", analytics.data);
+// Access the complete data object
+console.log("Full analytics data:", analytics.data);
 ```
 
-## Opciones de configuración
+## Configuration Options
 
 ```typescript
 import { useSoloAnalytics } from "solo-analytics";
 
 const analytics = useSoloAnalytics({
-  // Actualizar automáticamente los datos dinámicos (red, performance)
+  // Automatically refresh dynamic data (network, performance)
   autoRefresh: true,
-  // Intervalo de actualización en milisegundos (por defecto: 30000)
+  // Refresh interval in milliseconds (default: 30000)
   refreshInterval: 10000,
-  // Detectar cambios de visibilidad de la página
+  // Track page visibility changes
   trackVisibility: true,
+  // Skip expensive async probes (incognito, battery, media, permissions)
+  detectFeatures: true,
+  // Defer async probes to idle time (default: true, recommended)
+  lazyFeatures: true,
 });
 ```
 
-## API de retorno
+## API Reference
 
-La función `useSoloAnalytics` retorna un objeto con las siguientes propiedades y métodos:
+The `useSoloAnalytics()` function returns an object with the following methods and properties:
 
-### Métodos
+### Methods
 
-- `refresh()`: Actualiza manualmente todos los datos de análisis
-- `destroy()`: Limpia todos los listeners y timers para evitar fugas de memoria
+- `refresh()`: Manually triggers a refresh of all analytics data
+- `destroy()`: Cleans up all event listeners and timers to prevent memory leaks
 
-### Propiedades de conveniencia
+### Convenience Properties
 
-- `isMobile`: Indica si es un dispositivo móvil
-- `isTablet`: Indica si es una tablet
-- `isDesktop`: Indica si es un dispositivo de escritorio
-- `isOnline`: Estado de conexión a internet
-- `isVisible`: Si la página está visible actualmente
-- `browserName`: Nombre del navegador
-- `osName`: Nombre del sistema operativo
+- `isMobile`: Whether the device is a mobile phone
+- `isTablet`: Whether the device is a tablet
+- `isDesktop`: Whether the device is a desktop computer
+- `isOnline`: Current network connection state
+- `isVisible`: Whether the page is currently visible
+- `browserName`: The name of the browser
+- `osName`: The name of the operating system
 
-### Datos completos
+### Complete Data
 
-- `data`: Un objeto que contiene toda la información detallada
+- `data`: An object containing all detailed analytics information
 
-## Estructura de datos
+## Data Structure
 
-El objeto `data` contiene la siguiente estructura:
+The `data` object contains the following structure:
 
 ```typescript
 interface SoloAnalyticsInfo {
@@ -161,7 +170,7 @@ interface SoloAnalyticsInfo {
 }
 ```
 
-## Uso en proyectos
+## Framework Integration Examples
 
 ### React
 
@@ -173,38 +182,126 @@ function DeviceInfo() {
   const [analytics, setAnalytics] = useState<SoloAnalyticsReturn | null>(null);
 
   useEffect(() => {
-    // Inicializar en el lado del cliente
+    // Initialize on the client side
     const analyticsInstance = useSoloAnalytics();
     setAnalytics(analyticsInstance);
 
-    // Limpiar al desmontar
+    // Cleanup on unmount
     return () => {
       analyticsInstance.destroy();
     };
   }, []);
 
-  if (!analytics) return <div>Cargando...</div>;
+  if (!analytics) return <div>Loading...</div>;
 
   return (
     <div>
-      <h1>Información del dispositivo</h1>
+      <h1>Device Information</h1>
       <p>
-        Tipo:{" "}
+        Type:{" "}
         {analytics.isMobile
-          ? "Móvil"
+          ? "Mobile"
           : analytics.isTablet
           ? "Tablet"
           : "Desktop"}
       </p>
-      <p>Navegador: {analytics.browserName}</p>
-      <p>Sistema operativo: {analytics.osName}</p>
-      <p>En línea: {analytics.isOnline ? "Sí" : "No"}</p>
+      <p>Browser: {analytics.browserName}</p>
+      <p>Operating System: {analytics.osName}</p>
+      <p>Network Status: {analytics.isOnline ? "Online" : "Offline"}</p>
     </div>
   );
 }
 ```
 
-### JavaScript Vanilla
+### Vue 3
+
+```vue
+<template>
+  <div>
+    <h1>Device Information</h1>
+    <p>Type: {{ deviceType }}</p>
+    <p>Browser: {{ analytics.browserName }}</p>
+    <p>Operating System: {{ analytics.osName }}</p>
+    <p>Network Status: {{ analytics.isOnline ? "Online" : "Offline" }}</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { onMounted, onUnmounted, ref, computed } from "vue";
+import { useSoloAnalytics, SoloAnalyticsReturn } from "solo-analytics";
+
+const analytics = ref<SoloAnalyticsReturn | null>(null);
+
+onMounted(() => {
+  analytics.value = useSoloAnalytics({
+    trackVisibility: true,
+  });
+});
+
+onUnmounted(() => {
+  analytics.value?.destroy();
+});
+
+const deviceType = computed(() => {
+  if (!analytics.value) return "Unknown";
+
+  if (analytics.value.isMobile) return "Mobile";
+  if (analytics.value.isTablet) return "Tablet";
+  return "Desktop";
+});
+</script>
+```
+
+### Nuxt 3
+
+```vue
+<template>
+  <div>
+    <h1>Device Information</h1>
+    <div v-if="analytics">
+      <p>Type: {{ deviceType }}</p>
+      <p>Browser: {{ analytics.browserName }}</p>
+      <p>Operating System: {{ analytics.osName }}</p>
+      <p>Network Status: {{ analytics.isOnline ? "Online" : "Offline" }}</p>
+    </div>
+    <div v-else>
+      <p>Loading device information...</p>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { useSoloAnalytics, SoloAnalyticsReturn } from "solo-analytics";
+
+const analytics = ref<SoloAnalyticsReturn | null>(null);
+
+// Important: Only initialize on client-side to avoid SSR issues
+onMounted(() => {
+  analytics.value = useSoloAnalytics({
+    trackVisibility: true,
+    autoRefresh: true,
+    refreshInterval: 15000,
+  });
+});
+
+onBeforeUnmount(() => {
+  if (analytics.value) {
+    analytics.value.destroy();
+  }
+});
+
+const deviceType = computed(() => {
+  if (!analytics.value) return "Unknown";
+
+  if (analytics.value.isMobile) return "Mobile";
+  if (analytics.value.isTablet) return "Tablet";
+  return "Desktop";
+});
+</script>
+```
+
+### Vanilla JavaScript
 
 ```html
 <script type="module">
@@ -213,18 +310,18 @@ function DeviceInfo() {
   document.addEventListener("DOMContentLoaded", () => {
     const analytics = useSoloAnalytics();
 
-    // Mostrar información en la página
+    // Display information on the page
     document.getElementById("deviceType").textContent = analytics.isMobile
-      ? "Móvil"
+      ? "Mobile"
       : analytics.isTablet
       ? "Tablet"
       : "Desktop";
 
     document.getElementById(
       "browserInfo"
-    ).textContent = `${analytics.browserName} en ${analytics.osName}`;
+    ).textContent = `${analytics.browserName} on ${analytics.osName}`;
 
-    // Limpiar al cerrar
+    // Cleanup on window close
     window.addEventListener("beforeunload", () => {
       analytics.destroy();
     });
@@ -232,6 +329,90 @@ function DeviceInfo() {
 </script>
 ```
 
-## Licencia
+## Browser Compatibility
+
+Solo Analytics is compatible with all modern browsers, including:
+
+- Chrome 60+
+- Firefox 55+
+- Safari 11+
+- Edge 16+
+- Opera 47+
+- iOS Safari 11+
+- Android Browser 67+
+
+Some advanced features may not be available in older browsers but the library includes graceful fallbacks.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run development server (demo playground)
+npm run dev
+
+# Type-check and build for production
+npm run build
+
+# Run tests
+npm test
+
+# Watch tests during development
+npm run test:watch
+```
+
+## Performance
+
+Solo Analytics is designed to stay off the critical path:
+
+| Metric | Value |
+|--------|-------|
+| ESM bundle (gzip) | ~3.5 KB |
+| UMD bundle (gzip) | ~3.1 KB |
+| `sideEffects` | `false` (tree-shakeable) |
+
+**Recommendations:**
+
+- Use `lazyFeatures: true` (default) so async probes run during idle time
+- Set `detectFeatures: false` if you only need UA, screen, and network data
+- Call `destroy()` when unmounting in SPAs to clear timers and listeners
+- Initialize client-side only (`onMounted` in Vue/Nuxt, `useEffect` in React)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Repository
+
+GitHub: [https://github.com/cesswhite/solo-analytics](https://github.com/cesswhite/solo-analytics)
+
+## License
+
+MIT License
+
+Copyright (c) 2025 Céss White
+
+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.
 
-MIT
+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/dist/composables/useSoloAnalytics.d.ts

@@ -0,0 +1,46 @@
+import { SoloAnalyticsInfo } from '../types/analytics';
+/**
+ * Type definition for analytics options
+ */
+export interface SoloAnalyticsOptions {
+    /** Automatically refresh dynamic data (network, performance) */
+    autoRefresh?: boolean;
+    /** Refresh interval in milliseconds (default: 30000) */
+    refreshInterval?: number;
+    /** Track page visibility changes */
+    trackVisibility?: boolean;
+    /**
+     * Run expensive async probes (incognito, battery, media, permissions).
+     * Set to `false` to skip entirely and reduce main-thread work.
+     * @default true
+     */
+    detectFeatures?: boolean;
+    /**
+     * Defer async feature probes to idle time via requestIdleCallback.
+     * Sync data (UA, screen, network) is collected immediately.
+     * @default true
+     */
+    lazyFeatures?: boolean;
+}
+/**
+ * Type definition for the return value of useSoloAnalytics
+ */
+export interface SoloAnalyticsReturn {
+    data: SoloAnalyticsInfo;
+    refresh: () => Promise<void>;
+    isMobile: boolean;
+    isTablet: boolean;
+    isDesktop: boolean;
+    isOnline: boolean;
+    isVisible: boolean;
+    browserName: string;
+    osName: string;
+    destroy: () => void;
+}
+/**
+ * A function that provides comprehensive browser, device, and performance analytics.
+ * @param options Configuration options
+ * @returns Object with analytics data and helper methods
+ */
+export declare function useSoloAnalytics(options?: SoloAnalyticsOptions): SoloAnalyticsReturn;
+//# sourceMappingURL=useSoloAnalytics.d.ts.map

package/dist/composables/useSoloAnalytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSoloAnalytics.d.ts","sourceRoot":"","sources":["../../src/composables/useSoloAnalytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAevD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AA8ED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CA6JxF"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { useSoloAnalytics } from './composables/useSoloAnalytics';
+export type { SoloAnalyticsOptions, SoloAnalyticsReturn } from './composables/useSoloAnalytics';
+export type { SoloAnalyticsInfo, BrowserInfo, OSInfo, DeviceInfo, NetworkInfo, ScreenInfo, PerformanceInfo, LocationInfo } from './types/analytics';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAGhG,YAAY,EACV,iBAAiB,EACjB,WAAW,EACX,MAAM,EACN,UAAU,EACV,WAAW,EACX,UAAU,EACV,eAAe,EACf,YAAY,EACb,MAAM,mBAAmB,CAAC"}