---
title: BillServiceHelper
summary: API reference for BillServiceHelper.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-24
library: SAIF.Services
reference_type: package
---

# BillServiceHelper

Shared collaborator for legal-bill validation and lookup logic — user payment-authority limits, valid received/service date ranges (including 6-month prepayment windows checked against `IWorkCalendarService` and claim injury dates from `ICCClaimApiService`), the next scheduled issue date for a payment transaction type, deposition/doctor-conference notes for a case, financial-transaction lookups, and client-side error logging — used by `BillService`, `BillSaveService`, `BillPaymentService`, and `CaseCostService`.

## Purpose
- Computes a user's maximum payment authority for a given approval purpose and payment type from `EmployeeAuthorityLimit` records.
- Determines whether received/service-from/service-thru dates fall within valid ranges relative to the claim's injury date, today, prepayment rules (6-month window), and the work calendar.
- Returns the next scheduled issue date for a payment transaction type code.
- Retrieves deposition/doctor-conference legal notes for a case and the financial transaction associated with a bill.
- Converts client-side JavaScript exceptions into logged server-side exceptions, and formats billed units into a human-readable quantity string (copies, hours, or plain count).

## Context
- Namespace: `SAIF.Services.Legal.Bills`
- Assembly/package: `SAIF.Services` (packaged inside the `SAIF.SAIFCode.Core` NuGet package).

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| BillServiceHelper (constructor) | `public BillServiceHelper(IUnitOfWork unitOfWork, ILegalQueryProvider legalQueryProvider, ILogService logService, ILegalNotesService legalNotesService, IWorkCalendarService workCalendarService, ICCClaimApiService ccclaimApiService)` | Wires the unit of work, legal query provider, log service, notes service, work-calendar service, and claim API client used by the helper's date-validation and lookup methods. |
| UserAuthorityLevel | `public decimal UserAuthorityLevel(string employeeId, ApprovalTypes purpose, string paymentType)` | Returns the employee's active maximum payment amount for the given payment-authority purpose and payment type (business process = `Payments`), or `0` if no matching, unexpired limit exists. |
| IsValidIssueDate | `public bool IsValidIssueDate(DateTime workDate, string code)` | Returns `true` if `workDate` is on or after the transaction type's next issue date, on or before 14 days from today, and a working day per `IWorkCalendarService`. |
| GetNextIssueDate | `public DateTime GetNextIssueDate(string code)` | Returns the configured next issue date for the given payment transaction type code, defaulting to today if none is configured. |
| IsValidReceivedDate | `public bool IsValidReceivedDate(long caseId, DateTime workDate)` | Returns `true` if the date is on or before today and on or after the case's claim injury date; returns `false` if the claim cannot be found. |
| IsValidServiceFromDate | `public bool IsValidServiceFromDate(long caseId, DateTime workDate, bool isPrepayment)` | Returns `true` if the date is on or after the claim's injury date and, depending on `isPrepayment`, on or before today or within 6 months in the future. |
| IsValidServiceThruDate | `public bool IsValidServiceThruDate(DateTime fromDate, DateTime? thruDate, bool isPrepayment)` | Returns `true` when `thruDate` is null or a min/max sentinel value, or when it is on/after `fromDate` and within the today/6-month prepayment window. |
| GetBillNotes | `public IList<LegalNote> GetBillNotes(long caseId)` | Returns the case's deposition and doctor-conference legal notes, most recently created first, via `ILegalNotesService.GetNotes`. |
| GetFinancialTransaction | `public FinancialTransaction GetFinancialTransaction(long billId, long claimId)` | Returns the financial transaction associated with a legal bill and claim, mapped from `ILegalQueryProvider.GetLegalBillFinancialTransaction`. |
| LogError | `public void LogError(ClientException data)` | Parses the app/page/state segments from the client exception's URL and logs the client-reported error (message and stack trace) via `ILogService.LogException`. |
| UnitsToQuantityString | `public string UnitsToQuantityString(long units, string code)` | Formats billed units as `"N Copies"` for copy service codes, as rounded hours (`units * 15 / 60`) for conference/deposition (and cancellation) service codes, or as a plain unit count otherwise. |

## Behavioral notes
- `IsValidReceivedDate` and `IsValidServiceFromDate` both resolve the claim via `ICCClaimApiService.GetClaim` (awaited synchronously) keyed off the legal case's `ClaimId`, and return `false` if no claim is found.
- `IsValidIssueDate` combines a database-configured next issue date, a hard 14-day lookahead cap, and the injected work-calendar service's working-day check.
- `GetBillNotes` is hardcoded to only the `Deposition` and `DoctorConference` note categories.*

## Constraints and usage notes
- Only `unitOfWork` and `legalQueryProvider`/`logService` are null-checked in the constructor via `Enforce.ArgumentNotNull`; `legalNotesService`, `workCalendarService`, and `ccclaimApiService` are not validated for null.*
- `LogError` assumes the client exception's `Url` is slash-delimited with the app name in segment 3 and the page name in segment 5; malformed URLs fall back to empty strings rather than throwing.*

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- `Services/SAIF.Services/Legal/Bills/BillServiceHelper.cs`