[DX-1204] Mark v1 callback API as deprecated

scripts/moduleReport.ts

@@ -6,7 +6,7 @@ import { gzip } from 'zlib';
 import Table from 'cli-table';
 
 // The maximum size we allow for a minimal useful Realtime bundle (i.e. one that can subscribe to a channel)
-const minimalUsefulRealtimeBundleSizeThresholdsKiB = { raw: 106, gzip: 32 };
+const minimalUsefulRealtimeBundleSizeThresholdsKiB = { raw: 107, gzip: 33 };
 
 const baseClientNames = ['BaseRest', 'BaseRealtime'];
 

src/common/lib/client/auth.ts

@@ -254,7 +254,15 @@ class Auth {
    */
   async authorize(tokenParams: API.TokenParams | null, authOptions: AuthOptions | null): Promise<API.TokenDetails>;
 
-  async authorize(
+  authorize(...args: unknown[]): Promise<API.TokenDetails> {
+    Utils.detectV1Callback(args, 0);
+    return this._authorizeImpl(
+      args[0] as Record<string, any> | null | undefined,
+      args[1] as AuthOptions | null | undefined,
+    );
+  }
+
+  private async _authorizeImpl(
     tokenParams?: Record<string, any> | null,
     authOptions?: AuthOptions | null,
   ): Promise<API.TokenDetails> {
@@ -390,7 +398,15 @@ class Auth {
    */
   async requestToken(tokenParams: API.TokenParams | null, authOptions: AuthOptions): Promise<API.TokenDetails>;
 
-  async requestToken(tokenParams?: API.TokenParams | null, authOptions?: AuthOptions): Promise<API.TokenDetails> {
+  requestToken(...args: unknown[]): Promise<API.TokenDetails> {
+    Utils.detectV1Callback(args, 0);
+    return this._requestTokenImpl(args[0] as API.TokenParams | null | undefined, args[1] as AuthOptions | undefined);
+  }
+
+  private async _requestTokenImpl(
+    tokenParams?: API.TokenParams | null,
+    authOptions?: AuthOptions,
+  ): Promise<API.TokenDetails> {
     /* RSA8e: if authOptions passed in, they're used instead of stored, don't merge them */
     const resolvedAuthOptions = authOptions || this.authOptions;
     const resolvedTokenParams = tokenParams || Utils.copy(this.tokenParams);
@@ -744,7 +760,15 @@ 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.
    */
-  async createTokenRequest(tokenParams: API.TokenParams | null, authOptions: any): Promise<API.TokenRequest> {
+  createTokenRequest(...args: unknown[]): Promise<API.TokenRequest> {
+    Utils.detectV1Callback(args, 0);
+    return this._createTokenRequestImpl(args[0] as API.TokenParams | null, args[1]);
+  }
+
+  private async _createTokenRequestImpl(
+    tokenParams: API.TokenParams | null,
+    authOptions: any,
+  ): Promise<API.TokenRequest> {
     /* RSA9h: if authOptions passed in, they're used instead of stored, don't merge them */
     authOptions = authOptions || this.authOptions;
     tokenParams = tokenParams || Utils.copy<API.TokenParams>(this.tokenParams);

src/common/lib/client/connection.ts

@@ -3,6 +3,7 @@ import ConnectionManager from '../transport/connectionmanager';
 import Logger from '../util/logger';
 import ConnectionStateChange from './connectionstatechange';
 import ErrorInfo from '../types/errorinfo';
+import * as Utils from '../util/utils';
 import { NormalisedClientOptions } from '../../types/ClientOptions';
 import BaseRealtime from './baserealtime';
 import Platform from 'common/platform';
@@ -46,7 +47,12 @@ class Connection extends EventEmitter {
     this.connectionManager.requestState({ state: 'connecting' });
   }
 
-  async ping(): Promise<number> {
+  ping(...args: unknown[]): Promise<number> {
+    Utils.detectV1Callback(args, 0);
+    return this._pingImpl();
+  }
+
+  private async _pingImpl(): Promise<number> {
     Logger.logAction(this.logger, Logger.LOG_MINOR, 'Connection.ping()', '');
     return this.connectionManager.ping();
   }

src/common/lib/client/realtimechannel.ts

@@ -250,7 +250,12 @@ class RealtimeChannel extends EventEmitter {
     return false;
   }
 
-  async publish(...args: any[]): Promise<API.PublishResult> {
+  publish(...args: unknown[]): Promise<API.PublishResult> {
+    Utils.detectV1Callback(args, 0);
+    return this._publishImpl(args);
+  }
+
+  private async _publishImpl(args: any[]): Promise<API.PublishResult> {
     const first = args[0],
       second = args[1];
     let messages: Message[];
@@ -453,7 +458,12 @@ class RealtimeChannel extends EventEmitter {
     this.send(msg);
   }
 
-  async subscribe(...args: unknown[] /* [event], listener */): Promise<ChannelStateChange | null> {
+  subscribe(...args: unknown[] /* [event], listener */): Promise<ChannelStateChange | null> {
+    Utils.detectV1Callback(args, 2);
+    return this._subscribeImpl(args);
+  }
+
+  private async _subscribeImpl(args: unknown[]): Promise<ChannelStateChange | null> {
     const [event, listener] = RealtimeChannel.processListenerArgs(args);
 
     if (this.state === 'failed') {
@@ -985,7 +995,12 @@ class RealtimeChannel extends EventEmitter {
     }
   }
 
-  history = async function (
+  history = function (this: RealtimeChannel, ...args: unknown[]): Promise<PaginatedResult<Message>> {
+    Utils.detectV1Callback(args, 0);
+    return this._historyImpl(args[0] as RealtimeHistoryParams | null);
+  } as any;
+
+  private _historyImpl = async function (
     this: RealtimeChannel,
     params: RealtimeHistoryParams | null,
   ): Promise<PaginatedResult<Message>> {

src/common/lib/client/realtimepresence.ts

@@ -54,14 +54,24 @@ class RealtimePresence extends EventEmitter {
     this.pendingPresence = [];
   }
 
-  async enter(data: unknown): Promise<void> {
+  enter(...args: unknown[]): Promise<void> {
+    Utils.detectV1Callback(args, 0);
+    return this._enterImpl(args[0]);
+  }
+
+  private async _enterImpl(data: unknown): Promise<void> {
     if (isAnonymousOrWildcard(this)) {
       throw new ErrorInfo('clientId must be specified to enter a presence channel', 40012, 400);
     }
     return this._enterOrUpdateClient(undefined, undefined, data, 'enter');
   }
 
-  async update(data: unknown): Promise<void> {
+  update(...args: unknown[]): Promise<void> {
+    Utils.detectV1Callback(args, 0);
+    return this._updateImpl(args[0]);
+  }
+
+  private async _updateImpl(data: unknown): Promise<void> {
     if (isAnonymousOrWildcard(this)) {
       throw new ErrorInfo('clientId must be specified to update presence data', 40012, 400);
     }
@@ -129,7 +139,12 @@ class RealtimePresence extends EventEmitter {
     }
   }
 
-  async leave(data: unknown): Promise<void> {
+  leave(...args: unknown[]): Promise<void> {
+    Utils.detectV1Callback(args, 0);
+    return this._leaveImpl(args[0]);
+  }
+
+  private async _leaveImpl(data: unknown): Promise<void> {
     if (isAnonymousOrWildcard(this)) {
       throw new ErrorInfo('clientId must have been specified to enter or leave a presence channel', 40012, 400);
     }
@@ -176,7 +191,12 @@ class RealtimePresence extends EventEmitter {
     }
   }
 
-  async get(params?: RealtimePresenceParams): Promise<PresenceMessage[]> {
+  get(...args: unknown[]): Promise<PresenceMessage[]> {
+    Utils.detectV1Callback(args, 0);
+    return this._getImpl(args[0] as RealtimePresenceParams | undefined);
+  }
+
+  private async _getImpl(params?: RealtimePresenceParams): Promise<PresenceMessage[]> {
     const waitForSync = !params || ('waitForSync' in params ? params.waitForSync : true);
 
     function toMessages(members: PresenceMap): PresenceMessage[] {
@@ -204,7 +224,12 @@ class RealtimePresence extends EventEmitter {
     return toMessages(this.members);
   }
 
-  async history(params: RealtimeHistoryParams | null): Promise<PaginatedResult<PresenceMessage>> {
+  history(...args: unknown[]): Promise<PaginatedResult<PresenceMessage>> {
+    Utils.detectV1Callback(args, 0);
+    return this._historyImpl(args[0] as RealtimeHistoryParams | null);
+  }
+
+  private async _historyImpl(params: RealtimeHistoryParams | null): Promise<PaginatedResult<PresenceMessage>> {
     Logger.logAction(this.logger, Logger.LOG_MICRO, 'RealtimePresence.history()', 'channel = ' + this.name);
     // We fetch this first so that any plugin-not-provided error takes priority over other errors
     const restMixin = this.channel.client.rest.presenceMixin;
@@ -407,7 +432,12 @@ class RealtimePresence extends EventEmitter {
     });
   }
 
-  async subscribe(..._args: unknown[] /* [event], listener */): Promise<void> {
+  subscribe(..._args: unknown[] /* [event], listener */): Promise<void> {
+    Utils.detectV1Callback(_args, 2);
+    return this._subscribeImpl(_args);
+  }
+
+  private async _subscribeImpl(_args: unknown[]): Promise<void> {
     const args = RealtimeChannel.processListenerArgs(_args);
     const event = args[0];
     const listener = args[1];

src/common/lib/types/errorinfo.ts

@@ -8,6 +8,7 @@ export interface IPartialErrorInfo extends Error {
   cause?: ErrorInfo | PartialErrorInfo;
   href?: string;
   detail?: Record<string, string>;
+  hint?: string;
 }
 
 function toString(err: ErrorInfo | PartialErrorInfo) {
@@ -16,6 +17,7 @@ function toString(err: ErrorInfo | PartialErrorInfo) {
   if (err.statusCode) result += '; statusCode=' + err.statusCode;
   if (err.code) result += '; code=' + err.code;
   if (err.cause) result += '; cause=' + Utils.inspectError(err.cause);
+  if (err.hint) result += '; hint=' + err.hint;
   if (err.detail && Object.keys(err.detail).length > 0) result += '; detail=' + JSON.stringify(err.detail);
   if (err.href && !(err.message && err.message.indexOf('help.ably.io') > -1)) result += '; see ' + err.href + ' ';
   result += ']';
@@ -42,6 +44,7 @@ export default class ErrorInfo extends Error implements IPartialErrorInfo, API.E
   cause?: ErrorInfo;
   href?: string;
   detail?: Record<string, string>;
+  hint?: string;
 
   constructor(message: string, code: number, statusCode: number, cause?: ErrorInfo, detail?: Record<string, string>) {
     super(message);
@@ -82,6 +85,7 @@ export class PartialErrorInfo extends Error implements IPartialErrorInfo {
   cause?: ErrorInfo | PartialErrorInfo;
   href?: string;
   detail?: Record<string, string>;
+  hint?: string;
 
   constructor(
     message: string,

src/common/lib/util/utils.ts

@@ -263,6 +263,38 @@ export function isErrorInfoOrPartialErrorInfo(err: unknown): err is ErrorInfo |
   return typeof err == 'object' && err !== null && (err instanceof ErrorInfo || err instanceof PartialErrorInfo);
 }
 
+/**
+ * Detect a v1-style trailing callback on a public method's args list and throw a
+ * steering error. v2 removed callback support from these methods, but agents trained
+ * on v1 docs keep passing callbacks — without this check, the callback is silently
+ * swallowed and the call hangs (subscribe) or no-ops (publish).
+ *
+ * Apply only to methods whose v1 form accepted a Node-style (err, result) callback
+ * and which are promise-only in v2. Do not apply to APIs that legitimately accept a
+ * trailing function (e.g. ClientOptions.authCallback).
+ *
+ * Fires when the trailing arg is a function AND either:
+ *   - `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 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>, v2TrailingFnArity: number): void {
+  const n = args.length;
+  if (typeof args[n - 1] !== 'function') return;
+  if (n <= v2TrailingFnArity && typeof args[n - 2] !== 'function') return;
+  const err = new ErrorInfo('v1 callback signature is no longer supported.', 40025, 400);
+  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;
+}
+
 export function inspectError(err: unknown): string {
   if (
     err instanceof Error ||

src/platform/react-hooks/src/hooks/useChannel.ts

@@ -1,5 +1,5 @@
 import * as Ably from 'ably';
-import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useEffect, useMemo, useRef } from 'react';
 import { ChannelParameters } from '../AblyReactHooks.js';
 import { useAbly } from './useAbly.js';
 import { useStateErrors } from './useStateErrors.js';
@@ -56,8 +56,8 @@ export function useChannel(
 
   const ablyMessageCallbackRef = useRef(ablyMessageCallback);
 
-  const history: Ably.RealtimeChannel['history'] = useCallback(
-    (params?: Ably.RealtimeHistoryParams) => channel.history(params),
+  const history: Ably.RealtimeChannel['history'] = useMemo(
+    () => ((params?: Ably.RealtimeHistoryParams) => channel.history(params)) as Ably.RealtimeChannel['history'],
     [channel],
   );
 

test/realtime/auth.test.js

@@ -1643,5 +1643,41 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, Helper, async
         });
       };
     });
+
+    /**
+     * v1-style trailing-callback shape on Auth.{authorize, requestToken,
+     * createTokenRequest} throws synchronously with a steering ErrorInfo.
+     */
+    [
+      { method: 'authorize', invoke: (auth) => auth.authorize(null, null, () => {}) },
+      { method: 'requestToken', invoke: (auth) => auth.requestToken(null, null, () => {}) },
+      { method: 'createTokenRequest', invoke: (auth) => auth.createTokenRequest(null, null, () => {}) },
+    ].forEach(function (testCase) {
+      it('v1_callback_auth_' + testCase.method + '_throws_synchronously', function (done) {
+        var helper = this.test.helper,
+          realtime = helper.AblyRealtime({ autoConnect: false });
+
+        try {
+          testCase.invoke(realtime.auth);
+          helper.closeAndFinish(
+            done,
+            realtime,
+            new Error('expected auth.' + testCase.method + '() to throw on v1 callback shape'),
+          );
+        } catch (err) {
+          try {
+            expect(err.code).to.equal(40025);
+            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('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) {
+            helper.closeAndFinish(done, realtime, assertionErr);
+          }
+        }
+      });
+    });
   });
 });

test/realtime/channel.test.js

@@ -1449,6 +1449,61 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, Helper, async
       });
     });
 
+    /**
+     * v1-style trailing-callback shape on RealtimeChannel.{publish, subscribe,
+     * 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' }, () => {}) },
+      {
+        method: 'subscribe',
+        invoke: (ch) =>
+          ch.subscribe(
+            'event',
+            () => {},
+            () => {},
+          ),
+      },
+      {
+        method: 'subscribe_listener_callback',
+        invoke: (ch) =>
+          ch.subscribe(
+            () => {},
+            () => {},
+          ),
+      },
+      { 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({ autoConnect: false }),
+          channel = realtime.channels.get('v1cb_channel_' + testCase.method);
+
+        try {
+          testCase.invoke(channel);
+          helper.closeAndFinish(
+            done,
+            realtime,
+            new Error('expected ' + testCase.method + '() to throw on v1 callback shape'),
+          );
+        } catch (err) {
+          try {
+            expect(err.code).to.equal(40025);
+            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('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) {
+            helper.closeAndFinish(done, realtime, assertionErr);
+          }
+        }
+      });
+    });
+
     /**
      * A channel attach that times out should be retried
      *