@dbx-tools/teams 0.3.39

package/src/builder.ts

@@ -0,0 +1,102 @@
+/**
+ * Compile a high-level {@link card.CardSpec} into a valid Adaptive Card 1.5
+ * document. The model drafts the small semantic spec; this is the single place
+ * that turns it into the element tree the `adaptivecards` renderer consumes and
+ * Teams accepts, so a card is well-formed by construction rather than by hoping
+ * the model produced correct schema.
+ *
+ * Element choices are deliberate and conservative:
+ * - the title is a bold, large `TextBlock`; the subtitle a lighter one;
+ * - body text is a wrapping `TextBlock` (Teams renders its Markdown subset);
+ * - facts become a single `FactSet` (the right control for key/value detail);
+ * - each action becomes an `Action.OpenUrl` - the one action safe to render in
+ *   any host with no back end wired up.
+ *
+ * @module
+ */
+
+import { card } from "@dbx-tools/shared-teams";
+
+/** An Adaptive Card element (loosely typed; the builder owns the exact shapes). */
+type CardElement = Record<string, unknown>;
+
+/** Build the title / subtitle heading block(s). */
+function headingElements(spec: card.CardSpec): CardElement[] {
+  const elements: CardElement[] = [
+    {
+      type: "TextBlock",
+      text: spec.title,
+      size: "Large",
+      weight: "Bolder",
+      wrap: true,
+    },
+  ];
+  if (spec.subtitle) {
+    elements.push({
+      type: "TextBlock",
+      text: spec.subtitle,
+      isSubtle: true,
+      spacing: "None",
+      wrap: true,
+    });
+  }
+  return elements;
+}
+
+/** Build the optional body `TextBlock`. */
+function textElements(spec: card.CardSpec): CardElement[] {
+  if (!spec.text) return [];
+  return [{ type: "TextBlock", text: spec.text, wrap: true }];
+}
+
+/** Build the optional `FactSet` from the spec's facts. */
+function factElements(spec: card.CardSpec): CardElement[] {
+  if (!spec.facts || spec.facts.length === 0) return [];
+  return [
+    {
+      type: "FactSet",
+      facts: spec.facts.map((fact) => ({ title: fact.title, value: fact.value })),
+    },
+  ];
+}
+
+/** Build the `Action.OpenUrl` actions from the spec's link buttons. */
+function actionElements(spec: card.CardSpec): CardElement[] {
+  if (!spec.actions || spec.actions.length === 0) return [];
+  return spec.actions.map((action) => ({
+    type: "Action.OpenUrl",
+    title: action.title,
+    url: action.url,
+  }));
+}
+
+/**
+ * Compile a semantic card spec into a full Adaptive Card document. The result
+ * validates against {@link card.adaptiveCardSchema} and is ready to render with
+ * the `adaptivecards` package or post to a Teams incoming webhook.
+ */
+export function buildAdaptiveCard(spec: card.CardSpec): card.AdaptiveCard {
+  const body: CardElement[] = [
+    ...headingElements(spec),
+    ...textElements(spec),
+    ...factElements(spec),
+  ];
+  const actions = actionElements(spec);
+  const document: card.AdaptiveCard = {
+    type: "AdaptiveCard",
+    $schema: card.ADAPTIVE_CARD_SCHEMA_URL,
+    version: card.ADAPTIVE_CARD_VERSION,
+    body,
+    ...(actions.length > 0 ? { actions } : {}),
+  };
+  return document;
+}
+
+/**
+ * Compile a spec into the tool/route result shape: the validated Adaptive Card
+ * document plus the title echoed back for a caller that wants a label without
+ * re-reading the document.
+ */
+export function buildCardResult(spec: card.CardSpec): card.CardResult {
+  return { title: spec.title, card: buildAdaptiveCard(spec) };
+}

package/src/config.ts

@@ -0,0 +1,268 @@
+/**
+ * Configuration for the Teams plugin: the typed {@link TeamsPluginConfig}
+ * (the plugin's slice of AppKit config), the JSON Schema the manifest
+ * publishes for it, and {@link resolveTeamsConfig} which layers that config
+ * over environment defaults into the concrete {@link ResolvedTeamsConfig} the
+ * runtime + tools read.
+ *
+ * Building a card is a pure transform, so the config is deliberately small:
+ * the Adaptive Card version the builder targets, an optional Teams
+ * incoming-webhook URL a deployment can wire up to actually POST cards to a
+ * channel, and which sibling plugin owns the agents the conversation endpoint
+ * answers with.
+ *
+ * The remaining fields are the Azure Bot registration a real Teams channel
+ * needs: `appId` / `appPassword` (the bot's Entra application credentials, used
+ * both to validate the inbound JWT audience and to fetch the outbound Connector
+ * token) and `appTenantId` (set only for a single-tenant bot). When no `appId`
+ * is configured the `/messages` endpoint stays MOUNTED but refuses every
+ * request, so an unconfigured deployment cannot accidentally expose an
+ * unauthenticated bot endpoint.
+ *
+ * Env fallbacks: `TEAMS_CARD_VERSION`, `TEAMS_WEBHOOK_URL`,
+ * `TEAMS_AGENT_PLUGIN`, `TEAMS_APP_ID`, `TEAMS_APP_PASSWORD`,
+ * `TEAMS_APP_TENANT_ID`. The `MICROSOFT_APP_*` spellings the Bot Framework SDK
+ * uses are accepted as aliases so an existing bot's environment drops in
+ * unchanged.
+ *
+ * @module
+ */
+
+import { ValidationError, type BasePluginConfig } from "@databricks/appkit";
+import { object, string } from "@dbx-tools/shared-core";
+import { card } from "@dbx-tools/shared-teams";
+import type { JSONSchema7 } from "json-schema";
+
+/** Dedicated override for the Adaptive Card schema version the builder targets. */
+export const CARD_VERSION_ENV = "TEAMS_CARD_VERSION";
+
+/** Environment name for an optional Teams incoming-webhook URL. */
+export const WEBHOOK_URL_ENV = "TEAMS_WEBHOOK_URL";
+
+/** Environment name overriding which sibling plugin provides the agents. */
+export const AGENT_PLUGIN_ENV = "TEAMS_AGENT_PLUGIN";
+
+/**
+ * Environment names for the bot's Entra app id, in precedence order. The
+ * `MICROSOFT_APP_ID` alias is what the Bot Framework SDK and the Azure portal's
+ * generated settings use, so an existing bot deployment needs no new variable.
+ */
+export const APP_ID_ENVS = ["TEAMS_APP_ID", "MICROSOFT_APP_ID"] as const;
+
+/** Environment names for the bot's client secret, in precedence order. */
+export const APP_PASSWORD_ENVS = ["TEAMS_APP_PASSWORD", "MICROSOFT_APP_PASSWORD"] as const;
+
+/**
+ * Environment names for the bot's tenant, in precedence order. Set only for a
+ * single-tenant bot; a multi-tenant bot leaves it unset.
+ */
+export const APP_TENANT_ENVS = ["TEAMS_APP_TENANT_ID", "MICROSOFT_APP_TENANT_ID"] as const;
+
+/**
+ * Environment name for the unauthenticated-messaging escape hatch. Named
+ * `TEAMS_ALLOW_UNAUTHENTICATED` (rather than something softer like `TEAMS_DEV`)
+ * so what it disables is unmistakable in a shell history or deploy manifest.
+ */
+export const ALLOW_UNAUTHENTICATED_ENV = "TEAMS_ALLOW_UNAUTHENTICATED";
+
+/**
+ * Default registered name of the plugin the conversation endpoint asks for an
+ * agent. `mastra` is the name `@dbx-tools/appkit-mastra` registers under.
+ */
+export const DEFAULT_AGENT_PLUGIN = "mastra";
+
+/** AppKit config accepted by the Teams plugin. */
+export interface TeamsPluginConfig extends BasePluginConfig {
+  /**
+   * Adaptive Card schema version the builder targets. Defaults to
+   * {@link card.ADAPTIVE_CARD_VERSION} (`"1.5"`, what Teams supports). Falls
+   * back to `TEAMS_CARD_VERSION`.
+   */
+  cardVersion?: string;
+  /**
+   * Optional Teams incoming-webhook URL. When set, the plugin's `postCard`
+   * export / route posts the compiled card to this channel; when unset,
+   * posting is disabled and the plugin only builds cards for the UI to render.
+   * Falls back to `TEAMS_WEBHOOK_URL`.
+   */
+  webhookUrl?: string;
+  /**
+   * Registered name of the sibling plugin whose agents answer a conversation
+   * turn. Defaults to {@link DEFAULT_AGENT_PLUGIN} (`"mastra"`); set it when the
+   * Mastra plugin is mounted under a `config.name` override. Falls back to
+   * `TEAMS_AGENT_PLUGIN`.
+   */
+  agentPlugin?: string;
+  /**
+   * The bot's Entra application (client) id from its Azure Bot registration.
+   * Required before `POST /api/teams/messages` will accept a request: it is the
+   * audience an inbound Bot Framework token must carry, and the client id used
+   * to fetch an outbound Connector token. Falls back to `TEAMS_APP_ID` /
+   * `MICROSOFT_APP_ID`.
+   */
+  appId?: string;
+  /**
+   * Client secret for {@link appId}. Needed to send replies through the
+   * Connector API; without it inbound activities still validate but the bot
+   * cannot answer. Falls back to `TEAMS_APP_PASSWORD` /
+   * `MICROSOFT_APP_PASSWORD`.
+   */
+  appPassword?: string;
+  /**
+   * Tenant id for a SINGLE-tenant bot registration. Leave unset for a
+   * multi-tenant bot. Falls back to `TEAMS_APP_TENANT_ID` /
+   * `MICROSOFT_APP_TENANT_ID`.
+   */
+  appTenantId?: string;
+  /**
+   * Serve `POST /messages` with NO inbound token validation, and reply in the
+   * HTTP response instead of through the Connector API.
+   *
+   * This exists so the messaging endpoint can be exercised locally - by the
+   * in-repo preview chat, a `curl`, or the Bot Framework Emulator - without an
+   * Azure Bot registration. It removes the endpoint's ONLY trust boundary: any
+   * caller that can reach the route can drive the agent and read its answers.
+   *
+   * Never enable it on a deployment reachable from the internet. It is ignored
+   * unless `NODE_ENV` is `development` (see {@link resolveTeamsConfig}), so a
+   * production build cannot be talked into it by an environment variable alone.
+   * Falls back to `TEAMS_ALLOW_UNAUTHENTICATED`.
+   */
+  allowUnauthenticated?: boolean;
+}
+
+/** The concrete config the runtime reads, after config + env resolution. */
+export interface ResolvedTeamsConfig {
+  /** Adaptive Card schema version the builder stamps onto every document. */
+  cardVersion: string;
+  /** Teams incoming-webhook URL, or `undefined` when posting is disabled. */
+  webhookUrl?: string;
+  /** Registered name of the plugin the conversation endpoint resolves agents from. */
+  agentPlugin: string;
+  /** Bot app (client) id, or `undefined` when no bot registration is configured. */
+  appId?: string;
+  /** Bot client secret, or `undefined` when replies cannot be sent. */
+  appPassword?: string;
+  /** Tenant id for a single-tenant bot, or `undefined` for a multi-tenant one. */
+  appTenantId?: string;
+  /**
+   * Whether `POST /messages` serves turns with NO token validation. See
+   * {@link TeamsPluginConfig.allowUnauthenticated}.
+   */
+  allowUnauthenticated: boolean;
+}
+
+/** JSON Schema published in the plugin manifest for {@link TeamsPluginConfig}. */
+export const TEAMS_CONFIG_SCHEMA: JSONSchema7 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    cardVersion: {
+      type: "string",
+      description: `Adaptive Card schema version the builder targets. ${CARD_VERSION_ENV} overrides it.`,
+    },
+    webhookUrl: {
+      type: "string",
+      description: `Optional Teams incoming-webhook URL used to post cards. ${WEBHOOK_URL_ENV} overrides it.`,
+    },
+    agentPlugin: {
+      type: "string",
+      description: `Registered name of the sibling plugin whose agents answer a conversation turn. ${AGENT_PLUGIN_ENV} overrides it.`,
+    },
+    appId: {
+      type: "string",
+      description: `Entra app (client) id of the Azure Bot registration. Required for the Teams messaging endpoint. ${APP_ID_ENVS[0]} overrides it.`,
+    },
+    appPassword: {
+      type: "string",
+      description: `Client secret for the bot app id, used to fetch an outbound Connector token. ${APP_PASSWORD_ENVS[0]} overrides it.`,
+    },
+    appTenantId: {
+      type: "string",
+      description: `Tenant id for a single-tenant bot registration; unset for multi-tenant. ${APP_TENANT_ENVS[0]} overrides it.`,
+    },
+    allowUnauthenticated: {
+      type: "boolean",
+      description:
+        "Serve the Teams messaging endpoint with NO token validation, replying in " +
+        "the HTTP response. Local development only; ignored unless NODE_ENV is " +
+        `development. ${ALLOW_UNAUTHENTICATED_ENV} overrides it.`,
+    },
+  },
+};
+
+/**
+ * Layer the plugin config over environment defaults into the concrete config
+ * the runtime uses. Fails loudly on a webhook URL that is present but not a
+ * valid absolute URL, since that is a deploy-time mistake.
+ */
+export function resolveTeamsConfig(overrides?: TeamsPluginConfig): ResolvedTeamsConfig {
+  const cardVersion =
+    string.trimToNull(overrides?.cardVersion) ??
+    string.trimToNull(process.env[CARD_VERSION_ENV]) ??
+    card.ADAPTIVE_CARD_VERSION;
+  const webhookUrl =
+    string.trimToNull(overrides?.webhookUrl) ?? string.trimToNull(process.env[WEBHOOK_URL_ENV]);
+  if (webhookUrl !== null && !isAbsoluteUrl(webhookUrl)) {
+    throw ValidationError.invalidValue(
+      WEBHOOK_URL_ENV,
+      webhookUrl,
+      "an absolute https URL for the Teams webhook",
+    );
+  }
+  const agentPlugin =
+    string.trimToNull(overrides?.agentPlugin) ??
+    string.trimToNull(process.env[AGENT_PLUGIN_ENV]) ??
+    DEFAULT_AGENT_PLUGIN;
+  // Two independent conditions must BOTH hold: the operator asked for it, and
+  // this is a development build. Gating on `NODE_ENV` as well means a stray
+  // variable in a production environment cannot silently expose the endpoint.
+  const requested =
+    overrides?.allowUnauthenticated ?? object.toBoolean(process.env[ALLOW_UNAUTHENTICATED_ENV]);
+  const allowUnauthenticated = requested === true && process.env.NODE_ENV === "development";
+  return {
+    cardVersion,
+    agentPlugin,
+    allowUnauthenticated,
+    ...(webhookUrl !== null ? { webhookUrl } : {}),
+    ...spread("appId", string.trimToNull(overrides?.appId) ?? fromEnv(APP_ID_ENVS)),
+    ...spread(
+      "appPassword",
+      string.trimToNull(overrides?.appPassword) ?? fromEnv(APP_PASSWORD_ENVS),
+    ),
+    ...spread("appTenantId", string.trimToNull(overrides?.appTenantId) ?? fromEnv(APP_TENANT_ENVS)),
+  };
+}
+
+/**
+ * First non-empty value among `names` in the environment, or `null`. Lets a
+ * `TEAMS_*` variable win over the `MICROSOFT_APP_*` alias the Bot Framework SDK
+ * uses without duplicating the lookup per field.
+ */
+function fromEnv(names: readonly string[]): string | null {
+  for (const name of names) {
+    const value = string.trimToNull(process.env[name]);
+    if (value !== null) return value;
+  }
+  return null;
+}
+
+/**
+ * `{ [key]: value }` when `value` is present, otherwise nothing - so an absent
+ * optional field stays ABSENT rather than becoming an explicit `undefined`,
+ * which `exactOptionalPropertyTypes` rejects.
+ */
+function spread<K extends string>(key: K, value: string | null): Record<K, string> | undefined {
+  return value === null ? undefined : ({ [key]: value } as Record<K, string>);
+}
+
+/** Whether `value` parses as an absolute URL. */
+function isAbsoluteUrl(value: string): boolean {
+  try {
+    // eslint-disable-next-line no-new
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/connector.ts

@@ -0,0 +1,103 @@
+/**
+ * Bot Framework Connector API client - how a reply actually reaches Teams.
+ *
+ * This is the part that makes the difference between a chat API and a bot. Azure
+ * Bot Service does NOT read replies from the body of the `/messages` response:
+ * it expects `200` (an acknowledgement that the activity was accepted) and then
+ * a separate, authenticated call back to the `serviceUrl` the activity arrived
+ * with. So a turn is inherently asynchronous - acknowledge, think, then deliver.
+ *
+ * Two calls are modelled, both `POST` to the conversation's activity collection:
+ *
+ *   - {@link sendActivity} - `POST /v3/conversations/{id}/activities/{replyToId}`
+ *     delivers a reply threaded under the user's message.
+ *   - {@link sendTyping} - the same call with a `typing` activity, which is what
+ *     puts the "…" indicator in the channel while the agent works.
+ *
+ * `serviceUrl` is always supplied by the CALLER from a validated source (see
+ * `isAllowedServiceUrl`), never read straight off an untrusted request body:
+ * these calls carry the bot's bearer token, so the destination host is a
+ * security-relevant input.
+ *
+ * @module
+ */
+
+import { log } from "@dbx-tools/shared-core";
+import type { activity as activityContract } from "@dbx-tools/shared-teams";
+
+const logger = log.logger("teams:connector");
+
+/** Everything needed to address one Connector call. */
+export interface ConnectorTarget {
+  /** Base URL the activity arrived from, e.g. `https://smba.trafficmanager.net/amer/`. */
+  serviceUrl: string;
+  /** Conversation the reply belongs to. */
+  conversationId: string;
+  /** Bearer token for the bot's app registration. */
+  token: string;
+  /** Activity the reply threads under, when replying to a specific message. */
+  replyToId?: string;
+  /** Cancels the request with the turn. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Build the activities URL for a conversation.
+ *
+ * `replyToId` selects the threaded form, which is what makes a reply appear
+ * attached to the user's message rather than as a loose channel post.
+ */
+const activitiesUrl = (target: ConnectorTarget): string => {
+  const base = target.serviceUrl.replace(/\/+$/, "");
+  const conversation = encodeURIComponent(target.conversationId);
+  const suffix = target.replyToId ? `/${encodeURIComponent(target.replyToId)}` : "";
+  return `${base}/v3/conversations/${conversation}/activities${suffix}`;
+};
+
+/**
+ * Deliver one activity to a conversation through the Connector API.
+ *
+ * Returns the id the channel assigned the posted activity, when it reports one -
+ * useful for a later update/delete, and for correlating logs with what a user
+ * sees in the channel.
+ */
+export const sendActivity = async (
+  activity: activityContract.Activity,
+  target: ConnectorTarget,
+): Promise<string | undefined> => {
+  const response = await fetch(activitiesUrl(target), {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${target.token}`,
+    },
+    body: JSON.stringify(activity),
+    ...(target.signal ? { signal: target.signal } : {}),
+  });
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(`teams: connector rejected the activity (${response.status}) ${detail}`.trim());
+  }
+  const payload = (await response.json().catch(() => null)) as { id?: unknown } | null;
+  const id = typeof payload?.id === "string" ? payload.id : undefined;
+  logger.debug("activity delivered", { conversation: target.conversationId, id });
+  return id;
+};
+
+/**
+ * Show the typing indicator in the conversation.
+ *
+ * Best-effort by design: a failed indicator must never fail the turn, because
+ * the card that follows is the actual answer. A failure is logged at debug and
+ * swallowed.
+ */
+export const sendTyping = async (target: ConnectorTarget): Promise<void> => {
+  try {
+    await sendActivity({ type: "typing" }, target);
+  } catch (err) {
+    logger.debug("typing indicator failed", {
+      conversation: target.conversationId,
+      error: (err as Error).message,
+    });
+  }
+};