feat: upgrade Twilio SDK to v5 and require as peer dependency

WHAT:
- Upgraded the core `twilio` Node.js helper library to v5.5.2 across
  relevant packages (`runtime-handler`, `create-twilio-function` defaults,
  test dependencies).
- Changed `@twilio-labs/serverless-runtime-types` and
  `@twilio-labs/twilio-run` to declare `twilio` as a `peerDependency`
  (^5.5.2) instead of a direct dependency.
- Updated internal type definitions (`ClientOpts`) for compatibility with
  `[email protected]`.
- Updated Twilio Console URL generation logic in `twilio-run`.
- Updated default dependencies (`typescript`, `serverlessRuntimeTypes`) used
  by `create-twilio-function`.

WHY:
- Aligns the toolkit with the latest Twilio SDK features, improvements, and
  security updates available in v5.
- Resolves potential version conflicts and type mismatches (e.g.,
  TS2322/TS2352) by ensuring a single `twilio` instance is used, managed
  explicitly by the consuming project. This promotes a more stable and
  predictable dependency graph.

BREAKING CHANGE:
Consumers of `@twilio-labs/twilio-run` or projects directly importing
types from `@twilio-labs/serverless-runtime-types` MUST now explicitly
install `twilio` as a direct dependency in their own project.

Add the `twilio` dependency:
```bash
npm install twilio@^5.5.2 --save-dev
yarn add twilio@^5.5.2 --dev
```

Author: mikefaille

.changeset/heavy-moose-appear.md

@@ -0,0 +1,27 @@
+---
+'@twilio-labs/serverless-runtime-types': major
+'twilio-run': major
+'create-twilio-function': minor
+'@twilio/runtime-handler': minor
+---
+
+feat: Upgrade Twilio SDK to v5 and use peer dependency
+
+**WHAT:**
+- Upgraded the core `twilio` Node.js helper library to v5.5.2 across the toolkit.
+- Changed `@twilio-labs/serverless-runtime-types` and `@twilio-labs/twilio-run` to require `twilio` as a `peerDependency` instead of a direct dependency.
+- Updated type definitions (`ClientOpts`) for compatibility with `[email protected]`.
+- Updated default dependencies (`twilio`, `typescript`, `serverlessRuntimeTypes`) used by `@twilio-labs/create-twilio-function`.
+
+**WHY:**
+- Aligns the toolkit with the latest Twilio SDK features, improvements, and security updates.
+- Resolves potential type conflicts (e.g., `TS2322`/`TS2352`) by ensuring a single `twilio` instance, managed by the user's project.
+
+**HOW:**
+**BREAKING CHANGE:** Users of `@twilio-labs/twilio-run` or projects importing types from `@twilio-labs/serverless-runtime-types` **must** now add `twilio` as a direct dependency to their project:
+```bash
+npm install twilio@^5.5.2
+# or
+yarn add twilio@^5.5.2
+```
+After updating toolkit packages and adding `twilio`, perform a clean install (delete `node_modules` and lock file, then run `npm install` or `yarn install`).

package.json

@@ -26,7 +26,7 @@
     "@changesets/cli": "^2.26.0",
     "@commitlint/cli": "^19.1.0",
     "@commitlint/config-conventional": "^19.1.0",
-    "@twilio/test-dep": "npm:twilio@4.22.0",
+    "@twilio/test-dep": "npm:twilio@5.2.2",
     "@types/jest": "^29.2.4",
     "all-contributors-cli": "^6.1.2",
     "commitizen": "^4.2.4",
@@ -45,6 +45,9 @@
     "typedoc": "^0.27.4",
     "typescript": "^5.3.3"
   },
+  "peerDependencies": {
+			"twilio": "^5.5.2"
+  },		
   "lint-staged": {
     "*.{js,jsx,ts,tsx}": [
       "prettier --write",

packages/create-twilio-function/package.json

@@ -24,7 +24,7 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@twilio/runtime-handler": "^2.0.3",
+    "@twilio/runtime-handler": "^2.1.0",
     "nock": "^11.3.4"
   },
   "dependencies": {

packages/create-twilio-function/src/create-twilio-function/versions.js

@@ -1,13 +1,13 @@
 const pkgJson = require('../../package.json');
 
 module.exports = {
-  twilio: '5.0.3',
+  twilio: '5.5.2',
   twilioRuntimeHandler: pkgJson.devDependencies[
     '@twilio/runtime-handler'
   ].replace(/[\^~]/, ''),
   twilioRun: pkgJson.dependencies['twilio-run'],
   node: '18',
-  typescript: '^5.3.3',
-  serverlessRuntimeTypes: '^4.0.0',
+  typescript: '^5.8.0',
+  serverlessRuntimeTypes: '^4.0.1',
   copyfiles: '^2.4.1',
 };

packages/runtime-handler/package.json

@@ -70,7 +70,7 @@
     "nocache": "^2.1.0",
     "normalize.css": "^8.0.1",
     "serialize-error": "^7.0.1",
-    "twilio": "4.23.0"
+    "twilio": "5.5.2"
   },
   "gitHead": "6db273648ed19474f4125042556b10c051529912"
 }

packages/serverless-runtime-types/README.md

@@ -22,6 +22,17 @@
 npm install @twilio-labs/serverless-runtime-types
 ```
 
+**Peer Dependency Requirement:**
+
+This package requires the core `twilio` Node.js library as a **peer dependency** (version `^5.5.2` or compatible). This is necessary to ensure type consistency and prevent version conflicts within your project.
+
+**You MUST explicitly install both `@twilio-labs/serverless-runtime-types` and a compatible version of `twilio` in your project.**
+
+```bash
+# Using npm
+npm install @twilio-labs/serverless-runtime-types twilio@^5.5.2 --save-dev
+```
+
 ## Example
 
 ### In JavaScript

packages/serverless-runtime-types/package.json

@@ -29,12 +29,14 @@
   },
   "dependencies": {
     "@types/express": "^4.17.21",
-    "@types/qs": "^6.9.4",
-    "twilio": "^4.23.0"
+    "@types/qs": "^6.9.4"
   },
+  "peerDependencies": {
+		"twilio": "^5.5.2"
+  },		
   "devDependencies": {
     "all-contributors-cli": "^6.7.0",
-    "typescript": "^5.3.3"
+    "typescript": "^5.8.0"
   },
   "publishConfig": {
     "access": "public"

packages/serverless-runtime-types/types.d.ts

@@ -2,7 +2,7 @@ import * as twilio from 'twilio';
 import { ServiceContext } from 'twilio/lib/rest/sync/v1/service';
 import { SyncListListInstance } from 'twilio/lib/rest/sync/v1/service/syncList';
 import { SyncMapListInstance } from 'twilio/lib/rest/sync/v1/service/syncMap';
-import { TwilioClientOptions } from 'twilio/lib/rest/Twilio';
+import { ClientOpts } from 'twilio';
 
 export type EnvironmentVariables = {
   [key: string]: string | undefined;
@@ -187,7 +187,7 @@ export interface TwilioResponse {
   removeCookie(key: string): TwilioResponse;
 }
 
-export type RuntimeSyncClientOptions = TwilioClientOptions & {
+export type RuntimeSyncClientOptions = ClientOpts & {
   serviceName?: string;
 };
 
@@ -360,7 +360,7 @@ export type Context<T = {}> = {
    * };
    * ```
    */
-  getTwilioClient(options?: TwilioClientOptions): twilio.Twilio;
+  getTwilioClient(options?: ClientOpts): twilio.Twilio;
   /**
    * The domain name for the Service that contains this Function.
    */
@@ -412,6 +412,7 @@ export type GlobalTwilio = Omit<typeof twilio, 'default'> & {
 export { ServiceContext } from 'twilio/lib/rest/sync/v1/service';
 export { SyncListListInstance } from 'twilio/lib/rest/sync/v1/service/syncList';
 export { SyncMapListInstance } from 'twilio/lib/rest/sync/v1/service/syncMap';
-export { TwilioClientOptions } from 'twilio/lib/rest/Twilio';
+export { ClientOpts as TwilioClientOptions } from 'twilio/lib/rest/Twilio';
+
 export type TwilioClient = twilio.Twilio;
 export type TwilioPackage = typeof twilio;

packages/twilio-run/package.json

@@ -76,12 +76,14 @@
     "serialize-error": "^7.0.1",
     "terminal-link": "^1.3.0",
     "title": "^3.4.1",
-    "twilio": "^4.23.0",
     "type-fest": "^0.15.1",
     "window-size": "^1.1.1",
     "wrap-ansi": "^7.0.0",
     "yargs": "^17.2.1"
   },
+  "peerDependencies": {
+	  "twilio": "^5.5.2"
+	},		
   "optionalDependencies": {
     "ngrok": "^3.3.0"
   },
@@ -113,7 +115,7 @@
     "nock": "^12.0.2",
     "supertest": "^3.1.0",
     "typescript": "^4.9.4",
-    "@twilio/test-dep": "npm:twilio@4.22.0"
+    "@twilio/test-dep": "npm:twilio@5.5.2"
   },
   "files": [
     "bin/",

packages/twilio-run/src/runtime/internal/runtime.ts

@@ -16,7 +16,7 @@ import { getDebugFunction } from '../../utils/logger';
 
 const debug = getDebugFunction('twilio-run:runtime');
 
-const { getCachedResources } = require('./route-cache');
+import { getCachedResources } from './route-cache';
 
 function getAssets(): AssetResourceMap {
   const { assets } = getCachedResources();
@@ -72,9 +72,9 @@ export function create({ env }: StartCliConfig): RuntimeInstance {
         .join(',')})`,
     });
     const client = twilio(env.ACCOUNT_SID, env.AUTH_TOKEN, options);
-    const service = (client.sync.v1.services(
+    const service = client.sync.v1.services(
       serviceName || 'default'
-    ) as unknown) as RuntimeSyncServiceContext;
+    ) as unknown as RuntimeSyncServiceContext;
 
     service.maps = service.syncMaps;
     service.lists = service.syncLists;