From eed8e0534a7775bf9ce1631aa147afd5f353f6d1 Mon Sep 17 00:00:00 2001
From: Philipp Burckhardt <pburckhardt@outlook.com>
Date: Sat, 10 Jun 2023 18:04:50 -0400
Subject: [PATCH] docs: include descriptions of API method params

---
 src/services/slack.ts | 126 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 123 insertions(+), 3 deletions(-)

diff --git a/src/services/slack.ts b/src/services/slack.ts
index 97dfbcb..dcc2560 100644
--- a/src/services/slack.ts
+++ b/src/services/slack.ts
@@ -55,51 +55,171 @@ export type SlackBlock = {
   [key: string]: any
 }
 
+/**
+ * Parameters for the Slack API's `chat.postMessage` method.
+ *
+ * @see {@link https://api.slack.com/methods/chat.postMessage}
+ */
 export type SlackPostMessageParams = {
   /**
-   * The text of the message to send.
+   * The formatted text of the message to be published.
    */
   text: string
 
   /**
-   * The ID of the channel to send the message to.
+   * Channel, private group, or IM channel to send the message to. Can be an encoded ID, or a name.
    */
   channel?: string
 
   /**
-   * The timestamp of a parent message to send the message as a reply to.
+   * Provide another message's ts value to make this message a reply. Avoid using a reply's ts value; use its parent instead.
    */
   thread_ts?: string
+
+  /**
+   * A JSON-based array of structured attachments, presented as a URL-encoded string.
+   */
   attachments?: SlackAttachment[]
+
+  /**
+   * A JSON-based array of structured blocks, presented as a URL-encoded string.
+   */
   blocks?: SlackBlock[]
+
+  /**
+   * Emoji to use as the icon for this message. Overrides icon_url.
+   */
   icon_emoji?: string
+
+  /**
+   * URL to an image to use as the icon for this message.
+   */
   icon_url?: string
+
+  /**
+   * If set to true, user group handles (to name just one example) will be linked in the message text.
+   */
   link_names?: boolean
+
+  /**
+   * Change how messages are treated (default: 'none').
+   */
   parse?: 'full' | 'none'
+
+  /**
+   * Used in conjunction with thread_ts and indicates whether reply should be made visible to everyone in the channel or conversation.
+   */
   reply_broadcast?: boolean
+
+  /**
+   * Pass true to enable unfurling of primarily text-based content.
+   */
   unfurl_links?: boolean
+
+  /**
+   * Pass false to disable unfurling of media content.
+   */
   unfurl_media?: boolean
+
+  /**
+   * Set your bot's user name.
+   */
   username?: string
 }
 
+/**
+ * Parameters for the Slack API's `conversations.history` method.
+ *
+ * @see {@link https://api.slack.com/methods/conversations.history}
+ */
 export type SlackConversationHistoryParams = {
+  /**
+   * The conversation ID to fetch history for.
+   */
   channel: string
+
+  /**
+   * Only messages after this Unix timestamp will be included in results (default: `0`).
+   */
   oldest?: string
+
+  /**
+   * The cursor value used for pagination of results (default: first page).
+   */
   cursor?: string
+
+  /**
+   * Only messages before this Unix timestamp will be included in results (default: now).
+   */
   latest?: string
+
+  /**
+   * The maximum number of items to return (default: `100`).
+   */
   limit?: number
+
+  /**
+   * Include messages with the oldest or latest timestamps in results. Ignored unless either timestamp is specified (default: `false`).
+   */
   inclusive?: boolean
+
+  /**
+   * Return all metadata associated with the messages (default: `false`).
+   */
   include_all_metadata?: boolean
 }
 
+/**
+ * Parameters for the Slack API's `conversations.replies` method.
+ *
+ * @see {@link https://api.slack.com/methods/conversations.replies}
+ */
 export type SlackConversationRepliesParams = {
+  /**
+   * The conversation ID to fetch the thread from.
+   */
   channel: string
+
+  /**
+   * Unique identifier of either a thread’s parent message or a message in the thread.
+   *
+   * ### Notes
+   *
+   * -   ts must be the timestamp of an existing message with 0 or more replies.
+   * -   If there are no replies then just the single message referenced by ts will return - it is just an ordinary, unthreaded message.
+   */
   ts: string
+
+  /**
+   * The cursor value used for pagination of results.
+   * Set this to the `next_cursor` attribute returned by a previous request's response_metadata.
+   */
   cursor?: string
+
+  /**
+   * Only messages before this Unix timestamp will be included in results.
+   */
   latest?: string
+
+  /**
+   * Only messages after this Unix timestamp will be included in results.
+   */
   oddest?: string
+
+  /**
+   * The maximum number of items to return.
+   * Fewer than the requested number of items may be returned, even if the end of the users list hasn't been reached.
+   */
   limit?: number
+
+  /**
+   * Include messages with the oldest or latest timestamps in results. Ignored unless either timestamp is specified.
+   */
   inclusive?: boolean
+
+  /**
+   * Return all metadata associated with this message.
+   */
   include_thread_metadata?: boolean
 }