From 7c4bffa7d4032c00c2cb88fac840cfe4dc01b3cc Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Tue, 21 Jan 2025 10:49:48 -0300
Subject: [PATCH] Fix typings for RealtimeChannel.modes

For some reason, this property returns lowercased values. So, reflect
this in the typings. This is the only non-breaking change we can make,
since:

- if we change the return value of RealtimeChannel.modes to be
  uppercase, that will break things for users who are checking this
  return value against a list of lowercase values (having previously
  observed that this property returns lowercase values even though it
  contradicts the typings)

- if we change the ChannelModes type to be lowercase, then we break
  things for TypeScript users who are setting `modes` in their channel
  options

I have also changed the ChannelModes type to indicate that it accepts
lowercased values; this allows a user to pass a ResolvedChannelModes
when setting `modes` in their channel options.

In our next major release, we should remove this duplicate type and only
allow a single case (probably lowercase, since that's what we use for
all of the other enum values in this SDK). Have created #1954 for this.

Resolves #1952.
---
 ably.d.ts | 49 +++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 43 insertions(+), 6 deletions(-)

diff --git a/ably.d.ts b/ably.d.ts
index dc4119729..089da9994 100644
--- a/ably.d.ts
+++ b/ably.d.ts
@@ -853,23 +853,25 @@ declare namespace ChannelModes {
   /**
    * The client can publish messages.
    */
-  type PUBLISH = 'PUBLISH';
+  type PUBLISH = 'PUBLISH' | 'publish';
   /**
    * The client can subscribe to messages.
    */
-  type SUBSCRIBE = 'SUBSCRIBE';
+  type SUBSCRIBE = 'SUBSCRIBE' | 'subscribe';
   /**
    * The client can enter the presence set.
    */
-  type PRESENCE = 'PRESENCE';
+  type PRESENCE = 'PRESENCE' | 'presence';
   /**
    * The client can receive presence messages.
    */
-  type PRESENCE_SUBSCRIBE = 'PRESENCE_SUBSCRIBE';
+  type PRESENCE_SUBSCRIBE = 'PRESENCE_SUBSCRIBE' | 'presence_subscribe';
 }
 
 /**
  * Describes the possible flags used to configure client capabilities, using {@link ChannelOptions}.
+ *
+ * **Note:** This type admits uppercase or lowercase values for reasons of backwards compatibility. In the next major release of this SDK, it will be merged with {@link ResolvedChannelMode} and only admit lowercase values; see [this GitHub issue](https://github.com/ably/ably-js/issues/1954).
  */
 export type ChannelMode =
   | ChannelModes.PUBLISH
@@ -877,6 +879,41 @@ export type ChannelMode =
   | ChannelModes.PRESENCE
   | ChannelModes.PRESENCE_SUBSCRIBE;
 
+/**
+ * The `ResolvedChannelModes` namespace describes the possible values of the {@link ResolvedChannelMode} type.
+ */
+declare namespace ResolvedChannelModes {
+  /**
+   * The client can publish messages.
+   */
+  type PUBLISH = 'publish';
+  /**
+   * The client can subscribe to messages.
+   */
+  type SUBSCRIBE = 'subscribe';
+  /**
+   * The client can enter the presence set.
+   */
+  type PRESENCE = 'presence';
+  /**
+   * The client can receive presence messages.
+   */
+  type PRESENCE_SUBSCRIBE = 'presence_subscribe';
+}
+
+/**
+ * Describes the configuration that a {@link RealtimeChannel} is using, as returned by {@link RealtimeChannel.modes}.
+ *
+ * This type is the same as the {@link ChannelMode} type but with all of the values lowercased.
+ *
+ * **Note:** This type exists for reasons of backwards compatibility. In the next major release of this SDK, it will be merged with {@link ChannelMode}; see [this GitHub issue](https://github.com/ably/ably-js/issues/1954).
+ */
+export type ResolvedChannelMode =
+  | ResolvedChannelModes.PUBLISH
+  | ResolvedChannelModes.SUBSCRIBE
+  | ResolvedChannelModes.PRESENCE
+  | ResolvedChannelModes.PRESENCE_SUBSCRIBE;
+
 /**
  * Passes additional properties to a {@link Channel} or {@link RealtimeChannel} object, such as encryption, {@link ChannelMode} and channel parameters.
  */
@@ -2090,9 +2127,9 @@ export declare interface RealtimeChannel extends EventEmitter<channelEventCallba
    */
   params: ChannelParams;
   /**
-   * An array of {@link ChannelMode} objects.
+   * An array of {@link ResolvedChannelMode} objects.
    */
-  modes: ChannelMode[];
+  modes: ResolvedChannelMode[];
   /**
    * Deregisters the given listener for the specified event name. This removes an earlier event-specific subscription.
    *