DX-1209: inline fix-it hints on SDK ErrorInfo throw sites

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: 108, gzip: 33 };
+const minimalUsefulRealtimeBundleSizeThresholdsKiB = { raw: 118, gzip: 36 };
 
 const baseClientNames = ['BaseRest', 'BaseRealtime'];
 

src/common/lib/client/baseclient.ts

@@ -76,21 +76,33 @@ class BaseClient {
       if (!keyMatch) {
         const msg = 'invalid key parameter';
         Logger.logAction(this.logger, Logger.LOG_ERROR, 'BaseClient()', msg);
-        throw new ErrorInfo(msg, 40400, 404);
+        throw new ErrorInfo({
+          message: msg,
+          code: 40400,
+          statusCode: 404,
+          hint: 'ClientOptions.key must be the full "appId.keyId:secret" string copied from the Ably dashboard. If you have the Ably CLI installed, `ably auth keys list` shows the keys configured on the current app.',
+        });
       }
       normalOptions.keyName = keyMatch[1];
       normalOptions.keySecret = keyMatch[2];
     }
 
     if ('clientId' in normalOptions) {
-      if (!(typeof normalOptions.clientId === 'string' || normalOptions.clientId === null))
-        throw new ErrorInfo('clientId must be either a string or null', 40012, 400);
-      else if (normalOptions.clientId === '*')
-        throw new ErrorInfo(
-          'Can’t use "*" as a clientId as that string is reserved. (To change the default token request behaviour to use a wildcard clientId, use {defaultTokenParams: {clientId: "*"}})',
-          40012,
-          400,
-        );
+      if (!(typeof normalOptions.clientId === 'string' || normalOptions.clientId === null)) {
+        throw new ErrorInfo({
+          message: 'clientId must be either a string or null',
+          code: 40012,
+          statusCode: 400,
+          hint: 'Pass a stable string such as a user id to identify the client, or null (or omit it) for an anonymous client. Values like numbers or objects are not accepted.',
+        });
+      } else if (normalOptions.clientId === '*') {
+        throw new ErrorInfo({
+          message: 'Can’t use "*" as a clientId as that string is reserved',
+          code: 40012,
+          statusCode: 400,
+          hint: 'ClientOptions.clientId sets one fixed identity and cannot be "*". To let this client act as any clientId, request a wildcard token instead: set defaultTokenParams: { clientId: "*" } on the client. The "*" belongs in the token request, not in ClientOptions.clientId.',
+        });
+      }
     }
 
     Logger.logAction(this.logger, Logger.LOG_MINOR, 'BaseClient()', 'started; version = ' + Defaults.version);

src/common/lib/client/baserealtime.ts

@@ -199,11 +199,13 @@ class Channels extends EventEmitter {
       channel = this.all[name] = new RealtimeChannel(this.realtime, name, channelOptions);
     } else if (channelOptions) {
       if (channel._shouldReattachToSetOptions(channelOptions, channel.channelOptions)) {
-        throw new ErrorInfo(
-          'Channels.get() cannot be used to set channel options that would cause the channel to reattach. Please, use RealtimeChannel.setOptions() instead.',
-          40000,
-          400,
-        );
+        throw new ErrorInfo({
+          message:
+            'Channels.get() cannot be used to set channel options that would cause the channel to reattach: channels.get() returns the existing channel instance.',
+          code: 40000,
+          statusCode: 400,
+          hint: 'To change params or modes on an existing channel, call channel.setOptions(opts) on the channel returned by channels.get(name). setOptions() re-attaches the channel to apply the new options.',
+        });
       }
       channel.setOptions(channelOptions);
     }

src/common/lib/client/paginatedresource.ts

@@ -147,15 +147,25 @@ export class PaginatedResult<T> {
       return this.get(this._relParams!.first);
     }
 
-    throw new ErrorInfo('No link to the first page of results', 40400, 404);
+    throw new ErrorInfo({
+      message: 'No link to the first page of results',
+      code: 40400,
+      statusCode: 404,
+      hint: 'first() is only available on results from a paginated REST query (such as channel history, presence, or stats), whose response includes a link to the first page. This result has no such link, so there is no first page to return.',
+    });
   }
 
   async current(): Promise<PaginatedResult<T>> {
     if (this.hasCurrent()) {
       return this.get(this._relParams!.current);
     }
 
-    throw new ErrorInfo('No link to the current page of results', 40400, 404);
+    throw new ErrorInfo({
+      message: 'No link to the current page of results',
+      code: 40400,
+      statusCode: 404,
+      hint: 'current() reloads the current page and is only available on results from a paginated REST query (such as channel history, presence, or stats). This result has no such link. To page through results, use next() with hasNext() or isLast() instead.',
+    });
   }
 
   async next(): Promise<PaginatedResult<T> | null> {

src/common/lib/client/push.ts

@@ -15,6 +15,14 @@ import type {
 import Platform from 'common/platform';
 import type { ErrCallback } from 'common/types/utils';
 
+// Keep this byte-identical to the copy in src/plugins/push/pushactivation.ts. The plugin only
+// type-imports from common client modules, so a value import here is not viable for the build.
+const PUSH_ACTIVATION_NOT_AVAILABLE_HINT =
+  'Run push.activate() in a browser environment with service worker support. From a server, use client.push.admin instead. Call client.push.admin.publish(recipient, payload) to send to a device or clientId. Call client.push.admin.deviceRegistrations.save(device) to register a device record.';
+
+const PUSH_DEACTIVATION_NOT_AVAILABLE_HINT =
+  'Run push.deactivate() in a browser environment with service worker support. From a server, call client.push.admin.deviceRegistrations.remove(deviceId) to remove a device registration.';
+
 class Push {
   client: BaseClient;
   admin: Admin;
@@ -37,11 +45,24 @@ class Push {
         return;
       }
       if (!this.stateMachine) {
-        reject(new ErrorInfo('This platform is not supported as a target of push notifications', 40000, 400));
+        const err = new ErrorInfo({
+          message:
+            'This platform is not supported as a target of push notifications: push activation requires a browser environment with service worker support',
+          code: 40000,
+          statusCode: 400,
+          hint: PUSH_ACTIVATION_NOT_AVAILABLE_HINT,
+        });
+        reject(err);
         return;
       }
       if (this.stateMachine.activatedCallback) {
-        reject(new ErrorInfo('Activation already in progress', 40000, 400));
+        const err = new ErrorInfo({
+          message: 'Activation already in progress',
+          code: 40000,
+          statusCode: 400,
+          hint: 'Await the in-flight push.activate() before calling it again.',
+        });
+        reject(err);
         return;
       }
       this.stateMachine.activatedCallback = (err: ErrorInfo) => {
@@ -65,11 +86,24 @@ class Push {
         return;
       }
       if (!this.stateMachine) {
-        reject(new ErrorInfo('This platform is not supported as a target of push notifications', 40000, 400));
+        const err = new ErrorInfo({
+          message:
+            'This platform is not supported as a target of push notifications: push activation requires a browser environment with service worker support',
+          code: 40000,
+          statusCode: 400,
+          hint: PUSH_DEACTIVATION_NOT_AVAILABLE_HINT,
+        });
+        reject(err);
         return;
       }
       if (this.stateMachine.deactivatedCallback) {
-        reject(new ErrorInfo('Deactivation already in progress', 40000, 400));
+        const err = new ErrorInfo({
+          message: 'Deactivation already in progress',
+          code: 40000,
+          statusCode: 400,
+          hint: 'Await the in-flight push.deactivate() before calling it again.',
+        });
+        reject(err);
         return;
       }
       this.stateMachine.deactivatedCallback = (err: ErrorInfo) => {
@@ -156,11 +190,12 @@ class DeviceRegistrations {
       deviceId = deviceIdOrDetails.id || deviceIdOrDetails;
 
     if (typeof deviceId !== 'string' || !deviceId.length) {
-      throw new ErrorInfo(
-        'First argument to DeviceRegistrations#get must be a deviceId string or DeviceDetails',
-        40000,
-        400,
-      );
+      throw new ErrorInfo({
+        message: 'First argument to DeviceRegistrations#get must be a deviceId string or DeviceDetails',
+        code: 40000,
+        statusCode: 400,
+        hint: 'Pass either the device id string or a DeviceDetails object with a non-empty .id field. The local device id is available from client.device().id after push.activate() completes. Alternatively pass the .id of a DeviceDetails returned by push.admin.deviceRegistrations.save().',
+      });
     }
 
     Utils.mixin(headers, client.options.headers);
@@ -209,11 +244,12 @@ class DeviceRegistrations {
       deviceId = deviceIdOrDetails.id || deviceIdOrDetails;
 
     if (typeof deviceId !== 'string' || !deviceId.length) {
-      throw new ErrorInfo(
-        'First argument to DeviceRegistrations#remove must be a deviceId string or DeviceDetails',
-        40000,
-        400,
-      );
+      throw new ErrorInfo({
+        message: 'First argument to DeviceRegistrations#remove must be a deviceId string or DeviceDetails',
+        code: 40000,
+        statusCode: 400,
+        hint: 'Pass either the device id string or the DeviceDetails object (with a non-empty .id field). To deactivate the local device, call client.push.deactivate() instead.',
+      });
     }
 
     Utils.mixin(headers, client.options.headers);

src/common/lib/client/realtimeannotations.ts

@@ -69,13 +69,15 @@ class RealtimeAnnotations {
       await channel.attach();
     }
 
-    // explicit check for attach state in caes attachOnSubscribe=false
+    // explicit check for attach state in case attachOnSubscribe=false
     if ((this.channel.state === 'attached' && this.channel._mode & flags.ANNOTATION_SUBSCRIBE) === 0) {
-      throw new ErrorInfo(
-        "You are trying to add an annotation listener, but you haven't requested the annotation_subscribe channel mode in ChannelOptions, so this won't do anything (we only deliver annotations to clients who have explicitly requested them)",
-        93001,
-        400,
-      );
+      throw new ErrorInfo({
+        message:
+          "You are trying to add an annotation listener, but you haven't requested the annotation_subscribe channel mode in ChannelOptions, so this won't do anything (we only deliver annotations to clients who have explicitly requested them)",
+        code: 93001,
+        statusCode: 400,
+        hint: 'Enable the mode on the channel with channel.setOptions({ modes: ["subscribe", "annotation_subscribe"] }), which re-attaches with the new mode (calling channels.get(name, { modes }) on an existing channel throws, and appending to channel.modes does not enable it server-side). If the re-attach is rejected by the server, confirm the channel namespace has "Message annotations, updates, appends, and deletes" enabled in the Ably dashboard and that your API key has annotation-subscribe capability on this channel. If you have the Ably CLI installed, `ably apps rules list` shows which namespaces have it enabled and `ably auth keys list` shows the capabilities of your key.',
+      });
     }
   }