dolphin-server-modules 1.6.0 → 1.6.1

package/DOLPHIN_MASTER_GUIDE_NEPALI.md

@@ -850,7 +850,102 @@ await signaling.invite('user1', 'user2', { sdp: 'offer_data' });
 // 2. IoT / Medical Command
 await signaling.sendCommand('DoctorApp', 'Machine_01', { action: 'START' });
 
-निष्कर्ष (Conclusion)
+१८. Folder Structure र Architecture बेस्ट प्राक्टिस (Zero to Scale)
+एउटा ठूलो सङ्गठन वा IoT एप्लिकेसन डिजाइन गर्दा प्रोजेक्टलाई एउटै फाइलमा नराखी व्यवस्थित तरिकाले यसरी मिलाउनुपर्छ:
+
+```text
+my-dolphin-app/
+├── src/
+│   ├── config/              # Database, Redis जस्ता कन्फिगरेसन 
+│   ├── models/              # Mongoose/DB स्किमाहरू (Product.ts, SensorData.ts)
+│   ├── controllers/         # लजिक र CRUD ह्यान्डलर (UserCtrl.ts, IoT_Ctrl.ts)
+│   ├── middlewares/         # ZodValidation, AuthGuard, ErrorHandler
+│   ├── routes/              # apiRouter (Independent Routing)
+│   ├── realtime/            # IoT र WebSocket का इभेन्ट-ह्यान्डलर (pub/sub)
+│   ├── app.ts               # Dolphin Server र WebSockets (wss) को सेटअप
+│   └── index.ts             # सर्भर सुरु गर्ने (app.listen)
+├── package.json
+└── tsconfig.json
+```
+यो तरिका अपनाउँदा तपाइँको REST API र IoT को RealtimeCore कहिल्यै पनि नराम्रोसँग जेलिँदैन (Tight Coupling हुँदैन)।
+
+१९. Global Error Handling (सर्भर क्र्यास हुनबाट बचाउने)
+Dolphin मा तपाईंले लेखेको कुनै कस्टम लजिकले Error फाले पनि सर्भर क्र्यास हुनुहुँदैन। यसको लागि ग्लोबल मिडलवेयर (Global Middleware) प्रयोग गर्नुपर्छ:
+
+```typescript
+app.use(async (ctx, next) => {
+  try {
+    if (next) await next();
+  } catch (error) {
+    console.error("🔥 SYSTEM ERROR:", error.message);
+    // क्लाईन्टलाई नराम्रो HTML को सट्टा राम्रो JSON पठाउने
+    ctx.status(500).json({
+      success: false,
+      message: "Internal Server Error",
+      error: process.env.NODE_ENV !== 'production' ? error.stack : undefined
+    });
+  }
+});
+```
+
+२०. Frontend सँग जोड्ने (React & IoT WebSockets)
+फ्रन्टइन्ड (Frontend) बाट Dolphin API लाई कल गर्न तपाईंले सुरुमा CORS अन गर्नुपर्छ।
+
+CORS Setup:
+```typescript
+import cors from 'cors';
+app.use(cors({ origin: 'http://localhost:3000', credentials: true })); 
+```
+
+React बाट IoT WebSocket जोड्ने:
+```javascript
+import { useEffect, useState } from 'react';
+
+function Dashboard() {
+  const [temp, setTemp] = useState(0);
+
+  useEffect(() => {
+    // 1. Dolphin को WebSocket मा कनेक्ट गर्ने
+    const ws = new WebSocket('ws://localhost:8080?id=React_Dashboard&type=monitor');
+    
+    ws.onmessage = (event) => {
+      const parsed = JSON.parse(event.data);
+      if(parsed.topic === 'sensors/temperature') {
+         setTemp(parsed.payload.value);
+      }
+    };
+    
+    // 2. Dolphin लाई कुन टपिक सुन्ने भनेर Subscribe मेसेज पठाउने
+    ws.onopen = () => {
+       ws.send(JSON.stringify({ action: 'subscribe', topic: 'sensors/temperature' }));
+    };
+    
+    return () => ws.close();
+  }, []);
+
+  return <div><h1>लाइभ तापक्रम: {temp} °C 🌡️</h1></div>;
+}
+```
+
+२१. Production Deployment (सर्भर लाइभ गर्ने)
+तपाईँको Dolphin सर्भर रकेट जस्तै तयार छ। अब यसलाई लाइभ (World Wide Web) मा राख्न PM2 प्रयोग गरिन्छ जसले क्र्यास भएको खण्डमा तुरुन्त (0.1ms) सर्भरलाई अटो-रिस्टार्ट (Auto-Restart) गर्छ।
+
+PM2 इन्स्टल र सुरु गर्न:
+```bash
+# 1. PM2 लाई Global रूपमा राख्ने
+npm install -g pm2
+
+# 2. तपाईंको Code लाई Build गर्ने
+npm run build
+
+# 3. PM2 द्वारा Background मा सर्भर सुरु गर्ने
+pm2 start dist/index.js --name "dolphin-iot-backend"
+
+# 4. सर्भरका Logs (Error/Info) हेर्न
+pm2 logs dolphin-iot-backend
+```
+
+२२. निष्कर्ष (Conclusion)
 बधाई छ! तपाईँले Dolphin Framework v2.0 को Master Guide पूरा गर्नुभयो। अब तपाईँ:
 
 ✅ हाई-पर्फर्मेन्स API सर्भर बनाउन

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './realtime/codec';
 export * from './realtime/index';
 export * from './swagger/swagger';
+export * from './signaling/index';

package/dist/index.js

@@ -17,4 +17,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./realtime/codec"), exports);
 __exportStar(require("./realtime/index"), exports);
 __exportStar(require("./swagger/swagger"), exports);
+__exportStar(require("./signaling/index"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AACA,mDAAiC;AACjC,mDAAiC;AACjC,oDAAkC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AACA,mDAAiC;AACjC,mDAAiC;AACjC,oDAAkC;AAClC,oDAAkC"}

package/dist/signaling/index.d.ts

@@ -0,0 +1,47 @@
+import { RealtimeCore } from '../realtime/core';
+export declare enum SignalType {
+    INVITE = "INVITE",
+    ACCEPT = "ACCEPT",
+    REJECT = "REJECT",
+    END = "END",
+    ICE_CANDIDATE = "ICE_CANDIDATE",
+    COMMAND = "COMMAND",
+    COMMAND_ACK = "COMMAND_ACK",
+    TELEMETRY = "TELEMETRY",
+    ACK = "ACK"
+}
+export interface SignalingPayload {
+    msgId: string;
+    from: string;
+    to: string;
+    type: SignalType | string;
+    data?: any;
+    timestamp: number;
+}
+export type SignalHandler = (payload: SignalingPayload) => void;
+export declare class UniversalSignaling {
+    private rt;
+    private pendingAcks;
+    constructor(rt: RealtimeCore);
+    /**
+     * Internal mechanism to send a signal directly to the device.
+     */
+    private sendRaw;
+    /**
+     * Used to acknowledge a signal natively
+     */
+    handleAck(msgId: string): void;
+    ack(from: string, to: string, msgIdToAck: string): void;
+    invite(from: string, to: string, data?: any): Promise<boolean>;
+    accept(from: string, to: string, sdp?: any): Promise<boolean>;
+    reject(from: string, to: string, reason?: string): Promise<boolean>;
+    end(from: string, to: string, reason?: string): Promise<boolean>;
+    iceCandidate(from: string, to: string, candidate: any): Promise<boolean>;
+    sendCommand(from: string, to: string, commandData: any, requireAck?: boolean): Promise<boolean>;
+    sendTelemetry(from: string, to: string | 'all', telemetryData: any): Promise<void>;
+    /**
+     * Listen to any incoming signals for a particular topic or private channel
+     */
+    onSignalFor(deviceId: string, handler: SignalHandler): void;
+}
+export declare function createSignaling(rt: RealtimeCore): UniversalSignaling;

package/dist/signaling/index.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UniversalSignaling = exports.SignalType = void 0;
+exports.createSignaling = createSignaling;
+var SignalType;
+(function (SignalType) {
+    // Connection / WebRTC
+    SignalType["INVITE"] = "INVITE";
+    SignalType["ACCEPT"] = "ACCEPT";
+    SignalType["REJECT"] = "REJECT";
+    SignalType["END"] = "END";
+    SignalType["ICE_CANDIDATE"] = "ICE_CANDIDATE";
+    // Custom Data / Control
+    SignalType["COMMAND"] = "COMMAND";
+    SignalType["COMMAND_ACK"] = "COMMAND_ACK";
+    SignalType["TELEMETRY"] = "TELEMETRY";
+    // General Acknowledgements
+    SignalType["ACK"] = "ACK";
+})(SignalType || (exports.SignalType = SignalType = {}));
+class UniversalSignaling {
+    rt;
+    pendingAcks = new Map();
+    constructor(rt) {
+        this.rt = rt;
+    }
+    /**
+     * Internal mechanism to send a signal directly to the device.
+     */
+    async sendRaw(to, type, data, from, requireAck = false, timeoutMs = 3000) {
+        const msgId = `sig_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+        const payload = {
+            msgId,
+            from,
+            to,
+            type,
+            data,
+            timestamp: Date.now()
+        };
+        if (requireAck) {
+            return new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    this.pendingAcks.delete(msgId);
+                    resolve(false);
+                }, timeoutMs);
+                this.pendingAcks.set(msgId, { resolve, timer });
+                // Use RealtimeCore's privatePub channel
+                this.rt.privatePub(to, payload);
+            });
+        }
+        else {
+            this.rt.privatePub(to, payload);
+            return true;
+        }
+    }
+    /**
+     * Used to acknowledge a signal natively
+     */
+    handleAck(msgId) {
+        const pending = this.pendingAcks.get(msgId);
+        if (pending) {
+            clearTimeout(pending.timer);
+            pending.resolve(true);
+            this.pendingAcks.delete(msgId);
+        }
+    }
+    ack(from, to, msgIdToAck) {
+        this.rt.privatePub(to, {
+            msgId: `sig_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`,
+            type: SignalType.ACK,
+            from,
+            to,
+            data: { ackId: msgIdToAck },
+            timestamp: Date.now()
+        });
+    }
+    // --- WebRTC / Session Methods ---
+    async invite(from, to, data) {
+        return this.sendRaw(to, SignalType.INVITE, data, from, true);
+    }
+    async accept(from, to, sdp) {
+        return this.sendRaw(to, SignalType.ACCEPT, sdp, from);
+    }
+    async reject(from, to, reason) {
+        return this.sendRaw(to, SignalType.REJECT, { reason }, from);
+    }
+    async end(from, to, reason) {
+        return this.sendRaw(to, SignalType.END, { reason }, from);
+    }
+    async iceCandidate(from, to, candidate) {
+        return this.sendRaw(to, SignalType.ICE_CANDIDATE, candidate, from);
+    }
+    // --- Industrial / Medical Control Methods ---
+    async sendCommand(from, to, commandData, requireAck = true) {
+        return this.sendRaw(to, SignalType.COMMAND, commandData, from, requireAck);
+    }
+    async sendTelemetry(from, to, telemetryData) {
+        const payload = {
+            msgId: `tel_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`,
+            from,
+            to,
+            type: SignalType.TELEMETRY,
+            data: telemetryData,
+            timestamp: Date.now()
+        };
+        if (to === 'all') {
+            this.rt.publish(`telemetry/broadcast`, payload);
+        }
+        else {
+            this.rt.privatePub(to, payload);
+        }
+    }
+    /**
+     * Listen to any incoming signals for a particular topic or private channel
+     */
+    onSignalFor(deviceId, handler) {
+        this.rt.subscribe(`phone/signaling/${deviceId}`, (payload) => {
+            // Auto-handle native ACK processing
+            if (payload.type === SignalType.ACK && payload.data?.ackId) {
+                this.handleAck(payload.data.ackId);
+            }
+            handler(payload);
+        }, deviceId);
+    }
+}
+exports.UniversalSignaling = UniversalSignaling;
+function createSignaling(rt) {
+    return new UniversalSignaling(rt);
+}
+//# sourceMappingURL=index.js.map

package/dist/signaling/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../signaling/index.ts"],"names":[],"mappings":";;;AAwJA,0CAEC;AAxJD,IAAY,UAeX;AAfD,WAAY,UAAU;IACpB,sBAAsB;IACtB,+BAAiB,CAAA;IACjB,+BAAiB,CAAA;IACjB,+BAAiB,CAAA;IACjB,yBAAW,CAAA;IACX,6CAA+B,CAAA;IAE/B,wBAAwB;IACxB,iCAAmB,CAAA;IACnB,yCAA2B,CAAA;IAC3B,qCAAuB,CAAA;IAEvB,2BAA2B;IAC3B,yBAAW,CAAA;AACb,CAAC,EAfW,UAAU,0BAAV,UAAU,QAerB;AAaD,MAAa,kBAAkB;IACrB,EAAE,CAAe;IACjB,WAAW,GAAG,IAAI,GAAG,EAAoE,CAAC;IAElG,YAAY,EAAgB;QAC1B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,OAAO,CAAC,EAAU,EAAE,IAAY,EAAE,IAAS,EAAE,IAAY,EAAE,aAAsB,KAAK,EAAE,YAAoB,IAAI;QAC5H,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QAChF,MAAM,OAAO,GAAqB;YAChC,KAAK;YACL,IAAI;YACJ,EAAE;YACF,IAAI;YACJ,IAAI;YACJ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC;QAEF,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;gBACtC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;oBAC5B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBAC/B,OAAO,CAAC,KAAK,CAAC,CAAC;gBACjB,CAAC,EAAE,SAAS,CAAC,CAAC;gBAEd,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;gBAEhD,wCAAwC;gBACxC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;YAClC,CAAC,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;YAChC,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACI,SAAS,CAAC,KAAa;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,OAAO,EAAE,CAAC;YACZ,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC5B,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACtB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAEM,GAAG,CAAC,IAAY,EAAE,EAAU,EAAE,UAAkB;QACrD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE;YACrB,KAAK,EAAE,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;YACxE,IAAI,EAAE,UAAU,CAAC,GAAG;YACpB,IAAI;YACJ,EAAE;YACF,IAAI,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE;YAC3B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC,CAAC;IACL,CAAC;IAED,mCAAmC;IAE5B,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,EAAU,EAAE,IAAU;QACtD,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/D,CAAC;IAEM,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,EAAU,EAAE,GAAS;QACrD,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IACxD,CAAC;IAEM,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,EAAU,EAAE,MAAe;QAC3D,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,UAAU,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,CAAC;IAC/D,CAAC;IAEM,KAAK,CAAC,GAAG,CAAC,IAAY,EAAE,EAAU,EAAE,MAAe;QACxD,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,UAAU,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,CAAC;IAC5D,CAAC;IAEM,KAAK,CAAC,YAAY,CAAC,IAAY,EAAE,EAAU,EAAE,SAAc;QAChE,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,UAAU,CAAC,aAAa,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IACrE,CAAC;IAED,+CAA+C;IAExC,KAAK,CAAC,WAAW,CAAC,IAAY,EAAE,EAAU,EAAE,WAAgB,EAAE,aAAsB,IAAI;QAC7F,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IAC7E,CAAC;IAEM,KAAK,CAAC,aAAa,CAAC,IAAY,EAAE,EAAkB,EAAE,aAAkB;QAC7E,MAAM,OAAO,GAAG;YACd,KAAK,EAAE,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;YACxE,IAAI;YACJ,EAAE;YACF,IAAI,EAAE,UAAU,CAAC,SAAS;YAC1B,IAAI,EAAE,aAAa;YACnB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC;QAEF,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;YACjB,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;QAClD,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED;;OAEG;IACI,WAAW,CAAC,QAAgB,EAAE,OAAsB;QACzD,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,mBAAmB,QAAQ,EAAE,EAAE,CAAC,OAAY,EAAE,EAAE;YAChE,oCAAoC;YACpC,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,CAAC,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;gBAC3D,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrC,CAAC;YACD,OAAO,CAAC,OAA2B,CAAC,CAAC;QACvC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACf,CAAC;CACF;AAxHD,gDAwHC;AAED,SAAgB,eAAe,CAAC,EAAgB;IAC9C,OAAO,IAAI,kBAAkB,CAAC,EAAE,CAAC,CAAC;AACpC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dolphin-server-modules",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "homepage": "https://github.com/Phuyalshankar/dolphin-server-modules#readme",
   "description": "Core utility modules for Auth, CRUD, and Controllers",
   "main": "dist/index.js",