@khester/create-dynamics-app 1.1.0 → 2.1.0

package/templates/dynamics-365-starter/src/examples/entity-examples/opportunity-model.ts

@@ -1,545 +0,0 @@
-/**
- * Example: Creating a custom Opportunity entity model
- *
- * This example demonstrates how to extend the BaseEntity pattern
- * to create a new entity model with validation, CRUD operations,
- * and integration with the ServiceFactory and logging system.
- *
- * @example
- * ```typescript
- * // Create a new opportunity
- * const opportunity = new Opportunity({
- *   name: 'New Sales Opportunity',
- *   estimatedvalue: 50000,
- *   closeprobability: 75
- * });
- *
- * // Validate and save
- * opportunity.validate();
- * const saved = await Opportunity.create(apiService, opportunity);
- * ```
- */
-
-import { IApiService } from '@khester/dynamics-ui-api-client';
-import { BaseEntity } from '../../models/BaseEntity';
-
-/**
- * Opportunity entity interface
- * Define all properties that the Opportunity entity can have
- */
-export interface IOpportunity {
-  /** Unique identifier for the opportunity */
-  opportunityid?: string;
-
-  /** Opportunity name (required) */
-  name: string;
-
-  /** Estimated value of the opportunity */
-  estimatedvalue?: number;
-
-  /** Close probability percentage (0-100) */
-  closeprobability?: number;
-
-  /** Expected close date */
-  estimatedclosedate?: string;
-
-  /** Opportunity description */
-  description?: string;
-
-  /** Associated account ID */
-  parentaccountid?: string;
-
-  /** Associated contact ID */
-  parentcontactid?: string;
-
-  /** Sales stage option set value */
-  salesstagecode?: number;
-
-  /** Opportunity status (open/won/lost) */
-  statecode?: number;
-
-  /** Detailed status reason */
-  statuscode?: number;
-
-  /** Created date */
-  createdon?: string;
-
-  /** Modified date */
-  modifiedon?: string;
-
-  /** Owner ID */
-  ownerid?: string;
-}
-
-/**
- * Opportunity entity constants
- * Following the same pattern as AccountConstants and ContactConstants
- */
-export class OpportunityConstants {
-  /** Entity name for single opportunity */
-  public static readonly EntityName: string = 'opportunity';
-
-  /** Entity collection name for multiple opportunities */
-  public static readonly EntityCollectionName: string = 'opportunities';
-
-  /** Primary key field */
-  public static readonly PrimaryKey: string = 'opportunityid';
-
-  /** Primary name field */
-  public static readonly PrimaryName: string = 'name';
-
-  /** Estimated value field */
-  public static readonly EstimatedValue: string = 'estimatedvalue';
-
-  /** Close probability field */
-  public static readonly CloseProbability: string = 'closeprobability';
-
-  /** Estimated close date field */
-  public static readonly EstimatedCloseDate: string = 'estimatedclosedate';
-
-  /** Description field */
-  public static readonly Description: string = 'description';
-
-  /** Parent account reference */
-  public static readonly ParentAccountId: string = 'parentaccountid';
-
-  /** Parent contact reference */
-  public static readonly ParentContactId: string = 'parentcontactid';
-
-  /** Sales stage code */
-  public static readonly SalesStageCode: string = 'salesstagecode';
-
-  /** State code (Active/Inactive) */
-  public static readonly StateCode: string = 'statecode';
-
-  /** Status code (detailed status) */
-  public static readonly StatusCode: string = 'statuscode';
-
-  /** Created date */
-  public static readonly CreatedOn: string = 'createdon';
-
-  /** Modified date */
-  public static readonly ModifiedOn: string = 'modifiedon';
-
-  /** Owner ID */
-  public static readonly OwnerId: string = 'ownerid';
-}
-
-/**
- * Sales Stage Option Set Values
- */
-export enum SalesStageCode_OptionSet {
-  Qualify = 0,
-  Develop = 1,
-  Propose = 2,
-  Close = 3,
-}
-
-/**
- * Opportunity State Code Option Set
- */
-export enum OpportunityStateCode_OptionSet {
-  Open = 0,
-  Won = 1,
-  Lost = 2,
-}
-
-/**
- * Opportunity Status Code Option Set
- */
-export enum OpportunityStatusCode_OptionSet {
-  InProgress = 1,
-  OnHold = 2,
-  Won = 3,
-  Canceled = 4,
-  OutSold = 5,
-}
-
-/**
- * Opportunity entity model class
- *
- * Extends BaseEntity to provide CRUD operations, validation,
- * and integration with the logging system.
- *
- * @example
- * ```typescript
- * // Create and validate an opportunity
- * const opp = new Opportunity({
- *   name: 'Q1 Software License Deal',
- *   estimatedvalue: 75000,
- *   closeprobability: 80,
- *   estimatedclosedate: '2024-03-31'
- * });
- *
- * // Validation happens automatically
- * const isValid = opp.validate();
- *
- * // Save to Dynamics 365
- * const savedOpp = await Opportunity.create(apiService, opp);
- * ```
- */
-export class Opportunity extends BaseEntity implements IOpportunity {
-  opportunityid?: string;
-  name: string;
-  estimatedvalue?: number;
-  closeprobability?: number;
-  estimatedclosedate?: string;
-  description?: string;
-  parentaccountid?: string;
-  parentcontactid?: string;
-  salesstagecode?: number;
-  statecode?: number;
-  statuscode?: number;
-  createdon?: string;
-  modifiedon?: string;
-  ownerid?: string;
-
-  /**
-   * Constructor for Opportunity entity
-   * @param opportunity - The opportunity data to initialize with
-   */
-  constructor(opportunity: IOpportunity) {
-    super();
-    this.opportunityid = opportunity.opportunityid;
-    this.name = opportunity.name;
-    this.estimatedvalue = opportunity.estimatedvalue;
-    this.closeprobability = opportunity.closeprobability;
-    this.estimatedclosedate = opportunity.estimatedclosedate;
-    this.description = opportunity.description;
-    this.parentaccountid = opportunity.parentaccountid;
-    this.parentcontactid = opportunity.parentcontactid;
-    this.salesstagecode = opportunity.salesstagecode;
-    this.statecode = opportunity.statecode;
-    this.statuscode = opportunity.statuscode;
-    this.createdon = opportunity.createdon;
-    this.modifiedon = opportunity.modifiedon;
-    this.ownerid = opportunity.ownerid;
-  }
-
-  /**
-   * Validates the opportunity instance
-   * @returns True if valid, throws error if invalid
-   * @throws Error with validation message if validation fails
-   *
-   * @example
-   * ```typescript
-   * try {
-   *   opportunity.validate();
-   *   console.log('Opportunity is valid');
-   * } catch (error) {
-   *   console.error('Validation failed:', error.message);
-   * }
-   * ```
-   */
-  validate(): boolean {
-    if (!this.name || this.name.trim().length === 0) {
-      throw new Error('Opportunity name is required');
-    }
-
-    if (this.name.length > 300) {
-      throw new Error('Opportunity name cannot exceed 300 characters');
-    }
-
-    if (this.estimatedvalue !== undefined && this.estimatedvalue < 0) {
-      throw new Error('Estimated value cannot be negative');
-    }
-
-    if (this.closeprobability !== undefined) {
-      if (this.closeprobability < 0 || this.closeprobability > 100) {
-        throw new Error('Close probability must be between 0 and 100');
-      }
-    }
-
-    if (this.estimatedclosedate) {
-      const closeDate = new Date(this.estimatedclosedate);
-      const today = new Date();
-      if (closeDate < today) {
-        throw new Error('Estimated close date cannot be in the past');
-      }
-    }
-
-    return true;
-  }
-
-  /**
-   * Creates a new opportunity record
-   * @param apiService - The API service instance
-   * @param opportunity - The opportunity to create
-   * @returns Promise resolving to the created opportunity
-   *
-   * @example
-   * ```typescript
-   * const newOpportunity = new Opportunity({
-   *   name: 'Enterprise Software Deal',
-   *   estimatedvalue: 100000,
-   *   closeprobability: 70
-   * });
-   *
-   * const created = await Opportunity.create(apiService, newOpportunity);
-   * console.log('Created opportunity:', created.opportunityid);
-   * ```
-   */
-  public static async create(
-    apiService: IApiService,
-    opportunity: Opportunity
-  ): Promise<Opportunity> {
-    const loggerContext = 'Opportunity.create';
-    console.log(`${loggerContext}: Creating new opportunity`, {
-      name: opportunity.name,
-    });
-
-    return await this.createEntity<Opportunity>(
-      apiService,
-      opportunity,
-      OpportunityConstants.EntityCollectionName,
-      loggerContext
-    );
-  }
-
-  /**
-   * Updates an existing opportunity record
-   * @param apiService - The API service instance
-   * @param opportunity - The opportunity to update
-   * @returns Promise resolving to the updated opportunity
-   *
-   * @example
-   * ```typescript
-   * // Load existing opportunity
-   * const opportunity = await Opportunity.retrieveById(apiService, opportunityId);
-   *
-   * // Update properties
-   * opportunity.closeprobability = 90;
-   * opportunity.salesstagecode = SalesStageCode_OptionSet.Close;
-   *
-   * // Save changes
-   * const updated = await Opportunity.update(apiService, opportunity);
-   * ```
-   */
-  public static async update(
-    apiService: IApiService,
-    opportunity: Opportunity
-  ): Promise<Opportunity> {
-    const loggerContext = 'Opportunity.update';
-
-    if (!opportunity.opportunityid) {
-      throw new Error('Opportunity ID is required for update');
-    }
-
-    console.log(`${loggerContext}: Updating opportunity`, {
-      opportunityid: opportunity.opportunityid,
-      name: opportunity.name,
-    });
-
-    return await this.updateEntity<Opportunity>(
-      apiService,
-      opportunity.opportunityid,
-      opportunity,
-      OpportunityConstants.EntityCollectionName,
-      OpportunityConstants.PrimaryKey,
-      loggerContext
-    );
-  }
-
-  /**
-   * Deletes an opportunity record
-   * @param apiService - The API service instance
-   * @param opportunityId - The ID of the opportunity to delete
-   * @returns Promise resolving when deletion is complete
-   *
-   * @example
-   * ```typescript
-   * await Opportunity.delete(apiService, opportunityId);
-   * console.log('Opportunity deleted successfully');
-   * ```
-   */
-  public static async delete(
-    apiService: IApiService,
-    opportunityId: string
-  ): Promise<void> {
-    const loggerContext = 'Opportunity.delete';
-    console.log(`${loggerContext}: Deleting opportunity`, {
-      opportunityid: opportunityId,
-    });
-
-    return await this.deleteEntity(
-      apiService,
-      opportunityId,
-      OpportunityConstants.EntityCollectionName,
-      loggerContext
-    );
-  }
-
-  /**
-   * Retrieves opportunities based on a filter
-   * @param apiService - The API service instance
-   * @param filter - Optional FetchXML filter string
-   * @returns Promise resolving to an array of opportunities
-   *
-   * @example
-   * ```typescript
-   * // Get all high-value opportunities
-   * const filter = `<filter type="and">
-   *   <condition attribute="estimatedvalue" operator="ge" value="50000" />
-   *   <condition attribute="statecode" operator="eq" value="0" />
-   * </filter>`;
-   *
-   * const opportunities = await Opportunity.retrieveByFilter(apiService, filter);
-   * ```
-   */
-  public static async retrieveByFilter(
-    apiService: IApiService,
-    filter?: string
-  ): Promise<Opportunity[]> {
-    const loggerContext = 'Opportunity.retrieveByFilter';
-    console.log(`${loggerContext}: Retrieving opportunities with filter`, {
-      filter,
-    });
-
-    const attributes = [
-      OpportunityConstants.PrimaryKey,
-      OpportunityConstants.PrimaryName,
-      OpportunityConstants.EstimatedValue,
-      OpportunityConstants.CloseProbability,
-      OpportunityConstants.EstimatedCloseDate,
-      OpportunityConstants.Description,
-      OpportunityConstants.ParentAccountId,
-      OpportunityConstants.ParentContactId,
-      OpportunityConstants.SalesStageCode,
-      OpportunityConstants.StateCode,
-      OpportunityConstants.StatusCode,
-      OpportunityConstants.CreatedOn,
-      OpportunityConstants.ModifiedOn,
-      OpportunityConstants.OwnerId,
-    ];
-
-    const fetchXml = this.buildFetchXml(
-      OpportunityConstants.EntityName,
-      attributes,
-      filter,
-      { attribute: OpportunityConstants.PrimaryName }
-    );
-
-    return await this.retrieveEntitiesByFilter<Opportunity>(
-      apiService,
-      OpportunityConstants.EntityCollectionName,
-      fetchXml,
-      Opportunity,
-      loggerContext
-    );
-  }
-
-  /**
-   * Retrieves a single opportunity by ID
-   * @param apiService - The API service instance
-   * @param opportunityId - The opportunity ID
-   * @returns Promise resolving to the opportunity or null if not found
-   *
-   * @example
-   * ```typescript
-   * const opportunity = await Opportunity.retrieveById(apiService, 'guid-here');
-   * if (opportunity) {
-   *   console.log('Found opportunity:', opportunity.name);
-   * }
-   * ```
-   */
-  public static async retrieveById(
-    apiService: IApiService,
-    opportunityId: string
-  ): Promise<Opportunity | null> {
-    const loggerContext = 'Opportunity.retrieveById';
-    console.log(`${loggerContext}: Retrieving opportunity by ID`, {
-      opportunityid: opportunityId,
-    });
-
-    const filter = `<filter type="and">
-      <condition attribute="${OpportunityConstants.PrimaryKey}" operator="eq" value="${this.escapeXml(opportunityId)}" />
-    </filter>`;
-
-    const opportunities = await this.retrieveByFilter(apiService, filter);
-    return opportunities.length > 0 ? opportunities[0] : null;
-  }
-
-  /**
-   * Retrieves active opportunities only
-   * @param apiService - The API service instance
-   * @returns Promise resolving to an array of active opportunities
-   *
-   * @example
-   * ```typescript
-   * const activeOpportunities = await Opportunity.retrieveActiveOpportunities(apiService);
-   * console.log(`Found ${activeOpportunities.length} active opportunities`);
-   * ```
-   */
-  public static async retrieveActiveOpportunities(
-    apiService: IApiService
-  ): Promise<Opportunity[]> {
-    const loggerContext = 'Opportunity.retrieveActiveOpportunities';
-    console.log(`${loggerContext}: Retrieving active opportunities`);
-
-    const filter = `<filter type="and">
-      <condition attribute="${OpportunityConstants.StateCode}" operator="eq" value="0" />
-    </filter>`;
-
-    return await this.retrieveByFilter(apiService, filter);
-  }
-
-  /**
-   * Retrieves opportunities by sales stage
-   * @param apiService - The API service instance
-   * @param salesStage - The sales stage to filter by
-   * @returns Promise resolving to an array of opportunities in the specified stage
-   *
-   * @example
-   * ```typescript
-   * const proposalStageOpps = await Opportunity.retrieveBySalesStage(
-   *   apiService,
-   *   SalesStageCode_OptionSet.Propose
-   * );
-   * ```
-   */
-  public static async retrieveBySalesStage(
-    apiService: IApiService,
-    salesStage: SalesStageCode_OptionSet
-  ): Promise<Opportunity[]> {
-    const loggerContext = 'Opportunity.retrieveBySalesStage';
-    console.log(`${loggerContext}: Retrieving opportunities by sales stage`, {
-      salesStage,
-    });
-
-    const filter = `<filter type="and">
-      <condition attribute="${OpportunityConstants.SalesStageCode}" operator="eq" value="${salesStage}" />
-      <condition attribute="${OpportunityConstants.StateCode}" operator="eq" value="0" />
-    </filter>`;
-
-    return await this.retrieveByFilter(apiService, filter);
-  }
-
-  /**
-   * Retrieves opportunities by account
-   * @param apiService - The API service instance
-   * @param accountId - The account ID to filter by
-   * @returns Promise resolving to an array of opportunities for the specified account
-   *
-   * @example
-   * ```typescript
-   * const accountOpportunities = await Opportunity.retrieveByAccount(apiService, accountId);
-   * console.log(`Account has ${accountOpportunities.length} opportunities`);
-   * ```
-   */
-  public static async retrieveByAccount(
-    apiService: IApiService,
-    accountId: string
-  ): Promise<Opportunity[]> {
-    const loggerContext = 'Opportunity.retrieveByAccount';
-    console.log(`${loggerContext}: Retrieving opportunities by account`, {
-      accountId,
-    });
-
-    const filter = `<filter type="and">
-      <condition attribute="${OpportunityConstants.ParentAccountId}" operator="eq" value="${this.escapeXml(accountId)}" />
-      <condition attribute="${OpportunityConstants.StateCode}" operator="eq" value="0" />
-    </filter>`;
-
-    return await this.retrieveByFilter(apiService, filter);
-  }
-}