From bf0ffeb082381ec20758a3ede4cfb95c7f6c31b9 Mon Sep 17 00:00:00 2001
From: Andrew Bulat <andrii.bulat@gmail.com>
Date: Tue, 19 Nov 2024 03:18:28 +0000
Subject: [PATCH] Add LiveObjects access and subscription public API to the
 `ably.d.ts`

This is needed to enable LiveObjects plugin package tests and TypeScript
checks.
---
 ably.d.ts | 112 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 111 insertions(+), 1 deletion(-)

diff --git a/ably.d.ts b/ably.d.ts
index 2f3dd499a..2c8307158 100644
--- a/ably.d.ts
+++ b/ably.d.ts
@@ -2028,7 +2028,117 @@ export declare interface PushChannel {
 /**
  * Enables the LiveObjects state to be subscribed to for a channel.
  */
-export declare interface LiveObjects {}
+export declare interface LiveObjects {
+  /**
+   * Retrieves the root {@link LiveMap} object for state on a channel.
+   *
+   * @returns A promise which, upon success, will be fulfilled with a {@link LiveMap} object. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
+   */
+  getRoot(): Promise<LiveMap>;
+}
+
+/**
+ * The `LiveMap` class represents a synchronized key/value storage, similar to a JavaScript Map, where all changes are synchronized across clients in realtime.
+ * Conflict-free resolution for updates follows Last Write Wins (LWW) semantics, meaning that if two clients update the same key in the map, the last change wins.
+ *
+ * Keys must be strings. Values can be another Live Object, or a primitive type, such as a string, number, boolean, or binary data (see {@link StateValue}).
+ */
+export declare interface LiveMap extends LiveObject<LiveMapUpdate> {
+  /**
+   * Returns the value associated with a given key. Returns `undefined` if the key doesn't exist in a map.
+   *
+   * @param key - The key to retrieve the value for.
+   * @returns A {@link LiveObject}, a primitive type (string, number, boolean, or binary data) or `undefined` if the key doesn't exist in a map.
+   */
+  get(key: string): LiveObject | StateValue | undefined;
+
+  /**
+   * Returns the number of key/value pairs in the map.
+   */
+  size(): number;
+}
+
+/**
+ * Represents an update to a {@link LiveMap} object, describing the keys that were updated or removed.
+ */
+export declare interface LiveMapUpdate extends LiveObjectUpdate {
+  /**
+   * An object containing keys from a `LiveMap` that have changed, along with their change status:
+   * - `updated` - the value of a key in the map was updated.
+   * - `removed` - the key was removed from the map.
+   */
+  update: { [keyName: string]: 'updated' | 'removed' };
+}
+
+/**
+ * Represents a primitive value that can be stored in a {@link LiveMap}.
+ */
+export type StateValue = string | number | boolean | Buffer | Uint8Array;
+
+/**
+ * The `LiveCounter` class represents a synchronized counter that can be incremented or decremented and is synchronized across clients in realtime.
+ */
+export declare interface LiveCounter extends LiveObject<LiveCounterUpdate> {
+  /**
+   * Returns the current value of the counter.
+   */
+  value(): number;
+}
+
+/**
+ * Represents an update to a {@link LiveCounter} object, describing the change to the underlying value.
+ */
+export declare interface LiveCounterUpdate extends LiveObjectUpdate {
+  /**
+   * Describes the numerical change to the counter value.
+   */
+  update: { inc: number };
+}
+
+/**
+ * Describes the common interface for all conflict-free data structures supported by the `LiveObjects`.
+ */
+export declare interface LiveObject<TUpdate extends LiveObjectUpdate = LiveObjectUpdate> {
+  /**
+   * Registers a listener that is called each time this Live Object is updated.
+   *
+   * @param listener - An event listener function that is called with an update object whenever this Live Object is updated.
+   * @returns A {@link SubscribeResponse} object that allows the provided listener to be deregistered from future updates.
+   */
+  subscribe(listener: (update: TUpdate) => void): SubscribeResponse;
+
+  /**
+   * Deregisters the given listener from updates for this Live Object.
+   *
+   * @param listener - An event listener function.
+   */
+  unsubscribe(listener: (update: TUpdate) => void): void;
+
+  /**
+   * Deregisters all listeners from updates for this Live Object.
+   */
+  unsubscribeAll(): void;
+}
+
+/**
+ * Represents a generic update object describing the changes that occurred on a Live Object.
+ */
+export declare interface LiveObjectUpdate {
+  /**
+   * Holds an update object which describe changes applied to the object.
+   */
+  update: any;
+}
+
+/**
+ * Object returned from a `subscribe` call, allowing the listener provided in that call to be deregistered.
+ */
+export declare interface SubscribeResponse {
+  /**
+   * Deregisters the listener passed to the `subscribe` call.
+   */
+  unsubscribe(): void;
+}
 
 /**
  * Enables messages to be published and historic messages to be retrieved for a channel.