⚡ Context Awareness SDK

A lightweight, zero-dependency JavaScript SDK for capturing real-time device context and environmental signals—including Geolocation, Reverse Geocoding, Ambient Weather, Battery Health, Network State, Hardware Capacity, and Temporal Cycles.

It features background Service Worker integration and automated periodic dispatches to keep native and web notification systems in sync with current context.

📦 Installation

Install the package via npm:

npm install context-awareness-sdk

🚀 Quick Start Guide
​1. Serve the Service Worker
​Ensure sw.js (included in the package) is hosted from your project's public root directory so the browser can register it.
​2. Initialize and Start Tracking
​Import and launch the SDK in your web or mobile application:

import { AwarenessEngine } from 'context-awareness-sdk';

const engine = new AwarenessEngine({
  serviceWorkerPath: './sw.js',
  notificationIntervalMs: 60000, // Trigger updates every 60 seconds
  enableNotifications: true,
  debug: false
});

// Subscribe to real-time context updates
engine.subscribe((signals) => {
  console.log('Current Device Signals:', signals);
});

// Start tracking signals & periodic notifications
await engine.start();

⚙️ Configuration Options
​You can customize the engine's behavior during initialization:
Parameter Type Default Description
serviceWorkerPath string './sw.js' Path to the background Service Worker file.
notificationIntervalMs number 60000 Frequency (in milliseconds) for periodic notification updates.
weatherRefreshDistanceMeters number 1000 Minimum movement distance (in meters) required before fetching fresh weather data.
enableNotifications boolean true Enables or disables background notification dispatches.
autoRequestPermissions boolean true Automatically prompts the user for Notification and Geolocation permissions on start.
debug boolean false

📡 Tracked Context Signals (28 Total)
​The SDK automatically monitors and exposes 28 distinct context signals across 6 core categories:
​📍 Geolocation & Motion (1–6)
​Location Name: Reverse-geocoded place name (e.g., City, Country).
​GPS Latitude: Current latitude coordinates.
​GPS Longitude: Current longitude coordinates.
​GPS Accuracy: Radius accuracy in meters.
​Motion Speed: Active movement speed (m/s).
​Compass Heading: Compass direction in degrees (^\circ).
​🌤️ Ambient Weather (7–12)
​Weather Condition: Human-readable condition summary (e.g., Clear sky, Rain).
​Ambient Temperature: Current temperature (^\circ C).
​Relative Humidity: Current air humidity percentage (\%).
​Wind Speed: Wind speed (km/h).
​WMO Weather Code: Standard numerical WMO weather code.
​Rain Detection: Boolean flag indicating active precipitation.
​🔋 Battery & Power (13–16)
​Battery Level: Current battery charge percentage (\%).
​Charging State: Boolean indicator for active charging.
​Battery Health Warning: Low power flag (\le 20\%).
​Power Connection Source: Identifies AC adapter vs. battery power.
​📶 Network & System Hardware (17–21)
​Online Status: Network connectivity indicator (navigator.onLine).
​Network State: Active connection state indicator.
​Device RAM: Approximate device memory capacity (GB).
​CPU Logical Cores: Available hardware concurrency.
​Touch Support: Maximum simultaneous touch point capacity.
​⏰ Temporal & Locale Context (22–25)
​Day Cycle Phase: Categorized time phase (Morning, Afternoon, Evening, Night).
​Weekend Status: Boolean weekend vs. weekday detector.
​System TimeZone: Local IANA time zone string (e.g., Africa/Lagos).
​System Language: Preferred system locale string (e.g., en-US).
​👁️ Application & Environment (26–28)
​App Visibility State: App foreground (visible) vs. background (hidden) state.
​Document Focus: Active window focus detector.
​Notification Permission Status: Browser notification permission state.
​📖 Complete API Documentation
​For advanced architecture guides, custom signal integrations, and full API references, visit https://docs.google.com/document/d/1ZpgBYpuP-D7VgeeFDODMne-T5epp4OsWlPk0GqIIUdE/edit?usp=drivesdk.

​📄 License
​MIT
---

### Step 2: Save and Publish

1. Press **`Ctrl + O`** then **`Enter`** to save inside `nano`.
2. Press **`Ctrl + X`** to exit.
3. Publish your updated package:

```bash
npm publish --access public