@mindbill/react 0.23.2 → 0.25.0

package/README.md

@@ -152,15 +152,17 @@ The component includes the interaction model, not just the markup:
 - paste-friendly `MM/DD/YYYY` date fields and required-field asterisks;
 - ZIP-to-city/state completion through MindBill's authenticated postal directory;
 - complete, server-backed ICD-10 search with an alphabetized 100-code first page, automatic 100-code scroll paging, common-injury quick picks, and removable chips;
-- canonical claims-administrator search through the authenticated MindBill payer directory;
+- canonical claims-administrator matching through the authenticated MindBill payer directory: exact aliases select automatically, while fuzzy matches show up to five explicit suggestions with claim-number pattern evidence;
 - QME, AME, and Psych QME evaluation modes with medical-legal modifier defaults; Psych QME also seeds `Z04.6` when no more specific diagnosis was supplied, and exposes it as a Psych quick pick;
 - searchable workers-comp procedure/modifier controls, medical-legal fee-schedule amounts, totals, valid manual CPT/HCPCS entry, and an automatically maintained empty line;
-- removable source documents with new-tab previews, a locked auto-attached practice W-9, and a full-width click, panel-drop, or whole-page PDF upload area. Every visible source document is included until removed; uploaded PDFs do not require document-type tagging.
+- removable source documents with new-tab previews, a locked auto-attached practice W-9, and a full-width click, panel-drop, or whole-page PDF upload area. Med-legal mode assigns every document to `J4 - Med-Legal Report` without showing another control; professional mode shows the complete searchable PWK01 report-type directory. Override that presentation with `attachmentReportTypeMode`, `attachmentReportTypes`, and `defaultAttachmentReportType`.
 
 Partners supply tenant-specific bootstrap data, one short-lived browser session callback, and optionally an `onSubmitted` callback to persist the returned `billId`. Required fields, validation, ZIP lookup, ICD-10 and payer directories, service-line behavior, PDF encoding, wire-format serialization, atomic submission, attachments, and submission UX stay inside `@mindbill/react`, so every integration receives the same billing workflow. Optional `diagnosisOptions`, `procedureOptions`, `modifierOptions`, and lookup callbacks extend or replace defaults when a partner has licensed or organization-specific data.
 
 Validation is component-owned as well. A missing routing payer is highlighted immediately; Submit highlights every invalid control with a specific message, focuses and scrolls to the first problem, and continues validating as the user corrects the form.
 
+The complete immutable snapshot requires patient identity and address; employer, injury date, service date, and a canonical claims-administrator directory selection; at least one ICD-10 diagnosis and procedure line; billing provider name, Tax ID, NPI, phone, and address; rendering provider name, NPI, and taxonomy; and service-facility address plus place-of-service code. Address line 2 and physician license metadata remain optional. For California workers-comp CMS-1500 output, `renderingProvider.taxonomy` is the 10-character provider taxonomy placed in shaded Box 24J with qualifier `ZZ`; it is not replaced by the physician license number.
+
 `BILL_SUBMISSION_REQUIRED_FIELDS` and `validateBillSubmission` expose the same contract for tests and non-visual integrations. The component never creates a draft; `onSubmitted` fires only after MindBill accepts a locally valid immutable snapshot. The legacy `onSubmit` escape hatch remains optional for unusual deployments, but connected integrations should omit it so the library owns the complete contract.
 
 `BillReviewForm` remains available for legacy integrations that already own a custom review model. New integrations should use `BillSubmissionForm`.

package/dist/index.d.ts

@@ -357,9 +357,17 @@ declare function BillReadOnlyForm({ data, appearance, className, style, onOpenAt
 
 declare const BILL_SUBMISSION_DOCUMENT_TYPES: readonly ["final_report", "proof_of_service", "letter_of_attestation", "form_122", "return_to_work_voucher", "w9", "medical_records", "appeal", "other"];
 type BillSubmissionDocumentType = (typeof BILL_SUBMISSION_DOCUMENT_TYPES)[number];
+type BillSubmissionAttachmentReportTypeMode = "auto" | "hidden" | "visible";
+type BillSubmissionReportTypeOption = {
+    code: string;
+    label: string;
+};
+declare const MED_LEGAL_REPORT_TYPE_CODE = "OZ:J4";
+declare const BILL_SUBMISSION_REPORT_TYPES: readonly BillSubmissionReportTypeOption[];
 type BillSubmissionEvaluationType = "qme" | "ame" | "psych_qme";
 type BillSubmissionAddress = {
     line1: string;
+    line2?: string;
     city: string;
     state: string;
     postalCode: string;
@@ -448,6 +456,36 @@ type BillSubmissionInput = {
         diagnosisPointers?: number[];
     }>;
 };
+/** A validated, submission-ready bill. The form accepts partial provider data while editing,
+ * but only emits this complete contract after every required field has passed validation. */
+type CompleteBillSubmissionInput = Omit<BillSubmissionInput, "claim" | "billingProvider" | "renderingProvider" | "serviceLocation" | "diagnoses" | "serviceLines"> & {
+    claim: BillSubmissionInput["claim"] & {
+        employer: string;
+        dateOfInjury: string;
+        claimsAdministrator: {
+            id: string;
+            name: string;
+        };
+    };
+    billingProvider: {
+        name: string;
+        taxId: string;
+        npi: string;
+        phone: string;
+        address: BillSubmissionAddress;
+    };
+    renderingProvider: NonNullable<BillSubmissionInput["renderingProvider"]> & {
+        name: string;
+        npi: string;
+        taxonomy: string;
+    };
+    serviceLocation: NonNullable<BillSubmissionInput["serviceLocation"]> & {
+        address: BillSubmissionAddress;
+        placeOfServiceCode: string;
+    };
+    diagnoses: string[];
+    serviceLines: BillSubmissionInput["serviceLines"];
+};
 type BillSubmissionSourceAttachment = {
     id: string;
     fileName: string;
@@ -459,15 +497,18 @@ type BillSubmissionSourceAttachment = {
     autoAttached?: boolean;
     removable?: boolean;
     previewUrl?: string;
+    reportTypeCode?: string;
 };
 type BillSubmissionUpload = {
     file: File;
     documentType: BillSubmissionDocumentType;
     description?: string;
+    reportTypeCode?: string;
 };
 type BillSubmissionFormValue = {
-    bill: BillSubmissionInput;
+    bill: CompleteBillSubmissionInput;
     sourceAttachmentIds: string[];
+    sourceAttachmentReportTypes: Record<string, string>;
     uploads: BillSubmissionUpload[];
 };
 type BillSubmissionFormProps = {
@@ -491,6 +532,10 @@ type BillSubmissionFormProps = {
     onLookupPostalCode?: (postalCode: string) => Promise<BillSubmissionPostalPlace | null>;
     procedureOptions?: BillSubmissionProcedureOption[];
     modifierOptions?: BillSubmissionModifierOption[];
+    /** Auto hides and forces J4 for med-legal bills; treatment bills show the full report-type directory. */
+    attachmentReportTypeMode?: BillSubmissionAttachmentReportTypeMode;
+    attachmentReportTypes?: readonly BillSubmissionReportTypeOption[];
+    defaultAttachmentReportType?: string;
     appearance?: MindBillReactAppearance;
     className?: string;
     style?: CSSProperties;
@@ -504,15 +549,17 @@ type BillSubmissionFormProps = {
      */
     children?: ReactNode;
 };
-declare const BILL_SUBMISSION_REQUIRED_FIELDS: readonly ["patient.firstName", "patient.lastName", "patient.dateOfBirth", "patient.address.line1", "patient.address.city", "patient.address.state", "patient.address.postalCode", "claim.claimNumber", "claim.claimsAdministrator", "service.date", "diagnoses[]", "serviceLines[].code", "serviceLines[].units"];
+declare const BILL_SUBMISSION_REQUIRED_FIELDS: readonly ["patient.firstName", "patient.lastName", "patient.dateOfBirth", "patient.address.line1", "patient.address.city", "patient.address.state", "patient.address.postalCode", "claim.claimNumber", "claim.employer", "claim.dateOfInjury", "claim.claimsAdministrator", "service.date", "billingProvider.name", "billingProvider.taxId", "billingProvider.npi", "billingProvider.phone", "billingProvider.address.line1", "billingProvider.address.city", "billingProvider.address.state", "billingProvider.address.postalCode", "renderingProvider.name", "renderingProvider.npi", "renderingProvider.taxonomy", "serviceLocation.placeOfServiceCode", "serviceLocation.address.line1", "serviceLocation.address.city", "serviceLocation.address.state", "serviceLocation.address.postalCode", "diagnoses[]", "serviceLines[].code", "serviceLines[].units"];
 type BillSubmissionValidation = {
     valid: boolean;
     fieldErrors: Record<string, string>;
 };
-declare function prepareBillSubmissionDocuments({ attachments, selectedIds, uploads, fetch: fetchOverride, }: {
+declare function prepareBillSubmissionDocuments({ attachments, selectedIds, uploads, reportTypeCodeByAttachmentId, defaultReportTypeCode, fetch: fetchOverride, }: {
     attachments: BillSubmissionSourceAttachment[];
     selectedIds: string[];
     uploads: BillSubmissionUpload[];
+    reportTypeCodeByAttachmentId?: Record<string, string>;
+    defaultReportTypeCode?: string;
     fetch?: typeof globalThis.fetch;
 }): Promise<BrowserBillSubmissionDocument[]>;
 declare function ensureTrailingBillSubmissionLine(lines: BillSubmissionInput["serviceLines"]): BillSubmissionInput["serviceLines"];
@@ -523,6 +570,9 @@ declare const PSYCH_QME_DEFAULT_DIAGNOSIS = "Z04.6";
 /** Seed Psych QME's general examination code only when no diagnosis was supplied. */
 declare function applyBillSubmissionEvaluationDiagnoses(diagnoses: string[] | undefined, type: BillSubmissionEvaluationType): string[];
 declare function validateBillSubmission(bill: BillSubmissionInput): BillSubmissionValidation;
+declare function normalizeClaimsAdministratorName(value: string): string;
+declare function exactClaimsAdministratorMatch(results: BillReviewPayer$1[], suppliedName: string): BillReviewPayer$1 | undefined;
+declare function claimsAdministratorRecommendations(results: BillReviewPayer$1[], limit?: number): BillReviewPayer$1[];
 type BillSubmissionSectionId = "header" | "patient" | "claim" | "providers" | "serviceLines" | "attachments" | "actions";
 declare function BillSubmissionHeader(): ReactElement;
 declare function BillSubmissionPatientSection(): ReactElement;
@@ -531,7 +581,7 @@ declare function BillSubmissionProvidersSection(): ReactElement;
 declare function BillSubmissionServiceLinesSection(): ReactElement;
 declare function BillSubmissionAttachmentsSection(): ReactElement;
 declare function BillSubmissionActions(): ReactElement;
-declare function BillSubmissionForm({ initialBill, attachments, onSubmit, onSubmitted, getSession, sessionEndpoint, apiBaseUrl, fetch: fetchOverride, onSearchClaimsAdministrators, diagnosisOptions, onSearchDiagnoses, onLookupPostalCode, procedureOptions, modifierOptions, appearance, className, style, disabled, submitLabel, heading, description, children, }: BillSubmissionFormProps): ReactElement;
+declare function BillSubmissionForm({ initialBill, attachments, onSubmit, onSubmitted, getSession, sessionEndpoint, apiBaseUrl, fetch: fetchOverride, onSearchClaimsAdministrators, diagnosisOptions, onSearchDiagnoses, onLookupPostalCode, procedureOptions, modifierOptions, attachmentReportTypeMode, attachmentReportTypes, defaultAttachmentReportType, appearance, className, style, disabled, submitLabel, heading, description, children, }: BillSubmissionFormProps): ReactElement;
 
 /** Public-domain and MindBill-owned metadata. CPT descriptions are intentionally limited to the curated catalog. */
 declare const DEFAULT_BILL_SUBMISSION_PROCEDURES: BillSubmissionProcedureOption[];
@@ -793,4 +843,4 @@ type MindBillWidgetProps = {
 declare function MindBillBillTimeline(props: MindBillWidgetProps): ReactElement;
 declare function MindBillBillReview(props: MindBillWidgetProps): ReactElement;
 
-export { BILL_SUBMISSION_DIAGNOSIS_QUICK_PICKS, BILL_SUBMISSION_DOCUMENT_TYPES, BILL_SUBMISSION_REQUIRED_FIELDS, type BillActivityEvent, BillActivityTimeline, type BillActivityTimelineProps, type BillAgingBucket, type BillAgingBucketId, BillAgingSummary, type BillAgingSummaryProps, BillLifecycleActions, type BillLifecycleActionsProps, BillLifecycleProgress, type BillLifecycleProgressProps, type BillLifecycleStage, BillList, type BillListProps, BillPayerContactCard, type BillPayerContactCardProps, BillPaymentLedger, type BillPaymentLedgerProps, BillReadOnlyForm, type BillReadOnlyFormProps, BillRemittanceCard, type BillRemittanceCardProps, type BillReviewAttachment, type BillReviewBillingProvider, type BillReviewClinician, type BillReviewData, type BillReviewDocumentType, type BillReviewDraft, type BillReviewFeatures, BillReviewForm, type BillReviewFormProps, type BillReviewLineItem, type BillReviewLocation, type BillReviewPayer, type BillReviewSaveInput, BillSnapshotSummary, type BillSnapshotSummaryProps, type BillStatusAction, type BillStatusClient, type BillStatusClientOptions, type BillStatusData, type BillStatusSession, type BillStatusSessionProvider, type BillStatusSessionRequest, BillStatusSummary, type BillStatusSummaryProps, BillSubmissionActions, type BillSubmissionAddress, BillSubmissionAttachmentsSection, BillSubmissionClaimSection, type BillSubmissionDiagnosisOption, type BillSubmissionDocumentType, type BillSubmissionEvaluationType, BillSubmissionForm, type BillSubmissionFormProps, type BillSubmissionFormValue, BillSubmissionHeader, type BillSubmissionInput, type BillSubmissionModifierOption, BillSubmissionPatientSection, type BillSubmissionPostalPlace, type BillSubmissionProcedureOption, BillSubmissionProvidersSection, type BillSubmissionRoute, type BillSubmissionSectionId, BillSubmissionServiceLinesSection, type BillSubmissionSourceAttachment, type BillSubmissionUpload, type BillSubmissionValidation, type BillingComponentProps, BillingDashboard, type BillingDashboardBill, type BillingDashboardProps, type BillingDashboardSummary, BillingReport, type BillingReportDimension, type BillingReportProps, type BillingReportRow, ConnectedBillLifecycle, type ConnectedBillLifecycleProps, ConnectedBillStatus, type ConnectedBillStatusProps, DEFAULT_BILL_SUBMISSION_MODIFIERS, DEFAULT_BILL_SUBMISSION_PROCEDURES, MindBillBillReview, MindBillBillTimeline, type MindBillReactAppearance, type MindBillThemePreset, type MindBillWidgetProps, PSYCH_QME_DEFAULT_DIAGNOSIS, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, applyBillSubmissionEvaluationDiagnoses, applyBillSubmissionEvaluationModifiers, billActivityEventLabel, billAgingBucket, billAgingDays, billLifecycleDisplayLabel, billLifecycleStage, buildBillReviewSaveInput, buildBillingReportCsv, buildBillingReportRows, calculateBillSubmissionAllowedAmount, createBillStatusClient, ensureTrailingBillSubmissionLine, ensureTrailingProcedureLine, formatBillSubmissionDate, mindBillAppearanceStyle, mindBillThemePresets, parseBillSubmissionDate, prepareBillSubmissionDocuments, resolveMindBillAppearance, summarizeBillingDashboard, useBillLifecycle, useBillStatus, validateBillSubmission, visibleBillLifecycleActions };
+export { BILL_SUBMISSION_DIAGNOSIS_QUICK_PICKS, BILL_SUBMISSION_DOCUMENT_TYPES, BILL_SUBMISSION_REPORT_TYPES, BILL_SUBMISSION_REQUIRED_FIELDS, type BillActivityEvent, BillActivityTimeline, type BillActivityTimelineProps, type BillAgingBucket, type BillAgingBucketId, BillAgingSummary, type BillAgingSummaryProps, BillLifecycleActions, type BillLifecycleActionsProps, BillLifecycleProgress, type BillLifecycleProgressProps, type BillLifecycleStage, BillList, type BillListProps, BillPayerContactCard, type BillPayerContactCardProps, BillPaymentLedger, type BillPaymentLedgerProps, BillReadOnlyForm, type BillReadOnlyFormProps, BillRemittanceCard, type BillRemittanceCardProps, type BillReviewAttachment, type BillReviewBillingProvider, type BillReviewClinician, type BillReviewData, type BillReviewDocumentType, type BillReviewDraft, type BillReviewFeatures, BillReviewForm, type BillReviewFormProps, type BillReviewLineItem, type BillReviewLocation, type BillReviewPayer, type BillReviewSaveInput, BillSnapshotSummary, type BillSnapshotSummaryProps, type BillStatusAction, type BillStatusClient, type BillStatusClientOptions, type BillStatusData, type BillStatusSession, type BillStatusSessionProvider, type BillStatusSessionRequest, BillStatusSummary, type BillStatusSummaryProps, BillSubmissionActions, type BillSubmissionAddress, type BillSubmissionAttachmentReportTypeMode, BillSubmissionAttachmentsSection, BillSubmissionClaimSection, type BillSubmissionDiagnosisOption, type BillSubmissionDocumentType, type BillSubmissionEvaluationType, BillSubmissionForm, type BillSubmissionFormProps, type BillSubmissionFormValue, BillSubmissionHeader, type BillSubmissionInput, type BillSubmissionModifierOption, BillSubmissionPatientSection, type BillSubmissionPostalPlace, type BillSubmissionProcedureOption, BillSubmissionProvidersSection, type BillSubmissionReportTypeOption, type BillSubmissionRoute, type BillSubmissionSectionId, BillSubmissionServiceLinesSection, type BillSubmissionSourceAttachment, type BillSubmissionUpload, type BillSubmissionValidation, type BillingComponentProps, BillingDashboard, type BillingDashboardBill, type BillingDashboardProps, type BillingDashboardSummary, BillingReport, type BillingReportDimension, type BillingReportProps, type BillingReportRow, ConnectedBillLifecycle, type ConnectedBillLifecycleProps, ConnectedBillStatus, type ConnectedBillStatusProps, DEFAULT_BILL_SUBMISSION_MODIFIERS, DEFAULT_BILL_SUBMISSION_PROCEDURES, MED_LEGAL_REPORT_TYPE_CODE, MindBillBillReview, MindBillBillTimeline, type MindBillReactAppearance, type MindBillThemePreset, type MindBillWidgetProps, PSYCH_QME_DEFAULT_DIAGNOSIS, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, applyBillSubmissionEvaluationDiagnoses, applyBillSubmissionEvaluationModifiers, billActivityEventLabel, billAgingBucket, billAgingDays, billLifecycleDisplayLabel, billLifecycleStage, buildBillReviewSaveInput, buildBillingReportCsv, buildBillingReportRows, calculateBillSubmissionAllowedAmount, claimsAdministratorRecommendations, createBillStatusClient, ensureTrailingBillSubmissionLine, ensureTrailingProcedureLine, exactClaimsAdministratorMatch, formatBillSubmissionDate, mindBillAppearanceStyle, mindBillThemePresets, normalizeClaimsAdministratorName, parseBillSubmissionDate, prepareBillSubmissionDocuments, resolveMindBillAppearance, summarizeBillingDashboard, useBillLifecycle, useBillStatus, validateBillSubmission, visibleBillLifecycleActions };