@microsoft/agents-hosting-extensions-msteams 1.7.2

package/dist/src/teamsApiClientExtensions.d.ts

@@ -0,0 +1,13 @@
+import { TurnContext } from '@microsoft/agents-hosting';
+/**
+ * Turn state key used to store the Teams API client for the current turn.
+ */
+export declare const TeamsClientKey: unique symbol;
+/**
+ * Creates and stores a Teams API client for the current Teams turn.
+ *
+ * @param context - Turn context whose turn state should receive the Teams client.
+ * @param channelId - Teams channel ID to match before creating the client. Defaults to `msteams`.
+ * @throws If the connector client or service URL required to create the Teams client is missing.
+ */
+export declare function setTeamsApiClient(context: TurnContext, channelId?: string): void;

package/dist/src/teamsApiClientExtensions.js

@@ -0,0 +1,41 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TeamsClientKey = void 0;
+exports.setTeamsApiClient = setTeamsApiClient;
+const agents_activity_1 = require("@microsoft/agents-activity");
+const teams_api_1 = require("@microsoft/teams.api");
+const errorHelper_1 = require("./errorHelper");
+/**
+ * Turn state key used to store the Teams API client for the current turn.
+ */
+exports.TeamsClientKey = Symbol('TeamsClient');
+/**
+ * Creates and stores a Teams API client for the current Teams turn.
+ *
+ * @param context - Turn context whose turn state should receive the Teams client.
+ * @param channelId - Teams channel ID to match before creating the client. Defaults to `msteams`.
+ * @throws If the connector client or service URL required to create the Teams client is missing.
+ */
+function setTeamsApiClient(context, channelId = 'msteams') {
+    var _a;
+    if (context.activity.channelId !== channelId || context.turnState.has(exports.TeamsClientKey)) {
+        return;
+    }
+    const connectorClient = context.turnState.get(context.adapter.ConnectorClientKey);
+    const serviceUrl = (_a = context.activity.serviceUrl) !== null && _a !== void 0 ? _a : connectorClient === null || connectorClient === void 0 ? void 0 : connectorClient.httpClient.baseURL;
+    if (!connectorClient) {
+        throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.TeamsApiClientSetupFailed, undefined, { missing: 'ConnectorClient in turnState' });
+    }
+    if (!serviceUrl) {
+        throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.TeamsApiClientSetupFailed, undefined, { missing: 'activity.serviceUrl and ConnectorClient baseURL' });
+    }
+    context.turnState.set(exports.TeamsClientKey, new teams_api_1.Client(serviceUrl, {
+        headers: getClientHeaders(connectorClient)
+    }));
+}
+function getClientHeaders(connectorClient) {
+    return { ...connectorClient.httpClient.defaultHeaders };
+}
+//# sourceMappingURL=teamsApiClientExtensions.js.map

package/dist/src/teamsApiClientExtensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teamsApiClientExtensions.js","sourceRoot":"","sources":["../../src/teamsApiClientExtensions.ts"],"names":[],"mappings":";AAAA,4DAA4D;AAC5D,kCAAkC;;;AAmBlC,8CAsBC;AAvCD,gEAA4D;AAE5D,oDAA4D;AAC5D,+CAAsC;AAEtC;;GAEG;AACU,QAAA,cAAc,GAAG,MAAM,CAAC,aAAa,CAAC,CAAA;AAEnD;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAE,OAAoB,EAAE,YAAoB,SAAS;;IACpF,IAAI,OAAO,CAAC,QAAQ,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,sBAAc,CAAC,EAAE,CAAC;QACtF,OAAM;IACR,CAAC;IAED,MAAM,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,GAAG,CAAkB,OAAO,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAClG,MAAM,UAAU,GAAG,MAAA,OAAO,CAAC,QAAQ,CAAC,UAAU,mCAAI,eAAe,aAAf,eAAe,uBAAf,eAAe,CAAE,UAAU,CAAC,OAAO,CAAA;IAErF,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,iCAAe,CAAC,iBAAiB,CAAC,KAAK,EAAE,oBAAM,CAAC,yBAAyB,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,8BAA8B,EAAE,CAAC,CAAA;IAC1I,CAAC;IAED,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,iCAAe,CAAC,iBAAiB,CAAC,KAAK,EAAE,oBAAM,CAAC,yBAAyB,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,iDAAiD,EAAE,CAAC,CAAA;IAC7J,CAAC;IAED,OAAO,CAAC,SAAS,CAAC,GAAG,CACnB,sBAAc,EACd,IAAI,kBAAW,CAAC,UAAU,EAAE;QAC1B,OAAO,EAAE,gBAAgB,CAAC,eAAe,CAAC;KAC3C,CAAC,CACH,CAAA;AACH,CAAC;AAED,SAAS,gBAAgB,CAAE,eAAgC;IACzD,OAAO,EAAE,GAAG,eAAe,CAAC,UAAU,CAAC,cAAc,EAAE,CAAA;AACzD,CAAC"}

package/dist/src/teamsHeaderPropagation.d.ts

@@ -0,0 +1,14 @@
+import type { HeaderPropagationCollection } from '@microsoft/agents-hosting';
+/**
+ * Product token appended to outbound User-Agent headers by the Teams extension.
+ */
+export declare const TEAMS_USER_AGENT_PRODUCT: string;
+/**
+ * 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 declare function applyTeamsHeaderPropagation(headers: HeaderPropagationCollection): void;

package/dist/src/teamsHeaderPropagation.js

@@ -0,0 +1,35 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEAMS_USER_AGENT_PRODUCT = void 0;
+exports.applyTeamsHeaderPropagation = applyTeamsHeaderPropagation;
+const package_json_1 = require("../package.json");
+const USER_AGENT_HEADER = 'User-Agent';
+/**
+ * Product token appended to outbound User-Agent headers by the Teams extension.
+ */
+exports.TEAMS_USER_AGENT_PRODUCT = `agents-sdk-js-teams/${package_json_1.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.
+ */
+function applyTeamsHeaderPropagation(headers) {
+    var _a, _b, _c;
+    const userAgentKey = (_b = (_a = headers.key) === null || _a === void 0 ? void 0 : _a.call(headers, USER_AGENT_HEADER)) !== null && _b !== void 0 ? _b : USER_AGENT_HEADER;
+    const userAgent = (_c = headers.outgoing[userAgentKey]) !== null && _c !== void 0 ? _c : headers.incoming[userAgentKey];
+    if (!userAgent) {
+        headers.add({ [userAgentKey]: exports.TEAMS_USER_AGENT_PRODUCT });
+    }
+    else if (!userAgent.includes(exports.TEAMS_USER_AGENT_PRODUCT)) {
+        headers.concat({ [userAgentKey]: exports.TEAMS_USER_AGENT_PRODUCT });
+    }
+    else if (!headers.outgoing[userAgentKey]) {
+        headers.propagate([userAgentKey]);
+    }
+}
+//# sourceMappingURL=teamsHeaderPropagation.js.map

package/dist/src/teamsHeaderPropagation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teamsHeaderPropagation.js","sourceRoot":"","sources":["../../src/teamsHeaderPropagation.ts"],"names":[],"mappings":";AAAA,4DAA4D;AAC5D,kCAAkC;;;AAmBlC,kEAWC;AA3BD,kDAAyC;AAEzC,MAAM,iBAAiB,GAAG,YAAY,CAAA;AACtC;;GAEG;AACU,QAAA,wBAAwB,GAAG,uBAAuB,sBAAO,EAAE,CAAA;AAExE;;;;;;;GAOG;AACH,SAAgB,2BAA2B,CAAE,OAAoC;;IAC/E,MAAM,YAAY,GAAG,MAAA,MAAA,OAAO,CAAC,GAAG,wDAAG,iBAAiB,CAAC,mCAAI,iBAAiB,CAAA;IAC1E,MAAM,SAAS,GAAG,MAAA,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,mCAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAA;IAElF,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,gCAAwB,EAAE,CAAC,CAAA;IAC3D,CAAC;SAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,gCAAwB,CAAC,EAAE,CAAC;QACzD,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,gCAAwB,EAAE,CAAC,CAAA;IAC9D,CAAC;SAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QAC3C,OAAO,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC,CAAA;IACnC,CAAC;AACH,CAAC"}

package/dist/src/teamsModelExtensions.d.ts

@@ -0,0 +1,19 @@
+import type { MessagingExtensionAction, TaskModuleRequest } from '@microsoft/teams.api';
+type TeamsDataContainer = Pick<TaskModuleRequest, 'data'> | Pick<MessagingExtensionAction, 'data'> | null | undefined;
+/**
+ * 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 declare function teamsGetDataAs<T = unknown>(request: TeamsDataContainer): T | undefined;
+/**
+ * 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 declare function teamsGetDataString(source: TeamsDataContainer | unknown, key: string, defaultValue?: string): string;
+export {};

package/dist/src/teamsModelExtensions.js

@@ -0,0 +1,38 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.teamsGetDataAs = teamsGetDataAs;
+exports.teamsGetDataString = teamsGetDataString;
+function hasDataProperty(value) {
+    return typeof value === 'object' && value !== null && Object.prototype.hasOwnProperty.call(value, 'data');
+}
+function getSourceData(source) {
+    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.
+ */
+function teamsGetDataAs(request) {
+    return (request === null || request === void 0 ? void 0 : request.data) == null ? undefined : request.data;
+}
+/**
+ * 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.
+ */
+function teamsGetDataString(source, key, defaultValue) {
+    const data = getSourceData(source);
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        return defaultValue !== null && defaultValue !== void 0 ? defaultValue : '';
+    }
+    const value = data[key];
+    return typeof value === 'string' ? value : defaultValue !== null && defaultValue !== void 0 ? defaultValue : '';
+}
+//# sourceMappingURL=teamsModelExtensions.js.map

package/dist/src/teamsModelExtensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teamsModelExtensions.js","sourceRoot":"","sources":["../../src/teamsModelExtensions.ts"],"names":[],"mappings":";AAAA,4DAA4D;AAC5D,kCAAkC;;AAoBlC,wCAEC;AAUD,gDAQC;AAlCD,SAAS,eAAe,CAAE,KAAc;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AAC3G,CAAC;AAED,SAAS,aAAa,CAAE,MAAoC;IAC1D,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAA;AACvD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,cAAc,CAAe,OAA2B;IACtE,OAAO,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,IAAI,KAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,IAAS,CAAA;AAC9D,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAAE,MAAoC,EAAE,GAAW,EAAE,YAAqB;IAC1G,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAA;IAClC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,OAAO,YAAY,aAAZ,YAAY,cAAZ,YAAY,GAAI,EAAE,CAAA;IAC3B,CAAC;IAED,MAAM,KAAK,GAAI,IAAgC,CAAC,GAAG,CAAC,CAAA;IACpD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,aAAZ,YAAY,cAAZ,YAAY,GAAI,EAAE,CAAA;AAC/D,CAAC"}

package/dist/src/teamsProactiveServiceEndpoints.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare const TeamsProactiveServiceEndpoints: {
+    /** Service endpoint for the public global Teams environment. */
+    readonly publicGlobal: "https://smba.trafficmanager.net/teams/";
+    /** Service endpoint for the GCC (Government Community Cloud) Teams environment. */
+    readonly gcc: "https://smba.infra.gcc.teams.microsoft.com/teams";
+    /** Service endpoint for the GCC High Teams environment. */
+    readonly gccHigh: "https://smba.infra.gov.teams.microsoft.us/teams";
+    /** Service endpoint for the DoD (Department of Defense) Teams environment. */
+    readonly dod: "https://smba.infra.dod.teams.microsoft.us/teams";
+};

package/dist/src/teamsProactiveServiceEndpoints.js

@@ -0,0 +1,21 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TeamsProactiveServiceEndpoints = void 0;
+/**
+ * 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.
+ */
+exports.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'
+};
+//# sourceMappingURL=teamsProactiveServiceEndpoints.js.map

package/dist/src/teamsProactiveServiceEndpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teamsProactiveServiceEndpoints.js","sourceRoot":"","sources":["../../src/teamsProactiveServiceEndpoints.ts"],"names":[],"mappings":";AAAA,4DAA4D;AAC5D,kCAAkC;;;AAElC;;;;GAIG;AACU,QAAA,8BAA8B,GAAG;IAC5C,gEAAgE;IAChE,YAAY,EAAE,wCAAwC;IACtD,mFAAmF;IACnF,GAAG,EAAE,kDAAkD;IACvD,2DAA2D;IAC3D,OAAO,EAAE,iDAAiD;IAC1D,8EAA8E;IAC9E,GAAG,EAAE,iDAAiD;CAC9C,CAAA"}

package/dist/src/teamsRouteHandler.d.ts

@@ -0,0 +1,13 @@
+import { RouteHandler, 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 declare function createTeamsRouteHandler<TState extends TurnState>(handler: TeamsRouteHandler<TState>): RouteHandler<TState>;

package/dist/src/teamsRouteHandler.js

@@ -0,0 +1,18 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTeamsRouteHandler = createTeamsRouteHandler;
+const teamsTurnContext_1 = require("./teamsTurnContext");
+/**
+ * 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.
+ */
+function createTeamsRouteHandler(handler) {
+    return async (context, state) => {
+        await handler(new teamsTurnContext_1.TeamsTurnContext(context), state);
+    };
+}
+//# sourceMappingURL=teamsRouteHandler.js.map

package/dist/src/teamsRouteHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teamsRouteHandler.js","sourceRoot":"","sources":["../../src/teamsRouteHandler.ts"],"names":[],"mappings":";AAAA,4DAA4D;AAC5D,kCAAkC;;AAgBlC,0DAIC;AAjBD,yDAAqD;AAOrD;;;;;GAKG;AACH,SAAgB,uBAAuB,CAA4B,OAAkC;IACnG,OAAO,KAAK,EAAE,OAAoB,EAAE,KAAa,EAAE,EAAE;QACnD,MAAM,OAAO,CAAC,IAAI,mCAAgB,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,CAAA;IACrD,CAAC,CAAA;AACH,CAAC"}

package/dist/src/teamsTurnContext.d.ts

@@ -0,0 +1,64 @@
+import { Activity } from '@microsoft/agents-activity';
+import { Client as GraphClient } from '@microsoft/microsoft-graph-client';
+import { ResourceResponse, TurnContext } from '@microsoft/agents-hosting';
+import { Client as TeamsClient } from '@microsoft/teams.api';
+import type { TeamsActivity } from './teamsActivity';
+/**
+ * Turn context wrapper that exposes Teams-specific helpers for a Teams activity turn.
+ */
+export declare 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.
+     */
+    get activity(): 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;
+    /**
+     * 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.
+     */
+    sendTargetedActivity(activity: Activity): Promise<ResourceResponse | undefined>;
+    /**
+     * 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.
+     */
+    sendTargetedActivities(activities: Activity[]): Promise<ResourceResponse[]>;
+    /**
+     * 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): GraphClient;
+    /**
+     * 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): GraphClient;
+    /**
+     * 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): GraphClient;
+    private getUserAuthorization;
+    private getConnections;
+}

package/dist/src/teamsTurnContext.js

@@ -0,0 +1,113 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TeamsTurnContext = void 0;
+const agents_activity_1 = require("@microsoft/agents-activity");
+const agents_hosting_1 = require("@microsoft/agents-hosting");
+const errorHelper_1 = require("./errorHelper");
+const teamsApiClientExtensions_1 = require("./teamsApiClientExtensions");
+const graphClientFactory_1 = require("./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.
+ */
+class TeamsTurnContext extends agents_hosting_1.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.
+     */
+    get activity() {
+        return super.activity;
+    }
+    /**
+     * 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() {
+        const teamsClient = this.turnState.get(teamsApiClientExtensions_1.TeamsClientKey);
+        if (!teamsClient) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.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) {
+        const targetedActivity = agents_activity_1.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) {
+        const targetedActivities = activities.map((activity) => {
+            const targetedActivity = agents_activity_1.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, graphBaseUrl = DEFAULT_GRAPH_BASE_URL) {
+        return (0, graphClientFactory_1.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 = DEFAULT_GRAPH_BASE_URL) {
+        const tokenProvider = this.getConnections().getTokenProviderFromActivity(this.identity, this.activity);
+        return (0, graphClientFactory_1.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, graphBaseUrl = DEFAULT_GRAPH_BASE_URL) {
+        if (!connectionName) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.TeamsGraphParameterRequired, undefined, { parameterName: 'connectionName' });
+        }
+        return (0, graphClientFactory_1.createAppGraphClient)(this.getConnections().getConnection(connectionName), graphBaseUrl);
+    }
+    getUserAuthorization() {
+        const authorization = this.turnState.get(agents_hosting_1.AgentApplication.UserAuthorizationKey);
+        if (!authorization) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.TeamsGraphUserAuthorizationNotConfigured);
+        }
+        return authorization;
+    }
+    getConnections() {
+        const connections = this.turnState.get(agents_hosting_1.AgentApplication.ConnectionsKey);
+        if (!connections) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.TeamsGraphConnectionsNotConfigured);
+        }
+        return connections;
+    }
+}
+exports.TeamsTurnContext = TeamsTurnContext;
+//# sourceMappingURL=teamsTurnContext.js.map

package/dist/src/teamsTurnContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teamsTurnContext.js","sourceRoot":"","sources":["../../src/teamsTurnContext.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@microsoft/agents-hosting-extensions-msteams",
+  "version": "1.7.2",
+  "homepage": "https://github.com/microsoft/Agents-for-js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microsoft/Agents-for-js.git"
+  },
+  "author": {
+    "name": "Microsoft",
+    "email": "agentssdk@microsoft.com",
+    "url": "https://aka.ms/Agents"
+  },
+  "description": "Microsoft 365 Agents SDK for JavaScript. MS Teams extensions",
+  "keywords": [
+    "Agents"
+  ],
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "dependencies": {
+    "@microsoft/agents-activity": "1.7.2",
+    "@microsoft/agents-hosting": "1.7.2",
+    "@microsoft/microsoft-graph-client": "3.0.7",
+    "@microsoft/teams.api": "2.0.14",
+    "zod": "3.25.75"
+  },
+  "license": "MIT",
+  "files": [
+    "README.md",
+    "dist/package.json",
+    "dist/src",
+    "src",
+    "package.json"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "require": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/activity-extensions/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+export { parseTeamsChannelData } from './teamsChannelData'

package/src/activity-extensions/teamsChannelData.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { z } from 'zod'
+import type { ChannelData } from '@microsoft/teams.api'
+
+/**
+ * Root-level validation for Teams channel data objects.
+ *
+ * The Teams SDK already defines the nested ChannelData shape. This parser
+ * normalizes missing root data to an empty object, verifies non-nullish input is
+ * an object, and preserves all properties as-is.
+ */
+const teamsChannelDataZodSchema = z.object({}).passthrough()
+
+/**
+ * Parses the given object as Teams ChannelData.
+ *
+ * @param {unknown} o - The value to parse.
+ * @returns {ChannelData} - The parsed ChannelData.
+ */
+export function parseTeamsChannelData (o: unknown): ChannelData {
+  if (o == null) {
+    return {} as ChannelData
+  }
+
+  return teamsChannelDataZodSchema.parse(o) as ChannelData
+}

package/src/app/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+export * from './teamsAppExtensions'