@cogitator-ai/channels 0.17.0 → 0.18.0

package/dist/channels/teams/channel.js

@@ -0,0 +1,1071 @@
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import { z } from 'zod';
+import { chunkMessage } from '../../formatters/markdown.js';
+import { imagesAsLinks } from '../../formatters/markdown-images.js';
+import { attachmentTypeOf, attachmentsOf, conversationTypeOf, downloadInfoOf, fileConsentOf, joinConversation, mentionsBot, mimeTypeOf, parseActivity, splitConversation, teamOf, tenantOf, tenantsDisagree, textWithoutMention, } from './activity.js';
+import { TeamsAuthError, TeamsTokenVerifier } from './auth.js';
+import { ADAPTIVE_CARD, FILE_CONSENT_CARD, FILE_INFO_CARD, buttonsCard, executeDataOf, submitDataOf, } from './cards.js';
+import { TEAMS_REQUEST_TIMEOUT, TeamsApiError, TeamsClient, } from './client.js';
+import { ConversationPacer, pause } from './pacer.js';
+import { BOT_FRAMEWORK_TENANT, TeamsCredentials } from './token.js';
+/** The largest message Teams is advised to take, in bytes of the activity JSON. */
+export const TEAMS_MAX_MESSAGE_BYTES = 80 * 1024;
+/**
+ * The longest text sent as one message, in characters: JSON takes at most six bytes for one
+ * character (`\u0001`), so this many stay under {@link TEAMS_MAX_MESSAGE_BYTES} whatever they are.
+ */
+export const TEAMS_MESSAGE_CHARS = Math.floor(TEAMS_MAX_MESSAGE_BYTES / 6);
+/** The port of the channel's own server by default, the port Bot Framework samples use. */
+export const TEAMS_DEFAULT_PORT = 3978;
+/** The path of the channel's own server by default, the messaging endpoint of Azure Bot Service. */
+export const TEAMS_DEFAULT_PATH = '/api/messages';
+/** The Bot Connector of the commercial cloud, for conversations no activity came from yet. */
+export const TEAMS_GLOBAL_SERVICE_URL = 'https://smba.trafficmanager.net/teams/';
+/** The largest webhook body the channel's own server takes by default, in bytes. */
+export const TEAMS_DEFAULT_MAX_BODY = 1024 * 1024;
+/**
+ * The shortest time between two updates of one message, in ms, so a streamed answer takes at
+ * most one of the 60 requests a conversation may have in 30 seconds every second, and new
+ * messages always find room.
+ */
+export const TEAMS_MIN_EDIT_INTERVAL = 1000;
+const MAX_TRACKED = 1000;
+const MAX_CONVERSATIONS = 10_000;
+const MAX_PENDING_UPLOADS = 100;
+/** How long a file waits for its consent card to be answered, in ms. */
+const UPLOAD_TTL = 60 * 60 * 1000;
+/** The size of one upload request, a multiple of 320 KiB as OneDrive upload sessions want. */
+const UPLOAD_FRAGMENT = 32 * 320 * 1024;
+/** The largest file a user sends that is handed to the agent, in bytes. */
+const MAX_INBOUND_FILE = 20 * 1024 * 1024;
+/**
+ * How long a webhook request waits for the gateway to take its message, in ms. A gateway that
+ * queues takes it at once, one that answers before it returns is answered `202` after this long.
+ */
+const HANDOVER_TIMEOUT = 3000;
+/** How long an `Action.Execute` press waits for its answer, under the time Teams waits, in ms. */
+const INVOKE_TIMEOUT = 4000;
+/** What a button press is answered with when nothing else is said and its card is not known. */
+const ACTION_RECEIVED = 'Done';
+/** How long `stop()` waits for requests under way before it closes their connections, in ms. */
+const STOP_GRACE = 3000;
+/** Answers to a file consent card the bot can no longer act on, or that was declined. */
+const UPLOAD_GONE = 'That file is no longer available, ask for it again.';
+const UPLOAD_DECLINED = 'The file was not sent.';
+const ACTIVITY_MESSAGE = 'application/vnd.microsoft.activity.message';
+const ResourceSchema = z.object({ id: z.string().optional() });
+function textResponse(status, body) {
+    return { status, body, contentType: 'text/plain' };
+}
+function jsonResponse(status, value) {
+    return { status, body: JSON.stringify(value), contentType: 'application/json' };
+}
+function header(headers, name) {
+    const wanted = name.toLowerCase();
+    const key = Object.keys(headers).find((candidate) => candidate.toLowerCase() === wanted);
+    const value = key === undefined ? undefined : headers[key];
+    return Array.isArray(value) ? value[0] : value;
+}
+function bodyText(raw) {
+    return typeof raw === 'string' ? raw : Buffer.from(raw).toString('utf-8');
+}
+function textFormatOf(format) {
+    if (format === 'plain')
+        return 'plain';
+    if (format === 'html')
+        return 'xml';
+    return 'extendedmarkdown';
+}
+/**
+ * Markdown with its images turned into links (`![alt](url)` becomes `[alt](url)`) and raw
+ * `<img>` tags into text, outside code: Teams loads an image as soon as it shows the message,
+ * so an answer steered by injected text could send what it read to any address in an image URL.
+ */
+export function withoutImages(text) {
+    return imagesAsLinks(text);
+}
+function bodyFor(text, textFormat) {
+    return textFormat === 'extendedmarkdown' ? withoutImages(text) : text;
+}
+/** Resolves with `fallback` when `promise` takes longer than `ms`. */
+function within(promise, ms, fallback) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(fallback), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+function forgetOldest(collection, max = MAX_TRACKED) {
+    while (collection.size > max) {
+        const oldest = collection.keys().next().value;
+        if (oldest === undefined)
+            return;
+        collection.delete(oldest);
+    }
+}
+function remember(map, key, value, max = MAX_TRACKED) {
+    map.delete(key);
+    map.set(key, value);
+    forgetOldest(map, max);
+}
+/** The conversation whose limits a request counts against: a channel with all its threads. */
+function paceKeyOf(conversationId) {
+    return splitConversation(conversationId).channelId;
+}
+function activitiesPath(conversationId, activityId) {
+    const base = `/v3/conversations/${encodeURIComponent(conversationId)}/activities`;
+    return activityId === undefined ? base : `${base}/${encodeURIComponent(activityId)}`;
+}
+/** Splits text into the messages Teams takes: at most {@link TEAMS_MESSAGE_CHARS} characters each. */
+export function splitTeamsText(text) {
+    return chunkMessage(text, TEAMS_MESSAGE_CHARS).filter((part) => part.trim());
+}
+class BodyTooLarge extends Error {
+}
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                reject(new BodyTooLarge('Webhook body too large'));
+                req.pause();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks)));
+        req.on('error', reject);
+    });
+}
+/**
+ * A Microsoft Teams channel on the Bot Framework protocol, with no SDK: Bot Framework posts
+ * activities to a webhook, each checked against its signed JWT, and answers go back through the
+ * Bot Connector REST API with a client credentials token of the app registration.
+ *
+ * Each chat is a conversation: `channelId` is the Teams conversation id of a personal or group
+ * chat, or of a team channel, whose threads are topics (`topicId` is the thread's root message
+ * id), so each channel thread is a conversation of its own. In group chats and channels the bot
+ * answers @mentions, without the mention in the text. Buttons are Adaptive Cards, answers are
+ * Markdown and can be edited, so they stream.
+ */
+export class TeamsChannel {
+    type = 'teams';
+    editable = true;
+    nativeMarkdown = true;
+    maxMessageChars = TEAMS_MESSAGE_CHARS;
+    config;
+    tenantId;
+    verifier;
+    credentials;
+    client;
+    fetchImpl;
+    handler = null;
+    actionHandler = null;
+    /** Activities taken, by `conversation|id`, so one sent again is handled once */
+    delivered = new Set();
+    /** Messages handed to the gateway whose handler has not resolved yet, by delivery key */
+    inFlight = new Set();
+    /** Messages of `inFlight` the gateway handed back while they were being taken */
+    refused = new Set();
+    /** The delivery key of each message handed over, by message id */
+    deliveryKeys = new Map();
+    conversations = new Map();
+    sent = new Map();
+    updates = new Map();
+    pacer = new ConversationPacer();
+    /** Conversations whose messages Teams blocks (`MessageWritesBlocked`), by pacing key */
+    blocked = new Set();
+    /** Messages whose webhook request was answered before the gateway took them, by delivery key */
+    answeredEarly = new Set();
+    activeRequests = new Set();
+    /** Waits that end at once when the channel stops */
+    onHalt = new Set();
+    /** Aborts every request and wait under way when the channel stops */
+    halt = new AbortController();
+    answers = new Map();
+    /** The conversation of each button press, to answer it with a message once its request is over */
+    actionConversations = new Map();
+    uploads = new Map();
+    server;
+    running = false;
+    stopped = false;
+    constructor(config) {
+        if (!config.appId)
+            throw new Error('[teams] appId is required: the Microsoft App ID of the bot');
+        const appType = config.appType ?? 'SingleTenant';
+        if (appType !== 'MultiTenant' && !config.tenantId) {
+            throw new Error(`[teams] tenantId is required for a ${appType} bot: the tenant of its app registration`);
+        }
+        if (appType === 'UserAssignedMSI' && !config.tokenProvider) {
+            throw new Error('[teams] tokenProvider is required for a UserAssignedMSI bot: a function that returns a token of the managed identity');
+        }
+        if (!config.appPassword && !config.tokenProvider) {
+            throw new Error('[teams] appPassword (a client secret) or tokenProvider is required');
+        }
+        this.config = config;
+        if (config.tenantId)
+            this.tenantId = config.tenantId;
+        this.fetchImpl = config.fetch ?? fetch;
+        this.verifier = new TeamsTokenVerifier({
+            appId: config.appId,
+            ...(config.openIdMetadataUrl && { metadataUrl: config.openIdMetadataUrl }),
+            ...(config.fetch && { fetch: config.fetch }),
+        });
+        this.credentials = new TeamsCredentials({
+            appId: config.appId,
+            ...(config.appPassword && { appPassword: config.appPassword }),
+            tenant: appType === 'MultiTenant' ? BOT_FRAMEWORK_TENANT : (config.tenantId ?? ''),
+            ...(config.tokenProvider && { provider: config.tokenProvider }),
+            ...(config.loginUrl && { loginUrl: config.loginUrl }),
+            ...(config.fetch && { fetch: config.fetch }),
+        });
+        this.client = new TeamsClient({
+            credentials: this.credentials,
+            pacer: this.pacer,
+            ...(config.retry && { retry: config.retry }),
+            ...(config.requestTimeout !== undefined && { timeout: config.requestTimeout }),
+            ...(config.fetch && { fetch: config.fetch }),
+        });
+    }
+    onMessage(handler) {
+        this.handler = handler;
+    }
+    onAction(handler) {
+        this.actionHandler = handler;
+    }
+    async start() {
+        if (this.running)
+            return;
+        if (this.config.tenants === '*') {
+            console.warn('[teams] tenants is "*": the bot answers users of every tenant its app is installed in');
+        }
+        else if (this.allowedTenants().length === 0) {
+            console.warn('[teams] No tenants set: the bot answers nobody. Set tenants or tenantId');
+        }
+        this.running = true;
+        this.stopped = false;
+        if (this.halt.signal.aborted)
+            this.halt = new AbortController();
+        const webhook = this.config.webhook;
+        if (webhook?.port !== undefined) {
+            try {
+                await this.listen(webhook.port, webhook.path ?? TEAMS_DEFAULT_PATH, webhook.host);
+            }
+            catch (error) {
+                this.running = false;
+                throw error;
+            }
+        }
+    }
+    async stop() {
+        this.running = false;
+        this.stopped = true;
+        for (const answer of this.answers.values())
+            answer.resolve({});
+        this.answers.clear();
+        for (const halt of this.onHalt)
+            halt();
+        this.onHalt.clear();
+        this.halt.abort(new Error('[teams] The channel stopped'));
+        const server = this.server;
+        this.server = undefined;
+        if (!server)
+            return;
+        const closed = new Promise((resolve) => server.close(() => resolve()));
+        server.closeIdleConnections();
+        let timer;
+        await Promise.race([
+            Promise.allSettled([...this.activeRequests]),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, STOP_GRACE);
+            }),
+        ]);
+        clearTimeout(timer);
+        server.closeAllConnections();
+        await closed;
+    }
+    /**
+     * Takes back a message the gateway does not answer because it stops. One it refuses while it
+     * is being handed over gets its webhook request answered `503`. One it dropped after its
+     * request was answered cannot come again, since Bot Framework does not send an activity twice
+     * once it was taken, so it is logged.
+     */
+    async redeliver(msg) {
+        const key = this.deliveryKeys.get(msg.id);
+        if (key && this.inFlight.has(key) && !this.answeredEarly.has(key)) {
+            this.refused.add(key);
+            return;
+        }
+        if (key)
+            this.delivered.delete(key);
+        console.warn(`[teams] The message ${msg.id} in ${msg.channelId} was dropped unanswered after its request was answered, so Bot Framework will not send it again`);
+    }
+    /**
+     * Answers a request Bot Framework posts: checks its token, answers at once and hands the
+     * activity to the agent after. A button press of an Adaptive Card (`Action.Execute`) is
+     * answered with the press's answer in the response, within a few seconds. Mount it in any HTTP
+     * server with the raw body. It works before `start()` too, answers a message `503` while no
+     * `onMessage` handler is set, so Bot Framework sends it again, and answers `503` once stopped.
+     */
+    async handleWebhook(request) {
+        if (this.stopped)
+            return textResponse(503, 'The channel is stopped');
+        if (request.method !== 'POST')
+            return textResponse(405, 'Method not allowed');
+        const authorization = header(request.headers, 'authorization') ?? '';
+        if (authorization.slice(0, 7).toLowerCase() !== 'bearer ') {
+            return textResponse(401, 'Unauthorized');
+        }
+        let verified;
+        try {
+            verified = await this.verifier.verify(authorization.slice(7).trim());
+        }
+        catch (error) {
+            if (!(error instanceof TeamsAuthError))
+                throw error;
+            if (error.status === 503)
+                console.error(error.message, error.cause);
+            return textResponse(error.status, error.status === 503 ? 'Unavailable' : 'Unauthorized');
+        }
+        let activity;
+        try {
+            activity = parseActivity(JSON.parse(bodyText(request.rawBody ?? '')));
+        }
+        catch {
+            return textResponse(400, 'Invalid activity');
+        }
+        if (verified.serviceUrl !== activity.serviceUrl) {
+            return textResponse(401, 'Unauthorized');
+        }
+        if (!verified.endorsements.includes(activity.channelId)) {
+            return textResponse(403, 'Forbidden');
+        }
+        if (!this.allowsServiceUrl(activity.serviceUrl))
+            return textResponse(403, 'Forbidden');
+        if (activity.channelId !== 'msteams')
+            return textResponse(202, 'Ignored');
+        this.rememberConversation(activity);
+        if (activity.from.id === activity.recipient?.id) {
+            return textResponse(202, 'Ignored');
+        }
+        const pressed = activity.type === 'message' ? submitDataOf(activity.value) : undefined;
+        if (activity.type === 'message' && pressed === undefined && !this.handler) {
+            return textResponse(503, 'Not ready, send it again later');
+        }
+        const key = activity.id ? `${activity.conversation.id}|${activity.id}` : undefined;
+        if (key !== undefined) {
+            if (this.delivered.has(key)) {
+                return activity.type === 'invoke'
+                    ? jsonResponse(200, { statusCode: 200, type: ACTIVITY_MESSAGE, value: ACTION_RECEIVED })
+                    : textResponse(200, 'Already received');
+            }
+            this.delivered.add(key);
+            forgetOldest(this.delivered);
+        }
+        if (activity.type === 'invoke')
+            return this.invoke(activity);
+        if (activity.type !== 'message')
+            return textResponse(202, 'Accepted');
+        if (pressed !== undefined) {
+            if (this.admits(activity)) {
+                void this.press(activity, pressed).catch((error) => console.error('[teams] Button press failed:', error));
+            }
+            return textResponse(202, 'Accepted');
+        }
+        return this.handOver(activity, key);
+    }
+    /**
+     * A Node request listener that answers Bot Framework's requests on any path it is mounted at.
+     * Bodies over `webhook.maxBody` (1 MB by default) are refused with `413`.
+     */
+    webhookListener() {
+        const limit = this.config.webhook?.maxBody ?? TEAMS_DEFAULT_MAX_BODY;
+        return (req, res) => {
+            readBody(req, limit)
+                .then((rawBody) => this.handleWebhook({ method: req.method ?? 'GET', headers: req.headers, rawBody }))
+                .then((response) => res
+                .writeHead(response.status, { 'content-type': response.contentType })
+                .end(response.body))
+                .catch((error) => {
+                if (error instanceof BodyTooLarge) {
+                    res.writeHead(413, { 'content-type': 'text/plain', connection: 'close' });
+                    res.end('Payload too large');
+                    return;
+                }
+                console.error('[teams] Webhook request failed:', error);
+                if (!res.headersSent)
+                    res.writeHead(500);
+                res.end();
+            });
+        };
+    }
+    /**
+     * Sends `text` to the conversation `channelId`, in the channel thread of `topicId`, as several
+     * messages when it is longer than one holds. With `replyTo` the first one replies to that
+     * message, and `buttons` go under the last as an Adaptive Card. Resolves with the id of the
+     * first message.
+     */
+    async sendText(channelId, text, options) {
+        const conversationId = joinConversation(channelId, options?.topicId);
+        const parts = splitTeamsText(text);
+        if (parts.length === 0)
+            throw new Error('[teams] Nothing to send');
+        const textFormat = textFormatOf(options?.format);
+        const card = options?.buttons?.length ? buttonsCard(options.buttons) : undefined;
+        const ids = [];
+        for (const [index, part] of parts.entries()) {
+            const last = index === parts.length - 1;
+            ids.push(await this.post(conversationId, { text: part, textFormat, ...(last && card && { card }) }, index === 0 ? options?.replyTo : undefined));
+        }
+        return ids[0] ?? '';
+    }
+    /**
+     * Replaces the text of a message the bot sent, keeping its buttons as they are now, also when
+     * a change of them is still on its way, unless `buttons` are given. Updates of one message go
+     * out one at a time, at least {@link TEAMS_MIN_EDIT_INTERVAL} apart and behind new messages
+     * when the conversation nears its limits, and those made meanwhile are folded into the next,
+     * the latest text winning, so a streamed answer never queues more than Teams takes.
+     */
+    async editText(channelId, messageId, text, options) {
+        if (text.length > TEAMS_MESSAGE_CHARS) {
+            throw new Error(`[teams] A message holds at most ${TEAMS_MESSAGE_CHARS} characters`);
+        }
+        const known = this.updates.get(messageId)?.next ?? this.sent.get(messageId);
+        const textFormat = textFormatOf(options?.format);
+        const card = options?.buttons?.length ? buttonsCard(options.buttons) : undefined;
+        return this.update(known?.conversationId ?? joinConversation(channelId, options?.topicId), messageId, (current) => ({ ...current, text, textFormat, ...(card && { card }) }));
+    }
+    /** Replaces the buttons of a message the bot sent, or removes them with `null`. */
+    async editButtons(channelId, messageId, buttons) {
+        const known = this.sent.get(messageId) ?? this.updates.get(messageId)?.next;
+        if (!known) {
+            throw new Error(`[teams] The text of message ${messageId} in ${channelId} is not known, so its buttons cannot be changed`);
+        }
+        const card = buttons?.length ? buttonsCard(buttons) : undefined;
+        return this.update(known.conversationId, messageId, (current) => {
+            const kept = {
+                conversationId: current.conversationId,
+                text: current.text,
+                textFormat: current.textFormat,
+            };
+            return card ? { ...kept, card } : kept;
+        });
+    }
+    /** Deletes a message the bot sent. */
+    async deleteMessage(channelId, messageId) {
+        const conversationId = this.sent.get(messageId)?.conversationId ?? channelId;
+        await this.call('DELETE', conversationId, activitiesPath(conversationId, messageId));
+        this.sent.delete(messageId);
+    }
+    /**
+     * Shows the typing indicator. It is skipped when the conversation has no room for it now, or
+     * Teams blocks the bot's messages there, since a late indicator says nothing.
+     */
+    async sendTyping(channelId, options) {
+        const conversationId = joinConversation(channelId, options?.topicId);
+        const key = paceKeyOf(conversationId);
+        if (this.stopped || this.blocked.has(key) || !this.pacer.tryAcquire(key))
+            return;
+        await this.call('POST', conversationId, activitiesPath(conversationId), { type: 'typing' }, { priority: 'background', reserved: true, retries: 0 });
+    }
+    /**
+     * Sends a file. A `buffer` goes out in personal chats only: Teams asks the user to accept it
+     * with a file consent card and the file is uploaded to their OneDrive once they do, which needs
+     * `supportsFiles` in the app manifest. Bots cannot upload files to group chats and channels
+     * without Microsoft Graph, so there a file needs a public `url`: an image is shown inline,
+     * another file is sent as a link. Resolves with the id of the message sent.
+     */
+    async sendFile(channelId, file, options) {
+        const conversationId = joinConversation(channelId, options?.topicId);
+        const filename = file.filename ?? (file.type === 'image' ? 'image' : 'file');
+        const textFormat = textFormatOf(options?.format);
+        if (file.buffer) {
+            if (file.buffer.length === 0)
+                throw new Error('[teams] The file is empty');
+            if (this.typeOf(conversationId) !== 'personal') {
+                throw new Error('[teams] Teams takes uploads from bots in personal chats only: in group chats and channels send a file with a public url');
+            }
+            const uploadId = randomUUID();
+            const buffer = Buffer.from(file.buffer);
+            this.expireUploads();
+            remember(this.uploads, uploadId, {
+                conversationId,
+                buffer,
+                filename,
+                ...(file.caption && { caption: file.caption }),
+                textFormat,
+                createdAt: Date.now(),
+            }, MAX_PENDING_UPLOADS);
+            return this.post(conversationId, {
+                text: '',
+                textFormat,
+                attachments: [
+                    {
+                        contentType: FILE_CONSENT_CARD,
+                        name: filename,
+                        content: {
+                            description: file.caption ?? filename,
+                            sizeInBytes: buffer.length,
+                            acceptContext: { uploadId },
+                            declineContext: { uploadId },
+                        },
+                    },
+                ],
+            });
+        }
+        if (!file.url || !/^https?:\/\//i.test(file.url)) {
+            throw new Error('[teams] A file needs a buffer (personal chats) or a public http(s) url');
+        }
+        if (file.type === 'image') {
+            return this.post(conversationId, {
+                text: file.caption ?? '',
+                textFormat,
+                attachments: [{ contentType: file.mimeType, contentUrl: file.url, name: filename }],
+            }, options?.replyTo);
+        }
+        const link = `[${filename.replace(/[[\]]/g, '')}](<${file.url}>)`;
+        return this.sendText(channelId, file.caption ? `${file.caption}\n\n${link}` : link, options);
+    }
+    /**
+     * Answers a button press. An `Action.Execute` press still waiting for its answer gets it in
+     * the response, shown to the user who pressed. Otherwise a `text` is sent to the conversation
+     * as a message, since Teams has no other way to answer a press. An `alert`, meant for the one
+     * who pressed only (such as "this prompt expired"), is not posted where everyone reads it.
+     */
+    async answerAction(actionId, options) {
+        const pending = this.answers.get(actionId);
+        if (pending) {
+            this.answers.delete(actionId);
+            pending.resolve(options ?? {});
+            return;
+        }
+        const conversationId = this.actionConversations.get(actionId);
+        this.actionConversations.delete(actionId);
+        if (!options?.text || options.alert || !conversationId)
+            return;
+        await this.post(conversationId, { text: options.text, textFormat: 'plain' });
+    }
+    allowedTenants() {
+        if (this.config.tenants === '*')
+            return [];
+        return this.config.tenants ?? (this.tenantId ? [this.tenantId] : []);
+    }
+    /** Whether the sender of an activity may talk to the bot: by their tenant and the user list. */
+    admits(activity) {
+        if (tenantsDisagree(activity))
+            return false;
+        if (this.config.tenants !== '*') {
+            const tenant = tenantOf(activity)?.toLowerCase();
+            if (!tenant || !this.allowedTenants().some((allowed) => allowed.toLowerCase() === tenant)) {
+                return false;
+            }
+        }
+        const users = this.config.users;
+        if (users?.length) {
+            const { aadObjectId, id } = activity.from;
+            return users.some((user) => user === aadObjectId || user === id);
+        }
+        return true;
+    }
+    allowsServiceUrl(serviceUrl) {
+        let url;
+        try {
+            url = new URL(serviceUrl);
+        }
+        catch {
+            return false;
+        }
+        const plainAllowed = this.config.openIdMetadataUrl !== undefined;
+        if (url.protocol !== 'https:' && !(plainAllowed && url.protocol === 'http:'))
+            return false;
+        const hosts = this.config.serviceUrlHosts;
+        if (!hosts?.length)
+            return true;
+        const host = url.hostname.toLowerCase();
+        return hosts.some((allowed) => allowed.toLowerCase() === host);
+    }
+    /** Remembers the Bot Connector and kind of the conversation of a verified activity. */
+    rememberConversation(activity) {
+        const { id, conversationType } = activity.conversation;
+        const entry = {
+            serviceUrl: activity.serviceUrl,
+            type: conversationTypeOf(id, conversationType),
+        };
+        remember(this.conversations, id, entry, MAX_CONVERSATIONS);
+        this.blocked.delete(paceKeyOf(id));
+        const { channelId } = splitConversation(id);
+        if (channelId !== id)
+            remember(this.conversations, channelId, entry, MAX_CONVERSATIONS);
+    }
+    serviceUrlOf(conversationId) {
+        return (this.conversations.get(conversationId)?.serviceUrl ??
+            this.conversations.get(splitConversation(conversationId).channelId)?.serviceUrl ??
+            this.config.serviceUrl ??
+            TEAMS_GLOBAL_SERVICE_URL);
+    }
+    typeOf(conversationId) {
+        return this.conversations.get(conversationId)?.type ?? conversationTypeOf(conversationId);
+    }
+    /**
+     * Calls the Bot Connector for a conversation, paced by its limits. A conversation where Teams
+     * blocks the bot's messages is not called again until an activity comes from it, and nothing
+     * is called once the channel stopped: its waits and requests under way are aborted.
+     */
+    async call(method, conversationId, path, body, options = {}) {
+        const key = paceKeyOf(conversationId);
+        if (this.stopped)
+            throw new Error(`[teams] ${method} ${path} refused: the channel is stopped`);
+        if (this.blocked.has(key)) {
+            throw new TeamsApiError('auth', `${method} ${path} skipped: Teams blocks the bot's messages in this conversation (MessageWritesBlocked) until the user writes again`, { status: 403, errorCode: 'MessageWritesBlocked' });
+        }
+        try {
+            return await this.client.request(method, this.serviceUrlOf(conversationId), path, body, {
+                key,
+                ...(options.priority && { priority: options.priority }),
+                ...(options.reserved && { reserved: true }),
+            }, {
+                signal: this.halt.signal,
+                ...(options.retries !== undefined && { retries: options.retries }),
+            });
+        }
+        catch (error) {
+            if (error instanceof TeamsApiError && error.errorCode === 'MessageWritesBlocked') {
+                this.blocked.add(key);
+                forgetOldest(this.blocked);
+            }
+            throw error;
+        }
+    }
+    /** Where a message of an activity goes: the chat, and the channel thread it is in. */
+    placeOf(activity) {
+        const conversation = activity.conversation;
+        const type = conversationTypeOf(conversation.id, conversation.conversationType);
+        const { channelId, topicId } = splitConversation(conversation.id);
+        if (type === 'personal')
+            return { channelId };
+        if (type === 'groupChat')
+            return { channelId, ...(topicId && { topicId }), groupId: channelId };
+        const root = topicId ?? activity.replyToId ?? activity.id;
+        return {
+            channelId,
+            ...(root && { topicId: root }),
+            groupId: teamOf(activity) ?? channelId,
+        };
+    }
+    /**
+     * Hands a message to the gateway and answers its request once the gateway took it, or after
+     * a few seconds. One the gateway refuses because it stops is answered `503`, and one it gives
+     * back after its request was answered is logged by `redeliver`.
+     */
+    async handOver(activity, key) {
+        const accepted = this.receive(activity, key).catch((error) => {
+            console.error('[teams] Message failed:', error);
+            return 'taken';
+        });
+        const pending = Symbol('pending');
+        const handedOver = await within(accepted, HANDOVER_TIMEOUT, pending);
+        if (handedOver === 'refused') {
+            if (key !== undefined)
+                this.delivered.delete(key);
+            return textResponse(503, 'Not taken now, send it again later');
+        }
+        if (handedOver === pending && key !== undefined) {
+            this.answeredEarly.add(key);
+            forgetOldest(this.answeredEarly);
+            void accepted.finally(() => this.answeredEarly.delete(key));
+        }
+        return textResponse(202, 'Accepted');
+    }
+    async receive(activity, key) {
+        const handler = this.handler;
+        if (!handler || !this.admits(activity))
+            return 'skipped';
+        const conversation = activity.conversation;
+        const type = conversationTypeOf(conversation.id, conversation.conversationType);
+        if (type !== 'personal' && this.config.trigger !== 'all' && !mentionsBot(activity)) {
+            return 'skipped';
+        }
+        const text = textWithoutMention(activity);
+        const attachments = await this.inboundAttachments(activity);
+        if (!text && attachments.length === 0)
+            return 'skipped';
+        const place = this.placeOf(activity);
+        const id = activity.id ?? randomUUID();
+        const message = {
+            id,
+            channelType: this.type,
+            channelId: place.channelId,
+            userId: activity.from.aadObjectId ?? activity.from.id,
+            ...(activity.from.name && { userName: activity.from.name }),
+            ...(place.groupId && { groupId: place.groupId }),
+            text,
+            ...(attachments.length > 0 && { attachments }),
+            ...(activity.replyToId && { replyTo: activity.replyToId }),
+            ...(place.topicId && { topicId: place.topicId }),
+            raw: activity,
+        };
+        const flightKey = key ?? `${conversation.id}|${id}`;
+        remember(this.deliveryKeys, id, flightKey);
+        this.inFlight.add(flightKey);
+        try {
+            await handler(message);
+        }
+        catch (error) {
+            console.error('[teams] Message handler error:', error);
+        }
+        finally {
+            this.inFlight.delete(flightKey);
+        }
+        return this.refused.delete(flightKey) ? 'refused' : 'taken';
+    }
+    /**
+     * The files of a message the agent can read: files sent in a personal chat, by their download
+     * URL, and inline images, downloaded with the bot's token from the Bot Connector the activity
+     * came through (and from nowhere else, so the token never leaves it).
+     */
+    async inboundAttachments(activity) {
+        const attachments = [];
+        const serviceHost = new URL(activity.serviceUrl).host;
+        for (const attachment of attachmentsOf(activity)) {
+            const info = downloadInfoOf(attachment);
+            if (info && /^https:\/\//i.test(info.downloadUrl)) {
+                const mimeType = mimeTypeOf(info.fileType);
+                attachments.push({
+                    type: attachmentTypeOf(mimeType),
+                    url: info.downloadUrl,
+                    mimeType,
+                    ...(attachment.name && { filename: attachment.name }),
+                });
+                continue;
+            }
+            const kind = attachmentTypeOf(attachment.contentType);
+            if (kind === 'file' || !attachment.contentUrl)
+                continue;
+            let url;
+            try {
+                url = new URL(attachment.contentUrl);
+            }
+            catch {
+                continue;
+            }
+            if (url.host !== serviceHost)
+                continue;
+            const buffer = await this.download(url.href).catch((error) => {
+                console.warn('[teams] Could not download a file of a message:', error);
+                return undefined;
+            });
+            if (!buffer)
+                continue;
+            attachments.push({
+                type: kind,
+                buffer,
+                mimeType: attachment.contentType,
+                ...(attachment.name && { filename: attachment.name }),
+            });
+        }
+        return attachments;
+    }
+    async download(url) {
+        const token = await this.credentials.token();
+        const response = await this.fetchImpl(url, {
+            headers: { authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(this.config.requestTimeout ?? TEAMS_REQUEST_TIMEOUT),
+        });
+        if (!response.ok)
+            throw new Error(`GET ${url} answered ${response.status}`);
+        const length = Number(response.headers.get('content-length'));
+        if (Number.isFinite(length) && length > MAX_INBOUND_FILE)
+            return undefined;
+        const buffer = Buffer.from(await response.arrayBuffer());
+        return buffer.byteLength > MAX_INBOUND_FILE ? undefined : buffer;
+    }
+    /** The action of a button press, from an `Action.Submit` message or an `Action.Execute` invoke. */
+    actionOf(activity, data) {
+        const place = this.placeOf(activity);
+        const id = activity.id ?? randomUUID();
+        remember(this.actionConversations, id, joinConversation(place.channelId, place.topicId));
+        return {
+            id,
+            channelType: this.type,
+            channelId: place.channelId,
+            userId: activity.from.aadObjectId ?? activity.from.id,
+            ...(activity.from.name && { userName: activity.from.name }),
+            ...(activity.replyToId && { messageId: activity.replyToId }),
+            ...(place.topicId && { topicId: place.topicId }),
+            ...(place.groupId && { groupId: place.groupId }),
+            data,
+            raw: activity,
+        };
+    }
+    async press(activity, data) {
+        if (!this.actionHandler)
+            return;
+        await this.actionHandler(this.actionOf(activity, data));
+    }
+    async invoke(activity) {
+        if (activity.name === 'adaptiveCard/action')
+            return this.execute(activity);
+        if (activity.name === 'fileConsent/invoke') {
+            const answer = fileConsentOf(activity.value);
+            if (answer && this.admits(activity)) {
+                void this.consented(activity, answer).catch((error) => console.error('[teams] Answering a file consent failed:', error));
+            }
+            return jsonResponse(200, {});
+        }
+        return textResponse(501, 'Not implemented');
+    }
+    /**
+     * Answers an `Action.Execute` press within the time Teams waits: with the text the press is
+     * answered with, or else the message's card once the press is handled (so it shows what the
+     * press changed, such as an approval's decision), or as it is when time runs out.
+     */
+    async execute(activity) {
+        const data = executeDataOf(activity.value);
+        if (data === undefined || !this.admits(activity)) {
+            return jsonResponse(200, {
+                statusCode: 400,
+                type: 'application/vnd.microsoft.error',
+                value: {
+                    code: 'BadRequest',
+                    message: data === undefined ? 'Unknown action' : 'Not allowed',
+                },
+            });
+        }
+        const action = this.actionOf(activity, data);
+        let answered = {};
+        if (this.actionHandler) {
+            const answer = new Promise((resolve) => {
+                this.answers.set(action.id, { resolve });
+            });
+            const handled = this.actionHandler(action).then(() => ({}), (error) => {
+                console.error('[teams] Button press failed:', error);
+                return {};
+            });
+            const deadline = Date.now() + INVOKE_TIMEOUT;
+            answered = await within(Promise.race([answer, handled]), INVOKE_TIMEOUT, {});
+            this.answers.delete(action.id);
+            if (!answered.text && !this.stopped) {
+                let halt = () => { };
+                const halted = new Promise((resolve) => {
+                    halt = () => resolve({});
+                });
+                this.onHalt.add(halt);
+                await within(Promise.race([handled, halted]), Math.max(0, deadline - Date.now()), {});
+                this.onHalt.delete(halt);
+            }
+        }
+        if (answered.text) {
+            return jsonResponse(200, { statusCode: 200, type: ACTIVITY_MESSAGE, value: answered.text });
+        }
+        const messageId = activity.replyToId;
+        const pending = messageId ? this.updates.get(messageId) : undefined;
+        const card = pending
+            ? pending.next.card
+            : messageId
+                ? this.sent.get(messageId)?.card
+                : undefined;
+        if (card)
+            return jsonResponse(200, { statusCode: 200, type: ADAPTIVE_CARD, value: card });
+        return jsonResponse(200, { statusCode: 200, type: ACTIVITY_MESSAGE, value: ACTION_RECEIVED });
+    }
+    /**
+     * Uploads a file the user accepted, in the conversation the consent card was sent to. A card
+     * the bot no longer knows (it restarted, or the file expired) and a declined one are answered
+     * with a short message.
+     */
+    async consented(activity, answer) {
+        const conversationId = activity.conversation.id;
+        const uploadId = answer.context?.uploadId;
+        const upload = uploadId ? this.uploads.get(uploadId) : undefined;
+        if (!uploadId || upload?.conversationId !== conversationId) {
+            if (answer.action === 'accept') {
+                await this.post(conversationId, { text: UPLOAD_GONE, textFormat: 'plain' });
+            }
+            return;
+        }
+        this.uploads.delete(uploadId);
+        if (answer.action !== 'accept' || !answer.uploadInfo) {
+            await this.post(conversationId, { text: UPLOAD_DECLINED, textFormat: 'plain' });
+            return;
+        }
+        await this.upload(upload, answer.uploadInfo).catch(async (error) => {
+            console.error(`[teams] Uploading ${upload.filename} failed:`, error);
+            await this.post(conversationId, {
+                text: `The file ${upload.filename} could not be uploaded.`,
+                textFormat: 'plain',
+            });
+        });
+    }
+    async upload(upload, info) {
+        if (!/^https:\/\//i.test(info.uploadUrl))
+            throw new Error('The upload URL is not https');
+        const size = upload.buffer.length;
+        for (let start = 0; start < size; start += UPLOAD_FRAGMENT) {
+            const end = Math.min(start + UPLOAD_FRAGMENT, size);
+            const response = await this.fetchImpl(info.uploadUrl, {
+                method: 'PUT',
+                headers: {
+                    'content-length': String(end - start),
+                    'content-range': `bytes ${start}-${end - 1}/${size}`,
+                },
+                body: new Uint8Array(upload.buffer.subarray(start, end)),
+                signal: AbortSignal.timeout(this.config.requestTimeout ?? TEAMS_REQUEST_TIMEOUT),
+            });
+            if (!response.ok)
+                throw new Error(`The upload answered ${response.status}`);
+        }
+        await this.post(upload.conversationId, {
+            text: upload.caption ?? '',
+            textFormat: upload.textFormat,
+            attachments: [
+                {
+                    contentType: FILE_INFO_CARD,
+                    contentUrl: info.contentUrl,
+                    name: info.name,
+                    content: { uniqueId: info.uniqueId, fileType: info.fileType ?? '' },
+                },
+            ],
+        });
+    }
+    expireUploads() {
+        const oldest = Date.now() - UPLOAD_TTL;
+        for (const [id, upload] of this.uploads) {
+            if (upload.createdAt >= oldest)
+                break;
+            this.uploads.delete(id);
+        }
+    }
+    /** Posts a message activity, as a reply to `replyTo` when given, and remembers what it holds. */
+    async post(conversationId, content, replyTo) {
+        const attachments = content.card
+            ? [{ contentType: ADAPTIVE_CARD, content: content.card }]
+            : content.attachments;
+        const activity = {
+            type: 'message',
+            ...(content.text && {
+                text: bodyFor(content.text, content.textFormat),
+                textFormat: content.textFormat,
+            }),
+            ...(attachments && { attachments }),
+            ...(replyTo && { replyToId: replyTo }),
+        };
+        const response = await this.call('POST', conversationId, activitiesPath(conversationId, replyTo), activity);
+        const parsed = ResourceSchema.safeParse(response);
+        const id = parsed.success ? (parsed.data.id ?? '') : '';
+        if (id && !content.attachments) {
+            remember(this.sent, id, {
+                conversationId,
+                text: content.text,
+                textFormat: content.textFormat,
+                ...(content.card && { card: content.card }),
+            });
+        }
+        return id;
+    }
+    /**
+     * Updates a message the bot sent (`PUT`), one update of it at a time: changes made while one
+     * is under way are folded into the next, which sends the latest state.
+     */
+    update(conversationId, messageId, change) {
+        let state = this.updates.get(messageId);
+        if (!state) {
+            const base = this.sent.get(messageId) ?? {
+                conversationId,
+                text: '',
+                textFormat: 'extendedmarkdown',
+            };
+            state = { conversationId, next: base, dirty: false, lastAt: 0 };
+            remember(this.updates, messageId, state);
+        }
+        state.next = change(state.next);
+        state.dirty = true;
+        state.running ??= this.drainUpdates(messageId, state);
+        return state.running;
+    }
+    /**
+     * Sends the updates of a message one at a time. When one fails while a newer state waits,
+     * the newer one is still sent, so a streamed answer ends with its final text, and only a
+     * failure of the latest state reaches the callers.
+     */
+    async drainUpdates(messageId, state) {
+        try {
+            while (state.dirty) {
+                const wait = state.lastAt + TEAMS_MIN_EDIT_INTERVAL - Date.now();
+                if (wait > 0)
+                    await pause(wait, this.halt.signal);
+                state.dirty = false;
+                const entry = state.next;
+                state.lastAt = Date.now();
+                try {
+                    await this.call('PUT', state.conversationId, activitiesPath(state.conversationId, messageId), {
+                        type: 'message',
+                        id: messageId,
+                        text: bodyFor(entry.text, entry.textFormat),
+                        textFormat: entry.textFormat,
+                        ...(entry.card && {
+                            attachments: [{ contentType: ADAPTIVE_CARD, content: entry.card }],
+                        }),
+                    }, { priority: 'background' });
+                }
+                catch (error) {
+                    if (state.dirty && !this.blocked.has(paceKeyOf(state.conversationId)))
+                        continue;
+                    throw error;
+                }
+                remember(this.sent, messageId, entry);
+            }
+        }
+        finally {
+            state.running = undefined;
+            if (this.updates.get(messageId) === state)
+                this.updates.delete(messageId);
+        }
+    }
+    listen(port, path, host) {
+        const listener = this.webhookListener();
+        const routes = this.config.webhook?.routes ?? {};
+        const server = createServer((req, res) => {
+            const finished = new Promise((resolve) => res.once('close', resolve));
+            this.activeRequests.add(finished);
+            void finished.then(() => this.activeRequests.delete(finished));
+            let pathname;
+            try {
+                pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
+            }
+            catch {
+                res.writeHead(400, { 'content-type': 'text/plain' }).end('Bad request');
+                return;
+            }
+            if (pathname === path) {
+                listener(req, res);
+                return;
+            }
+            const route = Object.hasOwn(routes, pathname) ? routes[pathname] : undefined;
+            if (route) {
+                route(req, res);
+                return;
+            }
+            res.writeHead(404).end();
+        });
+        this.server = server;
+        return new Promise((resolve, reject) => {
+            const failed = (error) => {
+                this.server = undefined;
+                reject(error);
+            };
+            server.once('error', failed);
+            server.listen(port, host, () => {
+                server.off('error', failed);
+                resolve();
+            });
+        });
+    }
+}
+/** A Microsoft Teams channel on the Bot Framework protocol. */
+export function teamsChannel(config) {
+    return new TeamsChannel(config);
+}
+//# sourceMappingURL=channel.js.map