feat: add support to @slack/web-api for work objects

packages/types/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slack/types",
-  "version": "2.17.0",
+  "version": "2.17.0-featWorkObjectsBeta.2",
   "description": "Shared type definitions for the Node Slack SDK",
   "author": "Slack Technologies, LLC",
   "license": "MIT",

packages/types/src/events/entity-details-requested.ts

@@ -0,0 +1,20 @@
+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;
+}

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

packages/types/src/message-metadata.ts

@@ -1,5 +1,11 @@
+import type { Option, PlainTextElement, SlackFile } from './block-kit/composition-objects';
+
+// ------------------------------
+// Event metadata
+// ------------------------------
+
 /**
- * @description Application-specific data to attach to Slack message.
+ * @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}
  */
@@ -20,3 +26,287 @@ export interface MessageMetadata {
 export interface MessageMetadataEventPayloadObject {
   [key: string]: string | number | boolean;
 }
+
+// ------------------------------
+// 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<MessageMetadata> {
+  /**
+   * @description An array of work object entities.
+   */
+  entities?: EntityMetadata[];
+}
+
+/**
+ * @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<EntityTypedField, 'type'> {
+  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;
+  };
+}

packages/web-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slack/web-api",
-  "version": "7.11.0",
+  "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",
+    "@slack/types": "2.17.0-featWorkObjectsBeta.2",
     "@types/node": ">=18.0.0",
     "@types/retry": "0.12.0",
     "axios": "^1.11.0",

packages/web-api/src/methods.ts

@@ -177,6 +177,7 @@ import type {
   DndSetSnoozeArguments,
   DndTeamInfoArguments,
   EmojiListArguments,
+  EntityPresentDetailsArguments,
   FilesCommentsDeleteArguments,
   FilesCompleteUploadExternalArguments,
   FilesDeleteArguments,
@@ -437,6 +438,7 @@ import type {
   DndSetSnoozeResponse,
   DndTeamInfoResponse,
   EmojiListResponse,
+  EntityPresentDetailsResponse,
   FilesCommentsDeleteResponse,
   FilesCompleteUploadExternalResponse,
   FilesDeleteResponse,
@@ -1879,6 +1881,18 @@ export abstract class Methods extends EventEmitter<WebClientEvent> {
     list: bindApiCallWithOptionalArgument<EmojiListArguments, EmojiListResponse>(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<EntityPresentDetailsArguments, EntityPresentDetailsResponse>(
+      this,
+      'entity.presentDetails',
+    ),
+  };
+
   public readonly files = {
     /**
      * @description Finishes an upload started with {@link https://docs.slack.dev/reference/methods/files.getUploadURLExternal `files.getUploadURLExternal`}.