telnyx 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -1,4 +1,6 @@
 # CHANGELOG
+### v1.24.0
+- Security Updates + API Additions
 
 ### v1.23.0 (2021-10-19)
 - **Addresses** added `validate`

package/README.md

@@ -180,6 +180,29 @@ const event = telnyx.webhooks.constructEvent(
 );
 ```
 
+#### TeXML Signature
+
+TeXML sends webhooks as form-encoded payloads instead of JSON. To validate the signature, use the `telnyx.webhooks.signature.verifySignature` method.
+
+You can find an example of how to use this with [Express](https://expressjs.com/) in the [`examples/webhook-signing`](examples/webhook-signing) folder.
+
+```js
+const timeToleranceInSeconds = 300; // Will validate signatures of webhooks up to 5 minutes after Telnyx sent the request
+try {
+  telnyx.webhooks.signature.verifySignature(
+    webhookRawBody,
+    webhookTelnyxSignatureHeader,
+    webhookTelnyxTimestampHeader,
+    publicKey,
+    timeToleranceInSeconds
+  );
+} catch (e) {
+  console.log("Failed to validate the signature")
+  console.log(e);
+}
+
+```
+
 ### Writing a Plugin
 
 If you're writing a plugin that uses the library, we'd appreciate it if you identified using `telnyx.setAppInfo()`:
@@ -285,16 +308,38 @@ const allMessagingProfiles = await telnyx.messagingProfiles.list()
 
 ## Development
 
-The test suite depends on [telnyx-mock], so make sure to fetch and run it locally from a
-background terminal. The default `PORT` used is `12111`. If you want
-to target a different one, pass the environment variable `TELNYX_MOCK_PORT`.
-([telnyx-mock's README][telnyx-mock] also contains
-instructions for installing via Homebrew and other methods):
+### Setup
+The test suite depends on the [Prism Mock Server](https://github.com/stoplightio/prism).
+
+```bash
+npm install -g @stoplight/prism-cli
+
+# OR
 
-    go get -u github.com/team-telnyx/telnyx-mock
-    telnyx-mock
+yarn global add @stoplight/prism-cli
+```
+
+Once installed, start the prism mock service with the following command:
+
+```bash
+prism mock https://raw.githubusercontent.com/team-telnyx/openapi/master/openapi/spec3.json
+```
+
+--------
+
+One final step -- because the Node SDK originally expected to reach the legacy `telnyx-mock` service at port 12111 (in addition to providing a `/v2/` base path), we need to setup the [Telnyx mock proxy server](https://github.com/team-telnyx/telnyx-mock-server-proxy) to modify the request path and forward along to the prism mock server.
+
+```bash
+# In new terminal window
+
+git clone git@github.com:team-telnyx/telnyx-prism-mock.git
+cd telnyx-prism-mock/proxy
+
+yarn install
+node index.js
+```
 
-Run all tests:
+### Running Tests
 
 ```bash
 $ npm install

package/VERSION

@@ -1 +1 @@
-1.23.0
+1.24.0

package/lib/TelnyxResource.js

@@ -25,19 +25,23 @@ function TelnyxResource(telnyx, urlData) {
   this._telnyx = telnyx;
   this._urlData = urlData || {};
 
-  this.basePath = utils.makeURLInterpolator(this.basePath || telnyx.getApiField('basePath'));
+  this.basePath = utils.makeURLInterpolator(
+    this.basePath || telnyx.getApiField('basePath')
+  );
   this.resourcePath = this.path;
   this.path = utils.makeURLInterpolator(this.path);
 
   if (this.includeBasic) {
-    this.includeBasic.forEach(function(methodName) {
+    this.includeBasic.forEach(function (methodName) {
       this[methodName] = TelnyxResource.BASIC_METHODS[methodName];
     }, this);
   }
 
   if (this.nestedResources) {
     for (var resource in this.nestedResources) {
-      this[utils.pascalToCamelCase(resource)] = new this.nestedResources[resource](telnyx);
+      this[utils.pascalToCamelCase(resource)] = new this.nestedResources[
+        resource
+      ](telnyx);
     }
   }
 
@@ -49,13 +53,12 @@ function TelnyxResource(telnyx, urlData) {
 }
 
 TelnyxResource.prototype = {
-
   path: '',
 
   // Methods that don't use the API's default '/v1' path can override it with this setting.
   basePath: null,
 
-  initialize: function() {},
+  initialize: function () {},
 
   // Function to override the default data processor. This allows full control
   // over how a TelnyxResource's request data will get converted into an HTTP
@@ -67,26 +70,27 @@ TelnyxResource.prototype = {
   // be thrown, and they will be passed to the callback/promise.
   validateRequest: null,
 
-  createFullPath: function(commandPath, urlData) {
-    return path.join(
-      this.basePath(urlData),
-      this.path(urlData),
-      typeof commandPath == 'function' ?
-        commandPath(urlData) : commandPath
-    ).replace(/\\/g, '/'); // ugly workaround for Windows
+  createFullPath: function (commandPath, urlData) {
+    return path
+      .join(
+        this.basePath(urlData),
+        this.path(urlData),
+        typeof commandPath == 'function' ? commandPath(urlData) : commandPath
+      )
+      .replace(/\\/g, '/'); // ugly workaround for Windows
   },
 
   // Creates a relative resource path with symbols left in (unlike
   // createFullPath which takes some data to replace them with). For example it
   // might produce: /invoices/{id}
-  createResourcePathWithSymbols: function(pathWithSymbols) {
-    return '/' + path.join(
-      this.resourcePath,
-      pathWithSymbols || ''
-    ).replace(/\\/g, '/'); // ugly workaround for Windows
+  createResourcePathWithSymbols: function (pathWithSymbols) {
+    return (
+      '/' +
+      path.join(this.resourcePath, pathWithSymbols || '').replace(/\\/g, '/')
+    ); // ugly workaround for Windows
   },
 
-  createUrlData: function() {
+  createUrlData: function () {
     var urlData = {};
     // Merge in baseData
     for (var i in this._urlData) {
@@ -97,9 +101,9 @@ TelnyxResource.prototype = {
     return urlData;
   },
 
-  _timeoutHandler: function(timeout, req, callback) {
+  _timeoutHandler: function (timeout, req, callback) {
     var self = this;
-    return function() {
+    return function () {
       var timeoutErr = new Error('ETIMEDOUT');
       timeoutErr.code = 'ETIMEDOUT';
 
@@ -109,24 +113,25 @@ TelnyxResource.prototype = {
       callback.call(
         self,
         new Error.TelnyxConnectionError({
-          message: 'Request aborted due to timeout being reached (' + timeout + 'ms)',
+          message:
+            'Request aborted due to timeout being reached (' + timeout + 'ms)',
           detail: timeoutErr,
         }),
         null
       );
-    }
+    };
   },
 
-  _responseHandler: function(req, callback) {
+  _responseHandler: function (req, callback) {
     var self = this;
-    return function(res) {
+    return function (res) {
       var response = '';
 
       res.setEncoding('utf8');
-      res.on('data', function(chunk) {
+      res.on('data', function (chunk) {
         response += chunk;
       });
-      res.on('end', function() {
+      res.on('end', function () {
         var headers = res.headers || {};
         // NOTE: Telnyx responds with lowercase header names/keys.
 
@@ -152,7 +157,7 @@ TelnyxResource.prototype = {
           if (response.errors) {
             var error = {};
 
-            error.errors = response.errors
+            error.errors = response.errors;
 
             error.headers = headers;
             error.statusCode = res.statusCode;
@@ -186,56 +191,61 @@ TelnyxResource.prototype = {
     };
   },
 
-  _buildError: function(error, statusCode) {
+  _buildError: function (error, statusCode) {
     var err;
     switch (statusCode) {
-    case 400:
-      err = new Error.TelnyxInvalidRequestError(error);
-      break;
-    case 401:
-      err = new Error.TelnyxAuthenticationError(error);
-      break;
-    case 403:
-      err = new Error.TelnyxPermissionError(error);
-      break;
-    case 404:
-      err = new Error.TelnyxResourceNotFoundError(error);
-      break;
-    case 405:
-      err = new Error.TelnyxMethodNotSupportedError(error);
-      break;
-    case 408:
-      err = new Error.TelnyxTimeoutError(error);
-      break;
-    case 415:
-      err = new Error.TelnyxUnsupportedMediaTypeError(error);
-      break;
-    case 422:
-      err = new Error.TelnyxInvalidParametersError(error);
-      break;
-    case 429:
-      err = new Error.TelnyxRateLimitError(error);
-      break;
-    case 500:
-      err = new Error.TelnyxAPIError(error);
-      break;
-    case 503:
-      err = new Error.TelnyxServiceUnavailableError(error);
-      break;
-    default:
-      err = new Error.TelnyxAPIError(error);
+      case 400:
+        err = new Error.TelnyxInvalidRequestError(error);
+        break;
+      case 401:
+        err = new Error.TelnyxAuthenticationError(error);
+        break;
+      case 403:
+        err = new Error.TelnyxPermissionError(error);
+        break;
+      case 404:
+        err = new Error.TelnyxResourceNotFoundError(error);
+        break;
+      case 405:
+        err = new Error.TelnyxMethodNotSupportedError(error);
+        break;
+      case 408:
+        err = new Error.TelnyxTimeoutError(error);
+        break;
+      case 415:
+        err = new Error.TelnyxUnsupportedMediaTypeError(error);
+        break;
+      case 422:
+        err = new Error.TelnyxInvalidParametersError(error);
+        break;
+      case 429:
+        err = new Error.TelnyxRateLimitError(error);
+        break;
+      case 500:
+        err = new Error.TelnyxAPIError(error);
+        break;
+      case 503:
+        err = new Error.TelnyxServiceUnavailableError(error);
+        break;
+      default:
+        err = new Error.TelnyxAPIError(error);
     }
 
     return err;
   },
 
-  _generateConnectionErrorMessage: function(requestRetries) {
-    return 'An error occurred with our connection to Telnyx.' + (requestRetries > 0 ? ' Request was retried ' + requestRetries + ' times.' : '');
+  _generateConnectionErrorMessage: function (requestRetries) {
+    return (
+      'An error occurred with our connection to Telnyx.' +
+      (requestRetries > 0
+        ? ' Request was retried ' + requestRetries + ' times.'
+        : '')
+    );
   },
 
-  _errorHandler: function(req, requestRetries, callback) {
+  _errorHandler: function (req, requestRetries, callback) {
     var self = this;
-    return function(error) {
+    return function (error) {
       if (req._isAborted) {
         // already handled
         return;
@@ -248,10 +258,10 @@ TelnyxResource.prototype = {
         }),
         null
       );
-    }
+    };
   },
 
-  _shouldRetry: function(res, numRetries) {
+  _shouldRetry: function (res, numRetries) {
     // Do not retry if we are out of retries.
     if (numRetries >= this._telnyx.getMaxNetworkRetries()) {
       return false;
@@ -275,7 +285,7 @@ TelnyxResource.prototype = {
     return false;
   },
 
-  _getSleepTimeInMS: function(numRetries) {
+  _getSleepTimeInMS: function (numRetries) {
     var initialNetworkRetryDelay = this._telnyx.getInitialNetworkRetryDelay();
     var maxNetworkRetryDelay = this._telnyx.getMaxNetworkRetryDelay();
 
@@ -297,8 +307,9 @@ TelnyxResource.prototype = {
     return sleepSeconds * 1000;
   },
 
-  _defaultHeaders: function(auth, requestData) {
-    var userAgentString = 'Telnyx/v1 NodeBindings/' + this._telnyx.getConstant('PACKAGE_VERSION');
+  _defaultHeaders: function (auth, requestData) {
+    var userAgentString =
+      'Telnyx/v1 NodeBindings/' + this._telnyx.getConstant('PACKAGE_VERSION');
 
     if (this._telnyx._appInfo) {
       userAgentString += ' ' + this._telnyx.getAppInfoAsString();
@@ -306,10 +317,8 @@ TelnyxResource.prototype = {
 
     var headers = {
       // Use specified auth token or use default from this telnyx instance:
-      'Authorization': auth ?
-        'Bearer ' + auth :
-        this._telnyx.getApiField('auth'),
-      'Accept': 'application/json',
+      Authorization: auth ? 'Bearer ' + auth : this._telnyx.getApiField('auth'),
+      Accept: '*/*',
       'Content-Type': 'application/json',
       'Content-Length': Buffer.byteLength(requestData),
       'User-Agent': userAgentString,
@@ -318,7 +327,7 @@ TelnyxResource.prototype = {
     return headers;
   },
 
-  _request: function(method, host, path, data, auth, options, callback) {
+  _request: function (method, host, path, data, auth, options, callback) {
     var self = this;
     var requestData;
 
@@ -336,12 +345,17 @@ TelnyxResource.prototype = {
         } else {
           requestData = '';
         }
-      } else {
+      } else if (utils.isJsonString(data)) {
         requestData = data;
+      } else if (data != '' && data != null) {
+        path = path + '?' + encodeURI(data);
+        requestData = '';
+      } else {
+        requestData = '';
       }
 
       headers = self._defaultHeaders(auth, requestData);
-      self._telnyx.getClientUserAgent(function(cua) {
+      self._telnyx.getClientUserAgent(function (cua) {
         headers['X-Telnyx-Client-User-Agent'] = cua;
 
         if (options.headers) {
@@ -353,13 +367,29 @@ TelnyxResource.prototype = {
     }
 
     if (self.requestDataProcessor) {
-      self.requestDataProcessor(method, data, options.headers, makeRequestWithData);
+      self.requestDataProcessor(
+        method,
+        data,
+        options.headers,
+        makeRequestWithData
+      );
     } else if (method == 'GET') {
       makeRequestWithData(null, data ? utils.stringifyRequestData(data) : '');
-    } else if (method == 'DELETE') {
-      makeRequestWithData(null, '');
     } else {
-      makeRequestWithData(null, data ? JSON.stringify(data) : '');
+      let parameters;
+      if (data) {
+        if (data.filter && Object.keys(data.filter).length) {
+          parameters = utils.stringifyRequestData(data);
+        } else {
+          parameters = JSON.stringify(data);
+          if (parameters === '{}') {
+            parameters = '';
+          }
+        }
+      } else {
+        parameters = '';
+      }
+      makeRequestWithData(null, parameters);
     }
 
     function retryRequest(requestFn, headers, requestRetries) {
@@ -376,12 +406,17 @@ TelnyxResource.prototype = {
     function makeRequest(headers, numRetries) {
       var timeout = self._telnyx.getApiField('timeout');
       var isInsecureConnection = self._telnyx.getApiField('protocol') == 'http';
-      var agent = isInsecureConnection ? self._telnyx.getApiField('http_agent') : self._telnyx.getApiField('https_agent');
+      var agent = isInsecureConnection
+        ? self._telnyx.getApiField('http_agent')
+        : self._telnyx.getApiField('https_agent');
+
+      if (headers['Content-Length'] === 0) {
+        delete headers['Content-Length'];
+        delete headers['Content-Type'];
+      }
 
-      var req = (
-        isInsecureConnection ? http : https
-      ).request({
-        host: host || self._telnyx.getApiField('host'),
+      var req = (isInsecureConnection ? http : https).request({
+        host: self._telnyx.getApiField('host') || '127.0.0.1',
         port: self._telnyx.getApiField('port'),
         path: path,
         method: method,
@@ -405,7 +440,7 @@ TelnyxResource.prototype = {
 
       req.setTimeout(timeout, self._timeoutHandler(timeout, req, callback));
 
-      req.on('response', function(res) {
+      req.on('response', function (res) {
         if (self._shouldRetry(res, requestRetries)) {
           return retryRequest(makeRequest, headers, requestRetries);
         } else {
@@ -413,7 +448,7 @@ TelnyxResource.prototype = {
         }
       });
 
-      req.on('error', function(error) {
+      req.on('error', function (error) {
         if (self._shouldRetry(null, requestRetries)) {
           return retryRequest(makeRequest, headers, requestRetries);
         } else {
@@ -421,13 +456,16 @@ TelnyxResource.prototype = {
         }
       });
 
-      req.on('socket', function(socket) {
+      req.on('socket', function (socket) {
         if (socket.connecting) {
-          socket.on((isInsecureConnection ? 'connect' : 'secureConnect'), function() {
-            // Send payload; we're safe:
-            req.write(requestData);
-            req.end();
-          });
+          socket.on(
+            isInsecureConnection ? 'connect' : 'secureConnect',
+            function () {
+              // Send payload; we're safe:
+              req.write(requestData);
+              req.end();
+            }
+          );
         } else {
           // we're already connected
           req.write(requestData);

package/lib/makeRequest.js

@@ -5,11 +5,17 @@ var OPTIONAL_REGEX = /^optional!/;
 
 function getRequestOpts(self, requestArgs, spec, overrideData) {
   // Extract spec values with defaults.
-  var commandPath = typeof spec.path == 'function' ? spec.path
-    : utils.makeURLInterpolator(spec.path || '');
+  var commandPath =
+    typeof spec.path == 'function'
+      ? spec.path
+      : utils.makeURLInterpolator(spec.path || '');
   var requestMethod = (spec.method || 'GET').toUpperCase();
   var urlParams = spec.urlParams || [];
-  var encode = spec.encode || function(data) {return data;};
+  var encode =
+    spec.encode ||
+    function (data) {
+      return data;
+    };
   var host = spec.host;
 
   // Don't mutate args externally.
@@ -32,8 +38,13 @@ function getRequestOpts(self, requestArgs, spec, overrideData) {
     if (param == 'id' && typeof arg !== 'string') {
       path = self.createResourcePathWithSymbols(spec.path);
       throw new Error(
-        'Telnyx: "id" must be a string, but got: ' + typeof arg +
-        ' (on API request to `' + requestMethod + ' ' + path + '`)'
+        'Telnyx: "id" must be a string, but got: ' +
+          typeof arg +
+          ' (on API request to `' +
+          requestMethod +
+          ' ' +
+          path +
+          '`)'
       );
     }
 
@@ -45,8 +56,15 @@ function getRequestOpts(self, requestArgs, spec, overrideData) {
 
       path = self.createResourcePathWithSymbols(spec.path);
       throw new Error(
-        'Telnyx: Argument "' + urlParams[i] + '" required, but got: ' + arg +
-        ' (on API request to `' + requestMethod + ' ' + path + '`)'
+        'Telnyx: Argument "' +
+          urlParams[i] +
+          '" required, but got: ' +
+          arg +
+          ' (on API request to `' +
+          requestMethod +
+          ' ' +
+          path +
+          '`)'
       );
     }
 
@@ -62,8 +80,14 @@ function getRequestOpts(self, requestArgs, spec, overrideData) {
   if (args.length) {
     path = self.createResourcePathWithSymbols(spec.path);
     throw new Error(
-      'Telnyx: Unknown arguments (' + args + '). Did you mean to pass an options ' +
-      'object? (on API request to ' + requestMethod + ' `' + path + '`)'
+      'Telnyx: Unknown arguments (' +
+        args +
+        '). Did you mean to pass an options ' +
+        'object? (on API request to ' +
+        requestMethod +
+        ' `' +
+        path +
+        '`)'
     );
   }
 
@@ -85,7 +109,7 @@ function getRequestOpts(self, requestArgs, spec, overrideData) {
 }
 
 function makeRequest(self, requestArgs, spec, overrideData) {
-  return new Promise(function(resolve, reject) {
+  return new Promise(function (resolve, reject) {
     try {
       var opts = getRequestOpts(self, requestArgs, spec, overrideData);
     } catch (err) {
@@ -98,14 +122,22 @@ function makeRequest(self, requestArgs, spec, overrideData) {
         reject(err);
       } else {
         resolve(
-          spec.transformResponseData && response.data ?
-            spec.transformResponseData(response, self._telnyx) :
-            response
+          spec.transformResponseData && response.data
+            ? spec.transformResponseData(response, self._telnyx)
+            : response
         );
       }
     }
 
-    self._request(opts.requestMethod, opts.host, opts.requestPath, opts.data, opts.auth, {headers: opts.headers}, requestCallback);
+    self._request(
+      opts.requestMethod,
+      opts.host,
+      opts.requestPath,
+      opts.data,
+      opts.auth,
+      {headers: opts.headers},
+      requestCallback
+    );
   });
 }
 

package/lib/resources/AccessIpAddress.js

@@ -0,0 +1,6 @@
+'use strict';
+
+module.exports = require('../TelnyxResource').extend({
+  path: 'access_ip_address',
+  includeBasic: ['list', 'create', 'retrieve', 'del'],
+});

package/lib/resources/AccessIpRanges.js

@@ -0,0 +1,6 @@
+'use strict';
+
+module.exports = require('../TelnyxResource').extend({
+  path: 'access_ip_ranges',
+  includeBasic: ['list', 'create', 'retrieve', 'del'],
+});

package/lib/resources/ActivateDeactivateBulkCredentials.js

@@ -0,0 +1,20 @@
+'use strict';
+
+var TelnyxResource = require('../TelnyxResource');
+var utils = require('../utils');
+var telnyxMethod = TelnyxResource.method;
+
+function transformResponseData(response, telnyx) {
+  return utils.addResourceToResponseData(response, telnyx, 'actions', {});
+}
+
+module.exports = TelnyxResource.extend({
+  path: 'actions',
+
+  create: telnyxMethod({
+    method: 'POST',
+    path: '/{action}/telephony_credentials',
+    urlParams: ['action'],
+    transformResponseData: transformResponseData,
+  }),
+});

package/lib/resources/Addresses.js

@@ -5,24 +5,19 @@ var utils = require('../utils');
 var telnyxMethod = TelnyxResource.method;
 
 function transformResponseData(response, telnyx) {
-  return utils.addResourceToResponseData(
-    response,
-    telnyx,
-    'addresses',
-    {
-      del: telnyxMethod({
-        method: 'DELETE',
-        path: '/{addressId}',
-        urlParams: ['addressId'],
-        paramsValues: [response.data.id],
-        paramsNames: ['id'],
-      }),
-    }
-  );
+  return utils.addResourceToResponseData(response, telnyx, 'addresses', {
+    del: telnyxMethod({
+      method: 'DELETE',
+      path: '/{addressId}',
+      urlParams: ['addressId'],
+      paramsValues: [response.data.id],
+      paramsNames: ['id'],
+    }),
+  });
 }
 
 module.exports = TelnyxResource.extend({
-  path: 'addresses',
+  path: 'account/addresses',
 
   list: telnyxMethod({
     method: 'GET',
@@ -47,6 +42,6 @@ module.exports = TelnyxResource.extend({
 
   validate: telnyxMethod({
     method: 'POST',
-    path: '/actions/validate'
+    path: '/actions/validate',
   }),
 });