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

package/dist/src/app/proactive/createConversationOptions.js

@@ -0,0 +1,10 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AzureBotScope = void 0;
+/**
+ * Default OAuth scope for Azure Bot Service authentication.
+ */
+exports.AzureBotScope = 'https://api.botframework.com';
+//# sourceMappingURL=createConversationOptions.js.map

package/dist/src/app/proactive/createConversationOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createConversationOptions.js","sourceRoot":"","sources":["../../../../src/app/proactive/createConversationOptions.ts"],"names":[],"mappings":";AAAA,4DAA4D;AAC5D,kCAAkC;;;AAKlC;;GAEG;AACU,QAAA,aAAa,GAAG,8BAA8B,CAAA"}

package/dist/src/app/proactive/createConversationOptionsBuilder.d.ts

@@ -0,0 +1,69 @@
+import type { Activity, ChannelAccount, ConversationParameters } from '@microsoft/agents-activity';
+import { type CreateConversationOptions } from './createConversationOptions';
+import type { ConversationClaims } from './conversation';
+/**
+ * Fluent builder for `CreateConversationOptions`.
+ *
+ * @example
+ * ```typescript
+ * const opts = CreateConversationOptionsBuilder
+ *   .create('my-client-id', 'msteams')
+ *   .withUser('user-aad-id')
+ *   .withTenantId('tenant-id')
+ *   .build()
+ * ```
+ */
+export declare class CreateConversationOptionsBuilder {
+    private readonly _claims;
+    private readonly _channelId;
+    private readonly _serviceUrl;
+    private _scope;
+    private _storeConversation;
+    private _parameters;
+    private _activity;
+    private constructor();
+    /**
+     * 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;
+    /** Adds a member (the target user) to `parameters.members`. */
+    withUser(userId: string, userName?: string): this;
+    withUser(account: ChannelAccount): this;
+    /** Sets `parameters.activity`. Defaults `activity.type` to `'message'` if not provided. */
+    withActivity(activity: Partial<Activity>): this;
+    /** Merges additional channel-specific data into `parameters.channelData`. */
+    withChannelData(data: object): this;
+    /**
+     * Sets `parameters.tenantId`.
+     * On `msteams` channels, also sets `channelData.tenant.id`.
+     */
+    withTenantId(tenantId: string): this;
+    /**
+     * Sets `parameters.isGroup = true` and `channelData.channel.id`.
+     * Only has effect on `msteams` channels.
+     */
+    withTeamsChannelId(teamsChannelId: string): this;
+    /** Sets `parameters.topicName`. */
+    withTopicName(name: string): this;
+    /** Sets `parameters.isGroup`. */
+    isGroup(value: boolean): this;
+    /** Overrides the default `AzureBotScope` OAuth scope. */
+    withScope(scope: string): this;
+    /** Controls whether the resulting conversation is stored after creation. */
+    storeConversation(value: boolean): this;
+    /**
+     * Builds and returns `CreateConversationOptions`.
+     * @throws if no members were added via `withUser()`.
+     */
+    build(): CreateConversationOptions;
+}

package/dist/src/app/proactive/createConversationOptionsBuilder.js

@@ -0,0 +1,141 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateConversationOptionsBuilder = void 0;
+const agents_activity_1 = require("@microsoft/agents-activity");
+const errorHelper_1 = require("../../errorHelper");
+const createConversationOptions_1 = require("./createConversationOptions");
+const conversationReferenceBuilder_1 = require("./conversationReferenceBuilder");
+/**
+ * Fluent builder for `CreateConversationOptions`.
+ *
+ * @example
+ * ```typescript
+ * const opts = CreateConversationOptionsBuilder
+ *   .create('my-client-id', 'msteams')
+ *   .withUser('user-aad-id')
+ *   .withTenantId('tenant-id')
+ *   .build()
+ * ```
+ */
+class CreateConversationOptionsBuilder {
+    constructor(claims, channelId, serviceUrl) {
+        this._scope = createConversationOptions_1.AzureBotScope;
+        this._storeConversation = false;
+        this._parameters = {
+            channelData: {},
+        };
+        this._claims = claims;
+        this._channelId = channelId;
+        this._serviceUrl =
+            serviceUrl !== null && serviceUrl !== void 0 ? serviceUrl : conversationReferenceBuilder_1.ConversationReferenceBuilder.serviceUrlForChannel(channelId);
+    }
+    static create(agentClientIdOrClaims, channelId, serviceUrl, parameters) {
+        const claims = 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: agents_activity_1.RoleTypes.Agent };
+        }
+        return builder;
+    }
+    withUser(userIdOrAccount, userName) {
+        var _a;
+        const account = typeof userIdOrAccount === 'string'
+            ? { id: userIdOrAccount, name: userName }
+            : userIdOrAccount;
+        const members = (_a = this._parameters.members) !== null && _a !== void 0 ? _a : [];
+        members.push(account);
+        this._parameters = { ...this._parameters, members };
+        return this;
+    }
+    /** Sets `parameters.activity`. Defaults `activity.type` to `'message'` if not provided. */
+    withActivity(activity) {
+        this._activity = activity;
+        return this;
+    }
+    /** Merges additional channel-specific data into `parameters.channelData`. */
+    withChannelData(data) {
+        var _a;
+        this._parameters = {
+            ...this._parameters,
+            channelData: { ...((_a = this._parameters.channelData) !== null && _a !== void 0 ? _a : {}), ...data },
+        };
+        return this;
+    }
+    /**
+     * Sets `parameters.tenantId`.
+     * On `msteams` channels, also sets `channelData.tenant.id`.
+     */
+    withTenantId(tenantId) {
+        this._parameters = { ...this._parameters, tenantId };
+        if (this._channelId === agents_activity_1.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) {
+        if (this._channelId !== agents_activity_1.Channels.Msteams)
+            return this;
+        this._parameters = { ...this._parameters, isGroup: true };
+        this.withChannelData({ channel: { id: teamsChannelId } });
+        return this;
+    }
+    /** Sets `parameters.topicName`. */
+    withTopicName(name) {
+        this._parameters = { ...this._parameters, topicName: name };
+        return this;
+    }
+    /** Sets `parameters.isGroup`. */
+    isGroup(value) {
+        this._parameters = { ...this._parameters, isGroup: value };
+        return this;
+    }
+    /** Overrides the default `AzureBotScope` OAuth scope. */
+    withScope(scope) {
+        this._scope = scope;
+        return this;
+    }
+    /** Controls whether the resulting conversation is stored after creation. */
+    storeConversation(value) {
+        this._storeConversation = value;
+        return this;
+    }
+    /**
+     * Builds and returns `CreateConversationOptions`.
+     * @throws if no members were added via `withUser()`.
+     */
+    build() {
+        var _a;
+        if (!((_a = this._parameters.members) === null || _a === void 0 ? void 0 : _a.length)) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.CreateConversationBuilderMembersRequired);
+        }
+        const 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,
+            },
+        };
+    }
+}
+exports.CreateConversationOptionsBuilder = CreateConversationOptionsBuilder;
+//# sourceMappingURL=createConversationOptionsBuilder.js.map

package/dist/src/app/proactive/createConversationOptionsBuilder.js.map

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

package/dist/src/app/proactive/index.d.ts

@@ -0,0 +1,7 @@
+export * from './conversation';
+export * from './conversationBuilder';
+export * from './conversationReferenceBuilder';
+export * from './createConversationOptions';
+export * from './createConversationOptionsBuilder';
+export * from './proactiveOptions';
+export * from './proactive';

package/dist/src/app/proactive/index.js

@@ -0,0 +1,26 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./conversation"), exports);
+__exportStar(require("./conversationBuilder"), exports);
+__exportStar(require("./conversationReferenceBuilder"), exports);
+__exportStar(require("./createConversationOptions"), exports);
+__exportStar(require("./createConversationOptionsBuilder"), exports);
+__exportStar(require("./proactiveOptions"), exports);
+__exportStar(require("./proactive"), exports);
+//# sourceMappingURL=index.js.map

package/dist/src/app/proactive/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/app/proactive/index.ts"],"names":[],"mappings":";AAAA,4DAA4D;AAC5D,kCAAkC;;;;;;;;;;;;;;;;AAElC,iDAA8B;AAC9B,wDAAqC;AACrC,iEAA8C;AAC9C,8DAA2C;AAC3C,qEAAkD;AAClD,qDAAkC;AAClC,8CAA2B"}

package/dist/src/app/proactive/proactive.d.ts

@@ -0,0 +1,248 @@
+import type { Activity } from '@microsoft/agents-activity';
+import type { ResourceResponse } from '../../connector-client';
+import type { BaseAdapter } from '../../baseAdapter';
+import type { TurnContext } from '../../turnContext';
+import type { TurnState } from '../turnState';
+import type { RouteHandler } from '../routeHandler';
+import type { AgentApplication } from '../agentApplication';
+import type { ProactiveOptions } from './proactiveOptions';
+import type { CreateConversationOptions } from './createConversationOptions';
+import { Conversation } from './conversation';
+/**
+ * Provides methods for storing, retrieving, and managing conversation references to enable
+ * proactive messaging scenarios. Supports sending activities and continuing conversations outside
+ * the standard request/response flow using stored conversation references.
+ *
+ * @remarks
+ * Use the `Proactive` class to implement scenarios where an agent needs to initiate conversations
+ * or send messages to users without an incoming activity, such as notifications or scheduled alerts.
+ * Some operations require that conversation references be stored using {@link storeConversation}
+ * before they can be used.
+ *
+ * Access via `app.proactive` after configuring `proactive` in {@link AgentApplicationOptions}.
+ */
+export declare class Proactive<TState extends TurnState> {
+    /**
+     * `activity.valueType` that indicates additional key/values for the ContinueConversation event.
+     */
+    static readonly ContinueConversationValueType = "application/vnd.microsoft.activity.continueconversation+json";
+    private readonly _app;
+    private readonly _options;
+    private readonly _storage?;
+    constructor(app: AgentApplication<TState>, options: ProactiveOptions);
+    private requireStorage;
+    private requireAppStorage;
+    /**
+     * Stores the current conversation reference from a live {@link TurnContext} in proactive storage.
+     *
+     * @param context - The context object for the current turn, containing activity and conversation
+     *   information.
+     * @returns The conversation ID that can be used to retrieve the reference in future operations.
+     * @example
+     * ```typescript
+     * // Inside an onMessage handler — save the conversation so we can message later
+     * app.onActivity('message', async (ctx, state) => {
+     *   const convId = await app.proactive.storeConversation(ctx)
+     *   await ctx.sendActivity(`Conversation stored. ID: ${convId}`)
+     * })
+     * ```
+     */
+    storeConversation(context: TurnContext): Promise<string>;
+    /**
+     * Stores an explicit {@link Conversation} object in proactive storage.
+     *
+     * @param conversation - The conversation reference record to store.
+     * @returns The conversation ID that can be used to retrieve the reference in future operations.
+     * @throws If the conversation fails validation (missing `conversation.id`, `serviceUrl`, or
+     *   `claims.aud`).
+     * @example
+     * ```typescript
+     * // Build a Conversation manually and store it
+     * const conv = ConversationBuilder
+     *   .create('my-app-id', 'msteams')
+     *   .withUser('user-aad-id')
+     *   .withConversationId('19:existing-thread-id@thread.tacv2')
+     *   .build()
+     * const convId = await app.proactive.storeConversation(conv)
+     * ```
+     */
+    storeConversation(conversation: Conversation): Promise<string>;
+    /**
+     * Retrieves the stored {@link Conversation} associated with the given conversation ID.
+     *
+     * @param conversationId - The unique identifier of the conversation to retrieve.
+     * @returns The stored `Conversation`, or `undefined` if no record exists for that ID.
+     * @example
+     * ```typescript
+     * const conv = await app.proactive.getConversation(convId)
+     * if (conv) {
+     *   await app.proactive.sendActivity(adapter, conv, { text: 'Hello!' })
+     * }
+     * ```
+     */
+    getConversation(conversationId: string): Promise<Conversation | undefined>;
+    /**
+     * Retrieves the stored {@link Conversation} for the given ID, throwing if no record is found.
+     *
+     * @param conversationId - The unique identifier of the conversation to retrieve.
+     * @returns The stored `Conversation`.
+     * @throws `Error` if no conversation reference is found for the specified ID.
+     * @example
+     * ```typescript
+     * // Use when absence of the conversation should be treated as an error
+     * const conv = await app.proactive.getConversationOrThrow(convId)
+     * await app.proactive.sendActivity(adapter, conv, { text: 'Alert: your report is ready.' })
+     * ```
+     */
+    getConversationOrThrow(conversationId: string): Promise<Conversation>;
+    /**
+     * Deletes the stored conversation reference for the given conversation ID.
+     *
+     * @param conversationId - The unique identifier of the conversation whose reference should be
+     *   deleted.
+     * @remarks If no record exists for the given ID, no action is taken.
+     * @example
+     * ```typescript
+     * // Clean up after a conversation has ended
+     * app.onActivity('endOfConversation', async (ctx, state) => {
+     *   await app.proactive.deleteConversation(ctx.activity.conversation.id)
+     * })
+     * ```
+     */
+    deleteConversation(conversationId: string): Promise<void>;
+    /**
+     * Sends an activity to a stored conversation, looking it up by ID.
+     *
+     * @param adapter - The channel adapter used to send the activity.
+     * @param conversationId - The ID of a conversation previously stored via {@link storeConversation}.
+     * @param activity - The activity to send. If `type` is not set it defaults to `'message'`.
+     * @returns A {@link ResourceResponse} with the ID of the sent activity.
+     * @throws `Error` if no conversation reference is found for the specified ID.
+     * @example
+     * ```typescript
+     * // Send a notification using a previously stored conversation ID
+     * await app.proactive.sendActivity(adapter, storedConvId, { text: 'Your order has shipped!' })
+     * ```
+     */
+    sendActivity(adapter: BaseAdapter, conversationId: string, activity: Partial<Activity>): Promise<ResourceResponse>;
+    /**
+     * Sends an activity to an existing conversation using the provided {@link Conversation} reference.
+     *
+     * @param adapter - The channel adapter used to send the activity.
+     * @param conversation - A `Conversation` instance created via its constructor or
+     *   {@link ConversationBuilder}.
+     * @param activity - The activity to send. If `type` is not set it defaults to `'message'`.
+     * @returns A {@link ResourceResponse} with the ID of the sent activity.
+     * @example
+     * ```typescript
+     * // Build a Conversation from a stored reference and send a message
+     * const conv = await app.proactive.getConversationOrThrow(convId)
+     * const response = await app.proactive.sendActivity(adapter, conv, { text: 'Hello from the agent!' })
+     * console.log('Sent activity ID:', response.id)
+     * ```
+     */
+    sendActivity(adapter: BaseAdapter, conversation: Conversation, activity: Partial<Activity>): Promise<ResourceResponse>;
+    /**
+     * Continues a stored conversation by executing the given handler within the context of that
+     * conversation, looking it up by ID.
+     *
+     * See the {@link Conversation} overload for full details.
+     *
+     * @param adapter - The channel adapter used to continue the conversation.
+     * @param conversationId - The ID of a conversation previously stored via {@link storeConversation}.
+     * @param handler - The route handler to execute within the continued conversation context.
+     * @param autoSignInHandlers - Optional list of OAuth connection names whose tokens should be
+     *   acquired before invoking the handler.
+     * @param continuationActivity - Optional activity fields merged into the continuation activity,
+     *   making them available on `ctx.activity` inside the handler (e.g. `value`, `valueType`).
+     * @throws `Error` if no conversation reference is found for the specified ID.
+     * @example
+     * ```typescript
+     * // Scheduled job: send a daily digest to all stored conversations
+     * for (const convId of storedIds) {
+     *   await app.proactive.continueConversation(adapter, convId, async (ctx, state) => {
+     *     await ctx.sendActivity('Here is your daily digest...')
+     *   })
+     * }
+     * ```
+     */
+    continueConversation(adapter: BaseAdapter, conversationId: string, handler: RouteHandler<TState>, autoSignInHandlers?: string[], continuationActivity?: Partial<Activity>): Promise<void>;
+    /**
+     * Continues an existing conversation by executing the given handler within the context of the
+     * provided {@link Conversation} reference. The handler receives a {@link TurnContext} and a
+     * freshly loaded {@link TurnState} scoped to the original conversation, enabling the agent to
+     * respond as if replying to an incoming activity.
+     *
+     * @remarks
+     * Exceptions thrown inside the handler are captured and re-thrown after the adapter callback
+     * completes, since the adapter would otherwise silently swallow them.
+     *
+     * If `autoSignInHandlers` are supplied and the application has user authorization configured,
+     * tokens are acquired before the handler is called. If not all tokens are available and
+     * `proactiveOptions.failOnUnsignedInConnections` is not `false`, an error is thrown.
+     *
+     * @param adapter - The channel adapter used to continue the conversation.
+     * @param conversation - A `Conversation` instance created via its constructor or
+     *   {@link ConversationBuilder}.
+     * @param handler - The route handler to execute within the continued conversation context.
+     * @param autoSignInHandlers - Optional list of OAuth connection names whose tokens should be
+     *   acquired before invoking the handler.
+     * @param continuationActivity - Optional activity fields merged into the continuation activity,
+     *   making them available on `ctx.activity` inside the handler (e.g. `value`, `valueType`).
+     * @example
+     * ```typescript
+     * // Continue a conversation with a custom value payload
+     * const conv = await app.proactive.getConversationOrThrow(convId)
+     * await app.proactive.continueConversation(
+     *   adapter,
+     *   conv,
+     *   async (ctx, state) => {
+     *     const payload = ctx.activity.value as { alertType: string }
+     *     await ctx.sendActivity(`Alert triggered: ${payload.alertType}`)
+     *   },
+     *   undefined,
+     *   { value: { alertType: 'threshold-exceeded' }, valueType: Proactive.ContinueConversationValueType }
+     * )
+     * ```
+     */
+    continueConversation(adapter: BaseAdapter, conversation: Conversation, handler: RouteHandler<TState>, autoSignInHandlers?: string[], continuationActivity?: Partial<Activity>): Promise<void>;
+    /**
+     * Creates a new conversation using the specified channel adapter and conversation options.
+     *
+     * @remarks
+     * This wraps `CloudAdapter.createConversationAsync()`, which requires real network connectivity
+     * and authentication. The provided adapter must implement
+     * `createConversationAsync()`; a `TypeError` is thrown if it does not.
+     *
+     * If `createOptions.storeConversation` is `true`, the resulting {@link Conversation} is
+     * automatically stored via {@link storeConversation} so it can be retrieved by ID later.
+     *
+     * If a `handler` is provided it is executed within the newly created conversation, giving the
+     * agent a chance to send an initial message or load state.
+     *
+     * @param adapter - The channel adapter used to create the conversation. Must implement
+     *   `createConversationAsync()` (i.e. a `CloudAdapter` instance).
+     * @param createOptions - Details required to create the conversation, including identity, channel,
+     *   service URL, OAuth scope, and `ConversationParameters`. Build with
+     *   {@link CreateConversationOptionsBuilder}.
+     * @param handler - Optional route handler executed immediately after the conversation is created.
+     * @returns The newly created {@link Conversation}.
+     * @throws `TypeError` if the adapter does not implement `createConversationAsync()`.
+     * @example
+     * ```typescript
+     * // Initiate a new 1:1 conversation with a Teams user and send a welcome message
+     * const opts = CreateConversationOptionsBuilder
+     *   .create(process.env.APP_ID!, 'msteams')
+     *   .withUser('user-aad-object-id')
+     *   .withTenantId('tenant-id')
+     *   .storeConversation(true)
+     *   .build()
+     *
+     * const conv = await app.proactive.createConversation(adapter, opts, async (ctx, state) => {
+     *   await ctx.sendActivity('Hi! I have an update for you.')
+     * })
+     * console.log('New conversation ID:', conv.reference.conversation.id)
+     * ```
+     */
+    createConversation(adapter: BaseAdapter, createOptions: CreateConversationOptions, handler?: RouteHandler<TState>): Promise<Conversation>;
+}