feat(web-api): expose public ts property on ChatStream (#2611)

Co-authored-by: William Bergamin <wbergamin@salesforce.com>

Author: srtaalej

.changeset/expose-ts-on-chat-streamer.md

@@ -0,0 +1,24 @@
+---
+"@slack/web-api": minor
+---
+
+feat: expose public read-only `ts` getter on `ChatStreamer` for fallback to [`chat.update`](https://docs.slack.dev/reference/methods/chat.update) when a stream expires server-side
+
+```js
+import { WebClient } from "@slack/web-api";
+
+const client = new WebClient(process.env.SLACK_BOT_TOKEN);
+
+const streamer = client.chatStream({
+  channel: "C0123456789",
+  thread_ts: "1700000001.123456",
+  recipient_team_id: "T0123456789",
+  recipient_user_id: "U0123456789",
+});
+
+await streamer.append({ markdown_text: "hello!" });
+// streamer.ts is now set after the first flush
+console.log(streamer.ts);
+
+await streamer.stop();
+```

packages/web-api/src/WebClient.test.ts

@@ -1295,6 +1295,34 @@ describe('WebClient', () => {
       scope.done();
     });
 
+    it('ts is undefined before flush and set after', async () => {
+      const scope = nock('https://slack.com')
+        .post('/api/chat.startStream')
+        .reply(200, {
+          ok: true,
+          ts: '123.123',
+        })
+        .post('/api/chat.stopStream')
+        .reply(200, {
+          ok: true,
+        });
+      const streamer = client.chatStream({
+        buffer_size: 5,
+        channel: 'C0123456789',
+        thread_ts: '123.000',
+        recipient_team_id: 'T0123456789',
+        recipient_user_id: 'U0123456789',
+      });
+      assert.strictEqual(streamer.ts, undefined);
+
+      await streamer.append({ markdown_text: 'hello!' });
+      assert.strictEqual(streamer.ts, '123.123');
+
+      await streamer.stop();
+      assert.strictEqual(streamer.ts, '123.123');
+      scope.done();
+    });
+
     it('streams a long message', async () => {
       const contextActionsBlock: ContextActionsBlock = {
         type: 'context_actions',

packages/web-api/src/chat-stream.ts

@@ -54,6 +54,15 @@ export class ChatStreamer {
     this.streamArgs = args;
   }
 
+  /**
+   * @description The message timestamp of the stream. Returns `undefined` until the first flush
+   * (when `chat.startStream` is called).
+   * @see {@link https://docs.slack.dev/reference/methods/chat.update}
+   */
+  get ts(): string | undefined {
+    return this.streamTs;
+  }
+
   /**
    * Append to the stream.
    *