DX-1204: address review feedback on v1 callback guard

- rename minV2Args -> v2TrailingFnArity (clearer semantics; docstring was
  contradicting itself with "maximum" wording)
- use unknown[] consistently in rest signatures across auth, connection,
  channel, and presence guarded methods
- point the hint at the Promise migration explicitly ("v2 uses Promises")
- remove redundant unsubscribe guard (v1 unsubscribe never took a callback)
- drop one-off "synchronous" inline comment from publish; the JSDoc on
  detectV1Callback already explains the sync-throw rationale
- use autoConnect:false in sync-throw tests so they don't open a connection
  just to validate argument-shape rejection

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: umair-ably

src/common/lib/client/auth.ts

@@ -254,9 +254,12 @@ class Auth {
    */
   async authorize(tokenParams: API.TokenParams | null, authOptions: AuthOptions | null): Promise<API.TokenDetails>;
 
-  authorize(...args: any[]): Promise<API.TokenDetails> {
+  authorize(...args: unknown[]): Promise<API.TokenDetails> {
     Utils.detectV1Callback(args, 0);
-    return this._authorizeImpl(args[0], args[1]);
+    return this._authorizeImpl(
+      args[0] as Record<string, any> | null | undefined,
+      args[1] as AuthOptions | null | undefined,
+    );
   }
 
   private async _authorizeImpl(
@@ -395,9 +398,9 @@ class Auth {
    */
   async requestToken(tokenParams: API.TokenParams | null, authOptions: AuthOptions): Promise<API.TokenDetails>;
 
-  requestToken(...args: any[]): Promise<API.TokenDetails> {
+  requestToken(...args: unknown[]): Promise<API.TokenDetails> {
     Utils.detectV1Callback(args, 0);
-    return this._requestTokenImpl(args[0], args[1]);
+    return this._requestTokenImpl(args[0] as API.TokenParams | null | undefined, args[1] as AuthOptions | undefined);
   }
 
   private async _requestTokenImpl(
@@ -757,9 +760,9 @@ class Auth {
    * - timestamp:     (optional) the time in ms since the epoch. If none is specified,
    *                  the system will be queried for a time value to use.
    */
-  createTokenRequest(...args: any[]): Promise<API.TokenRequest> {
+  createTokenRequest(...args: unknown[]): Promise<API.TokenRequest> {
     Utils.detectV1Callback(args, 0);
-    return this._createTokenRequestImpl(args[0], args[1]);
+    return this._createTokenRequestImpl(args[0] as API.TokenParams | null, args[1]);
   }
 
   private async _createTokenRequestImpl(

src/common/lib/client/connection.ts

@@ -47,7 +47,7 @@ class Connection extends EventEmitter {
     this.connectionManager.requestState({ state: 'connecting' });
   }
 
-  ping(...args: any[]): Promise<number> {
+  ping(...args: unknown[]): Promise<number> {
     Utils.detectV1Callback(args, 0);
     return this._pingImpl();
   }

src/common/lib/client/realtimechannel.ts

@@ -250,10 +250,7 @@ class RealtimeChannel extends EventEmitter {
     return false;
   }
 
-  publish(...args: any[]): Promise<API.PublishResult> {
-    // Detect a v1-shape trailing callback synchronously, before the async body
-    // starts — agents pasting v1 patterns need the throw to surface at the call
-    // site, not as an unobserved Promise rejection.
+  publish(...args: unknown[]): Promise<API.PublishResult> {
     Utils.detectV1Callback(args, 0);
     return this._publishImpl(args);
   }
@@ -489,7 +486,6 @@ class RealtimeChannel extends EventEmitter {
   }
 
   unsubscribe(...args: unknown[] /* [event], listener */): void {
-    Utils.detectV1Callback(args, 2);
     const [event, listener] = RealtimeChannel.processListenerArgs(args);
 
     // If we either have a filtered listener, a filter or both we need to do additional processing to find the original function(s)
@@ -999,9 +995,9 @@ class RealtimeChannel extends EventEmitter {
     }
   }
 
-  history = function (this: RealtimeChannel, ...args: any[]): Promise<PaginatedResult<Message>> {
+  history = function (this: RealtimeChannel, ...args: unknown[]): Promise<PaginatedResult<Message>> {
     Utils.detectV1Callback(args, 0);
-    return this._historyImpl(args[0]);
+    return this._historyImpl(args[0] as RealtimeHistoryParams | null);
   } as any;
 
   private _historyImpl = async function (

src/common/lib/client/realtimepresence.ts

@@ -54,7 +54,7 @@ class RealtimePresence extends EventEmitter {
     this.pendingPresence = [];
   }
 
-  enter(...args: any[]): Promise<void> {
+  enter(...args: unknown[]): Promise<void> {
     Utils.detectV1Callback(args, 0);
     return this._enterImpl(args[0]);
   }
@@ -66,7 +66,7 @@ class RealtimePresence extends EventEmitter {
     return this._enterOrUpdateClient(undefined, undefined, data, 'enter');
   }
 
-  update(...args: any[]): Promise<void> {
+  update(...args: unknown[]): Promise<void> {
     Utils.detectV1Callback(args, 0);
     return this._updateImpl(args[0]);
   }
@@ -139,7 +139,7 @@ class RealtimePresence extends EventEmitter {
     }
   }
 
-  leave(...args: any[]): Promise<void> {
+  leave(...args: unknown[]): Promise<void> {
     Utils.detectV1Callback(args, 0);
     return this._leaveImpl(args[0]);
   }
@@ -191,9 +191,9 @@ class RealtimePresence extends EventEmitter {
     }
   }
 
-  get(...args: any[]): Promise<PresenceMessage[]> {
+  get(...args: unknown[]): Promise<PresenceMessage[]> {
     Utils.detectV1Callback(args, 0);
-    return this._getImpl(args[0]);
+    return this._getImpl(args[0] as RealtimePresenceParams | undefined);
   }
 
   private async _getImpl(params?: RealtimePresenceParams): Promise<PresenceMessage[]> {
@@ -224,9 +224,9 @@ class RealtimePresence extends EventEmitter {
     return toMessages(this.members);
   }
 
-  history(...args: any[]): Promise<PaginatedResult<PresenceMessage>> {
+  history(...args: unknown[]): Promise<PaginatedResult<PresenceMessage>> {
     Utils.detectV1Callback(args, 0);
-    return this._historyImpl(args[0]);
+    return this._historyImpl(args[0] as RealtimeHistoryParams | null);
   }
 
   private async _historyImpl(params: RealtimeHistoryParams | null): Promise<PaginatedResult<PresenceMessage>> {

src/common/lib/util/utils.ts

@@ -274,23 +274,24 @@ export function isErrorInfoOrPartialErrorInfo(err: unknown): err is ErrorInfo |
  * trailing function (e.g. ClientOptions.authCallback).
  *
  * Fires when the trailing arg is a function AND either:
- *   - `args.length > minV2Args` (the trailing fn is beyond the v2 form's max), or
+ *   - `args.length > v2TrailingFnArity` (the trailing fn is beyond the arity at
+ *     which v2 legitimately ends in a function), or
  *   - the second-to-last arg is also a function — none of the v2 forms take two
  *     trailing functions, so e.g. `subscribe(listener, callback)` is always v1
  *     even though it matches the arity of `subscribe(event, listener)`.
  *
- * @param minV2Args - The maximum number of args the v2 form accepts. For methods
- *   whose v2 form never takes a trailing function (e.g. `authorize`, `publish`),
- *   pass `0`. For methods whose v2 form accepts a trailing listener (e.g.
- *   `subscribe(event, listener)`), pass the v2 arg count so the listener at the
- *   v2 max isn't misclassified as v1.
+ * @param v2TrailingFnArity - The arity at which v2 legitimately ends in a function
+ *   (e.g. `subscribe(event, listener)` → 2). For methods where v2 never ends in a
+ *   function (`authorize`, `publish`, `requestToken`, ...), pass 0.
  */
-export function detectV1Callback(args: ArrayLike<unknown>, minV2Args: number): void {
+export function detectV1Callback(args: ArrayLike<unknown>, v2TrailingFnArity: number): void {
   const n = args.length;
   if (typeof args[n - 1] !== 'function') return;
-  if (n <= minV2Args && typeof args[n - 2] !== 'function') return;
+  if (n <= v2TrailingFnArity && typeof args[n - 2] !== 'function') return;
   const err = new ErrorInfo('v1 callback signature is no longer supported.', 40000, 400);
-  err.hint = `Remove the trailing callback. See https://github.com/ably/ably-js/blob/main/docs/migration-guides/v2/lib.md`;
+  err.hint =
+    'v2 uses Promises — drop the trailing callback and `await` the returned promise. ' +
+    'See https://github.com/ably/ably-js/blob/main/docs/migration-guides/v2/lib.md';
   throw err;
 }
 

test/realtime/auth.test.js

@@ -1655,7 +1655,7 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, Helper, async
     ].forEach(function (testCase) {
       it('v1_callback_auth_' + testCase.method + '_throws_synchronously', function (done) {
         var helper = this.test.helper,
-          realtime = helper.AblyRealtime();
+          realtime = helper.AblyRealtime({ autoConnect: false });
 
         try {
           testCase.invoke(realtime.auth);
@@ -1670,7 +1670,7 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, Helper, async
             expect(err.message).to.contain('v1 callback signature');
             expect(err.message).to.contain('no longer supported');
             expect(err.hint).to.be.a('string');
-            expect(err.hint).to.contain('Remove the trailing callback');
+            expect(err.hint).to.contain('v2 uses Promises');
             expect(err.hint).to.contain('https://github.com/ably/ably-js/blob/main/docs/migration-guides/v2/lib.md');
             helper.closeAndFinish(done, realtime);
           } catch (assertionErr) {

test/realtime/channel.test.js

@@ -1451,9 +1451,9 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, Helper, async
 
     /**
      * v1-style trailing-callback shape on RealtimeChannel.{publish, subscribe,
-     * unsubscribe, history} throws synchronously with a steering ErrorInfo whose
-     * message diagnoses *what* went wrong and whose hint prescribes the v2
-     * replacement call.
+     * history} throws synchronously with a steering ErrorInfo whose message
+     * diagnoses *what* went wrong and whose hint prescribes the v2 replacement
+     * call.
      */
     [
       { method: 'publish', invoke: (ch) => ch.publish('event', { hello: 'world' }, () => {}) },
@@ -1474,28 +1474,11 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, Helper, async
             () => {},
           ),
       },
-      {
-        method: 'unsubscribe',
-        invoke: (ch) =>
-          ch.unsubscribe(
-            'event',
-            () => {},
-            () => {},
-          ),
-      },
-      {
-        method: 'unsubscribe_listener_callback',
-        invoke: (ch) =>
-          ch.unsubscribe(
-            () => {},
-            () => {},
-          ),
-      },
       { method: 'history', invoke: (ch) => ch.history(null, () => {}) },
     ].forEach(function (testCase) {
       it('v1_callback_' + testCase.method + '_throws_synchronously', function (done) {
         var helper = this.test.helper,
-          realtime = helper.AblyRealtime(),
+          realtime = helper.AblyRealtime({ autoConnect: false }),
           channel = realtime.channels.get('v1cb_channel_' + testCase.method);
 
         try {
@@ -1511,7 +1494,7 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, Helper, async
             expect(err.message).to.contain('v1 callback signature');
             expect(err.message).to.contain('no longer supported');
             expect(err.hint).to.be.a('string');
-            expect(err.hint).to.contain('Remove the trailing callback');
+            expect(err.hint).to.contain('v2 uses Promises');
             expect(err.hint).to.contain('https://github.com/ably/ably-js/blob/main/docs/migration-guides/v2/lib.md');
             helper.closeAndFinish(done, realtime);
           } catch (assertionErr) {

test/realtime/connection.test.js

@@ -480,7 +480,7 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, Helper, async
      */
     it('v1_callback_ping_throws_synchronously', function (done) {
       const helper = this.test.helper;
-      const realtime = helper.AblyRealtime();
+      const realtime = helper.AblyRealtime({ autoConnect: false });
       try {
         realtime.connection.ping(function noopCallback(err) {
           void err;
@@ -492,7 +492,7 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, Helper, async
           expect(err.message).to.contain('v1 callback signature');
           expect(err.message).to.contain('no longer supported');
           expect(err.hint).to.be.a('string');
-          expect(err.hint).to.contain('Remove the trailing callback');
+          expect(err.hint).to.contain('v2 uses Promises');
           expect(err.hint).to.contain('https://github.com/ably/ably-js/blob/main/docs/migration-guides/v2/lib.md');
           helper.closeAndFinish(done, realtime);
         } catch (assertionErr) {

test/realtime/presence.test.js

@@ -2340,7 +2340,7 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, Helper, async
     ].forEach(function (testCase) {
       it('v1_callback_presence_' + testCase.method + '_throws_synchronously', function (done) {
         var helper = this.test.helper,
-          realtime = helper.AblyRealtime({ clientId: testClientId }),
+          realtime = helper.AblyRealtime({ clientId: testClientId, autoConnect: false }),
           channel = realtime.channels.get('v1cb_presence_' + testCase.method);
 
         try {
@@ -2356,7 +2356,7 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, Helper, async
             expect(err.message).to.contain('v1 callback signature');
             expect(err.message).to.contain('no longer supported');
             expect(err.hint).to.be.a('string');
-            expect(err.hint).to.contain('Remove the trailing callback');
+            expect(err.hint).to.contain('v2 uses Promises');
             expect(err.hint).to.contain('https://github.com/ably/ably-js/blob/main/docs/migration-guides/v2/lib.md');
             helper.closeAndFinish(done, realtime);
           } catch (assertionErr) {