Remove hard delete, update ably and smaller refactors

- Deletion response now returns the clientId of the deleter.
- Deletes will soon be idempotent and will return the clientId associated with the delete (not necessarily the user).
- Update docs to remove mention of hard deletes.
- Remove old ably-js tgz and update message-parser.test.ts

- Move DetailsMetadata type to its own file.
- Refactored message deletion to use map for message actions to events.
- Fixed typos and improved logging for message operations.
- Updated isDeleted and isUpdated to getters.
- Fix tests

README.md

@@ -281,14 +281,12 @@ You can supply optional parameters to the `delete` method to provide additional
 These additional parameters are:
 * `description`: a string that can be used to inform others as to why the message was deleted.
 * `metadata`: a map of extra information that can be attached to the deletion message.
-* `hard`: a boolean that determines whether the message should be hard deleted or not. If `hard` is set to `true`, the message will be permanently deleted and will not be recoverable.
 
 The return of this call will be the deleted message, as it would appear to other subscribers of the room.
-
-By default, the `hard` parameter is set to `false`.
+This is a _soft delete_ and the message will still be available in the history, but with the `deletedAt` property set.
 
 ```ts
-const deletedMessage = await room.messages.delete(message);
+const deletedMessage = await room.messages.delete(message, { description: 'This message was deleted for ...' });
 ```
 
 ### Subscribing to incoming messages

demo/src/containers/Chat/Chat.tsx

@@ -13,7 +13,6 @@ import {
   Reaction,
 } from '@ably/chat';
 
-
 export const Chat = () => {
   const chatClient = useChatClient();
   const clientId = chatClient.clientId;
@@ -74,7 +73,7 @@ export const Chat = () => {
         .then((result: PaginatedResult<Message>) => {
           // reverse the messages so they are displayed in the correct order
           // and don't include deleted messages
-          setMessages(result.items.filter((m) => !m.isDeleted()).reverse());
+          setMessages(result.items.filter((m) => !m.isDeleted).reverse());
           setLoading(false);
         })
         .catch((error: unknown) => {

src/core/chat-api.ts

@@ -39,7 +39,6 @@ interface SendMessageParams {
 }
 
 interface DeleteMessageParams {
-  hard?: boolean;
   description?: string;
   metadata?: MessageDetailsMetadata;
 }
@@ -49,6 +48,11 @@ export interface DeleteMessageResponse {
    * The timestamp of when the deletion occurred.
    */
   deletedAt: number;
+
+  /**
+   * The clientId of the user who deleted the message.
+   */
+  clientId?: string;
 }
 
 /**
@@ -95,12 +99,11 @@ export class ChatApi {
     params?: DeleteMessageParams,
   ): Promise<DeleteMessageResponse> {
     const body: MessageDetails = { description: params?.description, metadata: params?.metadata };
-    const restParams = params?.hard ? { hard: true } : { hard: false };
     return this._makeAuthorizedRequest<DeleteMessageResponse>(
-      `/chat/v1/rooms/${roomId}/messages/${timeserial}/delete`,
+      `/chat/v2/rooms/${roomId}/messages/${timeserial}/delete`,
       'POST',
       body,
-      restParams,
+      {},
     );
   }
 

src/core/details-metadata.ts

@@ -0,0 +1,10 @@
+/**
+ * The type for metadata contained in the details field of a new chat message.
+ * This is a key-value pair where the key is a string, and the value is a string, it represents the metadata supplied
+ * to a message update or deletion request.
+ *
+ * Do not use metadata for authoritative information. There is no server-side
+ * validation. When reading the metadata, treat it like user input.
+ *
+ */
+export type DetailsMetadata = Record<string, string>;

src/core/index.ts

@@ -12,6 +12,7 @@ export type {
   OnConnectionStatusChangeResponse,
 } from './connection-status.js';
 export { ConnectionLifecycle } from './connection-status.js';
+export type { DetailsMetadata } from './details-metadata.js';
 export type { DiscontinuityListener, OnDiscontinuitySubscriptionResponse } from './discontinuity.js';
 export { ErrorCodes, errorInfoIs } from './errors.js';
 export { MessageEvents, PresenceEvents } from './events.js';
@@ -37,7 +38,7 @@ export type {
   QueryOptions,
   SendMessageParams,
 } from './messages.js';
-export type { DetailsMetadata, Metadata } from './metadata.js';
+export type { Metadata } from './metadata.js';
 export type { Occupancy, OccupancyEvent, OccupancyListener, OccupancySubscriptionResponse } from './occupancy.js';
 export type {
   Presence,

src/core/message.ts

@@ -1,5 +1,6 @@
+import { DetailsMetadata } from './details-metadata.js';
 import { Headers } from './headers.js';
-import { DetailsMetadata, Metadata } from './metadata.js';
+import { Metadata } from './metadata.js';
 import { DefaultTimeserial, Timeserial } from './timeserial.js';
 
 /**
@@ -132,13 +133,13 @@ export interface Message {
    * Determines if this message has been deleted.
    * @returns true if the message has been deleted.
    */
-  isDeleted(): boolean;
+  get isDeleted(): boolean;
 
   /**
    * Determines if this message has been updated.
    * @returns true if the message has been updated.
    */
-  isUpdated(): boolean;
+  get isUpdated(): boolean;
 
   /**
    * Determines if this message was created before the given message. This comparison is based on
@@ -198,11 +199,11 @@ export class DefaultMessage implements Message {
     Object.freeze(this);
   }
 
-  isDeleted(): boolean {
+  get isDeleted(): boolean {
     return this.deletedAt !== undefined;
   }
 
-  isUpdated(): boolean {
+  get isUpdated(): boolean {
     return this.updatedAt !== undefined;
   }
 

src/core/messages.ts

@@ -2,6 +2,7 @@ import * as Ably from 'ably';
 
 import { getChannel, messagesChannelName } from './channel.js';
 import { ChatApi } from './chat-api.js';
+import { DetailsMetadata } from './details-metadata.js';
 import {
   DiscontinuityEmitter,
   DiscontinuityListener,
@@ -13,7 +14,7 @@ import {
 import { ErrorCodes } from './errors.js';
 import { ChatMessageActions, MessageEvents, RealtimeMessageTypes } from './events.js';
 import { Logger } from './logger.js';
-import { DefaultMessage, Message, MessageDetailsMetadata, MessageHeaders, MessageMetadata } from './message.js';
+import { DefaultMessage, Message, MessageHeaders, MessageMetadata } from './message.js';
 import { parseMessage } from './message-parser.js';
 import { PaginatedResult } from './query.js';
 import { addListenerToChannelWithoutAttach } from './realtime-extensions.js';
@@ -30,6 +31,15 @@ interface MessageEventsMap {
   [MessageEvents.Deleted]: MessageEventPayload;
 }
 
+/**
+ * Mapping of chat message actions to message events.
+ */
+const MessageActionsToEventsMap: Map<ChatMessageActions, MessageEvents> = new Map<ChatMessageActions, MessageEvents>([
+  [ChatMessageActions.MessageCreate, MessageEvents.Created],
+  [ChatMessageActions.MessageUpdate, MessageEvents.Updated],
+  [ChatMessageActions.MessageDelete, MessageEvents.Deleted],
+]);
+
 /**
  * Options for querying messages in a chat room.
  */
@@ -72,23 +82,16 @@ export interface QueryOptions {
  * The parameters supplied to delete a message.
  */
 export interface DeleteMessageParams {
-  /**
-   * The optional method to use for deleting messages. Defaults to 'soft' if not provided.
-   * `soft` will mark the message as deleted but keep it in the history, while `hard` will
-   * permanently delete the message from persistent storage.
-   */
-  hard?: boolean;
-
   /**
    * The optional description for deleting messages.
    */
   description?: string;
 
   /**
-   * The {@link MessageDetailsMetadata} that will be added to the deletion request. Defaults to empty.
+   * The {@link DetailsMetadata} that will be added to the deletion request. Defaults to empty.
    *
    */
-  metadata?: MessageDetailsMetadata;
+  metadata?: DetailsMetadata;
 }
 
 /**
@@ -217,6 +220,7 @@ export interface Messages extends EmitsDiscontinuities {
    * Delete a message in the chat room.
    *
    * This method uses the Ably Chat API REST endpoint for deleting messages.
+   * It performs a `soft` delete, meaning the message is marked as deleted.
    *
    * Note that the Promise may resolve before OR after the message is deleted
    * from the realtime channel. This means you may see the message that was just
@@ -477,7 +481,7 @@ export class DefaultMessages
    * @throws {@link ErrorInfo} if headers defines any headers prefixed with reserved words.
    */
   async send(params: SendMessageParams): Promise<Message> {
-    this._logger.trace('Messages.send();');
+    this._logger.trace('Messages.send();', { params });
 
     const { text, metadata, headers } = params;
 
@@ -496,9 +500,9 @@ export class DefaultMessages
   /**
    * @inheritdoc Messages
    */
-  async delete(message: Message, deleteMessageParams?: DeleteMessageParams): Promise<Message> {
-    this._logger.trace('Messages.delete();');
-    const response = await this._chatApi.deleteMessage(this._roomId, message.timeserial, deleteMessageParams);
+  async delete(message: Message, params?: DeleteMessageParams): Promise<Message> {
+    this._logger.trace('Messages.delete();', { params });
+    const response = await this._chatApi.deleteMessage(this._roomId, message.timeserial, params);
     const deletedMessage: Message = new DefaultMessage(
       message.timeserial,
       message.clientId,
@@ -508,16 +512,16 @@ export class DefaultMessages
       message.metadata,
       message.headers,
       new Date(response.deletedAt),
-      this._clientId,
+      response.clientId,
       {
-        description: deleteMessageParams?.description,
-        metadata: deleteMessageParams?.metadata,
+        description: params?.description,
+        metadata: params?.metadata,
       },
       message.updatedAt,
       message.updatedBy,
       message.updateDetail,
     );
-    this._logger.debug('Messages.delete(); message deleted successfully', { message });
+    this._logger.debug('Messages.delete(); message deleted successfully', { deletedMessage });
     return deletedMessage;
   }
 
@@ -561,30 +565,12 @@ export class DefaultMessages
     this._listenerSubscriptionPoints.clear();
   }
 
-  // This function is used to convert the message action from Ably to the chat MessageEvents.
-  private _messageActionToMessageEvent(action: ChatMessageActions): MessageEvents | undefined {
-    switch (action) {
-      case ChatMessageActions.MessageCreate: {
-        return MessageEvents.Created;
-      }
-      case ChatMessageActions.MessageUpdate: {
-        return MessageEvents.Updated;
-      }
-      case ChatMessageActions.MessageDelete: {
-        return MessageEvents.Deleted;
-      }
-      default: {
-        return undefined;
-      }
-    }
-  }
-
   private _processEvent(channelEventMessage: Ably.InboundMessage) {
     this._logger.trace('Messages._processEvent();', {
       channelEventMessage,
     });
     const { action } = channelEventMessage;
-    const event = this._messageActionToMessageEvent(action as ChatMessageActions);
+    const event = MessageActionsToEventsMap.get(action as ChatMessageActions);
     if (!event) {
       this._logger.debug('Messages._processEvent(); received unknown message action', { action });
       return;

src/core/metadata.ts

@@ -10,14 +10,3 @@
  *
  */
 export type Metadata = Record<string, unknown>;
-
-/**
- * The type for metadata contained in the details fields of a chat message.
- * This is a key-value pair where the key is a string, and the value is a string, it represents the metadata supplied
- * to a message update or deletion request.
- *
- * Do not use metadata for authoritative information. There is no server-side
- * validation. When reading the metadata, treat it like user input.
- *
- */
-export type DetailsMetadata = Record<string, string>;

src/react/README.md

@@ -187,7 +187,7 @@ This hook allows you to access the `Messages` instance of a `Room` from your Rea
 ### Sending, Deleting And Getting Messages
 
 The hook will provide the `Messages` instance, should you wish to interact with it directly, a `send` method
-that can be used to send a messages to the room,
+that can be used to send a message to the room,
 a `deleteMessage` method that can be used to delete a message from the room,
 and a `get` method that can be used to retrieve messages from the room.
 
@@ -197,7 +197,7 @@ import { Message } from '@ably/chat';
 
 const MyComponent = () => {
   const { send, get, deleteMessage } = useMessages();
-
+  const [message, setMessage] = useState<Message>;
   const handleGetMessages = () => {
     // fetch the last 3 messages, oldest to newest
     get({ limit: 3, direction: 'forwards' }).then((result) => console.log('Previous messages: ', result.items));
@@ -208,14 +208,14 @@ const MyComponent = () => {
   };
 
   const handleDeleteMessage = (message: Message) => {
-    deleteMessage(message, { description: 'deleted by user', hard: false });
+    deleteMessage(message, { description: 'deleted by user' });
   };
 
   return (
     <div>
       <button onClick={handleMessageSend}>Send Message</button>
       <button onClick={handleGetMessages}>Get Messages</button>
-      <button onClick={handleDeleteMessage}>Delete Message</button>
+      <button onClick={handleDeleteMessage(message)}>Delete Message</button>
     </div>
   );
 };

test/core/message-parser.test.ts

@@ -147,7 +147,7 @@ describe('parseMessage', () => {
         timestamp: 1234567890,
         extras: {},
         serial: 'cbfkKvEYgBhDaZ38195418@1728402074206-0:0',
-        action: 'MESSAGE_UPDATE',
+        action: ChatMessageActions.MessageUpdate,
       },
       expectedError: 'received incoming update message without updatedAt',
     },
@@ -160,7 +160,7 @@ describe('parseMessage', () => {
         timestamp: 1234567890,
         extras: {},
         serial: 'cbfkKvEYgBhDaZ38195418@1728402074206-0:0',
-        action: 'MESSAGE_DELETE',
+        action: ChatMessageActions.MessageDelete,
       },
       expectedError: 'received incoming deletion message without deletedAt',
     },

test/core/message.test.ts

@@ -120,7 +120,7 @@ describe('ChatMessage', () => {
       new Date(1672531200000),
     );
 
-    expect(firstMessage.isDeleted()).toBe(true);
+    expect(firstMessage.isDeleted).toBe(true);
   });
 
   it('is updated', () => {
@@ -140,7 +140,7 @@ describe('ChatMessage', () => {
       new Date(1672531200000),
     );
 
-    expect(firstMessage.isUpdated()).toBe(true);
+    expect(firstMessage.isUpdated).toBe(true);
   });
 
   it('throws an error with an invalid timeserial', () => {

test/core/messages.integration.test.ts

@@ -112,7 +112,6 @@ describe('messages integration', () => {
     const deletedMessage1 = await room.messages.delete(message1, {
       description: 'Deleted message',
       metadata: { key: 'value' },
-      hard: false,
     });
 
     // Wait up to 5 seconds for the promises to resolve
@@ -175,7 +174,8 @@ describe('messages integration', () => {
     expect(history.hasNext()).toBe(false);
   });
 
-  it<TestContext>('should be able to retrieve chat deletion in history', async (context) => {
+  // At the moment, the history API does not materialize deleted messages in the history.
+  it.skip<TestContext>('should be able to retrieve chat deletion in history', async (context) => {
     const { chat } = context;
 
     const room = getRandomRoom(chat);
@@ -187,7 +187,7 @@ describe('messages integration', () => {
     const deletedMessage1 = await room.messages.delete(message1, { description: 'Deleted message' });
 
     // Do a history request to get the deleted message
-    const history = await room.messages.get({ limit: 1, direction: 'forwards' });
+    const history = await room.messages.get({ limit: 3, direction: 'forwards' });
 
     expect(history.items).toEqual([
       expect.objectContaining({