DX-1205: throw on legacy v1 ably/promises and ably/callbacks imports

Add subpath exports for the two v1 entry points (callbacks.js and
promises.js at the package root, both removed in mid-2023 during v2
prep) so that code written against v1 — or generated by an LLM trained
on v1 docs — fails on import with an actionable migration message
instead of Node's generic ERR_PACKAGE_PATH_NOT_EXPORTED.

The .js shims throw at module load; the .d.ts siblings keep
`@arethetypeswrong/cli` happy across node10/node16/bundler resolution
modes, carry an `@deprecated` tag for IDE hovers, and resolve to `never`
so any property access errors at compile time. URL points at the
in-repo migration guide, matching the convention from DX-1204
(src/common/lib/util/utils.ts:293).

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

Author: umair-ably

callbacks.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @deprecated `'ably/callbacks'` was the v1 callback API entry point and has been removed in ably-js v2.
+ * v2 is promise-only — import from `'ably'` directly and switch to `await` / `.then()`.
+ *
+ * Importing this subpath throws at module load with the migration link.
+ *
+ * @see https://github.com/ably/ably-js/blob/main/docs/migration-guides/v2/lib.md
+ */
+declare const ablyCallbacksV1EntryPointRemoved: never;
+export = ablyCallbacksV1EntryPointRemoved;

callbacks.js

@@ -0,0 +1,5 @@
+'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",
+);

package.json

@@ -39,14 +39,26 @@
         "types": "./liveobjects.d.ts",
         "default": "./build/liveobjects.js"
       }
+    },
+    "./promises": {
+      "types": "./promises.d.ts",
+      "default": "./promises.js"
+    },
+    "./callbacks": {
+      "types": "./callbacks.d.ts",
+      "default": "./callbacks.js"
     }
   },
   "files": [
     "build/**",
     "ably.d.ts",
+    "callbacks.d.ts",
+    "callbacks.js",
     "liveobjects.d.ts",
     "liveobjects.d.mts",
     "modular.d.ts",
+    "promises.d.ts",
+    "promises.js",
     "push.d.ts",
     "resources/**",
     "src/**",

promises.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @deprecated `'ably/promises'` was the v1 entry point and is no longer available in ably-js v2.
+ * v2 is promise-only — import from `'ably'` directly.
+ *
+ * Importing this subpath throws at module load with the migration link.
+ *
+ * @see https://github.com/ably/ably-js/blob/main/docs/migration-guides/v2/lib.md
+ */
+declare const ablyPromisesV1EntryPointRemoved: never;
+export = ablyPromisesV1EntryPointRemoved;

promises.js

@@ -0,0 +1,5 @@
+'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",
+);

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

@@ -0,0 +1,56 @@
+'use strict';
+
+define(['chai'], function (chai) {
+  const { expect } = chai;
+  const fs = require('fs');
+  const path = require('path');
+  const repoRoot = path.resolve(__dirname, '..', '..');
+
+  describe('legacy v1 import-path shims', function () {
+    function loadShim(relPath) {
+      const abs = path.join(repoRoot, relPath);
+      delete require.cache[abs];
+      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/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('package.json exports map wires the legacy subpaths to the shim files and their types', function () {
+      const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+
+      expect(pkg.exports['./promises'], "exports['./promises']").to.deep.equal({
+        types: './promises.d.ts',
+        default: './promises.js',
+      });
+      expect(pkg.exports['./callbacks'], "exports['./callbacks']").to.deep.equal({
+        types: './callbacks.d.ts',
+        default: './callbacks.js',
+      });
+
+      for (const file of ['promises.js', 'promises.d.ts', 'callbacks.js', 'callbacks.d.ts']) {
+        expect(fs.existsSync(path.join(repoRoot, file)), file).to.equal(true);
+      }
+    });
+
+    it("'files' array ships the legacy shim files in the published package", function () {
+      const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+      for (const file of ['promises.js', 'promises.d.ts', 'callbacks.js', 'callbacks.d.ts']) {
+        expect(pkg.files, `files[] should include ${file}`).to.include(file);
+      }
+    });
+  });
+});