@mindbill/react 0.18.0 → 0.20.0

package/README.md

@@ -8,7 +8,7 @@ npm install @mindbill/react @mindbill/node
 
 ## Connected lifecycle
 
-`ConnectedBillLifecycle` starts after your server atomically creates and submits an immutable bill. It owns bill loading, status refresh, EORs, payment posting, Second Bill Review, and close.
+`ConnectedBillLifecycle` starts after your server atomically creates and submits an immutable bill. It owns the submitted-to-closed progress rail, a read-only rendering of the exact submitted snapshot, server-owned human-readable history, packet download, EORs, payment posting, Second Bill Review, close, and reopen. The only persistent header action is **Download packet**; status-dependent actions appear in the details view when MindBill makes them available.
 
 ```tsx
 import { ConnectedBillLifecycle } from "@mindbill/react";
@@ -79,6 +79,20 @@ import { ConnectedBillStatus } from "@mindbill/react";
 
 Use `useBillStatus({ billId })` when you want to render custom status UI. It returns `data`, `error`, `isLoading`, `isRefreshing`, and `refresh`. Use `createBillStatusClient` outside React.
 
+The public lifecycle is `Submitted → Accepted → Processed → Closed`. Rejections and denials remain detailed states inside the Processed stage so the progress rail stays stable while the action sheet explains what the user can do next. Partner APIs and components do not expose draft or queued states.
+
+## Read-only bill details
+
+Use `BillReadOnlyForm` when you already loaded `BillLifecycleData` and only need the immutable detail surface. It uses the same section order and responsive layout as `BillSubmissionForm`, but renders values, calculated fees, and attachments without form controls.
+
+```tsx
+import { BillReadOnlyForm } from "@mindbill/react";
+
+<BillReadOnlyForm data={billLifecycleData} onOpenAttachment={openAttachment} />
+```
+
+`ConnectedBillLifecycle` composes this component with the Details / Bill history switch, so most partners should not assemble these pieces themselves.
+
 ## Lifecycle actions
 
 MindBill returns the actions that are valid for the bill's current state. Render that server-authoritative list instead of duplicating rejection, EOR, denial, review, payment, and closure rules in your application.
@@ -94,6 +108,7 @@ import { BillLifecycleActions } from "@mindbill/react";
       case "post_payment": return setPaymentOpen(true);
       case "second_review": return setSecondReviewOpen(true);
       case "close": return bill.closeBill({ reason: "Resolved" });
+      case "reopen": return bill.reopenBill({ reason: "Follow-up is continuing" });
     }
   }}
 />
@@ -103,15 +118,15 @@ Disabled actions are hidden by default. Set `showUnavailable` to show them with
 
 ## Activity timeline
 
-`BillActivityTimeline` renders ordered lifecycle events. Feed it events stored from MindBill's signed webhooks so a reload does not depend on browser callback history.
+`BillActivityTimeline` renders the ordered, human-readable lifecycle events returned by MindBill. Partners do not need to store or reconstruct bill history.
 
 ```tsx
 import { BillActivityTimeline } from "@mindbill/react";
 
-<BillActivityTimeline events={billEvents} />
+<BillActivityTimeline events={bill.data.activity} />
 ```
 
-Browser callbacks such as `onChanged` are for immediate UI, navigation, optimistic state, and analytics. Signed webhooks are the authoritative integration for durable server state.
+Browser callbacks such as `onChanged` are for immediate UI, navigation, optimistic state, and analytics. MindBill remains authoritative for durable history; signed webhooks are available when your backend also needs event-driven synchronization.
 
 ## Bill submission form
 
@@ -125,6 +140,10 @@ import { BillSubmissionForm } from "@mindbill/react";
 <BillSubmissionForm
   initialBill={bootstrap.bill}
   attachments={bootstrap.attachments}
+  getSession={() => fetch("/api/mindbill/session", { method: "POST" }).then(r => r.json())}
+  diagnosisOptions={bootstrap.diagnoses}
+  procedureOptions={bootstrap.procedures}
+  onLookupPostalCode={lookupPostalCode}
   appearance={{ preset: "qme-companion" }}
   onSubmit={({ bill, sourceAttachmentIds, uploads }) =>
     submitBill({ bill, sourceAttachmentIds, uploads })
@@ -132,6 +151,19 @@ import { BillSubmissionForm } from "@mindbill/react";
 />
 ```
 
+The component includes the interaction model, not just the markup:
+
+- a responsive two-column review form (one column on narrow screens);
+- paste-friendly `MM/DD/YYYY` date fields and required-field asterisks;
+- ZIP-to-city/state completion through `onLookupPostalCode`;
+- searchable ICD-10 multi-select with removable chips;
+- canonical claims-administrator search through the authenticated MindBill payer directory;
+- QME, AME, and Psych QME evaluation modes with medical-legal modifier defaults;
+- searchable procedure/modifier controls, fee-schedule amounts, totals, and an automatically maintained empty line;
+- auto-attached source documents, practice W-9 treatment, and click, panel-drop, or whole-page PDF upload.
+
+Partners supply tenant-specific bootstrap data and server callbacks. Required fields, validation, payer selection, service-line behavior, attachments, and submission UX stay inside `@mindbill/react`, so every integration receives the same billing workflow.
+
 `BILL_SUBMISSION_REQUIRED_FIELDS` and `validateBillSubmission` expose the same contract for tests and non-visual integrations. The component never creates a draft; its callback fires only when the user submits a locally valid snapshot.
 
 `BillReviewForm` remains available for legacy integrations that already own a custom review model. New integrations should use `BillSubmissionForm`.

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { MindBillAppearance, MindBillEventDetail, MindBillErrorDetail } from '@mindbill/embed';
 export { MindBillAppearance, MindBillErrorDetail, MindBillEventDetail } from '@mindbill/embed';
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { BillLifecycleAction, BillLifecycleDelivery, BillPaymentRecord, BillRemittanceSummary, BillLifecycleData, BillLifecycleClientOptions, BillLifecycleClient, BillEorDocument } from '@mindbill/browser';
-export { BillActivityRecord, BillEorDocument, BillLifecycleAction, BillLifecycleActionId, BillLifecycleClient, BillLifecycleClientOptions, BillLifecycleData, BillLifecycleDelivery, BillLifecycleSession, BillLifecycleSessionProvider, BillLifecycleSessionRequest, BillPaymentRecord, BillRemittanceSummary, CloseBillInput, PostBillPaymentInput, SubmitSecondReviewInput, createBillLifecycleClient } from '@mindbill/browser';
+import { BillReviewData as BillReviewData$1, BillReviewAttachment as BillReviewAttachment$1, BillLifecycleSessionProvider, BillReviewPayer as BillReviewPayer$1, BillLifecycleAction, BillLifecycleDelivery, BillPaymentRecord, BillRemittanceSummary, BillLifecycleData, BillLifecycleClientOptions, BillLifecycleClient, BillEorDocument } from '@mindbill/browser';
+export { BillActivityRecord, BillEorDocument, BillLifecycleAction, BillLifecycleActionId, BillLifecycleClient, BillLifecycleClientOptions, BillLifecycleData, BillLifecycleDelivery, BillLifecycleSession, BillLifecycleSessionProvider, BillLifecycleSessionRequest, BillPaymentRecord, BillRemittanceSummary, CloseBillInput, PostBillPaymentInput, ReopenBillInput, SubmitSecondReviewInput, createBillLifecycleClient } from '@mindbill/browser';
 
 type MindBillThemePreset = "mindbill" | "qme-companion" | "orange-bright" | "clinical-blue";
 type MindBillReactAppearance = MindBillAppearance & {
@@ -346,14 +346,41 @@ type BillStatusAction = {
 };
 declare function BillStatusSummary({ status, submittedAt, agingDays, updatedAt, totalCharge, totalPaid, balanceDue, actions, className, style, appearance }: BillStatusSummaryProps): ReactElement;
 
+type BillReadOnlyFormProps = {
+    data: BillReviewData$1;
+    appearance?: MindBillReactAppearance;
+    className?: string;
+    style?: CSSProperties;
+    onOpenAttachment?: (attachment: BillReviewAttachment$1) => void | Promise<void>;
+};
+declare function BillReadOnlyForm({ data, appearance, className, style, onOpenAttachment }: BillReadOnlyFormProps): ReactElement;
+
 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 BillSubmissionEvaluationType = "qme" | "ame" | "psych_qme";
 type BillSubmissionAddress = {
     line1: string;
     city: string;
     state: string;
     postalCode: string;
 };
+type BillSubmissionDiagnosisOption = {
+    code: string;
+    description: string;
+};
+type BillSubmissionProcedureOption = {
+    code: string;
+    description: string;
+    allowedAmount?: number;
+};
+type BillSubmissionModifierOption = {
+    code: string;
+    description: string;
+};
+type BillSubmissionPostalPlace = {
+    city: string;
+    state: string;
+};
 type BillSubmissionInput = {
     externalId?: string;
     billingMode?: "med_legal" | "professional";
@@ -363,7 +390,7 @@ type BillSubmissionInput = {
         firstName: string;
         middleName?: string;
         lastName: string;
-        dateOfBirth?: string;
+        dateOfBirth: string;
         ssn?: string;
         gender?: "M" | "F" | "X";
         phone?: string;
@@ -427,6 +454,10 @@ type BillSubmissionSourceAttachment = {
     documentType: BillSubmissionDocumentType;
     description?: string;
     selected?: boolean;
+    /** Auto-attached documents such as a practice W-9 cannot be deselected. */
+    autoAttached?: boolean;
+    removable?: boolean;
+    previewUrl?: string;
 };
 type BillSubmissionUpload = {
     file: File;
@@ -442,6 +473,17 @@ type BillSubmissionFormProps = {
     initialBill: BillSubmissionInput;
     attachments?: BillSubmissionSourceAttachment[];
     onSubmit: (value: BillSubmissionFormValue) => void | Promise<void>;
+    /** Short-lived partner browser session. Enables the built-in canonical payer directory. */
+    getSession?: BillLifecycleSessionProvider;
+    sessionEndpoint?: string;
+    apiBaseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    onSearchClaimsAdministrators?: (query: string, claimNumber?: string) => Promise<BillReviewPayer$1[]>;
+    diagnosisOptions?: BillSubmissionDiagnosisOption[];
+    onSearchDiagnoses?: (query: string) => Promise<BillSubmissionDiagnosisOption[]>;
+    onLookupPostalCode?: (postalCode: string) => Promise<BillSubmissionPostalPlace | null>;
+    procedureOptions?: BillSubmissionProcedureOption[];
+    modifierOptions?: BillSubmissionModifierOption[];
     appearance?: MindBillReactAppearance;
     className?: string;
     style?: CSSProperties;
@@ -450,13 +492,17 @@ type BillSubmissionFormProps = {
     heading?: ReactNode;
     description?: ReactNode;
 };
-declare const BILL_SUBMISSION_REQUIRED_FIELDS: readonly ["patient.firstName", "patient.lastName", "patient.address.line1", "patient.address.city", "patient.address.state", "patient.address.postalCode", "claim.claimNumber", "service.date", "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.claimsAdministrator", "service.date", "serviceLines[].code", "serviceLines[].units"];
 type BillSubmissionValidation = {
     valid: boolean;
     fieldErrors: Record<string, string>;
 };
+declare function ensureTrailingBillSubmissionLine(lines: BillSubmissionInput["serviceLines"]): BillSubmissionInput["serviceLines"];
+declare function parseBillSubmissionDate(value: string): string | undefined;
+declare function formatBillSubmissionDate(value: string | null | undefined): string;
+declare function applyBillSubmissionEvaluationModifiers(lines: BillSubmissionInput["serviceLines"], type: BillSubmissionEvaluationType): BillSubmissionInput["serviceLines"];
 declare function validateBillSubmission(bill: BillSubmissionInput): BillSubmissionValidation;
-declare function BillSubmissionForm({ initialBill, attachments, onSubmit, appearance, className, style, disabled, submitLabel, heading, description, }: BillSubmissionFormProps): ReactElement;
+declare function BillSubmissionForm({ initialBill, attachments, onSubmit, getSession, sessionEndpoint, apiBaseUrl, fetch: fetchOverride, onSearchClaimsAdministrators, diagnosisOptions, onSearchDiagnoses, onLookupPostalCode, procedureOptions, modifierOptions, appearance, className, style, disabled, submitLabel, heading, description, }: BillSubmissionFormProps): ReactElement;
 
 type BillStatusData = {
     billId: string;
@@ -551,7 +597,7 @@ type BillActivityTimelineProps = SurfaceProps & {
 /** Human-readable fallback for a signed partner event type. */
 declare function billActivityEventLabel(type: string): string;
 declare function BillActivityTimeline({ events, emptyLabel, appearance, className, style, formatDate }: BillActivityTimelineProps): ReactElement;
-type BillLifecycleStage = "created" | "submitted" | "accepted" | "response" | "follow_up" | "closed";
+type BillLifecycleStage = "submitted" | "accepted" | "processed" | "closed";
 /** Maps MindBill's detailed lifecycle state into a compact progress stage. */
 declare function billLifecycleStage(state: string): BillLifecycleStage;
 type BillLifecycleProgressProps = SurfaceProps & {
@@ -593,7 +639,9 @@ type UseBillLifecycleResult = {
     getDeliveryOptions: BillLifecycleClient["getDeliveryOptions"];
     openAttachment: (attachment: BillReviewAttachment) => Promise<void>;
     openEor: (document: BillEorDocument) => Promise<void>;
+    downloadPacket: () => Promise<void>;
     closeBill: BillLifecycleClient["closeBill"];
+    reopenBill: BillLifecycleClient["reopenBill"];
     postPayment: BillLifecycleClient["postPayment"];
     submitSecondReview: BillLifecycleClient["submitSecondReview"];
 };
@@ -620,4 +668,4 @@ type MindBillWidgetProps = {
 declare function MindBillBillTimeline(props: MindBillWidgetProps): ReactElement;
 declare function MindBillBillReview(props: MindBillWidgetProps): ReactElement;
 
-export { BILL_SUBMISSION_DOCUMENT_TYPES, BILL_SUBMISSION_REQUIRED_FIELDS, type BillActivityEvent, BillActivityTimeline, type BillActivityTimelineProps, BillLifecycleActions, type BillLifecycleActionsProps, BillLifecycleProgress, type BillLifecycleProgressProps, type BillLifecycleStage, BillPayerContactCard, type BillPayerContactCardProps, BillPaymentLedger, type BillPaymentLedgerProps, 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, type BillSubmissionAddress, type BillSubmissionDocumentType, BillSubmissionForm, type BillSubmissionFormProps, type BillSubmissionFormValue, type BillSubmissionInput, type BillSubmissionRoute, type BillSubmissionSourceAttachment, type BillSubmissionUpload, type BillSubmissionValidation, ConnectedBillLifecycle, type ConnectedBillLifecycleProps, ConnectedBillStatus, type ConnectedBillStatusProps, MindBillBillReview, MindBillBillTimeline, type MindBillReactAppearance, type MindBillThemePreset, type MindBillWidgetProps, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, billActivityEventLabel, billLifecycleStage, buildBillReviewSaveInput, createBillStatusClient, ensureTrailingProcedureLine, mindBillAppearanceStyle, mindBillThemePresets, resolveMindBillAppearance, useBillLifecycle, useBillStatus, validateBillSubmission, visibleBillLifecycleActions };
+export { BILL_SUBMISSION_DOCUMENT_TYPES, BILL_SUBMISSION_REQUIRED_FIELDS, type BillActivityEvent, BillActivityTimeline, type BillActivityTimelineProps, BillLifecycleActions, type BillLifecycleActionsProps, BillLifecycleProgress, type BillLifecycleProgressProps, type BillLifecycleStage, 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, type BillSubmissionAddress, type BillSubmissionDiagnosisOption, type BillSubmissionDocumentType, type BillSubmissionEvaluationType, BillSubmissionForm, type BillSubmissionFormProps, type BillSubmissionFormValue, type BillSubmissionInput, type BillSubmissionModifierOption, type BillSubmissionPostalPlace, type BillSubmissionProcedureOption, type BillSubmissionRoute, type BillSubmissionSourceAttachment, type BillSubmissionUpload, type BillSubmissionValidation, ConnectedBillLifecycle, type ConnectedBillLifecycleProps, ConnectedBillStatus, type ConnectedBillStatusProps, MindBillBillReview, MindBillBillTimeline, type MindBillReactAppearance, type MindBillThemePreset, type MindBillWidgetProps, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, applyBillSubmissionEvaluationModifiers, billActivityEventLabel, billLifecycleStage, buildBillReviewSaveInput, createBillStatusClient, ensureTrailingBillSubmissionLine, ensureTrailingProcedureLine, formatBillSubmissionDate, mindBillAppearanceStyle, mindBillThemePresets, parseBillSubmissionDate, resolveMindBillAppearance, useBillLifecycle, useBillStatus, validateBillSubmission, visibleBillLifecycleActions };