tools/ts_interfaces/terms.ts

/**
 * @file terms.ts
 * @description Financial, time-based, and obligation terms interfaces
 * Machine-readable structured terms for contracts
 */

import * as plugins from './plugins.js';
import type {
  TPaymentFrequency,
  TPaymentMethod,
  TPaymentStatus,
  TInterestType,
  TPenaltyType,
  TDurationUnit,
  TRenewalType,
  TNoticeEffectivePoint,
  TNoticeForm,
  TMilestoneStatus,
  TObligationType,
  TObligationStatus,
  TObligationPriority,
  TDeliverableStatus,
  TInsuranceType,
} from './types.js';

// ============================================================================
// FINANCIAL TERMS INTERFACES
// ============================================================================

/**
 * Monetary amount with currency
 */
export interface IMonetaryAmount {
  amount: number;
  currency: string;
  includesTax: boolean;
  taxRate?: number;
}

/**
 * Payment schedule entry
 */
export interface IPaymentScheduleEntry {
  paymentId: string;
  description: string;
  amount: IMonetaryAmount;
  dueDate: number;
  frequency: TPaymentFrequency;
  numberOfPayments?: number;
  isFinalPayment: boolean;
  milestoneId?: string;
  status: TPaymentStatus;
  paidDate?: number;
}

/**
 * Interest rate configuration
 */
export interface IInterestRate {
  type: TInterestType;
  baseRate: number;
  spread?: number;
  referenceRate?: string;
  compoundingFrequency?: TPaymentFrequency;
  maxRate?: number;
  minRate?: number;
}

/**
 * Penalty configuration
 */
export interface IPenalty {
  id: string;
  type: TPenaltyType;
  description: string;
  fixedAmount?: IMonetaryAmount;
  percentage?: number;
  percentageOf?: 'contract_value' | 'outstanding_amount' | 'monthly_value' | 'custom';
  interestRate?: IInterestRate;
  gracePeriod?: IDuration;
  maximumPenalty?: IMonetaryAmount;
}

/**
 * Billing rate for time-based contracts
 */
export interface IBillingRate {
  id: string;
  description: string;
  type: 'hourly' | 'daily' | 'weekly' | 'monthly' | 'per_unit' | 'flat';
  rate: IMonetaryAmount;
  roleId?: string;
  minimumUnit?: number;
}

/**
 * Price adjustment provisions
 */
export interface IPriceAdjustment {
  type: 'fixed_increase' | 'cpi_linked' | 'negotiated' | 'formula_based';
  frequency: TPaymentFrequency;
  fixedIncreasePercentage?: number;
  linkedIndex?: string;
  formula?: string;
  maxIncrease?: number;
  noticePeriod?: IDuration;
}

/**
 * Comprehensive financial terms
 */
export interface IFinancialTerms {
  totalValue?: IMonetaryAmount;
  paymentSchedule: IPaymentScheduleEntry[];
  paymentMethods: TPaymentMethod[];
  paymentTerms?: string;
  paymentDueDays?: number;
  deposit?: IMonetaryAmount;
  depositRefundable: boolean;
  retainer?: IMonetaryAmount;
  billingRates: IBillingRate[];
  interestRates: {
    latePayment?: IInterestRate;
    financing?: IInterestRate;
  };
  penalties: IPenalty[];
  priceAdjustment?: IPriceAdjustment;
  paymentAccount?: plugins.tsclass.finance.ISepaConnection;
  notes?: string;
}

// ============================================================================
// TIME-BASED TERMS INTERFACES
// ============================================================================

/**
 * Duration specification
 */
export interface IDuration {
  value: number;
  unit: TDurationUnit;
}

/**
 * Milestone definition
 */
export interface IMilestone {
  milestoneId: string;
  name: string;
  description: string;
  targetDate?: number;
  completedDate?: number;
  status: TMilestoneStatus;
  dependsOn: string[];
  paymentId?: string;
  deliverables: string[];
  acceptanceCriteria: string[];
}

/**
 * Deadline definition
 */
export interface IDeadline {
  id: string;
  name: string;
  description?: string;
  date: number;
  type: 'hard' | 'soft';
  penalty?: IPenalty;
  reminderDays: number[];
}

/**
 * Key date for tracking
 */
export interface IKeyDate {
  id: string;
  name: string;
  date: number;
  type: 'anniversary' | 'review' | 'renewal_deadline' | 'price_adjustment' | 'custom';
  notes?: string;
}

/**
 * Notice period configuration
 */
export interface INoticePeriod {
  duration: IDuration;
  effectivePoint: TNoticeEffectivePoint;
  form: TNoticeForm;
}

/**
 * Renewal terms
 */
export interface IRenewalTerms {
  type: TRenewalType;
  renewalPeriod?: IDuration;
  maxRenewals?: number;
  currentRenewalCount: number;
  nonRenewalNotice?: INoticePeriod;
  renewalPriceAdjustment?: IPriceAdjustment;
  conditions: string[];
}

/**
 * Termination terms
 */
export interface ITerminationTerms {
  noticePeriod: INoticePeriod;
  immediateTerminationGrounds: string[];
  terminationFee?: IMonetaryAmount;
  postTerminationObligations: string[];
  survivalClauses: string[];
}

/**
 * Comprehensive time-based terms
 */
export interface ITimeTerms {
  effectiveDate?: number;
  executionDate?: number;
  expirationDate?: number;
  duration?: IDuration;
  isIndefinite: boolean;
  commencementConditions: string[];
  milestones: IMilestone[];
  deadlines: IDeadline[];
  noticePeriods: {
    termination?: INoticePeriod;
    renewal?: INoticePeriod;
    amendment?: INoticePeriod;
    priceChange?: INoticePeriod;
  };
  renewal?: IRenewalTerms;
  termination?: ITerminationTerms;
  keyDates: IKeyDate[];
}

// ============================================================================
// OBLIGATION TERMS INTERFACES
// ============================================================================

/**
 * Deliverable definition
 */
export interface IDeliverable {
  deliverableId: string;
  name: string;
  description: string;
  responsiblePartyId: string;
  receivingPartyId?: string;
  dueDate?: number;
  milestoneId?: string;
  acceptanceCriteria: string[];
  quantity?: number;
  unit?: string;
  qualityStandards: string[];
  deliveryMethod?: string;
  status: TDeliverableStatus;
}

/**
 * Service level definition
 */
export interface IServiceLevel {
  slId: string;
  metric: string;
  description?: string;
  target: number;
  unit: string;
  measurementPeriod: TPaymentFrequency;
  minimumLevel?: number;
  penalty?: IPenalty;
  remedyCredit?: IMonetaryAmount;
  exclusions: string[];
  reporting?: {
    frequency: TPaymentFrequency;
    format?: string;
  };
}

/**
 * Quantity specification
 */
export interface IQuantitySpec {
  minimum?: number;
  maximum?: number;
  target?: number;
  unit: string;
  period?: TPaymentFrequency;
}

/**
 * General obligation
 */
export interface IObligation {
  obligationId: string;
  type: TObligationType;
  description: string;
  obligorPartyId: string;
  beneficiaryPartyId?: string;
  dueDate?: number;
  recurring: boolean;
  frequency?: TPaymentFrequency;
  duration?: IDuration;
  priority: TObligationPriority;
  clauseId?: string;
  status: TObligationStatus;
}

/**
 * Warranty definition
 */
export interface IWarranty {
  id: string;
  description: string;
  duration?: IDuration;
  scope?: string;
  limitations: string[];
  remedies: string[];
}

/**
 * Representation definition
 */
export interface IRepresentation {
  id: string;
  partyId: string;
  statement: string;
  asOfDate: 'signing' | 'effective_date' | 'ongoing';
}

/**
 * Insurance requirement
 */
export interface IInsuranceRequirement {
  id: string;
  type: TInsuranceType;
  minimumCoverage: IMonetaryAmount;
  description?: string;
  requireCertificate: boolean;
}

/**
 * Comprehensive obligation terms
 */
export interface IObligationTerms {
  deliverables: IDeliverable[];
  serviceLevels: IServiceLevel[];
  quantities: IQuantitySpec[];
  obligations: IObligation[];
  warranties: IWarranty[];
  representations: IRepresentation[];
  insuranceRequirements: IInsuranceRequirement[];
  complianceRequirements: string[];
}

// ============================================================================
// FACTORY FUNCTIONS FOR EMPTY STRUCTURES
// ============================================================================

/**
 * Create empty financial terms
 */
export function createEmptyFinancialTerms(): IFinancialTerms {
  return {
    paymentSchedule: [],
    paymentMethods: [],
    depositRefundable: false,
    billingRates: [],
    interestRates: {},
    penalties: [],
  };
}

/**
 * Create empty time terms
 */
export function createEmptyTimeTerms(): ITimeTerms {
  return {
    isIndefinite: false,
    commencementConditions: [],
    milestones: [],
    deadlines: [],
    noticePeriods: {},
    keyDates: [],
  };
}

/**
 * Create empty obligation terms
 */
export function createEmptyObligationTerms(): IObligationTerms {
  return {
    deliverables: [],
    serviceLevels: [],
    quantities: [],
    obligations: [],
    warranties: [],
    representations: [],
    insuranceRequirements: [],
    complianceRequirements: [],
  };
}