@elliemae/pui-scripting-object 1.46.4 → 1.48.0

package/dist/types/lib/objects/auth.d.ts

@@ -7,8 +7,19 @@ export type UnAuthorizedError = Error;
  * Personas information
  */
 export type Personas = {
+    /**
+     * unique identifier for the persona
+     */
     entityId: string;
+    /**
+     * type of the entity
+     * @example 'Persona'
+     */
     entityType: string;
+    /**
+     * name of the entity
+     * @example 'Loan Officer'
+     */
     entityName: string;
 };
 /**
@@ -129,10 +140,6 @@ export type TokenInfo = {
      * @example https://int.api.ellielabs.com
      */
     host_name: string;
-    /**
-     * unique id of the oauth client
-     */
-    client_id: string;
 };
 /**
  * Methods to get information about the user and access token
@@ -148,6 +155,10 @@ export interface IAuth extends IScriptingObject {
      * @param redirectUri redirect url of the plugin / microapp
      * @param scope scope of the plugin / microapp
      * @returns auth code
+     * @example
+     * ```javascript
+     * const authCode = await auth.createAuthCode('abc', 'https://clientx.com', 'lp');
+     * ```
      */
     createAuthCode(clientId: string, redirectUri: string, scope: string): Promise<string>;
     /**
@@ -156,6 +167,10 @@ export interface IAuth extends IScriptingObject {
      * should able to find out the caller of this api and request necessary child token
      * @returns access token with the api base url
      * @throws {UnAuthorizedError} if the customization, requesting the token, doesn not have active subscription to developer connect product
+     * @example
+     * ```javascript
+     * const token = await auth.getAccessToken();
+     * ```
      */
     getAccessToken(): Promise<TokenInfo>;
     /**

package/dist/types/lib/objects/loan.d.ts

@@ -35,7 +35,7 @@ export type CurrentApplicationOptions = {
     /**
      * unique borrower pair id
      */
-    borrowerPairId: string;
+    id: string;
 };
 /**
  * loan record actions
@@ -107,6 +107,77 @@ export declare enum LoanLevelActions {
     CALCULATE_EEM_MORTGAGE = "calculateEEMMortgage",
     COPY_BORROWER_TO_TAX_REQUEST = "copyBorrowerToTaxRequest"
 }
+/**
+ * Loan collection names
+ */
+export declare enum LoanCollection {
+    AffiliatedBusinessArrangements = "AB0000",
+    AlternateNameBorrower = "URLABAKA0000",
+    AlternateNameCoBorrower = "URLACAKA0000",
+    BorrowerCreditReports = "BCRED0000",
+    BorrowerEmployer = "BE0000",
+    BorrowerResidence = "BR0000",
+    CoBorrowerCreditReports = "CCRED0000",
+    CoBorrowerEmployer = "CE0000",
+    CoBorrowerResidence = "CR0000",
+    DepositoryInformation = "DD0000",
+    Disclosures = "DISC0000",
+    EarlyCheck = "EC0000",
+    Escrow = "HUD0000",
+    GiftOrGrant = "URLARGG0000",
+    GoodFaithChangeOfCircumstance = "XCOC0000",
+    GSERepAndWarrantTracker = "TQLGSE0000",
+    HomeCounselingProvider = "HC0000",
+    IRS4506Record = "AR0000",
+    IRS4506TRecord = "IR0000",
+    ItemizedEscrowPayment = "AEA0000",
+    LiabilityInformation = "FL0000",
+    LoanPrograms = "LP0000",
+    MortgageProperty = "FM0000",
+    NonBorrowingOwnerFileContact = "NBOC0000",
+    NYFees = "NYFEES0000",
+    OtherAssets = "URLAROA0000",
+    OtherBorrowerEmployer = "FBE0000",
+    OtherCoBorrowerEmployer = "FCE0000",
+    OtherIncome = "URLAROIS0000",
+    OtherLiabilitiesOrDepository = "URLAROL0000",
+    PropertyValuations = "PVAL0000",
+    REGZDrawRepayPeriodDraw = "HTD0000",
+    REGZDrawRepayPeriodRepay = "HTR0000",
+    Riders = "RIDER0000",
+    Scenarios = "SCEN0000",
+    SettlementServiceProvider = "SP0000",
+    SpecialFeatureCodes = "SFC0000",
+    TQLBorrower4506TOrders = "TQL4506T0000",
+    TQLComplianceOrdersLastAlert = "TQLCOMPLIANCEALERT0000",
+    TQLDocumentDeliveredToInvestor = "TQLDOCDATE0000",
+    TQLFraudOrders = "TQLFRAUDALERT0000",
+    TrustAccountTransactionDescription = "TA0000",
+    UCDAdjustmentType = "UNFL0000",
+    Valuation = "VAL0000",
+    VerificationOfAdditionalLoans = "URLARAL0000",
+    VestingParty = "TR0000",
+    CorrespondentOtherInsurances = "CORROI0000"
+}
+/**
+ * Loan collection object
+ */
+export type LoanCollectionObject = {
+    /**
+     * unique id of the collection. e.g: LoanCollection
+     */
+    id: string;
+    /**
+     * object type
+     */
+    objectType: string;
+    /**
+     * Removes a collection record from the LoanCollection reference
+     * @param index Zero based collection index to delete, i.e. use 0 to delete first record from collection. This argument is required. You can also use negative values to delete in reverse order e.g to delete last record use -1, second from last use -2 & so on.
+     * @param applicationIndex  Zero based application index (Borrower Pair Index), use 0 to remove data that belongs to 1st borrower pair. This argument is optional. If this argument is missing, removeAt will perform delete on current selected borrower pair's index
+     */
+    removeAt: (index: number, applicationIndex: number) => void;
+};
 /**
  * Loan commit event parameters
  */
@@ -145,6 +216,27 @@ export type LoanCommittedListener = (params: {
     eventParams: CommitInfo;
     eventOptions?: Record<string, unknown>;
 }) => void;
+/**
+ * Loan change event parameters
+ */
+export type LoanChangeEventInfo = {
+    /**
+     * field id
+     */
+    fieldId: string;
+    /**
+     * operation performed on the field
+     */
+    op: string;
+    /**
+     * old field value
+     */
+    oldVal: string;
+    /**
+     * new field value
+     */
+    newVal: string;
+};
 /**
  * Event handler for loan data change event
  * @param params event parameters
@@ -156,7 +248,7 @@ export type LoanCommittedListener = (params: {
 export type LoanChangeListener = (params: {
     obj: ILoan;
     eventName: string;
-    eventParams: Record<string, never>;
+    eventParams: LoanChangeEventInfo;
     eventOptions?: Record<string, unknown>;
 }) => void;
 /**
@@ -239,6 +331,32 @@ export type MilestoneInfo = {
      */
     name: string;
 };
+/**
+ * Selected application related information
+ */
+export type ApplicationInfo = {
+    /**
+     * borrower pair index
+     */
+    index: number;
+    /**
+     * borrower pair unique id
+     */
+    id: string;
+    /**
+     * borrower pair legacy id
+     */
+    legacyId: string;
+};
+/**
+ * Return type for action execution
+ */
+export type ActionResponse = {
+    /**
+     * action status. e.g. success
+     */
+    status: string;
+};
 /**
  * event handler for loan milestone completed event
  * @param params event parameters
@@ -398,71 +516,239 @@ export interface ILoan extends IScriptingObject {
      * event fired when the loan application is selected
      *
      * Use {@link LoanApplicationSelectedListener} to handle this event
+     * @example
+     * with v2 SSF
+     * ```ts
+     * guest.subscribe({
+     *  eventId: 'loan.applicationselected',
+     *  callback: ({ eventParams }) => {
+     *    console.log('Application Selected', eventParams);
+     *  });
+     * });
+     * ```
+     * @example
+     * with v1 SSF
+     * ```ts
+     * elli.script.subscribe('loan', 'applicationselected', ({ eventParams }) => {
+     *  console.log('Application Selected', eventParams);
+     * });
      */
     readonly ApplicationSelected: IEvent;
     /**
-     * event fired when the loan is closed
+     * event fired prior to closing the loan
      *
      * Use {@link LoanCloseListener} to handle this event
+     * @example
+     * with v2 SSF
+     * ```ts
+     * guest.subscribe({
+     *  eventId: 'loan.close',
+     *  callback: ({ eventParams }) => {
+     *    console.log('Loan closing', eventParams);
+     *    return true;
+     *  });
+     * });
+     * ```
+     * @example
+     * with v1 SSF
+     * ```ts
+     * elli.script.subscribe('loan', 'close', ({ eventParams }) => {
+     *  console.log('Loan closing', eventParams);
+     *  return true;
+     * });
      */
     readonly Close: IEvent;
     /**
-     * event fired when the loan is changed
+     * event fired for each loan change made by the user
      *
      * Use {@link LoanChangeListener} to handle this event
+     * @example
+     * with v2 SSF
+     * ```ts
+     * guest.subscribe({
+     *  eventId: 'loan.change',
+     *  callback: ({ eventParams }) => {
+     *    console.log('Loan changed', eventParams);
+     *  });
+     * });
+     * ```
+     * @example
+     * with v1 SSF
+     * ```ts
+     * elli.script.subscribe('loan', 'change', ({ eventParams }) => {
+     *  console.log('Loan changed', eventParams);
+     * });
      */
     readonly Change: IEvent;
     /**
-     * event fired when the loan is committed
+     * event fired when the loan changes are committed
      *
      * Use {@link LoanCommittedListener} to handle this event
+     * @example
+     * with v2 SSF
+     * ```ts
+     * guest.subscribe({
+     *  eventId: 'loan.committed',
+     *  callback: ({ eventParams }) => {
+     *    console.log('Loan committed', eventParams);
+     *  });
+     * });
+     * ```
+     * @example
+     * with v1 SSF
+     * ```ts
+     * elli.script.subscribe('loan', 'committed', ({ eventParams }) => {
+     *  console.log('Loan committed', eventParams);
+     * });
      */
     readonly Committed: IEvent;
     /**
      * event fired when the loan edit mode is changed
      *
      * Use {@link LoanEditModeChangeListener} to handle this event
+     * @example
+     * with v2 SSF
+     * ```ts
+     * guest.subscribe({
+     *  eventId: 'loan.editModeChange',
+     *  callback: ({ eventParams }) => {
+     *    console.log('Loan edit mode changed', eventParams);
+     *  });
+     * });
+     * ```
+     * @example
+     * with v1 SSF
+     * ```ts
+     * elli.script.subscribe('loan', 'editModeChange', ({ eventParams }) => {
+     *  console.log('Loan edit mode changed', eventParams);
+     * });
      */
     readonly EditModeChange: IEvent;
     /**
      * event fired when the loan milestone is completed
      *
      * Use {@link LoanMilestoneCompletedListener} to handle this event
+     * @example
+     * with v2 SSF
+     * ```ts
+     * guest.subscribe({
+     *  eventId: 'loan.milestoneCompleted',
+     *  callback: ({ eventParams }) => {
+     *    console.log('Loan milestone completed', eventParams);
+     *  });
+     * });
+     * ```
+     * @example
+     * with v1 SSF
+     * ```ts
+     * elli.script.subscribe('loan', 'milestoneCompleted', ({ eventParams }) => {
+     *  console.log('Loan milestone completed', eventParams);
+     * });
      */
     readonly MilestoneCompleted: IEvent;
     /**
      * event fired when the loan is opened
      *
      * Use {@link LoanOpenListener} to handle this event
+     * @example
+     * with v2 SSF
+     * ```ts
+     * guest.subscribe({
+     *  eventId: 'loan.open',
+     *  callback: ({ eventParams }) => {
+     *    console.log('Loan open', eventParams);
+     *  });
+     * });
+     * ```
+     * @example
+     * with v1 SSF
+     * ```ts
+     * elli.script.subscribe('loan', 'open', ({ eventParams }) => {
+     *  console.log('Loan open', eventParams);
+     * });
      */
     readonly Open: IEvent;
     /**
-     * event fired when the loan is ready to commit
+     * event is fired prior to saving and pending changes to the loan
+     *
+     * One can use this event to perform custom validation and, via the feedback mechanism, prevent the loan from being saved.
      *
      * Use {@link LoanPreCommitListener} handles this event
+     * @example
+     * with v2 SSF
+     * ```ts
+     * guest.subscribe({
+     *  eventId: 'loan.precommit',
+     *  callback: ({ eventParams }) => {
+     *    console.log('Loan precommit', eventParams);
+     *    return true;
+     *  });
+     * });
+     * ```
+     * @example
+     * with v1 SSF
+     * ```ts
+     * elli.script.subscribe('loan', 'precommit', ({ eventParams }) => {
+     *  console.log('Loan precommit', eventParams);
+     *  return true;
+     * });
      */
     readonly PreCommit: IEvent;
     /**
-     * event fired when the loan is ready to complete milestone
+     * event is fired when the user attempts to complete a milestone and allows for custom validation, and cancellation, of the process.
      *
      * Use {@link LoanPreMilestoneCompleteListener} to handle this event
+     * @example
+     * with v2 SSF
+     * ```ts
+     * guest.subscribe({
+     *  eventId: 'loan.premilestoneComplete',
+     *  callback: ({ eventParams }) => {
+     *    console.log('Loan pre-milestone complete', eventParams);
+     *    return true;
+     *  });
+     * });
+     * ```
+     * @example
+     * with v1 SSF
+     * ```ts
+     * elli.script.subscribe('loan', 'premilestoneComplete', ({ eventParams }) => {
+     *  console.log('Loan pre-milestone complete', eventParams);
+     *  return true;
+     * });
      */
     readonly PreMilestoneComplete: IEvent;
     /**
-     * event fired when the loan is synced
+     * event fired when the loan is synced with any changes made by other users or external systems
      *
      * Use {@link LoanSyncListener} to handle this event
+     * @example
+     * with v2 SSF
+     * ```ts
+     * guest.subscribe({
+     *  eventId: 'loan.sync',
+     *  callback: ({ eventParams }) => {
+     *    console.log('Loan synced', eventParams);
+     *  });
+     * });
+     * ```
+     * @example
+     * with v1 SSF
+     * ```ts
+     * elli.script.subscribe('loan', 'sync', ({ eventParams }) => {
+     *  console.log('Loan synced', eventParams);
+     * });
      */
     readonly Sync: IEvent;
     /**
      * Get complete Loan object
      * @returns v3 Loan Object
+     * @example
+     * ```ts
+     * const loanData = await loan.all();
+     * ```
      */
     all(): Promise<LoanObject>;
-    /**
-     * Applies a partial loan object to the current loan,
-     */
-    apply(loan: LoanObject): Promise<void>;
     /**
      * Applies or removes the calculation lock on a loan field.
      *
@@ -470,107 +756,125 @@ export interface ILoan extends IScriptingObject {
      *
      * Parameters are: ID of the field you want to apply or remove the calculation lock and the status you want to set the lock to
      * @param fieldId ID of the field you want to apply or remove the calculation lock
-     * @param lock
+     * @param lock status you want to set the lock to
+     * @example
+     * ```ts
+     * await loan.applyLock('4001', true);
+     * ```
      */
     applyLock(fieldId: string, lock: boolean): Promise<void>;
     /**
      * Executes calculations and business rules
+     * @returns updated loan object
+     * @example
+     * ```ts
+     * await loan.calculate();
+     * ```
      */
-    calculate(): Promise<void>;
+    calculate(): Promise<LoanObject>;
     /**
      * Commit all pending changes on the current loan
      *
+     * Fires the loan.precommit event before committing the changes
+     *
+     * Fires the loan.committed event after committing the changes
+     *
+     * Business rule violations will prevent the loan from being committed
+     * @returns loan id
+     * @example
+     * ```ts
+     * await loan.commit();
+     * ```
      */
-    commit(): Promise<void>;
+    commit(): Promise<string>;
     /**
      * Execute loan level action, this is specific to v3 stateful implementation
-     * @param type type of action to be executed
+     *
+     * Invokes state API with all pending changes in current change-set along with requested loan action
+     *
+     * Fires the loan.sync event after the action is executed
+     * @param type type of action to be executed. e.g. updateCorrespondentBalance
      * @param params additional parameters for the action
+     * @returns updated loan object
+     * @example
+     * ```ts
+     * await loan.execAction('calculateEEMMortgage');
+     * ```
      */
-    execAction(type: LoanLevelActions, params?: Record<string, unknown>): Promise<LoanObject>;
-    /**
-     * Returns an object with current application selected
-     */
-    getCurrentApplication(): Promise<Record<string, string>>;
+    execAction(type: LoanLevelActions, params?: Record<string, unknown>): Promise<ActionResponse>;
     /**
      * Returns an object reference of type LoanCollection.
      *
      * Argument "name" is required & used to get specific collection like BorrowerEmployer, Escrow etc.
      * @param name collection template name
+     * @returns collection object
+     * @throws error if collection name is invalid
+     * @example
+     * ```ts
+     * const borrowerEmployer = await loan.getCollection('BorrowerEmployer');
+     * ```
      */
-    getCollection(name: string): Promise<Record<string, string>>;
+    getCollection(name: LoanCollection): Promise<LoanCollectionObject>;
     /**
-     * get value of the given field id
-     * @param id field id
-     * @returns field value
+     * Get the current borrower pair information
+     * @returns borrower pair information
+     * @example
+     * ```ts
+     * const currentApplication = await loan.getCurrentApplication();
+     * ```
      */
-    getField(id: string): Promise<string>;
+    getCurrentApplication(): Promise<ApplicationInfo>;
     /**
-     * get options for loan fields / custom form controls
-     *
-     * supports both standard & custom loan fields.
-     *
-     * control Ids takes precedence over field Ids.
-     * @param {FieldOptionsParam} param parameter for getting field options
-     * @returns array of field options for each field / control id
-     *
-     * #### Example
-     *
-     *  ```ts
-     *  const fieldOptions = await loan.getFieldOptions({ fieldIds: ['1543', '1544'] });
-     *  ```
-     *
-     *  ```ts
-     *  const fieldOptions = await loan.getFieldOptions({ controlIds: ['111', '112'] });
-     *  ```
-     *
-     * Following is a sample field options for field Id 1543:
+     * get value of the standard or custom field
+     * @param id field id
+     * @returns field value. Default or blank value is returned if the field is not set
+     * @throws error if field id is empty, null or undefined
+     * @example
+     * ```ts
+     * const fieldValue = await loan.getField('4001');
      * ```
-     *  1543: [
-     *   {
-     *     value: 'Manual Underwriting',
-     *     name: 'Manual Underwriting'
-     *   },
-     *   {
-     *     value: 'DU',
-     *     name: 'DU'
-     *   },
-     *   {
-     *     value: 'LP',
-     *     name: 'LP'
-     *   },
-     *   {
-     *     value: 'LQA',
-     *     name: 'LQA'
-     *   },
-     *   {
-     *     value: 'Other',
-     *     name: 'Other'
-     *   }
-     * ]
+     * @example
+     * ```ts
+     * const fieldValue = await loan.getField('URLA.X1');
      * ```
      */
-    getFieldOptions(param: FieldOptionsParam): Promise<Record<string, FieldOptions[]>>;
+    getField(id: string): Promise<string>;
     /**
-     * Returns the value of a single field using its field ID.
-     * @param ids The field ID of the fields to retrieve.
+     * Returns the value of a standard or custom fields
+     *
+     * Default or blank value is returned if the field is not set
+     * @param ids The field Ids to get the value of
+     * @returns The field values
+     * @example
+     * ```ts
+     * const fieldValues = await loan.getFields(['4001', '4002']);
+     * ```
      */
     getFields(ids: string[]): Promise<Record<string, string>>;
-    /**
-     * get snapshot of loan object
-     */
-    getLockSnapshot(): Promise<Record<string, string>>;
     /**
      * Indicates if the loan is editable or in a read-only state.
      */
     isReadOnly(): Promise<boolean>;
     /**
      * Syncs the loan workspace with any changes made by other users.
+     * @example
+     * ```ts
+     * await loan.merge();
+     * ```
      */
     merge(): Promise<void>;
     /**
-     * Update data for current application
-     * @param options options for setting current application
+     * Switch borrower pair
+     *
+     * Fires the loan.applicationselected event after the borrower pair is switched
+     * @param options borrower pair information
+     * @throws error if borrower pair infromation is invalid
+     * @example
+     * ```ts
+     * await loan.setCurrentApplication({
+     *  id: '5D3B4A1B-3D3B-4A1B-5D3B-4A1B3D3B4A1B'
+     * });
+     * ```
      */
     setCurrentApplication(options: CurrentApplicationOptions): Promise<void>;
     /**
@@ -580,19 +884,23 @@ export interface ILoan extends IScriptingObject {
      *
      * Use this api to prevent current user from making edits to the loan file, while a compliance based workflow is in progress
      * @param options options for setting edit mode
+     * @example
+     * ```ts
+     * await loan.setEditMode({mode: 'READONLY', moduleId: 'urn:encompass:efolder'});
+     * ```
      */
     setEditMode(options: EditModeOptions): Promise<void>;
     /**
-     * Set the values of one or more fields on the Loan.
+     * Set the values of one or more standard or custom fields
+     *
+     * Throws an error if non-existing field id is passed. Fields following the non-existing field will not be set.
+     *
+     * Fires the loan.change event for each field that is changed and loan.sync event after all fields are set
      * @param fields list of field ids and their values
+     * @example
+     * ```ts
+     * await loan.setField({'4000': 'John', '4002': 'David'});
+     * ```
      */
     setFields(fields: Record<string, string>): Promise<void>;
-    /**
-     * insert, delete, update, replace different loand record types.
-     *
-     * scope includes log and non-log record types
-     * @param options options for updating records
-     * @returns array of record ids or loan view entity
-     */
-    updateRecords(options: RecordOptions): Promise<Array<string> | Array<unknown>>;
 }