@atomist/automation-client/lib/spi/message/MessageClient.d.ts

Atomist API for software low-level client

import { Action, SlackMessage } from "@atomist/slack-messages";
import { AnyOptions } from "../../configuration";
import { HandleCommand } from "../../HandleCommand";
import { HandlerContext } from "../../HandlerContext";
import { Source } from "../../internal/transport/RequestProcessor";
import { ParameterType } from "../../SmartParameters";
/**
 * Implemented by classes that can send bot messages, whether to
 * channels or individuals, including actions and updates.
 */
export interface MessageClient {
    /**
     * Send a response back to where this command request originated.
     * @param msg
     * @param {MessageOptions} options
     * @returns {Promise<any>}
     */
    respond(msg: any, options?: MessageOptions): Promise<any>;
    /**
     * Send a message to any given destination.
     * @param msg
     * @param {Destination | Destination[]} destinations
     * @param {MessageOptions} options
     * @returns {Promise<any>}
     */
    send(msg: any, destinations: Destination | Destination[], options?: MessageOptions): Promise<any>;
    /**
     * Optionally delete message that was previously sent.
     * @param destinations
     * @param id
     */
    delete?(destinations: Destination | Destination[], options: RequiredMessageOptions): Promise<void>;
}
/**
 * MessageClient to send messages to the default Slack team.
 */
export interface SlackMessageClient {
    /**
     * Send a message to a Slack user
     * @param {string | SlackMessage | SlackFileMessage} msg
     * @param {string | string[]} users
     * @param {MessageOptions} options
     * @returns {Promise<any>}
     */
    addressUsers(msg: string | SlackMessage | SlackFileMessage, users: string | string[], options?: MessageOptions): Promise<any>;
    /**
     * Send a message to a Slack channel
     * @param {string | SlackMessage | SlackFileMessage} msg
     * @param {string | string[]} channels
     * @param {MessageOptions} options
     * @returns {Promise<any>}
     */
    addressChannels(msg: string | SlackMessage | SlackFileMessage, channels: string | string[], options?: MessageOptions): Promise<any>;
}
/**
 * Basic message destination.
 */
export interface Destination {
    /** Type of Destination. */
    userAgent: string;
}
/**
 * Message Destination for the Web App.
 */
export declare class WebDestination implements Destination {
    static WEB_USER_AGENT: string;
    userAgent: string;
}
/**
 * Message Destination for the Web App.
 */
export declare class SourceDestination implements Destination {
    readonly source: Source;
    readonly system: "slack" | "web";
    static SOURCE_USER_AGENT: string;
    userAgent: string;
    constructor(source: Source, system: "slack" | "web");
}
export declare function addressWeb(): WebDestination;
/**
 * Message Destination for Slack.
 */
export declare class SlackDestination implements Destination {
    team: string;
    static SLACK_USER_AGENT: string;
    userAgent: string;
    /** Slack user names to send message to. */
    users: string[];
    /** Slack channel names to send message to. */
    channels: string[];
    /**
     * Create a Destination suitable for sending messages to a Slack
     * workspace.
     *
     * @param team Slack workspace ID, which typically starts with the
     *             letter "T", consists of numbers and upper-case letters,
     *             and is nine characters long.  It can be obtained by
     *             sending the Atomist Slack bot the message "team".
     * @return {SlackDestination} A MessageClient suitable for sending messages.
     */
    constructor(team: string);
    /**
     * Address user by Slack user name.  This method appends the
     * provided user to a list of users that will be sent the message
     * via this Destination.  In other words, calling repeatedly with
     * differing Slack user names results in the message being sent to
     * all such users.
     *
     * @param {string} user Slack user name.
     * @returns {SlackDestination} MessageClient Destination that results
     *          in message being send to user.
     */
    addressUser(user: string): SlackDestination;
    /**
     * Address channel by Slack channel name.  This method appends the
     * provided channel to a list of channels that will be sent the
     * message via this Destination.  In other words, calling
     * repeatedly with differing Slack channel names results in the
     * message being sent to all such channels.
     *
     * @param {string} channel Slack channel name.
     * @returns {SlackDestination} MessageClient Destination that results
     *          in message being send to channel.
     */
    addressChannel(channel: string): SlackDestination;
}
/**
 * Shortcut for creating a SlackDestination which addresses the given
 * users.
 *
 * @param {string} team Slack workspace ID to create Destination for.
 * @param {string} users Slack user names to send message to.
 * @returns {SlackDestination} MessageClient Destination to pass to `send`.
 */
export declare function addressSlackUsers(team: string, ...users: string[]): SlackDestination;
/**
 * Shortcut for creating a SlackDestination which addresses the given
 * users in all Slack teams connected to the context.
 *
 * @param {HandlerContext} ctx Handler context as passed to the Handler handle method.
 * @param {string} users Slack user names to send message to.
 * @returns {Promise<SlackDestination>} MessageClient Destination to pass to `send`.
 */
export declare function addressSlackUsersFromContext(ctx: HandlerContext, ...users: string[]): Promise<SlackDestination>;
/**
 * Shortcut for creating a SlackDestination which addresses the given
 * channels.
 *
 * @param {string} team Slack workspace ID to create Destination for.
 * @param {string} channels Slack channel names to send messages to.
 * @returns {SlackDestination} MessageClient Destination to pass to `send`.
 */
export declare function addressSlackChannels(team: string, ...channels: string[]): SlackDestination;
/**
 * Shortcut for creating a SlackDestination which addresses the given
 * channels in all Slack teams connected to the context.
 *
 * @param {HandlerContext} ctx Handler context as passed to the Handler handle method.
 * @param {string} channels Slack channel names to send messages to.
 * @returns {Promise<SlackDestination>} MessageClient Destination to pass to `send`.
 */
export declare function addressSlackChannelsFromContext(ctx: HandlerContext, ...channels: string[]): Promise<SlackDestination>;
/**
 * Message Destination for Custom Event types.
 */
export declare class CustomEventDestination implements Destination {
    rootType: string;
    static INGESTER_USER_AGENT: string;
    userAgent: string;
    /**
     * Constructur returning a Destination for creating an instance of
     * the Custom Event type `rootType`.
     */
    constructor(rootType: string);
}
/**
 * Helper wrapping the constructor for CustomEventDestination.
 */
export declare function addressEvent(rootType: string): CustomEventDestination;
/**
 * Message to create a Snippet in Slack
 */
export interface SlackFileMessage {
    content: string;
    title?: string;
    fileName?: string;
    fileType?: string;
    comment?: string;
}
export declare type RequiredMessageOptions = Pick<MessageOptions, "id" | "thread"> & {
    id: string;
};
/**
 * Options for sending messages using the MessageClient.
 */
export interface MessageOptions extends AnyOptions {
    /**
     * Unique message id per channel and team. This is required
     * if you wish to re-write a message at a later time.
     */
    id?: string;
    /**
     * Time to live for a posted message. If ts + ttl of the
     * existing message with ts is < as a new incoming message
     * with the same id, the message will be re-written.
     */
    ttl?: number;
    /**
     * Timestamp of the message. The timestamp needs to be
     * sortable lexicographically. Should be in milliseconds and
     * defaults to Date.now().
     *
     * This is only applicable if id is set too.
     */
    ts?: number;
    /**
     * If update_only is given, this message will only be posted
     * if a previous message with the same id exists.
     */
    post?: "update_only" | "always";
    /**
     * Optional thread identifier to send this message to or true to send
     * this to the message that triggered this command.
     */
    thread?: string | boolean;
}
/** Valid MessageClient types. */
export declare const MessageMimeTypes: {
    SLACK_JSON: string;
    SLACK_FILE_JSON: string;
    PLAIN_TEXT: string;
    APPLICATION_JSON: string;
};
export interface CommandReferencingAction extends Action {
    command: CommandReference;
}
/**
 * Information about a command handler used to connect message actions
 * to a command.
 */
export interface CommandReference {
    /**
     * The id of the action as referenced in the markup.
     */
    id: string;
    /**
     * The name of the command the button or menu should invoke
     * when selected.
     */
    name: string;
    /**
     *  List of parameters to be passed to the command.
     */
    parameters?: {
        [key: string]: any;
    };
    /**
     * Name of the parameter that should be used to pass the values
     * of the menu drop-down.
     */
    parameterName?: string;
}
/**
 * Create a slack button that invokes a command handler.
 */
export declare function buttonForCommand(buttonSpec: ButtonSpecification, command: string | HandleCommand, parameters?: ParameterType): Action;
/**
 * Create a Slack menu that invokes a command handler.
 */
export declare function menuForCommand(selectSpec: MenuSpecification, command: string | HandleCommand, parameterName: string, parameters?: ParameterType): Action;
/**
 * Check if the object is a valid Slack message.
 */
export declare function isSlackMessage(object: any): object is SlackMessage;
/**
 * Check if the object is a valid Slack file message, i.e., a snippet.
 */
export declare function isFileMessage(object: any): object is SlackFileMessage;
/**
 * Extract command name from the argument.
 */
export declare function commandName(command: any): string;
/**
 * Merge the provided parameters into any parameters provided as
 * command object instance variables.
 */
export declare function mergeParameters(command: any, parameters: any): any;
export interface ActionConfirmation {
    title?: string;
    text: string;
    ok_text?: string;
    dismiss_text?: string;
}
export interface ButtonSpecification {
    text: string;
    style?: string;
    confirm?: ActionConfirmation;
    role?: string;
}
export interface SelectOption {
    text: string;
    value: string;
}
export interface OptionGroup {
    text: string;
    options: SelectOption[];
}
export declare type DataSource = "static" | "users" | "channels" | "conversations" | "external";
export interface MenuSpecification {
    text: string;
    options: SelectOption[] | DataSource | OptionGroup[];
    role?: string;
}
//# sourceMappingURL=MessageClient.d.ts.map