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;
    /**
     * Options forwarded to {@link injectWidgetProtocol} when the protocol
     * is auto-injected into the widget HTML. Use this to configure
     * notifications, display modes, or enable CSP violation debugging
     * without calling `injectWidgetProtocol` manually.
     *
     * The `name` field is always set from the payload's `name` and cannot
     * be overridden here.
     */
    protocolOptions?: Omit<IInjectWidgetProtocolOptions, 'name'>;
}
/**
 * Known host notification types from the MCP Apps spec (`ui/notifications/*`).
 * These are the suffix portion of the full method name, e.g. 'tool-result'
 * maps to the JSON-RPC method `ui/notifications/tool-result`.
 *
 * @see MCP Apps Protocol (SEP-1865) - Notifications section
 */
type WidgetNotification = 'tool-result' | 'tool-input' | 'tool-input-partial' | 'tool-cancelled' | 'host-context-changed' | 'resource-teardown' | (string & {});
/**
 * Options for injecting the MCP Apps protocol into widget HTML.
 *
 * @experimental This API is in preview and may change in the future.
 * Diagnostic: ExperimentalTeamsHtmlWidget
 */
export interface IInjectWidgetProtocolOptions {
    /**
     * The widget app name sent during ui/initialize.
     * @default 'widget'
     */
    name?: string;
    /**
     * The widget app version sent during ui/initialize.
     * @default '1.0.0'
     */
    version?: string;
    /**
     * Capabilities declared to the host during the `ui/initialize` handshake.
     * Sent as `appCapabilities` in the init request per the MCP Apps spec.
     */
    appCapabilities?: {
        /**
         * Display modes this widget supports. An array because a widget can
         * declare support for multiple modes (e.g. both inline and fullscreen).
         * The host uses this to determine which mode transitions to offer the user.
         *
         * Note: 'pip' is defined in the MCP Apps spec but not yet supported by Teams.
         *
         * @example ['inline', 'fullscreen']
         */
        availableDisplayModes?: Array<'inline' | 'fullscreen' | 'pip'>;
    };
    /**
     * Host notifications to listen for. These correspond to JSON-RPC methods
     * defined in the MCP Apps spec under `ui/notifications/*`. For each
     * notification included, define the matching `window.onX` callback in
     * your widget HTML to handle it.
     *
     * Known notifications (from the MCP Apps spec):
     * - `'tool-result'` (`ui/notifications/tool-result`) - define `window.onToolResult`
     * - `'tool-input'` (`ui/notifications/tool-input`) - define `window.onToolInput`
     * - `'tool-input-partial'` (`ui/notifications/tool-input-partial`) - define `window.onToolInputPartial`
     * - `'tool-cancelled'` (`ui/notifications/tool-cancelled`) - define `window.onToolCancelled`
     * - `'host-context-changed'` (`ui/notifications/host-context-changed`) - define `window.onHostContextChanged`
     * - `'resource-teardown'` (`ui/notifications/resource-teardown`) - define `window.onResourceTeardown`
     *
     * Unknown notification names are ignored (only the above are injected).
     *
     * @default [] (no notification hooks injected)
     */
    notifications?: WidgetNotification[];
    /**
     * When true, injects a `securitypolicyviolation` event listener that logs CSP violations to the console.
     * This catches dynamically constructed URLs that static analysis ({@link validateSecurityPolicy}) cannot detect.
     *
     * Should only be enabled during development.
     *
     * @default false
     */
    debugCspViolations?: boolean;
}
/**
 * Injects the MCP Apps protocol script into widget HTML.
 *
 * This is a convenience helper - widgets that implement the protocol themselves do not need to use it.
 * {@link buildHtmlWidgetMarkdown} calls this internally, so most developers won't call it directly.
 *
 * This sets up:
 * - The ui/initialize handshake (required for rendering)
 * - Size reporting via ui/notifications/size-changed
 * - Optional notification hooks (opt-in via `notifications` option)
 *
 * If the HTML already contains the protocol (detected by the presence of `ui/initialize`), it is returned unchanged.
 *
 * @param html - The raw HTML content for the widget.
 * @param options - Optional configuration for the protocol setup.
 * @returns The HTML with the protocol script injected.
 *
 * @experimental This API is in preview and may change in the future.
 * Diagnostic: ExperimentalTeamsHtmlWidget
 */
export declare function injectWidgetProtocol(html: string, options?: IInjectWidgetProtocolOptions): string;
/**
 * Wraps an HTML widget payload in the ` ```html-widget ` markdown code fence
 * format required by Teams to render the widget in a message.
 *
 * @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.
 *
 * @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)`). Use the `debugCspViolations`
 * option on {@link injectWidgetProtocol} for runtime detection.
 *
 * 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;
export {};