@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/src/models/Contact.ts

@@ -0,0 +1,580 @@
+import { IApiService } from '@khester/dynamics-ui-api-client';
+import { BaseEntity } from './BaseEntity';
+import { ContactConstants } from '../constants/contact';
+
+/**
+ * Interface for Contact entity
+ */
+export interface IContact {
+  contactid?: string;
+  firstname?: string;
+  lastname?: string;
+  fullname?: string;
+  middlename?: string;
+  salutation?: string;
+  suffix?: string;
+  jobtitle?: string;
+  emailaddress1?: string;
+  emailaddress2?: string;
+  emailaddress3?: string;
+  telephone1?: string; // Business Phone
+  telephone2?: string; // Home Phone
+  mobilephone?: string;
+  fax?: string;
+  pager?: string;
+  parentcustomerid?: string;
+  parentcustomerid_name?: string;
+  department?: string;
+  managerid?: string;
+  assistantname?: string;
+  assistantphone?: string;
+  birthdate?: string;
+  anniversary?: string;
+  gendercode?: number;
+  familystatuscode?: number;
+  haschildrencode?: boolean;
+  childrensnames?: string;
+  description?: string;
+  donotbulkemail?: boolean;
+  donotemail?: boolean;
+  donotfax?: boolean;
+  donotphone?: boolean;
+  donotpostalmail?: boolean;
+  donotsendmm?: boolean;
+  preferredcontactmethodcode?: number;
+  preferredappointmentdaycode?: number;
+  preferredappointmenttimecode?: number;
+  address1_addresstypecode?: string;
+  address1_city?: string;
+  address1_country?: string;
+  address1_county?: string;
+  address1_fax?: string;
+  address1_latitude?: number;
+  address1_line1?: string;
+  address1_line2?: string;
+  address1_line3?: string;
+  address1_longitude?: number;
+  address1_name?: string;
+  address1_postalcode?: string;
+  address1_postofficebox?: string;
+  address1_primarycontactname?: string;
+  address1_shippingmethodcode?: number;
+  address1_stateorprovince?: string;
+  address1_telephone1?: string;
+  address1_telephone2?: string;
+  address1_telephone3?: string;
+  address1_upszone?: string;
+  address1_utcoffset?: number;
+  creditlimit?: number;
+  creditonhold?: boolean;
+  paymenttermscode?: number;
+  customersizecode?: number;
+  leadsourcecode?: number;
+  websiteurl?: string;
+  governmentid?: string;
+  yomifirstname?: string;
+  yomilastname?: string;
+  yomimiddlename?: string;
+  yomifullname?: string;
+  statecode?: number;
+  statuscode?: number;
+  createdon?: string;
+  modifiedon?: string;
+  createdby?: string;
+  modifiedby?: string;
+  ownerid?: string;
+  transactioncurrencyid?: string;
+}
+
+/**
+ * Contact entity model class
+ */
+export class Contact extends BaseEntity implements IContact {
+  contactid?: string;
+  firstname?: string;
+  lastname?: string;
+  fullname?: string;
+  middlename?: string;
+  salutation?: string;
+  suffix?: string;
+  jobtitle?: string;
+  emailaddress1?: string;
+  emailaddress2?: string;
+  emailaddress3?: string;
+  telephone1?: string;
+  telephone2?: string;
+  mobilephone?: string;
+  fax?: string;
+  pager?: string;
+  parentcustomerid?: string;
+  parentcustomerid_name?: string;
+  department?: string;
+  managerid?: string;
+  assistantname?: string;
+  assistantphone?: string;
+  birthdate?: string;
+  anniversary?: string;
+  gendercode?: number;
+  familystatuscode?: number;
+  haschildrencode?: boolean;
+  childrensnames?: string;
+  description?: string;
+  donotbulkemail?: boolean;
+  donotemail?: boolean;
+  donotfax?: boolean;
+  donotphone?: boolean;
+  donotpostalmail?: boolean;
+  donotsendmm?: boolean;
+  preferredcontactmethodcode?: number;
+  preferredappointmentdaycode?: number;
+  preferredappointmenttimecode?: number;
+  address1_addresstypecode?: string;
+  address1_city?: string;
+  address1_country?: string;
+  address1_county?: string;
+  address1_fax?: string;
+  address1_latitude?: number;
+  address1_line1?: string;
+  address1_line2?: string;
+  address1_line3?: string;
+  address1_longitude?: number;
+  address1_name?: string;
+  address1_postalcode?: string;
+  address1_postofficebox?: string;
+  address1_primarycontactname?: string;
+  address1_shippingmethodcode?: number;
+  address1_stateorprovince?: string;
+  address1_telephone1?: string;
+  address1_telephone2?: string;
+  address1_telephone3?: string;
+  address1_upszone?: string;
+  address1_utcoffset?: number;
+  creditlimit?: number;
+  creditonhold?: boolean;
+  paymenttermscode?: number;
+  customersizecode?: number;
+  leadsourcecode?: number;
+  websiteurl?: string;
+  governmentid?: string;
+  yomifirstname?: string;
+  yomilastname?: string;
+  yomimiddlename?: string;
+  yomifullname?: string;
+  statecode?: number;
+  statuscode?: number;
+  createdon?: string;
+  modifiedon?: string;
+  createdby?: string;
+  modifiedby?: string;
+  ownerid?: string;
+  transactioncurrencyid?: string;
+
+  /**
+   * Constructor for Contact entity
+   * @param contact The contact data
+   */
+  constructor(contact: IContact) {
+    super();
+    this.contactid = contact.contactid;
+    this.firstname = contact.firstname;
+    this.lastname = contact.lastname;
+    this.fullname = contact.fullname;
+    this.middlename = contact.middlename;
+    this.salutation = contact.salutation;
+    this.suffix = contact.suffix;
+    this.jobtitle = contact.jobtitle;
+    this.emailaddress1 = contact.emailaddress1;
+    this.emailaddress2 = contact.emailaddress2;
+    this.emailaddress3 = contact.emailaddress3;
+    this.telephone1 = contact.telephone1;
+    this.telephone2 = contact.telephone2;
+    this.mobilephone = contact.mobilephone;
+    this.fax = contact.fax;
+    this.pager = contact.pager;
+    this.parentcustomerid = contact.parentcustomerid;
+    this.parentcustomerid_name = contact.parentcustomerid_name;
+    this.department = contact.department;
+    this.managerid = contact.managerid;
+    this.assistantname = contact.assistantname;
+    this.assistantphone = contact.assistantphone;
+    this.birthdate = contact.birthdate;
+    this.anniversary = contact.anniversary;
+    this.gendercode = contact.gendercode;
+    this.familystatuscode = contact.familystatuscode;
+    this.haschildrencode = contact.haschildrencode;
+    this.childrensnames = contact.childrensnames;
+    this.description = contact.description;
+    this.donotbulkemail = contact.donotbulkemail;
+    this.donotemail = contact.donotemail;
+    this.donotfax = contact.donotfax;
+    this.donotphone = contact.donotphone;
+    this.donotpostalmail = contact.donotpostalmail;
+    this.donotsendmm = contact.donotsendmm;
+    this.preferredcontactmethodcode = contact.preferredcontactmethodcode;
+    this.preferredappointmentdaycode = contact.preferredappointmentdaycode;
+    this.preferredappointmenttimecode = contact.preferredappointmenttimecode;
+    this.address1_addresstypecode = contact.address1_addresstypecode;
+    this.address1_city = contact.address1_city;
+    this.address1_country = contact.address1_country;
+    this.address1_county = contact.address1_county;
+    this.address1_fax = contact.address1_fax;
+    this.address1_latitude = contact.address1_latitude;
+    this.address1_line1 = contact.address1_line1;
+    this.address1_line2 = contact.address1_line2;
+    this.address1_line3 = contact.address1_line3;
+    this.address1_longitude = contact.address1_longitude;
+    this.address1_name = contact.address1_name;
+    this.address1_postalcode = contact.address1_postalcode;
+    this.address1_postofficebox = contact.address1_postofficebox;
+    this.address1_primarycontactname = contact.address1_primarycontactname;
+    this.address1_shippingmethodcode = contact.address1_shippingmethodcode;
+    this.address1_stateorprovince = contact.address1_stateorprovince;
+    this.address1_telephone1 = contact.address1_telephone1;
+    this.address1_telephone2 = contact.address1_telephone2;
+    this.address1_telephone3 = contact.address1_telephone3;
+    this.address1_upszone = contact.address1_upszone;
+    this.address1_utcoffset = contact.address1_utcoffset;
+    this.creditlimit = contact.creditlimit;
+    this.creditonhold = contact.creditonhold;
+    this.paymenttermscode = contact.paymenttermscode;
+    this.customersizecode = contact.customersizecode;
+    this.leadsourcecode = contact.leadsourcecode;
+    this.websiteurl = contact.websiteurl;
+    this.governmentid = contact.governmentid;
+    this.yomifirstname = contact.yomifirstname;
+    this.yomilastname = contact.yomilastname;
+    this.yomimiddlename = contact.yomimiddlename;
+    this.yomifullname = contact.yomifullname;
+    this.statecode = contact.statecode;
+    this.statuscode = contact.statuscode;
+    this.createdon = contact.createdon;
+    this.modifiedon = contact.modifiedon;
+    this.createdby = contact.createdby;
+    this.modifiedby = contact.modifiedby;
+    this.ownerid = contact.ownerid;
+    this.transactioncurrencyid = contact.transactioncurrencyid;
+  }
+
+  /**
+   * Validates the contact instance
+   * @returns True if valid, throws error if invalid
+   */
+  validate(): boolean {
+    // At least one of firstname or lastname is required
+    if (
+      (!this.firstname || this.firstname.trim().length === 0) &&
+      (!this.lastname || this.lastname.trim().length === 0)
+    ) {
+      throw new Error('Contact must have either first name or last name');
+    }
+
+    if (this.firstname && this.firstname.length > 50) {
+      throw new Error('First name cannot exceed 50 characters');
+    }
+
+    if (this.lastname && this.lastname.length > 50) {
+      throw new Error('Last name cannot exceed 50 characters');
+    }
+
+    if (this.middlename && this.middlename.length > 100) {
+      throw new Error('Middle name cannot exceed 100 characters');
+    }
+
+    if (this.jobtitle && this.jobtitle.length > 100) {
+      throw new Error('Job title cannot exceed 100 characters');
+    }
+
+    if (this.emailaddress1 && !this.isValidEmail(this.emailaddress1)) {
+      throw new Error('Invalid primary email address format');
+    }
+
+    if (this.emailaddress2 && !this.isValidEmail(this.emailaddress2)) {
+      throw new Error('Invalid secondary email address format');
+    }
+
+    if (this.emailaddress3 && !this.isValidEmail(this.emailaddress3)) {
+      throw new Error('Invalid tertiary email address format');
+    }
+
+    if (this.websiteurl && !this.isValidUrl(this.websiteurl)) {
+      throw new Error('Invalid website URL format');
+    }
+
+    if (this.birthdate && !this.isValidDate(this.birthdate)) {
+      throw new Error('Invalid birth date format');
+    }
+
+    if (this.anniversary && !this.isValidDate(this.anniversary)) {
+      throw new Error('Invalid anniversary date format');
+    }
+
+    if (this.creditlimit !== undefined && this.creditlimit < 0) {
+      throw new Error('Credit limit cannot be negative');
+    }
+
+    return true;
+  }
+
+  /**
+   * Creates a new contact record
+   * @param apiService The API service instance
+   * @param contact The contact to create
+   * @returns Promise resolving to the created contact
+   */
+  public static async create(
+    apiService: IApiService,
+    contact: Contact
+  ): Promise<Contact> {
+    const loggerContext = 'Contact.create';
+    console.log(`${loggerContext}: Creating new contact`, {
+      firstname: contact.firstname,
+      lastname: contact.lastname,
+    });
+
+    return await this.createEntity<Contact>(
+      apiService,
+      contact,
+      ContactConstants.EntityCollectionName,
+      loggerContext
+    );
+  }
+
+  /**
+   * Updates an existing contact record
+   * @param apiService The API service instance
+   * @param contact The contact to update
+   * @returns Promise resolving to the updated contact
+   */
+  public static async update(
+    apiService: IApiService,
+    contact: Contact
+  ): Promise<Contact> {
+    const loggerContext = 'Contact.update';
+
+    if (!contact.contactid) {
+      throw new Error('Contact ID is required for update');
+    }
+
+    console.log(`${loggerContext}: Updating contact`, {
+      contactid: contact.contactid,
+      firstname: contact.firstname,
+      lastname: contact.lastname,
+    });
+
+    return await this.updateEntity<Contact>(
+      apiService,
+      contact.contactid,
+      contact,
+      ContactConstants.EntityCollectionName,
+      ContactConstants.PrimaryKey,
+      loggerContext
+    );
+  }
+
+  /**
+   * Deletes a contact record
+   * @param apiService The API service instance
+   * @param contactId The ID of the contact to delete
+   * @returns Promise resolving when deletion is complete
+   */
+  public static async delete(
+    apiService: IApiService,
+    contactId: string
+  ): Promise<void> {
+    const loggerContext = 'Contact.delete';
+    console.log(`${loggerContext}: Deleting contact`, { contactid: contactId });
+
+    return await this.deleteEntity(
+      apiService,
+      contactId,
+      ContactConstants.EntityCollectionName,
+      loggerContext
+    );
+  }
+
+  /**
+   * Retrieves contacts based on a filter
+   * @param apiService The API service instance
+   * @param filter Optional FetchXML filter string
+   * @returns Promise resolving to an array of contacts
+   */
+  public static async retrieveByFilter(
+    apiService: IApiService,
+    filter?: string
+  ): Promise<Contact[]> {
+    const loggerContext = 'Contact.retrieveByFilter';
+    console.log(`${loggerContext}: Retrieving contacts with filter`, {
+      filter,
+    });
+
+    const attributes = [
+      ContactConstants.PrimaryKey,
+      ContactConstants.FirstName,
+      ContactConstants.LastName,
+      ContactConstants.PrimaryName,
+      ContactConstants.JobTitle,
+      ContactConstants.EMailAddress1,
+      ContactConstants.BusinessPhone,
+      ContactConstants.MobilePhone,
+      ContactConstants.CompanyName,
+      ContactConstants.Department,
+      ContactConstants.Address1_City,
+      ContactConstants.Address1_StateOrProvince,
+      ContactConstants.Address1_Country,
+      ContactConstants.StateCode,
+      ContactConstants.StatusCode,
+      ContactConstants.CreatedOn,
+      ContactConstants.ModifiedOn,
+    ];
+
+    const fetchXml = this.buildFetchXml(
+      ContactConstants.EntityName,
+      attributes,
+      filter,
+      { attribute: ContactConstants.LastName }
+    );
+
+    return await this.retrieveEntitiesByFilter<Contact>(
+      apiService,
+      ContactConstants.EntityCollectionName,
+      fetchXml,
+      Contact,
+      loggerContext
+    );
+  }
+
+  /**
+   * Retrieves a single contact by ID
+   * @param apiService The API service instance
+   * @param contactId The contact ID
+   * @returns Promise resolving to the contact or null if not found
+   */
+  public static async retrieveById(
+    apiService: IApiService,
+    contactId: string
+  ): Promise<Contact | null> {
+    const loggerContext = 'Contact.retrieveById';
+    console.log(`${loggerContext}: Retrieving contact by ID`, {
+      contactid: contactId,
+    });
+
+    const filter = `<filter type="and">
+      <condition attribute="${ContactConstants.PrimaryKey}" operator="eq" value="${this.escapeXml(contactId)}" />
+    </filter>`;
+
+    const contacts = await this.retrieveByFilter(apiService, filter);
+    return contacts.length > 0 ? contacts[0] : null;
+  }
+
+  /**
+   * Retrieves contacts by name (partial match on first or last name)
+   * @param apiService The API service instance
+   * @param name The name to search for
+   * @returns Promise resolving to an array of matching contacts
+   */
+  public static async retrieveByName(
+    apiService: IApiService,
+    name: string
+  ): Promise<Contact[]> {
+    const loggerContext = 'Contact.retrieveByName';
+    console.log(`${loggerContext}: Retrieving contacts by name`, { name });
+
+    const filter = `<filter type="or">
+      <condition attribute="${ContactConstants.FirstName}" operator="like" value="%${this.escapeXml(name)}%" />
+      <condition attribute="${ContactConstants.LastName}" operator="like" value="%${this.escapeXml(name)}%" />
+      <condition attribute="${ContactConstants.PrimaryName}" operator="like" value="%${this.escapeXml(name)}%" />
+    </filter>`;
+
+    return await this.retrieveByFilter(apiService, filter);
+  }
+
+  /**
+   * Retrieves contacts by email address
+   * @param apiService The API service instance
+   * @param email The email address to search for
+   * @returns Promise resolving to an array of matching contacts
+   */
+  public static async retrieveByEmail(
+    apiService: IApiService,
+    email: string
+  ): Promise<Contact[]> {
+    const loggerContext = 'Contact.retrieveByEmail';
+    console.log(`${loggerContext}: Retrieving contacts by email`, { email });
+
+    const filter = `<filter type="or">
+      <condition attribute="${ContactConstants.EMailAddress1}" operator="eq" value="${this.escapeXml(email)}" />
+      <condition attribute="${ContactConstants.EMailAddress2}" operator="eq" value="${this.escapeXml(email)}" />
+      <condition attribute="${ContactConstants.EMailAddress3}" operator="eq" value="${this.escapeXml(email)}" />
+    </filter>`;
+
+    return await this.retrieveByFilter(apiService, filter);
+  }
+
+  /**
+   * Retrieves contacts by account (parent customer)
+   * @param apiService The API service instance
+   * @param accountId The account ID
+   * @returns Promise resolving to an array of contacts for the account
+   */
+  public static async retrieveByAccount(
+    apiService: IApiService,
+    accountId: string
+  ): Promise<Contact[]> {
+    const loggerContext = 'Contact.retrieveByAccount';
+    console.log(`${loggerContext}: Retrieving contacts by account`, {
+      accountId,
+    });
+
+    const filter = `<filter type="and">
+      <condition attribute="${ContactConstants.ParentCustomerId}" operator="eq" value="${this.escapeXml(accountId)}" />
+    </filter>`;
+
+    return await this.retrieveByFilter(apiService, filter);
+  }
+
+  /**
+   * Retrieves active contacts only
+   * @param apiService The API service instance
+   * @returns Promise resolving to an array of active contacts
+   */
+  public static async retrieveActiveContacts(
+    apiService: IApiService
+  ): Promise<Contact[]> {
+    const loggerContext = 'Contact.retrieveActiveContacts';
+    console.log(`${loggerContext}: Retrieving active contacts`);
+
+    const filter = `<filter type="and">
+      <condition attribute="${ContactConstants.StateCode}" operator="eq" value="0" />
+    </filter>`;
+
+    return await this.retrieveByFilter(apiService, filter);
+  }
+
+  /**
+   * Helper method to validate email format
+   */
+  private isValidEmail(email: string): boolean {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+  }
+
+  /**
+   * Helper method to validate URL format
+   */
+  private isValidUrl(url: string): boolean {
+    try {
+      new URL(url);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Helper method to validate date format
+   */
+  private isValidDate(dateString: string): boolean {
+    const date = new Date(dateString);
+    return !isNaN(date.getTime());
+  }
+}