feat!: Merge branch '4.0.0-rc' to main (#883)

.eslintrc.json

@@ -117,7 +117,7 @@
     ],
     "quotes": [
       2,
-      "single"
+      "double"
     ],
     "indent": [
       2,

.github/workflows/test-and-deploy.yml

@@ -17,7 +17,7 @@ jobs:
     timeout-minutes: 20
     strategy:
       matrix:
-        node: [ 6, 8, 10, 12, 14, 16, lts/* ]
+        node: [ 14, 16, 18, lts/* ]
     steps:
       - name: Checkout twilio-node
         uses: actions/checkout@v3
@@ -33,6 +33,16 @@ jobs:
       - name: Run Unit Tests
         run: npm run ci
 
+      - name: Run Cluster Tests
+        if: (!github.event.pull_request.head.repo.fork)
+        env:
+          TWILIO_ACCOUNT_SID: ${{ secrets.TWILIO_ACCOUNT_SID }}
+          TWILIO_API_KEY: ${{ secrets.TWILIO_CLUSTER_TEST_API_KEY}}
+          TWILIO_API_SECRET: ${{ secrets.TWILIO_CLUSTER_TEST_API_KEY_SECRET }}
+          TWILIO_FROM_NUMBER: ${{ secrets.TWILIO_FROM_NUMBER }}
+          TWILIO_TO_NUMBER: ${{ secrets.TWILIO_TO_NUMBER }}
+        run: npm run cluster
+
       - name: SonarCloud Scan
         if: ${{ (github.event_name == 'pull_request' || github.ref_type == 'branch') && matrix.node == 'lts/*' && !github.event.pull_request.head.repo.fork }}
         uses: SonarSource/sonarcloud-github-action@master

.gitignore

@@ -1,4 +1,4 @@
-### Logs ###
+### Logs ###
 logs
 *.log
 
@@ -14,13 +14,13 @@ pids
 node_modules
 
 ### Test coverage ###
-spec/coverage
+coverage
 
 ### Custom ignores ###
 config.js
 .idea
 
-### jsdoc dir ###
+### typedoc dir ###
 docs
 
 ### ide / editors ###
@@ -29,3 +29,6 @@ docs
 ### Libraries don't need locks files ###
 yarn.lock
 package-lock.json
+
+**/.openapi-generator*
+dist

.jshintrc

@@ -44,7 +44,7 @@
   "newcap": true,
 
   // Enforce use of single quotation marks for strings.
-  "quotmark": "single",
+  "quotmark": "double",
 
   // Enforce placing 'use strict' at the top function scope
   "strict": true,

.prettierignore

@@ -0,0 +1,8 @@
+.github
+coverage
+dist
+docs
+
+babel.config.js
+*.md
+*.json

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:12.17
+FROM node:14
 
 RUN mkdir /twilio
 WORKDIR /twilio
@@ -8,7 +8,9 @@ ENV NODE_PATH /usr/local/lib/node_modules
 COPY lib ./lib
 COPY spec ./spec
 COPY examples ./examples
-COPY index.js .
-COPY package* ./
+COPY index.ts package.json babel.config.js tsconfig.json ./
+
+RUN npm config set unsafe-perm true # Needed to run prepublish as root.
 
 RUN npm install . --include=dev
+RUN npm install -g .

Makefile

@@ -1,25 +1,24 @@
-.PHONY: test-install install test test-docker docs clean
+.PHONY: test-install install test test-docker docs clean prettier
 
 test-install:
 	npm install --only=dev
 
 install:
-	@node --version || (echo "Node is not installed, please install Node >= 0.12"; exit 1);
+	@node --version || (echo "Node is not installed, please install Node >= 14"; exit 1);
 	rm -f package-lock.json
 	npm install
 
 test:
 	npm test
 
-test-docker:
-	docker build -t twilio/twilio-node .
-	docker run twilio/twilio-node npm run ci
-
 docs:
-	npm run jsdoc
+	npm run typedoc
 
 clean:
-	rm -rf node_modules
+	rm -rf node_modules dist
+
+prettier:
+	npm run prettier
 
 API_DEFINITIONS_SHA=$(shell git log --oneline | grep Regenerated | head -n1 | cut -d ' ' -f 5)
 CURRENT_TAG=$(shell expr "${GITHUB_TAG}" : ".*-rc.*" >/dev/null && echo "rc" || echo "latest")

PULL_REQUEST_TEMPLATE.md

@@ -12,6 +12,8 @@ Please enter each Issue number you are resolving in your PR after one of the fol
 e.g.
 Fixes #1
 Closes #2
+
+Note: If you made changes to the Request Validation logic, please run `npm run webhook-test` locally and ensure all test cases pass
 -->
 
 # Fixes #

README.md

@@ -19,25 +19,16 @@ The Node library documentation can be found [here][libdocs].
 
 This library supports the following Node.js implementations:
 
-* Node.js 6
-* Node.js 8
-* Node.js 10
-* Node.js 12
 * Node.js 14
 * Node.js 16
+* Node.js 18
 
 TypeScript is supported for TypeScript version 2.9 and above.
 
 ## Installation
 
 `npm install twilio` or `yarn add twilio`
 
-### Installing Release Candidates
-
-Or, if you're wanting to install the latest release candidate use:
-
-`npm install twilio@rc` or `yarn add twilio@rc`
-
 ## Sample Usage
 
 Check out these [code examples](examples) in JavaScript and TypeScript to get up and running quickly.
@@ -48,15 +39,44 @@ Check out these [code examples](examples) in JavaScript and TypeScript to get up
 
 If your environment requires SSL decryption, you can set the path to CA bundle in the env var `TWILIO_CA_BUNDLE`.
 
+### Client Initialization
+If you invoke any V2010 operations without specifying an account SID, `twilio-node` will automatically use the `TWILIO_ACCOUNT_SID` value that the client was initialized with. This is useful for when you'd like to, for example, fetch resources for your main account but also your subaccount. See below:
+
+```javascript
+var accountSid = process.env.TWILIO_ACCOUNT_SID; // Your Account SID from www.twilio.com/console
+var authToken = process.env.TWILIO_AUTH_TOKEN;   // Your Auth Token from www.twilio.com/console
+var subaccountSid = process.env.TWILIO_ACCOUNT_SUBACCOUNT_SID; // Your Subaccount SID from www.twilio.com/console
+
+const client = require('twilio')(accountSid, authToken);
+const mainAccountCalls = client.api.v2010.account.calls.list; // SID not specified, so defaults to accountSid
+const subaccountCalls = client.api.v2010.account(subaccountSid).calls.list // SID specified as subaccountSid
+```
+
 ### Lazy Loading
 
-`twilio-node` supports lazy loading required modules for faster loading time. Lazy loading is disabled by default. To enable lazy loading, simply instantiate the Twilio client with the `lazyLoading` flag set to `true`:
+`twilio-node` supports lazy loading required modules for faster loading time. Lazy loading is enabled by default. To disable lazy loading, simply instantiate the Twilio client with the `lazyLoading` flag set to `false`:
+```javascript
+var accountSid = process.env.TWILIO_ACCOUNT_SID; // Your Account SID from www.twilio.com/console
+var authToken = process.env.TWILIO_AUTH_TOKEN;   // Your Auth Token from www.twilio.com/console
+
+const client = require('twilio')(accountSid, authToken, {
+    lazyLoading: false
+});
+```
+
+### Enable Auto-Retry with Exponential Backoff
+
+`twilio-node` supports automatic retry with exponential backoff when API requests receive an [Error 429 response](https://support.twilio.com/hc/en-us/articles/360044308153-Twilio-API-response-Error-429-Too-Many-Requests-). This retry with exponential backoff feature is disabled by default. To enable this feature, instantiate the Twilio client with the `autoRetry` flag set to `true`.
+
+Optionally, the maximum number of retries performed by this feature can be set with the `maxRetries` flag. The default maximum number of retries is `3`.
+
 ```javascript
 var accountSid = process.env.TWILIO_ACCOUNT_SID; // Your Account SID from www.twilio.com/console
 var authToken = process.env.TWILIO_AUTH_TOKEN;   // Your Auth Token from www.twilio.com/console
 
 const client = require('twilio')(accountSid, authToken, {
-    lazyLoading: true
+    autoRetry: true,
+    maxRetries: 3
 });
 ```
 

UPGRADE.md

@@ -1,6 +1,56 @@
-Upgrade Guide
+# Upgrade Guide
 
-After 3.0.0 all MINOR and MAJOR version bumps will have upgrade notes posted here.
+_All `MAJOR` version bumps will have upgrade notes posted here._
+
+[2023-01-25] 3.x.x to 4.x.x
+-----------------------------
+
+* Supported Node.js versions updated
+  * Upgrade to Node.js >= 14
+  * Dropped support for Node.js < 14 ([#791](https://github.com/twilio/twilio-node/pull/791))
+  * Added support for Node.js 18 ([#794](https://github.com/twilio/twilio-node/pull/794))
+* Lazy loading enabled by default ([#752](https://github.com/twilio/twilio-node/pull/752))
+  * Required Twilio modules now lazy load by default
+  * See the [README](README.md) for how to disable lazy loading
+* Type changes from `object` to `Record` ([#873](https://github.com/twilio/twilio-node/pull/873))
+  * Certain response properties now use the `Record` type with `string` keys
+  * Including the `subresourceUris` property for v2010 APIs and the `links` properties for non-v2010 APIs
+* Creating an AccessToken requires an `identity` in the options ([#875](https://github.com/twilio/twilio-node/pull/875))
+* JWT token building deprecations
+  * `ConversationsGrant` has been deprecated in favor of `VoiceGrant` ([#783](https://github.com/twilio/twilio-node/pull/783))
+  * `IpMessagingGrant` has been removed ([#784](https://github.com/twilio/twilio-node/pull/784))
+* TwiML function deprecations ([#788](https://github.com/twilio/twilio-node/pull/788))
+  * `Refer.referSip()` replaced by `Refer.sip()`
+  * `ssmlBreak()` replaced by `break_()`
+  * `ssmlEmphasis()` replaced by `emphasis()`
+  * `ssmlLang()` replaced by `lang()`
+  * `ssmlP()` replaced by `p()`
+  * `ssmlPhoneme()` replaced by `phoneme()`
+  * `ssmlProsody()` replaced by `prosody()`
+  * `ssmlS()` replaced by `s()`
+  * `ssmlSayAs()` replaced by `sayAs()`
+  * `ssmlSub()` replaced by `sub()`
+  * `ssmlW()` replaced by `w()`
+    * Old:
+    ```js
+    const response = new VoiceResponse();
+    const say = response.say("Hello");
+    say.ssmlEmphasis("you");
+    ```
+    * New:
+    ```js
+    const response = new VoiceResponse();
+    const say = response.say("Hello");
+    say.emphasis("you");
+    ```
+* TaskRouter Workers Statistics operations updated ([#820](https://github.com/twilio/twilio-node/pull/820))
+  * Cumulative and Real-Time Workers Statistics no longer accept a WorkerSid
+  * `GET /v1/Workspaces/{WorkspaceSid}/Workers/CumulativeStatistics`
+    * Old: `client.taskrouter.v1.workspaces('WS...').workers('WK...).cumulativeStatistics()`
+    * New: `client.taskrouter.v1.workspaces('WS...').workers.cumulativeStatistics()`
+  * `GET /v1/Workspaces/{WorkspaceSid}/Workers/RealTimeStatistics`
+    * Old: `client.taskrouter.v1.workspaces('WS...').workers('WK...).realTimeStatistics()`
+    * New: `client.taskrouter.v1.workspaces('WS...').workers.realTimeStatistics()`
 
 [2017-05-22] 3.1.x to 3.2.x
 ---------------------------

babel.config.js

@@ -0,0 +1,9 @@
+module.exports = {
+  presets: [
+    ['@babel/preset-env', {targets: {node: 'current'}}],
+    '@babel/preset-typescript',
+  ],
+  plugins: [
+    'babel-plugin-replace-ts-export-assignment',
+  ],
+};

cluster_test.spec.ts

@@ -0,0 +1,94 @@
+jest.setTimeout(15000);
+
+import twilio from "./lib/";
+
+const fromNumber = process.env.TWILIO_FROM_NUMBER;
+const toNumber = process.env.TWILIO_TO_NUMBER;
+const apiKey = process.env.TWILIO_API_KEY;
+const apiSecret = process.env.TWILIO_API_SECRET;
+const accountSid = process.env.TWILIO_ACCOUNT_SID;
+const testClient = twilio(apiKey, apiSecret, { accountSid });
+const twiml = new twilio.twiml.VoiceResponse();
+
+test("Should send a text", () => {
+  return testClient.messages
+    .create({
+      body: "hello world",
+      to: toNumber,
+      from: fromNumber,
+    })
+    .then((msg) => {
+      expect(msg.sid).not.toBeUndefined();
+      expect(msg.to).toBe(toNumber);
+      expect(msg.from).toBe(fromNumber);
+      expect(msg.body).toBe("hello world");
+    });
+});
+
+test("Should list incoming numbers", () => {
+  return testClient.incomingPhoneNumbers.list().then((incomingPhoneNumbers) => {
+    expect(incomingPhoneNumbers).not.toBeNull();
+    expect(incomingPhoneNumbers.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+test("Should list a incoming number", () => {
+  return testClient.incomingPhoneNumbers
+    .list({ limit: 1 })
+    .then((incomingPhoneNumbers) => {
+      expect(incomingPhoneNumbers).not.toBeUndefined();
+      expect(incomingPhoneNumbers.length).toEqual(1);
+    });
+});
+
+test("Should allow special characters for friendly and identity name", async () => {
+  const friendlyName = "service|friendly&name";
+  const identityName = "user|identity&string";
+  const conversation = await testClient.conversations.v1.conversations.create({
+    friendlyName: friendlyName,
+  });
+  const participant = await testClient.conversations.v1
+    .conversations(conversation.sid)
+    .participants.create({ identity: identityName });
+
+  expect(conversation).not.toBeNull();
+  expect(participant).not.toBeNull();
+  expect(conversation.friendlyName).toBe(friendlyName);
+  expect(participant.identity).toBe(identityName);
+
+  const removeConversation = await testClient.conversations.v1
+    .conversations(conversation.sid)
+    .remove();
+
+  expect(removeConversation).toBeTruthy();
+});
+
+test("Should list available numbers", () => {
+  return testClient
+    .availablePhoneNumbers("US")
+    .tollFree.list({ limit: 2 })
+    .then((tollFree) => {
+      expect(tollFree).not.toBeNull();
+      expect(tollFree.length).toEqual(2);
+    });
+});
+
+test("Should call with twiml string", () => {
+  return testClient.calls
+    .create({
+      twiml: twiml.toString(),
+      to: toNumber,
+      from: fromNumber,
+    })
+    .then((call) => expect(call.sid).toBeDefined());
+});
+
+test("Should call with twiml object", () => {
+  return testClient.calls
+    .create({
+      twiml: twiml,
+      to: toNumber,
+      from: fromNumber,
+    })
+    .then((call) => expect(call.sid).toBeDefined());
+});