@microsoft/agents-hosting-extensions-msteams 1.7.0-beta.10.g0c6864b626

package/src/teamsHeaderPropagation.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { HeaderPropagationCollection } from '@microsoft/agents-hosting'
+import { version } from '../package.json'
+
+const USER_AGENT_HEADER = 'User-Agent'
+/**
+ * Product token appended to outbound User-Agent headers by the Teams extension.
+ */
+export const TEAMS_USER_AGENT_PRODUCT = `agents-sdk-js-teams/${version}`
+
+/**
+ * Applies Teams-specific header propagation to an outbound header collection.
+ *
+ * The current implementation appends the Teams SDK product token to `User-Agent`, preserving
+ * any existing incoming or outgoing User-Agent value.
+ *
+ * @param headers - Header propagation collection for the current request.
+ */
+export function applyTeamsHeaderPropagation (headers: HeaderPropagationCollection): void {
+  const userAgentKey = headers.key?.(USER_AGENT_HEADER) ?? USER_AGENT_HEADER
+  const userAgent = headers.outgoing[userAgentKey] ?? headers.incoming[userAgentKey]
+
+  if (!userAgent) {
+    headers.add({ [userAgentKey]: TEAMS_USER_AGENT_PRODUCT })
+  } else if (!userAgent.includes(TEAMS_USER_AGENT_PRODUCT)) {
+    headers.concat({ [userAgentKey]: TEAMS_USER_AGENT_PRODUCT })
+  } else if (!headers.outgoing[userAgentKey]) {
+    headers.propagate([userAgentKey])
+  }
+}

package/src/teamsModelExtensions.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { MessagingExtensionAction, TaskModuleRequest } from '@microsoft/teams.api'
+
+type TeamsDataContainer = Pick<TaskModuleRequest, 'data'> | Pick<MessagingExtensionAction, 'data'> | null | undefined
+
+function hasDataProperty (value: unknown): value is { data?: unknown } {
+  return typeof value === 'object' && value !== null && Object.prototype.hasOwnProperty.call(value, 'data')
+}
+
+function getSourceData (source: TeamsDataContainer | unknown): unknown {
+  return hasDataProperty(source) ? source.data : source
+}
+
+/**
+ * Gets the data payload from a Teams task module request or message extension action as the specified type.
+ *
+ * @param request - Teams request or action that contains a `data` payload.
+ * @returns The data payload cast to the requested type, or undefined when no data is present.
+ */
+export function teamsGetDataAs<T = unknown> (request: TeamsDataContainer): T | undefined {
+  return request?.data == null ? undefined : request.data as T
+}
+
+/**
+ * Gets a string property from a Teams task module request, message extension action, or raw data object.
+ *
+ * @param source - Teams request, Teams action, or raw data object to inspect.
+ * @param key - Property name to read from the data object.
+ * @param defaultValue - Value returned when the property is missing or is not a string.
+ * @returns The string property value, the default value, or an empty string.
+ */
+export function teamsGetDataString (source: TeamsDataContainer | unknown, key: string, defaultValue?: string): string {
+  const data = getSourceData(source)
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+    return defaultValue ?? ''
+  }
+
+  const value = (data as Record<string, unknown>)[key]
+  return typeof value === 'string' ? value : defaultValue ?? ''
+}

package/src/teamsProactiveServiceEndpoints.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * Well-known service endpoint URLs for sending proactive messages to Microsoft Teams.
+ * Use these only if the incoming request serviceUrl is unavailable; once a serviceUrl
+ * has been returned from a prior conversation, cache and use that value instead.
+ */
+export const TeamsProactiveServiceEndpoints = {
+  /** Service endpoint for the public global Teams environment. */
+  publicGlobal: 'https://smba.trafficmanager.net/teams/',
+  /** Service endpoint for the GCC (Government Community Cloud) Teams environment. */
+  gcc: 'https://smba.infra.gcc.teams.microsoft.com/teams',
+  /** Service endpoint for the GCC High Teams environment. */
+  gccHigh: 'https://smba.infra.gov.teams.microsoft.us/teams',
+  /** Service endpoint for the DoD (Department of Defense) Teams environment. */
+  dod: 'https://smba.infra.dod.teams.microsoft.us/teams'
+} as const

package/src/teamsRouteHandler.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { RouteHandler, TurnContext, TurnState } from '@microsoft/agents-hosting'
+import { TeamsTurnContext } from './teamsTurnContext'
+
+/**
+ * Route handler that receives a Teams-specific turn context.
+ */
+export type TeamsRouteHandler<TState extends TurnState> = (context: TeamsTurnContext, state: TState) => Promise<void>
+
+/**
+ * Wraps a Teams route handler so it can be registered with an agent application route.
+ *
+ * @param handler - Handler that expects a Teams turn context.
+ * @returns A route handler that creates a Teams turn context for the current turn.
+ */
+export function createTeamsRouteHandler<TState extends TurnState> (handler: TeamsRouteHandler<TState>): RouteHandler<TState> {
+  return async (context: TurnContext, state: TState) => {
+    await handler(new TeamsTurnContext(context), state)
+  }
+}

package/src/teamsTurnContext.ts

@@ -0,0 +1,125 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { Activity, ExceptionHelper } from '@microsoft/agents-activity'
+import { Client as GraphClient } from '@microsoft/microsoft-graph-client'
+import { AgentApplication, type Authorization, type Connections, ResourceResponse, TurnContext } from '@microsoft/agents-hosting'
+import { Client as TeamsClient } from '@microsoft/teams.api'
+import { Errors } from './errorHelper'
+import type { TeamsActivity } from './teamsActivity'
+import { TeamsClientKey } from './teamsApiClientExtensions'
+import { createAppGraphClient, createUserGraphClient } from './graphClientFactory'
+
+const DEFAULT_GRAPH_BASE_URL = 'https://graph.microsoft.com/v1.0'
+
+/**
+ * Turn context wrapper that exposes Teams-specific helpers for a Teams activity turn.
+ */
+export class TeamsTurnContext extends TurnContext {
+  /**
+   * Gets the incoming activity with strongly typed Teams channel data.
+   *
+   * @remarks
+   * The returned object is the original turn activity. This getter only narrows
+   * its TypeScript type and does not convert or clone the activity.
+   */
+  override get activity (): TeamsActivity {
+    return super.activity as TeamsActivity
+  }
+
+  /**
+   * Gets the Teams API client for the current turn.
+   *
+   * @returns The Teams API client configured for the activity's service URL.
+   * @throws If the Teams API client is not available in turn state.
+   */
+  get client (): TeamsClient {
+    const teamsClient = this.turnState.get<TeamsClient>(TeamsClientKey)
+    if (!teamsClient) {
+      throw ExceptionHelper.generateException(Error, Errors.TeamsApiClientNotAvailable)
+    }
+    return teamsClient
+  }
+
+  /**
+   * Sends a cloned copy of an activity as a Teams targeted activity.
+   *
+   * @param activity - The activity to send to the targeted recipient.
+   * @returns The resource response for the sent activity, if provided by the adapter.
+   */
+  async sendTargetedActivity (activity: Activity): Promise<ResourceResponse | undefined> {
+    const targetedActivity = Activity.fromObject(activity)
+    targetedActivity.makeTargetedActivity()
+    return await this.sendActivity(targetedActivity)
+  }
+
+  /**
+   * Sends cloned copies of activities as Teams targeted activities.
+   *
+   * @param activities - The activities to send to targeted recipients.
+   * @returns Resource responses for the sent activities.
+   */
+  async sendTargetedActivities (activities: Activity[]): Promise<ResourceResponse[]> {
+    const targetedActivities = activities.map((activity) => {
+      const targetedActivity = Activity.fromObject(activity)
+      targetedActivity.makeTargetedActivity()
+      return targetedActivity
+    })
+    return await this.sendActivities(targetedActivities)
+  }
+
+  /**
+   * Creates a Microsoft Graph client authenticated with a delegated token for the current user.
+   *
+   * @param handlerName - Optional authorization handler name. Required when multiple handlers are configured.
+   * @param graphBaseUrl - Optional Graph base URL. Defaults to Microsoft Graph v1.0.
+   * @returns A Microsoft Graph client configured with delegated permissions.
+   */
+  getGraphClient (handlerName?: string, graphBaseUrl: string = DEFAULT_GRAPH_BASE_URL): GraphClient {
+    return createUserGraphClient(this.getUserAuthorization(), this, handlerName, graphBaseUrl)
+  }
+
+  /**
+   * Creates a Microsoft Graph client authenticated with an app-only token from the current turn's connection.
+   *
+   * @param graphBaseUrl - Optional Graph base URL. Defaults to Microsoft Graph v1.0.
+   * @returns A Microsoft Graph client configured with application permissions.
+   */
+  getAppGraphClient (graphBaseUrl: string = DEFAULT_GRAPH_BASE_URL): GraphClient {
+    const tokenProvider = this.getConnections().getTokenProviderFromActivity(this.identity, this.activity)
+    return createAppGraphClient(tokenProvider, graphBaseUrl)
+  }
+
+  /**
+   * Creates a Microsoft Graph client authenticated with an app-only token from a named connection.
+   *
+   * @param connectionName - The configured token connection name.
+   * @param graphBaseUrl - Optional Graph base URL. Defaults to Microsoft Graph v1.0.
+   * @returns A Microsoft Graph client configured with application permissions.
+   */
+  getAppGraphClientForConnection (connectionName: string, graphBaseUrl: string = DEFAULT_GRAPH_BASE_URL): GraphClient {
+    if (!connectionName) {
+      throw ExceptionHelper.generateException(Error, Errors.TeamsGraphParameterRequired, undefined, { parameterName: 'connectionName' })
+    }
+
+    return createAppGraphClient(this.getConnections().getConnection(connectionName), graphBaseUrl)
+  }
+
+  private getUserAuthorization (): Authorization {
+    const authorization = this.turnState.get<Authorization>(AgentApplication.UserAuthorizationKey)
+    if (!authorization) {
+      throw ExceptionHelper.generateException(Error, Errors.TeamsGraphUserAuthorizationNotConfigured)
+    }
+
+    return authorization
+  }
+
+  private getConnections (): Connections {
+    const connections = this.turnState.get<Connections>(AgentApplication.ConnectionsKey)
+    if (!connections) {
+      throw ExceptionHelper.generateException(Error, Errors.TeamsGraphConnectionsNotConfigured)
+    }
+
+    return connections
+  }
+}