twilio 5.11.2 → 5.12.0

package/lib/base/ApiResponse.d.ts

@@ -0,0 +1,34 @@
+/**
+ * API Response wrapper containing HTTP metadata
+ *
+ * This interface is returned by *WithHttpInfo methods and provides access to:
+ * - The response data (resource instance, page, or boolean)
+ * - HTTP status code
+ * - Response headers
+ */
+export interface ApiResponse<T> {
+    /**
+     * The response data
+     * - For create/fetch/update: Resource instance
+     * - For delete/remove: boolean indicating success
+     * - For page: Page object
+     */
+    body: T;
+    /**
+     * HTTP status code from the response
+     * - 200: Success (fetch, update)
+     * - 201: Created (create)
+     * - 204: No Content (delete)
+     * - 4xx/5xx: Error responses
+     */
+    statusCode: number;
+    /**
+     * Response headers as key-value pairs
+     * Common headers include:
+     * - Content-Type
+     * - X-RateLimit-Remaining
+     * - X-RateLimit-Limit
+     * - X-Request-ID
+     */
+    headers: Record<string, string>;
+}

package/lib/base/ApiResponse.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/base/TokenPage.d.ts

@@ -0,0 +1,134 @@
+import Version from "./Version";
+import Response from "../http/response";
+/**
+ * Token-based pagination metadata structure
+ * Used for APIs that return pagination tokens instead of URLs
+ */
+export interface TokenPaginationPayload {
+    [key: string]: any;
+    meta: {
+        key: string;
+        pageSize?: number;
+        nextToken?: string | null;
+        previousToken?: string | null;
+    };
+}
+interface Solution {
+    [name: string]: any;
+}
+/**
+ * TokenPage handles token-based pagination where the API returns
+ * nextToken/previousToken strings instead of full URLs.
+ *
+ * Example response format:
+ * {
+ *   "meta": {
+ *     "key": "items",
+ *     "pageSize": 50,
+ *     "nextToken": "abc123",
+ *     "previousToken": "xyz789"
+ *   },
+ *   "items": [
+ *     { "id": 1, "name": "Item 1" },
+ *     { "id": 2, "name": "Item 2" }
+ *   ]
+ * }
+ */
+export default class TokenPage<TVersion extends Version, TPayload extends TokenPaginationPayload, TResource, TInstance> {
+    instances: TInstance[];
+    protected _version: TVersion;
+    protected _payload: TPayload;
+    protected _solution: Solution;
+    private readonly _uri;
+    private readonly _params;
+    /**
+     * Base page object to maintain request state for token-based pagination.
+     *
+     * @param version - A twilio version instance
+     * @param response - The http response
+     * @param uri - The URI for making pagination requests
+     * @param data - The request parameters
+     * @param solution - path solution
+     */
+    constructor(version: TVersion, response: Response<string | TPayload>, uri: string, data?: Record<string, any>, solution?: Solution);
+    /**
+     * 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 from the payload
+     *
+     * @param payload - json payload
+     * @returns the page of records
+     */
+    loadPage(payload: TPayload): TResource[];
+    /**
+     * Build a new instance given a json payload
+     *
+     * @param payload - Payload response from the API
+     * @returns instance of a resource
+     */
+    getInstance(payload: TResource): TInstance;
+    /**
+     * Load a list of records
+     *
+     * @param resources - json payload of records
+     * @returns list of resources
+     */
+    loadInstances(resources: TResource[]): TInstance[];
+    toJSON(): object;
+    /**
+     * Returns the key that identifies the collection in the response.
+     *
+     * @returns the key or undefined if doesn't exist
+     */
+    get key(): string | undefined;
+    /**
+     * Returns the page size or undefined if doesn't exist.
+     *
+     * @returns the page size or undefined
+     */
+    get pageSize(): number | undefined;
+    /**
+     * Returns the next_token for pagination or undefined if doesn't exist.
+     *
+     * @returns the next token or undefined
+     */
+    get nextToken(): string | undefined;
+    /**
+     * Returns the previous_token for pagination or undefined if doesn't exist.
+     *
+     * @returns the previous token or undefined
+     */
+    get previousToken(): string | undefined;
+    /**
+     * Internal helper to fetch a page using a given token.
+     *
+     * @param token - The pagination token to use
+     * @returns promise that resolves to the page or undefined if no token exists
+     */
+    private _getPage;
+    /**
+     * Fetch the next page of records using token-based pagination.
+     * Makes a request to the same URI with pageToken set to nextToken.
+     *
+     * @returns promise that resolves to next page of results,
+     * or undefined if there isn't a nextToken.
+     */
+    nextPage(): Promise<TokenPage<TVersion, TPayload, TResource, TInstance>> | undefined;
+    /**
+     * Fetch the previous page of records using token-based pagination.
+     * Makes a request to the same URI with pageToken set to previousToken.
+     *
+     * @returns promise that resolves to previous page of results,
+     * or undefined if there isn't a previousToken.
+     */
+    previousPage(): Promise<TokenPage<TVersion, TPayload, TResource, TInstance>> | undefined;
+}
+export {};

package/lib/base/TokenPage.js

@@ -0,0 +1,197 @@
+"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"));
+/**
+ * TokenPage handles token-based pagination where the API returns
+ * nextToken/previousToken strings instead of full URLs.
+ *
+ * Example response format:
+ * {
+ *   "meta": {
+ *     "key": "items",
+ *     "pageSize": 50,
+ *     "nextToken": "abc123",
+ *     "previousToken": "xyz789"
+ *   },
+ *   "items": [
+ *     { "id": 1, "name": "Item 1" },
+ *     { "id": 2, "name": "Item 2" }
+ *   ]
+ * }
+ */
+class TokenPage {
+    /**
+     * Base page object to maintain request state for token-based pagination.
+     *
+     * @param version - A twilio version instance
+     * @param response - The http response
+     * @param uri - The URI for making pagination requests
+     * @param data - The request parameters
+     * @param solution - path solution
+     */
+    constructor(version, response, uri, data = {}, solution = {}) {
+        const payload = this.processResponse(response);
+        this._version = version;
+        this._payload = payload;
+        this._solution = solution;
+        this._uri = uri;
+        this._params = data;
+        this.instances = this.loadInstances(this.loadPage(payload));
+    }
+    /**
+     * 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 from the payload
+     *
+     * @param payload - json payload
+     * @returns the page of records
+     */
+    loadPage(payload) {
+        if (payload.meta?.key) {
+            return payload[payload.meta.key];
+        }
+        throw new Error("Token pagination requires meta.key to be present in response");
+    }
+    /**
+     * 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("TokenPage.getInstance() must be implemented in the derived class");
+    }
+    /**
+     * Load a list of records
+     *
+     * @param resources - json payload of records
+     * @returns list of resources
+     */
+    loadInstances(resources) {
+        const instances = [];
+        resources.forEach((resource) => {
+            instances.push(this.getInstance(resource));
+        });
+        return instances;
+    }
+    toJSON() {
+        const clone = {};
+        Object.entries(this).forEach(([key, value]) => {
+            if (!key.startsWith("_") && typeof value !== "function") {
+                clone[key] = value;
+            }
+        });
+        return clone;
+    }
+    /**
+     * Returns the key that identifies the collection in the response.
+     *
+     * @returns the key or undefined if doesn't exist
+     */
+    get key() {
+        if (this._payload.meta && this._payload.meta.key) {
+            return this._payload.meta.key;
+        }
+        return undefined;
+    }
+    /**
+     * Returns the page size or undefined if doesn't exist.
+     *
+     * @returns the page size or undefined
+     */
+    get pageSize() {
+        if (this._payload.meta && this._payload.meta.pageSize) {
+            return this._payload.meta.pageSize;
+        }
+        return undefined;
+    }
+    /**
+     * Returns the next_token for pagination or undefined if doesn't exist.
+     *
+     * @returns the next token or undefined
+     */
+    get nextToken() {
+        if (this._payload.meta &&
+            this._payload.meta.nextToken !== undefined &&
+            this._payload.meta.nextToken !== null) {
+            return this._payload.meta.nextToken;
+        }
+        return undefined;
+    }
+    /**
+     * Returns the previous_token for pagination or undefined if doesn't exist.
+     *
+     * @returns the previous token or undefined
+     */
+    get previousToken() {
+        if (this._payload.meta &&
+            this._payload.meta.previousToken !== undefined &&
+            this._payload.meta.previousToken !== null) {
+            return this._payload.meta.previousToken;
+        }
+        return undefined;
+    }
+    /**
+     * Internal helper to fetch a page using a given token.
+     *
+     * @param token - The pagination token to use
+     * @returns promise that resolves to the page or undefined if no token exists
+     */
+    _getPage(token) {
+        if (!token) {
+            return undefined;
+        }
+        if (!this._uri) {
+            throw new Error("URI must be provided for token pagination");
+        }
+        const params = { ...this._params, pageToken: token };
+        const responsePromise = this._version.page({
+            method: "get",
+            uri: this._uri,
+            params: params,
+        });
+        return responsePromise.then((response) => {
+            return new this.constructor(this._version, response, this._uri, this._params, this._solution);
+        });
+    }
+    /**
+     * Fetch the next page of records using token-based pagination.
+     * Makes a request to the same URI with pageToken set to nextToken.
+     *
+     * @returns promise that resolves to next page of results,
+     * or undefined if there isn't a nextToken.
+     */
+    nextPage() {
+        return this._getPage(this.nextToken);
+    }
+    /**
+     * Fetch the previous page of records using token-based pagination.
+     * Makes a request to the same URI with pageToken set to previousToken.
+     *
+     * @returns promise that resolves to previous page of results,
+     * or undefined if there isn't a previousToken.
+     */
+    previousPage() {
+        return this._getPage(this.previousToken);
+    }
+}
+exports.default = TokenPage;

package/lib/base/TwilioServiceException.d.ts

@@ -0,0 +1,30 @@
+interface ValidationError {
+    detail: string;
+    pointer: string;
+}
+interface TwilioServiceErrorResponse {
+    type: string;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    code: number;
+    errors?: ValidationError[];
+}
+export default class TwilioServiceException extends Error implements TwilioServiceErrorResponse {
+    type: string;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    code: number;
+    errors?: ValidationError[];
+    constructor(response: any);
+    /**
+     * Check if a response body matches the RFC-9457 structure
+     * @param body - The response body to check
+     * @returns true if the body has the required RFC-9457 fields
+     */
+    static isRFC9457Response(body: any): boolean;
+}
+export {};

package/lib/base/TwilioServiceException.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class TwilioServiceException extends Error {
+    constructor(response) {
+        const isResponseBodyString = typeof response.body == "string";
+        const body = isResponseBodyString
+            ? parseResponseBody(response.body)
+            : response.body;
+        // Initialize status first for the error message
+        const status = body?.status || response.statusCode;
+        super(`[HTTP ${status}] ${body?.title || "Failed to execute request"}`);
+        // Set all required properties
+        this.type = body?.type || "";
+        this.title = body?.title || "Failed to execute request";
+        this.status = status;
+        this.code = body?.code || 0;
+        // Set optional properties
+        if (body?.detail) {
+            this.detail = body.detail;
+        }
+        if (body?.instance) {
+            this.instance = body.instance;
+        }
+        if (body?.errors) {
+            this.errors = body.errors;
+        }
+    }
+    /**
+     * Check if a response body matches the RFC-9457 structure
+     * @param body - The response body to check
+     * @returns true if the body has the required RFC-9457 fields
+     */
+    static isRFC9457Response(body) {
+        if (!body || typeof body !== "object") {
+            return false;
+        }
+        // Check for required fields according to the spec
+        return (typeof body.type === "string" &&
+            typeof body.title === "string" &&
+            typeof body.status === "number" &&
+            typeof body.code === "number");
+    }
+}
+exports.default = TwilioServiceException;
+function parseResponseBody(response_body) {
+    let body = null;
+    try {
+        body = JSON.parse(response_body);
+    }
+    catch (catchError) {
+        body = null;
+    }
+    return body;
+}

package/lib/base/Version.d.ts

@@ -1,5 +1,6 @@
 import Domain from "./Domain";
 import { RequestOpts } from "./BaseTwilio";
+import { ApiResponse } from "./ApiResponse";
 export interface PageLimitOptions {
     /**
      * The maximum number of items to fetch
@@ -26,6 +27,14 @@ export default class Version {
      */
     constructor(domain: Domain, version: string | Version);
     get domain(): Domain;
+    /**
+     * Throws the appropriate exception based on the response format
+     *
+     * @param response - the response object
+     * @throws TwilioServiceException if response matches RFC-9457 format
+     * @throws RestException for legacy format
+     */
+    private throwException;
     /**
      * Generate absolute url from a uri
      *
@@ -104,6 +113,66 @@ export default class Version {
      * @returns promise that resolves to true if record was deleted
      */
     remove(opts: RequestOpts): Promise<boolean>;
+    /**
+     * Create a new record and return response metadata
+     *
+     * @param opts - request options
+     *
+     * @throws TwilioServiceException if response matches RFC-9457 format
+     * @throws RestException for legacy format
+     * @throws Error If response returns non 2xx or 201 status code
+     *
+     * @returns promise that resolves to ApiResponse with created record and metadata
+     */
+    createWithResponseInfo<T>(opts: RequestOpts): Promise<ApiResponse<T>>;
+    /**
+     * Fetch an instance of a record and return response metadata
+     *
+     * @param opts - request options
+     *
+     * @throws TwilioServiceException if response matches RFC-9457 format
+     * @throws RestException for legacy format
+     * @throws Error If response returns non 2xx or 3xx status code
+     *
+     * @returns promise that resolves to ApiResponse with fetched record and metadata
+     */
+    fetchWithResponseInfo<T>(opts: RequestOpts): Promise<ApiResponse<T>>;
+    /**
+     * Update a record and return response metadata
+     *
+     * @param opts - request options
+     *
+     * @throws TwilioServiceException if response matches RFC-9457 format
+     * @throws RestException for legacy format
+     * @throws Error If response returns non 2xx status code
+     *
+     * @returns promise that resolves to ApiResponse with updated record and metadata
+     */
+    updateWithResponseInfo<T>(opts: RequestOpts): Promise<ApiResponse<T>>;
+    /**
+     * Patch a record and return response metadata
+     *
+     * @param opts - request options
+     *
+     * @throws TwilioServiceException if response matches RFC-9457 format
+     * @throws RestException for legacy format
+     * @throws Error If response returns non 2xx status code
+     *
+     * @returns promise that resolves to ApiResponse with patched record and metadata
+     */
+    patchWithResponseInfo<T>(opts: RequestOpts): Promise<ApiResponse<T>>;
+    /**
+     * Delete a record and return response metadata
+     *
+     * @param opts - request options
+     *
+     * @throws TwilioServiceException if response matches RFC-9457 format
+     * @throws RestException for legacy format
+     * @throws Error If response returns a 5xx status
+     *
+     * @returns promise that resolves to ApiResponse with boolean and metadata
+     */
+    removeWithResponseInfo(opts: RequestOpts): Promise<ApiResponse<boolean>>;
     /**
      * Process limits for list requests
      *
@@ -136,4 +205,37 @@ export default class Version {
      */
     each<T>(params?: any, callback?: (item: T, done: (err?: Error) => void) => void): Promise<void>;
     list<T>(params?: any, callback?: (error: Error | null, items: T) => any): Promise<any>;
+    /**
+     * For each record instance, executes a provided callback function with that
+     * instance and captures HTTP response metadata from the first page
+     *
+     * @param params - Parameters (Optional)
+     * @param params.limit - Optional maximum number of record instances to
+     *  fetch
+     * @param params.pageSize - Optional maximum number of records to return
+     *  with every request
+     * @param params.callback - Callback function to call with each
+     *  record instance
+     * @param params.done - Optional done function to call when all
+     *  records are processed, the limit is reached, or an error occurs.
+     *  Receives an error argument if an error occurs, and ApiResponse metadata.
+     * @param callback - Callback function to call with each record.
+     *  Receives a done function argument that will short-circuit the for-each
+     *  loop that may accept an error argument.
+     * @returns Returns a promise that resolves with first page metadata when all records
+     *  processed or if the limit is reached, and rejects with an error if an
+     *  error occurs and is not handled in the user provided done function.
+     */
+    eachWithHttpInfo<T>(params?: any, callback?: (item: T, done: (err?: Error) => void) => void): Promise<ApiResponse<void>>;
+    /**
+     * Fetches all records and returns them as an array with HTTP response metadata
+     * from the first page
+     *
+     * @param params - Parameters (Optional)
+     * @param params.limit - Optional maximum number of record instances to fetch
+     * @param params.pageSize - Optional maximum number of records to return with every request
+     * @param callback - Optional callback function
+     * @returns Promise that resolves to ApiResponse with array of all records and first page metadata
+     */
+    listWithHttpInfo<T>(params?: any, callback?: (error: Error | null, items: ApiResponse<T[]>) => any): Promise<ApiResponse<T[]>>;
 }