@microsoft/agents-hosting 1.5.0-beta.1.g77c44097fe → 1.5.0-beta.12.ga9a2b23c19

package/src/app/proactive/conversationReferenceBuilder.ts

@@ -0,0 +1,161 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { ChannelAccount, ConversationReference } from '@microsoft/agents-activity'
+import { Channels, RoleTypes } from '@microsoft/agents-activity'
+import { debug } from '@microsoft/agents-activity/logger'
+
+const logger = debug('agents:conversation-reference-builder')
+
+/** Set of all channel IDs defined in the Channels enum, used for validation. */
+const knownChannelIds = new Set(Object.values(Channels) as string[])
+
+/**
+ * Well-known Teams service URLs for proactive messaging.
+ *
+ * Use only when the incoming `serviceUrl` from a real conversation is unavailable.
+ * Once you have received a `serviceUrl` from a real turn, cache and prefer that value.
+ */
+export const TeamsServiceEndpoints = {
+  /** Standard public cloud Teams endpoint. */
+  publicGlobal: 'https://smba.trafficmanager.net/teams/',
+  /** US Government Community Cloud (GCC). */
+  gcc: 'https://smba.infra.gcc.teams.microsoft.com/teams',
+  /** US Government Community Cloud High (GCC-High). */
+  gccHigh: 'https://smba.infra.gov.teams.microsoft.us/teams',
+  /** US Department of Defense (DoD). */
+  dod: 'https://smba.infra.dod.teams.microsoft.us/teams',
+} as const
+
+/**
+ * Fluent builder for `ConversationReference`.
+ */
+export class ConversationReferenceBuilder {
+  private readonly _channelId: string
+  private _serviceUrl: string
+  private _agent: ChannelAccount
+  private _user?: ChannelAccount
+  private _conversationId?: string
+  private _activityId?: string
+  private _locale?: string
+
+  private constructor (channelId: string, serviceUrl: string, agent: ChannelAccount) {
+    this._channelId = channelId
+    this._serviceUrl = serviceUrl
+    this._agent = agent
+  }
+
+  /**
+   * Creates a new builder seeded with the agent identity and channel.
+   * On Teams, the agent id is prefixed with `28:` automatically.
+   * @param agentClientId The agent's client (app) ID.
+   * @param channelId The target channel (e.g. `'msteams'`, `'webchat'`).
+   * @param serviceUrl Optional override. If omitted, `build()` fills in the
+   *   channel default via `serviceUrlForChannel()`.
+   */
+  static create (
+    agentClientId: string,
+    channelId: string,
+    serviceUrl?: string
+  ): ConversationReferenceBuilder {
+    return new ConversationReferenceBuilder(
+      channelId,
+      serviceUrl ?? '',
+      ConversationReferenceBuilder.agentForChannel(channelId, agentClientId)
+    )
+  }
+
+  /**
+   * Returns the default service URL for a channel.
+   * Teams returns the public global endpoint; all other channels use the
+   * `https://{channelId}.botframework.com/` pattern (matching C# behavior).
+   */
+  static serviceUrlForChannel (channelId: string): string {
+    if (!channelId) return ''
+    if (channelId === Channels.Msteams) return TeamsServiceEndpoints.publicGlobal
+    if (!knownChannelIds.has(channelId)) {
+      logger.warn(
+        `serviceUrlForChannel: unrecognized channelId '${channelId}' — constructing fallback URL ` +
+        'https://<channelId>.botframework.com/. Provide an explicit serviceUrl to suppress this warning.'
+      )
+    }
+    return `https://${channelId}.botframework.com/`
+  }
+
+  /** Sets `reference.user` from an id + optional name. Role defaults to `RoleTypes.User`. */
+  withUser (userId: string, userName?: string): this
+  /** Sets `reference.user` from a full `ChannelAccount`. */
+  withUser (account: ChannelAccount): this
+  withUser (userIdOrAccount: string | ChannelAccount, userName?: string): this {
+    this._user = typeof userIdOrAccount === 'string'
+      ? { id: userIdOrAccount, name: userName, role: RoleTypes.User }
+      : userIdOrAccount
+    return this
+  }
+
+  /** Sets `reference.agent` from an id + optional name. Role defaults to `RoleTypes.Agent`. On Teams, id is prefixed with `28:`. */
+  withAgent (agentClientId: string, agentName?: string): this
+  /** Sets `reference.agent` from a full `ChannelAccount`. */
+  withAgent (account: ChannelAccount): this
+  withAgent (agentIdOrAccount: string | ChannelAccount, agentName?: string): this {
+    this._agent = typeof agentIdOrAccount === 'string'
+      ? ConversationReferenceBuilder.agentForChannel(this._channelId, agentIdOrAccount, agentName)
+      : agentIdOrAccount
+    return this
+  }
+
+  /** Sets `reference.serviceUrl`. */
+  withServiceUrl (serviceUrl: string): this {
+    this._serviceUrl = serviceUrl
+    return this
+  }
+
+  /** Sets `reference.conversation.id`. */
+  withConversationId (id: string): this {
+    this._conversationId = id
+    return this
+  }
+
+  /** Sets `reference.activityId`. */
+  withActivityId (activityId: string): this {
+    this._activityId = activityId
+    return this
+  }
+
+  /** Sets `reference.locale`. */
+  withLocale (locale: string): this {
+    this._locale = locale
+    return this
+  }
+
+  /** Builds and returns the `ConversationReference`. */
+  build (): ConversationReference {
+    const serviceUrl =
+      this._serviceUrl || ConversationReferenceBuilder.serviceUrlForChannel(this._channelId)
+
+    const ref: ConversationReference = {
+      channelId: this._channelId,
+      serviceUrl,
+      conversation: { id: this._conversationId ?? '', isGroup: false },
+      agent: this._agent,
+      user: this._user ?? { role: RoleTypes.User },
+    }
+
+    if (this._activityId !== undefined) ref.activityId = this._activityId
+    if (this._locale !== undefined) ref.locale = this._locale
+
+    return ref
+  }
+
+  /**
+   * Builds a `ChannelAccount` for the agent, applying the Teams `28:` id prefix
+   * when the channel is `msteams`.
+   */
+  private static agentForChannel (channelId: string, agentClientId: string, agentName?: string): ChannelAccount {
+    return {
+      id: channelId === Channels.Msteams ? `28:${agentClientId}` : agentClientId,
+      name: agentName,
+      role: RoleTypes.Agent,
+    }
+  }
+}

package/src/app/proactive/createConversationOptions.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { ConversationParameters } from '@microsoft/agents-activity'
+import type { ConversationClaims } from './conversation'
+
+/**
+ * Default OAuth scope for Azure Bot Service authentication.
+ */
+export const AzureBotScope = 'https://api.botframework.com'
+
+/**
+ * Options passed to `Proactive.createConversation()`.
+ * Flattened — no nested Conversation wrapper.
+ */
+export interface CreateConversationOptions {
+  /** JWT claims for the agent identity. `aud` must be the agent's client ID. */
+  identity: ConversationClaims
+  /** The target channel (e.g. `'msteams'`). */
+  channelId: string
+  /** The service URL for the channel. */
+  serviceUrl: string
+  /**
+   * OAuth scope for token acquisition.
+   * Defaults to `AzureBotScope` when not set by the builder.
+   */
+  scope: string
+  /**
+   * When `true`, the resulting `Conversation` is stored automatically after
+   * creation. Defaults to `false`.
+   */
+  storeConversation?: boolean
+  /** Conversation configuration passed to `adapter.createConversationAsync()`. */
+  parameters: Partial<ConversationParameters>
+}

package/src/app/proactive/createConversationOptionsBuilder.ts

@@ -0,0 +1,181 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { Activity, ChannelAccount, ConversationParameters } from '@microsoft/agents-activity'
+import { Channels, ExceptionHelper, RoleTypes } from '@microsoft/agents-activity'
+import { Errors } from '../../errorHelper'
+import { AzureBotScope, type CreateConversationOptions } from './createConversationOptions'
+import type { ConversationClaims } from './conversation'
+import { ConversationReferenceBuilder } from './conversationReferenceBuilder'
+
+/**
+ * Fluent builder for `CreateConversationOptions`.
+ *
+ * @example
+ * ```typescript
+ * const opts = CreateConversationOptionsBuilder
+ *   .create('my-client-id', 'msteams')
+ *   .withUser('user-aad-id')
+ *   .withTenantId('tenant-id')
+ *   .build()
+ * ```
+ */
+export class CreateConversationOptionsBuilder {
+  private readonly _claims: ConversationClaims
+  private readonly _channelId: string
+  private readonly _serviceUrl: string
+  private _scope: string = AzureBotScope
+  private _storeConversation: boolean = false
+  private _parameters: Partial<ConversationParameters> = {
+    channelData: {},
+  }
+
+  private _activity: Partial<Activity> | undefined
+
+  private constructor (claims: ConversationClaims, channelId: string, serviceUrl?: string) {
+    this._claims = claims
+    this._channelId = channelId
+    this._serviceUrl =
+      serviceUrl ?? ConversationReferenceBuilder.serviceUrlForChannel(channelId)
+  }
+
+  /**
+   * Creates a new builder from an agent client ID string.
+   * @param agentClientId The agent's client (app) ID.
+   * @param channelId The target channel (e.g. `'msteams'`).
+   * @param serviceUrl Optional service URL override.
+   */
+  static create (agentClientId: string, channelId: string, serviceUrl?: string, parameters?: Partial<ConversationParameters>): CreateConversationOptionsBuilder
+  /**
+   * Creates a new builder from an existing claims object (e.g. from a stored `Conversation`).
+   * @param claims JWT claims — `aud` must be the agent's client ID.
+   * @param channelId The target channel (e.g. `'msteams'`).
+   * @param serviceUrl Optional service URL override.
+   */
+  static create (claims: ConversationClaims, channelId: string, serviceUrl?: string, parameters?: Partial<ConversationParameters>): CreateConversationOptionsBuilder
+  static create (
+    agentClientIdOrClaims: string | ConversationClaims,
+    channelId: string,
+    serviceUrl?: string,
+    parameters?: Partial<ConversationParameters>
+  ): CreateConversationOptionsBuilder {
+    const claims: ConversationClaims = typeof agentClientIdOrClaims === 'string'
+      ? { aud: agentClientIdOrClaims }
+      : agentClientIdOrClaims
+
+    const builder = new CreateConversationOptionsBuilder(claims, channelId, serviceUrl)
+    if (parameters) {
+      builder._parameters = { ...builder._parameters, ...parameters }
+    }
+
+    // Set parameters.agent if not already provided — matches C# behavior
+    if (!builder._parameters.agent) {
+      builder._parameters.agent = { id: claims.aud, role: RoleTypes.Agent }
+    }
+
+    return builder
+  }
+
+  /** Adds a member (the target user) to `parameters.members`. */
+  withUser (userId: string, userName?: string): this
+  withUser (account: ChannelAccount): this
+  withUser (userIdOrAccount: string | ChannelAccount, userName?: string): this {
+    const account: ChannelAccount =
+      typeof userIdOrAccount === 'string'
+        ? { id: userIdOrAccount, name: userName }
+        : userIdOrAccount
+    const members = this._parameters.members ?? []
+    members.push(account)
+    this._parameters = { ...this._parameters, members }
+    return this
+  }
+
+  /** Sets `parameters.activity`. Defaults `activity.type` to `'message'` if not provided. */
+  withActivity (activity: Partial<Activity>): this {
+    this._activity = activity
+    return this
+  }
+
+  /** Merges additional channel-specific data into `parameters.channelData`. */
+  withChannelData (data: object): this {
+    this._parameters = {
+      ...this._parameters,
+      channelData: { ...(this._parameters.channelData as object ?? {}), ...data },
+    }
+    return this
+  }
+
+  /**
+   * Sets `parameters.tenantId`.
+   * On `msteams` channels, also sets `channelData.tenant.id`.
+   */
+  withTenantId (tenantId: string): this {
+    this._parameters = { ...this._parameters, tenantId }
+    if (this._channelId === Channels.Msteams) {
+      this.withChannelData({ tenant: { id: tenantId } })
+    }
+    return this
+  }
+
+  /**
+   * Sets `parameters.isGroup = true` and `channelData.channel.id`.
+   * Only has effect on `msteams` channels.
+   */
+  withTeamsChannelId (teamsChannelId: string): this {
+    if (this._channelId !== Channels.Msteams) return this
+    this._parameters = { ...this._parameters, isGroup: true }
+    this.withChannelData({ channel: { id: teamsChannelId } })
+    return this
+  }
+
+  /** Sets `parameters.topicName`. */
+  withTopicName (name: string): this {
+    this._parameters = { ...this._parameters, topicName: name }
+    return this
+  }
+
+  /** Sets `parameters.isGroup`. */
+  isGroup (value: boolean): this {
+    this._parameters = { ...this._parameters, isGroup: value }
+    return this
+  }
+
+  /** Overrides the default `AzureBotScope` OAuth scope. */
+  withScope (scope: string): this {
+    this._scope = scope
+    return this
+  }
+
+  /** Controls whether the resulting conversation is stored after creation. */
+  storeConversation (value: boolean): this {
+    this._storeConversation = value
+    return this
+  }
+
+  /**
+   * Builds and returns `CreateConversationOptions`.
+   * @throws if no members were added via `withUser()`.
+   */
+  build (): CreateConversationOptions {
+    if (!this._parameters.members?.length) {
+      throw ExceptionHelper.generateException(Error, Errors.CreateConversationBuilderMembersRequired)
+    }
+
+    const activity: Partial<Activity> = {
+      type: 'message',
+      ...this._activity,
+    }
+
+    return {
+      identity: this._claims,
+      channelId: this._channelId,
+      serviceUrl: this._serviceUrl,
+      scope: this._scope,
+      storeConversation: this._storeConversation,
+      parameters: {
+        ...this._parameters,
+        activity: activity as Activity,
+      },
+    }
+  }
+}

package/src/app/proactive/index.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+export * from './conversation'
+export * from './conversationBuilder'
+export * from './conversationReferenceBuilder'
+export * from './createConversationOptions'
+export * from './createConversationOptionsBuilder'
+export * from './proactiveOptions'
+export * from './proactive'