diff --git a/packages/types/src/block-kit/block-elements.ts b/packages/types/src/block-kit/block-elements.ts index 1eb335023..2447c73a5 100644 --- a/packages/types/src/block-kit/block-elements.ts +++ b/packages/types/src/block-kit/block-elements.ts @@ -5,15 +5,19 @@ import { Confirmable, Dispatchable, Focusable, + MaxItemsSelectable, Placeholdable, + RichTextBorderable, RichTextStyleable, + URLRespondable, } from './extensions'; import { + ColorScheme, Option, PlainTextElement, PlainTextOption, - UrlImageObject, SlackFileImageObject, + UrlImageObject, } from './composition-objects'; import { RichTextBlock } from './blocks'; @@ -51,7 +55,7 @@ export interface Button extends Actionable, Confirmable { * more sparingly than primary. * If you don't include this field, the default button style will be used. */ - style?: 'danger' | 'primary'; + style?: ColorScheme; /** * @description A label for longer descriptive text about a button element. This label will be read out by screen * readers instead of the button `text` object. Maximum length for this field is 75 characters. @@ -250,6 +254,7 @@ export interface MultiUsersSelect extends Actionable, Confirmable, Focusable, + MaxItemsSelectable, Placeholdable { /** * @description The type of element. In this case `type` is always `multi_users_select`. @@ -259,10 +264,6 @@ export interface MultiUsersSelect * @description An array of user IDs of any valid users to be pre-selected when the menu loads. */ initial_users?: string[]; - /** - * @description Specifies the maximum number of items that can be selected in the menu. Minimum number is `1`. - */ - max_selected_items?: number; } /** @@ -316,6 +317,7 @@ export interface MultiStaticSelect extends Actionable, Confirmable, Focusable, + MaxItemsSelectable, Placeholdable { /** * @description The type of element. In this case `type` is always `multi_static_select`. @@ -345,10 +347,6 @@ export interface MultiStaticSelect label: PlainTextElement; options: PlainTextOption[]; }[]; - /** - * @description Specifies the maximum number of items that can be selected in the menu. Minimum number is 1. - */ - max_selected_items?: number; } /** @@ -361,7 +359,8 @@ export interface ConversationsSelect extends Actionable, Confirmable, Focusable, - Placeholdable { + Placeholdable, + URLRespondable { /** * @description The type of element. In this case `type` is always `conversations_select`. */ @@ -371,15 +370,6 @@ export interface ConversationsSelect * `default_to_current_conversation` is also supplied, `initial_conversation` will take precedence. */ initial_conversation?: string; - // TODO: maybe factor out `response_url_enabled` into its own mixin as part of `extensions.ts`? - // this is used in channel select too - /** - * @description When set to `true`, the {@link https://api.slack.com/reference/interaction-payloads/views#view_submission `view_submission` payload} - * from the menu's parent view will contain a `response_url`. This `response_url` can be used for - * {@link https://api.slack.com/interactivity/handling#message_responses message responses}. The target conversation - * for the message will be determined by the value of this select menu. - */ - response_url_enabled?: boolean; /** * @description Pre-populates the select menu with the conversation that the user was viewing when they opened the * modal, if available. Default is `false`. @@ -408,6 +398,7 @@ export interface MultiConversationsSelect extends Actionable, Confirmable, Focusable, + MaxItemsSelectable, Placeholdable { /** * @description The type of element. In this case `type` is always `conversations_select`. @@ -419,11 +410,6 @@ export interface MultiConversationsSelect * `default_to_current_conversation` is also supplied, `initial_conversation` will be ignored. */ initial_conversations?: string[]; - // TODO: factor `max_selected_items` into its own extension / mixin? - /** - * @description Specifies the maximum number of items that can be selected in the menu. Minimum number is 1. - */ - max_selected_items?: number; /** * @description Pre-populates the select menu with the conversation that the user was viewing when they opened the * modal, if available. Default is `false`. @@ -450,7 +436,8 @@ export interface ChannelsSelect extends Actionable, Confirmable, Focusable, - Placeholdable { + Placeholdable, + URLRespondable { /** * @description The type of element. In this case `type` is always `channels_select`. */ @@ -459,15 +446,6 @@ export interface ChannelsSelect * @description The ID of any valid public channel to be pre-selected when the menu loads. */ initial_channel?: string; - // TODO: maybe factor out `response_url_enabled` into its own mixin as part of `extensions.ts`? - // this is used in convo selects too - /** - * @description When set to `true`, the {@link https://api.slack.com/reference/interaction-payloads/views#view_submission `view_submission` payload} - * from the menu's parent view will contain a `response_url`. This `response_url` can be used for - * {@link https://api.slack.com/interactivity/handling#message_responses message responses}. The target channel - * for the message will be determined by the value of this select menu. - */ - response_url_enabled?: boolean; } /** @@ -480,6 +458,7 @@ export interface MultiChannelsSelect extends Actionable, Confirmable, Focusable, + MaxItemsSelectable, Placeholdable { /** * @description The type of element. In this case `type` is always `multi_channels_select`. @@ -490,11 +469,6 @@ export interface MultiChannelsSelect * @description An array of one or more IDs of any valid public channel to be pre-selected when the menu loads. */ initial_channels?: string[]; - // TODO: maybe factor out `max_selected_items` into its own mixin in `extensions.ts`? - /** - * @description Specifies the maximum number of items that can be selected in the menu. Minimum number is 1. - */ - max_selected_items?: number; } /** @@ -534,6 +508,7 @@ export interface MultiExternalSelect extends Actionable, Confirmable, Focusable, + MaxItemsSelectable, Placeholdable { /** * @description The type of element. In this case `type` is always `multi_external_select`. @@ -550,11 +525,6 @@ export interface MultiExternalSelect * of typed characters required before dispatch. The default value is `3`. */ min_query_length?: number; - // TODO: maybe factor out `max_selected_items` into its own mixin in `extensions.ts`? - /** - * @description Specifies the maximum number of items that can be selected in the menu. Minimum number is 1. - */ - max_selected_items?: number; } /* @@ -774,7 +744,7 @@ export interface WorkflowButton extends Confirmable { * more sparingly than primary. * If you don't include this field, the default button style will be used. */ - style?: 'danger' | 'primary'; + style?: ColorScheme; /** * @description A label for longer descriptive text about a button element. This label will be read out by screen * readers instead of the button `text` object. Maximum length for this field is 75 characters. @@ -999,7 +969,7 @@ export interface RichTextSection { /** * @description A list block within a rich text field. */ -export interface RichTextList { +export interface RichTextList extends RichTextBorderable { /** * @description The type of element. In this case `type` is always `rich_text_list`. */ @@ -1018,17 +988,12 @@ export interface RichTextList { * or characters rendered as the list points. Also affected by the `style` property. */ indent?: number; - /** - * @description Whether to render a quote-block-like border on the inline side of the list. `0` renders no border - * while `1` renders a border. - */ - border?: 0 | 1; } /** * @description A quote block within a rich text field. */ -export interface RichTextQuote { +export interface RichTextQuote extends RichTextBorderable { /** * @description The type of element. In this case `type` is always `rich_text_quote`. */ @@ -1037,17 +1002,12 @@ export interface RichTextQuote { * @description An array of {@link RichTextElement} comprising the quote block. */ elements: RichTextElement[]; - /** - * @description Whether to render a quote-block-like border on the inline side of the text quote. - * `0` renders no border, while `1` renders a border. Defaults to `0`. - */ - border?: 0 | 1; } /** * @description A block of preformatted text within a rich text field. */ -export interface RichTextPreformatted { +export interface RichTextPreformatted extends RichTextBorderable { /** * @description The type of element. In this case `type` is always `rich_text_preformatted`. */ @@ -1056,11 +1016,6 @@ export interface RichTextPreformatted { * @description An array of either {@link RichTextLink} or {@link RichTextText} comprising the preformatted text. */ elements: (RichTextText | RichTextLink)[]; - /** - * @description Whether to render a quote-block-like border on the inline side of the preformatted text. - * `0` renders no border, while `1` renders a border. Defaults to `0`. - */ - border?: 0 | 1; } /** diff --git a/packages/types/src/block-kit/blocks.ts b/packages/types/src/block-kit/blocks.ts index 5eb8b8c1b..e9a157367 100644 --- a/packages/types/src/block-kit/blocks.ts +++ b/packages/types/src/block-kit/blocks.ts @@ -50,6 +50,7 @@ export interface Block { */ export type KnownBlock = ImageBlock | ContextBlock | ActionsBlock | DividerBlock | SectionBlock | InputBlock | FileBlock | HeaderBlock | VideoBlock | RichTextBlock; + /** * A helper union type of all known Blocks as well as the generic {@link Block} interface. A full list of known blocks * is available here: {@link https://api.slack.com/reference/block-kit/blocks Blocks reference}. diff --git a/packages/types/src/block-kit/composition-objects.ts b/packages/types/src/block-kit/composition-objects.ts index 5e8a1757e..41ce1e346 100644 --- a/packages/types/src/block-kit/composition-objects.ts +++ b/packages/types/src/block-kit/composition-objects.ts @@ -1,5 +1,14 @@ // This file contains objects documented here: https://api.slack.com/reference/block-kit/composition-objects +/** + * Re-usable labels for common color schemes present in Slack. `danger` displays with a red background (red text on + * mobile), while `primary` displays with a green background (green text on mobile). + */ +export type ColorScheme = 'primary' | 'danger'; + +/** The conversation type as available within the Slack UI. */ +export type ConversationType = 'im' | 'mpim' | 'private' | 'public'; + // TODO: breaking change: remove `Confirm` and move properties to `ConfirmationDialog` below on next major release. /** * @deprecated {@link Confirm} aliased to {@link ConfirmationDialog} in order to make the construct clearer @@ -17,12 +26,12 @@ export interface Confirm { * @description A {@link PlainTextElement} text object that defines the explanatory text that appears in the confirm * dialog. Maximum length for the `text` in this field is 300 characters. */ - text: PlainTextElement | MrkdwnElement; + text: PlainTextElement | MrkdwnElement; // TODO: breaking change: this should not be a mrkdwnelement /** * @description A {@link PlainTextElement} text object to define the text of the button that confirms the action. * Maximum length for the `text` in this field is 30 characters. */ - confirm?: PlainTextElement; // TODO: breaking change, text is required according to https://api.slack.com/reference/block-kit/composition-objects#confirm + confirm?: PlainTextElement; // TODO: breaking change, confirm is required according to https://api.slack.com/reference/block-kit/composition-objects#confirm /** * @description A {@link PlainTextElement} text object to define the text of the button that cancels the action. * Maximum length for the `text` in this field is 30 characters. @@ -33,7 +42,7 @@ export interface Confirm { * with a red background on desktop, or red text on mobile. A value of `primary` will display the button with a green * background on desktop, or blue text on mobile. If this field is not provided, the default value will be `primary`. */ - style?: 'primary' | 'danger'; + style?: ColorScheme; } /** @@ -164,15 +173,13 @@ export interface MrkdwnElement { verbatim?: boolean; } -type Conversation = 'im' | 'mpim' | 'private' | 'public'; - interface BaseConversationFilter { /** * @description Indicates which type of conversations should be included in the list. When this field is provided, any * conversations that do not match will be excluded. You should provide an array of strings from the following options: * `im`, `mpim`, `private`, and `public`. The array cannot be empty. */ - include?: [Conversation, ...Conversation[]]; // TS gymnastics for "at least one item" + include?: [ConversationType, ...ConversationType[]]; /** * @description Indicates whether to exclude external {@link https://api.slack.com/enterprise/shared-channels shared channels} * from conversation lists. This field will not exclude users from shared channels. Defaults to `false`. diff --git a/packages/types/src/block-kit/extensions.ts b/packages/types/src/block-kit/extensions.ts index d5b86b4ab..81feee8f8 100644 --- a/packages/types/src/block-kit/extensions.ts +++ b/packages/types/src/block-kit/extensions.ts @@ -25,6 +25,14 @@ export interface Confirmable { confirm?: ConfirmationDialog; } +export interface Dispatchable { + /** + * @description A {@link DispatchActionConfig} object that determines when during text input the element returns a + * {@link https://api.slack.com/reference/interaction-payloads/block-actions `block_actions` payload}. + */ + dispatch_action_config?: DispatchActionConfig; +} + export interface Focusable { /** * @description Indicates whether the element will be set to auto focus within the @@ -34,6 +42,13 @@ export interface Focusable { focus_on_load?: boolean; } +export interface MaxItemsSelectable { + /** + * @description Specifies the maximum number of items that can be selected. Minimum number is 1. + */ + max_selected_items?: number; +} + export interface Placeholdable { /** * @description A {@link PlainTextElement} object that defines the placeholder text shown on the element. Maximum @@ -42,12 +57,23 @@ export interface Placeholdable { placeholder?: PlainTextElement; } -export interface Dispatchable { +export interface URLRespondable { /** - * @description A {@link DispatchActionConfig} object that determines when during text input the element returns a - * {@link https://api.slack.com/reference/interaction-payloads/block-actions `block_actions` payload}. + * @description When set to `true`, the {@link https://api.slack.com/reference/interaction-payloads/views#view_submission `view_submission` payload} + * from the menu's parent view will contain a `response_url`. This `response_url` can be used for + * {@link https://api.slack.com/interactivity/handling#message_responses message responses}. The target conversation + * for the message will be determined by the value of this select menu. */ - dispatch_action_config?: DispatchActionConfig; + response_url_enabled?: boolean; +} + +/** For use in setting border style details on certain Rich Text elements. */ +export interface RichTextBorderable { + /** + * @description Whether to render a quote-block-like border on the inline side of the list. `0` renders no border + * while `1` renders a border. + */ + border?: 0 | 1; } /** diff --git a/packages/types/src/message-attachments.ts b/packages/types/src/message-attachments.ts index 9cd45d8af..59c301f42 100644 --- a/packages/types/src/message-attachments.ts +++ b/packages/types/src/message-attachments.ts @@ -102,8 +102,8 @@ export interface MessageAttachment { * relative to the present. Form factors, like mobile versus desktop may also transform its rendered appearance. */ ts?: string; - actions?: AttachmentAction[]; // TODO: not documented in https://api.slack.com/reference/messaging/attachments - callback_id?: string; // TODO: not documented in https://api.slack.com/reference/messaging/attachments + actions?: AttachmentAction[]; // TODO: https://api.slack.com/legacy/message-buttons#crafting_your_message + callback_id?: string; // TODO: https://api.slack.com/legacy/message-buttons#crafting_your_message /** * @description Field names that should be {@link https://api.slack.com/reference/surfaces/formatting#basics formatted by `mrkdwn` syntax}. * The fields that can be formatted in this way include the names of the `fields` property, or @@ -138,9 +138,8 @@ export interface MessageAttachmentField { short?: boolean; } -// TODO: unclear what this is or how to use this // https://api.slack.com/methods/chat.unfurl#markdown -export interface MessageAttachmentPreview { +interface MessageAttachmentPreview { type?: string; can_remove?: boolean; title?: PlainTextElement; @@ -148,8 +147,7 @@ export interface MessageAttachmentPreview { iconUrl?: string; } -// TODO: unclear what this is or how to use this -export interface AttachmentAction { +interface AttachmentAction { id?: string; confirm?: Confirmation; data_source?: 'static' | 'channels' | 'conversations' | 'users' | 'external'; @@ -168,7 +166,7 @@ export interface AttachmentAction { url?: string; } -export interface OptionField { +interface OptionField { description?: string; text: string; value: string; @@ -182,6 +180,7 @@ export interface Confirmation { title?: string; } +// Used in web-api chat.* API method request parameters export interface LinkUnfurls { [linkUrl: string]: MessageAttachment; } diff --git a/packages/web-api/src/types/request/chat.ts b/packages/web-api/src/types/request/chat.ts index 3ffda58ce..cb2ded901 100644 --- a/packages/web-api/src/types/request/chat.ts +++ b/packages/web-api/src/types/request/chat.ts @@ -1,6 +1,6 @@ import type { KnownBlock, - Block, + Block, // TODO: these will be combined into one in a new types release MessageAttachment, LinkUnfurls, MessageMetadata, diff --git a/packages/webhook/src/IncomingWebhook.ts b/packages/webhook/src/IncomingWebhook.ts index 448e8e80e..c83bc38d5 100644 --- a/packages/webhook/src/IncomingWebhook.ts +++ b/packages/webhook/src/IncomingWebhook.ts @@ -1,6 +1,6 @@ import { Agent } from 'http'; import axios, { AxiosInstance, AxiosResponse } from 'axios'; -import { MessageAttachment, Block, KnownBlock } from '@slack/types'; +import { MessageAttachment, Block, KnownBlock } from '@slack/types'; // TODO: Block and KnownBlock will be merged into AnyBlock in upcoming types release import { httpErrorWithOriginal, requestErrorWithOriginal } from './errors'; import { getUserAgent } from './instrument';