DX-1211: rewrite RealtimePresence interface docstrings (prerequisites, side-effects, failure modes)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: umair-ably

ably.d.ts

@@ -2155,51 +2155,69 @@ export declare interface Presence {
  */
 export declare interface RealtimePresence {
   /**
-   * Indicates whether the presence set synchronization between Ably and the clients on the channel has been completed. Set to `true` when the sync is complete.
+   * Indicates whether the presence set synchronization between Ably and the clients on the channel has been completed. Set to `true` when the sync is complete, and back to `false` whenever a new sync starts (typically after a (re)attach). The value is also `true` after the local presence set is cleared (when the channel becomes detached or failed, or attaches without the server reporting any presence members), so it indicates only that no sync is in progress (though it is initially `false`, before any sync has started), not that the channel is attached or that a sync ever ran. To wait for an in-progress sync, call {@link RealtimePresence.get | `get()`}, which by default resolves only once the sync completes.
+   *
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#sync-complete
    */
   syncComplete: boolean;
   /**
-   * Deregisters a specific listener that is registered to receive {@link PresenceMessage} on the channel for a given {@link PresenceAction}.
+   * Deregisters a specific listener that is registered to receive {@link PresenceMessage} on the channel for a given {@link PresenceAction}. This only removes the local listener; it does not detach the channel or remove this client from the presence set (use {@link RealtimePresence.leave | `leave()`} for that), and presence events may continue to arrive for any other registered listeners.
    *
    * @param presence - A specific {@link PresenceAction} to deregister the listener for.
    * @param listener - An event listener function.
+   * @example
+   * ```ts
+   * channel.presence.unsubscribe('enter', listener);
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#unsubscribe
    */
   unsubscribe(presence: PresenceAction, listener: messageCallback<PresenceMessage>): void;
   /**
-   * Deregisters a specific listener that is registered to receive {@link PresenceMessage} on the channel for a given array of {@link PresenceAction} objects.
+   * Deregisters a specific listener that is registered to receive {@link PresenceMessage} on the channel for a given array of {@link PresenceAction} objects. This only removes the local listener and does not detach the channel.
    *
    * @param presence - An array of {@link PresenceAction} objects to deregister the listener for.
    * @param listener - An event listener function.
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#unsubscribe
    */
   unsubscribe(presence: Array<PresenceAction>, listener: messageCallback<PresenceMessage>): void;
   /**
-   * Deregisters any listener that is registered to receive {@link PresenceMessage} on the channel for a specific {@link PresenceAction}
+   * Deregisters any listener that is registered to receive {@link PresenceMessage} on the channel for a specific {@link PresenceAction}. This only removes the local listeners and does not detach the channel.
    *
    * @param presence - A specific {@link PresenceAction} to deregister the listeners for.
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#unsubscribe
    */
   unsubscribe(presence: PresenceAction): void;
   /**
-   * Deregisters any listener that is registered to receive {@link PresenceMessage} on the channel for an array of {@link PresenceAction} objects
+   * Deregisters any listener that is registered to receive {@link PresenceMessage} on the channel for an array of {@link PresenceAction} objects. This only removes the local listeners and does not detach the channel.
    *
    * @param presence - An array of {@link PresenceAction} objects to deregister the listeners for.
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#unsubscribe
    */
   unsubscribe(presence: Array<PresenceAction>): void;
   /**
-   * Deregisters a specific listener that is registered to receive {@link PresenceMessage} on the channel.
+   * Deregisters a specific listener that is registered to receive {@link PresenceMessage} on the channel. This only removes the local listener and does not detach the channel.
    *
    * @param listener - An event listener function.
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#unsubscribe
    */
   unsubscribe(listener: messageCallback<PresenceMessage>): void;
   /**
-   * Deregisters all listeners currently receiving {@link PresenceMessage} for the channel.
+   * Deregisters all listeners currently receiving {@link PresenceMessage} for the channel. This only removes the local listeners and does not detach the channel or remove this client from the presence set, so the channel stays attached and an entered client remains present.
+   *
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#unsubscribe
    */
   unsubscribe(): void;
 
   /**
-   * Retrieves the current members present on the channel and the metadata for each member, such as their {@link PresenceAction} and ID. Returns an array of {@link PresenceMessage} objects.
+   * Retrieves the current members present on the channel and the metadata for each member, such as their {@link PresenceAction} and ID. Implicitly attaches the channel if it is not already attached. Requires the `presence_subscribe` mode (granted by default unless {@link ChannelOptions.modes} excludes it); without it the call resolves with an empty array rather than rejecting (or it rejects with a hinted {@link ErrorInfo} when {@link ClientOptions.strictMode} is enabled).
    *
    * @param params - A set of parameters which are used to specify which presence members should be retrieved.
    * @returns A promise which, upon success, will be fulfilled with an array of {@link PresenceMessage} objects. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
+   * @example
+   * ```ts
+   * const members = await channel.presence.get();
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#get
    */
   get(params?: RealtimePresenceParams): Promise<PresenceMessage[]>;
   /**
@@ -2217,10 +2235,16 @@ export declare interface RealtimePresence {
    */
   get(params: RealtimePresenceParams | null, callback: StandardCallback<PresenceMessage[]>): void;
   /**
-   * Retrieves a {@link PaginatedResult} object, containing an array of historical {@link PresenceMessage} objects for the channel. If the channel is configured to persist messages, then presence messages can be retrieved from history for up to 72 hours in the past. If not, presence messages can only be retrieved from history for up to two minutes in the past.
+   * Retrieves a {@link PaginatedResult} object, containing an array of historical {@link PresenceMessage} objects for the channel. Presence messages are retrievable for up to 72 hours in the past when message persistence is enabled for the channel by a channel rule; without it, only presence messages from the last two minutes, the service's default retention, are returned.
    *
    * @param params - A set of parameters which are used to specify which presence messages should be retrieved.
    * @returns A promise which, upon success, will be fulfilled with a {@link PaginatedResult} object containing an array of {@link PresenceMessage} objects. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
+   * @example
+   * ```ts
+   * const result = await channel.presence.history();
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#history
+   * @see https://ably.com/docs/storage-history/storage
    */
   history(params?: RealtimeHistoryParams): Promise<PaginatedResult<PresenceMessage>>;
   /**
@@ -2238,18 +2262,28 @@ export declare interface RealtimePresence {
    */
   history(params: RealtimeHistoryParams | null, callback: StandardCallback<PaginatedResult<PresenceMessage>>): void;
   /**
-   * Registers a listener that is called each time a {@link PresenceMessage} matching a given {@link PresenceAction}, or an action within an array of {@link PresenceAction | `PresenceAction`s}, is received on the channel, such as a new member entering the presence set.
+   * Registers a listener that is called each time a {@link PresenceMessage} matching a given {@link PresenceAction}, or an action within an array of {@link PresenceAction | `PresenceAction`s}, is received on the channel, such as a new member entering the presence set. Implicitly attaches the channel unless {@link ChannelOptions.attachOnSubscribe} is `false`. Requires the `presence_subscribe` mode (granted by default unless {@link ChannelOptions.modes} excludes it); if the channel attaches without it the server never delivers presence events, so the listener silently never fires: the call still resolves and nothing is logged.
    *
    * @param action - A {@link PresenceAction} or an array of {@link PresenceAction | `PresenceAction`s} to register the listener for.
    * @param listener - An event listener function.
-   * @returns A promise which resolves upon success of the channel {@link RealtimeChannel.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @returns A promise which resolves upon success of the channel {@link RealtimeChannel.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. When {@link ChannelOptions.attachOnSubscribe} is `false`, no attach is performed.
+   * @example
+   * ```ts
+   * await channel.presence.subscribe('enter', (member) => console.log(member.clientId));
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#subscribe
    */
   subscribe(action: PresenceAction | Array<PresenceAction>, listener?: messageCallback<PresenceMessage>): Promise<void>;
   /**
-   * Registers a listener that is called each time a {@link PresenceMessage} is received on the channel, such as a new member entering the presence set.
+   * Registers a listener that is called each time a {@link PresenceMessage} is received on the channel, such as a new member entering the presence set. Implicitly attaches the channel unless {@link ChannelOptions.attachOnSubscribe} is `false`. Requires the `presence_subscribe` mode (granted by default unless {@link ChannelOptions.modes} excludes it); if the channel attaches without it the server never delivers presence events, so the listener silently never fires: the call still resolves and nothing is logged.
    *
    * @param listener - An event listener function.
-   * @returns A promise which resolves upon success of the channel {@link RealtimeChannel.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @returns A promise which resolves upon success of the channel {@link RealtimeChannel.attach | `attach()`} operation and rejects with an {@link ErrorInfo} object upon its failure. When {@link ChannelOptions.attachOnSubscribe} is `false`, no attach is performed.
+   * @example
+   * ```ts
+   * await channel.presence.subscribe((member) => console.log(member.clientId));
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#subscribe
    */
   subscribe(listener?: messageCallback<PresenceMessage>): Promise<void>;
   /**
@@ -2272,10 +2306,15 @@ export declare interface RealtimePresence {
     callback: ErrorCallback,
   ): void;
   /**
-   * Enters the presence set for the channel, optionally passing a `data` payload. A `clientId` is required to be present on a channel.
+   * Enters the presence set for the channel, optionally passing a `data` payload. A `clientId` is required: if the client has no `clientId` (or the wildcard `*`), the call rejects with an {@link ErrorInfo}; set a `clientId` in {@link ClientOptions} or in the token, or use {@link RealtimePresence.enterClient | `enterClient()`} to enter on behalf of another identity. Implicitly attaches the channel if it is not already attached. Once entered, the member is automatically re-entered whenever the channel re-attaches after a disconnection; if that re-enter fails, the failure surfaces as a channel `update` event carrying the {@link ErrorInfo}, not as a rejection.
    *
    * @param data - The payload associated with the presence member.
    * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @example
+   * ```ts
+   * await channel.presence.enter({ status: 'online' });
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#enter
    */
   enter(data?: any): Promise<void>;
   /**
@@ -2293,10 +2332,15 @@ export declare interface RealtimePresence {
    */
   enter(data: any, callback: ErrorCallback): void;
   /**
-   * Updates the `data` payload for a presence member. If called before entering the presence set, this is treated as an {@link PresenceActions.ENTER} event.
+   * Updates the `data` payload for a presence member. If called before entering the presence set, this is treated as an {@link PresenceActions.ENTER} event. Requires an identified client: if the client has no `clientId` (or the wildcard `*`) set in the {@link ClientOptions} or the token, the call rejects with an {@link ErrorInfo} (use {@link RealtimePresence.updateClient | `updateClient()`} to update on behalf of another identity). Implicitly attaches the channel if it is not already attached.
    *
    * @param data - The payload to update for the presence member.
    * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @example
+   * ```ts
+   * await channel.presence.update({ status: 'busy' });
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#update
    */
   update(data?: any): Promise<void>;
   /**
@@ -2314,10 +2358,15 @@ export declare interface RealtimePresence {
    */
   update(data: any, callback: ErrorCallback): void;
   /**
-   * Leaves the presence set for the channel. A client must have previously entered the presence set before they can leave it.
+   * Leaves the presence set for the channel. A client must have previously entered the presence set before they can leave it. Requires the client to be identified: when the `clientId` is unset or a wildcard, the call rejects with an {@link ErrorInfo}; to leave on behalf of another identity use {@link RealtimePresence.leaveClient | `leaveClient()`}, which requires a wildcard `clientId` on the API key or token. Unlike {@link RealtimePresence.enter | `enter()`}, leaving does not implicitly attach the channel: the call proceeds only while the channel is `attached` or `attaching`, and rejects with an {@link ErrorInfo} in any other channel state or when the connection is unusable.
    *
    * @param data - The payload associated with the presence member.
    * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @example
+   * ```ts
+   * await channel.presence.leave();
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#leave
    */
   leave(data?: any): Promise<void>;
   /**
@@ -2335,27 +2384,42 @@ export declare interface RealtimePresence {
    */
   leave(data: any, callback: ErrorCallback): void;
   /**
-   * Enters the presence set of the channel for a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`.
+   * Enters the presence set of the channel for a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`; this is enforced by the server rather than the client, so without it the call rejects with an {@link ErrorInfo} returned by the server. Implicitly attaches the channel if it is not already attached. After a transient disconnection the library automatically re-enters the member on re-attach; if that re-enter fails, the failure surfaces as a channel `update` event carrying the {@link ErrorInfo}, not as a rejection.
    *
    * @param clientId - The ID of the client to enter into the presence set.
    * @param data - The payload associated with the presence member.
    * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @example
+   * ```ts
+   * await channel.presence.enterClient('bob', { status: 'online' });
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#enter-client
    */
   enterClient(clientId: string, data?: any): Promise<void>;
   /**
-   * Updates the `data` payload for a presence member using a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`.
+   * Updates the `data` payload for a presence member using a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`; this is enforced by the server rather than the client, so without it the call rejects with an {@link ErrorInfo} returned by the server. Implicitly attaches the channel if it is not already attached.
    *
    * @param clientId - The ID of the client to update in the presence set.
    * @param data - The payload to update for the presence member.
    * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @example
+   * ```ts
+   * await channel.presence.updateClient('bob', { status: 'busy' });
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#update-client
    */
   updateClient(clientId: string, data?: any): Promise<void>;
   /**
-   * Leaves the presence set of the channel for a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`.
+   * Leaves the presence set of the channel for a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`; this is enforced by the server rather than the client, so without it the call rejects with an {@link ErrorInfo} returned by the server. Unlike {@link RealtimePresence.enterClient | `enterClient()`}, this call does not implicitly attach the channel; when the channel is neither attached nor attaching it rejects with an {@link ErrorInfo} rather than attaching just to leave.
    *
    * @param clientId - The ID of the client to leave the presence set for.
    * @param data - The payload associated with the presence member.
    * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
+   * @example
+   * ```ts
+   * await channel.presence.leaveClient('bob');
+   * ```
+   * @see https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-presence#leave-client
    */
   leaveClient(clientId: string, data?: any): Promise<void>;
 }