@shyntech-proximity/sensor-app 1.0.0

package/README.md

@@ -0,0 +1,270 @@
+# Proximity Sensor Service
+
+The **Proximity Sensor Service** is a real-time physical–digital bridge that ingests **radio proximity signals** (Wi-Fi, Wi-Fi Direct, BLE) from nearby devices and resolves **nearby vendors and inventories** using SSID / identifier matching.
+
+It enables **hyperlocal discovery**, **foot-traffic monetization**, and **ambient commerce** without user interaction.
+
+---
+
+## 1. Scope & Responsibilities
+
+### What this service does
+
+| Area                 | Responsibility                               |
+| -------------------- | -------------------------------------------- |
+| Signal ingestion     | Receive Wi-Fi / Wi-Fi P2P / BLE scan data    |
+| Persistence          | Store scan events for analytics & replay     |
+| Proximity resolution | Match detected identifiers to vendors        |
+| Caching              | Maintain fast, short-lived proximity state   |
+| Web relay            | Serve nearby vendor inventory to web clients |
+
+### What this service does NOT do
+
+| Excluded           | Reason                               |
+| ------------------ | ------------------------------------ |
+| Vendor CRUD        | Handled by Vendor service            |
+| Inventory mutation | Read-only from proximity perspective |
+| Authentication     | Sensors are assumed trusted          |
+| Payments           | Out of scope                         |
+
+---
+
+## 2. Supported Proximity Technologies
+
+| Technology             | Status        | Purpose                  | Matching Key     |
+| ---------------------- | ------------- | ------------------------ | ---------------- |
+| **Wi-Fi**              | ✅ Implemented | Primary proximity signal | SSID             |
+| **Wi-Fi Direct (P2P)** | ✅ Implemented | Peer discovery, mesh     | SSID / Device ID |
+| **BLE**                | 🟡 Planned    | Ultra-low power beacons  | UUID / MAC       |
+
+---
+
+## 3. High-Level Architecture
+
+| Component               | Role                        |
+| ----------------------- | --------------------------- |
+| Native proximity device | Scans radio environment     |
+| Socket server           | Real-time ingestion         |
+| DeviceScan store        | Historical scan persistence |
+| Vendor store            | Known physical endpoints    |
+| Proximity cache         | Low-latency resolution      |
+| Web socket namespace    | Frontend notifications      |
+
+---
+
+## 4. Socket Namespaces
+
+### Namespace Overview
+
+| Namespace           | Client Type        | Purpose                          |
+| ------------------- | ------------------ | -------------------------------- |
+| `/proximity/native` | IoT / Edge devices | Send scan results                |
+| `/proximity/web`    | Browser clients    | Trigger & receive proximity data |
+
+---
+
+## 5. Socket Event Matrix
+
+### Server → Device
+
+| Event            | Frequency | Description             |
+| ---------------- | --------- | ----------------------- |
+| `start_scanning` | Every 4s  | Requests new scan cycle |
+
+---
+
+### Device → Server (Wi-Fi)
+
+| Event               | Payload            | Description         |
+| ------------------- | ------------------ | ------------------- |
+| `wifi::scan_result` | Wi-Fi scan payload | Standard Wi-Fi scan |
+
+---
+
+### Device → Server (Wi-Fi P2P)
+
+| Event                  | Payload          | Description           |
+| ---------------------- | ---------------- | --------------------- |
+| `wifip2p::scan_result` | P2P scan payload | Mesh / peer discovery |
+
+---
+
+### Web Client Events
+
+| Event                      | Direction    | Description              |
+| -------------------------- | ------------ | ------------------------ |
+| `PROXIMITY_SCAN::RUN_SCAN` | Web → Server | Trigger proximity lookup |
+| `PROXIMITY_SCAN`           | Server → Web | Return nearby vendors    |
+
+---
+
+## 6. REST API Surface
+
+### Endpoint Summary
+
+| Method | Endpoint                   | Purpose                |
+| ------ | -------------------------- | ---------------------- |
+| GET    | `/api/proximity/inventory` | Resolve nearby vendors |
+
+---
+
+### Identification Headers
+
+| Header         | Optional | Purpose                     |
+| -------------- | -------- | --------------------------- |
+| `x-device-sig` | Yes      | Persistent device signature |
+| `public_ip`    | Yes      | Network-level identity      |
+| `x-ws-token`   | Yes      | WebSocket fallback          |
+
+> The service automatically selects the **best available key**.
+
+---
+
+## 7. Proximity Resolution Flow
+
+| Step | Action                         |
+| ---- | ------------------------------ |
+| 1    | Device performs scan           |
+| 2    | Scan results sent via socket   |
+| 3    | Scan persisted to database     |
+| 4    | SSIDs / identifiers extracted  |
+| 5    | Vendors matched by identifiers |
+| 6    | Result cached                  |
+| 7    | Web client requests inventory  |
+| 8    | Cached vendors returned        |
+
+---
+
+## 8. Data Models
+
+### 8.1 Wi-Fi / Wi-Fi P2P Scan Payload
+
+| Field             | Type       | Required | Description          |
+| ----------------- | ---------- | -------- | -------------------- |
+| `device_id`       | string     | No       | Device identifier    |
+| `deviceSignature` | string     | No       | Persistent signature |
+| `public_ip`       | string     | No       | Network IP           |
+| `timestamp`       | ISO string | Yes      | Scan time            |
+| `scan_meta`       | object     | No       | Scan metadata        |
+| `detected_wifi`   | array      | Yes      | Detected networks    |
+
+---
+
+### 8.2 Detected Network
+
+| Field       | Type   | Description       |
+| ----------- | ------ | ----------------- |
+| `ssid`      | string | Network name      |
+| `rssi`      | number | Signal strength   |
+| `frequency` | number | Channel frequency |
+
+---
+
+### 8.3 BLE Scan Payload (Planned)
+
+| Field       | Type   | Description          |
+| ----------- | ------ | -------------------- |
+| `device_id` | string | BLE scanner          |
+| `beacons`   | array  | Detected BLE beacons |
+| `uuid`      | string | Beacon UUID          |
+| `major`     | number | Beacon major         |
+| `minor`     | number | Beacon minor         |
+| `rssi`      | number | Signal strength      |
+
+---
+
+## 9. Proximity Cache Structure
+
+| Key            | Description               |
+| -------------- | ------------------------- |
+| `ssids`        | Last detected identifiers |
+| `timestamp`    | Last scan time            |
+| `socketId`     | Active connection         |
+| `persistentId` | Device identity           |
+
+---
+
+## 10. Vendor Matching Logic
+
+| Signal Type | Matching Strategy                      |
+| ----------- | -------------------------------------- |
+| Wi-Fi       | SSID ∈ Vendor.SSID                     |
+| Wi-Fi P2P   | SSID ∈ Vendor.SSID                     |
+| BLE         | UUID ↔ Vendor beacon mapping (planned) |
+
+---
+
+## 11. Error Handling Matrix
+
+| Scenario          | Response           |
+| ----------------- | ------------------ |
+| Invalid payload   | Error ACK          |
+| Empty scan        | `stores_count = 0` |
+| No vendor match   | Valid empty result |
+| DB failure        | Error + logged     |
+| Socket disconnect | Scan loop stopped  |
+
+---
+
+## 12. Security Model
+
+| Aspect            | Current State   |
+| ----------------- | --------------- |
+| Authentication    | None            |
+| Authorization     | None            |
+| Trust model       | Device-based    |
+| Replay protection | Timestamp-based |
+| Rate limiting     | Not implemented |
+
+> Designed for **trusted edge devices**. Hardenable later.
+
+---
+
+## 13. Local Development
+
+### Requirements
+
+| Dependency | Version |
+| ---------- | ------- |
+| Node.js    | ≥ 18    |
+| MongoDB    | ≥ 5     |
+| Socket.IO  | v4      |
+
+---
+
+### Run Locally
+
+```bash
+npm install
+npm run dev
+```
+
+---
+
+## 14. Future Enhancements
+
+| Feature                  | Status  |
+| ------------------------ | ------- |
+| BLE beacon ingestion     | Planned |
+| Movement delta detection | Planned |
+| Confidence scoring       | Planned |
+| Multi-sensor fusion      | Planned |
+| Edge mesh propagation    | Planned |
+
+---
+
+## 15. Related Docs
+
+| Document       | Purpose                       |
+| -------------- | ----------------------------- |
+| `openapi.yaml` | REST API spec                 |
+| Vendor API     | Vendor & inventory management |
+| QA Matrix      | Test coverage                 |
+| SRS            | Functional requirements       |
+
+---
+
+## 16. Ownership
+
+**Proximity Platform – Sensor Layer**
+Built for **ambient, real-world intelligence**.

package/index.js

@@ -0,0 +1,143 @@
+import { DeviceScan } from "../models/DeviceScan.js";
+import { Vendor } from "../models/Vendor.js";
+import axios from "axios";
+
+
+
+export const initSocket = (io, proximityCache) => {
+  const nativeNamespace = io.of("/proximity/native");
+
+  nativeNamespace.on("connection", (socket) => {
+    const persistentId = socket.handshake.query.persistentId || socket.id;
+    console.log(`Proximity device connected: ${persistentId} (socket: ${socket.id})`);
+
+    // Send periodic scan requests
+    const scan = () => { console.log("[EMITTING SCAN REQUEST]"); socket.emit("start_scanning");}
+    const scanInterval = setInterval(scan, 4000);
+
+    // Receive scan result from proximity sensor
+    socket.on("wifi::scan_result", async (payload, ack) => {
+      try {
+        const { device_id, public_ip, detected_wifi, timestamp, scan_meta, deviceSignature } = payload;
+
+        // Choose best available unique key for device
+        const key = public_ip || deviceSignature || persistentId;
+
+        console.log(`[SCAN RESULT] From ${persistentId}:`, {
+          detected_wifi_count: detected_wifi?.length || 0,
+          ...payload
+        });
+
+        // Save scan data
+        await DeviceScan.create({
+          device_id,
+          public_ip,
+          detected_wifi,
+          timestamp,
+          scan_meta,
+        });
+
+        // Find nearby stores by SSID
+        const ssids = (detected_wifi || []).map((w) => w.ssid);
+        const stores = await Vendor.find({ ssid: { $in: ssids } }).lean();
+
+
+        // Check if that there's any changes between current datapoint and previous datapoints/
+        // Data points are dectected current and previous {stores, devicescans} value
+
+
+        if (ack) ack({ status: "ok", stores_count: stores.length });
+      } catch (e) {
+        console.error("scan_result error:", e);
+        if (ack) ack({ status: "error", error: e.message });
+      }
+    });
+
+
+    // === Receive Wi-Fi Direct scan results from nearby nodes ===
+    socket.on("wifip2p::scan_result", async (payload, ack) => {
+      console.log(payload)
+      try {
+        const {
+          device_id, public_ip, detected_wifi, timestamp, scan_meta, deviceSignature,
+        } = payload || {};
+
+        const key = public_ip || deviceSignature || persistentId;
+        const wifiCount = detected_wifi?.length || 0;
+
+        console.log(`📶 [SCAN RESULT] From ${device_id || "unknown"} →`, {
+          detected_wifi_count: wifiCount,
+          timestamp,
+          scan_meta,
+        });
+
+        // 🧠 Save scan data (to DB, file, or local storage)
+        await DeviceScan.create({
+          device_id,
+          public_ip,
+          detected_wifi,
+          timestamp,
+          scan_meta,
+        });
+
+        // 🏪 Identify known SSIDs linked to nearby “stores” or endpoints
+        const ssids = (detected_wifi || []).map((w) => w.ssid).filter(Boolean);
+        const stores = await Vendor.find({ ssid: { $in: ssids } }).lean();
+
+        // 🔒 Cache the device’s proximity data for rapid local queries
+        proximityCache[key] = {
+          ssids,
+          timestamp: Date.now(),
+          socketId: socket.id,
+          persistentId,
+        };
+
+        // ✅ Respond back to sender (ACK)
+        if (ack) ack({ status: "ok", stores_count: stores.length });
+
+        console.log(`✅ [Processed] ${wifiCount} networks, ${stores.length} matches.`);
+      } catch (e) {
+        console.error("❌ scan_result error:", e);
+        if (ack) ack({ status: "error", error: e.message });
+      }
+    });
+
+
+    socket.on("disconnect", () => {
+      console.log(`Device disconnected: ${persistentId} (socket: ${socket.id})`);
+      clearInterval(scanInterval);
+    });
+  });
+
+
+
+
+  const webNamespace = io.of("/proximity/web");
+
+  webNamespace.on("connection", socket => {
+    console.log("Server=>WebClient Socket Connted", socket.id)
+    socket.on("PROXIMITY_SCAN::RUN_SCAN", async(payload)=>{
+      try{
+        const res = await axios.get("http://10.48.59.128:5000/api/proximity/inventory", {
+           headers: {
+            "x-device-sig": payload.persistentId,
+            //public_ip: await fetchPublicIP(),
+          },
+        })
+        console.log(payload)
+        if(res.data.length > 0){
+          console.log("[EMITTING RESULT TO WEB]")
+          socket.emit("PROXIMITY_SCAN", {data:res.data});
+        }
+        else if(res.data.length == 0){
+          console.log("[EMITTING RESULT TO WEB]")
+          console.log(res.data);
+          //socket.emit("PROXIMITY_SCAN", {data:res.data});
+        }
+      }catch(e){
+        console.log(payload?.persistentId)
+      }
+    })
+  
+  })
+};

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@shyntech-proximity/sensor-app",
+  "version": "1.0.0",
+  "main": "index.js",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "@shyntech:registry": "https://gitlab.com/api/v4/projects/78157101/packages/npm/"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}