@phystack/hub-client 4.5.19-dev → 4.5.20-dev

package/src/index.ts

@@ -7,91 +7,28 @@ import {
   EdgeTwinResponse,
   EdgeTwinDesiredPropertiesResponse,
   PeripheralTwinResponse,
-  TwinTypeEnum,
   Instance,
   PeripheralInstance,
+  IPeripheralTwinInstance,
+  TwinMessageResult,
+  TwinMessageResultStatus,
 } from './types/twin.types';
-import {
-  PhygridDataChannel,
-  PhygridMediaStream,
-  WebRTCConnectionOptions,
-} from './types/webrtc.types';
 import { PhyHubConnection } from './services/phyhub-connection.service';
+import { PhyHubDirectConnection } from './services/phyhub-direct-connection.service';
 import { SignalsService } from './services/signals.service';
 import { DataRequestTypeEnum, InitSignalPayload } from './types/signal.types';
 import {
-  createWebRTCDataChannelConnection,
-  WebRTCDataChannelResult,
-} from './services/webrtc/datachannel';
-import {
-  createWebRTCMediaStreamConnection,
-  WebRTCMediaStreamResult,
-} from './services/webrtc/mediastream';
-// import { createWebRTCMediaStreamConnection, WebRTCMediaStreamResult } from './helpers/webrtc-mediastream';
-
-// Define WebRTC types that might not be available in all environments
-declare global {
-  // In browsers, these are standard WebRTC interfaces
-  // In Node.js, we polyfill them from @roamhq/wrtc
-  interface Window {
-    RTCVideoSource?: any;
-  }
-
-  namespace NodeJS {
-    interface Global {
-      MediaStream?: any;
-      RTCPeerConnection?: any;
-      RTCSessionDescription?: any;
-      RTCIceCandidate?: any;
-      RTCVideoSource?: any;
-    }
-  }
-
-  // Make RTCVideoSource available in function scope when used
-  var RTCVideoSource: any;
-}
-
-(async function initializeWebRTCGlobals() {
-  // Only run in Node environment
-  if (typeof window !== 'undefined') return;
-
-  try {
-    // Dynamically import wrtc
-    const wrtc = require('@roamhq/wrtc');
-
-    // Set all WebRTC globals
-    if (typeof global.MediaStream === 'undefined' && wrtc.MediaStream) {
-      global.MediaStream = wrtc.MediaStream;
-      console.log('Global MediaStream initialized');
-    }
-
-    if (typeof global.RTCPeerConnection === 'undefined' && wrtc.RTCPeerConnection) {
-      global.RTCPeerConnection = wrtc.RTCPeerConnection;
-      console.log('Global RTCPeerConnection initialized');
-    }
-
-    if (typeof global.RTCSessionDescription === 'undefined' && wrtc.RTCSessionDescription) {
-      global.RTCSessionDescription = wrtc.RTCSessionDescription;
-      console.log('Global RTCSessionDescription initialized');
-    }
-
-    if (typeof global.RTCIceCandidate === 'undefined' && wrtc.RTCIceCandidate) {
-      global.RTCIceCandidate = wrtc.RTCIceCandidate;
-      console.log('Global RTCIceCandidate initialized');
-    }
-
-    if (typeof (global as any).RTCVideoSource === 'undefined' && wrtc.nonstandard.RTCVideoSource) {
-      (global as any).RTCVideoSource = wrtc.nonstandard.RTCVideoSource;
-      console.log('Global RTCVideoSource initialized');
-    }
-
-    console.log('WebRTC globals successfully initialized');
-  } catch (error) {
-    console.error('Failed to initialize WebRTC globals:', error);
-  }
-})().catch(err => console.error('Error in WebRTC globals initialization:', err));
+  WebRTCManager,
+  TwinMessagingInterface,
+  PhygridDataChannel,
+  PhygridMediaStream,
+  WebRTCManagerOptions,
+  MediaStreamOptions,
+} from './services/webrtc';
+import { TwinRegistry } from './twin-registry';
+import { createTwinMessaging } from './twin-messaging';
 
-interface EventPayload<T = any> {
+export interface EventPayload<T = any> {
   twinId?: string;
   sourceTwinId?: string;
   sourceDeviceId?: string;
@@ -115,8 +52,9 @@ export class PhyHubClient {
   private subscribedTwins: Set<string> = new Set();
   private twinMessageListeners: { [key: string]: Set<(message: any) => void> } = {};
   private instances: Map<string, Instance> = new Map();
-  private peripheralInstances: Map<string, PeripheralInstance> = new Map();
   private twinUpdateListeners: { [key: string]: Set<(twin: TwinResponse) => void> } = {};
+  private twinInstancesRegistry: TwinRegistry | null = null;
+  private webrtcManager: WebRTCManager | null = null;
 
   private readonly EVENTS = {
     PING: 'ping',
@@ -205,6 +143,11 @@ export class PhyHubClient {
         }
       );
 
+      // In direct connection mode, fetch our device twin to get the actual twinId (ObjectId)
+      if (PhyHubDirectConnection.isEnabled()) {
+        await this.initializeDirectConnectionTwin();
+      }
+
       return this;
     } catch (err) {
       this.socket = null;
@@ -262,32 +205,31 @@ export class PhyHubClient {
       this.socketConnected = false;
     });
 
-    this.socket.on(this.EVENTS.TWIN_MESSAGE, (payload: EventPayload) => {
-      // console.log('Received TWIN_MESSAGE payload:', {
-      //   JSON: JSON.stringify(payload, null, 2),
-      // });
+    this.socket.on(this.EVENTS.TWIN_MESSAGE, (payload: EventPayload, callback?: (response: TwinMessageResult | null) => void) => {
+      let result: TwinMessageResult | null = null;
 
       if (payload.twinId && payload.data) {
-        // console.log('Received TWIN_MESSAGE event:', {
-        //   hasListeners: !!this.twinMessageListeners[payload.twinId],
-        //   listenerCount: this.twinMessageListeners[payload.twinId]?.size
-        // });
+        // Look up listeners by twinId (the target of the message)
+        // This is the original pre-PR-144 approach
         const listeners = this.twinMessageListeners[payload.twinId];
-        if (listeners) {
-          // console.log(`Executing ${listeners.size} listeners for twin ${payload.twinId}`);
-          listeners.forEach(callback => {
-            // console.log('Executing listener for twin:', callback);
+
+        if (listeners?.size) {
+          listeners.forEach(listener => {
             try {
-              callback(payload);
+              listener(payload);
+              result = { status: TwinMessageResultStatus.Success, message: 'Action completed' };
             } catch (error) {
-              console.error(`Error in twin message listener for ${payload.twinId}:`, error);
+              console.error(`[TWIN_MESSAGE] Error in listener for ${payload.twinId}:`, error);
+              result = { status: TwinMessageResultStatus.Error, message: (error as Error)?.message || 'An error occurred' };
             }
           });
         } else {
-          // console.log(`No listeners found for twin ${payload.twinId}`, JSON.stringify(payload, null, 2));
+          result = { status: TwinMessageResultStatus.Warning, message: `No listeners found for twin ${payload.twinId}` };
+        }
+
+        if (callback) {
+          callback(result);
         }
-      } else {
-        // console.log('Invalid twin message payload:', payload);
       }
     });
 
@@ -336,6 +278,10 @@ export class PhyHubClient {
     if (!PhyHubClient.instance) {
       PhyHubClient.instance = new PhyHubClient(params);
       await PhyHubClient.instance.initializeConnection();
+
+      // create twin registry to store instances
+      PhyHubClient.instance.twinInstancesRegistry = new TwinRegistry(PhyHubClient.instance);
+
       console.info(`connect(): Connection to phyhub initialized`);
     }
     return PhyHubClient.instance;
@@ -445,88 +391,109 @@ export class PhyHubClient {
     });
   }
 
-  public getDataChannel = async (targetTwinId: string): Promise<PhygridDataChannel> => {
-    const options: WebRTCConnectionOptions = {
-      targetTwinId,
-      sendTwinMessage: this.sendTwinMessage.bind(this),
-      subscribeTwin: this.subscribeTwin.bind(this),
-      onTwinMessage: this.onTwinMessage.bind(this),
-      offTwinMessage: this.offTwinMessage.bind(this),
-      useStun: true,
-      isInitiator: true,
-      channelPrefix: 'channel',
-      mediaOptions: { isMediaConnection: false },
-    };
-
-    const result = (await createWebRTCDataChannelConnection(options)) as WebRTCDataChannelResult;
-    return result.dataChannel;
+  /**
+   * Get a DataChannel connection to a target twin.
+   * Initiates a WebRTC DataChannel connection for peer-to-peer messaging.
+   * @param targetTwinId - The twin ID to connect to
+   * @param channelName - Optional channel name for multiple channels to same peer (default: 'default')
+   */
+  public getDataChannel = async (targetTwinId: string, channelName?: string): Promise<PhygridDataChannel> => {
+    const manager = await this.getWebRTCManager();
+    return manager.createDataChannel(targetTwinId, channelName);
   };
 
+  /**
+   * Listen for an incoming DataChannel from a specific twin.
+   * Call this when you expect another twin to initiate a connection.
+   * @param sourceTwinId - The twin ID that will initiate the connection
+   * @param callback - Called when the channel is established
+   * @param channelName - Optional channel name for multiple channels (default: 'default')
+   */
   public onDataChannel = async (
     sourceTwinId: string,
-    callback: (dc: PhygridDataChannel) => void
-  ) => {
-    const options: WebRTCConnectionOptions = {
-      targetTwinId: sourceTwinId,
-      sendTwinMessage: this.sendTwinMessage.bind(this),
-      subscribeTwin: this.subscribeTwin.bind(this),
-      onTwinMessage: this.onTwinMessage.bind(this),
-      offTwinMessage: this.offTwinMessage.bind(this),
-      useStun: true,
-      isInitiator: false,
-      channelPrefix: 'channel',
-      mediaOptions: { isMediaConnection: false },
-    };
-
-    const result = (await createWebRTCDataChannelConnection(options)) as WebRTCDataChannelResult;
-    callback(result.dataChannel);
+    callback: (dc: PhygridDataChannel) => void,
+    channelName?: string
+  ): Promise<void> => {
+    const manager = await this.getWebRTCManager();
+    const channel = await manager.acceptDataChannel(sourceTwinId, channelName);
+    callback(channel);
   };
 
-  public async getMediaStream(targetTwinId: string): Promise<{
+  /**
+   * Get a MediaStream connection to a target twin.
+   * Initiates a WebRTC MediaStream connection for peer-to-peer media.
+   * @param targetTwinId - The twin ID to connect to
+   * @param options - Optional MediaStream options (including channelName for multiple streams)
+   */
+  public async getMediaStream(
+    targetTwinId: string,
+    options?: MediaStreamOptions
+  ): Promise<{
     stream: PhygridMediaStream;
     close: () => void;
   }> {
-    const options: WebRTCConnectionOptions = {
-      targetTwinId,
-      sendTwinMessage: this.sendTwinMessage.bind(this),
-      subscribeTwin: this.subscribeTwin.bind(this),
-      onTwinMessage: this.onTwinMessage.bind(this),
-      offTwinMessage: this.offTwinMessage.bind(this),
-      isInitiator: true,
-      channelPrefix: 'media',
-      mediaOptions: {
-        isMediaConnection: true,
-        mediaDirection: 'recvonly',
-      },
-    };
-    const result: WebRTCMediaStreamResult = await createWebRTCMediaStreamConnection(options);
+    const manager = await this.getWebRTCManager();
+    const channelName = options?.channelName ?? 'default';
+    const stream = await manager.createMediaStream(targetTwinId, options, channelName);
     return {
-      stream: result.mediaStream,
-      close: result.close,
+      stream,
+      close: () => stream.close(),
     };
   }
 
+  /**
+   * Listen for an incoming MediaStream from a specific twin.
+   * Call this when you expect another twin to initiate a media connection.
+   * @param sourceTwinId - The twin ID that will initiate the connection
+   * @param callback - Callback when stream is received
+   * @param options - Optional MediaStream options (including channelName for multiple streams)
+   */
   public onMediaStream = async (
     sourceTwinId: string,
-    callback: (stream: PhygridMediaStream) => void
+    callback: (stream: PhygridMediaStream) => void,
+    options?: MediaStreamOptions
   ): Promise<void> => {
-    const options: WebRTCConnectionOptions = {
-      targetTwinId: sourceTwinId,
-      sendTwinMessage: this.sendTwinMessage.bind(this),
-      subscribeTwin: this.subscribeTwin.bind(this),
-      onTwinMessage: this.onTwinMessage.bind(this),
-      offTwinMessage: this.offTwinMessage.bind(this),
-      isInitiator: false,
-      channelPrefix: 'media',
-      mediaOptions: {
-        isMediaConnection: true,
-      },
-    };
-
-    const result: WebRTCMediaStreamResult = await createWebRTCMediaStreamConnection(options);
-    callback(result.mediaStream);
+    const manager = await this.getWebRTCManager();
+    const channelName = options?.channelName ?? 'default';
+    const stream = await manager.acceptMediaStream(sourceTwinId, options, channelName);
+    callback(stream);
   };
 
+  /**
+   * Get the WebRTCManager for advanced control over WebRTC connections.
+   * Provides access to events, connection state, and more.
+   */
+  public async getWebRTCManager(options?: WebRTCManagerOptions): Promise<WebRTCManager> {
+    if (!this.webrtcManager) {
+      await this.assureSocketConnection();
+
+      // Create TwinMessagingInterface adapter
+      const twinMessaging: TwinMessagingInterface = {
+        sendMessage: async (targetTwinId: string, data: any) => {
+          await this.sendTwinMessage(targetTwinId, data);
+        },
+        subscribe: async (twinId: string) => {
+          await this.subscribeTwin(twinId);
+        },
+        onMessage: (twinId: string, callback: (msg: any) => void) => {
+          this.onTwinMessage(twinId, callback);
+        },
+        offMessage: (twinId: string, callback: (msg: any) => void) => {
+          this.offTwinMessage(twinId, callback);
+        },
+        getOwnTwinId: () => {
+          if (!this.instanceId) {
+            throw new Error('Instance ID not set');
+          }
+          return this.instanceId;
+        },
+      };
+
+      this.webrtcManager = new WebRTCManager(twinMessaging, options);
+    }
+    return this.webrtcManager;
+  }
+
   // TODO properties should automatically be updated when the edge twin is updated
   // We could do a refresh method and call that on reconnect like we handle the resubscribes for peripherals
   public async getInstance(): Promise<Instance> {
@@ -543,50 +510,14 @@ export class PhyHubClient {
     let instance: Instance | undefined;
 
     let instanceTwin = await this.getTwinById(this.instanceId);
-    // console.log('getTwinById response', instanceTwin);
-
-    const edgeInstanceTypePrefix = 'edgeInstance';
-
-    const edgeTwinEmit = (type: string, payload: any) => {
-      // console.log('edgeTwinEmit', type, payload);
-      const { id: twinId } = instanceTwin;
-      const edgeTwinMessagePayload = {
-        type: `${edgeInstanceTypePrefix}:${type}`,
-        sourceTwinId: twinId,
-        sourceDeviceId: instanceTwin.deviceId,
-        data: payload,
-      };
-      // console.log('edgeTwinEmit', edgeTwinMessagePayload);
-      this.sendTwinMessage(twinId, edgeTwinMessagePayload);
-    };
-
-    const edgeTwinOn = (type: string, callback: (message: any) => void) => {
-      const { id: twinId } = instanceTwin;
-      const onEdgeTwinMessage = (payload: any) => {
-        // console.log('onEdgeTwinMessage callback', payload);
-        const messageType = payload.data?.type || payload.type;
-        if (messageType === `${edgeInstanceTypePrefix}:${type}`) {
-          // console.log('onEdgeTwinMessage', payload.data?.data || payload.data);
-          callback(payload.data?.data || payload.data);
-        } else {
-          // console.log('onEdgeTwinMessage', 'ignoring', messageType);
-        }
-      };
-      this.onTwinMessage(twinId, onEdgeTwinMessage);
-    };
 
-    const edgeTwinTo = (targetTwinId: string) => ({
-      emit: (type: string, payload: any) => {
-        // console.log('edgeTwinEmit', type, payload);
-        const edgeTwinMessagePayload = {
-          type: `${edgeInstanceTypePrefix}:${type}`,
-          sourceTwinId: instanceTwin.id,
-          sourceDeviceId: instanceTwin.deviceId,
-          data: payload,
-        };
-        // console.log('edgeTwinEmit', edgeTwinMessagePayload);
-        this.sendTwinMessage(targetTwinId, edgeTwinMessagePayload);
-      },
+    // Create messaging methods using the shared factory
+    const messaging = createTwinMessaging({
+      sendEvent: (targetTwinId, payload) => this.sendEvent(targetTwinId, payload),
+      onTwinMessage: (twinId, callback) => this.onTwinMessage(twinId, callback),
+      twinId: instanceTwin.id,
+      deviceId: instanceTwin.deviceId,
+      typePrefix: 'edgeInstance',
     });
 
     const getPeripheralTwins = async (): Promise<PeripheralTwinResponse[]> => {
@@ -648,27 +579,26 @@ export class PhyHubClient {
       });
     };
 
-    const getDataChannel = async () => {
-      return await this.getDataChannel(instanceTwin.id);
+    const getDataChannel = async (channelName?: string) => {
+      return await this.getDataChannel(instanceTwin.id, channelName);
     };
 
-    const onDataChannel = async (callback: (dc: PhygridDataChannel) => void) => {
-      return await this.onDataChannel(instanceTwin.id, callback);
+    const onDataChannel = async (callback: (dc: PhygridDataChannel) => void, channelName?: string) => {
+      return await this.onDataChannel(instanceTwin.id, callback, channelName);
     };
 
-    const getMediaStream = async () => {
+    const getMediaStream = async (channelName?: string) => {
       if (!instance) {
         throw new Error('Instance not initialized');
       }
-      return await this.getMediaStream(instance.id);
+      return await this.getMediaStream(instance.id, { channelName });
     };
 
-    const onMediaStream = async (callback: (stream: PhygridMediaStream) => void): Promise<void> => {
+    const onMediaStream = async (callback: (stream: PhygridMediaStream) => void, channelName?: string): Promise<void> => {
       if (!instance) {
         throw new Error('Instance not initialized');
       }
-      await this.onMediaStream(instance.id, callback);
-      // Return void to match the expected return type
+      await this.onMediaStream(instance.id, callback, { channelName });
     };
 
     const updateReported = async (properties: Record<string, any>) => {
@@ -682,9 +612,9 @@ export class PhyHubClient {
 
     instance = {
       ...instanceTwin,
-      emit: edgeTwinEmit,
-      on: edgeTwinOn,
-      to: edgeTwinTo,
+      emit: messaging.emit,
+      on: messaging.on,
+      to: messaging.to,
       createPeripheralTwin,
       updateReported,
       getPeripheralTwins,
@@ -707,303 +637,15 @@ export class PhyHubClient {
   }
 
   // TODO properties should automatically be updated when the edge twin is updated
-  public async getPeripheralInstance(peripheralTwinId: string): Promise<PeripheralInstance> {
-    if (this.peripheralInstances.has(peripheralTwinId)) {
-      return this.peripheralInstances.get(peripheralTwinId)!;
+  /**
+   * provides instance of PeripheralTwinInstance class
+  */
+  public async getPeripheralInstance(peripheralTwinId: string): Promise<IPeripheralTwinInstance | null> {
+    if (!this.twinInstancesRegistry) {
+      throw new Error('PhyHubClient instance is not initialized yet');
     }
-    // console.log(`Getting peripheral instance for twin ID: ${peripheralTwinId}`);
-    let peripheralInstance: PeripheralInstance | undefined;
-    const edgeInstance = await this.getInstance();
-    if (!edgeInstance) {
-      console.error('Edge instance not found');
-      throw new Error('Edge instance not found');
-    }
-
-    // console.log('getting peripheral twin', peripheralTwinId);
-
-    const peripheralTwin = await this.getTwinById(peripheralTwinId);
-    // console.log('peripheralTwinp', peripheralTwin);
-    if (!peripheralTwin) {
-      console.error(`Peripheral twin with id ${peripheralTwinId} not found`);
-      throw new Error(`Peripheral twin with id ${peripheralTwinId} not found`);
-    }
-
-    if (peripheralTwin.type !== TwinTypeEnum.Peripheral) {
-      throw new Error(`Twin ${peripheralTwinId} is not a peripheral twin`);
-    }
-
-    // Auto-subscribe if peripheral belongs to a different device
-    // if (peripheralTwin.deviceId !== edgeInstance.deviceId) {
-    // console.log('Auto-subscribing to peripheral twin', peripheralTwinId);
-    // const response =
-    await this.subscribeTwin(peripheralTwinId);
-    // console.log('subscribeTwin response', response);
-    // }
-
-    const instanceTypePrefix = 'peripheralInstance';
-
-    const peripheralTwinEmit = (type: string, payload: any) => {
-      // console.log(`Peripheral ${peripheralTwinId} emitting event:`, {
-      //   type,
-      //   payload
-      // });
-
-      const messagePayload = {
-        type: `${instanceTypePrefix}:${peripheralTwin.id}:${type}`,
-        sourceTwinId: peripheralTwin.id,
-        sourceDeviceId: edgeInstance.deviceId,
-        data: payload,
-      };
-
-      // console.log('Sending twin message:', JSON.stringify(messagePayload, null, 2));
-      this.sendTwinMessage(peripheralTwin.id, messagePayload);
-    };
-
-    const peripheralTwinOn = (type: string, callback: (message: any) => void) => {
-      console.log(`Setting up listener for peripheral ${peripheralTwinId} event: ${type}`);
-
-      const onMessage = (payload: any) => {
-        // console.log(`Received message for peripheral ${peripheralTwinId}:`, payload);
-        const messageType = payload.data?.type || payload.type;
-        if (messageType === `${instanceTypePrefix}:${peripheralTwin.id}:${type}`) {
-          // console.log('Processing matching message type');
-          callback(payload.data?.data || payload.data);
-        } else {
-          // console.log('Ignoring non-matching message type:', messageType);
-        }
-      };
-
-      this.onTwinMessage(peripheralTwin.id, onMessage);
-    };
-
-    const peripheralTwinTo = (targetTwinId: string) => ({
-      emit: (type: string, payload: any) => {
-        const messagePayload = {
-          type: `${instanceTypePrefix}:${peripheralTwin.id}:${type}`,
-          sourceTwinId: edgeInstance.id,
-          sourceDeviceId: edgeInstance.deviceId,
-          data: payload,
-        };
-        this.sendTwinMessage(targetTwinId, messagePayload);
-      },
-    });
-
-    const getDataChannel = async () => {
-      return await this.getDataChannel(peripheralTwin.id);
-    };
-
-    const onDataChannel = async (callback: (dc: PhygridDataChannel) => void) => {
-      return await this.onDataChannel(peripheralTwin.id, callback);
-    };
-
-    const getMediaStream = async () => {
-      if (!peripheralInstance) {
-        throw new Error('Peripheral instance not initialized');
-      }
-      return await this.getMediaStream(peripheralInstance.id);
-    };
-
-    const onMediaStream = async (callback: (stream: PhygridMediaStream) => void): Promise<void> => {
-      if (!peripheralInstance) {
-        throw new Error('Peripheral instance not initialized');
-      }
-      await this.onMediaStream(peripheralInstance.id, callback);
-      // Return void to match the expected return type
-    };
-
-    const updateReported = async (properties: Record<string, any>) => {
-      const newReported = {
-        ...properties,
-      };
-      const result = await this.updateReportedProperties(peripheralTwin.id, newReported);
-      // console.log('hub-client updateReported result', result);
-      Object.assign(peripheralInstance!, result);
-      return result;
-    };
-
-    const onUpdateReported = (callback: (reportedProperties: Record<string, any>) => void) => {
-      let previousProperties: Record<string, any> | undefined = undefined;
-
-      console.log(`[onUpdateReported] Registering handler for all reported properties`);
-
-      this.onTwinUpdate(peripheralTwin.id, (twin: TwinResponse) => {
-        console.log(`[onUpdateReported] Twin update received for ${peripheralTwin.id}`);
-
-        // Only process updates for this specific peripheral
-        if (twin.id !== peripheralTwin.id) {
-          console.log(`[onUpdateReported] Twin ID mismatch: ${twin.id} !== ${peripheralTwin.id}`);
-          return;
-        }
-
-        const reported = twin.properties.reported as Record<string, any>;
-
-        // Check if reported properties exist
-        if (reported) {
-          // If this is the first update, always trigger
-          if (previousProperties === undefined) {
-            console.log(`[onUpdateReported] First update - calling callback`);
-            previousProperties = JSON.parse(JSON.stringify(reported)); // Deep copy
-            callback(reported);
-            return;
-          }
-
-          const currentPropertiesStr = JSON.stringify(reported);
-          const previousPropertiesStr = JSON.stringify(previousProperties);
-
-          // Debug by printing parts of the strings - last 100 chars to avoid excessive logs
-          console.log(
-            `[onUpdateReported] Current (end): ...${currentPropertiesStr.substring(currentPropertiesStr.length - 100)}`
-          );
-          console.log(
-            `[onUpdateReported] Previous (end): ...${previousPropertiesStr.substring(previousPropertiesStr.length - 100)}`
-          );
-
-          // Additional check - compare string lengths first
-          if (currentPropertiesStr.length !== previousPropertiesStr.length) {
-            console.log(
-              `[onUpdateReported] String length changed: ${currentPropertiesStr.length} vs ${previousPropertiesStr.length}`
-            );
-          }
-
-          const hasChanged = currentPropertiesStr !== previousPropertiesStr;
-
-          console.log(
-            `[onUpdateReported] Properties comparison:`,
-            hasChanged ? 'CHANGED' : 'UNCHANGED'
-          );
-
-          if (hasChanged) {
-            previousProperties = JSON.parse(currentPropertiesStr); // Deep copy
-            console.log(`[onUpdateReported] Calling callback with updated reported properties`);
-            callback(reported);
-          } else {
-            // Force a callback call at least every 5 updates to ensure clients get updates
-            // This is a safety mechanism
-            console.log(`[onUpdateReported] No change detected in properties`);
-          }
-        } else {
-          console.log(`[onUpdateReported] No reported properties found`);
-        }
-      });
-    };
-
-    const onUpdateDesired = (callback: (desiredProperties: Record<string, any>) => void) => {
-      let previousProperties: Record<string, any> | undefined = undefined;
-
-      console.log(`[onUpdateDesired] Registering handler for all desired properties`);
-
-      this.onTwinUpdate(peripheralTwin.id, (twin: TwinResponse) => {
-        console.log(`[onUpdateDesired] Twin update received for ${peripheralTwin.id}`);
-
-        // Only process updates for this specific peripheral
-        if (twin.id !== peripheralTwin.id) {
-          console.log(`[onUpdateDesired] Twin ID mismatch: ${twin.id} !== ${peripheralTwin.id}`);
-          return;
-        }
-
-        const desired = twin.properties.desired as Record<string, any>;
-
-        // Check if desired properties exist
-        if (desired) {
-          // If this is the first update, always trigger
-          if (previousProperties === undefined) {
-            console.log(`[onUpdateDesired] First update - calling callback`);
-            previousProperties = JSON.parse(JSON.stringify(desired)); // Deep copy
-            callback(desired);
-            return;
-          }
-
-          const currentPropertiesStr = JSON.stringify(desired);
-          const previousPropertiesStr = JSON.stringify(previousProperties);
-
-          // Debug by printing parts of the strings - last 100 chars to avoid excessive logs
-          console.log(
-            `[onUpdateDesired] Current (end): ...${currentPropertiesStr.substring(currentPropertiesStr.length - 100)}`
-          );
-          console.log(
-            `[onUpdateDesired] Previous (end): ...${previousPropertiesStr.substring(previousPropertiesStr.length - 100)}`
-          );
-
-          // Additional check - compare string lengths first
-          if (currentPropertiesStr.length !== previousPropertiesStr.length) {
-            console.log(
-              `[onUpdateDesired] String length changed: ${currentPropertiesStr.length} vs ${previousPropertiesStr.length}`
-            );
-          }
-
-          const hasChanged = currentPropertiesStr !== previousPropertiesStr;
-
-          console.log(
-            `[onUpdateDesired] Properties comparison:`,
-            hasChanged ? 'CHANGED' : 'UNCHANGED'
-          );
-
-          if (hasChanged) {
-            previousProperties = JSON.parse(currentPropertiesStr); // Deep copy
-            console.log(`[onUpdateDesired] Calling callback with updated desired properties`);
-            callback(desired);
-          } else {
-            // Force a callback call at least every 5 updates to ensure clients get updates
-            // This is a safety mechanism
-            console.log(`[onUpdateDesired] No change detected in properties`);
-          }
-        } else {
-          console.log(`[onUpdateDesired] No desired properties found`);
-        }
-      });
-    };
-
-    const remove = async (): Promise<TwinResponse | void> => {
-      const payload: EventPayload = {
-        data: { twinId: peripheralTwin.id },
-      };
-
-      return new Promise((resolve, reject) => {
-        this.emit('deletePeripheralTwin', payload, (response: any) => {
-          const { twin } = response;
-          resolve(twin);
-        });
 
-        this.socket?.on('error', (error: any) => {
-          reject(error);
-        });
-      });
-    };
-
-    const updateDesired = async (properties: Record<string, any>): Promise<TwinResponse> => {
-      const payload: EventPayload = {
-        twinId: peripheralTwin.id,
-        data: properties,
-      };
-
-      return new Promise((resolve, reject) => {
-        this.emit('updatePeripheralTwinDesired', payload, (response: any) => {
-          const { twin } = response;
-          resolve(twin || {});
-        });
-
-        this.socket?.on('error', (error: any) => {
-          reject(error);
-        });
-      });
-    };
-
-    peripheralInstance = {
-      ...peripheralTwin,
-      emit: peripheralTwinEmit,
-      on: peripheralTwinOn,
-      to: peripheralTwinTo,
-      updateReported,
-      updateDesired,
-      onUpdateReported,
-      onUpdateDesired,
-      remove,
-      getDataChannel,
-      onDataChannel,
-      getMediaStream,
-      onMediaStream,
-    };
-    this.peripheralInstances.set(peripheralTwinId, peripheralInstance);
+    const peripheralInstance = await this.twinInstancesRegistry.getPeripheralInstance(peripheralTwinId);
     return peripheralInstance;
   }
 
@@ -1019,7 +661,7 @@ export class PhyHubClient {
         }
         if (currentWindow.parent === currentWindow) break;
         currentWindow = currentWindow.parent as Window & typeof globalThis;
-      } catch (e) {
+      } catch {
         break;
       }
     }
@@ -1106,11 +748,22 @@ export class PhyHubClient {
       return;
     }
 
-    const event = this.instanceId;
     const callback = typeof args[args.length - 1] === 'function' ? args.pop() : undefined;
-    const payload = { method, ...args[0] };
 
-    const emitArgs = [event, payload];
+    let emitArgs: any[];
+
+    // In direct connection mode, emit directly to the event name
+    // In normal mode, emit to instanceId channel with method in payload (for phyos routing)
+    if (PhyHubDirectConnection.isEnabled()) {
+      // Direct mode: emit to event name directly
+      const payload = args[0] || {};
+      emitArgs = [method, payload];
+    } else {
+      // Normal mode: emit to instanceId channel with method in payload
+      const event = this.instanceId;
+      const payload = { method, ...args[0] };
+      emitArgs = [event, payload];
+    }
 
     if (callback) {
       emitArgs.push(callback);
@@ -1187,16 +840,131 @@ export class PhyHubClient {
     return result;
   }
 
+  /**
+   * Send a fire-and-forget event to a twin.
+   * This is the standard way to send events - no response is expected.
+   */
+  public sendEvent(targetTwinId: string, data: any): void {
+    // console.log('[sendEvent] Sending to:', targetTwinId, 'data type:', data?.type || 'unknown');
+
+    // For fire-and-forget, we need to get the instance synchronously if possible
+    // or queue the message. We'll use a simpler approach here.
+    const instanceId = this.instanceId;
+    if (!instanceId) {
+      console.error('[sendEvent] Instance ID not set, cannot send event');
+      return;
+    }
+
+    // Get deviceId from cached instance if available
+    const cachedInstance = this.instances.get(instanceId);
+    const deviceId = cachedInstance?.deviceId || this.lastDeviceStatusResponse?.deviceId;
+
+    if (!deviceId) {
+      console.error('[sendEvent] Device ID not available, cannot send event');
+      return;
+    }
+
+    const payload: EventPayload = {
+      twinId: targetTwinId,
+      sourceTwinId: instanceId,
+      sourceDeviceId: deviceId,
+      data,
+    };
+
+    // Fire-and-forget: just emit, no callback, no promise
+    this.emit(this.EVENTS.TWIN_MESSAGE, payload);
+  }
+
+  /**
+   * @deprecated Use instance.request() or instance.to(twinId).request() instead.
+   * This method uses socket.io acknowledgements which may not work in all scenarios.
+   * The instance API uses a more reliable emit/on pattern for request-response.
+   */
+  public async request(
+    targetTwinId: string,
+    data: any,
+    callback?: (response: TwinMessageResult) => void
+  ): Promise<TwinMessageResult | undefined> {
+    console.log('[request] Sending to:', targetTwinId, 'data type:', data?.type || 'unknown');
+
+    const edgeInstance = await this.getInstance();
+    if (!edgeInstance) {
+      console.error('[request] Edge instance not found');
+      throw new Error('Edge instance not found');
+    }
+
+    const { id: edgeTwinId, deviceId } = edgeInstance;
+
+    if (!deviceId) {
+      console.error('[request] Device ID not available');
+      throw new Error('Device ID not available - ensure device is connected');
+    }
+
+    const payload: EventPayload = {
+      twinId: targetTwinId,
+      sourceTwinId: edgeTwinId,
+      sourceDeviceId: deviceId,
+      data,
+    };
+
+    if (callback) {
+      // Callback pattern: use socket.io acknowledgement
+      this.emit(this.EVENTS.TWIN_MESSAGE, payload, (response: TwinMessageResult) => {
+        callback(response);
+      });
+      return;
+    }
+
+    // Promise pattern: wait for response with timeout
+    return new Promise((resolve, reject) => {
+      const ACTION_TIMEOUT = 10 * 1000;
+      const timeoutId = setTimeout(() => {
+        if (this.socket) {
+          this.socket?.off(payload.data.type);
+        }
+        reject({
+          status: TwinMessageResultStatus.Error,
+          message: `Request timed out after ${ACTION_TIMEOUT}ms`
+        });
+      }, ACTION_TIMEOUT);
+
+      if (this.socket) {
+        this.socket.on(payload.data.type, (response: TwinMessageResult) => {
+          if (response && response.status !== TwinMessageResultStatus.Warning) {
+            clearTimeout(timeoutId);
+            this.socket?.off(payload.data.type);
+            resolve(response);
+          }
+        });
+      }
+
+      this.emit(this.EVENTS.TWIN_MESSAGE, payload, (response: TwinMessageResult) => {
+        // Socket.io acknowledgement received
+        clearTimeout(timeoutId);
+        if (this.socket) {
+          this.socket?.off(payload.data.type);
+        }
+        resolve(response);
+      });
+
+      this.socket?.on('error', (error: any) => {
+        clearTimeout(timeoutId);
+        console.error('[request] Socket error:', error);
+        reject(error);
+      });
+    });
+  }
+
+  /**
+   * @deprecated Use sendEvent() for fire-and-forget events, or request() for request-response.
+   * This method is kept for backwards compatibility.
+   */
   public async sendTwinMessage(
     targetTwinId: string,
     data: any,
     callback?: (response: any) => void
-  ) {
-    // console.log('sendTwinMessage called with:', {
-    //   targetTwinId,
-    //   data,
-    //   hasCallback: !!callback
-    // });
+  ): Promise<void> {
+    console.log('[sendTwinMessage] Sending to:', targetTwinId, 'data type:', data?.type || 'unknown');
 
     const edgeInstance = await this.getInstance();
     if (!edgeInstance) {
@@ -1218,27 +986,13 @@ export class PhyHubClient {
       data,
     };
 
-    // console.log('sendTwinMessage prepared payload:', JSON.stringify(payload, null, 2));
-
     if (callback) {
-      // console.log('sendTwinMessage emitting with callback');
       this.emit(this.EVENTS.TWIN_MESSAGE, payload, (response: any) => {
-        // console.log('sendTwinMessage callback received response:', response);
         callback(response);
       });
     } else {
-      // console.log('sendTwinMessage emitting with promise');
-      return new Promise((resolve, reject) => {
-        this.emit(this.EVENTS.TWIN_MESSAGE, payload, (response: any) => {
-          // console.log('sendTwinMessage promise received response:', response);
-          resolve(response);
-        });
-
-        this.socket?.on('error', (error: any) => {
-          console.error('sendTwinMessage socket error:', error);
-          reject(error);
-        });
-      });
+      // Fire-and-forget for backwards compatibility (no timeout/rejection)
+      this.emit(this.EVENTS.TWIN_MESSAGE, payload);
     }
   }
 
@@ -1246,32 +1000,10 @@ export class PhyHubClient {
     targetTwinId: string,
     callback: (message: any) => void
   ): Promise<void> {
-    console.log('onTwinMessage called for twin:', {
-      targetTwinId,
-      existingListeners: this.twinMessageListeners[targetTwinId]?.size || 0,
-    });
-
     if (!this.twinMessageListeners[targetTwinId]) {
-      // console.log(`Creating new listener set for twin ${targetTwinId}`);
       this.twinMessageListeners[targetTwinId] = new Set();
     }
-
     this.twinMessageListeners[targetTwinId].add(callback);
-    console.log(
-      `Added new callback. Total listeners: ${this.twinMessageListeners[targetTwinId].size}`
-    );
-
-    // console.log(`Adding callback to listeners for twin ${targetTwinId}`);
-    this.twinMessageListeners[targetTwinId].add(callback);
-
-    // console.log('Current listener count:', {
-    //   targetTwinId,
-    //   listenerCount: this.twinMessageListeners[targetTwinId].size,
-    //   allListeners: Object.keys(this.twinMessageListeners).map(id => ({
-    //     twinId: id,
-    //     count: this.twinMessageListeners[id].size
-    //   }))
-    // });
   }
 
   public offTwinMessage(targetTwinId: string, callback: (message: any) => void): boolean {
@@ -1307,10 +1039,6 @@ export class PhyHubClient {
   }
 
   public async subscribeTwin(targetTwinId: string, callback?: (response: any) => void) {
-    console.log(`[subscribeTwin] Starting subscription to twin ${targetTwinId}`);
-    console.log(`[subscribeTwin] Current subscribed twins:`, Array.from(this.subscribedTwins));
-    console.log(`[subscribeTwin] Current listeners:`, Object.keys(this.twinMessageListeners));
-
     this.subscribedTwins.add(targetTwinId);
     const edgeInstance = await this.getInstance();
     if (!edgeInstance) {
@@ -1325,17 +1053,13 @@ export class PhyHubClient {
       sourceDeviceId: deviceId,
     };
 
-    console.log(`[subscribeTwin] Emitting TWIN_SUBSCRIBE with payload:`, payload);
-
     if (callback) {
       this.emit(this.EVENTS.TWIN_SUBSCRIBE, payload, (response: any) => {
-        console.log(`[subscribeTwin] Subscription callback response:`, response);
         callback(response);
       });
     } else {
       return new Promise((resolve, reject) => {
         this.emit(this.EVENTS.TWIN_SUBSCRIBE, payload, (response: any) => {
-          console.log(`[subscribeTwin] Subscription promise response:`, response);
           resolve(response);
         });
 
@@ -1348,12 +1072,14 @@ export class PhyHubClient {
   }
 
   public async getTwinById(twinId: string): Promise<TwinResponse> {
+    console.log(`[getTwinById] Fetching twin: ${twinId}`);
     const payload: EventPayload<{ twinId: string }> = {
       data: { twinId },
     };
 
     return new Promise((resolve, reject) => {
       this.emit(this.EVENTS.GET_TWIN_BY_ID, payload, (response: any) => {
+        console.log(`[getTwinById] Response for ${twinId}:`, response);
         const { twin } = response;
         if (!twin) {
           reject(new Error(`Twin with id ${twinId} not found`));
@@ -1363,6 +1089,7 @@ export class PhyHubClient {
       });
 
       this.socket?.on('error', (error: any) => {
+        console.error(`[getTwinById] Socket error for ${twinId}:`, error);
         reject(error);
       });
     });
@@ -1390,7 +1117,7 @@ export class PhyHubClient {
   //   });
   // }
 
-  private async updateReportedProperties(
+  public async updateReportedProperties(
     twinId: string,
     reportedProperties: Record<string, any>
   ): Promise<TwinResponse> {
@@ -1414,16 +1141,99 @@ export class PhyHubClient {
       });
     });
   }
+
+  /**
+   * Initialize the device twin in direct connection mode.
+   * Waits for deviceAuthenticated, then calls connectDevice to get all twins
+   * for this device, including the device twin which provides the actual twinId.
+   */
+  private async initializeDirectConnectionTwin(): Promise<void> {
+    console.log('[initializeDirectConnectionTwin] Waiting for authentication...');
+
+    // First wait for deviceAuthenticated event from server
+    await new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('Timeout waiting for deviceAuthenticated'));
+      }, 10000);
+
+      this.socket?.once('deviceAuthenticated', (data: any) => {
+        clearTimeout(timeout);
+        console.log('[initializeDirectConnectionTwin] Authenticated:', data);
+        resolve();
+      });
+    });
+
+    console.log('[initializeDirectConnectionTwin] Calling connectDevice...');
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('Timeout waiting for connectDevice response'));
+      }, 10000);
+
+      // Use connectDevice to get all twins for this device
+      this.socket?.emit(
+        'connectDevice',
+        (response: any) => {
+          clearTimeout(timeout);
+          console.log('[initializeDirectConnectionTwin] connectDevice response:', JSON.stringify(response, null, 2));
+
+          if (response?.status === 'success' && response?.twins?.length > 0) {
+            // Find the device twin from the array (type is "Device" with capital D)
+            const deviceTwin = response.twins.find((t: any) => t.type === 'Device');
+
+            if (deviceTwin) {
+              const actualTwinId = deviceTwin.id || deviceTwin._id;
+              console.log(
+                `[initializeDirectConnectionTwin] Got device twin. DeviceId: ${deviceTwin.deviceId}, TwinId: ${actualTwinId}`
+              );
+              this.instanceId = actualTwinId;
+              resolve();
+            } else {
+              console.error('[initializeDirectConnectionTwin] No device twin found in twins array');
+              reject(new Error('No device twin found for this device'));
+            }
+          } else if (response?.status === 'error') {
+            const errorMessage = response?.message || 'Unknown error';
+            console.error('[initializeDirectConnectionTwin] connectDevice failed:', errorMessage);
+
+            // Provide more helpful error messages
+            if (errorMessage.includes('Failed to find device twin')) {
+              console.error('\n=== DEVICE TWIN NOT FOUND ===');
+              console.error('This device exists in the legacy database but has not been');
+              console.error('properly migrated to PhyHub. The device twins need to be created.');
+              console.error('');
+              console.error('To fix this:');
+              console.error('1. Reset isMigratedToPhyhub flag in legacy DB, OR');
+              console.error('2. Use a different device that has been properly migrated');
+              console.error('==============================\n');
+            }
+
+            reject(new Error(errorMessage));
+          } else {
+            console.error('[initializeDirectConnectionTwin] Unexpected response:', response);
+            reject(new Error('Failed to connect device'));
+          }
+        }
+      );
+    });
+  }
 }
 
 export const connectPhyClient = (
   params: { instanceId?: string; moduleName?: string; dataResidency?: string } = {}
 ) => PhyHubClient.connect(params);
 
-export type { EdgeTwinResponse, Instance, PeripheralInstance };
+export type { EdgeTwinResponse, Instance, PeripheralInstance, IPeripheralTwinInstance, TwinMessageResult };
+export { TwinMessageResultStatus };
 
 export default {
   connectPhyClient,
 };
 
-export type { PhygridDataChannel, PhygridMediaStream };
+// Re-export WebRTC types for convenience
+export type { PhygridDataChannel, PhygridMediaStream, WebRTCManagerOptions, MediaStreamOptions };
+export { WebRTCManager } from './services/webrtc';
+
+// Re-export twin messaging types for custom implementations
+export type { TwinMessagingContext, TwinMessagingMethods } from './twin-messaging';
+export { createTwinMessaging } from './twin-messaging';