@khester/create-dynamics-app 2.6.6 → 2.8.0

package/templates/teams-app/_variants/tab.sso/src/auth-bridge.ts

@@ -0,0 +1,52 @@
+import { app, authentication } from '@microsoft/teams-js';
+import { PublicClientApplication } from '@azure/msal-browser';
+
+/**
+ * Auth bridge — loaded by auth.html inside the window Teams opens for
+ * `authentication.authenticate()`. MSAL's popup flow is blocked inside the Teams
+ * tab iframe, so interactive sign-in happens here: loginRedirect → back to this
+ * page → handleRedirectPromise → notifySuccess back to the tab.
+ */
+const setStatus = (msg: string): void => {
+  const el = document.getElementById('status');
+  if (el) el.textContent = msg;
+};
+
+(async () => {
+  try {
+    await app.initialize();
+
+    const clientId = import.meta.env.VITE_CLIENT_ID ?? '';
+    const tenantId = import.meta.env.VITE_TENANT_ID ?? 'common';
+    if (!clientId) throw new Error('VITE_CLIENT_ID is not set — copy env.local.template to .env.local');
+
+    const pca = new PublicClientApplication({
+      auth: {
+        clientId,
+        authority: `https://login.microsoftonline.com/${tenantId}`,
+        redirectUri: `${window.location.origin}/auth.html`,
+      },
+      cache: { cacheLocation: 'localStorage' },
+    });
+    await pca.initialize();
+
+    setStatus('Completing sign-in…');
+    const response = await pca.handleRedirectPromise();
+    if (response?.account) {
+      setStatus(`Signed in as ${response.account.username}`);
+      authentication.notifySuccess(response.account.username);
+      return;
+    }
+
+    setStatus('Redirecting to sign in…');
+    await pca.loginRedirect({ scopes: ['User.Read'] });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    setStatus(`Sign-in failed: ${msg}`);
+    try {
+      authentication.notifyFailure(msg);
+    } catch {
+      // Outside a Teams auth window — the status line above is the surface.
+    }
+  }
+})();

package/templates/teams-app/_variants/tab.sso/src/hooks/useTeamsAuth.ts

@@ -0,0 +1,121 @@
+import { useState, useEffect, useCallback } from 'react';
+import { app, authentication } from '@microsoft/teams-js';
+import { PublicClientApplication, type AccountInfo } from '@azure/msal-browser';
+
+/**
+ * Teams-first auth: try Teams SSO (`authentication.getAuthToken()`), fall back to
+ * MSAL. Inside the Teams iframe, interactive sign-in must go through the auth
+ * bridge (`auth.html`) — `loginPopup` is blocked there; outside Teams (plain
+ * browser tab) MSAL redirect works directly.
+ *
+ * VITE_CLIENT_ID / VITE_TENANT_ID come from `.env.local` (see env.local.template);
+ * `teams-app-manager.sh identity` writes them after registering the Entra app.
+ */
+const clientId = import.meta.env.VITE_CLIENT_ID ?? '';
+const tenantId = import.meta.env.VITE_TENANT_ID ?? 'common';
+
+const msalInstance = new PublicClientApplication({
+  auth: {
+    clientId,
+    authority: `https://login.microsoftonline.com/${tenantId}`,
+    redirectUri: window.location.origin,
+  },
+  cache: { cacheLocation: 'localStorage' },
+});
+
+export interface AuthState {
+  token: string | null;
+  account: AccountInfo | null;
+  inTeams: boolean;
+  loading: boolean;
+  error: Error | null;
+}
+
+export function useTeamsAuth(): AuthState & { login: () => Promise<void> } {
+  const [state, setState] = useState<AuthState>({
+    token: null,
+    account: null,
+    inTeams: false,
+    loading: true,
+    error: null,
+  });
+
+  const getToken = useCallback(async () => {
+    // 1. Teams SSO — works once the app registration exposes api://{host}/{clientId}
+    //    with the Teams client ids pre-authorized.
+    try {
+      await app.initialize();
+      const ssoToken = await authentication.getAuthToken();
+      setState({ token: ssoToken, account: null, inTeams: true, loading: false, error: null });
+      return;
+    } catch {
+      // Not in Teams, or SSO not consented yet — fall through to MSAL.
+    }
+
+    // 2. MSAL silent — a previous interactive sign-in left an account in the cache.
+    try {
+      await msalInstance.initialize();
+      const redirect = await msalInstance.handleRedirectPromise().catch(() => null);
+      const account = redirect?.account ?? msalInstance.getAllAccounts()[0];
+      if (account) {
+        const result = await msalInstance.acquireTokenSilent({
+          scopes: ['User.Read'],
+          account,
+        });
+        setState({
+          token: result.accessToken,
+          account: result.account,
+          inTeams: false,
+          loading: false,
+          error: null,
+        });
+        return;
+      }
+      setState((prev) => ({ ...prev, loading: false }));
+    } catch (error) {
+      setState((prev) => ({ ...prev, loading: false, error: error as Error }));
+    }
+  }, []);
+
+  /** Interactive sign-in. In Teams → auth bridge popup; in a browser → MSAL redirect. */
+  const login = useCallback(async () => {
+    if (!clientId) {
+      setState((prev) => ({
+        ...prev,
+        error: new Error('VITE_CLIENT_ID is not set — copy env.local.template to .env.local'),
+      }));
+      return;
+    }
+    let inTeams = false;
+    try {
+      await app.initialize();
+      inTeams = true;
+    } catch {
+      // Plain browser tab.
+    }
+
+    try {
+      if (inTeams) {
+        // Teams opens auth.html in a real window where MSAL's redirect flow is
+        // allowed; the bridge calls notifySuccess/notifyFailure when done.
+        await authentication.authenticate({
+          url: `${window.location.origin}/auth.html`,
+          width: 600,
+          height: 535,
+        });
+        await getToken();
+        return;
+      }
+      await msalInstance.initialize();
+      await msalInstance.loginRedirect({ scopes: ['User.Read'] });
+    } catch (error) {
+      setState((prev) => ({ ...prev, error: error as Error }));
+    }
+  }, [getToken]);
+
+  useEffect(() => {
+    void getToken();
+  }, [getToken]);
+
+  return { ...state, login };
+}

package/templates/teams-app/_variants/tab.sso/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_CLIENT_ID?: string;
+  readonly VITE_TENANT_ID?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/templates/teams-app/_variants/tab.sso/vite.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { fileURLToPath, URL } from 'node:url';
+
+export default defineConfig({
+  plugins: [react()],
+  // Teams tabs must be served over HTTPS; `vite --https` or a tunnel in dev.
+  server: { port: 3000 },
+  build: {
+    outDir: 'dist',
+    rollupOptions: {
+      // MPA: the tab plus the auth bridge Teams opens for interactive sign-in.
+      input: {
+        main: fileURLToPath(new URL('./index.html', import.meta.url)),
+        auth: fileURLToPath(new URL('./auth.html', import.meta.url)),
+      },
+    },
+  },
+});

package/templates/teams-app/gitignore

@@ -1,5 +1,7 @@
 node_modules/
 dist/
+build/
 .env
 .env.local
+.teams/
 *.log

package/templates/teams-app/package.json

@@ -14,7 +14,7 @@
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "@fluentui/react-components": "^9.46.2",
-    "@microsoft/teams-js": "^2.19.0"
+    "@microsoft/teams-js": "^2.24.0"
   },
   "devDependencies": {
     "@types/react": "^18.2.0",

package/templates/teams-bot/.env.example

@@ -0,0 +1,18 @@
+# Bot Framework credentials — written to .env.local by `teams-app-manager.sh identity`
+# (which .env.local overrides; this file documents the full set). Never commit real values.
+MICROSOFT_APP_ID=
+MICROSOFT_APP_PASSWORD=
+MICROSOFT_APP_TENANT_ID=
+# SingleTenant (default) or MultiTenant — must match the Azure Bot resource's app type.
+MICROSOFT_APP_TYPE=SingleTenant
+
+# Shared secret required in the X-Notify-Key header by POST /api/notify (notification bots).
+NOTIFY_API_KEY=
+
+# Where conversation references persist (notification bots). On Azure App Service use
+# /home/data/conversations.json so subscriptions survive restarts and redeploys.
+CONVERSATION_STORE_PATH=./.data/conversations.json
+
+PORT=3978
+# Mock mode runs the bot without any Azure registration (try: npm run dev -- --interactive)
+MOCK_MODE=true

package/templates/teams-bot/README.md

@@ -0,0 +1,52 @@
+# {{projectName}}
+
+A Microsoft Teams bot built with the Bot Framework SDK v4 (TypeScript + Express),
+scaffolded by `create-dynamics-app --artifact teams-bot`.
+
+## Local development (no Azure needed)
+
+```bash
+cp .env.example .env        # MOCK_MODE=true is the default
+npm install
+npm run dev -- --interactive   # console chat loop against the bot logic
+npm run dev                    # or: run the HTTP server on http://localhost:3978
+```
+
+Mock mode drives the bot through the Bot Framework `TestAdapter` — no app registration,
+no tunnel. The HTTP server exposes:
+
+| Endpoint | Purpose |
+|----------|---------|
+| `POST /api/messages` | Bot Framework messaging endpoint |
+| `GET /health` | Health probe (used by the deploy pipeline) |
+| `POST /api/notify` | Proactive notifications (notification bots only; requires the `X-Notify-Key` header) |
+
+## Ship it to Azure + Teams
+
+The workspace pipeline provisions everything (App Service hosting, Entra app + secret,
+Azure Bot resource, Teams channel, app package):
+
+```bash
+teams-app-manager.sh up --project . --sideload
+```
+
+Or run the stages individually: `hosting` → `identity` → `deploy` → `package` → `sideload`.
+The packaged zip lands in `build/` and is uploaded to Teams via the admin center or
+"Upload a custom app". See `msft/05-m365/docs/teams-bot-runbook.md` in the workspace.
+
+## Configuration
+
+All settings come from env vars (see `.env.example`). In Azure they are App Service
+app settings; locally they live in `.env` / `.env.local` (the identity stage writes
+credentials to `.env.local`, which takes precedence).
+
+Key settings: the Bot Framework credential triple (app id / password / tenant id), the
+app type (SingleTenant default — must match the Azure Bot resource), the notify API key,
+and the conversation-store path (notification bots persist subscriber references there;
+on App Service use `/home/data/conversations.json` so they survive restarts).
+
+## Manifest
+
+`appPackage/manifest.template.json` keeps two deploy-time placeholders — the Teams app
+id and the bot id — that `teams-app-manager.sh package` renders from the provisioning
+state; everything else is baked at scaffold time.

package/templates/teams-bot/_variants/bot.echo/appPackage/manifest.template.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.19/MicrosoftTeams.schema.json",
+  "manifestVersion": "1.19",
+  "id": "{{TEAMS_APP_ID}}",
+  "version": "1.0.0",
+  "developer": {
+    "name": "Contoso",
+    "websiteUrl": "https://example.com",
+    "privacyUrl": "https://example.com/privacy",
+    "termsOfUseUrl": "https://example.com/terms"
+  },
+  "name": { "short": "{{projectName}}", "full": "{{projectName}}" },
+  "description": { "short": "{{projectName}} bot", "full": "{{projectName}} — a Microsoft Teams bot that echoes messages and responds to commands" },
+  "icons": { "color": "color.png", "outline": "outline.png" },
+  "accentColor": "#6264A7",
+  "bots": [
+    {
+      "botId": "{{BOT_ID}}",
+      "scopes": ["personal", "team", "groupChat"],
+      "supportsFiles": false,
+      "isNotificationOnly": false
+    }
+  ],
+  "permissions": ["identity"]
+}

package/templates/teams-bot/_variants/bot.echo/src/bot/TeamsBot.ts

@@ -0,0 +1,142 @@
+import {
+  TeamsActivityHandler,
+  TurnContext,
+  MessageFactory,
+  TeamsInfo,
+  AdaptiveCardInvokeValue,
+  AdaptiveCardInvokeResponse,
+} from 'botbuilder';
+import { createWelcomeCard, createHelpCard, createAboutCard } from './welcomeCard';
+
+export class TeamsBot extends TeamsActivityHandler {
+  constructor() {
+    super();
+
+    // Handle incoming messages
+    this.onMessage(async (context: TurnContext, next: () => Promise<void>) => {
+      await this.handleMessage(context);
+      await next();
+    });
+
+    // Handle members added (welcome message)
+    this.onMembersAdded(async (context: TurnContext, next: () => Promise<void>) => {
+      await this.handleMembersAdded(context);
+      await next();
+    });
+
+    // Handle members removed
+    this.onMembersRemoved(async (context: TurnContext, next: () => Promise<void>) => {
+      await this.handleMembersRemoved(context);
+      await next();
+    });
+  }
+
+  private async handleMessage(context: TurnContext): Promise<void> {
+    // Remove bot mention from message
+    const text = this.removeMentionText(context);
+    const command = text.toLowerCase().trim();
+
+    console.log(`Received message: "${text}"`);
+
+    // Handle commands
+    switch (command) {
+      case 'help':
+        await context.sendActivity({
+          attachments: [createHelpCard()],
+        });
+        break;
+
+      case 'about':
+        await context.sendActivity({
+          attachments: [createAboutCard()],
+        });
+        break;
+
+      default:
+        // Echo the message back
+        if (command.startsWith('echo ')) {
+          const echoText = text.substring(5);
+          await context.sendActivity(MessageFactory.text(`Echo: ${echoText}`));
+        } else {
+          await context.sendActivity(MessageFactory.text(`You said: "${text}"`));
+        }
+        break;
+    }
+  }
+
+  private async handleMembersAdded(context: TurnContext): Promise<void> {
+    const membersAdded = context.activity.membersAdded || [];
+    const botId = context.activity.recipient.id;
+
+    for (const member of membersAdded) {
+      // Only send welcome when the bot is added, not when users join
+      if (member.id !== botId) {
+        continue;
+      }
+
+      // Get the user's name
+      let userName = 'there';
+      try {
+        const members = await TeamsInfo.getMembers(context);
+        if (members && members.length > 0) {
+          // Find the user who added the bot (typically the first non-bot member)
+          const user = members.find((m) => m.id !== botId);
+          if (user) {
+            userName = user.name || user.givenName || 'there';
+          }
+        }
+      } catch (error) {
+        console.log('Could not get team members, using default greeting');
+      }
+
+      // Send welcome card
+      await context.sendActivity({
+        attachments: [createWelcomeCard(userName)],
+      });
+    }
+  }
+
+  private async handleMembersRemoved(context: TurnContext): Promise<void> {
+    const membersRemoved = context.activity.membersRemoved || [];
+
+    for (const member of membersRemoved) {
+      console.log(`Member removed: ${member.name || member.id}`);
+    }
+  }
+
+  // Handle Adaptive Card submit actions
+  protected async onAdaptiveCardInvoke(
+    context: TurnContext,
+    invokeValue: AdaptiveCardInvokeValue
+  ): Promise<AdaptiveCardInvokeResponse> {
+    const action = invokeValue.action?.data?.action;
+
+    if (action === 'hello') {
+      await context.sendActivity(MessageFactory.text('Hello! How can I help you today?'));
+    }
+
+    return {
+      statusCode: 200,
+      type: 'application/vnd.microsoft.activity.message',
+      value: { message: 'Action processed' },
+    };
+  }
+
+  // Helper to remove @mention from message text
+  private removeMentionText(context: TurnContext): string {
+    let text = context.activity.text || '';
+    const mentions = context.activity.entities?.filter(
+      (e) => e.type === 'mention'
+    );
+
+    if (mentions && mentions.length > 0) {
+      for (const mention of mentions) {
+        if (mention.mentioned?.id === context.activity.recipient.id) {
+          text = text.replace(mention.text || '', '').trim();
+        }
+      }
+    }
+
+    return text;
+  }
+}

package/templates/teams-bot/_variants/bot.echo/src/bot/welcomeCard.ts

@@ -0,0 +1,134 @@
+import { CardFactory, Attachment } from 'botbuilder';
+
+export function createWelcomeCard(userName: string): Attachment {
+  const card = {
+    type: 'AdaptiveCard',
+    $schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
+    version: '1.4',
+    body: [
+      {
+        type: 'TextBlock',
+        size: 'Large',
+        weight: 'Bolder',
+        text: `Welcome, ${userName}!`,
+        wrap: true,
+      },
+      {
+        type: 'TextBlock',
+        text: "I'm a Teams bot built with Bot Framework. Here's what I can do:",
+        wrap: true,
+        spacing: 'Medium',
+      },
+      {
+        type: 'FactSet',
+        facts: [
+          { title: 'Echo', value: 'I repeat what you say' },
+          { title: 'Help', value: 'Type "help" for commands' },
+          { title: 'About', value: 'Type "about" for info' },
+        ],
+      },
+      {
+        type: 'TextBlock',
+        text: 'Try sending me a message!',
+        wrap: true,
+        spacing: 'Medium',
+        color: 'Accent',
+      },
+    ],
+    actions: [
+      {
+        type: 'Action.Submit',
+        title: 'Say Hello',
+        data: { action: 'hello' },
+      },
+    ],
+  };
+
+  return CardFactory.adaptiveCard(card);
+}
+
+export function createHelpCard(): Attachment {
+  const card = {
+    type: 'AdaptiveCard',
+    $schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
+    version: '1.4',
+    body: [
+      {
+        type: 'TextBlock',
+        size: 'Medium',
+        weight: 'Bolder',
+        text: 'Available Commands',
+        wrap: true,
+      },
+      {
+        type: 'Container',
+        items: [
+          {
+            type: 'TextBlock',
+            text: '**help** - Show this help message',
+            wrap: true,
+          },
+          {
+            type: 'TextBlock',
+            text: '**about** - Learn about this bot',
+            wrap: true,
+          },
+          {
+            type: 'TextBlock',
+            text: '**echo [message]** - Echo your message',
+            wrap: true,
+          },
+          {
+            type: 'TextBlock',
+            text: 'Or just type anything and I will echo it back!',
+            wrap: true,
+            spacing: 'Medium',
+            isSubtle: true,
+          },
+        ],
+      },
+    ],
+  };
+
+  return CardFactory.adaptiveCard(card);
+}
+
+export function createAboutCard(): Attachment {
+  const card = {
+    type: 'AdaptiveCard',
+    $schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
+    version: '1.4',
+    body: [
+      {
+        type: 'TextBlock',
+        size: 'Medium',
+        weight: 'Bolder',
+        text: 'About This Bot',
+        wrap: true,
+      },
+      {
+        type: 'FactSet',
+        facts: [
+          { title: 'Name', value: '{{projectName}}' },
+          { title: 'Framework', value: 'Bot Framework SDK v4' },
+          { title: 'Scaffold', value: 'create-dynamics-app (teams-bot)' },
+        ],
+      },
+      {
+        type: 'TextBlock',
+        text: 'This bot demonstrates the fundamentals of building a Teams bot using the Bot Framework SDK.',
+        wrap: true,
+        spacing: 'Medium',
+      },
+    ],
+    actions: [
+      {
+        type: 'Action.OpenUrl',
+        title: 'View Documentation',
+        url: 'https://learn.microsoft.com/en-us/microsoftteams/platform/bots/what-are-bots',
+      },
+    ],
+  };
+
+  return CardFactory.adaptiveCard(card);
+}

package/templates/teams-bot/_variants/bot.echo/src/index.ts

@@ -0,0 +1,59 @@
+import express, { Request, Response } from 'express';
+import { config, validateConfig } from './config';
+import { createBotAdapter } from './adapters/botAdapter';
+import { TeamsBot } from './bot/TeamsBot';
+import { startInteractiveTest } from './mock/mockMode';
+
+validateConfig();
+
+// Interactive mock mode: console chat loop, no server / no Azure.
+if (process.argv.includes('--interactive')) {
+  startInteractiveTest();
+} else {
+  const app = express();
+  app.use(express.json());
+
+  const adapter = createBotAdapter();
+  const bot = new TeamsBot();
+
+  // Health check endpoint (the deploy pipeline gates on this)
+  app.get('/health', (_req: Request, res: Response) => {
+    res.json({
+      status: 'healthy',
+      timestamp: new Date().toISOString(),
+      mockMode: config.mockMode,
+    });
+  });
+
+  // Bot messaging endpoint
+  app.post('/api/messages', async (req: Request, res: Response) => {
+    try {
+      await adapter.process(req, res, (context) => bot.run(context));
+    } catch (error) {
+      console.error('Error processing message:', error);
+      res.status(500).send('Internal Server Error');
+    }
+  });
+
+  app.get('/', (_req: Request, res: Response) => {
+    res.json({
+      name: '{{projectName}}',
+      description: 'Microsoft Teams echo bot (Bot Framework SDK v4)',
+      endpoints: { messaging: '/api/messages', health: '/health' },
+      mockMode: config.mockMode,
+    });
+  });
+
+  app.listen(config.port, () => {
+    console.log(`\nBot server is running!`);
+    console.log(`   Local:  http://localhost:${config.port}`);
+    console.log(`   Health: http://localhost:${config.port}/health`);
+    console.log(`   Mode:   ${config.mockMode ? 'Mock (development)' : 'Production'}`);
+    console.log(`\n   Messaging endpoint: /api/messages`);
+
+    if (config.mockMode) {
+      console.log(`\nTip: run with --interactive for console testing:`);
+      console.log(`   npm run dev -- --interactive`);
+    }
+  });
+}