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

mikefaille · mikefaille · commit 26353ae886e4 · 2025-04-20T03:09:59.000-07:00
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
  `twilio@5.x`.
- 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
```
diff --git a/.changeset/heavy-moose-appear.md b/.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 `twilio@5.x`.
+- 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`).
diff --git a/package.json b/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",
diff --git a/packages/create-twilio-function/package.json b/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": {
diff --git a/packages/create-twilio-function/src/create-twilio-function/versions.js b/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',
 };
diff --git a/packages/runtime-handler/package.json b/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"
 }
diff --git a/packages/serverless-runtime-types/README.md b/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
diff --git a/packages/serverless-runtime-types/package.json b/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"
diff --git a/packages/serverless-runtime-types/types.d.ts b/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;
diff --git a/packages/twilio-run/package.json b/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/",
diff --git a/packages/twilio-run/src/commands/promote.ts b/packages/twilio-run/src/commands/promote.ts
@@ -94,7 +94,7 @@ export async function handler(
         config.targetEnvironment || 'production'
       }`
     );
-    printActivateResult(result, config.outputFormat);
+    printActivateResult(result, config.outputFormat, config.region);
   } catch (err) {
     handleError(err, spinner);
   }
diff --git a/packages/twilio-run/src/printers/activate.ts b/packages/twilio-run/src/printers/activate.ts
@@ -25,7 +25,8 @@ export function printActivateConfig(
 
 export function printActivateResult(
   result: ActivateResult,
-  outputFormat: OutputFormat
+  outputFormat: OutputFormat,
+  region = 'us1'
 ) {
   if (outputFormat === 'json') {
     writeJSONOutput(result);
@@ -36,7 +37,11 @@ export function printActivateResult(
 
   const twilioConsoleLogsLink = terminalLink(
     'Open the Twilio Console',
-    getTwilioConsoleDeploymentUrl(result.serviceSid, result.environmentSid),
+    getTwilioConsoleDeploymentUrl(
+      result.serviceSid,
+      result.environmentSid,
+      region
+    ),
     {
       fallback: (text: string, url: string) => chalk.dim(url),
     }
diff --git a/packages/twilio-run/src/printers/deploy.ts b/packages/twilio-run/src/printers/deploy.ts
@@ -64,7 +64,8 @@ function plainPrintDeployedResources(
     runtime: result.runtime,
     viewLiveLogs: getTwilioConsoleDeploymentUrl(
       result.serviceSid,
-      result.environmentSid
+      result.environmentSid,
+      config.region
     ),
   };
 
@@ -132,7 +133,11 @@ function prettyPrintDeployedResources(
 ) {
   const twilioConsoleLogsLink = terminalLink(
     'Open the Twilio Console',
-    getTwilioConsoleDeploymentUrl(result.serviceSid, result.environmentSid),
+    getTwilioConsoleDeploymentUrl(
+      result.serviceSid,
+      result.environmentSid,
+      config.region
+    ),
     {
       fallback: (text: string, url: string) => chalk.dim(url),
     }
@@ -159,8 +164,7 @@ function prettyPrintDeployedResources(
     const functionMessage = result.functionResources
       .sort(sortByAccess)
       .map((fn) => {
-        const accessPrefix =
-          chalk`{bold [${fn.access}]} `;
+        const accessPrefix = chalk`{bold [${fn.access}]} `;
         return chalk`   ${accessPrefix}{dim https://${result.domain}}${fn.path}`;
       })
       .join('\n');
@@ -172,8 +176,7 @@ function prettyPrintDeployedResources(
     const assetMessage = result.assetResources
       .sort(sortByAccess)
       .map((asset) => {
-        const accessPrefix =
-          chalk`{bold [${asset.access}]} `;
+        const accessPrefix = chalk`{bold [${asset.access}]} `;
         const accessUrl =
           asset.access === 'private'
             ? chalk`{dim Runtime.getAssets()['}${asset.path}{dim ']}`
@@ -223,7 +226,8 @@ export function printJsonDeployedResources(
     runtime: result.runtime,
     viewLiveLogs: getTwilioConsoleDeploymentUrl(
       result.serviceSid,
-      result.environmentSid
+      result.environmentSid,
+      config.region
     ),
     functions: result.functionResources.sort(sortByAccess).map(formatResource),
     assets: result.assetResources.sort(sortByAccess).map(formatResource),
diff --git a/packages/twilio-run/src/printers/utils.ts b/packages/twilio-run/src/printers/utils.ts
@@ -11,9 +11,10 @@ export const supportsEmoji =
 
 export function getTwilioConsoleDeploymentUrl(
   serviceSid: string,
-  environmentSid: string
+  environmentSid: string,
+  region = 'us1'
 ) {
-  return `https://www.twilio.com/console/functions/editor/${serviceSid}/environment/${environmentSid}`;
+  return `https://console.twilio.com/${region}/develop/functions/editor/${serviceSid}/environment/${environmentSid}`;
 }
 
 export function printObjectWithoutHeaders(obj: {}): string {
@@ -27,7 +28,7 @@ export function terminalLink(name: string, link: string): string {
 export function borderLeft(text: string, color: string): string {
   return text
     .split('\n')
-    .map(str => `${chalk.keyword(color)('│')} ${str}`)
+    .map((str) => `${chalk.keyword(color)('│')} ${str}`)
     .join('\n');
 }
 
diff --git a/packages/twilio-run/src/runtime/internal/runtime.ts b/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;
diff --git a/packages/twilio-run/src/runtime/route.ts b/packages/twilio-run/src/runtime/route.ts
@@ -4,6 +4,7 @@ import {
   ServerlessEventObject,
   ServerlessFunctionSignature,
 } from '@twilio-labs/serverless-runtime-types/types';
+
 import { fork } from 'child_process';
 import {
   NextFunction,
@@ -23,7 +24,6 @@ import { cleanUpStackTrace } from '../utils/stack-trace/clean-up';
 import { Reply } from './internal/functionRunner';
 import { Response } from './internal/response';
 import * as Runtime from './internal/runtime';
-import * as PATH from 'path';
 
 const RUNNER_PATH =
   process.env.NODE_ENV === 'test'
@@ -40,7 +40,7 @@ export function constructEvent<T extends ServerlessEventObject>(
   return { ...req.query, ...req.body };
 }
 
-export function constructContext<T extends {} = {}>(
+export function constructContext(
   { url, env }: StartCliConfig,
   functionPath: string
 ): Context<{

Original file line number	Diff line number	Diff line change
`@@ -70,7 +70,7 @@`
`70`	`70`	`"nocache": "^2.1.0",`
`71`	`71`	`"normalize.css": "^8.0.1",`
`72`	`72`	`"serialize-error": "^7.0.1",`
`73`		`- "twilio": "4.23.0"`
	`73`	`+ "twilio": "5.5.2"`
`74`	`74`	`},`
`75`	`75`	`"gitHead": "6db273648ed19474f4125042556b10c051529912"`
`76`	`76`	`}`
Original file line number	Diff line number	Diff line change
`@@ -94,7 +94,7 @@ export async function handler(`
`94`	`94`	`config.targetEnvironment \|\| 'production'`
`95`	`95`	}`
`96`	`96`	`);`
`97`		`- printActivateResult(result, config.outputFormat);`
	`97`	`+ printActivateResult(result, config.outputFormat, config.region);`
`98`	`98`	`} catch (err) {`
`99`	`99`	`handleError(err, spinner);`
`100`	`100`	`}`