From c635b77dc4522f731098b1b92023ecb9cad5ddc4 Mon Sep 17 00:00:00 2001
From: Fil Maj <fmaj@slack-corp.com>
Date: Tue, 8 Nov 2022 10:05:05 -0500
Subject: [PATCH] ChatUnfurlArguments require either `channel` and `ts` or
 `unfurl_id` and `source` properties to be specified in pairs (#1551)

* ChatUnfurlArguments require either `channel` and `ts` or `unfurl_id` and `source` properties to be specified in pairs. Fixes #1530.

* Expand ChatUnfurlArguments to accept either source and unfurl_id, or channel and ts. Add JSDoc for all ChatUnfurlArgument properties.
---
 packages/web-api/src/methods.ts | 49 +++++++++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 2 deletions(-)

diff --git a/packages/web-api/src/methods.ts b/packages/web-api/src/methods.ts
index 3d16183e3..99e7ef135 100644
--- a/packages/web-api/src/methods.ts
+++ b/packages/web-api/src/methods.ts
@@ -1480,15 +1480,60 @@ export interface ChatScheduledMessagesListArguments extends WebAPICallOptions, T
   team_id?: string; // required if org token is used
 }
 cursorPaginationEnabledMethods.add('chat.scheduledMessages.list');
-export interface ChatUnfurlArguments extends WebAPICallOptions, TokenOverridable {
+// ChannelAndTS and SourceAndUnfurlID are used as either-or mixins for ChatUnfurlArguments
+interface ChannelAndTSArguments {
+  /**
+   * @description Channel ID of the message. Both `channel` and `ts` must be provided together, or `unfurl_id` and
+   * `source` must be provided together.
+   */
   channel: string;
+  /**
+   * @description Timestamp of the message to add unfurl behavior to.
+   */
   ts: string;
+}
+
+interface SourceAndUnfurlIDArguments {
+  /**
+   * @description The source of the link to unfurl. The source may either be `composer`, when the link is inside the
+   * message composer, or `conversations_history`, when the link has been posted to a conversation.
+   */
+  source: 'composer' | 'conversations_history';
+  /**
+   * @description The ID of the link to unfurl. Both `unfurl_id` and `source` must be provided together, or `channel`
+   * and `ts` must be provided together.
+   */
+  unfurl_id: string;
+}
+export type ChatUnfurlArguments = (ChannelAndTSArguments | SourceAndUnfurlIDArguments) & WebAPICallOptions
+& TokenOverridable
+& {
+  /**
+   * @description URL-encoded JSON map with keys set to URLs featured in the the message, pointing to their unfurl
+   * blocks or message attachments.
+   */
   unfurls: LinkUnfurls;
+  /**
+   * @description Provide a simply-formatted string to send as an ephemeral message to the user as invitation to
+   * authenticate further and enable full unfurling behavior. Provides two buttons, Not now or Never ask me again.
+   */
   user_auth_message?: string;
+  /**
+   * @description Set to `true` to indicate the user must install your Slack app to trigger unfurls for this domain.
+   * Defaults to `false`.
+   */
   user_auth_required?: boolean;
+  /**
+   * @description Send users to this custom URL where they will complete authentication in your app to fully trigger
+   * unfurling. Value should be properly URL-encoded.
+   */
   user_auth_url?: string;
+  /**
+   * @description Provide a JSON based array of structured blocks presented as URL-encoded string to send as an
+   * ephemeral message to the user as invitation to authenticate further and enable full unfurling behavior.
+   */
   user_auth_blocks?: (KnownBlock | Block)[];
-}
+};
 export interface ChatUpdateArguments extends WebAPICallOptions, TokenOverridable {
   channel: string;
   ts: string;