twilio 3.83.4 → 4.0.0-rc.2

package/README.md

@@ -19,12 +19,9 @@ 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.
 
@@ -32,6 +29,12 @@ 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.
@@ -42,15 +45,28 @@ 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: true
+    lazyLoading: false
 });
 ```
 

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+declare const _exports: {
+    (accountSid: any, authToken: any, opts: any): import("./lib/rest/Twilio");
+    Twilio: typeof import("./lib/rest/Twilio");
+    jwt: typeof import("./lib").jwt;
+    twiml: typeof import("./lib").twiml;
+    RequestClient: typeof import("./lib/base/RequestClient");
+    validateRequest: typeof import("./lib/webhooks/webhooks").validateRequest;
+    validateRequestWithBody: typeof import("./lib/webhooks/webhooks").validateRequestWithBody;
+    validateExpressRequest: typeof import("./lib/webhooks/webhooks").validateExpressRequest;
+    webhook: typeof import("./lib/webhooks/webhooks").webhook;
+};
+export = _exports;

package/dist/index.js

@@ -0,0 +1 @@
+module.exports = require("./lib");

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

@@ -0,0 +1,84 @@
+/// <reference types="node" />
+import * as 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
+ *
+ * @constructor BaseTwilio
+ *
+ * @param {string} username -
+ *          The username used for authentication. This is normally account sid, but if using key/secret auth will be
+ *          the api key sid.
+ * @param {string} password -
+ *          The password used for authentication. This is normally auth token, but if using key/secret auth will be
+ *          the secret.
+ * @param {ClientOpts} [opts] - The options argument
+ *
+ * @returns {BaseTwilio} A new instance of BaseTwilio
+ */
+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;
+    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.
+     *
+     * @function request
+     * @memberof BaseTwilio#
+     *
+     * @param {RequestOpts} opts - The options argument
+     */
+    request(opts: RequestOpts): Promise<import("../http/response")<object>>;
+    /**
+     * Adds a region and/or edge to a given hostname
+     *
+     * @function getHostname
+     * @memberof BaseTwilio#
+     *
+     * @param {string} hostname - A URI hostname (e.g. api.twilio.com)
+     * @param {string | undefined} targetEdge - The targeted edge location (e.g. sydney)
+     * @param {string | undefined} 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
+     *
+     * @function validateSslCert
+     * @memberof BaseTwilio#
+     */
+    validateSslCert(): Promise<any>;
+}

package/dist/lib/base/BaseTwilio.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseTwilio = void 0;
+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
+ *
+ * @constructor BaseTwilio
+ *
+ * @param {string} username -
+ *          The username used for authentication. This is normally account sid, but if using key/secret auth will be
+ *          the api key sid.
+ * @param {string} password -
+ *          The password used for authentication. This is normally auth token, but if using key/secret auth will be
+ *          the secret.
+ * @param {ClientOpts} [opts] - The options argument
+ *
+ * @returns {BaseTwilio} A new instance of BaseTwilio
+ */
+/* jshint ignore:end */
+class BaseTwilio {
+    constructor(username, password, opts) {
+        this.opts = opts || {};
+        this.env = this.opts.env || process.env;
+        this.username = username || this.env.TWILIO_ACCOUNT_SID;
+        this.password = password || this.env.TWILIO_AUTH_TOKEN;
+        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.username) {
+            throw new Error("username is required");
+        }
+        if (!this.password) {
+            throw new Error("password is required");
+        }
+        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) {
+            const RequestClient = require("../base/RequestClient"); /* jshint ignore:line */
+            this._httpClient = new RequestClient();
+        }
+        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.
+     *
+     * @function request
+     * @memberof BaseTwilio#
+     *
+     * @param {RequestOpts} 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
+     *
+     * @function getHostname
+     * @memberof BaseTwilio#
+     *
+     * @param {string} hostname - A URI hostname (e.g. api.twilio.com)
+     * @param {string | undefined} targetEdge - The targeted edge location (e.g. sydney)
+     * @param {string | undefined} 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
+     *
+     * @function validateSslCert
+     * @memberof BaseTwilio#
+     */
+    /* 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

@@ -0,0 +1,37 @@
+export = Domain;
+/**
+ * Base domain object
+ *
+ * @constructor
+ *
+ * @param {Twilio} twilio - A Twilio Client
+ * @param {string} baseUrl - Base url for this domain
+ */
+declare function Domain(twilio: Twilio, baseUrl: string): void;
+declare class Domain {
+    /**
+     * Base domain object
+     *
+     * @constructor
+     *
+     * @param {Twilio} twilio - A Twilio Client
+     * @param {string} baseUrl - Base url for this domain
+     */
+    constructor(twilio: Twilio, baseUrl: string);
+    twilio: Twilio;
+    baseUrl: string;
+    /**
+     * Turn a uri into an absolute url
+     *
+     * @param  {string} uri uri to transform
+     * @return {string} absolute url
+     */
+    absoluteUrl(uri: string): string;
+    /**
+     * Make request to this domain
+     *
+     * @param {object} opts request options
+     * @return {Promise} request promise
+     */
+    request(opts: object): Promise<any>;
+}

package/dist/lib/base/Domain.js

@@ -0,0 +1,49 @@
+"use strict";
+const { trim } = require("./utility");
+/**
+ * Base domain object
+ *
+ * @constructor
+ *
+ * @param {Twilio} twilio - A Twilio Client
+ * @param {string} baseUrl - Base url for this domain
+ */
+function Domain(twilio, baseUrl) {
+    this.twilio = twilio;
+    this.baseUrl = baseUrl;
+}
+/**
+ * Turn a uri into an absolute url
+ *
+ * @param  {string} uri uri to transform
+ * @return {string} absolute url
+ */
+Domain.prototype.absoluteUrl = function (uri) {
+    var result = "";
+    if (typeof this.baseUrl === "string") {
+        const cleanBaseUrl = trim(this.baseUrl, "/");
+        result += cleanBaseUrl;
+        result += "/";
+    }
+    if (typeof uri === "string") {
+        uri = trim(uri, "/");
+        if (result === "") {
+            result += "/";
+        }
+        result += uri;
+    }
+    return result;
+};
+/**
+ * Make request to this domain
+ *
+ * @param {object} opts request options
+ * @return {Promise} request promise
+ */
+Domain.prototype.request = function (opts) {
+    return this.twilio.request({
+        ...opts,
+        uri: this.absoluteUrl(opts.uri),
+    });
+};
+module.exports = Domain;

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

@@ -0,0 +1,90 @@
+export = Page;
+/**
+ * @constructor
+ *
+ * @description Base page object to maintain request state.
+ *
+ * @param {Version} version - A twilio version instance
+ * @param {Object} response - The http response
+ * @param {Object} solution - path solution
+ */
+declare function Page(version: Version, response: any, solution: any): void;
+declare class Page {
+    /**
+     * @constructor
+     *
+     * @description Base page object to maintain request state.
+     *
+     * @param {Version} version - A twilio version instance
+     * @param {Object} response - The http response
+     * @param {Object} solution - path solution
+     */
+    constructor(version: Version, response: any, solution: any);
+    _version: Version;
+    _payload: any;
+    _solution: any;
+    nextPageUrl: string;
+    previousPageUrl: string;
+    instances: any[];
+    /**
+     * @constant META_KEYS
+     * @description meta keys returned in a list request
+     */
+    META_KEYS: string[];
+    /**
+     * Get the url of the previous page of records
+     *
+     * @return {string|undefined} url of the previous page
+     */
+    getPreviousPageUrl(): string | undefined;
+    /**
+     * Get the url of the next page of records
+     *
+     * @return {string|undefined} url of the next page
+     */
+    getNextPageUrl(): string | undefined;
+    /**
+     * Build a new instance given a json payload
+     * @abstract
+     *
+     * @param {object} payload - Payload response from the API
+     * @return {object} instance of a resource
+     */
+    getInstance(payload: object): object;
+    /**
+     * Load a list of records
+     *
+     * @param  {object} resources json payload of records
+     * @return {Array} list of resources
+     */
+    loadInstances(resources: object): any[];
+    /**
+     * Fetch the next page of records
+     *
+     * @return {promise} promise that resolves to next page of results
+     */
+    nextPage(): Promise<any>;
+    /**
+     * Fetch the previous page of records
+     *
+     * @return {promise} promise that resolves to previous page of results
+     */
+    previousPage(): Promise<any>;
+    /**
+     * Parse json response from API
+     * @throws {Error} If non 200 status code is returned
+     *
+     * @param  {object} response API response
+     * @return {object} json parsed response
+     */
+    processResponse(response: object): object;
+    /**
+     * Load a page of records
+     * @throws {Error} If records cannot be deserialized
+     *
+     * @param  {object} payload json payload
+     * @return {array} the page of records
+     */
+    loadPage(payload: object): any[];
+    toJSON(): {};
+}

package/dist/lib/base/Page.js

@@ -0,0 +1,180 @@
+"use strict";
+var RestException = require("./RestException");
+/**
+ * @constructor
+ *
+ * @description Base page object to maintain request state.
+ *
+ * @param {Version} version - A twilio version instance
+ * @param {Object} response - The http response
+ * @param {Object} solution - path solution
+ */
+function Page(version, response, solution) {
+    var payload = this.processResponse(response);
+    this._version = version;
+    this._payload = payload;
+    this._solution = solution;
+    this.nextPageUrl = this.getNextPageUrl();
+    this.previousPageUrl = this.getPreviousPageUrl();
+    this.instances = this.loadInstances(this.loadPage(payload));
+}
+/**
+ * @constant META_KEYS
+ * @description meta keys returned in a list request
+ */
+Page.prototype.META_KEYS = [
+    "end",
+    "first_page_uri",
+    "last_page_uri",
+    "next_page_uri",
+    "num_pages",
+    "page",
+    "page_size",
+    "previous_page_uri",
+    "start",
+    "total",
+    "uri",
+];
+/**
+ * Get the url of the previous page of records
+ *
+ * @return {string|undefined} url of the previous page
+ */
+Page.prototype.getPreviousPageUrl = function () {
+    if ("meta" in this._payload &&
+        "previous_page_url" in this._payload.meta &&
+        this._payload.meta.previous_page_url) {
+        // jshint ignore:line
+        return this._payload.meta.previous_page_url; // jshint ignore:line
+    }
+    if ("previous_page_uri" in this._payload && this._payload.previous_page_uri) {
+        // jshint ignore:line
+        return this._version._domain.absoluteUrl(this._payload.previous_page_uri); // jshint ignore:line
+    }
+    return undefined;
+};
+/**
+ * Get the url of the next page of records
+ *
+ * @return {string|undefined} url of the next page
+ */
+Page.prototype.getNextPageUrl = function () {
+    if ("meta" in this._payload &&
+        "next_page_url" in this._payload.meta &&
+        this._payload.meta.next_page_url) {
+        // jshint ignore:line
+        return this._payload.meta.next_page_url; // jshint ignore:line
+    }
+    if ("next_page_uri" in this._payload && this._payload.next_page_uri) {
+        // jshint ignore:line
+        return this._version._domain.absoluteUrl(this._payload.next_page_uri); // jshint ignore:line
+    }
+    return undefined;
+};
+/**
+ * Build a new instance given a json payload
+ * @abstract
+ *
+ * @param {object} payload - Payload response from the API
+ * @return {object} instance of a resource
+ */
+Page.prototype.getInstance = function (payload) {
+    throw new Error("Page.get_instance() must be implemented in the derived class");
+};
+/**
+ * Load a list of records
+ *
+ * @param  {object} resources json payload of records
+ * @return {Array} list of resources
+ */
+Page.prototype.loadInstances = function (resources) {
+    Object.keys(resources).forEach((key) => {
+        resources[key] = this.getInstance(resources[key]);
+    });
+    return resources;
+};
+/**
+ * Fetch the next page of records
+ *
+ * @return {promise} promise that resolves to next page of results
+ */
+Page.prototype.nextPage = function () {
+    if (!this.nextPageUrl) {
+        return undefined;
+    }
+    var promise = this._version._domain.twilio.request({
+        method: "GET",
+        uri: this.nextPageUrl,
+    });
+    promise = promise.then(function (response) {
+        return new this.constructor(this._version, response, this._solution);
+    }.bind(this));
+    return promise;
+};
+/**
+ * Fetch the previous page of records
+ *
+ * @return {promise} promise that resolves to previous page of results
+ */
+Page.prototype.previousPage = function () {
+    if (!this.previousPageUrl) {
+        return undefined;
+    }
+    var promise = this._version._domain.twilio.request({
+        method: "GET",
+        uri: this.previousPageUrl,
+    });
+    promise = promise.then(function (response) {
+        return new this.constructor(this._version, response, this._solution);
+    }.bind(this));
+    return promise;
+};
+/**
+ * Parse json response from API
+ * @throws {Error} If non 200 status code is returned
+ *
+ * @param  {object} response API response
+ * @return {object} json parsed response
+ */
+Page.prototype.processResponse = function (response) {
+    if (response.statusCode !== 200) {
+        throw new RestException(response);
+    }
+    if (typeof response.body === "string") {
+        return JSON.parse(response.body);
+    }
+    return response.body;
+};
+/**
+ * Load a page of records
+ * @throws {Error} If records cannot be deserialized
+ *
+ * @param  {object} payload json payload
+ * @return {array} the page of records
+ */
+Page.prototype.loadPage = function (payload) {
+    if ("meta" in payload && "key" in payload.meta) {
+        return payload[payload.meta.key];
+    }
+    const keys = Object.keys(payload).filter((key) => !this.META_KEYS.includes(key));
+    if (keys.length === 1) {
+        return payload[keys[0]];
+    }
+    throw new Error("Page Records cannot be deserialized");
+};
+function forOwn(obj, iteratee) {
+    obj = Object(obj);
+    for (const [key, val] of Object.entries(obj)) {
+        iteratee(val, key, obj);
+    }
+}
+Page.prototype.toJSON = function toJSON() {
+    let clone = {};
+    forOwn(this, (value, key) => {
+        if (!key.startsWith("_") && typeof value !== "function") {
+            clone[key] = value;
+        }
+    });
+    return clone;
+};
+module.exports = Page;