express-msteams-host v1.3.0-preview4

Express utility for Microsoft Teams Apps

This utility for Express is targeted for Microsoft Teams applications built generated by the Microsoft Teams Yeoman generator hosted on Express.

@master	@preview

The Middleware serves two major purposes:

• Automatic routing of web services for Bots, Connectors and Outgoing Webhooks based on TypeScript decorators
• Automatic routing of static pages for Tabs and Connectors

The middleware is automatically added to projects generated by the Microsoft Teams Yeoman generator.

Usage

For the automatic routing to work the following usage MUST be followed.

Creating a bot

Implementation and decorator usage for Bots

Bots MUST be implemented as a class using the IBot interface and decorated using the BotDeclaration decorator.

import { BotDeclaration, IBot } from 'express-msteams-host';
import { MemoryStorage, ConversationState, TurnContext } from 'botbuilder';

@BotDeclaration(
    '/api/messages',
    new MemoryStorage(),
    process.env.MICROSOFT_APP_ID,
    process.env.MICROSOFT_APP_PASSWORD)
export class myBot implements IBot {

    public constructor(conversationState: ConversationState) {
        ...
    }

    public async onTurn(context: TurnContext): Promise<any> {
        ...
    }

}

Decorators for Message Extensions

Message Extensions MUST be a class implementing the IMessageExtension interface and when declared in the bot implementation decorated with the MessageExtensionDeclarator decorator.

import { IMessageExtension } from 'express-msteams-host';
import { TurnContext } from 'botbuilder';
import { MessagingExtensionQuery, InvokeResponseTyped, MessagingExtensionResponse } from 'botbuilder-teams';


export default class MyMessageExtension implements IMessageExtension {
    public async onQuery(context: TurnContext, query: MessagingExtensionQuery): Promise<InvokeResponseTyped<MessagingExtensionResponse>> {
       ...
    }

    // this is used when canUpdateConfiguration is set to true 
    public async onQuerySettingsUrl(context: TurnContext): Promise<InvokeResponseTyped<{ composeExtension: { type: string, suggestedActions: { actions: Array<{ type: string, title: string, value: string }> } } }>> {
        ...
    }

    public onSettingsUpdate(context: TurnContext): Promise<InvokeResponse> {
       ...
    }

}

In the implementation of the bot, define the message extensions as below. You are responsible for instantiating the object, you might want to add additional parameters or configuration.

import { BotDeclaration, IBot } from 'express-msteams-host';
import { MemoryStorage, ConversationState, TurnContext } from 'botbuilder';
import { MyMessageExtension } from './MyMessageExtension';

@BotDeclaration(
    '/api/messages',
    new MemoryStorage()
    process.env.MICROSOFT_APP_ID,
    process.env.MICROSOFT_APP_PASSWORD)
export class myBot implements IBot {

    @MessageExtensionDeclaration('myMessageExtension')
    private _myMessageExtension: MyMessageExtension;

    public constructor(conversationState: ConversationState) {

        this._myMessageExtension = new MyMessageExtension();

        ...
    }

}

Decorator for Connectors

Connectors MUST be implemented as a class implementing the IConnector interface and decorated using the ConnectorDeclaration decorator.

import { ConnectorDeclaration, IConnector } from 'express-msteams-host';
import { Request } from "express";

@ConnectorDeclaration(
    '/api/connector/connect',
    '/api/connector/ping',
)
export class myConnector implements IConnector {
    Connect(req: Request): void {
        ...
    }

    Ping(req: Request): Promise<void>[] {
        ...
    }
}

Decorator for Outgoing Webhooks

Outgoing Webhooks MUST be implemented as a class implementing the IOutdegoingWebhook interface and decorated using the OutgoingWebhookDeclaration decorator.

import { OutgoingWebhookDeclaration, IOutgoingWebhook } from 'express-msteams-host';
import * as express from 'express';

@OutgoingWebhookDeclaration('/api/webhook')
export class myOutgoingWebhook implements IOutgoingWebhook {
    public requestHandler(req: Express.Request, res: Express.Response, next: Express.NextFunction): any {
        ...
    }
}

Preventing pages to be iframed in other applications than Microsoft Teams

By using the PreventIframe decorator on server side classes pages can be declared to include a CSP that prohibts the pages from being iframed into other applications than Microsoft Teams.

import { PreventIframe } from "express-msteams-host";

@PreventIframe("/page/index.html")
export class MyPage {
    ...
}

Logging

To enable logging from this module you need to add msteams to the DEBUG environment variable. See the debug package for more information.

Example for Windows command line:

SET DEBUG=msteams

License

Copyright (c) Wictor Wilén. All rights reserved.

Licensed under the MIT license.