DX-1205: split legacy import-shim throws into message + hint

Aligns with the DX-1204 / DX-1209 convention that ErrorInfo throws separate
*what failed* (message) from *how to fix it* (hint). The shims still throw
plain Error rather than ErrorInfo — pulling in ErrorInfo would mean
require'ing the built bundle just to throw, which defeats the point of a
top-level alias shim.

- promises.js / callbacks.js: stamp .hint on the thrown Error.
- Tests assert on err.message + err.hint separately (drift-pin against
  silent rephrasing).

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

Author: umair-ably

callbacks.js

@@ -1,5 +1,6 @@
 'use strict';
 
-throw new Error(
-  "'ably/callbacks' was the v1 callback API entry point and is no longer available. ably-js v2 is promise-only — import from 'ably' directly and switch to await / .then(). See https://github.com/ably/ably-js/blob/main/docs/migration-guides/v2/lib.md",
-);
+const err = new Error("'ably/callbacks' was the v1 callback API entry point and is no longer available.");
+err.hint =
+  "ably-js v2 is promise-only — import from 'ably' directly and switch to await / .then(). See https://github.com/ably/ably-js/blob/main/docs/migration-guides/v2/lib.md";
+throw err;

promises.js

@@ -1,5 +1,6 @@
 'use strict';
 
-throw new Error(
-  "'ably/promises' was the v1 entry point. ably-js v2 is promise-only — import from 'ably' directly. See https://github.com/ably/ably-js/blob/main/docs/migration-guides/v2/lib.md",
-);
+const err = new Error("'ably/promises' was the v1 entry point and is no longer available.");
+err.hint =
+  "ably-js v2 is promise-only — import from 'ably' directly. See https://github.com/ably/ably-js/blob/main/docs/migration-guides/v2/lib.md";
+throw err;

test/unit/legacy-import-shims.test.js

@@ -13,20 +13,32 @@ define(['chai'], function (chai) {
       require(abs);
     }
 
-    it("'ably/promises' shim throws naming the v1 entry point and migration guide", function () {
-      expect(() => loadShim('promises.js'))
-        .to.throw(Error)
-        .with.property('message')
-        .that.matches(/'ably\/promises' was the v1 entry point/)
-        .and.matches(/migration-guides\/v2\/lib\.md/);
+    it("'ably/promises' shim throws naming the v1 entry point, with a hint pointing at the migration guide", function () {
+      let caught;
+      try {
+        loadShim('promises.js');
+      } catch (err) {
+        caught = err;
+      }
+      expect(caught).to.be.an.instanceOf(Error);
+      expect(caught.message).to.match(/'ably\/promises' was the v1 entry point/);
+      expect(caught.hint).to.be.a('string');
+      expect(caught.hint).to.match(/promise-only/);
+      expect(caught.hint).to.match(/migration-guides\/v2\/lib\.md/);
     });
 
-    it("'ably/callbacks' shim throws naming the v1 callback API and migration guide", function () {
-      expect(() => loadShim('callbacks.js'))
-        .to.throw(Error)
-        .with.property('message')
-        .that.matches(/'ably\/callbacks' was the v1 callback API entry point/)
-        .and.matches(/migration-guides\/v2\/lib\.md/);
+    it("'ably/callbacks' shim throws naming the v1 callback API, with a hint pointing at the migration guide", function () {
+      let caught;
+      try {
+        loadShim('callbacks.js');
+      } catch (err) {
+        caught = err;
+      }
+      expect(caught).to.be.an.instanceOf(Error);
+      expect(caught.message).to.match(/'ably\/callbacks' was the v1 callback API entry point/);
+      expect(caught.hint).to.be.a('string');
+      expect(caught.hint).to.match(/await/);
+      expect(caught.hint).to.match(/migration-guides\/v2\/lib\.md/);
     });
 
     it('package.json exports map wires the legacy subpaths to the shim files and their types', function () {