Implement message append, protocol v5 with publish/update return values, and update/delete over realtime

ably.d.ts

@@ -1467,6 +1467,11 @@ export interface BatchPublishSuccessResult {
    * A unique ID prefixed to the {@link Message.id} of each published message.
    */
   messageId: string;
+  /**
+   * An array of message serials corresponding 1:1 to the messages that were published.
+   * A serial may be null if the message was discarded due to a configured conflation rule.
+   */
+  serials: (string | null)[];
 }
 
 /**
@@ -2317,26 +2322,26 @@ export declare interface Channel {
    *
    * @param messages - An array of {@link Message} objects.
    * @param options - Optional parameters, such as [`quickAck`](https://faqs.ably.com/why-are-some-rest-publishes-on-a-channel-slow-and-then-typically-faster-on-subsequent-publishes) sent as part of the query string.
-   * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @returns A promise which, upon success, will be fulfilled with a {@link PublishResult} object containing the serials of the published messages. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
    */
-  publish(messages: Message[], options?: PublishOptions): Promise<void>;
+  publish(messages: Message[], options?: PublishOptions): Promise<PublishResult>;
   /**
    * Publishes a message to the channel.
    *
    * @param message - A {@link Message} object.
    * @param options - Optional parameters, such as [`quickAck`](https://faqs.ably.com/why-are-some-rest-publishes-on-a-channel-slow-and-then-typically-faster-on-subsequent-publishes) sent as part of the query string.
-   * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @returns A promise which, upon success, will be fulfilled with a {@link PublishResult} object containing the serial of the published message. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
    */
-  publish(message: Message, options?: PublishOptions): Promise<void>;
+  publish(message: Message, options?: PublishOptions): Promise<PublishResult>;
   /**
    * Publishes a single message to the channel with the given event name and payload.
    *
    * @param name - The name of the message.
    * @param data - The payload of the message.
    * @param options - Optional parameters, such as [`quickAck`](https://faqs.ably.com/why-are-some-rest-publishes-on-a-channel-slow-and-then-typically-faster-on-subsequent-publishes) sent as part of the query string.
-   * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @returns A promise which, upon success, will be fulfilled with a {@link PublishResult} object containing the serial of the published message. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
    */
-  publish(name: string, data: any, options?: PublishOptions): Promise<void>;
+  publish(name: string, data: any, options?: PublishOptions): Promise<PublishResult>;
   /**
    * Retrieves a {@link ChannelDetails} object for the channel, which includes status and occupancy metrics.
    *
@@ -2355,19 +2360,28 @@ export declare interface Channel {
    *
    * @param message - A {@link Message} object containing a populated `serial` field and the fields to update.
    * @param operation - An optional {@link MessageOperation} object containing metadata about the update operation.
-   * @param params - Optional parameters sent as part of the query string.
-   * @returns A promise which on success will be fulfilled, and on failure, rejected with an {@link ErrorInfo} object which explains the error.
+   * @param options - Optional parameters to modify how the publish is made.
+   * @returns A promise which, upon success, will be fulfilled with an {@link UpdateDeleteResult} object containing the serial of the new version of the message. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
    */
-  updateMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<void>;
+  updateMessage(message: Message, operation?: MessageOperation, options?: PublishOptions): Promise<UpdateDeleteResult>;
   /**
    * Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses patch semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged (meaning that if you for example want the `MESSAGE_DELETE` to have an empty data, you should explicitly set the `data` to an empty object).
    *
    * @param message - A {@link Message} object containing a populated `serial` field.
    * @param operation - An optional {@link MessageOperation} object containing metadata about the delete operation.
-   * @param params - Optional parameters sent as part of the query string.
-   * @returns A promise which on success will be fulfilled, and on failure, rejected with an {@link ErrorInfo} object which explains the error.
+   * @param options - Optional parameters to modify how the publish is made.
+   * @returns A promise which, upon success, will be fulfilled with an {@link UpdateDeleteResult} object containing the serial of the new version of the message. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
    */
-  deleteMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<void>;
+  deleteMessage(message: Message, operation?: MessageOperation, options?: PublishOptions): Promise<UpdateDeleteResult>;
+  /**
+   * Appends data to an existing message. The supplied `data` field is appended to the previous message's data, while all other fields (`name`, `extras`) replace the previous values if provided.
+   *
+   * @param message - A {@link Message} object containing a populated `serial` field and the data to append.
+   * @param operation - An optional {@link MessageOperation} object containing metadata about the append operation.
+   * @param options - Optional parameters to modify how the publish is made.
+   * @returns A promise which, upon success, will be fulfilled with an {@link UpdateDeleteResult} object containing the serial of the new version of the message. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
+   */
+  appendMessage(message: Message, operation?: MessageOperation, options?: PublishOptions): Promise<UpdateDeleteResult>;
   /**
    * Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations.
    *
@@ -2564,23 +2578,26 @@ export declare interface RealtimeChannel extends EventEmitter<channelEventCallba
    *
    * @param name - The event name.
    * @param data - The message payload.
-   * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @param options - Optional parameters sent as part of the protocol message.
+   * @returns A promise which, upon success, will be fulfilled with a {@link PublishResult} object containing the serial of the published message. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
    */
-  publish(name: string, data: any): Promise<void>;
+  publish(name: string, data: any, options?: PublishOptions): Promise<PublishResult>;
   /**
    * Publishes an array of messages to the channel. When publish is called with this client library, it won't attempt to implicitly attach to the channel.
    *
    * @param messages - An array of {@link Message} objects.
-   * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @param options - Optional parameters sent as part of the protocol message.
+   * @returns A promise which, upon success, will be fulfilled with a {@link PublishResult} object containing the serials of the published messages. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
    */
-  publish(messages: Message[]): Promise<void>;
+  publish(messages: Message[], options?: PublishOptions): Promise<PublishResult>;
   /**
    * Publish a message to the channel. When publish is called with this client library, it won't attempt to implicitly attach to the channel.
    *
    * @param message - A {@link Message} object.
-   * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @param options - Optional parameters sent as part of the protocol message.
+   * @returns A promise which, upon success, will be fulfilled with a {@link PublishResult} object containing the serial of the published message. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
    */
-  publish(message: Message): Promise<void>;
+  publish(message: Message, options?: PublishOptions): Promise<PublishResult>;
   /**
    * If the channel is already in the given state, returns a promise which immediately resolves to `null`. Else, calls {@link EventEmitter.once | `once()`} to return a promise which resolves the next time the channel transitions to the given state.
    *
@@ -2599,19 +2616,28 @@ export declare interface RealtimeChannel extends EventEmitter<channelEventCallba
    *
    * @param message - A {@link Message} object containing a populated `serial` field and the fields to update.
    * @param operation - An optional {@link MessageOperation} object containing metadata about the update operation.
-   * @param params - Optional parameters sent as part of the query string.
-   * @returns A promise which on success will be fulfilled, and on failure, rejected with an {@link ErrorInfo} object which explains the error.
+   * @param options - Optional parameters to modify how the publish is made.
+   * @returns A promise which, upon success, will be fulfilled with an {@link UpdateDeleteResult} object containing the serial of the new version of the message. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
    */
-  updateMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<void>;
+  updateMessage(message: Message, operation?: MessageOperation, options?: PublishOptions): Promise<UpdateDeleteResult>;
   /**
    * Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses patch semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged (meaning that if you for example want the `MESSAGE_DELETE` to have an empty data, you should explicitly set the `data` to an empty object).
    *
    * @param message - A {@link Message} object containing a populated `serial` field.
    * @param operation - An optional {@link MessageOperation} object containing metadata about the delete operation.
-   * @param params - Optional parameters sent as part of the query string.
-   * @returns A promise which on success will be fulfilled, and on failure, rejected with an {@link ErrorInfo} object which explains the error.
+   * @param options - Optional parameters to modify how the publish is made.
+   * @returns A promise which, upon success, will be fulfilled with an {@link UpdateDeleteResult} object containing the serial of the new version of the message. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
+   */
+  deleteMessage(message: Message, operation?: MessageOperation, options?: PublishOptions): Promise<UpdateDeleteResult>;
+  /**
+   * Appends data to an existing message. The supplied `data` field is appended to the previous message's data, while all other fields (`name`, `extras`) replace the previous values if provided.
+   *
+   * @param message - A {@link Message} object containing a populated `serial` field and the data to append.
+   * @param operation - An optional {@link MessageOperation} object containing metadata about the append operation.
+   * @param options - Optional parameters to modify how the publish is made.
+   * @returns A promise which, upon success, will be fulfilled with an {@link UpdateDeleteResult} object containing the serial of the new version of the message. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
    */
-  deleteMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<void>;
+  appendMessage(message: Message, operation?: MessageOperation, options?: PublishOptions): Promise<UpdateDeleteResult>;
   /**
    * Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations.
    *
@@ -2630,12 +2656,7 @@ export declare interface RealtimeChannel extends EventEmitter<channelEventCallba
  */
 export type PublishOptions = {
   /**
-   * See [here](https://faqs.ably.com/why-are-some-rest-publishes-on-a-channel-slow-and-then-typically-faster-on-subsequent-publishes).
-   */
-  quickAck?: boolean;
-  /**
-   * Support any publish options that may be added serverside without needing
-   * typings changes.
+   * Publish options are server-defined
    */
   [k: string]: string | number | boolean | undefined;
 };
@@ -2973,6 +2994,28 @@ export interface MessageOperation {
   metadata?: Record<string, string>;
 }
 
+/**
+ * Contains the result of a publish operation.
+ */
+export interface PublishResult {
+  /**
+   * An array of message serials corresponding 1:1 to the messages that were published.
+   * A serial may be null if the message was discarded due to a configured conflation rule.
+   */
+  serials: (string | null)[];
+}
+
+/**
+ * Contains the result of an update or delete message operation.
+ */
+export interface UpdateDeleteResult {
+  /**
+   * The serial of the new version of the updated or deleted message.
+   * Will be null if the message was superseded by a subsequent update before it could be published.
+   */
+  versionSerial: string | null;
+}
+
 /**
  * The namespace containing the different types of message actions.
  */
@@ -3003,6 +3046,12 @@ declare namespace MessageActions {
    * the message.serial is the serial of the message for which this is a summary.
    */
   type MESSAGE_SUMMARY = 'message.summary';
+  /**
+   * Message action for an appended message. The `serial` field identifies the message to which
+   * data is being appended. The `data` field is appended to the previous message's data, while
+   * all other fields replace the previous values.
+   */
+  type MESSAGE_APPEND = 'message.append';
 }
 
 /**
@@ -3013,7 +3062,8 @@ export type MessageAction =
   | MessageActions.MESSAGE_UPDATE
   | MessageActions.MESSAGE_DELETE
   | MessageActions.META
-  | MessageActions.MESSAGE_SUMMARY;
+  | MessageActions.MESSAGE_SUMMARY
+  | MessageActions.MESSAGE_APPEND;
 
 /**
  * The namespace containing the different types of annotation actions.

src/common/lib/client/realtimeannotations.ts

@@ -45,12 +45,12 @@ class RealtimeAnnotations {
       channel: channelName,
       annotations: [wireAnnotation],
     });
-    return this.channel.sendMessage(pm);
+    await this.channel.sendMessage(pm);
   }
 
   async delete(msgOrSerial: string | Message, annotationValues: Partial<Properties<Annotation>>): Promise<void> {
     annotationValues.action = 'annotation.delete';
-    return this.publish(msgOrSerial, annotationValues);
+    await this.publish(msgOrSerial, annotationValues);
   }
 
   async subscribe(..._args: unknown[] /* [type], listener */): Promise<void> {