@twilio/mcs-client 0.5.2 → 0.6.0-canary.18

package/builds/lib.d.ts

@@ -1,6 +1,45 @@
 /// <reference types="node" />
 import * as log from "loglevel";
 import * as loglevel from "loglevel";
+/**
+ * Cancellable promise. Extends the functionality of the native Promise to include the cancel method.
+ *
+ * Example:
+ *
+ * ```ts
+ *
+ * const cancellableFetchPromise = new CancellablePromise(async (resolve, reject, onCancel) => {
+ *     const request = fetch("https://example.com/");
+ *
+ *     onCancel(() => request.cancel());
+ *
+ *     try {
+ *         const response = await request;
+ *         resolve(response);
+ *     } catch (err) {
+ *         reject(err);
+ *     }
+ * });
+ *
+ * cancellableFetchPromise.cancel();
+ * ```
+ */
+declare class CancellablePromise<T> extends Promise<T> {
+    private readonly onCancel?;
+    private rejectPromise?;
+    /**
+     * Creates a new CancellablePromise.
+     * @param executor A callback used to initialize the promise. This callback is passed three arguments:
+     * a resolve callback used to resolve the promise with a value or the result of another promise,
+     * a reject callback used to reject the promise with a provided reason or error,
+     * and an onCancel callback used to define behavior of cancellation.
+     */
+    constructor(executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: string | Error) => void, onCancel: (cancellationFunction: () => void) => void) => void);
+    /**
+     * Cancels the promise and invokes the cancellation callback if it was defined during instantiation. Cancellation will result in the promise being rejected.
+     */
+    cancel(): void;
+}
 type Headers = {
     [id: string]: string;
 };
@@ -17,11 +56,11 @@ declare class Transport {
     /**
      * Make a GET request by given URL
      */
-    get(url: string, headers: Headers): Promise<Response>;
+    get(url: string, headers: Headers): CancellablePromise<Response>;
     /**
      * Make a POST request by given URL
      */
-    post(url: string, headers: Headers, body?: any): Promise<Response>;
+    post(url: string, headers: Headers, body?: any): CancellablePromise<Response>;
 }
 interface BackoffOverride {
     max: number;
@@ -60,8 +99,8 @@ declare class Network {
     private backoffConfig;
     private retryWhenThrottled;
     private executeWithRetry;
-    get(url: string): Promise<any>;
-    post(url: string, category: MediaCategory | null, media: string | Buffer | Blob | FormData, contentType?: string, filename?: string): Promise<any>;
+    get(url: string): CancellablePromise<any>;
+    post(url: string, category: MediaCategory | null, media: string | Buffer | Blob | FormData | Record<string, unknown>, contentType?: string, filename?: string): CancellablePromise<any>;
 }
 type MediaCategory = "media" | "body" | "history";
 interface Links {
@@ -118,21 +157,8 @@ declare class Media {
      *
      * It is reasonable to build your own refresh logic upon these two functions: as soon as URL returned
      * by getCachedContentUrl() returns 40x status you should call getContentUrl() to refresh it.
-     *
-     * @returns {Promise<string>}
      */
-    getContentUrl(): Promise<string | null>;
-    /**
-     * Returns direct content URL to uploaded binary. This URL will expire after some time.
-     * This function does not support getting a new URL however. Once set it will remain the same.
-     * Use getContentUrl() to query a new one.
-     *
-     * It is reasonable to build your own refresh logic upon these two functions: as soon as URL returned
-     * by getCachedContentUrl() returns 40x status you should call getContentUrl() to refresh it.
-     *
-     * @returns {Promise<string>}
-     */
-    getCachedContentUrl(): Promise<string | null>;
+    getContentUrl(): CancellablePromise<string | null>;
     private _update;
 }
 interface Options$0 {
@@ -175,30 +201,32 @@ declare class Client {
     /**
      * Gets media from media service
      * @param {String} sid - Media's SID
-     * @returns {Promise<Media>}
      */
-    get(sid: string): Promise<Media>;
+    get(sid: string): CancellablePromise<Media>;
     /**
      * Posts raw content to media service
      * @param {String} contentType - content type of media
      * @param {String|Buffer|Blob} media - content to post
      * @param {MediaCategory|null} category - category for the media
-     * @returns {Promise<Media>}
      */
-    post(contentType: string, media: string | Buffer | Blob, category: MediaCategory | null, filename?: string): Promise<Media>;
+    post(contentType: string, media: string | Buffer | Blob, category: MediaCategory | null, filename?: string): CancellablePromise<Media>;
     /**
      * Posts FormData to media service. Can be used only with browser engine's FormData.
      * In non-browser FormData case the method will do promise reject with
      * new TypeError("Posting FormData supported only with browser engine's FormData")
      * @param {FormData} formData - form data to post
      * @param {MediaCategory|null} category - category for the media
-     * @returns {Promise<Media>}
      */
-    postFormData(formData: FormData, category?: MediaCategory | null): Promise<Media>;
+    postFormData(formData: FormData, category?: MediaCategory | null): CancellablePromise<Media>;
     /**
      * Retrieve information about multiple media SIDs at the same time.
      * @param mediaSids Array of Media SIDs to get information from.
      */
-    mediaSetGet(mediaSids: string[]): Promise<Media[]>;
+    mediaSetGet(mediaSids: string[]): CancellablePromise<Media[]>;
+    /**
+     * Retrieve temporary URLs for a set of media SIDs.
+     * @param mediaSids array of the media SIDs to get URLs from.
+     */
+    mediaSetGetContentUrls(mediaSids: string[]): CancellablePromise<Map<string, string>>;
 }
-export { Client, Client as McsClient, Client as default, Media, Media as McsMedia, MediaCategory, MediaCategory as McsMediaCategory };
+export { CancellablePromise, Client, Client as McsClient, Client as default, Media, Media as McsMedia, MediaCategory, MediaCategory as McsMediaCategory };