feat: [CHA-375] add draft messages api (#1490)

## CLA

- [ ] I have signed the [Stream
CLA](https://docs.google.com/forms/d/e/1FAIpQLScFKsKkAJI7mhCr7K9rEIOpqIDThrWxuvxnwUq2XkHyG154vQ/viewform)
(required).
- [ ] Code changes are tested

## Description of the changes, What, Why and How?

## Changelog

- Add Draft Messages API (thanks for the types @MartinCupela)

---------

Co-authored-by: MartinCupela <32706194+MartinCupela@users.noreply.github.com>
Co-authored-by: martincupela <martin.cupela@gmail.com>

Author: shaljam

src/channel.ts

@@ -62,6 +62,9 @@ import {
   AIState,
   MessageOptions,
   PushPreference,
+  CreateDraftResponse,
+  GetDraftResponse,
+  DraftMessagePayload,
 } from './types';
 import { Role } from './permissions';
 import { DEFAULT_QUERY_CHANNEL_MESSAGE_LIST_PAGE_SIZE } from './constants';
@@ -1351,6 +1354,47 @@ export class Channel<StreamChatGenerics extends ExtendableGenerics = DefaultGene
     return await this.getClient().removePollVote(messageId, pollId, voteId);
   }
 
+  /**
+   * createDraft - Creates or updates a draft message in a channel
+   *
+   * @param {string} channelType The channel type
+   * @param {string} channelID The channel ID
+   * @param {DraftMessagePayload<StreamChatGenerics>} message The draft message to create or update
+   *
+   * @return {Promise<CreateDraftResponse<StreamChatGenerics>>} Response containing the created draft
+   */
+  async createDraft(message: DraftMessagePayload<StreamChatGenerics>) {
+    return await this.getClient().post<CreateDraftResponse<StreamChatGenerics>>(this._channelURL() + '/draft', {
+      message,
+    });
+  }
+
+  /**
+   * deleteDraft - Deletes a draft message from a channel
+   *
+   * @param {Object} options
+   * @param {string} options.parent_id Optional parent message ID for drafts in threads
+   *
+   * @return {Promise<APIResponse>} API response
+   */
+  async deleteDraft({ parent_id }: { parent_id?: string } = {}) {
+    return await this.getClient().delete<APIResponse>(this._channelURL() + '/draft', { parent_id });
+  }
+
+  /**
+   * getDraft - Retrieves a draft message from a channel
+   *
+   * @param {Object} options
+   * @param {string} options.parent_id Optional parent message ID for drafts in threads
+   *
+   * @return {Promise<GetDraftResponse<StreamChatGenerics>>} Response containing the draft
+   */
+  async getDraft({ parent_id }: { parent_id?: string } = {}) {
+    return await this.getClient().get<GetDraftResponse<StreamChatGenerics>>(this._channelURL() + '/draft', {
+      parent_id,
+    });
+  }
+
   /**
    * on - Listen to events on this channel.
    *

src/client.ts

@@ -214,6 +214,10 @@ import {
   UserResponse,
   UserSort,
   VoteSort,
+  QueryDraftsResponse,
+  DraftFilters,
+  DraftSort,
+  Pager,
 } from './types';
 import { InsightMetrics, postInsights } from './insights';
 import { Thread } from './thread';
@@ -4046,4 +4050,27 @@ export class StreamChat<StreamChatGenerics extends ExtendableGenerics = DefaultG
       ...options,
     });
   }
+
+  /**
+   * queryDrafts - Queries drafts for the current user
+   *
+   * @param {object} [options] Query options
+   * @param {object} [options.filter] Filters for the query
+   * @param {number} [options.sort] Sort parameters
+   * @param {number} [options.limit] Limit the number of results
+   * @param {string} [options.next] Pagination parameter
+   * @param {string} [options.prev] Pagination parameter
+   * @param {string} [options.user_id] Has to be provided when called server-side
+   *
+   * @return {Promise<APIResponse & { drafts: DraftResponse<StreamChatGenerics>[]; next?: string }>} Response containing the drafts
+   */
+  async queryDrafts(
+    options: Pager & {
+      filter?: DraftFilters<StreamChatGenerics>;
+      sort?: DraftSort;
+      user_id?: string;
+    } = {},
+  ) {
+    return await this.post<QueryDraftsResponse<StreamChatGenerics>>(this.baseURL + '/drafts/query', options);
+  }
 }

src/types.ts

@@ -1597,6 +1597,18 @@ export type ChannelFilters<StreamChatGenerics extends ExtendableGenerics = Defau
     }
 >;
 
+export type DraftFilters<SCG extends ExtendableGenerics = DefaultGenerics> = {
+  channel_cid?:
+    | RequireOnlyOne<Pick<QueryFilter<DraftResponse<SCG>['channel_cid']>, '$in' | '$eq'>>
+    | PrimitiveFilter<DraftResponse<SCG>['channel_cid']>;
+  created_at?:
+    | RequireOnlyOne<Pick<QueryFilter<DraftResponse<SCG>['created_at']>, '$eq' | '$gt' | '$lt' | '$gte' | '$lte'>>
+    | PrimitiveFilter<DraftResponse<SCG>['created_at']>;
+  parent_id?:
+    | RequireOnlyOne<Pick<QueryFilter<DraftResponse<SCG>['created_at']>, '$in' | '$eq' | '$exists'>>
+    | PrimitiveFilter<DraftResponse<SCG>['parent_id']>;
+};
+
 export type QueryPollsParams = {
   filter?: QueryPollsFilters;
   options?: QueryPollsOptions;
@@ -2046,6 +2058,12 @@ export type SearchMessageSort<StreamChatGenerics extends ExtendableGenerics = De
   | SearchMessageSortBase<StreamChatGenerics>
   | Array<SearchMessageSortBase<StreamChatGenerics>>;
 
+export type DraftSortBase = {
+  created_at?: AscDesc;
+};
+
+export type DraftSort = DraftSortBase | Array<DraftSortBase>;
+
 export type QuerySort<StreamChatGenerics extends ExtendableGenerics = DefaultGenerics> =
   | BannedUsersSort
   | ChannelSort<StreamChatGenerics>
@@ -3833,3 +3851,51 @@ export type SdkIdentifier = { name: 'react' | 'react-native' | 'expo' | 'angular
  * available. Is used by the react-native SDKs to enrich the user agent further.
  */
 export type DeviceIdentifier = { os: string; model?: string };
+
+export declare type DraftResponse<StreamChatGenerics extends ExtendableGenerics = DefaultGenerics> = {
+  channel_cid: string;
+  created_at: string;
+  message: DraftMessage<StreamChatGenerics>;
+  channel?: ChannelResponse<StreamChatGenerics>;
+  parent_id?: string;
+  parent_message?: MessageResponseBase<StreamChatGenerics>;
+  quoted_message?: MessageResponseBase<StreamChatGenerics>;
+};
+export declare type CreateDraftResponse<
+  StreamChatGenerics extends ExtendableGenerics = DefaultGenerics
+> = APIResponse & {
+  draft: DraftResponse<StreamChatGenerics>;
+};
+
+export declare type GetDraftResponse<StreamChatGenerics extends ExtendableGenerics = DefaultGenerics> = APIResponse & {
+  draft: DraftResponse<StreamChatGenerics>;
+};
+
+export declare type QueryDraftsResponse<
+  StreamChatGenerics extends ExtendableGenerics = DefaultGenerics
+> = APIResponse & {
+  drafts: DraftResponse<StreamChatGenerics>[];
+  next?: string;
+};
+
+export declare type DraftMessagePayload<StreamChatGenerics extends ExtendableGenerics = DefaultGenerics> = Omit<
+  DraftMessage<StreamChatGenerics>,
+  'id'
+> &
+  Partial<Pick<DraftMessage<StreamChatGenerics>, 'id'>>;
+
+export declare type DraftMessage<StreamChatGenerics extends ExtendableGenerics = DefaultGenerics> = {
+  id: string;
+  text: string;
+  attachments?: Attachment<StreamChatGenerics>[];
+  custom?: {};
+  html?: string;
+  mentioned_users?: string[];
+  mml?: string;
+  parent_id?: string;
+  poll_id?: string;
+  quoted_message_id?: string;
+  show_in_channel?: boolean;
+  silent?: boolean;
+  type?: MessageLabel;
+};

test/unit/draft.test.js

@@ -0,0 +1,136 @@
+import { expect } from 'chai';
+import sinon from 'sinon';
+import { StreamChat } from '../../src';
+import { generateChannel } from './test-utils/generateChannel';
+import { v4 as uuidv4 } from 'uuid';
+
+describe('Draft Messages', () => {
+	let client;
+	let channel;
+	const apiKey = 'test-api-key';
+	const channelType = 'messaging';
+	const channelID = 'test-channel';
+	const userID = 'test-user';
+	const parentID = 'parent-message-id';
+
+	const draftMessage = {
+		text: 'Draft message text',
+		attachments: [{ type: 'image', url: 'https://example.com/image.jpg' }],
+		mentioned_users: ['user1', 'user2'],
+	};
+
+	const draftWithParent = {
+		text: 'Draft message text',
+		attachments: [{ type: 'image', url: 'https://example.com/image.jpg' }],
+		mentioned_users: ['user1', 'user2'],
+		parent_id: parentID,
+	};
+
+	const draftResponse = {
+		draft: {
+			channel_cid: `${channelType}:${channelID}`,
+			created_at: '2023-01-01T00:00:00Z',
+			message: {
+				id: 'draft-id',
+				...draftMessage,
+			},
+			parent_id: parentID,
+		},
+	};
+
+	beforeEach(() => {
+		client = new StreamChat(apiKey);
+		client.userID = userID;
+		let channelResponse = generateChannel({
+			channel: { id: channelID, name: 'Test channel', members: [] },
+		}).channel;
+		channel = client.channel(channelResponse.type, channelResponse.id);
+
+		// Mock the methods
+		sinon.stub(client, 'queryDrafts').resolves(draftResponse);
+		sinon.stub(channel, 'createDraft').resolves(draftResponse);
+		sinon.stub(channel, 'getDraft').resolves(draftResponse);
+		sinon.stub(channel, 'deleteDraft').resolves({ duration: '0.01ms' });
+	});
+
+	afterEach(() => {
+		sinon.restore();
+	});
+
+	it('should create a draft message', async () => {
+		const response = await channel.createDraft(draftMessage);
+
+		expect(channel.createDraft.calledOnce).to.be.true;
+		expect(channel.createDraft.firstCall.args[0]).to.deep.equal(draftMessage);
+		expect(response).to.deep.equal(draftResponse);
+	});
+
+	it('should create a draft message with parent ID', async () => {
+		const response = await channel.createDraft(draftWithParent);
+
+		expect(channel.createDraft.calledOnce).to.be.true;
+		expect(channel.createDraft.firstCall.args[0]).to.deep.equal(draftWithParent);
+		expect(response).to.deep.equal(draftResponse);
+	});
+
+	it('should get a draft message', async () => {
+		const response = await channel.getDraft(parentID);
+
+		expect(channel.getDraft.calledOnce).to.be.true;
+		expect(channel.getDraft.firstCall.args[0]).to.deep.equal(parentID);
+		expect(response).to.deep.equal(draftResponse);
+	});
+
+	it('should get a draft message with parent ID', async () => {
+		const response = await channel.getDraft(parentID);
+
+		expect(channel.getDraft.calledOnce).to.be.true;
+		expect(channel.getDraft.firstCall.args[0]).to.deep.equal(parentID);
+		expect(response).to.deep.equal(draftResponse);
+	});
+
+	it('should delete a draft message', async () => {
+		await channel.deleteDraft();
+
+		expect(channel.deleteDraft.calledOnce).to.be.true;
+		expect(channel.deleteDraft.firstCall.args[0]).to.be.undefined;
+	});
+
+	it('should delete a draft message with parent ID', async () => {
+		await channel.deleteDraft(parentID);
+
+		expect(channel.deleteDraft.calledOnce).to.be.true;
+		expect(channel.deleteDraft.firstCall.args[0]).to.deep.equal(parentID);
+	});
+
+	it('should query drafts', async () => {
+		const queryOptions = {
+			filter: { created_at: { $gt: '2023-01-01T00:00:00Z' } },
+			limit: 10,
+		};
+
+		const queryResponse = {
+			drafts: [draftResponse.draft, { ...draftResponse.draft, channel_cid: 'messaging:other-channel' }],
+			next: 'next-page-token',
+		};
+		client.queryDrafts.resolves(queryResponse);
+
+		const response = await client.queryDrafts(queryOptions);
+
+		expect(client.queryDrafts.calledOnce).to.be.true;
+		expect(client.queryDrafts.firstCall.args[0]).to.deep.equal(queryOptions);
+		expect(response).to.deep.equal(queryResponse);
+	});
+
+	it('should query drafts with default options', async () => {
+		const queryResponse = {
+			drafts: [draftResponse.draft],
+		};
+		client.queryDrafts.resolves(queryResponse);
+
+		const response = await client.queryDrafts();
+		expect(client.queryDrafts.calledOnce).to.be.true;
+		expect(client.queryDrafts.firstCall.args[0]).to.be.undefined;
+		expect(response).to.deep.equal(queryResponse);
+	});
+});