feat(interfaces): add comprehensive TypeScript interface modules, demo data, docs, and publish metadata

ts_interfaces/terms.ts

@@ -0,0 +1,405 @@
+/**
+ * @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: [],
+  };
+}