@cuylabs/agent-channel-teams 3.2.1 → 4.1.0

package/README.md

@@ -339,6 +339,68 @@ onTurn: async (context, next) => {
 },
 ```
 
+## Targeted Activities (Group Chat / Channel)
+
+Teams supports an `activityTreatment: targeted` entity that makes a reply
+visible only to one recipient inside a group conversation. Surfaced here in two
+places, both built on the `ActivityTreatments.Targeted` entity added in
+`@microsoft/agents-activity` 1.5:
+
+```ts
+import {
+  isTargetedTeamsActivity,
+  makeTargetedTeamsActivity,
+  parseTeamsActivity,
+} from "@cuylabs/agent-channel-teams";
+
+// Read on inbound: as a derived field on TeamsActivityInfo
+const teams = parseTeamsActivity(turnContext);
+if (teams.targeted) {
+  // The user explicitly asked the bot privately inside a group context
+}
+
+// Or directly from any TurnContext
+isTargetedTeamsActivity(turnContext);
+
+// Mark on outbound — only valid for group conversations
+const reply = MessageFactory.text("This response is just for you.");
+makeTargetedTeamsActivity(reply);
+await turnContext.sendActivity(reply);
+```
+
+The helper is idempotent and can be called before `TurnContext.sendActivity()`
+applies the conversation reference. Teams only honors this treatment in group
+chat and channel contexts.
+
+## Proactive Messaging
+
+`@cuylabs/agent-channel-teams/proactive` re-exports the M365 proactive bridge
+and adds a Teams-aware capture helper that bundles the `Conversation` together
+with parsed Teams metadata (tenant, surface, team, channel, meeting) so apps
+can route stored references later:
+
+```ts
+import {
+  captureTeamsConversationReference,
+  continueM365Conversation,
+} from "@cuylabs/agent-channel-teams/proactive";
+
+const capture = captureTeamsConversationReference(turnContext);
+await store.put(capture.teams.conversationId, capture);
+
+// Later:
+await continueM365Conversation(adapter, capture.conversation, async (ctx) => {
+  await ctx.sendActivity("Background work finished.");
+});
+```
+
+The upstream `Proactive` class (which is bound to `AgentApplication`) is
+intentionally not used; this package exposes the underlying
+`Conversation` / builder primitives plus a thin wrapper around
+`CloudAdapter.continueConversation`. See
+[`@cuylabs/agent-channel-m365` README](../agent-channel-m365/README.md#proactive-messaging)
+for the M365-level details and telemetry coverage.
+
 ## Docs
 
 The package README is the quick-start view. For the focused concept guides, use

package/dist/chunk-MBDHSFBF.js

@@ -0,0 +1,357 @@
+import {
+  parseTeamsChannelData
+} from "./chunk-B5KRH22J.js";
+
+// src/proactive.ts
+import {
+  captureM365ConversationReference
+} from "@cuylabs/agent-channel-m365/proactive";
+
+// src/teams-activity.ts
+import {
+  ActivityTreatments,
+  ActivityTypes
+} from "@microsoft/agents-activity";
+var ACTIVITY_TREATMENT_ENTITY_TYPE = "activityTreatment";
+function isTargetedTreatmentEntity(entity) {
+  const value = asObject(entity);
+  return value?.type === ACTIVITY_TREATMENT_ENTITY_TYPE && value.treatment === ActivityTreatments.Targeted;
+}
+function isTargetedTeamsActivity(context) {
+  const activity = context.activity;
+  const entities = activity?.entities;
+  if (!Array.isArray(entities)) return false;
+  return entities.some(isTargetedTreatmentEntity);
+}
+function makeTargetedTeamsActivity(activity) {
+  const entities = Array.isArray(activity.entities) ? activity.entities : [];
+  if (!entities.some(isTargetedTreatmentEntity)) {
+    activity.entities = [
+      ...entities,
+      {
+        type: ACTIVITY_TREATMENT_ENTITY_TYPE,
+        treatment: ActivityTreatments.Targeted
+      }
+    ];
+  }
+  return activity;
+}
+function asObject(value) {
+  return value && typeof value === "object" ? value : void 0;
+}
+function readString(value, key) {
+  const candidate = value?.[key];
+  return typeof candidate === "string" && candidate.trim() ? candidate : void 0;
+}
+function detectSurface(conversationType, meetingId, teamId) {
+  if (meetingId) return "meeting";
+  if (teamId) return "channel";
+  if (conversationType === "personal") return "personal";
+  if (conversationType === "groupChat") return "group";
+  return "unknown";
+}
+function includesName(names, candidate) {
+  return !!candidate && names.includes(candidate);
+}
+function parseTypedChannelData(channelData, options = {}) {
+  if (!channelData) return void 0;
+  try {
+    return parseTeamsChannelData(channelData);
+  } catch (error) {
+    if (options.strictChannelData ?? true) {
+      throw error;
+    }
+    return void 0;
+  }
+}
+var TEAMS_CONFIG_FETCH_NAMES = ["config/fetch"];
+var TEAMS_CONFIG_SUBMIT_NAMES = ["config/submit"];
+var TEAMS_FILE_CONSENT_NAMES = ["fileConsent/invoke"];
+var TEAMS_ACTIONABLE_MESSAGE_NAMES = [
+  "actionableMessage/executeAction"
+];
+var TEAMS_ADAPTIVE_CARD_ACTION_NAMES = [
+  "adaptiveCard/action"
+];
+var TEAMS_ADAPTIVE_CARD_SEARCH_NAMES = ["application/search"];
+var TEAMS_TASK_MODULE_FETCH_NAMES = [
+  "task/fetch",
+  "composeExtension/fetchTask"
+];
+var TEAMS_TASK_MODULE_SUBMIT_NAMES = ["task/submit"];
+var TEAMS_TAB_FETCH_NAMES = ["tab/fetch"];
+var TEAMS_TAB_SUBMIT_NAMES = ["tab/submit"];
+var TEAMS_MESSAGE_EXTENSION_QUERY_NAMES = [
+  "composeExtension/query",
+  "composeExtension/queryLink",
+  "composeExtension/anonymousQueryLink"
+];
+var TEAMS_MESSAGE_EXTENSION_SUBMIT_ACTION_NAMES = [
+  "composeExtension/submitAction"
+];
+var TEAMS_MESSAGE_EXTENSION_FETCH_TASK_NAMES = [
+  "composeExtension/fetchTask"
+];
+var TEAMS_MESSAGE_EXTENSION_QUERY_SETTING_URL_NAMES = [
+  "composeExtension/querySettingUrl"
+];
+var TEAMS_MESSAGE_EXTENSION_SETTING_NAMES = [
+  "composeExtension/setting"
+];
+var TEAMS_MESSAGE_EXTENSION_CARD_BUTTON_CLICKED_NAMES = [
+  "composeExtension/onCardButtonClicked"
+];
+var TEAMS_MESSAGE_EXTENSION_SELECT_NAMES = [
+  "composeExtension/selectItem"
+];
+var TEAMS_CARD_ACTION_SUBMIT_NAMES = ["message/submitAction"];
+var TEAMS_CONVERSATION_UPDATE_EVENT_NAMES = {
+  channelCreated: "channel-created",
+  channelDeleted: "channel-deleted",
+  channelRenamed: "channel-renamed",
+  channelRestored: "channel-restored",
+  channelShared: "channel-shared",
+  channelUnshared: "channel-unshared",
+  teamRenamed: "team-renamed",
+  teamArchived: "team-archived",
+  teamUnarchived: "team-unarchived",
+  teamDeleted: "team-deleted",
+  teamHardDeleted: "team-hard-deleted",
+  teamRestored: "team-restored"
+};
+var TEAMS_MEETING_EVENT_NAMES = {
+  "application/vnd.microsoft.readReceipt": "read-receipt",
+  "application/vnd.microsoft.meetingStart": "meeting-start",
+  "application/vnd.microsoft.meetingEnd": "meeting-end",
+  "application/vnd.microsoft.meetingParticipantJoin": "participants-join",
+  "application/vnd.microsoft.meetingParticipantLeave": "participants-leave",
+  "application/vnd.microsoft.meetingRoomJoin": "meeting-room-join",
+  "application/vnd.microsoft.meetingRoomLeave": "meeting-room-leave",
+  "application/vnd.microsoft.meetingReaction": "meeting-reaction",
+  "application/vnd.microsoft.meetingPollResponse": "meeting-poll-response",
+  "application/vnd.microsoft.meetingAppsInstalled": "meeting-apps-installed",
+  "application/vnd.microsoft.meetingAppsUninstalled": "meeting-apps-uninstalled",
+  "application/vnd.microsoft.meetingRecordingStarted": "meeting-recording-started",
+  "application/vnd.microsoft.meetingRecordingStopped": "meeting-recording-stopped",
+  "application/vnd.microsoft.meetingFocusChange": "meeting-focus-change",
+  "application/vnd.microsoft.meetingScreenShareStart": "meeting-screen-share-start",
+  "application/vnd.microsoft.meetingScreenShareStop": "meeting-screen-share-stop"
+};
+var TEAMS_MEETING_INVOKE_NAMES = {
+  "application/vnd.microsoft.meetingStageView": "meeting-stage-view",
+  "application/vnd.microsoft.meetingSmartReply": "meeting-smart-reply"
+};
+function detectKind(context, eventType) {
+  const { activity } = context;
+  const payload = asObject(activity.value);
+  const invokeName = activity.name;
+  switch (activity.type) {
+    case ActivityTypes.Message:
+      return "message";
+    case ActivityTypes.MessageReaction:
+      return "reaction";
+    case ActivityTypes.ConversationUpdate:
+      if (Array.isArray(activity.membersAdded) && activity.membersAdded.length > 0) {
+        return "members-added";
+      }
+      if (Array.isArray(activity.membersRemoved) && activity.membersRemoved.length > 0) {
+        return "members-removed";
+      }
+      if (eventType && eventType in TEAMS_CONVERSATION_UPDATE_EVENT_NAMES) {
+        return TEAMS_CONVERSATION_UPDATE_EVENT_NAMES[eventType];
+      }
+      return "conversation-update";
+    case ActivityTypes.MessageUpdate:
+      if (eventType === "editMessage") return "message-edit";
+      if (eventType === "undeleteMessage") return "message-restore";
+      return "other";
+    case ActivityTypes.MessageDelete:
+      if (eventType === "softDeleteMessage") return "message-delete";
+      return "other";
+    case ActivityTypes.Event:
+      if (invokeName && invokeName in TEAMS_MEETING_EVENT_NAMES) {
+        return TEAMS_MEETING_EVENT_NAMES[invokeName];
+      }
+      return "other";
+    case ActivityTypes.Invoke:
+      if (invokeName && invokeName in TEAMS_MEETING_INVOKE_NAMES) {
+        return TEAMS_MEETING_INVOKE_NAMES[invokeName];
+      }
+      if (includesName(TEAMS_CONFIG_FETCH_NAMES, invokeName)) {
+        return "config-fetch";
+      }
+      if (includesName(TEAMS_CONFIG_SUBMIT_NAMES, invokeName)) {
+        return "config-submit";
+      }
+      if (includesName(TEAMS_FILE_CONSENT_NAMES, invokeName)) {
+        return "file-consent";
+      }
+      if (includesName(TEAMS_ACTIONABLE_MESSAGE_NAMES, invokeName)) {
+        return "actionable-message-execute-action";
+      }
+      if (includesName(TEAMS_ADAPTIVE_CARD_ACTION_NAMES, invokeName)) {
+        return "adaptive-card-action";
+      }
+      if (includesName(TEAMS_ADAPTIVE_CARD_SEARCH_NAMES, invokeName)) {
+        return "adaptive-card-search";
+      }
+      if (includesName(TEAMS_TASK_MODULE_FETCH_NAMES, invokeName)) {
+        return invokeName === "composeExtension/fetchTask" ? "message-extension-fetch-task" : "task-fetch";
+      }
+      if (includesName(TEAMS_TASK_MODULE_SUBMIT_NAMES, invokeName)) {
+        return "task-submit";
+      }
+      if (includesName(TEAMS_TAB_FETCH_NAMES, invokeName)) {
+        return "tab-fetch";
+      }
+      if (includesName(TEAMS_TAB_SUBMIT_NAMES, invokeName)) {
+        return "tab-submit";
+      }
+      if (includesName(TEAMS_MESSAGE_EXTENSION_QUERY_NAMES, invokeName)) {
+        switch (invokeName) {
+          case "composeExtension/queryLink":
+            return "message-extension-query-link";
+          case "composeExtension/anonymousQueryLink":
+            return "message-extension-anonymous-query-link";
+          default:
+            return "message-extension-query";
+        }
+      }
+      if (includesName(TEAMS_MESSAGE_EXTENSION_SELECT_NAMES, invokeName)) {
+        return "message-extension-select-item";
+      }
+      if (includesName(TEAMS_MESSAGE_EXTENSION_SUBMIT_ACTION_NAMES, invokeName)) {
+        return "message-extension-submit-action";
+      }
+      if (includesName(
+        TEAMS_MESSAGE_EXTENSION_QUERY_SETTING_URL_NAMES,
+        invokeName
+      )) {
+        return "message-extension-query-setting-url";
+      }
+      if (includesName(TEAMS_MESSAGE_EXTENSION_SETTING_NAMES, invokeName)) {
+        return "message-extension-setting";
+      }
+      if (includesName(
+        TEAMS_MESSAGE_EXTENSION_CARD_BUTTON_CLICKED_NAMES,
+        invokeName
+      )) {
+        return "message-extension-card-button-clicked";
+      }
+      if (includesName(TEAMS_CARD_ACTION_SUBMIT_NAMES, invokeName)) {
+        return payload?.actionName === "feedback" ? "feedback" : "card-submit";
+      }
+      return "invoke";
+    default:
+      return "other";
+  }
+}
+function parseActors(channelData) {
+  const raw = channelData?.onBehalfOf;
+  if (!Array.isArray(raw)) return [];
+  const actors = [];
+  for (const item of raw) {
+    const actor = asObject(item);
+    const itemRef = asObject(actor?.item);
+    actors.push({
+      id: readString(itemRef, "id"),
+      displayName: readString(itemRef, "displayName"),
+      tenantId: readString(actor, "tenantId"),
+      userPrincipalName: readString(itemRef, "userPrincipalName")
+    });
+  }
+  return actors.filter(
+    (actor) => actor.id !== void 0 || actor.displayName !== void 0 || actor.userPrincipalName !== void 0
+  );
+}
+function parseTeamsActivity(context, options = {}) {
+  const { activity } = context;
+  const channelData = asObject(activity.channelData);
+  const parsedChannelData = parseTypedChannelData(channelData, options);
+  const team = asObject(channelData?.team);
+  const channel = asObject(channelData?.channel);
+  const tenant = asObject(channelData?.tenant);
+  const meeting = asObject(channelData?.meeting);
+  const eventType = parsedChannelData?.eventType ?? readString(channelData, "eventType");
+  const conversationType = typeof activity.conversation?.conversationType === "string" ? activity.conversation.conversationType : void 0;
+  const teamId = parsedChannelData?.team?.aadGroupId ?? parsedChannelData?.team?.id ?? readString(team, "aadGroupId") ?? readString(team, "id");
+  const meetingId = parsedChannelData?.meeting?.id ?? readString(meeting, "id");
+  const surface = detectSurface(
+    conversationType,
+    meetingId,
+    teamId
+  );
+  return {
+    channelId: activity.channelId ?? "unknown",
+    conversationId: activity.conversation?.id ?? "unknown",
+    activityId: activity.id ?? void 0,
+    messageId: activity.id ?? void 0,
+    replyToId: activity.replyToId ?? void 0,
+    invokeName: activity.name ?? void 0,
+    eventType,
+    tenantId: parsedChannelData?.tenant?.id ?? readString(tenant, "id") ?? activity.conversation?.tenantId,
+    teamId,
+    channelData: parsedChannelData,
+    channelThreadId: parsedChannelData?.channel?.id ?? readString(channel, "id"),
+    meetingId,
+    surface,
+    kind: detectKind(context, eventType),
+    actors: parseActors(channelData),
+    targeted: isTargetedTeamsActivity(context)
+  };
+}
+function parseTeamsActivitySafe(context) {
+  return parseTeamsActivity(context, { strictChannelData: false });
+}
+
+// src/proactive.ts
+import {
+  Conversation,
+  ConversationBuilder,
+  ConversationReferenceBuilder,
+  CreateConversationOptionsBuilder,
+  captureM365ConversationReference as captureM365ConversationReference2,
+  continueM365Conversation,
+  restoreM365ConversationReference
+} from "@cuylabs/agent-channel-m365/proactive";
+function captureTeamsConversationReference(context) {
+  const conversation = captureM365ConversationReference(context);
+  const teams = parseTeamsActivity(context, { strictChannelData: false });
+  return { conversation, teams };
+}
+
+export {
+  isTargetedTeamsActivity,
+  makeTargetedTeamsActivity,
+  TEAMS_CONFIG_FETCH_NAMES,
+  TEAMS_CONFIG_SUBMIT_NAMES,
+  TEAMS_FILE_CONSENT_NAMES,
+  TEAMS_ACTIONABLE_MESSAGE_NAMES,
+  TEAMS_ADAPTIVE_CARD_ACTION_NAMES,
+  TEAMS_ADAPTIVE_CARD_SEARCH_NAMES,
+  TEAMS_TASK_MODULE_FETCH_NAMES,
+  TEAMS_TASK_MODULE_SUBMIT_NAMES,
+  TEAMS_TAB_FETCH_NAMES,
+  TEAMS_TAB_SUBMIT_NAMES,
+  TEAMS_MESSAGE_EXTENSION_QUERY_NAMES,
+  TEAMS_MESSAGE_EXTENSION_SUBMIT_ACTION_NAMES,
+  TEAMS_MESSAGE_EXTENSION_FETCH_TASK_NAMES,
+  TEAMS_MESSAGE_EXTENSION_QUERY_SETTING_URL_NAMES,
+  TEAMS_MESSAGE_EXTENSION_SETTING_NAMES,
+  TEAMS_MESSAGE_EXTENSION_CARD_BUTTON_CLICKED_NAMES,
+  TEAMS_MESSAGE_EXTENSION_SELECT_NAMES,
+  TEAMS_CARD_ACTION_SUBMIT_NAMES,
+  TEAMS_CONVERSATION_UPDATE_EVENT_NAMES,
+  TEAMS_MEETING_EVENT_NAMES,
+  TEAMS_MEETING_INVOKE_NAMES,
+  parseTeamsActivity,
+  parseTeamsActivitySafe,
+  captureTeamsConversationReference,
+  Conversation,
+  ConversationBuilder,
+  ConversationReferenceBuilder,
+  CreateConversationOptionsBuilder,
+  captureM365ConversationReference2 as captureM365ConversationReference,
+  continueM365Conversation,
+  restoreM365ConversationReference
+};