@microsoft/agents-copilotstudio-client 0.6.1 → 0.6.11

package/src/copilotStudioWebChat.ts

@@ -6,106 +6,229 @@
 import { v4 as uuid } from 'uuid'
 
 import { Activity, ConversationAccount } from '@microsoft/agents-activity'
-import { Observable, BehaviorSubject, type Observer } from 'rxjs'
+import { Observable, BehaviorSubject, type Subscriber } from 'rxjs'
 
 import { CopilotStudioClient } from './copilotStudioClient'
+import { debug } from '@microsoft/agents-activity/src/logger'
 
+const logger = debug('copilot-studio:webchat')
+
+/**
+ * Configuration settings for the Copilot Studio WebChat connection.
+ * These settings control the behavior and appearance of the WebChat interface
+ * when connected to the Copilot Studio service.
+ */
 export interface CopilotStudioWebChatSettings {
   /**
-   * Whether to show typing indicators in the WebChat.
-   * Defaults to false.
+   * Whether to show typing indicators in the WebChat when the agent is processing a response.
+   * When enabled, users will see a typing indicator while waiting for the agent's reply,
+   * providing visual feedback that their message is being processed.
+   * @default false
    */
   showTyping?: boolean;
 }
 
+/**
+ * Represents a connection interface for integrating Copilot Studio with WebChat.
+ * This interface provides the necessary methods and observables to facilitate
+ * bidirectional communication between a WebChat client and the Copilot Studio service.
+ *
+ * The connection follows the DirectLine protocol pattern, making it compatible with
+ * Microsoft Bot Framework WebChat components.
+ */
 export interface CopilotStudioWebChatConnection {
   /**
-   * An observable that emits the connection status.
-   * 0 - Disconnected
-   * 1 - Connecting
-   * 2 - Connected
-  */
+   * An observable that emits the current connection status as numeric values.
+   * This allows WebChat clients to monitor and react to connection state changes.
+   *
+   * Connection status values:
+   * - 0: Disconnected - No active connection to the service
+   * - 1: Connecting - Attempting to establish connection
+   * - 2: Connected - Successfully connected and ready for communication
+   */
   connectionStatus$: BehaviorSubject<number>;
 
   /**
-   * An observable that emits incoming activities.
-   * The emitted activities will have a 'webchat:sequence-id' in their channelData.
+   * An observable stream that emits incoming activities from the Copilot Studio service.
+   * Each activity represents a message, card, or other interactive element sent by the agent.
+   *
+   * All emitted activities include:
+   * - A timestamp indicating when the activity was received
+   * - A 'webchat:sequence-id' in their channelData for proper message ordering
+   * - Standard Bot Framework Activity properties (type, text, attachments, etc.)
    */
   activity$: Observable<Partial<Activity>>;
 
   /**
-   * Posts an activity to the Copilot Studio service.
-   * The activity must have a non-empty text field.
-   * Returns an observable that emits the activity ID once the activity is posted.
+   * Posts a user activity to the Copilot Studio service and returns an observable
+   * that emits the activity ID once the message is successfully sent.
    *
-   * @param activity - The activity to post.
-   * @returns An observable that emits the activity ID.
+   * The method validates that the activity contains meaningful content and handles
+   * the complete message flow including optional typing indicators.
+   *
+   * @param activity - The user activity to send. Must contain a non-empty text field.
+   * @returns An observable that emits the unique activity ID upon successful posting.
+   * @throws Error if the activity text is empty or if the connection is not properly initialized.
    */
   postActivity(activity: Activity): Observable<string>;
 
   /**
-   * Ends the connection.
-   * This will complete the connectionStatus$ and activity$ observables.
+   * Gracefully terminates the connection to the Copilot Studio service.
+   * This method ensures proper cleanup by completing all active observables
+   * and releasing associated resources.
+   *
+   * After calling this method:
+   * - The connectionStatus$ observable will be completed
+   * - The activity$ observable will stop emitting new activities
+   * - No further activities can be posted through this connection
    */
   end(): void;
 }
 
 /**
- * This class is intended to be used in WebChat applications to connect to the Copilot Studio service.
+ * A utility class that provides WebChat integration capabilities for Copilot Studio services.
+ * This class acts as a bridge between Microsoft Bot Framework WebChat and Copilot Studio,
+ * enabling seamless communication through a DirectLine-compatible interface.
  *
- * example usage:
- * ```javascript
- * const client = new CopilotStudioClient(...)
+ * ## Key Features:
+ * - DirectLine protocol compatibility for easy WebChat integration
+ * - Real-time bidirectional messaging with Copilot Studio agents
+ * - Automatic conversation management and message sequencing
+ * - Optional typing indicators for enhanced user experience
+ * - Observable-based architecture for reactive programming patterns
+ *
+ * ## Usage Scenarios:
+ * - Embedding Copilot Studio agents in web applications
+ * - Creating custom chat interfaces with WebChat components
+ * - Building conversational AI experiences with Microsoft's bot ecosystem
+ *
+ * @example Basic WebChat Integration
+ * ```typescript
+ * import { CopilotStudioClient } from '@microsoft/agents-copilotstudio-client';
+ * import { CopilotStudioWebChat } from '@microsoft/agents-copilotstudio-client';
+ *
+ * // Initialize the Copilot Studio client
+ * const client = new CopilotStudioClient({
+ *   botId: 'your-bot-id',
+ *   tenantId: 'your-tenant-id'
+ * });
+ *
+ * // Create a WebChat-compatible connection
+ * const directLine = CopilotStudioWebChat.createConnection(client, {
+ *   showTyping: true
+ * });
+ *
+ * // Integrate with WebChat
  * window.WebChat.renderWebChat({
- *   directLine: CopilotStudioWebChat.createConnection(client)
- * })
+ *   directLine: directLine,
+ *   // ... other WebChat options
+ * }, document.getElementById('webchat'));
+ * ```
+ *
+ * @example Advanced Usage with Connection Monitoring
+ * ```typescript
+ * const connection = CopilotStudioWebChat.createConnection(client);
+ *
+ * // Monitor connection status
+ * connection.connectionStatus$.subscribe(status => {
+ *   switch (status) {
+ *     case 0: console.log('Disconnected'); break;
+ *     case 1: console.log('Connecting...'); break;
+ *     case 2: console.log('Connected and ready'); break;
+ *   }
+ * });
+ *
+ * // Listen for incoming activities
+ * connection.activity$.subscribe(activity => {
+ *   console.log('Received activity:', activity);
+ * });
  * ```
  */
 export class CopilotStudioWebChat {
   /**
-   * Creates a new DirectLine-Like connection to WebChat.
-   * When an activity is posted in WebChat, the connection will send it to the Copilot Studio service, awaiting response.
-   * After a response is received, it will emit the incoming activity back to WebChat.
+   * Creates a DirectLine-compatible connection for integrating Copilot Studio with WebChat.
+   *
+   * This method establishes a real-time communication channel between WebChat and the
+   * Copilot Studio service. The returned connection object implements the DirectLine
+   * protocol, making it fully compatible with Microsoft Bot Framework WebChat components.
+   *
+   * ## Connection Lifecycle:
+   * 1. **Initialization**: Creates observables for connection status and activity streaming
+   * 2. **Conversation Start**: Automatically initiates conversation when first activity is posted
+   * 3. **Message Flow**: Handles bidirectional message exchange with proper sequencing
+   * 4. **Cleanup**: Provides graceful connection termination
    *
-   * @param client - The Copilot Studio client instance.
-   * @param settings - Optional settings for the WebChat connection.
-   * @returns A new instance of CopilotStudioWebChatConnection.
+   * ## Message Processing:
+   * - User messages are validated and sent to Copilot Studio
+   * - Agent responses are received and formatted for WebChat
+   * - All activities include timestamps and sequence IDs for proper ordering
+   * - Optional typing indicators provide visual feedback during processing
+   *
+   * @param client - A configured CopilotStudioClient instance that handles the underlying
+   *                 communication with the Copilot Studio service. This client should be
+   *                 properly authenticated and configured with the target bot details.
+   *
+   * @param settings - Optional configuration settings that control the behavior of the
+   *                   WebChat connection. These settings allow customization of features
+   *                   like typing indicators and other user experience enhancements.
+   *
+   * @returns A new CopilotStudioWebChatConnection instance that can be passed directly
+   *          to WebChat's renderWebChat function as the directLine parameter. The
+   *          connection is immediately ready for use and will automatically manage
+   *          the conversation lifecycle.
+   *
+   * @throws Error if the provided client is not properly configured or if there are
+   *         issues establishing the initial connection to the Copilot Studio service.
+   *
+   * @example
+   * ```typescript
+   * const connection = CopilotStudioWebChat.createConnection(client, {
+   *   showTyping: true
+   * });
+   *
+   * // Use with WebChat
+   * window.WebChat.renderWebChat({
+   *   directLine: connection
+   * }, document.getElementById('webchat'));
+   * ```
    */
   static createConnection (
     client: CopilotStudioClient,
     settings?: CopilotStudioWebChatSettings
   ):CopilotStudioWebChatConnection {
+    logger.info('--> Creating connection between Copilot Studio and WebChat ...')
     let sequence = 0
-    let activityObserver: Observer<Partial<Activity>> | undefined
+    let activitySubscriber: Subscriber<Partial<Activity>> | undefined
     let conversation: ConversationAccount | undefined
 
     const connectionStatus$ = new BehaviorSubject(0)
-    const activity$ = Observable.create(
-      async (observer: Observer<Partial<Activity>>) => {
-        activityObserver = observer
+    const activity$ = createObservable<Partial<Activity>>(async (subscriber) => {
+      activitySubscriber = subscriber
 
-        if (connectionStatus$.value < 2) {
-          connectionStatus$.next(2)
-          return
-        }
-
-        notifyTyping()
-        const activity = await client.startConversationAsync()
-        conversation = activity.conversation
-        sequence = 0
-        notifyActivity(activity)
+      if (connectionStatus$.value < 2) {
+        connectionStatus$.next(2)
+        return
       }
-    )
+
+      logger.debug('--> Connection established.')
+      notifyTyping()
+      const activity = await client.startConversationAsync()
+      conversation = activity.conversation
+      sequence = 0
+      notifyActivity(activity)
+    })
 
     const notifyActivity = (activity: Partial<Activity>) => {
-      activityObserver?.next({
+      const newActivity = {
         ...activity,
         timestamp: new Date().toISOString(),
         channelData: {
           ...activity.channelData,
           'webchat:sequence-id': sequence++,
         },
-      })
+      }
+      logger.debug(`Notify '${newActivity.type}' activity to WebChat:`, newActivity)
+      activitySubscriber?.next(newActivity)
     }
 
     const notifyTyping = () => {
@@ -123,18 +246,22 @@ export class CopilotStudioWebChat {
       connectionStatus$,
       activity$,
       postActivity (activity: Activity) {
+        logger.info('--> Preparing to send activity to Copilot Studio ...')
+
         if (!activity.text?.trim()) {
           throw new Error('Activity text cannot be empty.')
         }
 
-        if (!activityObserver) {
-          throw new Error('Activity observer is not initialized.')
+        if (!activitySubscriber) {
+          throw new Error('Activity subscriber is not initialized.')
         }
 
-        return Observable.create(async (observer: Observer<string>) => {
+        return createObservable<string>(async (subscriber) => {
           try {
             const id = uuid()
 
+            logger.info('--> Sending activity to Copilot Studio ...')
+
             notifyActivity({ ...activity, id })
             notifyTyping()
 
@@ -143,22 +270,59 @@ export class CopilotStudioWebChat {
               notifyActivity(responseActivity)
             }
 
-            observer.next(id)
-            observer.complete()
+            subscriber.next(id)
+            subscriber.complete()
+            logger.info('--> Activity received correctly from Copilot Studio.')
           } catch (error) {
-            observer.error(error)
+            logger.error('Error sending Activity to Copilot Studio:', error)
+            subscriber.error(error)
           }
         })
       },
 
       end () {
+        logger.info('--> Ending connection between Copilot Studio and WebChat ...')
         connectionStatus$.complete()
-        activity$.complete()
-        if (activityObserver) {
-          activityObserver.complete()
-          activityObserver = undefined
+        if (activitySubscriber) {
+          activitySubscriber.complete()
+          activitySubscriber = undefined
         }
       },
     }
   }
 }
+
+/**
+ * Creates an RxJS Observable that wraps an asynchronous function execution.
+ *
+ * This utility function provides a clean way to convert async/await patterns
+ * into Observable streams, enabling integration with reactive programming patterns
+ * used throughout the WebChat connection implementation.
+ *
+ * The created Observable handles promise resolution and rejection automatically,
+ * converting them to appropriate next/error signals for subscribers.
+ *
+ * @template T - The type of value that the observable will emit
+ * @param fn - An asynchronous function that receives a Subscriber and performs
+ *             the desired async operation. The function should call subscriber.next()
+ *             with results and subscriber.complete() when finished.
+ * @returns A new Observable that executes the provided function and emits its results
+ *
+ * @example
+ * ```typescript
+ * const dataObservable = createObservable<string>(async (subscriber) => {
+ *   try {
+ *     const result = await fetchData();
+ *     subscriber.next(result);
+ *     subscriber.complete();
+ *   } catch (error) {
+ *     subscriber.error(error);
+ *   }
+ * });
+ * ```
+ */
+function createObservable<T> (fn: (subscriber: Subscriber<T>) => void): Observable<T> {
+  return new Observable<T>((subscriber: Subscriber<T>) => {
+    Promise.resolve(fn(subscriber)).catch((error) => subscriber.error(error))
+  })
+}

package/src/powerPlatformEnvironment.ts

@@ -5,10 +5,13 @@
 
 import { AgentType } from './agentType'
 import { ConnectionSettings } from './connectionSettings'
+import { debug } from '@microsoft/agents-activity/src/logger'
 import { PowerPlatformCloud } from './powerPlatformCloud'
 import { PrebuiltBotStrategy } from './strategies/prebuiltBotStrategy'
 import { PublishedBotStrategy } from './strategies/publishedBotStrategy'
 
+const logger = debug('copilot-studio:power-platform')
+
 /**
  * Generates the connection URL for Copilot Studio.
  * @param settings - The connection settings.
@@ -23,12 +26,14 @@ export function getCopilotStudioConnectionUrl (
   let cloudValue: PowerPlatformCloud = PowerPlatformCloud.Prod
 
   if (settings.directConnectUrl?.trim()) {
+    logger.debug(`Using direct connection: ${settings.directConnectUrl}`)
     if (!isValidUri(settings.directConnectUrl)) {
       throw new Error('directConnectUrl must be a valid URL')
     }
 
     // FIX for Missing Tenant ID
-    if (settings.directConnectUrl.toLocaleLowerCase().includes('tenants/00000000-0000-0000-0000-000000000000')) {
+    if (settings.directConnectUrl.toLowerCase().includes('tenants/00000000-0000-0000-0000-000000000000')) {
+      logger.debug(`Direct connection cannot be used, forcing default settings flow. Tenant ID is missing in the URL: ${settings.directConnectUrl}`)
       // Direct connection cannot be used, ejecting and forcing the normal settings flow:
       return getCopilotStudioConnectionUrl({ ...settings, directConnectUrl: '' }, conversationId)
     }
@@ -58,15 +63,17 @@ export function getCopilotStudioConnectionUrl (
   }
 
   if (cloudSetting !== PowerPlatformCloud.Unknown) {
+    logger.debug(`Using specified cloud setting: ${cloudSetting}`)
     cloudValue = cloudSetting
   }
 
   if (cloudSetting === PowerPlatformCloud.Other) {
     if (isNotEmptyCustomPowerPlatformCloud && isValidUri(settings.customPowerPlatformCloud!)) {
+      logger.debug(`Using custom Power Platform cloud: ${settings.customPowerPlatformCloud}`)
       cloudValue = PowerPlatformCloud.Other
     } else {
       throw new Error(
-        'customPowerPlatformCloud must be provided when PowerPlatformCloud is Other'
+        'customPowerPlatformCloud must be a valid URL'
       )
     }
   }
@@ -77,9 +84,11 @@ export function getCopilotStudioConnectionUrl (
     if (!Object.values(AgentType).includes(settings.copilotAgentType)) {
       throw new Error('Invalid AgentType enum key')
     } else {
+      logger.debug(`Using specified agent type: ${settings.copilotAgentType}`)
       agentType = settings.copilotAgentType
     }
   } else {
+    logger.debug('Using default agent type: Published')
     agentType = AgentType.Published
   }
 
@@ -98,7 +107,9 @@ export function getCopilotStudioConnectionUrl (
     }),
   }[agentType]()
 
-  return strategy.getConversationUrl(conversationId)
+  const url = strategy.getConversationUrl(conversationId)
+  logger.debug(`Generated Copilot Studio connection URL: ${url}`)
+  return url
 }
 
 /**