From c8c34826873ae7c2774166f02efa9121d58d6e52 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Tue, 8 Apr 2025 16:53:33 -0400 Subject: [PATCH 01/35] Add support for flexpane API --- .../src/events/entity-details-requested.ts | 10 ++++++ packages/types/src/events/index.ts | 2 ++ packages/types/src/message-metadata.ts | 30 +++++++++++++++-- packages/web-api/src/methods.ts | 14 ++++++++ packages/web-api/src/types/request/chat.ts | 16 ++++++++-- packages/web-api/src/types/request/entity.ts | 32 +++++++++++++++++++ packages/web-api/src/types/request/index.ts | 1 + .../response/EntityPresentDetailsResponse.ts | 17 ++++++++++ packages/web-api/src/types/response/index.ts | 1 + 9 files changed, 119 insertions(+), 4 deletions(-) create mode 100644 packages/types/src/events/entity-details-requested.ts create mode 100644 packages/web-api/src/types/request/entity.ts create mode 100644 packages/web-api/src/types/response/EntityPresentDetailsResponse.ts diff --git a/packages/types/src/events/entity-details-requested.ts b/packages/types/src/events/entity-details-requested.ts new file mode 100644 index 000000000..35b00d053 --- /dev/null +++ b/packages/types/src/events/entity-details-requested.ts @@ -0,0 +1,10 @@ +export interface EntityDetailsRequestedEvent { + type: 'entity_details_requested'; + user: string; + external_ref: { + id: string; + type?: string; + }; + trigger_id: string; + event_ts: string; +} diff --git a/packages/types/src/events/index.ts b/packages/types/src/events/index.ts index 72e4ad1e8..eb2a4c0e8 100644 --- a/packages/types/src/events/index.ts +++ b/packages/types/src/events/index.ts @@ -25,6 +25,7 @@ import type { import type { DNDUpdatedEvent, DNDUpdatedUserEvent } from './dnd'; import type { EmailDomainChangedEvent } from './email'; import type { EmojiChangedEvent } from './emoji'; +import type { EntityDetailsRequestedEvent } from './entity-details-requested'; import type { FileChangeEvent, FileCommentDeletedEvent, @@ -144,6 +145,7 @@ export type SlackEvent = | DNDUpdatedUserEvent | EmailDomainChangedEvent | EmojiChangedEvent + | EntityDetailsRequestedEvent | FileChangeEvent | FileCommentDeletedEvent | FileCreatedEvent diff --git a/packages/types/src/message-metadata.ts b/packages/types/src/message-metadata.ts index 69721ec68..2a1db320f 100644 --- a/packages/types/src/message-metadata.ts +++ b/packages/types/src/message-metadata.ts @@ -1,9 +1,14 @@ /** - * @description Application-specific data to attach to Slack message. + * @description Application-specific data to attach to a Slack message. + */ +export interface MessageMetadata extends EventMetadata, EntitiesMetadata {} + +/** + * @description Metadata that represents an event in Slack. * @see {@link https://api.slack.com/metadata/using Using Metadata} * @see {@link https://api.slack.com/reference/metadata#payload_structure Metadata Payload Structure} */ -export interface MessageMetadata { +export interface EventMetadata { /** * @description A human readable alphanumeric string representing your application's metadata event. * The value of this field may appear in the UI to developers. @@ -20,3 +25,24 @@ export interface MessageMetadata { export interface MessageMetadataEventPayloadObject { [key: string]: string | number | boolean; } + +/** + * @description Metadata that represents an entity. + */ +export interface EntitiesMetadata { + entities: EntityMetadata[]; +} + +/** + * @description Metadata that represents an entity. + */ +export interface EntityMetadata { + /** + * @description Entity type. Accepted values: ["slack#/entities/task", "slack#/entities/file"] + */ + entity_type: string; + /** + * @description Schema for the given entity type. + */ + entity_payload: object; +} diff --git a/packages/web-api/src/methods.ts b/packages/web-api/src/methods.ts index 0a5caf0ee..3fef6f99e 100644 --- a/packages/web-api/src/methods.ts +++ b/packages/web-api/src/methods.ts @@ -176,6 +176,7 @@ import type { DndSetSnoozeArguments, DndTeamInfoArguments, EmojiListArguments, + EntityPresentDetailsArguments, FilesCommentsDeleteArguments, FilesCompleteUploadExternalArguments, FilesDeleteArguments, @@ -429,6 +430,7 @@ import type { DndSetSnoozeResponse, DndTeamInfoResponse, EmojiListResponse, + EntityPresentDetailsResponse, FilesCommentsDeleteResponse, FilesCompleteUploadExternalResponse, FilesDeleteResponse, @@ -1616,6 +1618,18 @@ export abstract class Methods extends EventEmitter { update: bindApiCall(this, 'chat.update'), }; + public readonly entity = { + /** + * @description + * Provide information about the entity to be displayed in the flexpane. + * A link to the API documentation will be added when this API is publicly released. + */ + presentDetails: bindApiCall( + this, + 'entity.presentDetails', + ), + }; + public readonly conversations = { /** * @description Accepts an invitation to a Slack Connect channel. diff --git a/packages/web-api/src/types/request/chat.ts b/packages/web-api/src/types/request/chat.ts index e234f2df6..9567a64cc 100644 --- a/packages/web-api/src/types/request/chat.ts +++ b/packages/web-api/src/types/request/chat.ts @@ -2,6 +2,7 @@ import type { OptionalArgument } from '../helpers'; import type { Block, // TODO: these will be combined into one in a new types release + EntitiesMetadata, KnownBlock, LinkUnfurls, MessageAttachment, @@ -220,13 +221,24 @@ export interface SourceAndUnfurlID { } type UnfurlTarget = ChannelAndTS | SourceAndUnfurlID; +type ChatUnfurlEntitiesMetadata = EntitiesMetadata & { + /** + * @description The unfurl URL for the entity. + */ + app_unfurl_url?: string; +}; + // https://api.slack.com/methods/chat.unfurl export type ChatUnfurlArguments = { /** - * @description URL-encoded JSON map with keys set to URLs featured in the the message, pointing to their unfurl + * @description Object with keys set to URLs featured in the message, pointing to their unfurl * blocks or message attachments. */ - unfurls: LinkUnfurls; + unfurls?: LinkUnfurls; + /** + * @description Array of entities to attach to the message based on URLs featured in the message. + */ + metadata?: ChatUnfurlEntitiesMetadata; } & UnfurlTarget & TokenOverridable & { /** diff --git a/packages/web-api/src/types/request/entity.ts b/packages/web-api/src/types/request/entity.ts new file mode 100644 index 000000000..1cca0d282 --- /dev/null +++ b/packages/web-api/src/types/request/entity.ts @@ -0,0 +1,32 @@ +import type { EntityMetadata } from '@slack/types'; +import type { TokenOverridable } from './common'; + +// https://api.slack.com/methods/entity.presentDetails +export type EntityPresentDetailsArguments = TokenOverridable & { + /** + * @description Eentity metadata that will be presented in the flexpane. + * */ + metadata?: EntityMetadata; + /** + * @description A reference to the original user action that initated the request. + * */ + trigger_id: string; + /** + * @description Set user_auth_required to true to indicate that the user must authenticate to view the full + * flexpane data. Defaults to false. + * */ + user_auth_required?: boolean; + /** + * @description A custom URL to which users are directed for authentication if required. + * Example: "https://example.com/onboarding?user_id=xxx" + * */ + user_auth_url?: string; + /** @description Error response preventing flexpane data from being returned. */ + error?: { + // Error status indicating why the entity could not be presented. + // Accepted values: ["restricted", "internal_error", "not_found", "user_not_authed", "custom"] + status: string; + // If status is 'custom', you can use this field to provide a specific message. + custom_message?: string; + }; +}; diff --git a/packages/web-api/src/types/request/index.ts b/packages/web-api/src/types/request/index.ts index e7639fb4b..980c09008 100644 --- a/packages/web-api/src/types/request/index.ts +++ b/packages/web-api/src/types/request/index.ts @@ -78,6 +78,7 @@ export type { FilesRemoteAddArguments, } from './files'; export type { EmojiListArguments } from './emoji'; +export type { EntityPresentDetailsArguments } from './entity'; export type { DndEndDndArguments, DndEndSnoozeArguments, diff --git a/packages/web-api/src/types/response/EntityPresentDetailsResponse.ts b/packages/web-api/src/types/response/EntityPresentDetailsResponse.ts new file mode 100644 index 000000000..3876b76cd --- /dev/null +++ b/packages/web-api/src/types/response/EntityPresentDetailsResponse.ts @@ -0,0 +1,17 @@ +///////////////////////////////////////////////////////////////////////////////////////// +// // +// !!! DO NOT EDIT THIS FILE !!! // +// // +// This file is auto-generated by scripts/generate-web-api-types.sh in the repository. // +// Please refer to the script code to learn how to update the source data. // +// // +///////////////////////////////////////////////////////////////////////////////////////// + +import type { WebAPICallResult } from '../../WebClient'; +export type EntityPresentDetailsResponse = WebAPICallResult & { + error?: string; + needed?: string; + ok?: boolean; + provided?: string; + warning?: string; +}; diff --git a/packages/web-api/src/types/response/index.ts b/packages/web-api/src/types/response/index.ts index 0a5f259ad..af381fe6f 100644 --- a/packages/web-api/src/types/response/index.ts +++ b/packages/web-api/src/types/response/index.ts @@ -199,6 +199,7 @@ export { DndInfoResponse } from './DndInfoResponse'; export { DndSetSnoozeResponse } from './DndSetSnoozeResponse'; export { DndTeamInfoResponse } from './DndTeamInfoResponse'; export { EmojiListResponse } from './EmojiListResponse'; +export { EntityPresentDetailsResponse } from './EntityPresentDetailsResponse'; export { FilesCommentsAddResponse } from './FilesCommentsAddResponse'; export { FilesCommentsDeleteResponse } from './FilesCommentsDeleteResponse'; export { FilesCommentsEditResponse } from './FilesCommentsEditResponse'; From a3f8922f29c7f61eee08ad115c34f3b446e47bf8 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 9 Apr 2025 17:14:39 -0400 Subject: [PATCH 02/35] feat-work-objects: version bump for types pkg (#2229) --- packages/types/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/types/package.json b/packages/types/package.json index bb6078067..83dda9e31 100644 --- a/packages/types/package.json +++ b/packages/types/package.json @@ -1,6 +1,6 @@ { "name": "@slack/types", - "version": "2.14.0", + "version": "2.15.0-featWorkObjectsBeta.1", "description": "Shared type definitions for the Node Slack SDK", "author": "Slack Technologies, LLC", "license": "MIT", From dde54aa4259c6c61f0eac976d332f689a66c4677 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 9 Apr 2025 18:59:09 -0400 Subject: [PATCH 03/35] Update --- packages/types/package.json | 2 +- packages/types/src/message-metadata.ts | 4 +-- packages/web-api/src/types/request/chat.ts | 32 +++++++++++-------- .../web-api/test/types/methods/chat.test-d.ts | 32 ++++++++++++++++++- 4 files changed, 53 insertions(+), 17 deletions(-) diff --git a/packages/types/package.json b/packages/types/package.json index 83dda9e31..bb6078067 100644 --- a/packages/types/package.json +++ b/packages/types/package.json @@ -1,6 +1,6 @@ { "name": "@slack/types", - "version": "2.15.0-featWorkObjectsBeta.1", + "version": "2.14.0", "description": "Shared type definitions for the Node Slack SDK", "author": "Slack Technologies, LLC", "license": "MIT", diff --git a/packages/types/src/message-metadata.ts b/packages/types/src/message-metadata.ts index 2a1db320f..630e802a8 100644 --- a/packages/types/src/message-metadata.ts +++ b/packages/types/src/message-metadata.ts @@ -1,7 +1,7 @@ /** * @description Application-specific data to attach to a Slack message. */ -export interface MessageMetadata extends EventMetadata, EntitiesMetadata {} +export type MessageMetadata = EventMetadata | EntitiesMetadata; /** * @description Metadata that represents an event in Slack. @@ -27,7 +27,7 @@ export interface MessageMetadataEventPayloadObject { } /** - * @description Metadata that represents an entity. + * @description An array of entities. */ export interface EntitiesMetadata { entities: EntityMetadata[]; diff --git a/packages/web-api/src/types/request/chat.ts b/packages/web-api/src/types/request/chat.ts index 9567a64cc..2c7480344 100644 --- a/packages/web-api/src/types/request/chat.ts +++ b/packages/web-api/src/types/request/chat.ts @@ -2,7 +2,7 @@ import type { OptionalArgument } from '../helpers'; import type { Block, // TODO: these will be combined into one in a new types release - EntitiesMetadata, + EntityMetadata, KnownBlock, LinkUnfurls, MessageAttachment, @@ -221,25 +221,31 @@ export interface SourceAndUnfurlID { } type UnfurlTarget = ChannelAndTS | SourceAndUnfurlID; -type ChatUnfurlEntitiesMetadata = EntitiesMetadata & { - /** - * @description The unfurl URL for the entity. - */ - app_unfurl_url?: string; -}; - -// https://api.slack.com/methods/chat.unfurl -export type ChatUnfurlArguments = { +type ChatUnfurlArgumentUnfurls = { /** * @description Object with keys set to URLs featured in the message, pointing to their unfurl * blocks or message attachments. */ - unfurls?: LinkUnfurls; + unfurls: LinkUnfurls; +}; + +type ChatUnfurlArgumentMetadata = { /** * @description Array of entities to attach to the message based on URLs featured in the message. */ - metadata?: ChatUnfurlEntitiesMetadata; -} & UnfurlTarget & + metadata: { + entities: (EntityMetadata & { + /** + * @description The unfurl URL for the entity. + */ + app_unfurl_url: string; + })[]; + }; +}; + +// https://api.slack.com/methods/chat.unfurl +export type ChatUnfurlArguments = (ChatUnfurlArgumentUnfurls | ChatUnfurlArgumentMetadata) & + UnfurlTarget & TokenOverridable & { /** * @description Provide a simply-formatted string to send as an ephemeral message to the user as invitation to diff --git a/packages/web-api/test/types/methods/chat.test-d.ts b/packages/web-api/test/types/methods/chat.test-d.ts index cf5349a30..74b592307 100644 --- a/packages/web-api/test/types/methods/chat.test-d.ts +++ b/packages/web-api/test/types/methods/chat.test-d.ts @@ -399,6 +399,21 @@ expectAssignable>([ reply_broadcast: false, // can send a threaded message and explicitly not broadcast it }, ]); +expectAssignable>([ + { + channel: 'C1234', + text: 'hello', + thread_ts: '1234.56', + metadata: { + entities: [ + { + entity_type: 'slack#/entities/file', + entity_payload: {}, + }, + ], + }, + }, +]); // adding a test for when `reply_broadcast` specific boolean value is not known ahead of time // https://github.com/slackapi/node-slack-sdk/issues/1859 function wideBooleanTest(b: boolean) { @@ -546,7 +561,7 @@ expectError( ); expectError( web.chat.unfurl({ - channel: 'C1234', // missing unfurls + channel: 'C1234', // missing both unfurls and metadata ts: '1234.56', }), ); @@ -600,6 +615,21 @@ expectAssignable>([ ts: '1234.56', }, ]); +expectAssignable>([ + { + channel: 'C1234', + ts: '1234.56', + metadata: { + entities: [ + { + entity_type: 'slack#/entities/file', + entity_payload: {}, + app_unfurl_url: 'https://google.com', + }, + ], + }, + }, +]); // chat.update // -- sad path From 5813ae66d3209037506027165d5e01db9dcb4ea4 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 9 Apr 2025 22:41:43 -0400 Subject: [PATCH 04/35] feat-work-objects: version bump 2 for the types pkg (#2234) --- packages/types/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/types/package.json b/packages/types/package.json index bb6078067..183917e01 100644 --- a/packages/types/package.json +++ b/packages/types/package.json @@ -1,6 +1,6 @@ { "name": "@slack/types", - "version": "2.14.0", + "version": "2.15.0-featWorkObjectsBeta.2", "description": "Shared type definitions for the Node Slack SDK", "author": "Slack Technologies, LLC", "license": "MIT", From 6892aef3fae86f77ef8da3dc5eed41075fa76b82 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 9 Apr 2025 22:54:10 -0400 Subject: [PATCH 05/35] feat-work-objects: version bump for the web-api pkg (#2232) --- packages/web-api/package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/web-api/package.json b/packages/web-api/package.json index 8b4620228..17e62f5ad 100644 --- a/packages/web-api/package.json +++ b/packages/web-api/package.json @@ -1,6 +1,6 @@ { "name": "@slack/web-api", - "version": "7.9.1", + "version": "7.10.1-featWorkObjectsBeta.1", "description": "Official library for using the Slack Platform's Web API", "author": "Slack Technologies, LLC", "license": "MIT", @@ -36,7 +36,7 @@ }, "dependencies": { "@slack/logger": "^4.0.0", - "@slack/types": "^2.9.0", + "@slack/types": "2.15.0-featWorkObjectsBeta.2", "@types/node": ">=18.0.0", "@types/retry": "0.12.0", "axios": "^1.8.3", From c3cef1fa0266fbadbf294e3edafbb60d14d578b0 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Mon, 8 Sep 2025 10:54:32 -0400 Subject: [PATCH 06/35] update --- packages/types/package.json | 2 +- packages/types/src/message-metadata.ts | 34 +++++++++------ packages/web-api/package.json | 4 +- packages/web-api/src/types/request/chat.ts | 50 +++++++++++----------- 4 files changed, 50 insertions(+), 40 deletions(-) diff --git a/packages/types/package.json b/packages/types/package.json index 4449c5384..41fe94f39 100644 --- a/packages/types/package.json +++ b/packages/types/package.json @@ -1,6 +1,6 @@ { "name": "@slack/types", - "version": "2.17.0-tmp", + "version": "2.16.0", "description": "Shared type definitions for the Node Slack SDK", "author": "Slack Technologies, LLC", "license": "MIT", diff --git a/packages/types/src/message-metadata.ts b/packages/types/src/message-metadata.ts index 738e81a61..1fc9a926b 100644 --- a/packages/types/src/message-metadata.ts +++ b/packages/types/src/message-metadata.ts @@ -1,43 +1,53 @@ /** - * @description Application-specific data to attach to Slack message. + * @description Application-specific event or entity data to attach to Slack message. + * Provide 'event_type' and 'event_payload' to set event metadata, or use 'entities' to set work object entity metadata. * @see {@link https://docs.slack.dev/messaging/message-metadata Using Metadata} * @see {@link https://docs.slack.dev/messaging/message-metadata Metadata Payload Structure} */ -export interface EventMetadata { +export interface MessageMetadata { /** * @description A human readable alphanumeric string representing your application's metadata event. * The value of this field may appear in the UI to developers. */ - event_type: string; + event_type?: string; /** * @description A free-form object containing whatever data your application wishes to attach to messages. */ - event_payload: { + event_payload?: { [key: string]: string | number | boolean | MessageMetadataEventPayloadObject | MessageMetadataEventPayloadObject[]; }; + + /** + * @description An array of work object entities. + */ + entities?: EntityMetadata[]; } export interface MessageMetadataEventPayloadObject { [key: string]: string | number | boolean; } -/** - * @description An array of entities. - */ -export interface EntitiesMetadata { - entities: EntityMetadata[]; -} - /** * @description Metadata that represents an entity. */ export interface EntityMetadata { /** - * @description Entity type. Accepted values: ["slack#/entities/task", "slack#/entities/file"] + * @description Entity type. */ entity_type: string; /** * @description Schema for the given entity type. */ entity_payload: object; + /** + * @description Reference (and optional type) used to identify an entity within the developer's system. + */ + external_ref: { + id: string; + type?: string; + }; + /** + * @description URL used to identify an entity within the developer's system. + */ + url: string; } diff --git a/packages/web-api/package.json b/packages/web-api/package.json index b98d267b2..19ebec9e7 100644 --- a/packages/web-api/package.json +++ b/packages/web-api/package.json @@ -1,6 +1,6 @@ { "name": "@slack/web-api", - "version": "7.11.0-tmp", + "version": "7.10.0", "description": "Official library for using the Slack Platform's Web API", "author": "Slack Technologies, LLC", "license": "MIT", @@ -49,7 +49,7 @@ }, "dependencies": { "@slack/logger": "^4.0.0", - "@slack/types": "2.15.0-featWorkObjectsBeta.2", + "@slack/types": "^2.9.0", "@types/node": ">=18.0.0", "@types/retry": "0.12.0", "axios": "^1.11.0", diff --git a/packages/web-api/src/types/request/chat.ts b/packages/web-api/src/types/request/chat.ts index d0e4c0e15..c61691f90 100644 --- a/packages/web-api/src/types/request/chat.ts +++ b/packages/web-api/src/types/request/chat.ts @@ -230,32 +230,8 @@ export interface SourceAndUnfurlID { } type UnfurlTarget = ChannelAndTS | SourceAndUnfurlID; -// `unfurls` param of the `chat.unfurl` API -type ChatUnfurlArgumentUnfurls = { - /** - * @description Object with keys set to URLs featured in the message, pointing to their unfurl - * blocks or message attachments. - */ - unfurls: LinkUnfurls; -}; - -// `metadata` param of the `chat.unfurl` API -type ChatUnfurlArgumentMetadata = { - /** - * @description Array of entities to attach to the message based on URLs featured in the message. - */ - metadata: { - entities: (EntityMetadata & { - /** - * @description The unfurl URL for the entity. - */ - app_unfurl_url: string; - })[]; - }; -}; - // https://api.slack.com/methods/chat.unfurl -export type ChatUnfurlArguments = (ChatUnfurlArgumentUnfurls | ChatUnfurlArgumentMetadata) & +export type ChatUnfurlArguments = (BlockKitUnfurls | EntityMetadataUnfurls) & UnfurlTarget & TokenOverridable & { /** @@ -280,6 +256,30 @@ export type ChatUnfurlArguments = (ChatUnfurlArgumentUnfurls | ChatUnfurlArgumen user_auth_blocks?: (KnownBlock | Block)[]; }; +// `unfurls` param of the `chat.unfurl` API +type BlockKitUnfurls = { + /** + * @description Object with keys set to URLs featured in the message, pointing to their unfurl + * blocks or message attachments. + */ + unfurls: LinkUnfurls; +}; + +// `metadata` param of the `chat.unfurl` API +type EntityMetadataUnfurls = { + /** + * @description Array of entities to attach to the message based on URLs featured in the message. + */ + metadata: { + entities: (EntityMetadata & { + /** + * @description The unfurl URL for the entity. + */ + app_unfurl_url: string; + })[]; + }; +}; + // https://docs.slack.dev/reference/methods/chat.update export type ChatUpdateArguments = MessageContents & { /** @description Timestamp of the message to be updated. */ From da092d58dc58129a1eecfd619a6699a539f716f7 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 10 Sep 2025 10:02:09 -0400 Subject: [PATCH 07/35] update payload object, entity.presentDetails inputs, test, event --- .../src/events/entity-details-requested.ts | 13 ++++++++++--- packages/types/src/message-metadata.ts | 18 +++++++++++++++++- packages/web-api/src/types/request/entity.ts | 11 ++++++++--- .../web-api/test/types/methods/chat.test-d.ts | 12 ++++++++++-- 4 files changed, 45 insertions(+), 9 deletions(-) diff --git a/packages/types/src/events/entity-details-requested.ts b/packages/types/src/events/entity-details-requested.ts index 35b00d053..c122b1da9 100644 --- a/packages/types/src/events/entity-details-requested.ts +++ b/packages/types/src/events/entity-details-requested.ts @@ -1,10 +1,17 @@ export interface EntityDetailsRequestedEvent { type: 'entity_details_requested'; user: string; - external_ref: { + trigger_id: string; + link: { + url: string; + domain: string; + }; + user_locale: string; + event_ts: string; + external_ref?: { id: string; type?: string; }; - trigger_id: string; - event_ts: string; + message_ts?: string; + channel?: string; } diff --git a/packages/types/src/message-metadata.ts b/packages/types/src/message-metadata.ts index 1fc9a926b..4fcd179a5 100644 --- a/packages/types/src/message-metadata.ts +++ b/packages/types/src/message-metadata.ts @@ -27,6 +27,10 @@ export interface MessageMetadataEventPayloadObject { [key: string]: string | number | boolean; } +export interface MessageMetadataEventPayloadAttributes { + [key: string]: string | number | boolean | MessageMetadataEventPayloadAttributes; +} + /** * @description Metadata that represents an entity. */ @@ -38,7 +42,19 @@ export interface EntityMetadata { /** * @description Schema for the given entity type. */ - entity_payload: object; + entity_payload: { + // biome-ignore lint/complexity/noBannedTypes: Allow Object + attributes: Object; + // biome-ignore lint/complexity/noBannedTypes: Allow Object + fields?: Object; + // biome-ignore lint/complexity/noBannedTypes: Allow Object + custom_fields?: Object[]; + // biome-ignore lint/complexity/noBannedTypes: Allow Object + slack_file?: Object; + display_order?: string[]; + // biome-ignore lint/complexity/noBannedTypes: Allow Object + actions?: Object; + }; /** * @description Reference (and optional type) used to identify an entity within the developer's system. */ diff --git a/packages/web-api/src/types/request/entity.ts b/packages/web-api/src/types/request/entity.ts index 1cca0d282..bb69e28c4 100644 --- a/packages/web-api/src/types/request/entity.ts +++ b/packages/web-api/src/types/request/entity.ts @@ -4,7 +4,7 @@ import type { TokenOverridable } from './common'; // https://api.slack.com/methods/entity.presentDetails export type EntityPresentDetailsArguments = TokenOverridable & { /** - * @description Eentity metadata that will be presented in the flexpane. + * @description Entity metadata to be presented in the flexpane. * */ metadata?: EntityMetadata; /** @@ -24,9 +24,14 @@ export type EntityPresentDetailsArguments = TokenOverridable & { /** @description Error response preventing flexpane data from being returned. */ error?: { // Error status indicating why the entity could not be presented. - // Accepted values: ["restricted", "internal_error", "not_found", "user_not_authed", "custom"] status: string; - // If status is 'custom', you can use this field to provide a specific message. + // If status is 'custom', you can use this field to provide a message to the client. custom_message?: string; + // String format, eg. 'markdown'. + message_format?: string; + // If status is 'custom', you can use this field to provide a title to the client. + custom_title?: string; + // Set of action buttons to be shown in case of a specific error. + actions?: Object[]; }; }; diff --git a/packages/web-api/test/types/methods/chat.test-d.ts b/packages/web-api/test/types/methods/chat.test-d.ts index 9b4e77845..efe97c982 100644 --- a/packages/web-api/test/types/methods/chat.test-d.ts +++ b/packages/web-api/test/types/methods/chat.test-d.ts @@ -421,7 +421,11 @@ expectAssignable>([ entities: [ { entity_type: 'slack#/entities/file', - entity_payload: {}, + entity_payload: { + attributes: {} + }, + external_ref: {id: ""}, + url: "" }, ], }, @@ -643,7 +647,11 @@ expectAssignable>([ entities: [ { entity_type: 'slack#/entities/file', - entity_payload: {}, + entity_payload: { + attributes: {} + }, + external_ref: {id: ""}, + url: "", app_unfurl_url: 'https://google.com', }, ], From d889e0777d44bd43a2994208a90dbfee98d8ccd7 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 11 Sep 2025 21:22:32 -0400 Subject: [PATCH 08/35] feat-work-objects: beta version for the types pkg (#2366) --- packages/types/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/types/package.json b/packages/types/package.json index 41fe94f39..4c0334fd4 100644 --- a/packages/types/package.json +++ b/packages/types/package.json @@ -1,6 +1,6 @@ { "name": "@slack/types", - "version": "2.16.0", + "version": "2.16.0-featWorkObjectsBeta.1", "description": "Shared type definitions for the Node Slack SDK", "author": "Slack Technologies, LLC", "license": "MIT", From e6bd2ac812d2197d0fbfbd81e69fe323f4b58421 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 11 Sep 2025 22:02:30 -0400 Subject: [PATCH 09/35] lint --- packages/web-api/src/types/request/entity.ts | 1 + .../web-api/test/types/methods/chat.test-d.ts | 28 +++++++++++++------ 2 files changed, 21 insertions(+), 8 deletions(-) diff --git a/packages/web-api/src/types/request/entity.ts b/packages/web-api/src/types/request/entity.ts index bb69e28c4..577857846 100644 --- a/packages/web-api/src/types/request/entity.ts +++ b/packages/web-api/src/types/request/entity.ts @@ -32,6 +32,7 @@ export type EntityPresentDetailsArguments = TokenOverridable & { // If status is 'custom', you can use this field to provide a title to the client. custom_title?: string; // Set of action buttons to be shown in case of a specific error. + // biome-ignore lint/complexity/noBannedTypes: Allow Object actions?: Object[]; }; }; diff --git a/packages/web-api/test/types/methods/chat.test-d.ts b/packages/web-api/test/types/methods/chat.test-d.ts index efe97c982..bad1761cf 100644 --- a/packages/web-api/test/types/methods/chat.test-d.ts +++ b/packages/web-api/test/types/methods/chat.test-d.ts @@ -422,10 +422,10 @@ expectAssignable>([ { entity_type: 'slack#/entities/file', entity_payload: { - attributes: {} + attributes: {}, }, - external_ref: {id: ""}, - url: "" + external_ref: { id: '' }, + url: '', }, ], }, @@ -646,13 +646,25 @@ expectAssignable>([ metadata: { entities: [ { - entity_type: 'slack#/entities/file', + entity_type: 'slack#/entities/task', entity_payload: { - attributes: {} + attributes: { + title: { + text: 'Important task', + }, + }, + fields: { + status: { + value: 'All clear', + }, + description: { + value: 'Details of the task.', + }, + }, }, - external_ref: {id: ""}, - url: "", - app_unfurl_url: 'https://google.com', + external_ref: { id: '1234' }, + url: 'https://myappdomain.com/id/1234', + app_unfurl_url: 'https://myappdomain.com/id/1234?myquery=param', }, ], }, From c54c9b333781657f12b410abaabe315788d35d0b Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 11 Sep 2025 22:23:35 -0400 Subject: [PATCH 10/35] feat-work-objects: beta version for the web-api pkg (#2367) --- packages/web-api/package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/web-api/package.json b/packages/web-api/package.json index 19ebec9e7..9b87ae8c2 100644 --- a/packages/web-api/package.json +++ b/packages/web-api/package.json @@ -1,6 +1,6 @@ { "name": "@slack/web-api", - "version": "7.10.0", + "version": "7.10.0-featWorkObjectsBeta.2", "description": "Official library for using the Slack Platform's Web API", "author": "Slack Technologies, LLC", "license": "MIT", @@ -49,7 +49,7 @@ }, "dependencies": { "@slack/logger": "^4.0.0", - "@slack/types": "^2.9.0", + "@slack/types": "2.16.0-featWorkObjectsBeta.1", "@types/node": ">=18.0.0", "@types/retry": "0.12.0", "axios": "^1.11.0", From 24ecda63727aa2fda505544e09347299ba920fbe Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 8 Oct 2025 22:59:20 -0400 Subject: [PATCH 11/35] Update entity metadata definitions --- .../src/events/entity-details-requested.ts | 3 + packages/types/src/events/message-metadata.ts | 10 +- packages/types/src/message-metadata.ts | 232 +++++++++++++++++- packages/web-api/src/types/request/chat.ts | 7 +- .../web-api/src/types/request/manifest.ts | 3 +- .../web-api/test/types/methods/chat.test-d.ts | 47 ++-- 6 files changed, 255 insertions(+), 47 deletions(-) diff --git a/packages/types/src/events/entity-details-requested.ts b/packages/types/src/events/entity-details-requested.ts index c122b1da9..f9d69c462 100644 --- a/packages/types/src/events/entity-details-requested.ts +++ b/packages/types/src/events/entity-details-requested.ts @@ -6,6 +6,8 @@ export interface EntityDetailsRequestedEvent { url: string; domain: string; }; + entity_url: string; + app_unfurl_url?: string; user_locale: string; event_ts: string; external_ref?: { @@ -13,5 +15,6 @@ export interface EntityDetailsRequestedEvent { type?: string; }; message_ts?: string; + thread_ts?: string; channel?: string; } diff --git a/packages/types/src/events/message-metadata.ts b/packages/types/src/events/message-metadata.ts index e932ccaae..ab808d31a 100644 --- a/packages/types/src/events/message-metadata.ts +++ b/packages/types/src/events/message-metadata.ts @@ -1,4 +1,4 @@ -import type { MessageMetadata } from '../message-metadata'; +import type { EventMessageMetadata } from '../message-metadata'; export type AllMessageMetadataEvents = | MessageMetadataDeletedEvent @@ -12,7 +12,7 @@ export interface MessageMetadataPostedEvent { user_id: string; team_id: string; channel_id: string; - metadata: MessageMetadata; + metadata: EventMessageMetadata; message_ts: string; event_ts: string; } @@ -21,20 +21,20 @@ export interface MessageMetadataUpdatedEvent { type: 'message_metadata_updated'; channel_id: string; event_ts: string; - previous_metadata: MessageMetadata; + previous_metadata: EventMessageMetadata; app_id: string; bot_id?: string; user_id: string; team_id: string; message_ts: string; - metadata: MessageMetadata; + metadata: EventMessageMetadata; } export interface MessageMetadataDeletedEvent { type: 'message_metadata_deleted'; channel_id: string; event_ts: string; - previous_metadata: MessageMetadata; + previous_metadata: EventMessageMetadata; app_id: string; bot_id?: string; user_id: string; diff --git a/packages/types/src/message-metadata.ts b/packages/types/src/message-metadata.ts index 4fcd179a5..de41460f3 100644 --- a/packages/types/src/message-metadata.ts +++ b/packages/types/src/message-metadata.ts @@ -1,3 +1,5 @@ +import type { Option, PlainTextElement, SlackFile } from './block-kit/composition-objects'; + /** * @description Application-specific event or entity data to attach to Slack message. * Provide 'event_type' and 'event_payload' to set event metadata, or use 'entities' to set work object entity metadata. @@ -23,6 +25,12 @@ export interface MessageMetadata { entities?: EntityMetadata[]; } +// ------------------------------ +// Event metadata +// ------------------------------ + +export interface EventMessageMetadata extends Omit {} + export interface MessageMetadataEventPayloadObject { [key: string]: string | number | boolean; } @@ -31,8 +39,12 @@ export interface MessageMetadataEventPayloadAttributes { [key: string]: string | number | boolean | MessageMetadataEventPayloadAttributes; } +// ------------------------------ +// Work object metadata +// ------------------------------ + /** - * @description Metadata that represents an entity. + * @description Metadata that represents a work object entity. */ export interface EntityMetadata { /** @@ -43,17 +55,15 @@ export interface EntityMetadata { * @description Schema for the given entity type. */ entity_payload: { - // biome-ignore lint/complexity/noBannedTypes: Allow Object - attributes: Object; - // biome-ignore lint/complexity/noBannedTypes: Allow Object - fields?: Object; - // biome-ignore lint/complexity/noBannedTypes: Allow Object - custom_fields?: Object[]; - // biome-ignore lint/complexity/noBannedTypes: Allow Object - slack_file?: Object; + attributes: EntityAttributes; + fields?: FileEntityFields | TaskEntityFields | IncidentEntityFields | ContentItemEntityFields; + custom_fields?: EntityCustomField[]; + slack_file?: FileEntitySlackFile; display_order?: string[]; - // biome-ignore lint/complexity/noBannedTypes: Allow Object - actions?: Object; + actions?: { + primary_actions?: EntityActionButton[]; + overflow_actions?: EntityActionButton[]; + }; }; /** * @description Reference (and optional type) used to identify an entity within the developer's system. @@ -66,4 +76,204 @@ export interface EntityMetadata { * @description URL used to identify an entity within the developer's system. */ url: string; + + /** + * @description The exact URL posted in the source message. Required in metadata passed to `chat.unfurl`. + */ + app_unfurl_url?: string; +} + +export interface FileEntitySlackFile { + id: string; + type?: string; +} + +export interface EntityAttributes { + title: { + text: string; + edit?: EntityEditSupport; + }; + display_type?: string; + display_id?: string; + product_icon?: EntityIconField; + product_name?: string; + locale?: string; + full_size_preview?: EntityFullSizePreview; + metadata_last_modified?: number; +} + +export interface EntityIconField { + alt_text: string; + url?: string; + slack_file?: { + id?: string; + url?: string; + }; +} + +export interface EntityEditSupport { + enabled: boolean; + placeholder?: PlainTextElement; + hint?: PlainTextElement; + optional?: boolean; + select?: { + current_value?: string; + current_values?: string[]; + static_options?: Option[]; + fetch_options_dynamically?: boolean; + min_query_length?: number; + }; + number?: { + is_decimal_allowed?: boolean; + min_value?: number; + max_value?: number; + }; + text?: { + min_length?: number; + max_length?: number; + }; +} + +export interface EntityFullSizePreview { + is_supported: boolean; + preview_url?: string; + is_animated?: boolean; + width?: string; + height?: string; + mime_type?: string; + error?: { + code: string; + message?: string; + }; +} + +export interface FileEntityFields { + preview?: EntityImageField; + created_by?: EntityTypedField; + date_created?: EntityTimestampField; + date_updated?: EntityTimestampField; + last_modified_by?: EntityTypedField; + file_size?: EntityStringField; + mime_type?: EntityStringField; + full_size_preview?: EntityFullSizePreview; +} + +export interface TaskEntityFields { + description?: EntityStringField; + created_by?: EntityTypedField; + date_created?: EntityTimestampField; + date_updated?: EntityTimestampField; + assignee?: EntityTypedField; + status?: EntityStringField; + due_date?: EntityTypedField; + priority?: EntityStringField; +} + +export interface IncidentEntityFields { + status?: EntityStringField; + priority?: EntityStringField; + urgency?: EntityStringField; + created_by?: EntityTypedField; + assigned_to?: EntityTypedField; + date_created?: EntityTimestampField; + date_updated?: EntityTimestampField; + description?: EntityStringField; + service?: EntityStringField; +} + +export interface ContentItemEntityFields { + preview?: EntityImageField; + description?: EntityStringField; + created_by?: EntityTypedField; + date_created?: EntityTimestampField; + date_updated?: EntityTimestampField; + last_modified_by?: EntityTypedField; +} + +export interface EntityTypedField { + type: string; + label?: string; + value?: string | number; + link?: string; + icon?: EntityIconField; + long?: boolean; + format?: string; + image_url?: string; + slack_file?: SlackFile; + alt_text?: string; + edit?: EntityEditSupport; + tag_color?: string; + user?: EntityUserIDField | EntityUserField; +} + +export interface EntityStringField { + value: string; + label?: string; + format?: string; + link?: string; + icon?: EntityIconField; + long?: boolean; + type?: string; + tag_color?: string; + edit?: EntityEditSupport; +} + +export interface EntityUserIDField { + user_id: string; +} + +export interface EntityUserField { + text: string; + url?: string; + email?: string; + icon?: EntityIconField; +} + +export interface EntityTimestampField { + value: number; + label?: string; + link?: string; + icon?: EntityIconField; + type?: string; + edit?: EntityEditSupport; +} + +export interface EntityImageField { + alt_text: string; + label?: string; + image_url?: string; + slack_file?: SlackFile; + title?: string; + type?: string; +} + +export interface EntityCustomField { + label: string; + key: string; + type: string; + value?: string | number | EntityTypedField[]; + link?: string; + icon?: EntityIconField; + long?: boolean; + format?: string; + image_url?: string; + slack_file?: SlackFile; + alt_text?: string; + tag_color?: string; + edit?: EntityEditSupport; + item_type?: string; + user?: EntityUserIDField | EntityUserField; +} + +export interface EntityActionButton { + text: string; + action_id: string; + value?: string; + style?: string; + url?: string; + accessibility_label?: string; + processing_state?: { + enabled: boolean; + interstitial_text?: string; + }; } diff --git a/packages/web-api/src/types/request/chat.ts b/packages/web-api/src/types/request/chat.ts index c61691f90..c6fbca731 100644 --- a/packages/web-api/src/types/request/chat.ts +++ b/packages/web-api/src/types/request/chat.ts @@ -271,12 +271,7 @@ type EntityMetadataUnfurls = { * @description Array of entities to attach to the message based on URLs featured in the message. */ metadata: { - entities: (EntityMetadata & { - /** - * @description The unfurl URL for the entity. - */ - app_unfurl_url: string; - })[]; + entities: EntityMetadata[]; }; }; diff --git a/packages/web-api/src/types/request/manifest.ts b/packages/web-api/src/types/request/manifest.ts index e47308af3..a16071e4a 100644 --- a/packages/web-api/src/types/request/manifest.ts +++ b/packages/web-api/src/types/request/manifest.ts @@ -540,4 +540,5 @@ type ManifestEvent = | 'workflow_published' | 'workflow_step_deleted' | 'workflow_step_execute' - | 'workflow_unpublished'; + | 'workflow_unpublished' + | 'entity_details_requested'; diff --git a/packages/web-api/test/types/methods/chat.test-d.ts b/packages/web-api/test/types/methods/chat.test-d.ts index bad1761cf..61e397b7d 100644 --- a/packages/web-api/test/types/methods/chat.test-d.ts +++ b/packages/web-api/test/types/methods/chat.test-d.ts @@ -1,5 +1,5 @@ +import type { EntityMetadata } from '@slack/types'; import { expectAssignable, expectError } from 'tsd'; - import { WebClient } from '../../../src/WebClient'; const web = new WebClient('TOKEN'); @@ -639,34 +639,33 @@ expectAssignable>([ ts: '1234.56', }, ]); +const entityMetadata: EntityMetadata = { + entity_type: 'slack#/entities/task', + entity_payload: { + attributes: { + title: { + text: 'Important task', + }, + }, + fields: { + status: { + value: 'All clear', + }, + description: { + value: 'Details of the task.', + }, + }, + }, + external_ref: { id: '1234' }, + url: 'https://myappdomain.com/id/1234', + app_unfurl_url: 'https://myappdomain.com/id/1234?myquery=param', +}; expectAssignable>([ { channel: 'C1234', ts: '1234.56', metadata: { - entities: [ - { - entity_type: 'slack#/entities/task', - entity_payload: { - attributes: { - title: { - text: 'Important task', - }, - }, - fields: { - status: { - value: 'All clear', - }, - description: { - value: 'Details of the task.', - }, - }, - }, - external_ref: { id: '1234' }, - url: 'https://myappdomain.com/id/1234', - app_unfurl_url: 'https://myappdomain.com/id/1234?myquery=param', - }, - ], + entities: [entityMetadata], }, }, ]); From 02e5360ecf2bd6b4427b1cd7d681ac9c310044c9 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 9 Oct 2025 09:49:14 -0400 Subject: [PATCH 12/35] feat-work-objects: beta version for the types pkg (#2404) --- packages/types/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/types/package.json b/packages/types/package.json index 495b89f70..59139f7a5 100644 --- a/packages/types/package.json +++ b/packages/types/package.json @@ -1,6 +1,6 @@ { "name": "@slack/types", - "version": "2.17.0", + "version": "2.17.0-featWorkObjectsBeta.1", "description": "Shared type definitions for the Node Slack SDK", "author": "Slack Technologies, LLC", "license": "MIT", From b983ca5b04f31f81e4db1ae7cca969374ffe9c75 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 9 Oct 2025 10:01:25 -0400 Subject: [PATCH 13/35] update test --- packages/web-api/test/types/methods/chat.test-d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/web-api/test/types/methods/chat.test-d.ts b/packages/web-api/test/types/methods/chat.test-d.ts index 8e03512a8..639c53255 100644 --- a/packages/web-api/test/types/methods/chat.test-d.ts +++ b/packages/web-api/test/types/methods/chat.test-d.ts @@ -451,7 +451,7 @@ expectAssignable>([ { entity_type: 'slack#/entities/file', entity_payload: { - attributes: {}, + attributes: { title: { text: 'My File' } }, }, external_ref: { id: '' }, url: '', From 8201026582f298178f70d5d2b02235d88e721281 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 9 Oct 2025 10:20:31 -0400 Subject: [PATCH 14/35] feat-work-objects: beta version for the web-api pkg (#2405) --- packages/web-api/package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/web-api/package.json b/packages/web-api/package.json index 19e709698..47c237915 100644 --- a/packages/web-api/package.json +++ b/packages/web-api/package.json @@ -1,6 +1,6 @@ { "name": "@slack/web-api", - "version": "7.11.0", + "version": "7.11.0-featWorkObjectsBeta.1", "description": "Official library for using the Slack Platform's Web API", "author": "Slack Technologies, LLC", "license": "MIT", @@ -49,7 +49,7 @@ }, "dependencies": { "@slack/logger": "^4.0.0", - "@slack/types": "^2.17.0", + "@slack/types": "2.17.0-featWorkObjectsBeta.1", "@types/node": ">=18.0.0", "@types/retry": "0.12.0", "axios": "^1.11.0", From e4284e3a022f4965889bd55a6b0a61ac22434294 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 15 Oct 2025 16:03:49 -0400 Subject: [PATCH 15/35] update schema --- packages/types/src/message-metadata.ts | 53 +++++++++++++++---- packages/web-api/src/types/request/entity.ts | 5 +- .../web-api/test/types/methods/chat.test-d.ts | 13 ++++- 3 files changed, 56 insertions(+), 15 deletions(-) diff --git a/packages/types/src/message-metadata.ts b/packages/types/src/message-metadata.ts index de41460f3..a0250ee29 100644 --- a/packages/types/src/message-metadata.ts +++ b/packages/types/src/message-metadata.ts @@ -50,7 +50,7 @@ export interface EntityMetadata { /** * @description Entity type. */ - entity_type: string; + entity_type: EntityType | string; /** * @description Schema for the given entity type. */ @@ -68,10 +68,7 @@ export interface EntityMetadata { /** * @description Reference (and optional type) used to identify an entity within the developer's system. */ - external_ref: { - id: string; - type?: string; - }; + external_ref: ExternalRef; /** * @description URL used to identify an entity within the developer's system. */ @@ -83,6 +80,19 @@ export interface EntityMetadata { app_unfurl_url?: string; } +export interface ExternalRef { + id: string; + type?: string; +} + +export enum EntityType { + Task = 'slack#/entities/task', + File = 'slack#/entities/file', + Item = 'slack#/entities/item', + Incident = 'slack#/entities/incident', + ContentItem = 'slack#/entities/content_item', +} + export interface FileEntitySlackFile { id: string; type?: string; @@ -137,9 +147,6 @@ export interface EntityEditSupport { export interface EntityFullSizePreview { is_supported: boolean; preview_url?: string; - is_animated?: boolean; - width?: string; - height?: string; mime_type?: string; error?: { code: string; @@ -190,6 +197,10 @@ export interface ContentItemEntityFields { last_modified_by?: EntityTypedField; } +export interface EntityArrayItemField extends Omit { + type?: string; +} + export interface EntityTypedField { type: string; label?: string; @@ -204,6 +215,7 @@ export interface EntityTypedField { edit?: EntityEditSupport; tag_color?: string; user?: EntityUserIDField | EntityUserField; + entity_ref?: EntityRefField; } export interface EntityStringField { @@ -229,6 +241,14 @@ export interface EntityUserField { icon?: EntityIconField; } +export interface EntityRefField { + entity_url: string; + external_ref: ExternalRef; + title: string; + display_type?: string; + icon?: EntityIconField; +} + export interface EntityTimestampField { value: number; label?: string; @@ -250,8 +270,8 @@ export interface EntityImageField { export interface EntityCustomField { label: string; key: string; - type: string; - value?: string | number | EntityTypedField[]; + type: CustomFieldType | string; + value?: string | number | EntityArrayItemField[]; link?: string; icon?: EntityIconField; long?: boolean; @@ -263,6 +283,19 @@ export interface EntityCustomField { edit?: EntityEditSupport; item_type?: string; user?: EntityUserIDField | EntityUserField; + entity_ref?: EntityRefField; +} + +export enum CustomFieldType { + Integer = 'integer', + String = 'string', + Array = 'array', + Date = 'slack#/types/date', + Timestamp = 'slack#/types/timestamp', + Image = 'slack#/types/image', + ChannelId = 'slack#/types/channel_id', + User = 'slack#/types/user', + EntityRef = 'slack#/types/entity_ref', } export interface EntityActionButton { diff --git a/packages/web-api/src/types/request/entity.ts b/packages/web-api/src/types/request/entity.ts index 577857846..1b3798502 100644 --- a/packages/web-api/src/types/request/entity.ts +++ b/packages/web-api/src/types/request/entity.ts @@ -1,4 +1,4 @@ -import type { EntityMetadata } from '@slack/types'; +import type { EntityActionButton, EntityMetadata } from '@slack/types'; import type { TokenOverridable } from './common'; // https://api.slack.com/methods/entity.presentDetails @@ -32,7 +32,6 @@ export type EntityPresentDetailsArguments = TokenOverridable & { // If status is 'custom', you can use this field to provide a title to the client. custom_title?: string; // Set of action buttons to be shown in case of a specific error. - // biome-ignore lint/complexity/noBannedTypes: Allow Object - actions?: Object[]; + actions?: EntityActionButton[]; }; }; diff --git a/packages/web-api/test/types/methods/chat.test-d.ts b/packages/web-api/test/types/methods/chat.test-d.ts index 639c53255..569c10e8d 100644 --- a/packages/web-api/test/types/methods/chat.test-d.ts +++ b/packages/web-api/test/types/methods/chat.test-d.ts @@ -1,4 +1,4 @@ -import type { EntityMetadata } from '@slack/types'; +import { CustomFieldType, type EntityMetadata, EntityType } from '@slack/types'; import { expectAssignable, expectError } from 'tsd'; import { WebClient } from '../../../src/WebClient'; @@ -449,7 +449,7 @@ expectAssignable>([ metadata: { entities: [ { - entity_type: 'slack#/entities/file', + entity_type: EntityType.File, entity_payload: { attributes: { title: { text: 'My File' } }, }, @@ -752,6 +752,15 @@ const entityMetadata: EntityMetadata = { value: 'Details of the task.', }, }, + custom_fields: [ + { + label: 'My Field', + key: 'my-field', + type: CustomFieldType.Array, + item_type: 'slack#/types/channel_id', + value: [{ value: 'C0123ABC' }], + }, + ], }, external_ref: { id: '1234' }, url: 'https://myappdomain.com/id/1234', From bb49dd52e00a0786cf9ed788b77a7f7d6504ab3d Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 15 Oct 2025 16:35:51 -0400 Subject: [PATCH 16/35] feat-work-objects: beta version for the types pkg (#2406) --- packages/types/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/types/package.json b/packages/types/package.json index 59139f7a5..2b6a086bc 100644 --- a/packages/types/package.json +++ b/packages/types/package.json @@ -1,6 +1,6 @@ { "name": "@slack/types", - "version": "2.17.0-featWorkObjectsBeta.1", + "version": "2.17.0-featWorkObjectsBeta.2", "description": "Shared type definitions for the Node Slack SDK", "author": "Slack Technologies, LLC", "license": "MIT", From 480cb1f8fe16a38bc018db05c62963de6c137ecd Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 15 Oct 2025 16:50:17 -0400 Subject: [PATCH 17/35] feat-work-objects: beta version for the web-api pkg (#2407) --- packages/web-api/package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/web-api/package.json b/packages/web-api/package.json index 47c237915..4b01f9148 100644 --- a/packages/web-api/package.json +++ b/packages/web-api/package.json @@ -1,6 +1,6 @@ { "name": "@slack/web-api", - "version": "7.11.0-featWorkObjectsBeta.1", + "version": "7.11.0-featWorkObjectsBeta.2", "description": "Official library for using the Slack Platform's Web API", "author": "Slack Technologies, LLC", "license": "MIT", @@ -49,7 +49,7 @@ }, "dependencies": { "@slack/logger": "^4.0.0", - "@slack/types": "2.17.0-featWorkObjectsBeta.1", + "@slack/types": "2.17.0-featWorkObjectsBeta.2", "@types/node": ">=18.0.0", "@types/retry": "0.12.0", "axios": "^1.11.0", From c4992f607194800d31b37c636c9c8fb2d0bfc4a9 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 15 Oct 2025 22:33:19 -0400 Subject: [PATCH 18/35] Update URL in packages/web-api/src/types/request/chat.ts Co-authored-by: Eden Zimbelman --- packages/web-api/src/types/request/chat.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/web-api/src/types/request/chat.ts b/packages/web-api/src/types/request/chat.ts index 07eb77c45..89f6adb3d 100644 --- a/packages/web-api/src/types/request/chat.ts +++ b/packages/web-api/src/types/request/chat.ts @@ -256,7 +256,7 @@ export interface SourceAndUnfurlID { } type UnfurlTarget = ChannelAndTS | SourceAndUnfurlID; -// https://api.slack.com/methods/chat.unfurl +// https://docs.slack.dev/reference/methods/chat.unfurl export type ChatUnfurlArguments = (BlockKitUnfurls | EntityMetadataUnfurls) & UnfurlTarget & TokenOverridable & { From d2a9d93a46289494683244fd3ccad64d09e13d75 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 15 Oct 2025 22:34:47 -0400 Subject: [PATCH 19/35] Update URL in packages/web-api/src/types/request/entity.ts Co-authored-by: Eden Zimbelman --- packages/web-api/src/types/request/entity.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/web-api/src/types/request/entity.ts b/packages/web-api/src/types/request/entity.ts index 1b3798502..e977f46e2 100644 --- a/packages/web-api/src/types/request/entity.ts +++ b/packages/web-api/src/types/request/entity.ts @@ -1,7 +1,7 @@ import type { EntityActionButton, EntityMetadata } from '@slack/types'; import type { TokenOverridable } from './common'; -// https://api.slack.com/methods/entity.presentDetails +// https://docs.slack.dev/reference/methods/entity.presentDetails export type EntityPresentDetailsArguments = TokenOverridable & { /** * @description Entity metadata to be presented in the flexpane. From c4cb46c04f818531dedb89a42cf5d83d161e3c91 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 15 Oct 2025 22:41:41 -0400 Subject: [PATCH 20/35] alphabetical order --- packages/types/src/message-metadata.ts | 2 +- packages/web-api/src/methods.ts | 24 +++++++++---------- .../web-api/src/types/request/manifest.ts | 4 ++-- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/packages/types/src/message-metadata.ts b/packages/types/src/message-metadata.ts index a0250ee29..021b87ab8 100644 --- a/packages/types/src/message-metadata.ts +++ b/packages/types/src/message-metadata.ts @@ -56,7 +56,7 @@ export interface EntityMetadata { */ entity_payload: { attributes: EntityAttributes; - fields?: FileEntityFields | TaskEntityFields | IncidentEntityFields | ContentItemEntityFields; + fields?: ContentItemEntityFields | FileEntityFields | IncidentEntityFields | TaskEntityFields; custom_fields?: EntityCustomField[]; slack_file?: FileEntitySlackFile; display_order?: string[]; diff --git a/packages/web-api/src/methods.ts b/packages/web-api/src/methods.ts index 477d0bcab..a54420cf6 100644 --- a/packages/web-api/src/methods.ts +++ b/packages/web-api/src/methods.ts @@ -1644,18 +1644,6 @@ export abstract class Methods extends EventEmitter { update: bindApiCall(this, 'chat.update'), }; - public readonly entity = { - /** - * @description - * Provide information about the entity to be displayed in the flexpane. - * A link to the API documentation will be added when this API is publicly released. - */ - presentDetails: bindApiCall( - this, - 'entity.presentDetails', - ), - }; - public readonly conversations = { /** * @description Accepts an invitation to a Slack Connect channel. @@ -1893,6 +1881,18 @@ export abstract class Methods extends EventEmitter { list: bindApiCallWithOptionalArgument(this, 'emoji.list'), }; + public readonly entity = { + /** + * @description + * Provide information about the entity to be displayed in the flexpane. + * A link to the API documentation will be added when this API is publicly released. + */ + presentDetails: bindApiCall( + this, + 'entity.presentDetails', + ), + }; + public readonly files = { /** * @description Finishes an upload started with {@link https://docs.slack.dev/reference/methods/files.getUploadURLExternal `files.getUploadURLExternal`}. diff --git a/packages/web-api/src/types/request/manifest.ts b/packages/web-api/src/types/request/manifest.ts index a16071e4a..05a6613d0 100644 --- a/packages/web-api/src/types/request/manifest.ts +++ b/packages/web-api/src/types/request/manifest.ts @@ -467,6 +467,7 @@ type ManifestEvent = | 'dnd_updated_user' | 'email_domain_changed' | 'emoji_changed' + | 'entity_details_requested' | 'file_change' | 'file_comment_added' | 'file_comment_deleted' @@ -540,5 +541,4 @@ type ManifestEvent = | 'workflow_published' | 'workflow_step_deleted' | 'workflow_step_execute' - | 'workflow_unpublished' - | 'entity_details_requested'; + | 'workflow_unpublished'; From ec18401546162cad9ded820e4013c7ec9350f15e Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 16 Oct 2025 09:56:26 -0400 Subject: [PATCH 21/35] update comments to jsdoc format --- packages/web-api/src/types/request/entity.ts | 20 ++++++++++++++----- .../web-api/test/types/methods/chat.test-d.ts | 4 ++-- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/packages/web-api/src/types/request/entity.ts b/packages/web-api/src/types/request/entity.ts index e977f46e2..e3c72ac30 100644 --- a/packages/web-api/src/types/request/entity.ts +++ b/packages/web-api/src/types/request/entity.ts @@ -23,15 +23,25 @@ export type EntityPresentDetailsArguments = TokenOverridable & { user_auth_url?: string; /** @description Error response preventing flexpane data from being returned. */ error?: { - // Error status indicating why the entity could not be presented. + /** + * @description Error status indicating why the entity could not be presented. + * */ status: string; - // If status is 'custom', you can use this field to provide a message to the client. + /** + * @description If status is 'custom', you can use this field to provide a message to the client. + * */ custom_message?: string; - // String format, eg. 'markdown'. + /** + * @description String format, eg. 'markdown'. + * */ message_format?: string; - // If status is 'custom', you can use this field to provide a title to the client. + /** + * @description If status is 'custom', you can use this field to provide a title to the client. + * */ custom_title?: string; - // Set of action buttons to be shown in case of a specific error. + /** + * @description Set of action buttons to be shown in case of a specific error. + * */ actions?: EntityActionButton[]; }; }; diff --git a/packages/web-api/test/types/methods/chat.test-d.ts b/packages/web-api/test/types/methods/chat.test-d.ts index 569c10e8d..f1ec5f025 100644 --- a/packages/web-api/test/types/methods/chat.test-d.ts +++ b/packages/web-api/test/types/methods/chat.test-d.ts @@ -1,4 +1,4 @@ -import { CustomFieldType, type EntityMetadata, EntityType } from '@slack/types'; +import { CustomFieldType, type EntityMetadata } from '@slack/types'; import { expectAssignable, expectError } from 'tsd'; import { WebClient } from '../../../src/WebClient'; @@ -449,7 +449,7 @@ expectAssignable>([ metadata: { entities: [ { - entity_type: EntityType.File, + entity_type: 'slack#/entities/file', entity_payload: { attributes: { title: { text: 'My File' } }, }, From 6f56034b08bacf1c4beb38c65429ff8dc53e6a42 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 16 Oct 2025 12:16:36 -0400 Subject: [PATCH 22/35] update schema --- packages/types/src/events/message-metadata.ts | 10 ++--- packages/types/src/message-metadata.ts | 38 +++++++++---------- packages/web-api/src/types/request/chat.ts | 15 +++++--- 3 files changed, 34 insertions(+), 29 deletions(-) diff --git a/packages/types/src/events/message-metadata.ts b/packages/types/src/events/message-metadata.ts index ab808d31a..e932ccaae 100644 --- a/packages/types/src/events/message-metadata.ts +++ b/packages/types/src/events/message-metadata.ts @@ -1,4 +1,4 @@ -import type { EventMessageMetadata } from '../message-metadata'; +import type { MessageMetadata } from '../message-metadata'; export type AllMessageMetadataEvents = | MessageMetadataDeletedEvent @@ -12,7 +12,7 @@ export interface MessageMetadataPostedEvent { user_id: string; team_id: string; channel_id: string; - metadata: EventMessageMetadata; + metadata: MessageMetadata; message_ts: string; event_ts: string; } @@ -21,20 +21,20 @@ export interface MessageMetadataUpdatedEvent { type: 'message_metadata_updated'; channel_id: string; event_ts: string; - previous_metadata: EventMessageMetadata; + previous_metadata: MessageMetadata; app_id: string; bot_id?: string; user_id: string; team_id: string; message_ts: string; - metadata: EventMessageMetadata; + metadata: MessageMetadata; } export interface MessageMetadataDeletedEvent { type: 'message_metadata_deleted'; channel_id: string; event_ts: string; - previous_metadata: EventMessageMetadata; + previous_metadata: MessageMetadata; app_id: string; bot_id?: string; user_id: string; diff --git a/packages/types/src/message-metadata.ts b/packages/types/src/message-metadata.ts index 021b87ab8..8d5f003bc 100644 --- a/packages/types/src/message-metadata.ts +++ b/packages/types/src/message-metadata.ts @@ -1,8 +1,11 @@ import type { Option, PlainTextElement, SlackFile } from './block-kit/composition-objects'; +// ------------------------------ +// Event metadata +// ------------------------------ + /** - * @description Application-specific event or entity data to attach to Slack message. - * Provide 'event_type' and 'event_payload' to set event metadata, or use 'entities' to set work object entity metadata. + * @description Application-specific event data to attach to a Slack message. * @see {@link https://docs.slack.dev/messaging/message-metadata Using Metadata} * @see {@link https://docs.slack.dev/messaging/message-metadata Metadata Payload Structure} */ @@ -11,38 +14,35 @@ export interface MessageMetadata { * @description A human readable alphanumeric string representing your application's metadata event. * The value of this field may appear in the UI to developers. */ - event_type?: string; + event_type: string; /** * @description A free-form object containing whatever data your application wishes to attach to messages. */ - event_payload?: { + event_payload: { [key: string]: string | number | boolean | MessageMetadataEventPayloadObject | MessageMetadataEventPayloadObject[]; }; - - /** - * @description An array of work object entities. - */ - entities?: EntityMetadata[]; } -// ------------------------------ -// Event metadata -// ------------------------------ - -export interface EventMessageMetadata extends Omit {} - export interface MessageMetadataEventPayloadObject { [key: string]: string | number | boolean; } -export interface MessageMetadataEventPayloadAttributes { - [key: string]: string | number | boolean | MessageMetadataEventPayloadAttributes; -} - // ------------------------------ // Work object metadata // ------------------------------ +/** + * @description Application-specific entity and/or event data to attach to a Slack message. + * Provide 'entities' to set work object entity metadata. + * Provide 'event_type' and 'event_payload' to set event metadata. + */ +export interface EntityAndEventMessageMetadata extends Partial { + /** + * @description An array of work object entities. + */ + entities?: EntityMetadata[]; +} + /** * @description Metadata that represents a work object entity. */ diff --git a/packages/web-api/src/types/request/chat.ts b/packages/web-api/src/types/request/chat.ts index 89f6adb3d..32793fd73 100644 --- a/packages/web-api/src/types/request/chat.ts +++ b/packages/web-api/src/types/request/chat.ts @@ -1,5 +1,6 @@ import type { Block, // TODO: these will be combined into one in a new types release + EntityAndEventMessageMetadata, EntityMetadata, KnownBlock, LinkUnfurls, @@ -192,7 +193,7 @@ export type ChatPostMessageArguments = TokenOverridable & Authorship & Parse & LinkNames & - Metadata & + EntityAndEventMessageMetadata & Unfurls & { /** @description Disable Slack markup parsing by setting to `false`. Enabled by default. */ mrkdwn?: boolean; @@ -282,7 +283,9 @@ export type ChatUnfurlArguments = (BlockKitUnfurls | EntityMetadataUnfurls) & user_auth_blocks?: (KnownBlock | Block)[]; }; -// `unfurls` param of the `chat.unfurl` API +/** + * @description The `unfurls` param of the `chat.unfurl` API. + */ type BlockKitUnfurls = { /** * @description Object with keys set to URLs featured in the message, pointing to their unfurl @@ -291,12 +294,14 @@ type BlockKitUnfurls = { unfurls: LinkUnfurls; }; -// `metadata` param of the `chat.unfurl` API +/** + * @description The `metadata` param of the `chat.unfurl` API. + */ type EntityMetadataUnfurls = { /** - * @description Array of entities to attach to the message based on URLs featured in the message. + * @description Unfurl metadata featuring an array of entities to attach to the message based on URLs featured in the message. */ - metadata: { + metadata: Partial & { entities: EntityMetadata[]; }; }; From eeef76d2c27ea59292e9425c14eb62438c0f8088 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 16 Oct 2025 14:39:58 -0400 Subject: [PATCH 23/35] feat-work-objects: beta version for the types pkg (#2408) --- packages/types/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/types/package.json b/packages/types/package.json index 2b6a086bc..961bce17b 100644 --- a/packages/types/package.json +++ b/packages/types/package.json @@ -1,6 +1,6 @@ { "name": "@slack/types", - "version": "2.17.0-featWorkObjectsBeta.2", + "version": "2.17.0-featWorkObjectsBeta.3", "description": "Shared type definitions for the Node Slack SDK", "author": "Slack Technologies, LLC", "license": "MIT", From a44d4b3bac54bc05d1db9350e33ca6e71c73fd1b Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 16 Oct 2025 14:59:13 -0400 Subject: [PATCH 24/35] whoops --- packages/web-api/src/types/request/chat.ts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/web-api/src/types/request/chat.ts b/packages/web-api/src/types/request/chat.ts index 32793fd73..df21beed8 100644 --- a/packages/web-api/src/types/request/chat.ts +++ b/packages/web-api/src/types/request/chat.ts @@ -106,6 +106,10 @@ export interface BroadcastedThreadReply extends ThreadTS { // or not broadcasted. Broadcasted replies are necessarily threaded, so `thread_ts` becomes required. type ReplyInThread = WithinThreadReply | BroadcastedThreadReply; +export interface ChatPostMessageMetadata { + /** @description Object representing message metadata, which will be made accessible to any user or app. */ + metadata?: EntityAndEventMessageMetadata; +} export interface Metadata { /** @description Object representing message metadata, which will be made accessible to any user or app. */ metadata?: MessageMetadata; @@ -193,7 +197,7 @@ export type ChatPostMessageArguments = TokenOverridable & Authorship & Parse & LinkNames & - EntityAndEventMessageMetadata & + ChatPostMessageMetadata & Unfurls & { /** @description Disable Slack markup parsing by setting to `false`. Enabled by default. */ mrkdwn?: boolean; From 1d4325b1e318a6ce629b8da6983943aed227ab5f Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 16 Oct 2025 15:07:09 -0400 Subject: [PATCH 25/35] feat-work-objects: version bump for the web-api pkg (#2409) --- packages/web-api/package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/web-api/package.json b/packages/web-api/package.json index 4b01f9148..4530d33e5 100644 --- a/packages/web-api/package.json +++ b/packages/web-api/package.json @@ -1,6 +1,6 @@ { "name": "@slack/web-api", - "version": "7.11.0-featWorkObjectsBeta.2", + "version": "7.11.0-featWorkObjectsBeta.3", "description": "Official library for using the Slack Platform's Web API", "author": "Slack Technologies, LLC", "license": "MIT", @@ -49,7 +49,7 @@ }, "dependencies": { "@slack/logger": "^4.0.0", - "@slack/types": "2.17.0-featWorkObjectsBeta.2", + "@slack/types": "2.17.0-featWorkObjectsBeta.3", "@types/node": ">=18.0.0", "@types/retry": "0.12.0", "axios": "^1.11.0", From 019cfd3123aea3e20cd41f2c3ab5a72ba1ae3a0a Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 22 Oct 2025 10:53:55 -0400 Subject: [PATCH 26/35] update comment --- packages/web-api/src/methods.ts | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/packages/web-api/src/methods.ts b/packages/web-api/src/methods.ts index a54420cf6..377924b36 100644 --- a/packages/web-api/src/methods.ts +++ b/packages/web-api/src/methods.ts @@ -1883,9 +1883,8 @@ export abstract class Methods extends EventEmitter { public readonly entity = { /** - * @description - * Provide information about the entity to be displayed in the flexpane. - * A link to the API documentation will be added when this API is publicly released. + * @description Provide information about the entity to be displayed in the flexpane. + * @see {@link https://docs.slack.dev/reference/methods/entity.presentDetails} */ presentDetails: bindApiCall( this, From fae7b1789ac12728e5d2070fa2de0678612b43ed Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 22 Oct 2025 11:13:16 -0400 Subject: [PATCH 27/35] mv EntityAndEventMessageMetadata --- packages/types/src/message-metadata.ts | 12 ------------ packages/web-api/src/types/request/chat.ts | 14 +++++++++++--- 2 files changed, 11 insertions(+), 15 deletions(-) diff --git a/packages/types/src/message-metadata.ts b/packages/types/src/message-metadata.ts index 8d5f003bc..43728d38f 100644 --- a/packages/types/src/message-metadata.ts +++ b/packages/types/src/message-metadata.ts @@ -31,18 +31,6 @@ export interface MessageMetadataEventPayloadObject { // Work object metadata // ------------------------------ -/** - * @description Application-specific entity and/or event data to attach to a Slack message. - * Provide 'entities' to set work object entity metadata. - * Provide 'event_type' and 'event_payload' to set event metadata. - */ -export interface EntityAndEventMessageMetadata extends Partial { - /** - * @description An array of work object entities. - */ - entities?: EntityMetadata[]; -} - /** * @description Metadata that represents a work object entity. */ diff --git a/packages/web-api/src/types/request/chat.ts b/packages/web-api/src/types/request/chat.ts index df21beed8..314c3c6e4 100644 --- a/packages/web-api/src/types/request/chat.ts +++ b/packages/web-api/src/types/request/chat.ts @@ -1,6 +1,5 @@ import type { Block, // TODO: these will be combined into one in a new types release - EntityAndEventMessageMetadata, EntityMetadata, KnownBlock, LinkUnfurls, @@ -107,8 +106,17 @@ export interface BroadcastedThreadReply extends ThreadTS { type ReplyInThread = WithinThreadReply | BroadcastedThreadReply; export interface ChatPostMessageMetadata { - /** @description Object representing message metadata, which will be made accessible to any user or app. */ - metadata?: EntityAndEventMessageMetadata; + /** + * @description Object representing message metadata, entity and/or event data to attach to a Slack message. + * Provide 'entities' to set work object entity metadata. + * Provide 'event_type' and 'event_payload' to set event metadata. + */ + metadata?: Partial & { + /** + * @description An array of work object entities. + */ + entities?: EntityMetadata[]; + }; } export interface Metadata { /** @description Object representing message metadata, which will be made accessible to any user or app. */ From a2eaa7150080f21eeddceaa5d5273a80db4ea246 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 22 Oct 2025 11:23:55 -0400 Subject: [PATCH 28/35] rename types for unfurls and metadata param of chat.unfurl --- packages/web-api/src/types/request/chat.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/web-api/src/types/request/chat.ts b/packages/web-api/src/types/request/chat.ts index 314c3c6e4..efdbad52d 100644 --- a/packages/web-api/src/types/request/chat.ts +++ b/packages/web-api/src/types/request/chat.ts @@ -270,7 +270,7 @@ export interface SourceAndUnfurlID { type UnfurlTarget = ChannelAndTS | SourceAndUnfurlID; // https://docs.slack.dev/reference/methods/chat.unfurl -export type ChatUnfurlArguments = (BlockKitUnfurls | EntityMetadataUnfurls) & +export type ChatUnfurlArguments = (ChatUnfurlUnfurls | ChatUnfurlMetadata) & UnfurlTarget & TokenOverridable & { /** @@ -298,7 +298,7 @@ export type ChatUnfurlArguments = (BlockKitUnfurls | EntityMetadataUnfurls) & /** * @description The `unfurls` param of the `chat.unfurl` API. */ -type BlockKitUnfurls = { +interface ChatUnfurlUnfurls { /** * @description Object with keys set to URLs featured in the message, pointing to their unfurl * blocks or message attachments. @@ -309,7 +309,7 @@ type BlockKitUnfurls = { /** * @description The `metadata` param of the `chat.unfurl` API. */ -type EntityMetadataUnfurls = { +interface ChatUnfurlMetadata { /** * @description Unfurl metadata featuring an array of entities to attach to the message based on URLs featured in the message. */ From 26e3aa516b342e143d05a364e62c8fd8e96486a4 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 22 Oct 2025 12:06:39 -0400 Subject: [PATCH 29/35] biome fix --- packages/web-api/src/types/request/chat.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/web-api/src/types/request/chat.ts b/packages/web-api/src/types/request/chat.ts index efdbad52d..7734d7a7f 100644 --- a/packages/web-api/src/types/request/chat.ts +++ b/packages/web-api/src/types/request/chat.ts @@ -304,7 +304,7 @@ interface ChatUnfurlUnfurls { * blocks or message attachments. */ unfurls: LinkUnfurls; -}; +} /** * @description The `metadata` param of the `chat.unfurl` API. @@ -316,7 +316,7 @@ interface ChatUnfurlMetadata { metadata: Partial & { entities: EntityMetadata[]; }; -}; +} // https://docs.slack.dev/reference/methods/chat.update export type ChatUpdateArguments = MessageContents & { From 4eaeed883458e95a2e354eac9614e7c7f5865616 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 22 Oct 2025 12:32:33 -0400 Subject: [PATCH 30/35] make cli-test dependency versions exact --- packages/cli-test/package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/cli-test/package.json b/packages/cli-test/package.json index 02c230a78..d07c2c837 100644 --- a/packages/cli-test/package.json +++ b/packages/cli-test/package.json @@ -44,7 +44,7 @@ "@types/chai": "^4.3.16", "@types/mocha": "^10.0.6", "@types/node": "^24.0.3", - "@types/sinon": "^17.0.3", + "@types/sinon": "17.0.3", "c8": "^10.1.2", "chai": "^4.4.1", "cross-env": "^10.0.0", @@ -52,7 +52,7 @@ "mocha-junit-reporter": "^2.2.1", "mocha-multi-reporters": "^1.5.1", "shx": "^0.4.0", - "sinon": "^21.0.0", + "sinon": "21.0.0", "ts-node": "^10.9.2", "typedoc": "^0.28.7", "typedoc-plugin-markdown": "^4.7.1", From 6d2ebc4a4001a559dd896f4640d5d27646c65d6e Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Wed, 22 Oct 2025 13:30:06 -0400 Subject: [PATCH 31/35] Revert "make cli-test dependency versions exact" This reverts commit 4eaeed883458e95a2e354eac9614e7c7f5865616. --- packages/cli-test/package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/cli-test/package.json b/packages/cli-test/package.json index d07c2c837..02c230a78 100644 --- a/packages/cli-test/package.json +++ b/packages/cli-test/package.json @@ -44,7 +44,7 @@ "@types/chai": "^4.3.16", "@types/mocha": "^10.0.6", "@types/node": "^24.0.3", - "@types/sinon": "17.0.3", + "@types/sinon": "^17.0.3", "c8": "^10.1.2", "chai": "^4.4.1", "cross-env": "^10.0.0", @@ -52,7 +52,7 @@ "mocha-junit-reporter": "^2.2.1", "mocha-multi-reporters": "^1.5.1", "shx": "^0.4.0", - "sinon": "21.0.0", + "sinon": "^21.0.0", "ts-node": "^10.9.2", "typedoc": "^0.28.7", "typedoc-plugin-markdown": "^4.7.1", From c0cc1f66496e0f52f188f5b21d7c502a2361c496 Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 23 Oct 2025 09:33:29 -0400 Subject: [PATCH 32/35] rm types pkg updates --- packages/types/package.json | 2 +- .../src/events/entity-details-requested.ts | 20 -- packages/types/src/events/index.ts | 2 - packages/types/src/message-metadata.ts | 280 +----------------- packages/web-api/package.json | 2 +- 5 files changed, 3 insertions(+), 303 deletions(-) delete mode 100644 packages/types/src/events/entity-details-requested.ts diff --git a/packages/types/package.json b/packages/types/package.json index 961bce17b..495b89f70 100644 --- a/packages/types/package.json +++ b/packages/types/package.json @@ -1,6 +1,6 @@ { "name": "@slack/types", - "version": "2.17.0-featWorkObjectsBeta.3", + "version": "2.17.0", "description": "Shared type definitions for the Node Slack SDK", "author": "Slack Technologies, LLC", "license": "MIT", diff --git a/packages/types/src/events/entity-details-requested.ts b/packages/types/src/events/entity-details-requested.ts deleted file mode 100644 index f9d69c462..000000000 --- a/packages/types/src/events/entity-details-requested.ts +++ /dev/null @@ -1,20 +0,0 @@ -export interface EntityDetailsRequestedEvent { - type: 'entity_details_requested'; - user: string; - trigger_id: string; - link: { - url: string; - domain: string; - }; - entity_url: string; - app_unfurl_url?: string; - user_locale: string; - event_ts: string; - external_ref?: { - id: string; - type?: string; - }; - message_ts?: string; - thread_ts?: string; - channel?: string; -} diff --git a/packages/types/src/events/index.ts b/packages/types/src/events/index.ts index bb4de42c0..18b153fe1 100644 --- a/packages/types/src/events/index.ts +++ b/packages/types/src/events/index.ts @@ -25,7 +25,6 @@ import type { import type { DNDUpdatedEvent, DNDUpdatedUserEvent } from './dnd'; import type { EmailDomainChangedEvent } from './email'; import type { EmojiChangedEvent } from './emoji'; -import type { EntityDetailsRequestedEvent } from './entity-details-requested'; import type { FileChangeEvent, FileCommentDeletedEvent, @@ -145,7 +144,6 @@ export type SlackEvent = | DNDUpdatedUserEvent | EmailDomainChangedEvent | EmojiChangedEvent - | EntityDetailsRequestedEvent | FileChangeEvent | FileCommentDeletedEvent | FileCreatedEvent diff --git a/packages/types/src/message-metadata.ts b/packages/types/src/message-metadata.ts index 43728d38f..4733d25ea 100644 --- a/packages/types/src/message-metadata.ts +++ b/packages/types/src/message-metadata.ts @@ -1,11 +1,5 @@ -import type { Option, PlainTextElement, SlackFile } from './block-kit/composition-objects'; - -// ------------------------------ -// Event metadata -// ------------------------------ - /** - * @description Application-specific event data to attach to a Slack message. + * @description Application-specific data to attach to Slack message. * @see {@link https://docs.slack.dev/messaging/message-metadata Using Metadata} * @see {@link https://docs.slack.dev/messaging/message-metadata Metadata Payload Structure} */ @@ -26,275 +20,3 @@ export interface MessageMetadata { export interface MessageMetadataEventPayloadObject { [key: string]: string | number | boolean; } - -// ------------------------------ -// Work object metadata -// ------------------------------ - -/** - * @description Metadata that represents a work object entity. - */ -export interface EntityMetadata { - /** - * @description Entity type. - */ - entity_type: EntityType | string; - /** - * @description Schema for the given entity type. - */ - entity_payload: { - attributes: EntityAttributes; - fields?: ContentItemEntityFields | FileEntityFields | IncidentEntityFields | TaskEntityFields; - custom_fields?: EntityCustomField[]; - slack_file?: FileEntitySlackFile; - display_order?: string[]; - actions?: { - primary_actions?: EntityActionButton[]; - overflow_actions?: EntityActionButton[]; - }; - }; - /** - * @description Reference (and optional type) used to identify an entity within the developer's system. - */ - external_ref: ExternalRef; - /** - * @description URL used to identify an entity within the developer's system. - */ - url: string; - - /** - * @description The exact URL posted in the source message. Required in metadata passed to `chat.unfurl`. - */ - app_unfurl_url?: string; -} - -export interface ExternalRef { - id: string; - type?: string; -} - -export enum EntityType { - Task = 'slack#/entities/task', - File = 'slack#/entities/file', - Item = 'slack#/entities/item', - Incident = 'slack#/entities/incident', - ContentItem = 'slack#/entities/content_item', -} - -export interface FileEntitySlackFile { - id: string; - type?: string; -} - -export interface EntityAttributes { - title: { - text: string; - edit?: EntityEditSupport; - }; - display_type?: string; - display_id?: string; - product_icon?: EntityIconField; - product_name?: string; - locale?: string; - full_size_preview?: EntityFullSizePreview; - metadata_last_modified?: number; -} - -export interface EntityIconField { - alt_text: string; - url?: string; - slack_file?: { - id?: string; - url?: string; - }; -} - -export interface EntityEditSupport { - enabled: boolean; - placeholder?: PlainTextElement; - hint?: PlainTextElement; - optional?: boolean; - select?: { - current_value?: string; - current_values?: string[]; - static_options?: Option[]; - fetch_options_dynamically?: boolean; - min_query_length?: number; - }; - number?: { - is_decimal_allowed?: boolean; - min_value?: number; - max_value?: number; - }; - text?: { - min_length?: number; - max_length?: number; - }; -} - -export interface EntityFullSizePreview { - is_supported: boolean; - preview_url?: string; - mime_type?: string; - error?: { - code: string; - message?: string; - }; -} - -export interface FileEntityFields { - preview?: EntityImageField; - created_by?: EntityTypedField; - date_created?: EntityTimestampField; - date_updated?: EntityTimestampField; - last_modified_by?: EntityTypedField; - file_size?: EntityStringField; - mime_type?: EntityStringField; - full_size_preview?: EntityFullSizePreview; -} - -export interface TaskEntityFields { - description?: EntityStringField; - created_by?: EntityTypedField; - date_created?: EntityTimestampField; - date_updated?: EntityTimestampField; - assignee?: EntityTypedField; - status?: EntityStringField; - due_date?: EntityTypedField; - priority?: EntityStringField; -} - -export interface IncidentEntityFields { - status?: EntityStringField; - priority?: EntityStringField; - urgency?: EntityStringField; - created_by?: EntityTypedField; - assigned_to?: EntityTypedField; - date_created?: EntityTimestampField; - date_updated?: EntityTimestampField; - description?: EntityStringField; - service?: EntityStringField; -} - -export interface ContentItemEntityFields { - preview?: EntityImageField; - description?: EntityStringField; - created_by?: EntityTypedField; - date_created?: EntityTimestampField; - date_updated?: EntityTimestampField; - last_modified_by?: EntityTypedField; -} - -export interface EntityArrayItemField extends Omit { - type?: string; -} - -export interface EntityTypedField { - type: string; - label?: string; - value?: string | number; - link?: string; - icon?: EntityIconField; - long?: boolean; - format?: string; - image_url?: string; - slack_file?: SlackFile; - alt_text?: string; - edit?: EntityEditSupport; - tag_color?: string; - user?: EntityUserIDField | EntityUserField; - entity_ref?: EntityRefField; -} - -export interface EntityStringField { - value: string; - label?: string; - format?: string; - link?: string; - icon?: EntityIconField; - long?: boolean; - type?: string; - tag_color?: string; - edit?: EntityEditSupport; -} - -export interface EntityUserIDField { - user_id: string; -} - -export interface EntityUserField { - text: string; - url?: string; - email?: string; - icon?: EntityIconField; -} - -export interface EntityRefField { - entity_url: string; - external_ref: ExternalRef; - title: string; - display_type?: string; - icon?: EntityIconField; -} - -export interface EntityTimestampField { - value: number; - label?: string; - link?: string; - icon?: EntityIconField; - type?: string; - edit?: EntityEditSupport; -} - -export interface EntityImageField { - alt_text: string; - label?: string; - image_url?: string; - slack_file?: SlackFile; - title?: string; - type?: string; -} - -export interface EntityCustomField { - label: string; - key: string; - type: CustomFieldType | string; - value?: string | number | EntityArrayItemField[]; - link?: string; - icon?: EntityIconField; - long?: boolean; - format?: string; - image_url?: string; - slack_file?: SlackFile; - alt_text?: string; - tag_color?: string; - edit?: EntityEditSupport; - item_type?: string; - user?: EntityUserIDField | EntityUserField; - entity_ref?: EntityRefField; -} - -export enum CustomFieldType { - Integer = 'integer', - String = 'string', - Array = 'array', - Date = 'slack#/types/date', - Timestamp = 'slack#/types/timestamp', - Image = 'slack#/types/image', - ChannelId = 'slack#/types/channel_id', - User = 'slack#/types/user', - EntityRef = 'slack#/types/entity_ref', -} - -export interface EntityActionButton { - text: string; - action_id: string; - value?: string; - style?: string; - url?: string; - accessibility_label?: string; - processing_state?: { - enabled: boolean; - interstitial_text?: string; - }; -} diff --git a/packages/web-api/package.json b/packages/web-api/package.json index 4530d33e5..660ea9956 100644 --- a/packages/web-api/package.json +++ b/packages/web-api/package.json @@ -49,7 +49,7 @@ }, "dependencies": { "@slack/logger": "^4.0.0", - "@slack/types": "2.17.0-featWorkObjectsBeta.3", + "@slack/types": "2.17.0-featWorkObjectsBeta.4", "@types/node": ">=18.0.0", "@types/retry": "0.12.0", "axios": "^1.11.0", From d97416469a213b8e1788d5a575077ed3cc189fde Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 23 Oct 2025 10:17:17 -0400 Subject: [PATCH 33/35] feat-work-objects: version bump for the web-api pkg (#2416) --- packages/web-api/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/web-api/package.json b/packages/web-api/package.json index 660ea9956..fb1721f3c 100644 --- a/packages/web-api/package.json +++ b/packages/web-api/package.json @@ -1,6 +1,6 @@ { "name": "@slack/web-api", - "version": "7.11.0-featWorkObjectsBeta.3", + "version": "7.11.0-featWorkObjectsBeta.4", "description": "Official library for using the Slack Platform's Web API", "author": "Slack Technologies, LLC", "license": "MIT", From 5c174bd54fd5a0cb7ca190902da4df4c727f551e Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 23 Oct 2025 15:55:50 -0400 Subject: [PATCH 34/35] update types dependency and reset web-api package version --- packages/web-api/package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/web-api/package.json b/packages/web-api/package.json index fb1721f3c..56fc2fdb6 100644 --- a/packages/web-api/package.json +++ b/packages/web-api/package.json @@ -1,6 +1,6 @@ { "name": "@slack/web-api", - "version": "7.11.0-featWorkObjectsBeta.4", + "version": "7.11.0", "description": "Official library for using the Slack Platform's Web API", "author": "Slack Technologies, LLC", "license": "MIT", @@ -49,7 +49,7 @@ }, "dependencies": { "@slack/logger": "^4.0.0", - "@slack/types": "2.17.0-featWorkObjectsBeta.4", + "@slack/types": "2.18.0", "@types/node": ">=18.0.0", "@types/retry": "0.12.0", "axios": "^1.11.0", From 3ae97207a62a58077d2105cc65d18a00e801bf2e Mon Sep 17 00:00:00 2001 From: Elaine Vegeris Date: Thu, 23 Oct 2025 18:04:23 -0400 Subject: [PATCH 35/35] Update packages/web-api/package.json Co-authored-by: William Bergamin --- packages/web-api/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/web-api/package.json b/packages/web-api/package.json index 56fc2fdb6..2492e4870 100644 --- a/packages/web-api/package.json +++ b/packages/web-api/package.json @@ -49,7 +49,7 @@ }, "dependencies": { "@slack/logger": "^4.0.0", - "@slack/types": "2.18.0", + "@slack/types": "^2.18.0", "@types/node": ">=18.0.0", "@types/retry": "0.12.0", "axios": "^1.11.0",