@mastra/teams 0.0.0 → 0.1.0-alpha.0

package/dist/index.d.cts

@@ -0,0 +1,428 @@
+import { ChannelAdapterConfig, ChannelConfig, ChannelConnectResult, ChannelHandlers, ChannelInstallationInfo, ChannelPlatformInfo, ChannelProvider, StreamingConfig, WaitUntilFn } from "@mastra/core/channels";
+import { ChannelsStorage } from "@mastra/core/storage";
+import { TeamsAdapter, TeamsAdapter as TeamsAdapter$1, TeamsAdapterConfig, createTeamsAdapter } from "@chat-adapter/teams";
+import { Mastra } from "@mastra/core/mastra";
+import { ApiRoute } from "@mastra/core/server";
+//#region src/types.d.ts
+/** Microsoft Graph origin used for Entra application provisioning. */
+declare const GRAPH_API_BASE_URL = "https://graph.microsoft.com";
+/** Teams Developer Portal origin used for Bot Framework registrations. */
+declare const DEV_PORTAL_BASE_URL = "https://dev.teams.microsoft.com";
+/** Microsoft login origin used to validate bot credentials (client-credentials mint). */
+declare const LOGIN_BASE_URL = "https://login.microsoftonline.com";
+/**
+ * OAuth scope for Microsoft Graph control-plane calls (create Entra apps,
+ * mint client secrets). Passed to the delegated {@link TeamsTokenResolver}.
+ */
+declare const TEAMS_GRAPH_SCOPE = "https://graph.microsoft.com/.default";
+/**
+ * OAuth scope for the Teams Developer Portal API (bot registrations).
+ * Tokens for this audience are distinct from Graph tokens — a single access
+ * token cannot serve both APIs. Passed to the delegated
+ * {@link TeamsTokenResolver}.
+ */
+declare const TEAMS_DEV_PORTAL_SCOPE = "https://dev.teams.microsoft.com/AppDefinitions.ReadWrite";
+/**
+ * Teams Developer Portal page where minted bot registrations are managed and
+ * packaged into a Teams app for distribution.
+ */
+declare const DEV_PORTAL_BOTS_URL = "https://dev.teams.microsoft.com/bots";
+/**
+ * Resolve an access token for a Microsoft OAuth scope on demand.
+ *
+ * Teams provisioning spans two token audiences — Microsoft Graph
+ * ({@link TEAMS_GRAPH_SCOPE}) for Entra application management and the Teams
+ * Developer Portal ({@link TEAMS_DEV_PORTAL_SCOPE}) for bot registrations — so
+ * unlike the Slack/Telegram resolvers this one is scope-aware: the provider
+ * passes the scope it needs and the resolver returns a token minted for that
+ * audience.
+ */
+type TeamsTokenResolver = (scope: string | string[], tenantId?: string) => Promise<string>;
+/**
+ * Self-managed credentials: bring your own Azure Bot registration. The
+ * Microsoft App ID / password are supplied directly (provider defaults and/or
+ * per-`connect()`) and persisted in the install store. Mutually exclusive with
+ * {@link TeamsDelegatedCredentialsConfig}.
+ */
+interface TeamsSelfManagedCredentialsConfig {
+  /** Microsoft App (client) ID of an existing bot registration. */
+  appId?: string;
+  /** Client secret for {@link appId}. */
+  appPassword?: string;
+  tokenResolver?: never;
+}
+/**
+ * Delegated credentials: an external credential manager (e.g. the Mastra
+ * platform) owns a *manager* credential that can provision bots. The provider
+ * calls the resolver with the scope it needs ({@link TEAMS_GRAPH_SCOPE} or
+ * {@link TEAMS_DEV_PORTAL_SCOPE}) during `connect()`/`disconnect()` to mint
+ * per-agent Entra applications and Developer Portal bot registrations.
+ *
+ * The manager credential is used only at provisioning time. Each provisioned
+ * bot gets its own client secret, stored (encrypted) in the install store, and
+ * the runtime authenticates with Bot Framework using that per-agent secret —
+ * no manager-credential round-trip on the message path.
+ *
+ * Mutually exclusive with direct `appId`/`appPassword` credentials.
+ */
+interface TeamsDelegatedCredentialsConfig {
+  /** Resolve a manager access token for the given Microsoft OAuth scope. */
+  tokenResolver: TeamsTokenResolver;
+  appId?: never;
+  appPassword?: never;
+}
+/**
+ * How the provider obtains bot credentials: either directly
+ * (`appId`/`appPassword`, self-managed) or by provisioning per-agent bots via
+ * a scope-aware `tokenResolver` (delegated) — never both.
+ */
+type TeamsCredentialsConfig = TeamsSelfManagedCredentialsConfig | TeamsDelegatedCredentialsConfig;
+/**
+ * Configuration for {@link TeamsProvider}.
+ */
+interface TeamsProviderConfigBase {
+  /**
+   * Public HTTPS base URL used as the bot messaging endpoint
+   * (`{baseUrl}/teams/events/{webhookId}`). May be omitted and auto-detected
+   * from the Mastra server config.
+   */
+  baseUrl?: string;
+  /**
+   * Persistence for bot installations. Defaults to Mastra's channels storage
+   * when available, falling back to an in-memory store (dev/test only).
+   */
+  storage?: ChannelsStorage;
+  /**
+   * Passphrase for encrypting the per-bot client secret at rest (AES-256-GCM).
+   * Defaults to the `MASTRA_ENCRYPTION_KEY` env var.
+   */
+  encryptionKey?: string;
+  /** Entra tenant ID for single-tenant bots. */
+  appTenantId?: string;
+  /**
+   * Bot application audience. Provisioned (delegated) bots default to
+   * `MultiTenant`.
+   * @default 'MultiTenant'
+   */
+  appType?: 'MultiTenant' | 'SingleTenant';
+  /** Override the Bot Framework service URL (e.g. sovereign clouds). Forwarded to the adapter. */
+  apiUrl?: string;
+  /** Override Microsoft Graph origin (tests / sovereign clouds). @default 'https://graph.microsoft.com' */
+  graphBaseUrl?: string;
+  /** Override the Teams Developer Portal origin (tests). @default 'https://dev.teams.microsoft.com' */
+  devPortalBaseUrl?: string;
+  /** Override the Microsoft login origin used for credential validation (tests). @default 'https://login.microsoftonline.com' */
+  loginBaseUrl?: string;
+  /** Icon URL recorded on provisioned bot registrations. */
+  botIconUrl?: string;
+  /**
+   * Keep the serverless invocation alive while the agent stream runs after the
+   * webhook returns 200. See `ChannelConfig.waitUntil`.
+   */
+  waitUntil?: WaitUntilFn;
+  /**
+   * Stream agent text to Teams as it generates (native Teams streaming in DMs,
+   * post-and-edit elsewhere — handled by the adapter).
+   * @default true
+   */
+  streaming?: StreamingConfig;
+  /**
+   * Keep a typing indicator alive during generation.
+   * @default true
+   */
+  typingStatus?: boolean;
+  /** Override built-in event handlers. Forwarded to `AgentChannels`. */
+  handlers?: ChannelHandlers;
+  /** Which media types to send inline to the model. See `ChannelConfig.inlineMedia`. */
+  inlineMedia?: ChannelConfig['inlineMedia'];
+  /** Promote URLs in message text to file parts. See `ChannelConfig.inlineLinks`. */
+  inlineLinks?: ChannelConfig['inlineLinks'];
+  /** State adapter for deduplication, locking, and subscriptions. See `ChannelConfig.state`. */
+  state?: ChannelConfig['state'];
+  /** Fetch recent thread messages when the agent joins mid-conversation. See `ChannelConfig.threadContext`. */
+  threadContext?: ChannelConfig['threadContext'];
+  /** Additional options passed directly to the Chat SDK. See `ChannelConfig.chatOptions`. */
+  chatOptions?: ChannelConfig['chatOptions'];
+  /** Resolve the memory `resourceId` before a channel thread is created. See `ChannelConfig.resolveResourceId`. */
+  resolveResourceId?: ChannelConfig['resolveResourceId'];
+  /** Resolve `waitUntil` from the request's Hono `Context`. See `ChannelConfig.resolveWaitUntil`. */
+  resolveWaitUntil?: ChannelConfig['resolveWaitUntil'];
+  /** CORS configuration for the generated Teams webhook route. */
+  cors?: ChannelAdapterConfig['cors'];
+  /** Override how errors are rendered in Teams messages. See `ChannelAdapterConfig.formatError`. */
+  formatError?: ChannelAdapterConfig['formatError'];
+  /** How tool calls are rendered in the reply. See `ChannelAdapterConfig.toolDisplay`. */
+  toolDisplay?: ChannelAdapterConfig['toolDisplay'];
+  /** Whether to expose channel reaction tools to the agent. See `ChannelConfig.tools`. */
+  tools?: ChannelConfig['tools'];
+  /** Logger forwarded to the underlying `TeamsAdapter`. */
+  logger?: TeamsAdapterConfig['logger'];
+  /** Called after an agent successfully connects and the installation is persisted. */
+  onInstall?: (installation: TeamsInstallation) => void | Promise<void>;
+}
+/** See {@link TeamsProviderConfigBase} and {@link TeamsCredentialsConfig}. */
+type TeamsProviderConfig = TeamsProviderConfigBase & TeamsCredentialsConfig;
+/** Options accepted by {@link TeamsProvider.connect}. */
+interface TeamsConnectOptions {
+  /** Display name for the bot. Defaults to the agent id. */
+  name?: string;
+  /**
+   * Microsoft App (client) ID of an existing bot registration (self-managed
+   * mode). Falls back to the provider-level `appId`. Rejected in delegated
+   * mode, where bots are provisioned per agent.
+   */
+  appId?: string;
+  /** Client secret for {@link appId} (self-managed mode). Falls back to the provider-level `appPassword`. */
+  appPassword?: string;
+  /** Entra tenant ID for single-tenant bots. Falls back to the provider-level `appTenantId`. */
+  appTenantId?: string;
+}
+/**
+ * A Teams bot bound to a single agent (one bot = one agent).
+ * Persisted through {@link TeamsInstallStore}.
+ */
+interface TeamsInstallation {
+  /** Stable installation id. */
+  id: string;
+  /** The agent this bot is bound to. */
+  agentId: string;
+  /**
+   * Opaque id embedded in the messaging endpoint path
+   * (`/teams/events/:webhookId`). Inbound requests are authenticated by
+   * Microsoft's JWT signature (verified by the adapter), not by this id.
+   */
+  webhookId: string;
+  /** Whether the bot is provisioned/validated and routable. */
+  status: 'active' | 'pending';
+  /** Microsoft App (client) ID of the bot. */
+  appId?: string;
+  /**
+   * Entra application **object id** — only set for bots this provider
+   * provisioned (delegated mode); used to delete the application on
+   * disconnect.
+   */
+  entraObjectId?: string;
+  /** Client secret the bot authenticates to Bot Framework with (encrypted at rest). */
+  appPassword?: string;
+  /** Entra tenant ID for single-tenant bots. */
+  appTenantId?: string;
+  /** Bot application audience. */
+  appType?: 'MultiTenant' | 'SingleTenant';
+  /** Display name of the bot. */
+  botName?: string;
+  /** The messaging endpoint registered for the bot. */
+  messagingEndpoint?: string;
+  /** When the installation was created. */
+  installedAt: Date;
+}
+//#endregion
+//#region src/teams-provider.d.ts
+/**
+ * Resolve the per-adapter streaming/typing config the provider applies to the
+ * Teams entry in `AgentChannels.adapters` — both default on.
+ */
+declare function resolveTeamsAdapterConfig(config: Pick<TeamsProviderConfig, 'streaming' | 'typingStatus'>): {
+  streaming: StreamingConfig;
+  typingStatus: boolean;
+};
+/**
+ * Microsoft Teams channel provider for Mastra — a {@link ChannelProvider} over
+ * `@chat-adapter/teams`. The adapter handles the Bot Framework transport
+ * (activity parse, JWT webhook verification, send/stream, typing, adaptive
+ * cards); this provider adds the install/lifecycle layer.
+ *
+ * Credential modes (mutually exclusive, enforced at the type level):
+ *
+ * - **Self-managed** — bring your own Azure Bot registration: pass
+ *   `appId`/`appPassword` (provider-level or per-`connect()`). Point the bot's
+ *   messaging endpoint at `{baseUrl}/teams/events/{webhookId}`.
+ * - **Delegated** — pass a scope-aware `tokenResolver` for a *manager*
+ *   credential; `connect(agentId)` then provisions a bot per agent: an Entra
+ *   application (Microsoft Graph), a fresh client secret, and a Teams
+ *   Developer Portal bot registration pointing at this server. The per-agent
+ *   secret is stored (encrypted) and used by the runtime — the manager
+ *   credential is never needed on the message path.
+ *
+ * @example
+ * ```ts
+ * const teams = new TeamsProvider({ baseUrl: 'https://my-app.example.com', tokenResolver });
+ * const mastra = new Mastra({ agents: { myAgent }, channels: { teams } });
+ * await teams.connect('my-agent'); // → { type: 'deep_link', url: 'https://dev.teams.microsoft.com/bots' }
+ * ```
+ */
+declare class TeamsProvider implements ChannelProvider {
+  #private;
+  readonly id = "teams";
+  constructor(config?: TeamsProviderConfig);
+  /**
+   * Called by Mastra when this channel is registered.
+   * @internal
+   */
+  __attach(mastra: Mastra): void;
+  /**
+   * Per-bot messaging endpoint. A single POST route keyed by an opaque
+   * `webhookId`; inbound requests are authenticated by Microsoft's JWT
+   * signature (verified by the adapter against the bot's `appId`), not by the
+   * path. Auto-initializes on first hit (mirrors `@mastra/slack`).
+   */
+  getRoutes(): ApiRoute[];
+  /** Discovery metadata for the editor UI. */
+  getInfo(): ChannelPlatformInfo;
+  /**
+   * Restore installations from storage: rebuild an adapter per active bot and
+   * inject `AgentChannels` so the agent can receive events immediately.
+   * Idempotent. Does not re-register messaging endpoints (they persist in the
+   * bot registration across restarts); reconnect an agent if its `baseUrl` changed.
+   */
+  initialize(): Promise<void>;
+  /**
+   * Update runtime provider settings. Pass `appId`/`appPassword` to change the
+   * default bot credentials new {@link connect} calls fall back to; pass
+   * `baseUrl`/`apiUrl` to point the provider/adapter at a different host.
+   * `null` clears the default credentials only — per-bot installs are managed
+   * via {@link connect}/{@link disconnect}.
+   */
+  configure(credentials: {
+    appId?: string;
+    appPassword?: string;
+    appTenantId?: string;
+    baseUrl?: string;
+    apiUrl?: string;
+  } | null): Promise<void>;
+  /**
+   * Connect an agent to Microsoft Teams.
+   *
+   * - **Delegated** (`tokenResolver`): provisions a per-agent bot — Entra
+   *   application + client secret via Microsoft Graph, then a Teams Developer
+   *   Portal bot registration whose messaging endpoint points at this server —
+   *   and returns `{ type: 'deep_link' }` to the Developer Portal where the
+   *   bot is packaged into a Teams app for install.
+   * - **Self-managed** with `appId`/`appPassword` (per-call or provider
+   *   default): validates the credentials via a Bot Framework token mint,
+   *   persists the installation, and returns `{ type: 'immediate' }`. Point
+   *   the bot registration's messaging endpoint at the installation's
+   *   `messagingEndpoint`.
+   * - Self-managed without credentials: persists a pending installation and
+   *   returns `{ type: 'deep_link' }` pointing at the Teams Developer Portal.
+   */
+  connect(agentId: string, options?: TeamsConnectOptions): Promise<ChannelConnectResult>;
+  /**
+   * Disconnect an agent from Microsoft Teams. For bots this provider
+   * provisioned (delegated mode), the Developer Portal registration and the
+   * Entra application are deleted best-effort — a control-plane failure never
+   * blocks removal of the local installation.
+   */
+  disconnect(agentId: string): Promise<void>;
+  /** List installations (public info only — no secrets). */
+  listInstallations(): Promise<ChannelInstallationInfo[]>;
+  /**
+   * Get the full installation for an agent (includes the client secret).
+   * Returns `null` if the agent has no Teams installation. Mirrors
+   * `SlackProvider.getInstallation`.
+   */
+  getInstallation(agentId: string): Promise<TeamsInstallation | null>;
+  /** Whether at least one bot is actively registered. */
+  isConfigured(): boolean;
+  /**
+   * Get the live `TeamsAdapter` for an installation id, if one is active.
+   * Used for message formatting/posting. Mirrors `SlackProvider.getAdapter`.
+   */
+  getAdapter(installationId: string): TeamsAdapter$1 | undefined;
+}
+//#endregion
+//#region src/install-store.d.ts
+/** Platform identifier used for every stored record and route. */
+declare const PLATFORM = "teams";
+/**
+ * Persistence for Teams bot installations, layered over the platform-agnostic
+ * `ChannelsStorage` (the same store `@mastra/slack` / `@mastra/telegram` use).
+ * Installations are keyed by agent — one bot = one agent — and the per-bot
+ * fields live in the record's `data` blob. When an `encryptionKey` is
+ * supplied, `appPassword` (the bot's client secret) is AES-256-GCM encrypted
+ * at rest.
+ */
+declare class TeamsInstallStore {
+  #private;
+  private readonly storage;
+  private readonly encryptionKey?;
+  constructor(storage: ChannelsStorage, encryptionKey?: string | undefined);
+  /** Whether secrets written through this store are encrypted at rest. */
+  get canEncrypt(): boolean;
+  /** The active or pending installation for an agent, if any. */
+  getByAgent(agentId: string): Promise<TeamsInstallation | null>;
+  /** Look up an installation by the routing id in its messaging endpoint path. */
+  getByWebhookId(webhookId: string): Promise<TeamsInstallation | null>;
+  /** Insert or replace an installation. */
+  save(installation: TeamsInstallation): Promise<void>;
+  /** All Teams installations (active and pending). */
+  list(): Promise<TeamsInstallation[]>;
+  /** Remove an agent's installation, if present. */
+  deleteByAgent(agentId: string): Promise<void>;
+}
+/** Project an installation to its public, secret-free info for the editor UI. */
+declare function toInstallationInfo(install: TeamsInstallation): ChannelInstallationInfo;
+//#endregion
+//#region src/microsoft-clients.d.ts
+/** The subset of a Graph `application` resource the provider uses. */
+interface EntraApplication {
+  /** Directory **object id** — used for subsequent Graph calls (addPassword, delete). */
+  id: string;
+  /** The application (client) id — the bot's Microsoft App ID. */
+  appId: string;
+}
+/**
+ * Create an Entra application for a per-agent bot.
+ * @see https://learn.microsoft.com/graph/api/application-post-applications
+ */
+declare function createApplication(token: string, options: {
+  displayName: string;
+  signInAudience: 'AzureADMultipleOrgs' | 'AzureADMyOrg';
+}, graphBaseUrl?: string): Promise<EntraApplication>;
+/**
+ * Mint a client secret on an Entra application. The secret text is only
+ * returned by this call — it cannot be read back later.
+ * @see https://learn.microsoft.com/graph/api/application-addpassword
+ */
+declare function addApplicationPassword(token: string, applicationObjectId: string, displayName: string, graphBaseUrl?: string): Promise<string>;
+/**
+ * Delete an Entra application. Used to clean up provisioned bots on
+ * disconnect and to roll back a partially provisioned connect.
+ * @see https://learn.microsoft.com/graph/api/application-delete
+ */
+declare function deleteApplication(token: string, applicationObjectId: string, graphBaseUrl?: string): Promise<void>;
+/**
+ * A Teams Developer Portal bot registration, as accepted by
+ * `POST https://dev.teams.microsoft.com/api/botframework` (the same contract
+ * Microsoft's Teams Toolkit CLI uses).
+ */
+interface TeamsBotRegistration {
+  /** The bot's Microsoft App (client) ID. */
+  botId: string;
+  name: string;
+  description: string;
+  iconUrl: string;
+  messagingEndpoint: string;
+  callingEndpoint: string;
+}
+/** Register a bot with the Teams Developer Portal. */
+declare function createBotRegistration(token: string, registration: TeamsBotRegistration, devPortalBaseUrl?: string): Promise<void>;
+/** Delete a Teams Developer Portal bot registration. */
+declare function deleteBotRegistration(token: string, botId: string, devPortalBaseUrl?: string): Promise<void>;
+/**
+ * Validate a bot's `appId`/`appPassword` by minting a Bot Framework token via
+ * the OAuth2 client-credentials grant — the same exchange the adapter performs
+ * at runtime, so a success here means outbound sends will authenticate.
+ * Multi-tenant bots exchange against the `botframework.com` tenant.
+ *
+ * Throws when Microsoft rejects the credentials; transport failures are
+ * surfaced as-is (tagged `isTransportError`) so callers can tell connectivity
+ * problems apart from bad credentials.
+ */
+declare function validateBotCredentials(options: {
+  appId: string;
+  appPassword: string;
+  appTenantId?: string;
+}, loginBaseUrl?: string): Promise<void>;
+//#endregion
+export { DEV_PORTAL_BASE_URL, DEV_PORTAL_BOTS_URL, type EntraApplication, GRAPH_API_BASE_URL, LOGIN_BASE_URL, PLATFORM, TEAMS_DEV_PORTAL_SCOPE, TEAMS_GRAPH_SCOPE, TeamsAdapter, type TeamsBotRegistration, type TeamsConnectOptions, type TeamsCredentialsConfig, type TeamsDelegatedCredentialsConfig, TeamsInstallStore, type TeamsInstallation, TeamsProvider, type TeamsProviderConfig, type TeamsProviderConfigBase, type TeamsSelfManagedCredentialsConfig, type TeamsTokenResolver, addApplicationPassword, createApplication, createBotRegistration, createTeamsAdapter, deleteApplication, deleteBotRegistration, resolveTeamsAdapterConfig, toInstallationInfo, validateBotCredentials };
+//# sourceMappingURL=index.d.ts.map