@microsoft/agents-hosting 1.5.0-beta.10.gc9dfbe84d2 → 1.5.0-beta.12.ga9a2b23c19

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>;
+}

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

@@ -0,0 +1,271 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Proactive = void 0;
+const agents_activity_1 = require("@microsoft/agents-activity");
+const conversation_1 = require("./conversation");
+const logger_1 = require("@microsoft/agents-activity/logger");
+const errorHelper_1 = require("../../errorHelper");
+const logger = (0, logger_1.debug)('agents:proactive');
+const STORAGE_KEY_PREFIX = 'proactive/conversations/';
+/**
+ * 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}.
+ */
+class Proactive {
+    constructor(app, options) {
+        this._app = app;
+        this._options = options;
+        this._storage = options.storage;
+    }
+    requireStorage() {
+        if (!this._storage) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.ProactiveStorageRequired);
+        }
+        return this._storage;
+    }
+    requireAppStorage() {
+        const storage = this._app.options.storage;
+        if (!storage) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.ProactiveAppStorageRequired);
+        }
+        return storage;
+    }
+    async storeConversation(contextOrConversation) {
+        const conv = contextOrConversation instanceof conversation_1.Conversation
+            ? contextOrConversation
+            : new conversation_1.Conversation(contextOrConversation);
+        conv.validate();
+        const id = conv.reference.conversation.id;
+        await this.requireStorage().write({ [`${STORAGE_KEY_PREFIX}${id}`]: { reference: conv.reference, claims: conv.claims } });
+        return id;
+    }
+    /**
+     * 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!' })
+     * }
+     * ```
+     */
+    async getConversation(conversationId) {
+        const result = await this.requireStorage().read([`${STORAGE_KEY_PREFIX}${conversationId}`]);
+        const stored = result[`${STORAGE_KEY_PREFIX}${conversationId}`];
+        if (!stored)
+            return undefined;
+        return new conversation_1.Conversation(stored.claims, stored.reference);
+    }
+    /**
+     * 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.' })
+     * ```
+     */
+    async getConversationOrThrow(conversationId) {
+        const conv = await this.getConversation(conversationId);
+        if (!conv) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.ProactiveConversationNotFound, undefined, { conversationId });
+        }
+        return conv;
+    }
+    /**
+     * 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)
+     * })
+     * ```
+     */
+    async deleteConversation(conversationId) {
+        await this.requireStorage().delete([`${STORAGE_KEY_PREFIX}${conversationId}`]);
+    }
+    async sendActivity(adapter, conversationOrId, activity) {
+        const conv = typeof conversationOrId === 'string'
+            ? await this.getConversationOrThrow(conversationOrId)
+            : conversationOrId;
+        const activityToSend = { type: 'message', ...activity };
+        logger.info('sendActivity: conversation=%s channel=%s serviceUrl=%s', conv.reference.conversation.id, conv.reference.channelId, conv.reference.serviceUrl);
+        let response;
+        let caughtError;
+        await adapter.continueConversation(conv.identity, conv.reference, async (ctx) => {
+            try {
+                const result = await ctx.sendActivity(activityToSend);
+                response = result;
+            }
+            catch (err) {
+                caughtError = err;
+            }
+        });
+        if (caughtError !== undefined) {
+            logger.warn('sendActivity: failed for conversation=%s: %s', conv.reference.conversation.id, caughtError);
+            throw caughtError;
+        }
+        if (response === undefined)
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.ProactiveSendActivityNoResponse);
+        logger.debug('sendActivity: sent activity id=%s', response.id);
+        return response;
+    }
+    async continueConversation(adapter, conversationOrId, handler, autoSignInHandlers, continuationActivity) {
+        const conv = typeof conversationOrId === 'string'
+            ? await this.getConversationOrThrow(conversationOrId)
+            : conversationOrId;
+        logger.info('continueConversation: conversation=%s channel=%s serviceUrl=%s', conv.reference.conversation.id, conv.reference.channelId, conv.reference.serviceUrl);
+        let caughtError;
+        await adapter.continueConversation(conv.identity, conv.reference, async (ctx) => {
+            var _a, _b;
+            try {
+                // Merge caller-supplied activity fields (e.g. value, valueType) into the
+                // continuation activity so the handler can read request-time parameters.
+                if (continuationActivity) {
+                    Object.assign(ctx.activity, continuationActivity);
+                }
+                const state = this._app.options.turnStateFactory();
+                await state.load(ctx, this.requireAppStorage());
+                // Token acquisition (optional — only when auth is configured)
+                if ((autoSignInHandlers === null || autoSignInHandlers === void 0 ? void 0 : autoSignInHandlers.length) && this._app.hasUserAuthorization) {
+                    logger.debug('continueConversation: acquiring tokens for handlers: %o', autoSignInHandlers);
+                    const results = await Promise.all(autoSignInHandlers.map((handlerId) => this._app.authorization.getToken(ctx, handlerId).catch(() => ({ token: undefined }))));
+                    const allAcquired = results.every((r) => !!r.token);
+                    if (!allAcquired) {
+                        logger.warn('continueConversation: not all tokens acquired for conversation=%s handlers=%o', conv.reference.conversation.id, autoSignInHandlers);
+                        if (this._options.failOnUnsignedInConnections !== false) {
+                            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.ProactiveNotAllTokensAcquired);
+                        }
+                    }
+                }
+                await handler(ctx, state);
+                await state.save(ctx, this.requireAppStorage());
+            }
+            catch (err) {
+                caughtError = err;
+            }
+            finally {
+                if ((_b = (_a = ctx.streamingResponse) === null || _a === void 0 ? void 0 : _a.isStreamStarted) === null || _b === void 0 ? void 0 : _b.call(_a)) {
+                    await ctx.streamingResponse.endStream();
+                }
+            }
+        });
+        if (caughtError !== undefined) {
+            logger.warn('continueConversation: failed for conversation=%s: %s', conv.reference.conversation.id, caughtError);
+            throw caughtError;
+        }
+        logger.debug('continueConversation: complete for conversation=%s', conv.reference.conversation.id);
+    }
+    // ---------------------------------------------------------------------------
+    // Create new conversation
+    // ---------------------------------------------------------------------------
+    /**
+     * 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)
+     * ```
+     */
+    async createConversation(adapter, createOptions, handler) {
+        var _a, _b, _c;
+        if (!((_a = createOptions.parameters.members) === null || _a === void 0 ? void 0 : _a.length)) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.ProactiveMembersRequired);
+        }
+        // CloudAdapter.createConversationAsync(agentAppId, channelId, serviceUrl, audience, params, logic)
+        // The logic callback IS the handler — context is created internally by the adapter.
+        const cloudAdapter = adapter;
+        if (typeof cloudAdapter.createConversationAsync !== 'function') {
+            throw agents_activity_1.ExceptionHelper.generateException(TypeError, errorHelper_1.Errors.ProactiveCloudAdapterRequired);
+        }
+        logger.info('createConversation: channel=%s serviceUrl=%s members=%d', createOptions.channelId, createOptions.serviceUrl, (_c = (_b = createOptions.parameters.members) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0);
+        let capturedConv;
+        let caughtError;
+        await cloudAdapter.createConversationAsync(createOptions.identity.aud, createOptions.channelId, createOptions.serviceUrl, createOptions.scope, createOptions.parameters, async (ctx) => {
+            try {
+                const conv = new conversation_1.Conversation(createOptions.identity, ctx.activity.getConversationReference());
+                capturedConv = conv;
+                logger.debug('createConversation: created conversation=%s', conv.reference.conversation.id);
+                if (createOptions.storeConversation) {
+                    await this.storeConversation(conv);
+                }
+                if (handler) {
+                    const state = this._app.options.turnStateFactory();
+                    await state.load(ctx, this.requireAppStorage());
+                    await handler(ctx, state);
+                    await state.save(ctx, this.requireAppStorage());
+                }
+            }
+            catch (err) {
+                caughtError = err;
+            }
+        });
+        if (caughtError !== undefined) {
+            logger.warn('createConversation: failed for channel=%s: %s', createOptions.channelId, caughtError);
+            throw caughtError;
+        }
+        if (!capturedConv) {
+            throw agents_activity_1.ExceptionHelper.generateException(Error, errorHelper_1.Errors.ProactiveCallbackNotInvoked);
+        }
+        return capturedConv;
+    }
+}
+exports.Proactive = Proactive;
+/**
+ * `activity.valueType` that indicates additional key/values for the ContinueConversation event.
+ */
+Proactive.ContinueConversationValueType = 'application/vnd.microsoft.activity.continueconversation+json';
+//# sourceMappingURL=proactive.js.map

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

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

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

@@ -0,0 +1,19 @@
+import type { Storage } from '../../storage/storage';
+/**
+ * Configuration for the proactive messaging subsystem.
+ */
+export interface ProactiveOptions {
+    /**
+     * Storage backend for persisting conversation references.
+     *
+     * If omitted, falls back to `AgentApplicationOptions.storage`.
+     * A warning is logged when the fallback is used.
+     * Throws at initialization time if neither is configured.
+     */
+    storage?: Storage;
+    /**
+     * When `true` (default), `continueConversation()` throws if any requested
+     * token handler's user has not previously signed in.
+     */
+    failOnUnsignedInConnections?: boolean;
+}

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

@@ -0,0 +1,5 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=proactiveOptions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"proactiveOptions.js","sourceRoot":"","sources":["../../../../src/app/proactive/proactiveOptions.ts"],"names":[],"mappings":";AAAA,4DAA4D;AAC5D,kCAAkC"}

package/dist/src/errorHelper.js

@@ -575,6 +575,100 @@ exports.Errors = {
         description: 'Invalid action value: {error}'
     },
     // ============================================================================
+    // Proactive Messaging Errors (-120740 to -120799)
+    // ============================================================================
+    /**
+     * Error thrown when Application.proactive is accessed but no storage was configured.
+     */
+    ProactivePropertyUnavailable: {
+        code: -120740,
+        description: 'The Application.proactive property is unavailable because no storage was configured. Set options.storage or options.proactive.storage.'
+    },
+    /**
+     * Error thrown when a proactive storage operation is attempted without a storage backend.
+     */
+    ProactiveStorageRequired: {
+        code: -120741,
+        description: 'This proactive operation requires a storage backend. Set options.storage or options.proactive.storage.'
+    },
+    /**
+     * Error thrown when a conversation is not found in proactive storage.
+     */
+    ProactiveConversationNotFound: {
+        code: -120742,
+        description: "Conversation '{conversationId}' was not found in proactive storage."
+    },
+    /**
+     * Error thrown when sendActivity does not receive a ResourceResponse from the adapter.
+     */
+    ProactiveSendActivityNoResponse: {
+        code: -120743,
+        description: 'sendActivity: adapter did not return a ResourceResponse.'
+    },
+    /**
+     * Error thrown when not all token handlers have a signed-in user for proactive continuation.
+     */
+    ProactiveNotAllTokensAcquired: {
+        code: -120744,
+        description: 'Not all token handlers have a signed-in user.'
+    },
+    /**
+     * Error thrown when createConversation is called without any members.
+     */
+    ProactiveMembersRequired: {
+        code: -120745,
+        description: 'createConversation: at least one member must be specified in parameters.members.'
+    },
+    /**
+     * Error thrown when the adapter passed to createConversation does not support createConversationAsync.
+     */
+    ProactiveCloudAdapterRequired: {
+        code: -120746,
+        description: 'createConversation requires a CloudAdapter. The provided adapter does not implement createConversationAsync().'
+    },
+    /**
+     * Error thrown when createConversationAsync completes without invoking its callback.
+     */
+    ProactiveCallbackNotInvoked: {
+        code: -120747,
+        description: 'createConversation: createConversationAsync completed without invoking its callback.'
+    },
+    /**
+     * Error thrown when a Conversation reference is missing conversation.id.
+     */
+    ConversationInvalidId: {
+        code: -120748,
+        description: 'Conversation is invalid: reference.conversation.id is required.'
+    },
+    /**
+     * Error thrown when a Conversation reference is missing serviceUrl.
+     */
+    ConversationInvalidServiceUrl: {
+        code: -120749,
+        description: 'Conversation is invalid: reference.serviceUrl is required.'
+    },
+    /**
+     * Error thrown when a Conversation reference is missing claims.aud.
+     */
+    ConversationInvalidAud: {
+        code: -120750,
+        description: 'Conversation is invalid: claims.aud (agent client ID) is required.'
+    },
+    /**
+     * Error thrown when CreateConversationOptionsBuilder.build() is called without any members.
+     */
+    CreateConversationBuilderMembersRequired: {
+        code: -120751,
+        description: 'CreateConversationOptionsBuilder: at least one members entry must be added via withUser().'
+    },
+    /**
+     * Error thrown when a proactive operation that requires TurnState load/save is called without app storage.
+     */
+    ProactiveAppStorageRequired: {
+        code: -120752,
+        description: 'This proactive operation requires app storage to load and save TurnState. Set options.storage on AgentApplication.'
+    },
+    // ============================================================================
     // General Errors (-120990)
     // ============================================================================
     /**