feat: accept chunks as arguments to chat.{start,append,stop}Stream methods

packages/types/src/chunk.ts

@@ -0,0 +1,54 @@
+/**
+ * Base interface for streaming message chunks.
+ * https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming
+ */
+export interface Chunk {
+  type: string;
+}
+
+/**
+ * Used for streaming text content with markdown formatting support.
+ * https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming
+ */
+export interface MarkdownTextChunk extends Chunk {
+  type: 'markdown_text';
+  text: string;
+}
+
+/**
+ * URL source for task update chunks.
+ */
+export interface URLSource {
+  type: 'url';
+  url: string;
+  text: string;
+  icon_url?: string;
+}
+
+/**
+ * An updated title of plans for task and tool calls.
+ * https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming
+ */
+export interface PlanUpdateChunk extends Chunk {
+  type: 'plan_update';
+  title: string;
+}
+
+/**
+ * Used for displaying tool execution progress in a timeline-style UI.
+ * https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming
+ */
+export interface TaskUpdateChunk extends Chunk {
+  type: 'task_update';
+  id: string;
+  title: string;
+  status: 'pending' | 'in_progress' | 'complete' | 'error';
+  details?: string;
+  output?: string;
+  sources?: URLSource[];
+}
+
+/**
+ * Union type of all possible chunk types
+ */
+export type AnyChunk = MarkdownTextChunk | PlanUpdateChunk | TaskUpdateChunk;

packages/types/src/index.ts

@@ -3,6 +3,7 @@ export * from './block-kit/blocks';
 export * from './block-kit/composition-objects';
 export * from './block-kit/extensions';
 export * from './calls';
+export * from './chunk';
 export * from './dialog';
 export * from './events';
 export * from './message-attachments';

packages/web-api/package.json

@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "@slack/logger": "^4.0.0",
-    "@slack/types": "^2.18.0",
+    "@slack/types": "^2.19.0",
     "@types/node": ">=18.0.0",
     "@types/retry": "0.12.0",
     "axios": "^1.11.0",

packages/web-api/src/types/request/chat.ts

@@ -1,4 +1,5 @@
 import type {
+  AnyChunk,
   Block, // TODO: these will be combined into one in a new types release
   EntityMetadata,
   KnownBlock,
@@ -168,7 +169,13 @@ export interface Unfurls {
   unfurl_media?: boolean;
 }
 
-export interface ChatAppendStreamArguments extends TokenOverridable, ChannelAndTS, MarkdownText {}
+export interface ChatAppendStreamArguments extends TokenOverridable, ChannelAndTS, Partial<MarkdownText> {
+  /**
+   * @description An array of {@link https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming chunk objects} to append to the stream.
+   * Either `markdown_text` or `chunks` is required.
+   */
+  chunks?: AnyChunk[];
+}
 
 // https://docs.slack.dev/reference/methods/chat.delete
 export interface ChatDeleteArguments extends ChannelAndTS, AsUser, TokenOverridable {}
@@ -233,6 +240,11 @@ export type ChatScheduledMessagesListArguments = OptionalArgument<
 >;
 
 export interface ChatStartStreamArguments extends TokenOverridable, Channel, Partial<MarkdownText>, ThreadTS {
+  /**
+   * @description An array of {@link https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming chunk objects} to start the stream with.
+   * Either `markdown_text` or `chunks` is required.
+   */
+  chunks?: AnyChunk[];
   /**
    * @description The ID of the team that is associated with `recipient_user_id`.
    * This is required when starting a streaming conversation outside of a DM.
@@ -249,6 +261,10 @@ export type ChatStopStreamArguments = TokenOverridable &
   ChannelAndTS &
   Partial<MarkdownText> &
   Partial<Metadata> & {
+    /**
+     * @description An array of {@link https://docs.slack.dev/messaging/sending-and-scheduling-messages#text-streaming chunk objects} to finalize the stream with.
+     */
+    chunks?: AnyChunk[];
     /**
      * Block formatted elements will be appended to the end of the message.
      */

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

@@ -15,15 +15,10 @@ expectError(
 );
 expectError(
   web.chat.appendStream({
-    ts: '1234.56', // missing channel and markdown_text
-  }),
-);
-expectError(
-  web.chat.appendStream({
-    channel: 'C1234', // missing_markdown_text
-    ts: '1234.56',
+    ts: '1234.56', // missing channel
   }),
 );
+
 // -- happy path
 expectAssignable<Parameters<typeof web.chat.appendStream>>([
   {
@@ -32,6 +27,29 @@ expectAssignable<Parameters<typeof web.chat.appendStream>>([
     markdown_text: 'hello',
   },
 ]);
+expectAssignable<Parameters<typeof web.chat.appendStream>>([
+  {
+    channel: 'C1234',
+    ts: '1234.56',
+    chunks: [
+      {
+        type: 'markdown_text',
+        text: 'Hello world',
+      },
+      {
+        type: 'plan_update',
+        title: 'Analyzing request',
+      },
+      {
+        type: 'task_update',
+        id: 'task-1',
+        title: 'Processing request',
+        status: 'in_progress',
+        details: 'Working on it...',
+      },
+    ],
+  },
+]);
 
 // chat.delete
 // -- sad path
@@ -631,6 +649,29 @@ expectAssignable<Parameters<typeof web.chat.startStream>>([
     markdown_text: 'hello',
   },
 ]);
+expectAssignable<Parameters<typeof web.chat.startStream>>([
+  {
+    channel: 'C1234',
+    thread_ts: '1234.56',
+    chunks: [
+      {
+        type: 'markdown_text',
+        text: 'Hello world',
+      },
+      {
+        type: 'plan_update',
+        title: 'Analyzing request',
+      },
+      {
+        type: 'task_update',
+        id: 'task-1',
+        title: 'Processing request',
+        status: 'in_progress',
+        details: 'Working on it...',
+      },
+    ],
+  },
+]);
 expectAssignable<Parameters<typeof web.chat.startStream>>([
   {
     channel: 'C1234',
@@ -670,6 +711,30 @@ expectAssignable<Parameters<typeof web.chat.stopStream>>([
     blocks: [],
   },
 ]);
+expectAssignable<Parameters<typeof web.chat.stopStream>>([
+  {
+    channel: 'C1234',
+    ts: '1234.56',
+    chunks: [
+      {
+        type: 'markdown_text',
+        text: 'Hello world',
+      },
+      {
+        type: 'plan_update',
+        title: 'Analyzing request',
+      },
+      {
+        type: 'task_update',
+        id: 'task-1',
+        title: 'Processing request',
+        status: 'in_progress',
+        details: 'Working on it...',
+      },
+    ],
+    blocks: [],
+  },
+]);
 
 // chat.unfurl
 // -- sad path