POST /api/ClientContract
Authorization: Bearer {token}
Content-Type: application/json

[
  {
    "ref": "Acme Corp - Managed Services 2024",
    "client_id": 123,
    "type": "Recurring",
    "status": "Active",
    "startdate": "2024-01-01",
    "enddate": "2024-12-31",
    "billingfrequency": "Monthly",
    "invoiceday": 1,
    "value": 2500.00,
    "sla_id": 1,
    "includesallsites": true,
    "includesallassets": true,
    "notes": "Premium support tier, includes unlimited remote support"
  }
]

{
  "contracts": [
    {
      "id": 5001,
      "ref": "Acme Corp - Managed Services 2024",
      "client_id": 123,
      "client_name": "Acme Corporation",
      "status": "Active",
      "startdate": "2024-01-01",
      "enddate": "2024-12-31"
    }
  ]
}

GET /api/ClientContract?client_id=123

GET /api/ClientContract?status=Active

GET /api/ClientContract?enddate_before=2024-03-31&enddate_after=2024-01-01&status=Active

GET /api/ClientContract?type=Recurring

GET /api/ClientContract/5001

GET /api/ClientContract/5001?includerecurringinvoiceitems=true

POST /api/ClientContract
Authorization: Bearer {token}
Content-Type: application/json

[
  {
    "id": 5001,
    "status": "On Hold",
    "notes": "Client requested temporary pause - resume Feb 2024"
  }
]

POST /api/RecurringInvoiceItem
Authorization: Bearer {token}
Content-Type: application/json

[
  {
    "contract_id": 5001,
    "description": "Managed Workstation Support",
    "quantity": 25,
    "unitprice": 50.00,
    "startdate": "2024-01-01"
  },
  {
    "contract_id": 5001,
    "description": "Server Management",
    "quantity": 3,
    "unitprice": 200.00,
    "startdate": "2024-01-01"
  },
  {
    "contract_id": 5001,
    "description": "M365 Business Premium Licenses",
    "quantity": 25,
    "unitprice": 25.00,
    "startdate": "2024-01-01"
  }
]

[
  {
    "id": 10001,
    "quantity": 30,
    "notes": "Added 5 workstations in March"
  }
]

[
  {
    "ref": "Acme Corp - Prepaid Hours Q1 2024",
    "client_id": 123,
    "type": "Prepaid Hours",
    "status": "Active",
    "startdate": "2024-01-01",
    "enddate": "2024-03-31",
    "prepaid_hours": 40,
    "hourlyrate": 150.00,
    "value": 6000.00
  }
]

GET /api/ClientContract/5002?includehoursummary=true

{
  "prepaid_hours": 40,
  "prepaid_hours_used": 12.5,
  "prepaid_hours_remaining": 27.5
}

{
  "ticket_id": 54321,
  "timetaken": 60,
  "contract_id": 5002
}

[
  {
    "id": 5001,
    "sla_id": 1
  }
]

async function checkPrepaidBalance(contractId) {
  const contract = await getContract(contractId);
  const threshold = 10; // hours

  if (contract.prepaid_hours_remaining <= threshold) {
    return {
      alert: true,
      message: `Only ${contract.prepaid_hours_remaining} hours remaining`,
      suggestedAction: 'Create replenishment quote'
    };
  }

  return { alert: false };
}

async function reconcileContractBilling(contractId, period) {
  const contract = await getContract(contractId);
  const invoices = await getContractInvoices(contractId, period);
  const timeEntries = await getContractTime(contractId, period);

  const expectedRecurring = calculateRecurringTotal(contract);
  const actualBilled = invoices.reduce((sum, i) => sum + i.total, 0);
  const unbilledTime = timeEntries.filter(t => !t.invoiced);

  return {
    contract_id: contractId,
    period,
    expected_recurring: expectedRecurring,
    actual_billed: actualBilled,
    unbilled_time_entries: unbilledTime.length,
    unbilled_amount: unbilledTime.reduce((sum, t) => sum + (t.amount || 0), 0)
  };
}

function validateContract(contract) {
  const errors = [];

  if (!contract.ref || contract.ref.trim() === '') {
    errors.push('Contract reference is required');
  }

  if (!contract.client_id) {
    errors.push('Client ID is required');
  }

  if (!contract.startdate) {
    errors.push('Start date is required');
  }

  if (contract.enddate && contract.startdate > contract.enddate) {
    errors.push('End date must be after start date');
  }

  if (contract.type === 'Prepaid Hours' && !contract.prepaid_hours) {
    errors.push('Prepaid hours contracts require hours allocation');
  }

  return {
    isValid: errors.length === 0,
    errors
  };
}

GET /api/ClientContract?groupby=status&count=true

async function getExpiringContracts(days = 90) {
  const futureDate = new Date();
  futureDate.setDate(futureDate.getDate() + days);

  const contracts = await searchContracts({
    status: 'Active',
    enddate_before: futureDate.toISOString().split('T')[0]
  });

  return contracts.map(c => ({
    id: c.id,
    ref: c.ref,
    client_name: c.client_name,
    enddate: c.enddate,
    value: c.value,
    days_remaining: Math.ceil(
      (new Date(c.enddate) - new Date()) / (1000 * 60 * 60 * 24)
    )
  }));
}

async function getContractValueByClient() {
  const clients = await fetchAllClients();
  const results = [];

  for (const client of clients) {
    const contracts = await getClientContracts(client.id, { status: 'Active' });
    const totalValue = contracts.reduce((sum, c) => sum + (c.value || 0), 0);

    results.push({
      client_id: client.id,
      client_name: client.name,
      active_contracts: contracts.length,
      annual_value: totalValue
    });
  }

  return results.sort((a, b) => b.annual_value - a.annual_value);
}