@elliemae/pui-scripting-object 1.8.0 → 1.9.0

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/{loanv2.d.ts → objects/loanv2.d.ts}

@@ -1,4 +1,7 @@
 import { ILoan, LoanObject } from './loan.js';
+/**
+ * Types of field errors
+ */
 export declare enum FieldErrorType {
     /**
      * access related violations
@@ -23,20 +26,47 @@ export declare enum FieldErrorType {
      */
     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"
 }
 /**
@@ -54,6 +84,9 @@ export declare type CommitError = Error & {
         fieldErrors: FieldErrors[];
     };
 };
+/**
+ * Map of field ids to their loan contract path
+ */
 export declare type FieldIDToContractPath = {
     fieldId: string;
     contractPath: string;

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/{route.d.ts → objects/route.d.ts}

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

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

@@ -1,5 +1,5 @@
 /**
- * Methods and events to view, modify & get notified about parent window session storage
+ * store and retrieves values in host application's session storage
  */
 export interface ISession {
     /**

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

@@ -0,0 +1,295 @@
+/**
+ * user type context
+ */
+export declare enum OriginContext {
+    /**
+     * user interface is being presented to a user in a lending enterprise
+     */
+    LENDER = "lender",
+    /**
+     * user interface is being presented to a consumer/borrower
+     */
+    CONSUMER = "consumer"
+}
+/**
+ * transaction origination context
+ */
+export declare type OriginInfo = {
+    /**
+     * Temporary session token that grants authorization for a partner
+     * integration to access transaction origination information via the REST API's /partner/v2/origins/:id endpoint
+     */
+    partnerAccessToken: string;
+    /**
+     * Unique identifier for the transaction origination information snapshot accessible
+     * via the REST API's /partner/v2/origins/:id endpoint
+     */
+    id: string;
+    /**
+     * Unique identifier for the transaction in whose context the
+     * partner integrations user-interface is being launched.
+     * This is only available in the situation where your integration
+     * is being launched in the context of an existing transaction,
+     * and can be used to decide the appropriate view to display to users
+     */
+    transactionId?: string;
+    /**
+     * The user type in whose context your integration is being launched
+     */
+    context: OriginContext;
+};
+/**
+ * details about the transaction that is created / updated
+ */
+export declare type TransactionInfo = {
+    /**
+     * unique identifier for the transaction
+     */
+    id: string | null;
+};
+/**
+ * file attachment information
+ */
+export declare type TransactionResource = {
+    /**
+     * unique identifier for the file attachment
+     */
+    id: string;
+    /**
+     * name of the file attachment
+     */
+    name: string;
+    /**
+     * mime type of the file attachment
+     */
+    mimeType: string;
+};
+/**
+ * information about the transaction to be initiated
+ */
+export declare type TransactionOptions = {
+    request: {
+        /**
+         * The type of transaction request being initiated for the subject product.
+         * This must be one of the supported values for the request type that your application
+         * is configured to support - based on which its data entitlements are scoped.
+         */
+        type: string;
+        /**
+         * The specific set of selectable options that apply to the specific
+         * type of transaction request, as modeled by your application
+         */
+        options?: Record<string, string | boolean | number>;
+        /**
+         * The collection of file attachments - referred to as resource objects in the
+         * EPC API - to be attached to the transaction request.
+         * The id, name, and mimeType attribute needed for each resource object
+         * in the collection can be created in one of two ways:
+         *  Your application utilized the transaction.createResource method to build a custom file upload experience, and the user invoked this functionality and uploaded a file from their local drive.
+         *  Your application utilized the application.performAction("getAvailableResources") method to launch the host application's file explorer, and the user invoked this functionality and attached a file[s] from the host application.
+         * Once the resource objects are collected from these methods,
+         * be sure to echo them back to the EPC platform when creating a transaction!
+         */
+        resources: Array<TransactionResource>;
+    };
+};
+/**
+ * resource name to be uploaded
+ */
+export declare type TransactionResourceFile = {
+    /**
+     * name of the file
+     */
+    name: string;
+};
+/**
+ * response object of createResource method
+ */
+export declare type TransactionResourceResponse = {
+    /**
+     * resource id
+     */
+    id: string;
+    /**
+     * urn of the target upload location
+     */
+    respository: string;
+    /**
+     * name of the resource
+     */
+    name: string;
+    /**
+     * url to stream the resource
+     */
+    location: string;
+    /**
+     * authorization header to upload the resource
+     */
+    authorizationHeader: string;
+};
+export declare type TransactionEvent = {
+    /**
+     * event name
+     */
+    text: string;
+    /**
+     * urn representing the event type
+     */
+    type: string;
+    /**
+     * comments related to event
+     */
+    comments: string;
+    /**
+     * list of file attachments related to event
+     */
+    resources: Array<TransactionResource>;
+};
+/**
+ * Provides your applications lender/borrower-facing view with the necessary handles to model your application's
+ * transactional interaction with the EPC platform.
+ * Allows access to an interactive session's origination context,
+ * create a new transaction,
+ * update an existing transaction,
+ * create events/messages for a transaction, and more.
+ */
+export interface ITransaction {
+    /**
+     * Provide the necessary information for your application's user-interface to:
+     *  Access transaction origination information and bootstrap its user interaction
+     *  Know if it was launched in the context of an existing transaction, so it can present the relevant view
+     *
+     * @returns transaction origination information
+     */
+    getOrigin(): Promise<OriginInfo>;
+    /**
+     * Refresh your application's transaction origination context - if your current one expires.
+     * This method returns a new originId and partnerAccessToken - which your application back-end can use to retrieve a refreshed transaction origin:
+     *  A fresh snapshot of the loan data your application is entitled to receive in a transaction origin
+     *  A a fresh snapshot of the user's credential set configured by their Administrator for use with your application
+     *
+     * @returns transaction origination information
+     */
+    refreshOrigin(): Promise<OriginInfo>;
+    /**
+     * Allow Lenders to use your integration to upload files from their
+     * local drive as an attachment to a new transaction.
+     * This method returns a URL and authorization token,
+     * which are to be used to stream the selected file as binary content to the EPC platform
+     *
+     * @param options details of the resource to be uploaded
+     * @returns location and authorization header to upload the resource
+     */
+    createResource(options: TransactionResourceFile): Promise<TransactionResourceResponse>;
+    /**
+     * initiate a new transaction with your integration
+     *
+     * @param options details of the transaction to be initiated
+     * @returns transaction id
+     */
+    create(options: TransactionOptions): Promise<TransactionInfo>;
+    /**
+     * Set the transaction in whose context you want to invoke methods that operate on an existing transaction.
+     * The subject transaction must be one that was created for the current loan and EPC product.
+     * The methods that currently fall into this category are:
+     * transaction.update
+     * transaction.createEvent
+     *
+     * Although integrations are free to set the transactional context they are operating in,
+     * which may be necessary when providing views that allow users to switch between
+     * and perform actions on multiple transactions, the host application implicitly
+     * alters the transactional context in certain scenarios:
+     *
+     * Implicit transaction context setting!
+     * If your integration is launched by a user in the context of an existing transaction,
+     * such as from the services page on Loan Officer Connect, the document icon
+     * on the services side-nav in Encompass Desktop or when returning to a
+     * loan application in Consumer Connect, the transactional context is implicitly set to said transaction
+     * Every time a new transaction is created during a user's interaction with your integration,
+     * the context is set to the last created transaction
+     * If the integration was initially launched in the context of an existing transaction,
+     * transaction.getOrigin will always return the original transactionId the integration was launched
+     * in the context of, no matter how many times the transaction is set in the current interaction.
+     * You can leverage this to track the initial transaction context for a user interaction
+     *
+     * The current transactional context that your integration is operating in can be queried using the transaction.get method.
+     *
+     * @param options transaction details
+     * @returns transaction that has been set
+     */
+    set(options: TransactionInfo): Promise<TransactionInfo>;
+    /**
+     * Retrieve the transaction in whose context your integration is operating in, utilized by methods that operate on an existing transaction.
+     * The methods that currently fall into this category are:
+     * transaction.update
+     * transaction.createEvent
+     * Although integrations are free to set the transactional context they are operating in
+     * (using the transaction.set method) , which may be necessary when providing views that
+     * allow users to switch between and perform actions on multiple transactions,
+     * the host application implicitly alters the transactional context in certain scenarios:
+     *
+     * Implicit transaction context setting!
+     * If your integration is launched by a user in the context of an existing transaction,
+     * such as from the services page on Loan Officer Connect, the document icon on the services
+     * side-nav in Encompass Desktop or on a loan application in Consumer Connect is set to said transaction.
+     * Every time a new transaction is created during a user's interaction with your integration,
+     * the context is set to the last created transaction.
+     * If the integration was initially launched in the context of an existing transaction,
+     * the transaction.getOrigin method will always return the original transactionId the integration was launched
+     * in the context of, no matter how many times the transaction is set in the current interaction.
+     * You can leverage this to track the initial transaction context for a user interaction
+     *
+     * The current transactional context your integration operates in can be queried using the transaction.get method
+     *
+     * @returns transaction id details
+     */
+    get(): Promise<TransactionInfo>;
+    /**
+     * Allow Lenders to update an existing transaction by attaching new resources or updating
+     * the request options associated with the transaction.
+     * A transaction update will trigger an updated webhook event on the urn:elli:epc:transaction REST resource,
+     * indicating an updated transaction request is ready for your application to retrieve.
+     * The updated transaction request will contain:
+     * An updated options object, if set in this method
+     * An updated resources array, with the resources set in this method appended to the previously attached set
+     * By default, a fresh snapshot of the loan data your application is entitled to receive in the transaction request
+     * By default, a fresh snapshot of the user's credential set configured by their Administrator for use with your application
+     *
+     * Request type immutability
+     * The type for a lender initiated transaction request can not be updated once created.
+     * If you need to support the ability for a lender to change the request type for a transaction they have initiated,
+     * the initial transaction must be canceled via a transaction response status update (using the REST API),
+     * and the lender must initiate a new transaction request with the updated type
+     *
+     * @param options transaction details
+     * @returns transaction id
+     */
+    update(options: TransactionOptions): Promise<TransactionInfo>;
+    /**
+     * Allow Lenders to initiate an event/message for the subject transaction with your integration
+     *
+     * @param options details of the event/message to be initiated
+     * @returns transaction event id
+     */
+    createEvent(options: TransactionEvent): Promise<TransactionInfo>;
+    /**
+     * Navigate your users back to where they left off in the host Encompass application,
+     * after they are done interacting with your application's user-interface
+     */
+    close(): Promise<void>;
+    /**
+     * Navigate your users back to where they left off in the host Encompass application,
+     * after they have canceled an interaction with your application's user-interface without having
+     * initiated a transaction request (or any other related task) that they were working on.
+     * This signals a cancelation outcome to the host Encompass application -
+     * how this is handled by the host upon user navigation can vary across applications
+     */
+    cancel(): Promise<void>;
+    /**
+     * Navigate your users back to where they left off in the host Encompass application,
+     * after their has been an error (application error or workflow error) on your integrations user-interface.
+     * This signals an error outcome to the host Encompass application -
+     * how this is handled by the host upon user navigation can vary across applications
+     */
+    error(): Promise<void>;
+}