Update

Author: vegeris

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[];

packages/web-api/package.json

@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@slack/logger": "^4.0.0",
-    "@slack/types": "^2.9.0",
+    "@slack/types": "file:../types",
     "@types/node": ">=18.0.0",
     "@types/retry": "0.12.0",
     "axios": "^1.8.3",

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

packages/web-api/test/types/methods/chat.test-d.ts

@@ -399,6 +399,21 @@ expectAssignable<Parameters<typeof web.chat.postMessage>>([
     reply_broadcast: false, // can send a threaded message and explicitly not broadcast it
   },
 ]);
+expectAssignable<Parameters<typeof web.chat.postMessage>>([
+  {
+    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<Parameters<typeof web.chat.unfurl>>([
     ts: '1234.56',
   },
 ]);
+expectAssignable<Parameters<typeof web.chat.unfurl>>([
+  {
+    channel: 'C1234',
+    ts: '1234.56',
+    metadata: {
+      entities: [
+        {
+          entity_type: 'slack#/entities/file',
+          entity_payload: {},
+          app_unfurl_url: 'https://google.com',
+        },
+      ],
+    },
+  },
+]);
 
 // chat.update
 // -- sad path