telnyx 1.27.0 → 2.0.0-alpha.1

package/CHANGELOG.md

@@ -1,23 +1,72 @@
 # CHANGELOG
 
-##
+## v2
+
+### v2.0.0-alpha.1
+
+- Update actions workflow versions to v4 and `.npmignore` to v2
+- Update examples dependencies
+
+### v2.0.0-alpha.0
+
+- Add Typescript default config, linter and dependencies
+- Bump default Node version to `20`
+- Update README on [Development](./README.md#development) instructions
+- Remove `yarn` in favor of `npm` 10
+- Convert SDK files to Typescript
+- Convert Resources to Typescript
+- Use ES Modules syntax
+- Update package `main` entrypoint to be compiled version of [src telnyx.ts](./src/telnyx.ts)
+- Added `Jest` and create tests in Typescript
+- Update tests expect matchers according to limitations with `prism mock`
+- Add `nock` cleanup setup
+- Make `setApiKey` TelnyxObject prototype method private
+- Moved to `moduleResolution` Bundler to support better imports and tests with `Jest`
+- Enabled `esModuleInterop` for Jest
+- Update files included when publishing
+- Remove custom resource get `generateAccessTokenFromCredential` from `TelephonyCredentials`
+- Update `AutoRechargePreferences` resource
+- Remove `RegisterCall` resource
+- Remove `ProgrammableFaxCommants` specs
+- Remove `BulkCreation` resource
+- Update `TexmlApplications` resource
+- Remove `Conferences` `dial_participant` action
+- Remove `SimCards` `deletePublicIp` and `setPublicIp`
+- Update `Queues` method names to camelCase
+- Remove `VerifiedCallsDisplayProfile` resource
+- Update examples to Typescript
+- Remove duplicated `AccessTokens` resource
+- Move custom `AdvancedOptinoptout` resource to be `AutoRespConfigs` resource
+- Remove `Billing` resource
+- Remove inexistent `Bucket` resource
+- Move `BucketUsage` resource to `StorageBuckets`
+- Remove duplicated `BulkPhoneNumberCampaigns` resource
+- Remove duplicated `BulkPhoneNumberOperations` resource
+
+
+## v1
 
 ### v1.26.2
+
 - Fix Brand and Campaign redirects
 - Update security
 
 ### v1.26.1
+
 - Fix porting comments
 
 ### v1.26.0
+
 - Endpoint additions
 - Package upgrades
 - Preparation for typescript migration/support
 
 ### v1.25.5
+
 - Security Updates + API Additions
 
 ### v1.23.0 (2021-10-19)
+
 - **Addresses** added `validate`
 - **AuthenticationProvider** added `list`, `create`, `retrieve`, `update`, `del`
 - **DynamicEmergency** (for `endpoints` and `addresses`) added `list`, `retrieve`, `create`, `del`

package/LICENSE

@@ -1,6 +1,6 @@
 Copyright (C) 2011 Ask Bjørn Hansen
 Copyright (C) 2013 Stripe, Inc. (https://stripe.com)
-Copyright (C) 2019 Telnyx, Inc. (https://www.telnyx.com)
+Copyright (C) 2019 Telnyx, Inc. (https://telnyx.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,7 +2,6 @@
 
 [![Version](https://img.shields.io/npm/v/telnyx.svg)](https://www.npmjs.org/package/telnyx)
 [![Build Status](https://github.com/team-telnyx/telnyx-node/workflows/CI/badge.svg)](https://github.com/team-telnyx/telnyx-node/actions)
-[![Coverage Status](https://coveralls.io/repos/github/team-telnyx/telnyx-node/badge.svg?branch=master)](https://coveralls.io/github/team-telnyx/telnyx-node?branch=master)
 [![Downloads](https://img.shields.io/npm/dm/telnyx.svg)](https://www.npmjs.com/package/telnyx)
 [![Try on RunKit](https://badge.runkitcdn.com/telnyx.svg)](https://runkit.com/npm/telnyx)
 [![Join Slack](https://img.shields.io/badge/join-slack-infomational)](https://joinslack.telnyx.com/)
@@ -26,62 +25,41 @@ The package needs to be configured with your account's API key which is
 available in your the [Telnyx Mission Control Portal][api-keys]. Require it with the key's
 value:
 
-``` js
-const telnyx = require('telnyx')('KEY123456...');
+```typescript
+import Telnyx from 'telnyx';
+
+const telnyx = new Telnyx('KEY123456...');
 
 const messagingProfile = await telnyx.messagingProfiles.create({
-  name: 'Summer Campaign'
+  name: 'Summer Campaign',
 });
 ```
 
-Or with versions of Node.js prior to v7.9:
-
-``` js
-var telnyx = require('telnyx')('KEY123456...');
-
-telnyx.messagingProfiles.create(
-  { name: 'Summer Campaign' },
-  function(err, messagingProfile) {
-    err; // null if no error occurred
-    messagingProfile; // the created messaging profile object
-  }
-);
-```
-
-Or using ES modules, this looks more like:
-
-```js
-import Telnyx from 'telnyx';
-const telnyx = Telnyx('KEY...');
-//…
-```
-
 ### Using Promises
 
 Every method returns a chainable promise which can be used instead of a regular
 callback:
 
-```js
+```typescript
 // Create a new messaging profile and then send a message using that profile:
-telnyx.MessagingProfiles.create({
-  name: 'Summer Campaign'
-}).then((messagingProfile) => {
-  return telnyx.MessagingPhoneNumbers.update(
-    '+18005554000',
-    {
-      'messaging_profile_id': messagingProfile.data.id
-    }
-  );
-}).catch((err) => {
-  // Deal with an error
-});
+telnyx.,essagingProfiles.create({
+  name: 'Summer Campaign',
+})
+  .then((messagingProfile) => {
+    return telnyx.messagingPhoneNumbers.update('+18005554000', {
+      messaging_profile_id: messagingProfile.data.id,
+    });
+  })
+  .catch((err) => {
+    // Deal with an error
+  });
 ```
 
 ### Configuring Timeout
 
 Request timeout is configurable (the default is Node's default of 120 seconds):
 
-``` js
+```typescript
 telnyx.setTimeout(20000); // in ms (this is 20 seconds)
 ```
 
@@ -90,11 +68,12 @@ telnyx.setTimeout(20000); // in ms (this is 20 seconds)
 An [https-proxy-agent][https-proxy-agent] can be configured with
 `setHttpAgent`.
 
-To use telnyx behind a proxy you can pass  to sdk:
+To use telnyx behind a proxy you can pass to sdk:
+
+```typescript
+import ProxyAgent from 'https-proxy-agent';
 
-```js
 if (process.env.http_proxy) {
-  const ProxyAgent = require('https-proxy-agent');
   telnyx.setHttpAgent(new ProxyAgent(process.env.http_proxy));
 }
 ```
@@ -105,7 +84,7 @@ Automatic network retries can be enabled with `setMaxNetworkRetries`. This will
 retry requests `n` times with exponential backoff if they fail due to an
 intermittent network problem.
 
-```js
+```typescript
 // Retry a request once before giving up
 telnyx.setMaxNetworkRetries(1);
 ```
@@ -115,21 +94,23 @@ telnyx.setMaxNetworkRetries(1);
 Some information about the response which generated a resource is available
 with the `lastResponse` property:
 
-```js
-messagingProfile.lastResponse.requestId // see: https://telnyx.com/docs/api/node#request_ids
-messagingProfile.lastResponse.statusCode
+```typescript
+messagingProfile.lastResponse.requestId; // see: https://telnyx.com/docs/api/node#request_ids
+messagingProfile.lastResponse.statusCode;
 ```
 
 ### `request` and `response` events
 
-The Telnyx object emits `request` and `response` events.  You can use them like this:
+The Telnyx object emits `request` and `response` events. You can use them like this:
+
+```typescript
+import Telnyx from 'telnyx';
 
-```js
-const telnyx = require('telnyx')('KEY...');
+const telnyx = new Telnyx('KEY...');
 
 const onRequest = (request) => {
   // Do something.
-}
+};
 
 // Add the event handler function:
 telnyx.on('request', onRequest);
@@ -139,7 +120,8 @@ telnyx.off('request', onRequest);
 ```
 
 #### `request` object
-```js
+
+```typescript
 {
   method: 'POST',
   path: '/v2/messaging_profiles'
@@ -147,7 +129,8 @@ telnyx.off('request', onRequest);
 ```
 
 #### `response` object
-```js
+
+```typescript
 {
   method: 'POST',
   path: '/v2/messaging_profiles',
@@ -171,12 +154,12 @@ You can find an example of how to use this with [Express](https://expressjs.com/
 in the [`examples/webhook-signing`](examples/webhook-signing) folder, but here's
 what it looks like:
 
-```js
+```typescript
 const event = telnyx.webhooks.constructEvent(
   webhookRawBody,
   webhookTelnyxSignatureHeader,
   webhookTelnyxTimestampHeader,
-  publicKey
+  publicKey,
 );
 ```
 
@@ -186,7 +169,7 @@ TeXML sends webhooks as form-encoded payloads instead of JSON. To validate the s
 
 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
+```typescript
 const timeToleranceInSeconds = 300; // Will validate signatures of webhooks up to 5 minutes after Telnyx sent the request
 try {
   telnyx.webhooks.signature.verifySignature(
@@ -194,20 +177,19 @@ try {
     webhookTelnyxSignatureHeader,
     webhookTelnyxTimestampHeader,
     publicKey,
-    timeToleranceInSeconds
+    timeToleranceInSeconds,
   );
 } catch (e) {
-  console.log("Failed to validate the signature")
+  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()`:
 
-```js
+```typescript
 telnyx.setAppInfo({
   name: 'MyAwesomePlugin',
   version: '1.2.34', // Optional
@@ -222,14 +204,13 @@ This information is passed along when the library makes calls to the Telnyx API.
 You can auto-paginate list methods. We provide a few different APIs for this to
 aid with a variety of node versions and styles.
 
-
 #### Async iterators (`for-await-of`)
 
 If you are in a Node environment that has support for [async iteration](https://github.com/tc39/proposal-async-iteration#the-async-iteration-statement-for-await-of),
 such as Node 10+ or [babel](https://babeljs.io/docs/en/babel-plugin-transform-async-generator-functions),
 the following will auto-paginate:
 
-```js
+```typescript
 for await (const messagingProfile of telnyx.messagingProfiles.list()) {
   doSomething(messagingProfile);
   if (shouldStop()) {
@@ -243,36 +224,42 @@ for await (const messagingProfile of telnyx.messagingProfiles.list()) {
 If you are in a Node environment that has support for `await`, such as Node 7.9 and greater,
 you may pass an async function to `.autoPagingEach`:
 
-```js
-await telnyx.messagingProfiles.list().autoPagingEach(async (messagingProfile) => {
-  await doSomething(messagingProfile);
-  if (shouldBreak()) {
-    return false;
-  }
-})
+```typescript
+await telnyx.messagingProfiles
+  .list()
+  .autoPagingEach(async (messagingProfile) => {
+    await doSomething(messagingProfile);
+    if (shouldBreak()) {
+      return false;
+    }
+  });
 console.log('Done iterating.');
 ```
 
 Equivalently, without `await`, you may return a Promise, which can resolve to `false` to break:
 
-```js
-telnyx.messagingProfiles.list().autoPagingEach((messagingProfile) => {
-  return doSomething(messagingProfile).then(() => {
-    if (shouldBreak()) {
-      return false;
-    }
-  });
-}).then(() => {
-  console.log('Done iterating.');
-}).catch(handleError);
+```typescript
+telnyx.messagingProfiles
+  .list()
+  .autoPagingEach((messagingProfile) => {
+    return doSomething(messagingProfile).then(() => {
+      if (shouldBreak()) {
+        return false;
+      }
+    });
+  })
+  .then(() => {
+    console.log('Done iterating.');
+  })
+  .catch(handleError);
 ```
 
 If you prefer callbacks to promises, you may also use a `next` callback and a second `onDone` callback:
 
-```js
+```typescript
 telnyx.messagingProfiles.list().autoPagingEach(
   function onItem(messagingProfile, next) {
-    doSomething(messagingProfile, function(err, result) {
+    doSomething(messagingProfile, function (err, result) {
       if (shouldStop(result)) {
         next(false); // Passing `false` breaks out of the loop.
       } else {
@@ -286,8 +273,8 @@ telnyx.messagingProfiles.list().autoPagingEach(
     } else {
       console.log('Done iterating.');
     }
-  }
-)
+  },
+);
 ```
 
 If your `onItem` function does not accept a `next` callback parameter _or_ return a Promise,
@@ -301,31 +288,41 @@ to prevent runaway list growth from consuming too much memory.
 
 Returns a promise of an array of all items across pages for a list request.
 
-```js
-const allMessagingProfiles = await telnyx.messagingProfiles.list()
+```typescript
+const allMessagingProfiles = await telnyx.messagingProfiles
+  .list()
   .autoPagingToArray({limit: 10000});
 ```
 
 ## Development
 
 ### Setup
-The test suite depends on the [Prism Mock Server](https://github.com/stoplightio/prism).
+
+Run the following to create your env file
 
 ```bash
-npm install -g @stoplight/prism-cli
+cp .env.local .env
+```
+
+> Don't forget to update your `.env` values accordingly.
 
-# OR
+Now inject envs into terminal:
 
-yarn global add @stoplight/prism-cli
+```bash
+. ./setup_env.sh
 ```
 
-Once installed, start the prism mock service with the following command:
+> Feel free to use Node `--env-file` parameter to [setup envs](https://nodejs.org/en/learn/command-line/how-to-read-environment-variables-from-nodejs) if you prefer
+
+The test suite depends on the [Prism Mock Server](https://github.com/stoplightio/prism).
+
+Start the prism mock service with the following command:
 
 ```bash
-prism mock https://raw.githubusercontent.com/team-telnyx/openapi/master/openapi/spec3.json
+npx 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.
 
@@ -335,7 +332,7 @@ One final step -- because the Node SDK originally expected to reach the legacy `
 git clone git@github.com:team-telnyx/telnyx-prism-mock.git
 cd telnyx-prism-mock/proxy
 
-yarn install
+npm install
 node index.js
 ```
 
@@ -349,22 +346,22 @@ $ npm test
 Run all tests with a custom `telnyx-mock` port:
 
 ```bash
-$ TELNYX_MOCK_PORT=12000 npm test
+$ TELNYX_MOCK_PORT=12111 npm test
 ```
 
 Run a single test suite:
 
 ```bash
-$ npm run mocha -- test/Error.spec.js
+$ npm test -- test/Error.test.ts
 ```
 
 Run a single test (case sensitive):
 
 ```bash
-$ npm run mocha -- test/Error.spec.js --grep 'Populates with type'
+$ npm test -- test/Error.test.ts -t 'Populates with type'
 ```
 
-If you wish, you may run tests using your Telnyx *Test* API key by setting the
+If you wish, you may run tests using your Telnyx _Test_ API key by setting the
 environment variable `TELNYX_TEST_API_KEY` before running the tests:
 
 ```bash
@@ -377,10 +374,12 @@ $ npm test
 
 To inspect values in tests first import debug:
 
-```js
-var debug = require('debug')('foo');
+```typescript
+import Debug from 'debug';
+
+const debug = Debug('foo');
 //...
-debug(result)
+debug(result);
 ```
 
 Then run the tests with:
@@ -395,6 +394,24 @@ To view verbose debugging for `nock` run the tests with:
 $ DEBUG=nock.* npm test
 ```
 
+### Typescript
+
+Run:
+
+```bash
+npm run build
+```
+
+Then check output in [dist](./dist) folder
+
+### Linter (Prettier)
+
+Add an [editor integration](https://prettier.io/docs/en/editors.html) or:
+
+```bash
+$ npm run fix
+```
+
 ## Acknowledgements
 
 The contributors and maintainers of Telnyx Node would like to extend their deep gratitude to the

package/VERSION

@@ -1 +1 @@
-1.27.0
+2.0.0-alpha.1

package/dist/Error.js

@@ -0,0 +1,156 @@
+export const generate = (rawTelnyxError) => {
+    switch (rawTelnyxError.statusCode) {
+        case 400:
+            return new TelnyxInvalidRequestError(rawTelnyxError);
+        case 401:
+            return new TelnyxAuthenticationError(rawTelnyxError);
+        case 403:
+            return new TelnyxPermissionError(rawTelnyxError);
+        case 404:
+            return new TelnyxResourceNotFoundError(rawTelnyxError);
+        case 405:
+            return new TelnyxMethodNotSupportedError(rawTelnyxError);
+        case 408:
+            return new TelnyxTimeoutError(rawTelnyxError);
+        case 415:
+            return new TelnyxUnsupportedMediaTypeError(rawTelnyxError);
+        case 422:
+            return new TelnyxInvalidParametersError(rawTelnyxError);
+        case 429:
+            return new TelnyxRateLimitError(rawTelnyxError);
+        case 500:
+            return new TelnyxAPIError(rawTelnyxError);
+        case 503:
+            return new TelnyxServiceUnavailableError(rawTelnyxError);
+    }
+    return new TelnyxError({ type: 'Generic', message: 'Unknown Error' });
+};
+/**
+ * TelnyxError is the base error from which all other more specific Telnyx errors derive.
+ * Specifically for errors returned from Telnyx's REST API.
+ */
+export class TelnyxError extends Error {
+    message;
+    type;
+    raw;
+    headers;
+    requestId;
+    detail;
+    code;
+    statusCode;
+    responseBody;
+    constructor(raw = {}, type = null) {
+        super(raw.message);
+        this.type = type || this.constructor.name;
+        this.raw = raw;
+        this.code = raw.code;
+        this.detail = raw.detail;
+        this.headers = raw.headers;
+        this.requestId = raw.requestId;
+        this.statusCode = raw.statusCode;
+        this.responseBody = raw.responseBody;
+        // @ts-expect-error message needs to be required here
+        this.message = raw.message;
+    }
+    /**
+     * Helper factory which takes raw Telnyx errors and outputs wrapping instances
+     */
+    static generate = generate;
+}
+/**
+ * InvalidRequestError is raised when a request is initiated with invalid
+ * parameters.
+ */
+export class TelnyxInvalidRequestError extends TelnyxError {
+    constructor(raw = {}) {
+        super(raw, 'TelnyxInvalidRequestError');
+    }
+}
+/**
+ * APIError is a generic error that may be raised in cases where none of the
+ * other named errors cover the problem. It could also be raised in the case
+ * that a new error has been introduced in the API, but this version of the
+ * Node.JS SDK doesn't know how to handle it.
+ */
+export class TelnyxAPIError extends TelnyxError {
+    constructor(raw = {}) {
+        super(raw, 'TelnyxAPIError');
+    }
+}
+/**
+ * AuthenticationError is raised when invalid credentials are used to connect
+ * to Telnyx's servers.
+ */
+export class TelnyxAuthenticationError extends TelnyxError {
+    constructor(raw = {}) {
+        super(raw, 'TelnyxAuthenticationError');
+    }
+}
+/**
+ * PermissionError is raised in cases where access was attempted on a resource
+ * that wasn't allowed.
+ */
+export class TelnyxPermissionError extends TelnyxError {
+    constructor(raw = {}) {
+        super(raw, 'TelnyxPermissionError');
+    }
+}
+export class TelnyxResourceNotFoundError extends TelnyxError {
+    constructor(raw = {}) {
+        super(raw, 'TelnyxResourceNotFoundError');
+    }
+}
+export class TelnyxMethodNotSupportedError extends TelnyxError {
+    constructor(raw = {}) {
+        super(raw, 'TelnyxMethodNotSupportedError');
+    }
+}
+export class TelnyxTimeoutError extends TelnyxError {
+    constructor(raw = {}) {
+        super(raw, 'TelnyxTimeoutError');
+    }
+}
+export class TelnyxUnsupportedMediaTypeError extends TelnyxError {
+    constructor(raw = {}) {
+        super(raw, 'TelnyxUnsupportedMediaTypeError');
+    }
+}
+export class TelnyxInvalidParametersError extends TelnyxError {
+    constructor(raw = {}) {
+        super(raw, 'TelnyxInvalidParametersError');
+    }
+}
+/**
+ * RateLimitError is raised in cases where an account is putting too much load
+ * on Telnyx's API servers (usually by performing too many requests). Please
+ * back off on request rate.
+ */
+export class TelnyxRateLimitError extends TelnyxError {
+    constructor(raw = {}) {
+        super(raw, 'TelnyxRateLimitError');
+    }
+}
+export class TelnyxServiceUnavailableError extends TelnyxError {
+    constructor(raw = {}) {
+        super(raw, 'TelnyxServiceUnavailableError');
+    }
+}
+/**
+ * TelnyxConnectionError is raised in the event that the SDK can't connect to
+ * Telnyx's servers. That can be for a variety of different reasons from a
+ * downed network to a bad TLS certificate.
+ */
+export class TelnyxConnectionError extends TelnyxError {
+    constructor(raw = {}) {
+        super(raw, 'TelnyxConnectionError');
+    }
+}
+/**
+ * SignatureVerificationError is raised when the signature verification for a
+ * webhook fails
+ */
+export class TelnyxSignatureVerificationError extends TelnyxError {
+    constructor(raw = {}) {
+        super(raw, 'TelnyxSignatureVerificationError');
+    }
+}

package/dist/TelnyxMethod.basic.js

@@ -0,0 +1,24 @@
+import telnyxMethod from './TelnyxMethod';
+export const create = telnyxMethod({
+    method: 'POST',
+});
+export const list = telnyxMethod({
+    method: 'GET',
+    methodType: 'list',
+});
+export const retrieve = telnyxMethod({
+    method: 'GET',
+    path: '/{id}',
+    urlParams: ['id'],
+});
+export const update = telnyxMethod({
+    method: 'PATCH',
+    path: '{id}',
+    urlParams: ['id'],
+});
+// Avoid 'delete' keyword in JS
+export const del = telnyxMethod({
+    method: 'DELETE',
+    path: '{id}',
+    urlParams: ['id'],
+});