twilio 4.0.0-rc.5 → 4.0.1

package/README.md

@@ -29,12 +29,6 @@ TypeScript is supported for TypeScript version 2.9 and above.
 
 `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.
@@ -70,6 +64,22 @@ const client = require('twilio')(accountSid, authToken, {
 });
 ```
 
+### 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, {
+    autoRetry: true,
+    maxRetries: 3
+});
+```
+
 ### Specify Region and/or Edge
 
 To take advantage of Twilio's [Global Infrastructure](https://www.twilio.com/docs/global-infrastructure), specify the target Region and/or Edge for the client:
@@ -115,7 +125,7 @@ See [example](examples/express.js) for a code sample for incoming Twilio request
 
 ## Handling Exceptions
 
-For an example on how to handle exceptions in this helper library, please see the [Twilio documentation](https://www.twilio.com/docs/libraries/node/usage-guide#exceptions).
+For an example on how to handle exceptions in this helper library, please see the [Twilio documentation](https://www.twilio.com/docs/libraries/node#exceptions).
 
 ## Using a Custom HTTP Client
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "twilio",
   "description": "A Twilio helper library",
-  "version": "4.0.0-rc.5",
+  "version": "4.0.1",
   "author": "API Team <api@twilio.com>",
   "contributors": [
     {
@@ -30,35 +30,35 @@
     "xmlbuilder": "^13.0.2"
   },
   "devDependencies": {
-    "@babel/preset-env": "7.18.2",
-    "@babel/preset-typescript": "7.17.12",
-    "@types/jest": "^27.5.2",
+    "@babel/preset-env": "^7.20.2",
+    "@babel/preset-typescript": "^7.18.6",
+    "@types/jest": "^29.2.5",
     "@types/jsonwebtoken": "^9.0.0",
-    "@types/node": "9.6.57",
+    "@types/node": "^18.11.18",
     "@types/qs": "^6.9.7",
     "@types/url-parse": "^1.4.8",
     "babel-plugin-replace-ts-export-assignment": "^0.0.2",
-    "eslint": "^7.28.0",
+    "eslint": "^8.31.0",
     "express": "^4.17.1",
-    "jest": "^28.1.0",
+    "jest": "^29.3.1",
     "jshint": "^2.11.0",
     "localtunnel": "^2.0.2",
-    "mock-fs": "^4.12.0",
+    "mock-fs": "^5.2.0",
     "nock": "^13.2.9",
     "node-mocks-http": "^1.8.1",
     "prettier": "^2.7.1",
-    "ts-jest": "^28.0.3",
+    "ts-jest": "^29.0.5",
     "typescript": "^4.7.2",
     "typedoc": "^0.23.21"
   },
   "scripts": {
-    "test": "npm run test:javascript",
+    "test": "npm run test:javascript && npm run test:typescript",
     "test:javascript": "jest spec/* --coverage --detectOpenHandles",
     "test:typescript": "tsc --noEmit",
-    "jshint": "jshint lib/rest/** lib/base/** lib/http/**",
-    "jscs": "eslint lib/base/**/**.js lib/http/**/**.js --fix",
+    "jshint": "jshint src/rest/** src/base/** src/http/**",
+    "jscs": "eslint src/base/**/**.js src/http/**/**.js --fix",
     "prepublish": "npm run build",
-    "build": "tsc && cp package.json dist/",
+    "build": "tsc",
     "check": "npm run jshint && npm run jscs",
     "ci": "npm run test && npm run nsp && npm run prettier-check",
     "nsp": "npm audit --production",
@@ -66,13 +66,13 @@
     "prettier-check": "prettier --check .",
     "cluster": "jest ./cluster_test.spec.ts --coverage",
     "webhook-test": "jest ./webhook_cluster_test.spec.ts --coverage",
-    "typedoc": "typedoc --entryPointStrategy expand lib --out docs --logLevel Error"
+    "typedoc": "typedoc --entryPointStrategy expand src --out docs --logLevel Error"
   },
   "files": [
-    "dist"
+    "list"
   ],
-  "main": "./dist/lib",
-  "types": "./dist/index.d.ts",
+  "main": "./lib",
+  "types": "./index.d.ts",
   "engines": {
     "node": ">=14.0"
   },

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-import lib from "./lib";
-export default lib;

package/dist/index.js

@@ -1,7 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const lib_1 = __importDefault(require("./lib"));
-exports.default = lib_1.default;

package/dist/lib/base/BaseTwilio.d.ts

@@ -1,77 +0,0 @@
-/// <reference types="node" />
-import RequestClient from "./RequestClient";
-import { HttpMethod } from "../interfaces";
-export interface ClientOpts {
-    httpClient?: RequestClient;
-    accountSid?: string;
-    env?: NodeJS.ProcessEnv;
-    edge?: string;
-    region?: string;
-    lazyLoading?: boolean;
-    logLevel?: string;
-    userAgentExtensions?: string[];
-}
-export interface RequestOpts {
-    method?: HttpMethod;
-    uri?: string;
-    username?: string;
-    password?: string;
-    headers?: Headers;
-    params?: object;
-    data?: object;
-    timeout?: number;
-    allowRedirects?: boolean;
-    logLevel?: string;
-}
-/**
- * Parent class for Twilio Client that implements request & validation logic
- */
-export declare class BaseTwilio {
-    username: string;
-    password: string;
-    accountSid: string;
-    opts?: ClientOpts;
-    env?: NodeJS.ProcessEnv;
-    edge?: string;
-    region?: string;
-    logLevel?: string;
-    userAgentExtensions?: string[];
-    _httpClient?: RequestClient;
-    /**
-     * Create a BaseTwilio instance
-     *
-     * @param username -
-     *          The username used for authentication. This is normally account sid, but if using key/secret auth will be
-     *          the api key sid.
-     * @param password -
-     *          The password used for authentication. This is normally auth token, but if using key/secret auth will be
-     *          the secret.
-     * @param opts - The options argument
-     *
-     * @returns A new instance of BaseTwilio
-     */
-    constructor(username?: string, password?: string, opts?: ClientOpts);
-    get httpClient(): RequestClient;
-    /**
-     * Makes a request to the Twilio API using the configured http client.
-     * Authentication information is automatically added if none is provided.
-     *
-     * @param opts - The options argument
-     */
-    request(opts: RequestOpts): Promise<any>;
-    /**
-     * Adds a region and/or edge to a given hostname
-     *
-     * @param hostname - A URI hostname (e.g. api.twilio.com)
-     * @param targetEdge - The targeted edge location (e.g. sydney)
-     * @param targetRegion - The targeted region location (e.g. au1)
-     */
-    getHostname(hostname: string, targetEdge: string | undefined, targetRegion: string | undefined): string;
-    /**
-     * Validates that a request to the new SSL certificate is successful.
-     *
-     * @throws RestException if the request fails
-     *
-     */
-    validateSslCert(): Promise<any>;
-}

package/dist/lib/base/BaseTwilio.js

@@ -1,167 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.BaseTwilio = void 0;
-const RequestClient_1 = __importDefault(require("./RequestClient")); /* jshint ignore:line */
-const os = require("os"); /* jshint ignore:line */
-const url = require("url"); /* jshint ignore:line */
-const moduleInfo = require("../../package.json"); /* jshint ignore:line */
-const util = require("util"); /* jshint ignore:line */
-const RestException = require("../base/RestException"); /* jshint ignore:line */
-/* jshint ignore:start */
-/**
- * Parent class for Twilio Client that implements request & validation logic
- */
-/* jshint ignore:end */
-class BaseTwilio {
-    /* jshint ignore:start */
-    /**
-     * Create a BaseTwilio instance
-     *
-     * @param username -
-     *          The username used for authentication. This is normally account sid, but if using key/secret auth will be
-     *          the api key sid.
-     * @param password -
-     *          The password used for authentication. This is normally auth token, but if using key/secret auth will be
-     *          the secret.
-     * @param opts - The options argument
-     *
-     * @returns A new instance of BaseTwilio
-     */
-    /* jshint ignore:end */
-    constructor(username, password, opts) {
-        this.opts = opts || {};
-        this.env = this.opts.env || process.env;
-        this.username =
-            username ||
-                this.env.TWILIO_ACCOUNT_SID ||
-                (() => {
-                    throw new Error("username is required");
-                })();
-        this.password =
-            password ||
-                this.env.TWILIO_AUTH_TOKEN ||
-                (() => {
-                    throw new Error("password is required");
-                })();
-        this.accountSid = this.opts.accountSid || this.username;
-        this.edge = this.opts.edge || this.env.TWILIO_EDGE;
-        this.region = this.opts.region || this.env.TWILIO_REGION;
-        this.logLevel = this.opts.logLevel || this.env.TWILIO_LOG_LEVEL;
-        this.userAgentExtensions = this.opts.userAgentExtensions || [];
-        this._httpClient = this.opts.httpClient;
-        if (this.opts.lazyLoading === false) {
-            this._httpClient = this.httpClient;
-        }
-        if (!this.accountSid.startsWith("AC")) {
-            const apiKeyMsg = this.accountSid.startsWith("SK")
-                ? ". The given SID indicates an API Key which requires the accountSid to be passed as an additional option"
-                : "";
-            throw new Error("accountSid must start with AC" + apiKeyMsg);
-        }
-    }
-    get httpClient() {
-        if (!this._httpClient) {
-            this._httpClient = new RequestClient_1.default();
-        }
-        return this._httpClient;
-    }
-    /* jshint ignore:start */
-    /**
-     * Makes a request to the Twilio API using the configured http client.
-     * Authentication information is automatically added if none is provided.
-     *
-     * @param opts - The options argument
-     */
-    /* jshint ignore:end */
-    request(opts) {
-        opts = opts || {};
-        if (!opts.method) {
-            throw new Error("method is required");
-        }
-        if (!opts.uri) {
-            throw new Error("uri is required");
-        }
-        const username = opts.username || this.username;
-        const password = opts.password || this.password;
-        const headers = opts.headers || {};
-        const pkgVersion = moduleInfo.version;
-        const osName = os.platform();
-        const osArch = os.arch();
-        const nodeVersion = process.version;
-        headers["User-Agent"] = util.format("twilio-node/%s (%s %s) node/%s", pkgVersion, osName, osArch, nodeVersion);
-        this.userAgentExtensions?.forEach((extension) => {
-            headers["User-Agent"] += ` ${extension}`;
-        });
-        headers["Accept-Charset"] = "utf-8";
-        if (opts.method === "post" && !headers["Content-Type"]) {
-            headers["Content-Type"] = "application/x-www-form-urlencoded";
-        }
-        if (!headers["Accept"]) {
-            headers["Accept"] = "application/json";
-        }
-        var uri = new url.URL(opts.uri);
-        uri.hostname = this.getHostname(uri.hostname, this.edge, this.region);
-        return this.httpClient?.request({
-            method: opts.method,
-            uri: uri.href,
-            username: username,
-            password: password,
-            headers: headers,
-            params: opts.params,
-            data: opts.data,
-            timeout: opts.timeout,
-            allowRedirects: opts.allowRedirects,
-            logLevel: opts.logLevel,
-        });
-    }
-    /* jshint ignore:start */
-    /**
-     * Adds a region and/or edge to a given hostname
-     *
-     * @param hostname - A URI hostname (e.g. api.twilio.com)
-     * @param targetEdge - The targeted edge location (e.g. sydney)
-     * @param targetRegion - The targeted region location (e.g. au1)
-     */
-    /* jshint ignore:end */
-    getHostname(hostname, targetEdge, targetRegion) {
-        const defaultRegion = "us1";
-        const domain = hostname.split(".").slice(-2).join(".");
-        const prefix = hostname.split("." + domain)[0];
-        let [product, edge, region] = prefix.split(".");
-        if (edge && !region) {
-            region = edge;
-            edge = undefined;
-        }
-        region = targetRegion || region || (targetEdge && defaultRegion);
-        if (!region) {
-            return hostname;
-        }
-        edge = targetEdge || edge;
-        return [product, edge, region, domain].filter((part) => part).join(".");
-    }
-    /* jshint ignore:start */
-    /**
-     * Validates that a request to the new SSL certificate is successful.
-     *
-     * @throws RestException if the request fails
-     *
-     */
-    /* jshint ignore:end */
-    validateSslCert() {
-        return this.httpClient
-            ?.request({
-            method: "get",
-            uri: "https://api.twilio.com:8443/2010-04-01/.json",
-        })
-            .then((response) => {
-            if (response["statusCode"] < 200 || response["statusCode"] >= 300) {
-                throw new RestException(response);
-            }
-            return response;
-        });
-    }
-}
-exports.BaseTwilio = BaseTwilio;

package/dist/lib/base/Domain.d.ts

@@ -1,29 +0,0 @@
-import { BaseTwilio, RequestOpts } from "./BaseTwilio";
-/**
- * Base domain object
- */
-export default class Domain {
-    twilio: BaseTwilio;
-    baseUrl: string;
-    /**
-     * Creates a Domain instance
-     *
-     * @param twilio - A Twilio Client
-     * @param baseUrl - Base url for this domain
-     */
-    constructor(twilio: BaseTwilio, baseUrl: string);
-    /**
-     * Turn a uri into an absolute url
-     *
-     * @param uri - uri to transform
-     * @returns absolute url
-     */
-    absoluteUrl(uri?: string): string;
-    /**
-     * Make request to this domain
-     *
-     * @param opts - request options
-     * @returns request promise
-     */
-    request(opts: RequestOpts): Promise<any>;
-}

package/dist/lib/base/Domain.js

@@ -1,53 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const utility_1 = require("./utility");
-/**
- * Base domain object
- */
-class Domain {
-    /**
-     * Creates a Domain instance
-     *
-     * @param twilio - A Twilio Client
-     * @param baseUrl - Base url for this domain
-     */
-    constructor(twilio, baseUrl) {
-        this.twilio = twilio;
-        this.baseUrl = baseUrl;
-    }
-    /**
-     * Turn a uri into an absolute url
-     *
-     * @param uri - uri to transform
-     * @returns absolute url
-     */
-    absoluteUrl(uri) {
-        var result = "";
-        if (typeof this.baseUrl === "string") {
-            const cleanBaseUrl = (0, utility_1.trim)(this.baseUrl, "/");
-            result += cleanBaseUrl;
-            result += "/";
-        }
-        if (typeof uri === "string") {
-            uri = (0, utility_1.trim)(uri, "/");
-            if (result === "") {
-                result += "/";
-            }
-            result += uri;
-        }
-        return result;
-    }
-    /**
-     * Make request to this domain
-     *
-     * @param opts - request options
-     * @returns request promise
-     */
-    request(opts) {
-        return this.twilio.request({
-            ...opts,
-            uri: this.absoluteUrl(opts.uri),
-        });
-    }
-}
-exports.default = Domain;

package/dist/lib/base/Page.d.ts

@@ -1,104 +0,0 @@
-import Version from "./Version";
-import Response from "../http/response";
-export interface TwilioResponsePayload {
-    [key: string]: any;
-    first_page_uri: string;
-    next_page_uri: string;
-    page: number;
-    page_size: number;
-    previous_page_uri: string;
-    uri: string;
-    meta?: {
-        key?: string;
-        next_page_url?: string;
-        previous_page_url?: string;
-    };
-}
-interface Solution {
-    [name: string]: any;
-}
-export default class Page<TVersion extends Version, TPayload extends TwilioResponsePayload, TResource, TInstance> {
-    nextPageUrl?: string;
-    previousPageUrl?: string;
-    instances: TInstance[];
-    _version: TVersion;
-    _payload: TPayload;
-    _solution: Solution;
-    /**
-     *
-     * Base page object to maintain request state.
-     *
-     * @param version - A twilio version instance
-     * @param response - The http response
-     * @param solution - path solution
-     */
-    constructor(version: TVersion, response: Response<string | TPayload>, solution: Solution);
-    /**
-     * Meta keys returned in a list request
-     *
-     * @constant META_KEYS
-     */
-    static META_KEYS: string[];
-    /**
-     * Get the url of the previous page of records
-     *
-     * @returns url of the previous page, or undefined if the
-     * previous page URI/URL is not defined.
-     */
-    getPreviousPageUrl(): string | undefined;
-    /**
-     * Get the url of the next page of records
-     *
-     * @returns url of the next page, or undefined if the
-     * next page URI/URL is not defined.
-     */
-    getNextPageUrl(): string | undefined;
-    /**
-     * Build a new instance given a json payload
-     *
-     * @param payload - Payload response from the API
-     * @returns instance of a resource
-     */
-    getInstance(payload: any): TInstance;
-    /**
-     * Load a list of records
-     *
-     * @param resources - json payload of records
-     * @returns list of resources
-     */
-    loadInstances(resources: TResource[]): TInstance[];
-    /**
-     * Fetch the next page of records
-     *
-     * @returns promise that resolves to next page of results,
-     * or undefined if there isn't a nextPageUrl undefined.
-     */
-    nextPage(): Promise<Page<TVersion, TPayload, TResource, TInstance>> | undefined;
-    /**
-     * Fetch the previous page of records
-     *
-     * @returns promise that resolves to previous page of
-     * results, or undefined if there isn't a previousPageUrl undefined.
-     */
-    previousPage(): Promise<Page<TVersion, TPayload, TResource, TInstance>> | undefined;
-    /**
-     * Parse json response from API
-     *
-     * @param response - API response
-     *
-     * @throws Error If non 200 status code is returned
-     *
-     * @returns json parsed response
-     */
-    processResponse(response: Response<string | TPayload>): TPayload;
-    /**
-     * Load a page of records
-     *
-     * @param  {object} payload json payload
-     * @return {array} the page of records
-     */
-    loadPage(payload: TPayload): TResource[];
-    forOwn(obj: object, iteratee: (val: any, key: string, object: object) => void): void;
-    toJSON(): object;
-}
-export {};