@blackbaud/sky-addin-client 1.1.5 → 1.2.1

package/src/addin/addin-client.d.ts

@@ -1,277 +1,277 @@
-import { AddinClientArgs } from './client-interfaces/addin-client-args';
-import { AddinClientCloseModalArgs } from './client-interfaces/addin-client-close-modal-args';
-import { AddinClientEventArgs } from './client-interfaces/addin-client-event-args';
-import { AddinClientNavigateArgs } from './client-interfaces/addin-client-navigate-args';
-import { AddinClientOpenHelpArgs } from './client-interfaces/addin-client-open-help-args';
-import { AddinClientShowConfirmArgs } from './client-interfaces/addin-client-show-confirm-args';
-import { AddinClientShowErrorArgs } from './client-interfaces/addin-client-show-error-args';
-import { AddinClientShowFlyoutArgs } from './client-interfaces/addin-client-show-flyout-args';
-import { AddinClientShowFlyoutResult } from './client-interfaces/addin-client-show-flyout-result';
-import { AddinClientShowModalArgs } from './client-interfaces/addin-client-show-modal-args';
-import { AddinClientShowModalResult } from './client-interfaces/addin-client-show-modal-result';
-import { AddinClientShowToastArgs } from './client-interfaces/addin-client-show-toast-args';
-/**
- * Callback function to execute when an add-in event occurs.
- * @param context Abitrary context object passed to the event callback.
- * @param done Optional callback function to be executed when the client is done
- * processing the event.
- *
- * The following event types require the 'done' callback to be provided:
- * - 'form-save'
- * - 'form-cancel'
- */
-export declare type AddinEventCallback = (context: any, done?: () => void) => void;
-/**
- * Client for interacting with the parent page hosting the add-in.
- */
-export declare class AddinClient {
-    private args;
-    /**
-     * Tracks pending request to reeceive an auth-token from the host.
-     */
-    private authTokenRequests;
-    /**
-     * Counter to provide unique ids for each auth token request.
-     */
-    private lastAuthTokenRequestId;
-    /**
-     * Tracks modal add-ins that have been launched from this add-in.
-     */
-    private modalRequests;
-    /**
-     * Counter to provide unique ids for each modal request.
-     */
-    private lastModalRequestId;
-    /**
-     * Tracks the current flyout add-in that has been launched from this add-in.
-     */
-    private flyoutRequest;
-    /**
-     * Tracks the current confirm dialog that has been launched from this add-in.
-     */
-    private confirmRequest;
-    /**
-     * The origin of the host page.
-     */
-    private trustedOrigin;
-    /**
-     * A message handler listening to post-message events from the host page.
-     */
-    private windowMessageHandler;
-    /**
-     * setInterval id for tracking height changes of the iframe.
-     */
-    private heightChangeIntervalId;
-    /**
-     * Tracks the last height posted to the host page.
-     */
-    private lastPostedIframeHeight;
-    /**
-     * Stores the registered add-in events.
-     * Key - the event type.
-     * Value - The callback function to be executed when the event type occurs.
-     */
-    private registeredAddinEvents;
-    /**
-     * Stores the add-in events that have been sent to the host page.
-     * Key - the event request ID.
-     * Value - The Promise resolve function to be executed when the event is received by the host.
-     */
-    private sentEvents;
-    /**
-     * Stores the pending add-in events that are queued to be sent to the host page after 200
-     * milliseconds have expired.
-     * Key - the event type.
-     * Value - The Promise reject function to be executed if the event fails to be sent to the host page.
-     */
-    private pendingSentEvents;
-    /**
-     * The event request ID counter.
-     * The ID is incremented and assigned to each event that is sent.
-     */
-    private eventRequestId;
-    /**
-     * An array of event types that are supported by the host page.
-     * The add-in client will throw an error if an event is attempted but not one the supported types.
-     */
-    private supportedEventTypes;
-    /**
-     * @returns {string}  Returns the current query string path for the window, prefixed with ?.
-     */
-    private static getQueryString;
-    constructor(args: AddinClientArgs);
-    /**
-     * Cleans up the AddinClient, releasing all resources.
-     */
-    destroy(): void;
-    /**
-     * Requests the host page to navigate.
-     * @param args Arguments describing the navigation request.
-     */
-    navigate(args: AddinClientNavigateArgs): void;
-    /**
-     * Requests an authentication token for the current user.
-     * @deprecated Use getUserIdentityToken() instead.
-     * @returns {Promise<any>} Returns a promise which will resolve with the token value.
-     */
-    getAuthToken(): Promise<string>;
-    /**
-     * Requests a user identity token for the current user.
-     * @returns {Promise<any>} Returns a promise which will resolve with the token value.
-     */
-    getUserIdentityToken(): Promise<string>;
-    /**
-     * Requests the host page to launch a modal add-in.
-     * @param args Arguments for launching the modal.
-     * @returns {Promise<any>} Returns a promise that will be resolved when the modal add-in is closed.
-     * Promise will resolve with context data passed by from the modal add-in's closeModal call.
-     */
-    showModal(args: AddinClientShowModalArgs): AddinClientShowModalResult;
-    /**
-     * Informs the host to close this modal add-in.
-     * Should only be used from within the modal add-in and not the parent add-in.
-     * @param args Arguments to provide a context object back to the parent add-in.
-     */
-    closeModal(args: AddinClientCloseModalArgs): void;
-    /**
-     * Informs the host to open the help tab with the specified help key.
-     * @param args Arguments for launching the help tab.
-     */
-    openHelp(args: AddinClientOpenHelpArgs): void;
-    /**
-     * Informs the host to show a toast message.
-     * @param args Arguments for showing a toast.
-     */
-    showToast(args: AddinClientShowToastArgs): void;
-    /**
-     * Requests the host page to launch a flyout add-in.
-     * @param args Arguments for launching the flyout.
-     * @returns {Promise<any>} Returns a promise that will be resolved when the flyout add-in is closed.
-     */
-    showFlyout(args: AddinClientShowFlyoutArgs): AddinClientShowFlyoutResult;
-    /**
-     * Requests the host page to close the flyout add-in.
-     */
-    closeFlyout(): void;
-    /**
-     * Requests the host page to show a confirm dialog.
-     * @param args Arguments for showing a confirm dialog.
-     * @returns {Promise<string>} Returns a promise that will resolve with the
-     * confirm action when the dialog is closed.
-     */
-    showConfirm(args: AddinClientShowConfirmArgs): Promise<string>;
-    /**
-     * Informs the host to show an error dialog.
-     * @param args Arguments for showing an error dialog.
-     */
-    showError(args: AddinClientShowErrorArgs): void;
-    /**
-     * Requests the host page to show the page blocking wait indicator.
-     */
-    showWait(): void;
-    /**
-     * Requests the host page to hide the page blocking wait indicator.
-     */
-    hideWait(): void;
-    /**
-     * Registers a callback to be executed when the specified event type occurs.
-     * @param eventType The event type to process.
-     * @param callback The callback to execute when the event occurs.
-     */
-    addEventHandler(eventType: string, callback: AddinEventCallback): void;
-    /**
-     * Sends an event to be handled by the host page.
-     * @returns {Promise<void>} Returns a Promise which will resolve when the add-in host page receives the message, or
-     * rejects if a subsequent event occurs, for the same event type, within 200 milliseconds.
-     * The Promise also rejects if an event type is not one of the supported types from the host page.
-     * @see AddinClientInitArgs#supportedEventTypes
-     */
-    sendEvent(args: AddinClientEventArgs): Promise<void>;
-    /**
-     * Post a message to the host page informing it that the add-in is
-     * now started and listening for messages from the host.
-     */
-    private raiseAddinReadyMessage;
-    /**
-     * Handles the modal-closed message from the host.
-     * This is emitted to add-ins which have previously launched a modal, which is now
-     * closing.
-     * @param message The message data, which includes a context object from the closing modal, which should be passed
-     * to the calling modal in the showModal promise.
-     */
-    private handleModalClosedMessage;
-    /**
-     * Handles host message responses to a get-auth-token request.
-     * @param data The message.
-     */
-    private handleAuthTokenMessage;
-    /**
-     * Handles message events received from the add-in host page.
-     * @param event The event posted from the host.
-     */
-    private handleMessage;
-    /**
-     * Validates and registers a value as the origin of the parent page hosting the add-in.
-     * If the provided origin matches against our trusted whitelist, then it will be saved.
-     * Post messages will implicitly go to this origin and received messages will be filtered
-     * to just messages from this origin.
-     * @param hostOrigin
-     */
-    private setKnownAllowedHostOrigin;
-    /**
-     * Checks if the height of the iFrame has changed since it was last
-     * posted to the host page (or if it hasn't been posted yet) and initiates
-     * a new post if so.
-     */
-    private checkForHeightChangesOfAddinContent;
-    /**
-     * Starts a timeout interval to watch for height changes
-     * of the iframe content.
-     */
-    private trackHeightChangesOfAddinContent;
-    /**
-     * Posts a message to the parent window.
-     * @param message The message content to post.
-     * @param targetOrigin Optional. If provided, then the message will be posted to this origin.
-     *                     If not, then it will post to the pre-determined host page origin.
-     */
-    private postMessageToHostPage;
-    /**
-     * Processes an add-in event that occurs from the host and responds
-     * back to the host with an 'event-received' message.
-     * @param message The message to process by looking up executing the registered callback
-     * that matches the event type.
-     */
-    private processHostEvent;
-    /**
-     * Checks whether an event type is blocking and requires a response from the client
-     * before responding to the host.
-     * @param type The event type.
-     */
-    private isBlockingEventType;
-    /**
-     * Posts a message to the host page to indicate that a certain event has been received.
-     * @param eventRequestId The ID of the event request that was received.
-     */
-    private postEventReceivedMessage;
-    /**
-     * Attemps to resolve the Promise for a client event that has been received by the host page.
-     * @param message Message data that includes the ID of the event that was received.
-     */
-    private resolveClientEvent;
-    /**
-     * Checks whether a MessageEvent is from the execetd host origin.
-     * @param event
-     */
-    private isFromValidOrigin;
-    /**
-     * Log that a message was received with an invalid origin.
-     */
-    private warnInvalidOrigin;
-    /**
-     * Reads a query string value from the current window location.
-     * @param variable  Name of the query string parameter to ready.
-     * @returns         The value of the query string parameter.
-     */
-    private getQueryVariable;
-}
+import { AddinClientArgs } from './client-interfaces/addin-client-args';
+import { AddinClientCloseModalArgs } from './client-interfaces/addin-client-close-modal-args';
+import { AddinClientEventArgs } from './client-interfaces/addin-client-event-args';
+import { AddinClientNavigateArgs } from './client-interfaces/addin-client-navigate-args';
+import { AddinClientOpenHelpArgs } from './client-interfaces/addin-client-open-help-args';
+import { AddinClientShowConfirmArgs } from './client-interfaces/addin-client-show-confirm-args';
+import { AddinClientShowErrorArgs } from './client-interfaces/addin-client-show-error-args';
+import { AddinClientShowFlyoutArgs } from './client-interfaces/addin-client-show-flyout-args';
+import { AddinClientShowFlyoutResult } from './client-interfaces/addin-client-show-flyout-result';
+import { AddinClientShowModalArgs } from './client-interfaces/addin-client-show-modal-args';
+import { AddinClientShowModalResult } from './client-interfaces/addin-client-show-modal-result';
+import { AddinClientShowToastArgs } from './client-interfaces/addin-client-show-toast-args';
+/**
+ * Callback function to execute when an add-in event occurs.
+ * @param context Abitrary context object passed to the event callback.
+ * @param done Optional callback function to be executed when the client is done
+ * processing the event.
+ *
+ * The following event types require the 'done' callback to be provided:
+ * - 'form-save'
+ * - 'form-cancel'
+ */
+export type AddinEventCallback = (context: any, done?: () => void) => void;
+/**
+ * Client for interacting with the parent page hosting the add-in.
+ */
+export declare class AddinClient {
+    private args;
+    /**
+     * Tracks pending request to reeceive an auth-token from the host.
+     */
+    private authTokenRequests;
+    /**
+     * Counter to provide unique ids for each auth token request.
+     */
+    private lastAuthTokenRequestId;
+    /**
+     * Tracks modal add-ins that have been launched from this add-in.
+     */
+    private modalRequests;
+    /**
+     * Counter to provide unique ids for each modal request.
+     */
+    private lastModalRequestId;
+    /**
+     * Tracks the current flyout add-in that has been launched from this add-in.
+     */
+    private flyoutRequest;
+    /**
+     * Tracks the current confirm dialog that has been launched from this add-in.
+     */
+    private confirmRequest;
+    /**
+     * The origin of the host page.
+     */
+    private trustedOrigin;
+    /**
+     * A message handler listening to post-message events from the host page.
+     */
+    private windowMessageHandler;
+    /**
+     * setInterval id for tracking height changes of the iframe.
+     */
+    private heightChangeIntervalId;
+    /**
+     * Tracks the last height posted to the host page.
+     */
+    private lastPostedIframeHeight;
+    /**
+     * Stores the registered add-in events.
+     * Key - the event type.
+     * Value - The callback function to be executed when the event type occurs.
+     */
+    private registeredAddinEvents;
+    /**
+     * Stores the add-in events that have been sent to the host page.
+     * Key - the event request ID.
+     * Value - The Promise resolve function to be executed when the event is received by the host.
+     */
+    private sentEvents;
+    /**
+     * Stores the pending add-in events that are queued to be sent to the host page after 200
+     * milliseconds have expired.
+     * Key - the event type.
+     * Value - The Promise reject function to be executed if the event fails to be sent to the host page.
+     */
+    private pendingSentEvents;
+    /**
+     * The event request ID counter.
+     * The ID is incremented and assigned to each event that is sent.
+     */
+    private eventRequestId;
+    /**
+     * An array of event types that are supported by the host page.
+     * The add-in client will throw an error if an event is attempted but not one the supported types.
+     */
+    private supportedEventTypes;
+    /**
+     * @returns {string}  Returns the current query string path for the window, prefixed with ?.
+     */
+    private static getQueryString;
+    constructor(args: AddinClientArgs);
+    /**
+     * Cleans up the AddinClient, releasing all resources.
+     */
+    destroy(): void;
+    /**
+     * Requests the host page to navigate.
+     * @param args Arguments describing the navigation request.
+     */
+    navigate(args: AddinClientNavigateArgs): void;
+    /**
+     * Requests an authentication token for the current user.
+     * @deprecated Use getUserIdentityToken() instead.
+     * @returns {Promise<any>} Returns a promise which will resolve with the token value.
+     */
+    getAuthToken(): Promise<string>;
+    /**
+     * Requests a user identity token for the current user.
+     * @returns {Promise<any>} Returns a promise which will resolve with the token value.
+     */
+    getUserIdentityToken(): Promise<string>;
+    /**
+     * Requests the host page to launch a modal add-in.
+     * @param args Arguments for launching the modal.
+     * @returns {Promise<any>} Returns a promise that will be resolved when the modal add-in is closed.
+     * Promise will resolve with context data passed by from the modal add-in's closeModal call.
+     */
+    showModal(args: AddinClientShowModalArgs): AddinClientShowModalResult;
+    /**
+     * Informs the host to close this modal add-in.
+     * Should only be used from within the modal add-in and not the parent add-in.
+     * @param args Arguments to provide a context object back to the parent add-in.
+     */
+    closeModal(args: AddinClientCloseModalArgs): void;
+    /**
+     * Informs the host to open the help tab with the specified help key.
+     * @param args Arguments for launching the help tab.
+     */
+    openHelp(args: AddinClientOpenHelpArgs): void;
+    /**
+     * Informs the host to show a toast message.
+     * @param args Arguments for showing a toast.
+     */
+    showToast(args: AddinClientShowToastArgs): void;
+    /**
+     * Requests the host page to launch a flyout add-in.
+     * @param args Arguments for launching the flyout.
+     * @returns {Promise<any>} Returns a promise that will be resolved when the flyout add-in is closed.
+     */
+    showFlyout(args: AddinClientShowFlyoutArgs): AddinClientShowFlyoutResult;
+    /**
+     * Requests the host page to close the flyout add-in.
+     */
+    closeFlyout(): void;
+    /**
+     * Requests the host page to show a confirm dialog.
+     * @param args Arguments for showing a confirm dialog.
+     * @returns {Promise<string>} Returns a promise that will resolve with the
+     * confirm action when the dialog is closed.
+     */
+    showConfirm(args: AddinClientShowConfirmArgs): Promise<string>;
+    /**
+     * Informs the host to show an error dialog.
+     * @param args Arguments for showing an error dialog.
+     */
+    showError(args: AddinClientShowErrorArgs): void;
+    /**
+     * Requests the host page to show the page blocking wait indicator.
+     */
+    showWait(): void;
+    /**
+     * Requests the host page to hide the page blocking wait indicator.
+     */
+    hideWait(): void;
+    /**
+     * Registers a callback to be executed when the specified event type occurs.
+     * @param eventType The event type to process.
+     * @param callback The callback to execute when the event occurs.
+     */
+    addEventHandler(eventType: string, callback: AddinEventCallback): void;
+    /**
+     * Sends an event to be handled by the host page.
+     * @returns {Promise<void>} Returns a Promise which will resolve when the add-in host page receives the message, or
+     * rejects if a subsequent event occurs, for the same event type, within 200 milliseconds.
+     * The Promise also rejects if an event type is not one of the supported types from the host page.
+     * @see AddinClientInitArgs#supportedEventTypes
+     */
+    sendEvent(args: AddinClientEventArgs): Promise<void>;
+    /**
+     * Post a message to the host page informing it that the add-in is
+     * now started and listening for messages from the host.
+     */
+    private raiseAddinReadyMessage;
+    /**
+     * Handles the modal-closed message from the host.
+     * This is emitted to add-ins which have previously launched a modal, which is now
+     * closing.
+     * @param message The message data, which includes a context object from the closing modal, which should be passed
+     * to the calling modal in the showModal promise.
+     */
+    private handleModalClosedMessage;
+    /**
+     * Handles host message responses to a get-auth-token request.
+     * @param data The message.
+     */
+    private handleAuthTokenMessage;
+    /**
+     * Handles message events received from the add-in host page.
+     * @param event The event posted from the host.
+     */
+    private handleMessage;
+    /**
+     * Validates and registers a value as the origin of the parent page hosting the add-in.
+     * If the provided origin matches against our trusted whitelist, then it will be saved.
+     * Post messages will implicitly go to this origin and received messages will be filtered
+     * to just messages from this origin.
+     * @param hostOrigin
+     */
+    private setKnownAllowedHostOrigin;
+    /**
+     * Checks if the height of the iFrame has changed since it was last
+     * posted to the host page (or if it hasn't been posted yet) and initiates
+     * a new post if so.
+     */
+    private checkForHeightChangesOfAddinContent;
+    /**
+     * Starts a timeout interval to watch for height changes
+     * of the iframe content.
+     */
+    private trackHeightChangesOfAddinContent;
+    /**
+     * Posts a message to the parent window.
+     * @param message The message content to post.
+     * @param targetOrigin Optional. If provided, then the message will be posted to this origin.
+     *                     If not, then it will post to the pre-determined host page origin.
+     */
+    private postMessageToHostPage;
+    /**
+     * Processes an add-in event that occurs from the host and responds
+     * back to the host with an 'event-received' message.
+     * @param message The message to process by looking up executing the registered callback
+     * that matches the event type.
+     */
+    private processHostEvent;
+    /**
+     * Checks whether an event type is blocking and requires a response from the client
+     * before responding to the host.
+     * @param type The event type.
+     */
+    private isBlockingEventType;
+    /**
+     * Posts a message to the host page to indicate that a certain event has been received.
+     * @param eventRequestId The ID of the event request that was received.
+     */
+    private postEventReceivedMessage;
+    /**
+     * Attemps to resolve the Promise for a client event that has been received by the host page.
+     * @param message Message data that includes the ID of the event that was received.
+     */
+    private resolveClientEvent;
+    /**
+     * Checks whether a MessageEvent is from the execetd host origin.
+     * @param event
+     */
+    private isFromValidOrigin;
+    /**
+     * Log that a message was received with an invalid origin.
+     */
+    private warnInvalidOrigin;
+    /**
+     * Reads a query string value from the current window location.
+     * @param variable  Name of the query string parameter to ready.
+     * @returns         The value of the query string parameter.
+     */
+    private getQueryVariable;
+}