twilio 4.0.1 → 4.0.2

package/lib/base/BaseTwilio.d.ts

@@ -0,0 +1,81 @@
+/// <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[];
+    autoRetry?: boolean;
+    maxRetries?: number;
+}
+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;
+    autoRetry: boolean;
+    maxRetries?: number;
+    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/lib/base/BaseTwilio.js

@@ -0,0 +1,172 @@
+"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.autoRetry = this.opts.autoRetry || false;
+        this.maxRetries = this.opts.maxRetries;
+        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({
+                autoRetry: this.autoRetry,
+                maxRetries: this.maxRetries,
+            });
+        }
+        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/lib/base/Domain.d.ts

@@ -0,0 +1,29 @@
+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/lib/base/Domain.js

@@ -0,0 +1,53 @@
+"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/lib/base/Page.d.ts

@@ -0,0 +1,104 @@
+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 {};

package/lib/base/Page.js

@@ -0,0 +1,192 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const RestException_1 = __importDefault(require("./RestException"));
+class Page {
+    /**
+     *
+     * Base page object to maintain request state.
+     *
+     * @param version - A twilio version instance
+     * @param response - The http response
+     * @param solution - path solution
+     */
+    constructor(version, response, solution) {
+        let 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));
+    }
+    /**
+     * 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() {
+        if (this._payload.meta &&
+            "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
+     *
+     * @returns url of the next page, or undefined if the
+     * next page URI/URL is not defined.
+     */
+    getNextPageUrl() {
+        if (this._payload.meta &&
+            "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
+     *
+     * @param payload - Payload response from the API
+     * @returns instance of a resource
+     */
+    getInstance(payload) {
+        throw new Error("Page.get_instance() must be implemented in the derived class");
+    }
+    /**
+     * Load a list of records
+     *
+     * @param resources - json payload of records
+     * @returns list of resources
+     */
+    loadInstances(resources) {
+        let instances = [];
+        resources.forEach((resource) => {
+            instances.push(this.getInstance(resource));
+        });
+        return instances;
+    }
+    /**
+     * 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() {
+        if (!this.nextPageUrl) {
+            return undefined;
+        }
+        var reqPromise = this._version._domain.twilio.request({
+            method: "get",
+            uri: this.nextPageUrl,
+        });
+        var nextPagePromise = reqPromise.then(function (response) {
+            return new this.constructor(this._version, response, this._solution);
+        }.bind(this));
+        return nextPagePromise;
+    }
+    /**
+     * 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() {
+        if (!this.previousPageUrl) {
+            return undefined;
+        }
+        var reqPromise = this._version._domain.twilio.request({
+            method: "get",
+            uri: this.previousPageUrl,
+        });
+        var prevPagePromise = reqPromise.then(function (response) {
+            return new this.constructor(this._version, response, this._solution);
+        }.bind(this));
+        return prevPagePromise;
+    }
+    /**
+     * Parse json response from API
+     *
+     * @param response - API response
+     *
+     * @throws Error If non 200 status code is returned
+     *
+     * @returns json parsed response
+     */
+    processResponse(response) {
+        if (response.statusCode !== 200) {
+            throw new RestException_1.default(response);
+        }
+        if (typeof response.body === "string") {
+            return JSON.parse(response.body);
+        }
+        return response.body;
+    }
+    /**
+     * Load a page of records
+     *
+     * @param  {object} payload json payload
+     * @return {array} the page of records
+     */
+    loadPage(payload) {
+        if (payload.meta?.key) {
+            return payload[payload.meta.key];
+        }
+        const keys = Object.keys(payload).filter((key) => !Page.META_KEYS.includes(key));
+        if (keys.length === 1) {
+            return payload[keys[0]];
+        }
+        throw new Error("Page Records cannot be deserialized");
+    }
+    forOwn(obj, iteratee) {
+        obj = Object(obj);
+        for (const [key, val] of Object.entries(obj)) {
+            iteratee(val, key, obj);
+        }
+    }
+    toJSON() {
+        const clone = {};
+        this.forOwn(this, (value, key) => {
+            if (!key.startsWith("_") && typeof value !== "function") {
+                clone[key] = value;
+            }
+        });
+        return clone;
+    }
+}
+exports.default = Page;
+/**
+ * Meta keys returned in a list request
+ *
+ * @constant META_KEYS
+ */
+Page.META_KEYS = [
+    "end",
+    "first_page_uri",
+    "last_page_uri",
+    "next_page_uri",
+    "num_pages",
+    "page",
+    "page_size",
+    "previous_page_uri",
+    "start",
+    "total",
+    "uri",
+];