@phystack/hub-client 4.4.53 → 4.4.55

package/src/index.ts

@@ -13,88 +13,20 @@ import {
   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';
+  WebRTCManager,
+  TwinMessagingInterface,
+  PhygridDataChannel,
+  PhygridMediaStream,
+  WebRTCManagerOptions,
+  MediaStreamOptions,
+} from './services/webrtc';
 import { TwinRegistry } from './twin-registry';
-// import { createWebRTCMediaStreamConnection, WebRTCMediaStreamResult } from './helpers/webrtc-mediastream';
-
-export * from './types';
-
-// 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));
+import { createTwinMessaging } from './twin-messaging';
 
 export interface EventPayload<T = any> {
   twinId?: string;
@@ -122,6 +54,7 @@ export class PhyHubClient {
   private instances: Map<string, Instance> = 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',
@@ -210,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;
@@ -267,38 +205,50 @@ export class PhyHubClient {
       this.socketConnected = false;
     });
 
-    this.socket.on(this.EVENTS.TWIN_MESSAGE, (payload: EventPayload, callback: (response: TwinMessageResult | null) => void) => {
-      // 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) => {
+      console.log('[TWIN_MESSAGE] Received:', {
+        twinId: payload.twinId,
+        sourceTwinId: payload.sourceTwinId,
+        dataType: payload.data?.type,
+      });
 
       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
-        // });
-        const listeners = this.twinMessageListeners[payload.twinId];
+
+      if (payload.data) {
+        // Try to find listeners by sourceTwinId (messages FROM this twin)
+        // This is the correct lookup - we register for a peer's twin ID to receive messages FROM them
+        const sourceTwinId = payload.sourceTwinId;
+        const targetTwinId = payload.twinId;
+
+        // First try sourceTwinId (the sender) - this is what onTwinMessage registers for
+        let listeners = sourceTwinId ? this.twinMessageListeners[sourceTwinId] : undefined;
+
+        // Also check targetTwinId for backwards compatibility
+        if (!listeners && targetTwinId) {
+          listeners = this.twinMessageListeners[targetTwinId];
+        }
+
         if (listeners?.size) {
-          // console.log(`Executing ${listeners.size} listeners for twin ${payload.twinId}`);
+          console.log(`[TWIN_MESSAGE] Executing ${listeners.size} listeners`);
           listeners.forEach(listener => {
-            // console.log('Executing listener for twin:', listener);
             try {
               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:`, error);
               result = { status: TwinMessageResultStatus.Error, message: (error as Error)?.message || 'An error occurred' };
             }
           });
         } else {
-          // even though there are no errors, still send acknowledgement to the socket server
-          result = { status: TwinMessageResultStatus.Warning, message: `No listeners found for twin ${payload.twinId} on this socket` };
+          console.log(`[TWIN_MESSAGE] No listeners found for source=${sourceTwinId} or target=${targetTwinId}`);
+          result = { status: TwinMessageResultStatus.Warning, message: `No listeners found` };
         }
 
-        callback(result);
+        if (callback) {
+          callback(result);
+        }
       } else {
-        // console.log('Invalid twin message payload:', payload);
+        console.log('[TWIN_MESSAGE] Invalid payload (no data):', payload);
       }
     });
 
@@ -460,88 +410,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> {
@@ -558,50 +529,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[]> => {
@@ -663,27 +598,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>) => {
@@ -697,9 +631,9 @@ export class PhyHubClient {
 
     instance = {
       ...instanceTwin,
-      emit: edgeTwinEmit,
-      on: edgeTwinOn,
-      to: edgeTwinTo,
+      emit: messaging.emit,
+      on: messaging.on,
+      to: messaging.to,
       createPeripheralTwin,
       updateReported,
       getPeripheralTwins,
@@ -746,7 +680,7 @@ export class PhyHubClient {
         }
         if (currentWindow.parent === currentWindow) break;
         currentWindow = currentWindow.parent as Window & typeof globalThis;
-      } catch (e) {
+      } catch {
         break;
       }
     }
@@ -833,11 +767,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);
@@ -914,27 +859,63 @@ export class PhyHubClient {
     return result;
   }
 
-  public async sendTwinMessage(
+  /**
+   * 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: any) => void
-  ) : Promise<TwinMessageResult | undefined> {
-    // console.log('sendTwinMessage called with:', {
-    //   targetTwinId,
-    //   data,
-    //   hasCallback: !!callback
-    // });
+    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('sendTwinMessage failed: Edge instance not found');
+      console.error('[request] Edge instance not found');
       throw new Error('Edge instance not found');
     }
 
     const { id: edgeTwinId, deviceId } = edgeInstance;
 
     if (!deviceId) {
-      console.error('sendTwinMessage failed: Device ID not available');
+      console.error('[request] Device ID not available');
       throw new Error('Device ID not available - ensure device is connected');
     }
 
@@ -945,48 +926,92 @@ 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 pattern: use socket.io acknowledgement
+      this.emit(this.EVENTS.TWIN_MESSAGE, payload, (response: TwinMessageResult) => {
         callback(response);
       });
-    } else {
-      // console.log('sendTwinMessage emitting with promise');
-      return new Promise((resolve, reject) => {
+      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);
 
-        const twinMessageTimeout = 10 * 1000;
-        const twinMessageTimeoutId = setTimeout(() => {
-          if (this.socket) {
+      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);
           }
+        });
+      }
 
-          reject({ status: TwinMessageResultStatus.Error, message: `twinMessage failed to complete in specified time (${twinMessageTimeout} ms)`});
-        }, twinMessageTimeout);
-
+      this.emit(this.EVENTS.TWIN_MESSAGE, payload, (response: TwinMessageResult) => {
+        // Socket.io acknowledgement received
+        clearTimeout(timeoutId);
         if (this.socket) {
-          this.socket.on(payload.data.type, (response: TwinMessageResult) => {
-            if (response && response.status !== TwinMessageResultStatus.Warning) {
-              // clear timeout on receiving twinMessage result when response status is not warning
-              clearTimeout(twinMessageTimeoutId);
-
-              this.socket?.off(payload.data.type);
-              resolve(response);
-            }
-          });
+          this.socket?.off(payload.data.type);
         }
+        resolve(response);
+      });
 
-        this.emit(this.EVENTS.TWIN_MESSAGE, payload, (response: any) => {
-          console.log('sendTwinMessage promise received response:', response);
-        });
+      this.socket?.on('error', (error: any) => {
+        clearTimeout(timeoutId);
+        console.error('[request] Socket error:', error);
+        reject(error);
+      });
+    });
+  }
 
-        this.socket?.on('error', (error: any) => {
-          console.error('sendTwinMessage 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
+  ): Promise<void> {
+    console.log('[sendTwinMessage] Sending to:', targetTwinId, 'data type:', data?.type || 'unknown');
+
+    const edgeInstance = await this.getInstance();
+    if (!edgeInstance) {
+      console.error('sendTwinMessage failed: Edge instance not found');
+      throw new Error('Edge instance not found');
+    }
+
+    const { id: edgeTwinId, deviceId } = edgeInstance;
+
+    if (!deviceId) {
+      console.error('sendTwinMessage failed: 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) {
+      this.emit(this.EVENTS.TWIN_MESSAGE, payload, (response: any) => {
+        callback(response);
       });
+    } else {
+      // Fire-and-forget for backwards compatibility (no timeout/rejection)
+      this.emit(this.EVENTS.TWIN_MESSAGE, payload);
     }
   }
 
@@ -1096,12 +1121,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`));
@@ -1111,6 +1138,7 @@ export class PhyHubClient {
       });
 
       this.socket?.on('error', (error: any) => {
+        console.error(`[getTwinById] Socket error for ${twinId}:`, error);
         reject(error);
       });
     });
@@ -1162,16 +1190,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';