@elliemae/pui-scripting-object 1.7.0 → 1.9.0

package/dist/types/objects/form.d.ts

@@ -0,0 +1,47 @@
+export declare type FormDescriptor = {
+    id: string;
+    name: string;
+};
+/**
+ * Methods to get information about the custom form
+ */
+export interface IForm {
+    /**
+     * get metadata of the form
+     *
+     * @returns form metadata
+     */
+    getDescriptor(): Promise<FormDescriptor>;
+    /**
+     * get reference to the form's input control
+     *
+     * @param id form id
+     * @returns form input control object
+     */
+    getControl(id: string): Promise<any>;
+}
+/**
+ * event handler for form load event
+ *
+ * @param id unique id of the form that is loaded
+ */
+export declare type FormLoadListener = (id: string) => void;
+/**
+ * event handler for form unload event
+ *
+ * @param id unique id of the form that is unloaded
+ */
+export declare type FormUnloadListener = (id: string) => void;
+/**
+ * events that notifies the form's lifecycle
+ */
+export declare type FormEvents = {
+    /**
+     * form is loaded and ready for user interaction
+     */
+    'form.load': FormLoadListener;
+    /**
+     * form is unloaded and no longer available for user interaction
+     */
+    'form.unload': FormUnloadListener;
+};

package/dist/types/objects/global.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The Global object allows for data to be shared between custom forms/tools/plugins within a user's session.
+ * Unlike the Session scripting object, where data is isolated to be visible/accessible only by the form/plugin that writes the variables,
+ * values written to the Global store are visible to all such customizations
+ *
+ * The implementation of this object should write the global state data to the host application's sessionStore,
+ * but should ensure that the state is isolated away from the host application's state variables. This should be done by creating
+ * naming conventions for the global keyspaces, e.g. ssf.global.<key>.
+ *
+ * In order to ensure that guest applications cannot consume significant amounts of sessionStorage, restrictions should be placed on
+ * the number and size of the stored session state. In particular, we can start with these values:
+ * Each valueObj, when stringified, cannot exceed 5 KB
+ * Total global state should be limited to 50 values
+ * This will ensure that no guest can consume more than 250 KB of sessionStorage
+ *
+ */
+export interface IGlobal {
+    /**
+     * set a value in the global store
+     *
+     * @param key unique key to identify the value
+     * @param value value to be stored
+     */
+    set(key: string, value: any): Promise<void>;
+    /**
+     * get a value from the global store
+     *
+     * @param key unique key to identify the value
+     * @returns value stored in the global store
+     */
+    get(key: string): Promise<any>;
+}
+/**
+ * event handler for global state change event
+ *
+ * @param key name of the key for which the value changed
+ */
+export declare type GlobalStateChangeListener = (key: string) => void;
+/**
+ * events fired from Global scripting object
+ */
+export declare type GlobalEvents = {
+    /**
+     * event fired when a value changes in the global store
+     */
+    'global.change': GlobalStateChangeListener;
+};

package/dist/types/objects/http.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Provides methods to make call-outs to to external systems via HTTPS.
+ * By exposing this object from the host, it ensures that the call will bear the "Origin" header of the host application.
+ * This is critical for situations where the guest's code is running in a strict-mode sandbox (where the "allowSameOrigin" flag is false).
+ */
+export interface IHttp {
+    /**
+     * get http request
+     *
+     * @param url url to make the call to
+     * @param headersOrAccessToken http headers object or access token to be used for the call
+     * @returns http response object
+     * @throws error if the http call fails with non 2xx status code
+     */
+    get(url: string, headersOrAccessToken?: HeadersInit | string): Promise<Response>;
+    /**
+     * post http request
+     *
+     * @param url url to make the call to
+     * @param headersOrAccessToken http headers object or access token to be used for the call
+     * @returns http response object
+     * @throws error if the http call fails with non 2xx status code
+     */
+    post(url: string, content: string | Record<string, string>, headersOrAccessToken?: HeadersInit | string): Promise<Response>;
+    /**
+     * patch http request
+     *
+     * @param url url to make the call to
+     * @param headersOrAccessToken http headers object or access token to be used for the call
+     * @returns http response object
+     * @throws error if the http call fails with non 2xx status code
+     */
+    patch(url: string, content: string | Record<string, string>, headersOrAccessToken?: HeadersInit | string): Promise<Response>;
+    /**
+     * put http request
+     *
+     * @param url url to make the call to
+     * @param headersOrAccessToken http headers object or access token to be used for the call
+     * @returns http response object
+     * @throws error if the http call fails with non 2xx status code
+     */
+    put(url: string, content: string | Record<string, string>, headersOrAccessToken?: HeadersInit | string): Promise<Response>;
+    /**
+     * delete http request
+     *
+     * @param url url to make the call to
+     * @param headersOrAccessToken http headers object or access token to be used for the call
+     * @returns http response object
+     * @throws error if the http call fails with non 2xx status code
+     */
+    delete(url: string, headersOrAccessToken?: HeadersInit | string): Promise<Response>;
+}

package/dist/types/{loan.d.ts → objects/loan.d.ts}

@@ -11,6 +11,9 @@ export declare type FieldOptions = {
      */
     value: string;
 };
+/**
+ * v3 loan object
+ */
 export declare type LoanObject = Record<string, any>;
 export declare enum LoanLevelActions {
     UPDATE_CORRESPONDENT_BALANCE = "updateCorrespondentBalance",
@@ -19,11 +22,11 @@ export declare enum LoanLevelActions {
     CALCULATE_EEM_MORTGAGE = "calculateEEMMortgage"
 }
 /**
- * The Loan object provides methods for interacting with an open loan in the application's editor screen(s).
+ * Methods for interacting with an open loan in the application
  */
 export interface ILoan {
     /**
-     * Get entire Loan object
+     * Get complete Loan object
      *
      * @returns v3 Loan Object
      *
@@ -46,6 +49,12 @@ export interface ILoan {
      * | all |  ✔ |  ✔ |  ✔ |  ✖️ |
      */
     commit(): Promise<void>;
+    /**
+     * get value of the given field id
+     *
+     * @param id field id
+     * @returns field value
+     */
     getField(id: string): Promise<string>;
     /**
      * get options for list of fields
@@ -135,38 +144,93 @@ export interface ILoan {
     getLockSnapshot(): Promise<Record<string, string>>;
 }
 /**
- * This event is fired prior to saving and pending changes to the loan. The guest can use this event to perform custom validation and, via the feedback mechanism, prevent the loan from being saved
+ * event handler for loan precommit event
+ *
+ * @param cause cause of precommit event
+ * @returns true if precommit is allowed, false otherwise
  */
 export declare type LoanPreCommitListener = (cause: string) => boolean;
 /**
- * This event is fired after pending changes to the loan are committed
+ * event handler for loan commited event
+ *
+ * @param cause cause of commit event
  */
 export declare type LoanCommittedListener = (cause: string) => void;
 /**
- * This event is fired for each change made by the user in the UI
+ * event handler for loan data change event
  */
 export declare type LoanChangeListener = () => void;
 /**
- * This event is fired after the loan is sync'ed within any saved state made outside of the user's workspace. This event should fire after any call to calculate() or merge(), assuming any changes are made to the loan
+ * event handler for loan sync event
  */
 export declare type LoanSyncListener = () => void;
 /**
- * Fired after the loan is opened and ready for user interaction
+ * event handler for loan open event
  */
 export declare type LoanOpenListener = () => void;
 /**
- * Fired just prior to closing the loan in the UI
+ * event handler for loan close event
+ *
+ * @returns true if loan close is allowed, false otherwise
  */
 export declare type LoanCloseListener = () => boolean;
 /**
- * This event is fired after a milestone is completed by the user and committed to the server
+ * event handler for loan milestone completed event
+ *
+ * @param name milestone name
  */
 export declare type LoanMilestoneCompletedListener = (name: string) => void;
 /**
- * This event is fired when the user attempts to complete a milestone and allows for custom validation, and cancellation, of the process
+ * event handler for loan pre milestone complete event
+ *
+ * @returns true if milestone complete is allowed, false otherwise
  */
 export declare type LoanPreMilestoneCompleteListener = (name: string) => boolean;
 /**
- * This event is fired when a borrower pair changes
+ * event handler for loan application selected event
  */
 export declare type LoanApplicationSelectedListener = () => void;
+/**
+ * events supported by Loan scripting object
+ */
+export declare type LoanEvents = {
+    /**
+     * event is fired prior to saving any pending changes to the loan.
+     * The guest can use this event to perform custom validation and,
+     * via the feedback mechanism, prevent the loan from being saved
+     */
+    'loan.precommit': LoanPreCommitListener;
+    /**
+     * event is fired after pending changes to the loan are committed
+     */
+    'loan.committed': LoanCommittedListener;
+    /**
+     * event is fired for each change made by the user in the UI
+     */
+    'loan.change': LoanChangeListener;
+    /**
+     * event is fired after the loan is sync'ed within any saved state made outside of the user's workspace.
+     */
+    'loan.sync': LoanSyncListener;
+    /**
+     * event is fired after the loan is opened and ready for user interaction
+     */
+    'loan.open': LoanOpenListener;
+    /**
+     * event is fired just prior to closing the loan in the UI
+     */
+    'loan.close': LoanCloseListener;
+    /**
+     * event is fired after a milestone is completed by the user and committed to the server
+     */
+    'loan.milestoneCompleted': LoanMilestoneCompletedListener;
+    /**
+     * event is fired when the user attempts to complete a milestone and allows for custom validation,
+     * and cancellation, of the process
+     */
+    'loan.premilestoneComplete': LoanPreMilestoneCompleteListener;
+    /**
+     * event is fired when a borrower pair changes
+     */
+    'loan.applicationselected': LoanApplicationSelectedListener;
+};

package/dist/types/objects/loanv2.d.ts

@@ -0,0 +1,140 @@
+import { ILoan, LoanObject } from './loan.js';
+/**
+ * Types of field errors
+ */
+export declare enum FieldErrorType {
+    /**
+     * access related violations
+     */
+    ACCESS = "access",
+    /**
+     * Violation of a field data entry rule.
+     * Thrown only when value gets applied to the loan and will remain until user fixes the value
+     */
+    VALUE = "value",
+    /**
+     * Error during de\serialization of the field value
+     */
+    SERIALIZATION = "serialization",
+    /**
+     * Error due to invalid data like valid RuleActionType is not implemented
+     */
+    DATA = "data",
+    /**
+     * Error due to invalid user data based on current state of the loan
+     * This does not get applied to the loan
+     */
+    CONFLICT = "conflict"
+}
+/**
+ * Field error object
+ */
+export declare type FieldErrors = {
+    /**
+     * field id
+     */
+    id: string;
+    /**
+     * field error type
+     */
+    type: FieldErrorType;
+    /**
+     * error description
+     */
+    description: string;
+};
+/**
+ * Return type of setField method
+ */
+export declare type SetFieldResponse = {
+    /**
+     * List of fields not meeting data, access or required rule criteria
+     */
+    errors: FieldErrors[];
+};
+/**
+ * Types of commit errors
+ */
+export declare enum CommitErrorStatus {
+    /**
+     * Commit failed due to fields
+     */
+    FIELDERROR = "field_error",
+    /**
+     * Commit failed due to invalid lock or read only loan status
+     */
+    LOCK_INVALID_OR_REMOVED = "lock_invalid_or_removed",
+    /**
+     * Commit failed due to invalid workspace state
+     */
+    WORKSPACE_READ_ONLY = "workspace_read_only"
+}
+/**
+ * Error representing a commit failure
+ */
+export declare type CommitError = Error & {
+    status: CommitErrorStatus;
+    /**
+     * List of violated rules that failed the commit
+     */
+    ruleViolations: {
+        /**
+         * fields not meeting various field rules
+         */
+        fieldErrors: FieldErrors[];
+    };
+};
+/**
+ * Map of field ids to their loan contract path
+ */
+export declare type FieldIDToContractPath = {
+    fieldId: string;
+    contractPath: string;
+};
+/**
+ * All operations on a loan are stateful.  This means loan changes are not committed until the loan.commit is called
+ */
+export interface ILoanV2 extends Omit<ILoan, 'commit' | 'setFields' | 'merge'> {
+    /**
+     * Commit all pending changes on the current loan
+     *
+     * @returns {Promise<CommitResponse>}
+     * @throws {Error} if operation fails due to network errors
+     * @throws {CommitError} if operation fails due to business / functional rules
+     *
+     * #### Product Compatibility:
+     * | | Encompass | Encompass Web | TPO | Consumer Connect |
+     * :-----:|:-----: |:-----: |:-----: |:-----: |
+     * | commit |  ✖️ |  ✖️ |  ✖️ |  ✖️ |
+     */
+    commit(): Promise<void>;
+    /**
+     * Get the contract path for the given field ids
+     *
+     * @param fieldIds list of field ids for which loan contract path is required
+     * @returns list of field ids and their loan contract paths
+     * @throws {Error} if operation fails due to network errors
+     */
+    getContractPath(fieldIds: string[]): Promise<FieldIDToContractPath[]>;
+    /**
+     * Syncs the loan workspace with any changes made by other users
+     * #### Product Compatibility:
+     * | | Encompass | Encompass Web | TPO | Consumer Connect |
+     * :-----:|:-----: |:-----: |:-----: |:-----: |
+     * | merge |  ✖️ |  ✖️ |  ✖️ |  ✖️ |
+     */
+    merge(): Promise<LoanObject>;
+    /**
+     * Set the values of one or more fields on the Loan.
+     *
+     * @param fields list of field ids and their values
+     * @returns list of field ids that failed to set
+     * @throws {Error} if operation fails due to network error
+     *
+     * #### Product Compatibility:
+     * | | Encompass | Encompass Web | TPO | Consumer Connect |
+     * :-----:|:-----: |:-----: |:-----: |:-----: |
+     * | setFields |  ✖️ |  ✖️ |  ✖️ |  ✖️ |
+     */
+    setFields(fields: Record<string, string>): Promise<SetFieldResponse>;
+}

package/dist/types/objects/memStorage.d.ts

@@ -0,0 +1,26 @@
+/**
+ * get or set values in host application javascript memory
+ * values stored in memory are not persisted across sessions
+ *
+ * Host application implemeting this scripting object ensures,
+ * there are no collisions with keys from other microapp guest applications
+ * that means, two microapps can use same key to store different values. Thier values will not collide.
+ *
+ */
+export interface IMemStorage {
+    /**
+     * set a value in memory for given key
+     *
+     * @param clientId unique identifier assigned to the microapp
+     * @param key unique key to store the value
+     * @param value value to be stored. value should be JSON serializable
+     */
+    set(clientId: string, key: string, value: any): Promise<void>;
+    /**
+     * get a value from memory for given key and microapp id
+     *
+     * @param key unique key to retrieve the value
+     * @returns value stored in memory
+     */
+    get(clientId: string, key: string): Promise<any>;
+}

package/dist/types/objects/module.d.ts

@@ -0,0 +1,55 @@
+export declare enum LogLevel {
+    TRACE = "TRACE",
+    DEBUG = "DEBUG",
+    INFO = "INFO",
+    AUDIT = "AUDIT",
+    WARN = "WARN",
+    ERROR = "ERROR",
+    FATAL = "FATAL"
+}
+/**
+ * Methods to bootstraps feature modules
+ */
+export interface IModule {
+    /**
+     * get module-specific JavaScript object that can be used to communicate additional capabilities to the module
+     *
+     * @returns key-value pairs of module-specific JavaScript objects
+     */
+    getCapabilities(): Promise<Record<string, string>>;
+    /**
+     * Get startup parameters for the module
+     *
+     * @returns startup parameters as key-value pairs
+     */
+    getParameters(): Promise<Record<string, string>>;
+    /**
+     * unload the module from the host application
+     */
+    unload(): Promise<void>;
+    /**
+     * log a message to host application's logs
+     *
+     * @param message message to log
+     * @param logLevel level of the log message
+     */
+    log(message: string, logLevel: LogLevel): Promise<void>;
+}
+/**
+ * event handler that handles module unload event
+ *
+ * @param id unique id of the module that is being unloaded
+ * @returns true if the module can be unloaded, false otherwise
+ */
+export declare type ModuleUnLoadingListener = (id: string) => boolean;
+/**
+ * events that notifies the module's lifecycle
+ */
+export declare type ModuleEvents = {
+    /**
+     * event fired when the module is unloading
+     *
+     * @returns true if the module can be unloaded, false otherwise
+     */
+    'module.unloading': ModuleUnLoadingListener;
+};

package/dist/types/objects/route.d.ts

@@ -0,0 +1,7 @@
+import { To } from 'history';
+/**
+ * Methods to view, modify & get notified about parent window url navigation
+ */
+export interface IRoute {
+    navigate(path: To, state?: any): Promise<void>;
+}

package/dist/types/objects/session.d.ts

@@ -0,0 +1,18 @@
+/**
+ * store and retrieves values in host application's session storage
+ */
+export interface ISession {
+    /**
+     * set a value in the session storage
+     *
+     * @param key unique key to store the value
+     * @param value value to be stored
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * get a value from the session storage
+     *
+     * @param key unique key to retrieve the value
+     */
+    get(key: string): Promise<string>;
+}