@microsoft/teams.apps/dist/utils/html-widget.d.ts

<p> <a href="https://www.npmjs.com/package/@microsoft/teams.apps" target="_blank"> <img src="https://img.shields.io/npm/v/@microsoft/teams.apps/latest" /> </a> <a href="https://www.npmjs.com/package/@microsoft/teams.apps?activeTab=code

import { IHtmlWidgetPayload, IHtmlWidgetSecurityPolicy, IMcpUiUpdateModelContextRequest } from '@microsoft/teams.api';
/**
 * Input type for the widget builder functions. Identical to {@link IHtmlWidgetPayload}
 * but `type` is optional and defaults to `'widget/mcp-ui'`.
 *
 * @experimental This API is in preview and may change in the future.
 * Diagnostic: ExperimentalTeamsHtmlWidget
 */
export type IHtmlWidgetPayloadInput = Omit<IHtmlWidgetPayload, 'type'> & {
    type?: IHtmlWidgetPayload['type'];
};
/**
 * Options for building an HTML widget markdown string.
 *
 * @experimental This API is in preview and may change in the future.
 * Diagnostic: ExperimentalTeamsHtmlWidget
 */
export interface IHtmlWidgetMarkdownOptions {
    /**
     * Text to include before the widget code block.
     */
    before?: string;
    /**
     * Text to include after the widget code block.
     */
    after?: string;
}
/**
 * Wraps an HTML widget payload in the ` ```html-widget ` markdown code fence
 * format required by Teams to render the widget in a message.
 * The widget HTML is sent as authored.
 * The widget owns the `ui/initialize` handshake and the `ui/notifications/size-changed` reporting.
 * Without a size reporter, Teams renders the widget at about 150px tall.
 *
 * @param payload - The widget payload to serialize.
 * @param options - Optional text to include before/after the widget block.
 * @returns The markdown string containing the widget code block.
 *
 * @experimental This API is in preview and may change in the future.
 * Diagnostic: ExperimentalTeamsHtmlWidget
 */
export declare function buildHtmlWidgetMarkdown(payload: IHtmlWidgetPayloadInput, options?: IHtmlWidgetMarkdownOptions): string;
/**
 * Builds a message activity containing an HTML widget, ready to be sent.
 * The widget HTML is sent as authored, so the widget owns the `ui/initialize` handshake and the `ui/notifications/size-changed` reporting.
 *
 * @param payload - The widget payload to include in the message.
 * @param options - Optional text to include before/after the widget block.
 * @returns An activity object with textFormat set to 'extendedmarkdown'.
 *
 * @experimental This API is in preview and may change in the future.
 * Diagnostic: ExperimentalTeamsHtmlWidget
 */
export declare function buildHtmlWidgetMessage(payload: IHtmlWidgetPayloadInput, options?: IHtmlWidgetMarkdownOptions): {
    type: 'message';
    text: string;
    textFormat: 'extendedmarkdown';
};
/**
 * A warning produced by {@link validateSecurityPolicy} when the widget HTML
 * references an external origin that is not present in the declared security
 * policy.
 *
 * @experimental This API is in preview and may change in the future.
 * Diagnostic: ExperimentalTeamsHtmlWidget
 */
export interface ISecurityPolicyWarning {
    /** The URL or origin found in the HTML. */
    url: string;
    /** The HTML element or API where the reference was found (e.g. `<script>`, `fetch`). */
    source: string;
    /** The securityPolicy field that should include this origin. */
    policyField: keyof IHtmlWidgetSecurityPolicy;
    /** A human-readable description of the issue. */
    message: string;
}
/**
 * Validates that external references in widget HTML are covered by the
 * declared security policy. Returns an array of warnings for any
 * references to origins not present in the appropriate policy field.
 *
 * This is a static analysis tool - it cannot catch dynamically constructed
 * URLs (e.g. `fetch('https://' + domain)`). A `securitypolicyviolation` listener in the widget
 * reports those at runtime.
 *
 * Note: The CSP keyword `'self'` cannot be validated statically because it
 * resolves to the iframe's parent origin at runtime. References that would
 * be allowed by `'self'` may still produce warnings.
 *
 * @param html - The raw HTML content of the widget.
 * @param policy - The security policy to validate against.
 * @returns An array of warnings. Empty array means no issues found.
 *
 * @experimental This API is in preview and may change in the future.
 * Diagnostic: ExperimentalTeamsHtmlWidget
 */
export declare function validateSecurityPolicy(html: string, policy: IHtmlWidgetSecurityPolicy): ISecurityPolicyWarning[];
/**
 * Attempts to extract an MCP UI update-model-context request from a message
 * activity's `value`. A widget can request that content be added to the model
 * context by reusing the messageBack mechanism (like `Action.Submit` for
 * adaptive cards). Such a request arrives as a normal message activity whose
 * `value` carries the {@link IMcpUiUpdateModelContextRequest} payload. This is
 * fire-and-forget: the bot does not respond.
 *
 * This helper is tolerant of two wire shapes:
 *   1. The raw request object (`{ method: 'ui/update-model-context', params }`).
 *   2. An envelope of the form `{ type: 'widgetModelContext', data: <request> }`.
 *
 * @param activity - A message activity (or any object with a `value` field).
 * @returns The parsed request, or `undefined` if `value` is not a valid
 *   update-model-context request.
 *
 * @experimental This API is in preview and may change in the future.
 * Diagnostic: ExperimentalTeamsHtmlWidget
 */
export declare function tryGetWidgetModelContext(activity: {
    value?: any;
} | undefined | null): IMcpUiUpdateModelContextRequest | undefined;