@mindbill/react 0.16.0 → 0.18.0

package/README.md

@@ -8,18 +8,15 @@ npm install @mindbill/react @mindbill/node
 
 ## Connected lifecycle
 
-`ConnectedBillLifecycle` is the default integration. It owns bill loading, payer lookup, editable review, attachments, submission, status refresh, EORs, payment posting, Second Bill Review, correction/resubmission, and close.
-
-Procedure entry is keyboard-first: the form always keeps one empty row after the entered lines, grows as soon as that row is partially filled, and omits the empty row from save and submit payloads.
+`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.
 
 ```tsx
 import { ConnectedBillLifecycle } from "@mindbill/react";
 
 <ConnectedBillLifecycle
-  create={knownBillValues}
+  billId={billId}
   sessionEndpoint="/api/mindbill/session"
   appearance={{ preset: "qme-companion" }}
-  onBillCreated={(billId) => navigate(`/bills/${billId}`)}
 />
 ```
 
@@ -64,8 +61,6 @@ export async function POST(request: Request) {
 }
 ```
 
-The component searches MindBill's claims-administrator directory with both payer text and the current claim number. It explains name and claim-pattern evidence, shows delivery availability, and only preselects a high-confidence exact name or alias match.
-
 The API key binds every session to one organization. `subject` identifies the user and `permissions` express the role. MindBill enforces the organization boundary on every bill request. A permanent Partner API key must never enter frontend code.
 
 ## Compact status
@@ -98,7 +93,6 @@ import { BillLifecycleActions } from "@mindbill/react";
       case "view_eor": return bill.openEor();
       case "post_payment": return setPaymentOpen(true);
       case "second_review": return setSecondReviewOpen(true);
-      case "correct_and_resubmit": return bill.startCorrection();
       case "close": return bill.closeBill({ reason: "Resolved" });
     }
   }}
@@ -117,32 +111,31 @@ import { BillActivityTimeline } from "@mindbill/react";
 <BillActivityTimeline events={billEvents} />
 ```
 
-Browser callbacks such as `onBillCreated`, `onBillIdChange`, and `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. Signed webhooks are the authoritative integration for durable server state.
+
+## Bill submission form
 
-## Controlled escape hatch
+`BillSubmissionForm` owns the complete pre-submission experience: the bill field schema, required-field rules and red asterisks, validation, service-line editing, source-document selection, PDF uploads, and the single Submit action. Its `bill` value is structurally identical to the server SDK's `CreateBillRequest`.
 
-Use `BillReviewForm` only when your application intentionally owns the API calls and local review state. Known bill values and payer documents remain explicit and editable.
+The partner application only loads initial values and sends the component's immutable snapshot to its authenticated server route. Uploaded files stay in the browser until the user submits.
 
 ```tsx
-import { BillReviewForm } from "@mindbill/react";
+import { BillSubmissionForm } from "@mindbill/react";
 
-<BillReviewForm
-  data={billReview}
+<BillSubmissionForm
+  initialBill={bootstrap.bill}
+  attachments={bootstrap.attachments}
   appearance={{ preset: "qme-companion" }}
-  onSave={(input) => api.patch("/billing/review", input)}
-  onSubmit={(input, route) => api.post("/billing/submit", { input, route })}
-  onAddAttachment={(file, documentType, description) =>
-    api.upload("/billing/attachments", { file, documentType, description })
-  }
-  onRemoveAttachment={(attachmentId) =>
-    api.delete(`/billing/attachments/${attachmentId}`)
-  }
-  onSearchClaimsAdministrators={(query, claimNumber) =>
-    api.searchPayers({ query, claimNumber })
+  onSubmit={({ bill, sourceAttachmentIds, uploads }) =>
+    submitBill({ bill, sourceAttachmentIds, uploads })
   }
 />
 ```
 
+`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`.
+
 Use `BillStatusSummary` only when your application already owns status loading and wants a presentation-only component:
 
 ```tsx

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, BillLifecycleClientOptions, BrowserBillCreateInput, BillLifecycleData, BillLifecycleClient, BillEorDocument } from '@mindbill/browser';
-export { BillEorDocument, BillLifecycleAction, BillLifecycleActionId, BillLifecycleClient, BillLifecycleClientOptions, BillLifecycleData, BillLifecycleSession, BillLifecycleSessionProvider, BillLifecycleSessionRequest, BrowserBillAddress, BrowserBillCreateInput, CloseBillInput, PostBillPaymentInput, SubmitSecondReviewInput, createBillLifecycleClient } from '@mindbill/browser';
+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';
 
 type MindBillThemePreset = "mindbill" | "qme-companion" | "orange-bright" | "clinical-blue";
 type MindBillReactAppearance = MindBillAppearance & {
@@ -273,7 +273,7 @@ type BillDeliveryOptions = {
         mailingAddress?: string | null;
     };
 };
-type BillSubmissionInput = {
+type BillSubmissionInput$1 = {
     route: BillSubmissionRoute;
     destination?: {
         faxNumber?: string;
@@ -286,9 +286,11 @@ type BillSubmissionInput = {
 };
 type BillReviewFormProps = {
     data: BillReviewData;
-    onSave: (input: BillReviewSaveInput) => Promise<BillReviewData | void>;
-    onSubmit: (input: BillReviewSaveInput, submission: BillSubmissionInput) => Promise<void>;
-    onGetDeliveryOptions: () => Promise<BillDeliveryOptions>;
+    mode?: "review" | "submission";
+    initialSubmission?: BillSubmissionInput$1;
+    onSave?: (input: BillReviewSaveInput) => Promise<BillReviewData | void>;
+    onSubmit: (input: BillReviewSaveInput, submission: BillSubmissionInput$1) => Promise<void>;
+    onGetDeliveryOptions?: () => Promise<BillDeliveryOptions>;
     onAddAttachment: (file: File, documentType: BillReviewDocumentType, description?: string) => Promise<void>;
     onRemoveAttachment: (attachmentId: string) => Promise<void>;
     onOpenAttachment?: (attachment: BillReviewAttachment) => void;
@@ -321,7 +323,7 @@ type BillReviewDraft = {
     lineItems: BillReviewLineItem[];
 };
 declare function buildBillReviewSaveInput(draft: BillReviewDraft): BillReviewSaveInput;
-declare function BillReviewForm({ data, onSave, onSubmit, onGetDeliveryOptions, onAddAttachment, onRemoveAttachment, onOpenAttachment, onSearchClaimsAdministrators, className, style, appearance, features, disabled, }: BillReviewFormProps): ReactElement;
+declare function BillReviewForm({ data, mode, initialSubmission, onSave, onSubmit, onGetDeliveryOptions, onAddAttachment, onRemoveAttachment, onOpenAttachment, onSearchClaimsAdministrators, className, style, appearance, features, disabled, }: BillReviewFormProps): ReactElement;
 type BillStatusSummaryProps = {
     status: string;
     submittedAt?: string | null;
@@ -344,6 +346,118 @@ type BillStatusAction = {
 };
 declare function BillStatusSummary({ status, submittedAt, agingDays, updatedAt, totalCharge, totalPaid, balanceDue, actions, className, style, appearance }: BillStatusSummaryProps): 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 BillSubmissionAddress = {
+    line1: string;
+    city: string;
+    state: string;
+    postalCode: string;
+};
+type BillSubmissionInput = {
+    externalId?: string;
+    billingMode?: "med_legal" | "professional";
+    patient: {
+        id?: string;
+        externalId?: string;
+        firstName: string;
+        middleName?: string;
+        lastName: string;
+        dateOfBirth?: string;
+        ssn?: string;
+        gender?: "M" | "F" | "X";
+        phone?: string;
+        address: BillSubmissionAddress;
+    };
+    claim: {
+        id?: string;
+        externalId?: string;
+        claimNumber: string;
+        adjNumber?: string;
+        employer?: string;
+        dateOfInjury?: string;
+        injuryState?: string;
+        description?: string;
+        claimsAdministrator?: {
+            id?: string;
+            name: string;
+        };
+    };
+    service: {
+        date: string;
+        endDate?: string | null;
+        authorizationNumber?: string | null;
+    };
+    billingProvider?: {
+        name?: string;
+        taxId?: string;
+        npi?: string;
+        phone?: string;
+        address?: BillSubmissionAddress;
+    };
+    renderingProvider?: {
+        name?: string;
+        specialty?: string;
+        npi?: string;
+        taxonomy?: string;
+        licenseNumber?: string;
+        licenseState?: string;
+        isQme?: boolean;
+        isAme?: boolean;
+    };
+    serviceLocation?: {
+        name?: string;
+        address?: BillSubmissionAddress;
+        placeOfServiceCode?: string;
+    };
+    diagnoses?: string[];
+    serviceLines: Array<{
+        code: string;
+        modifiers?: string[];
+        units?: number;
+        serviceDate?: string;
+        serviceDateEnd?: string | null;
+        charge?: number;
+        diagnosisPointers?: number[];
+    }>;
+};
+type BillSubmissionSourceAttachment = {
+    id: string;
+    fileName: string;
+    documentType: BillSubmissionDocumentType;
+    description?: string;
+    selected?: boolean;
+};
+type BillSubmissionUpload = {
+    file: File;
+    documentType: BillSubmissionDocumentType;
+    description?: string;
+};
+type BillSubmissionFormValue = {
+    bill: BillSubmissionInput;
+    sourceAttachmentIds: string[];
+    uploads: BillSubmissionUpload[];
+};
+type BillSubmissionFormProps = {
+    initialBill: BillSubmissionInput;
+    attachments?: BillSubmissionSourceAttachment[];
+    onSubmit: (value: BillSubmissionFormValue) => void | Promise<void>;
+    appearance?: MindBillReactAppearance;
+    className?: string;
+    style?: CSSProperties;
+    disabled?: boolean;
+    submitLabel?: string;
+    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"];
+type BillSubmissionValidation = {
+    valid: boolean;
+    fieldErrors: Record<string, string>;
+};
+declare function validateBillSubmission(bill: BillSubmissionInput): BillSubmissionValidation;
+declare function BillSubmissionForm({ initialBill, attachments, onSubmit, appearance, className, style, disabled, submitLabel, heading, description, }: BillSubmissionFormProps): ReactElement;
+
 type BillStatusData = {
     billId: string;
     state: string;
@@ -406,15 +520,17 @@ type ConnectedBillStatusProps = UseBillStatusOptions & {
 };
 declare function ConnectedBillStatus({ actions, appearance, className, style, loadingFallback, errorFallback, ...options }: ConnectedBillStatusProps): ReactElement | null;
 
-type BillLifecycleActionsProps = {
+type SurfaceProps = {
+    appearance?: MindBillReactAppearance;
+    className?: string;
+    style?: CSSProperties;
+};
+type BillLifecycleActionsProps = SurfaceProps & {
     actions: readonly BillLifecycleAction[];
     onAction: (action: BillLifecycleAction) => void;
     /** Show disabled actions and the server-provided reason. Defaults to false. */
     showUnavailable?: boolean;
     disabled?: boolean;
-    appearance?: MindBillReactAppearance;
-    className?: string;
-    style?: CSSProperties;
 };
 /** Returns the server-authoritative actions that should be rendered. */
 declare function visibleBillLifecycleActions(actions: readonly BillLifecycleAction[], showUnavailable?: boolean): BillLifecycleAction[];
@@ -425,31 +541,48 @@ type BillActivityEvent = {
     createdAt: string;
     title?: string;
     description?: string;
-    actor?: string;
+    actor?: string | null;
 };
-type BillActivityTimelineProps = {
+type BillActivityTimelineProps = SurfaceProps & {
     events: readonly BillActivityEvent[];
     emptyLabel?: string;
-    appearance?: MindBillReactAppearance;
-    className?: string;
-    style?: CSSProperties;
     formatDate?: (createdAt: string) => string;
 };
 /** 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;
+declare function BillActivityTimeline({ events, emptyLabel, appearance, className, style, formatDate }: BillActivityTimelineProps): ReactElement;
+type BillLifecycleStage = "created" | "submitted" | "accepted" | "response" | "follow_up" | "closed";
+/** Maps MindBill's detailed lifecycle state into a compact progress stage. */
+declare function billLifecycleStage(state: string): BillLifecycleStage;
+type BillLifecycleProgressProps = SurfaceProps & {
+    state: string;
+    nativeStatus?: string;
+    submittedAt?: string | null;
+    agingDays?: number | null;
+};
+declare function BillLifecycleProgress({ state, nativeStatus, submittedAt, agingDays, appearance, className, style }: BillLifecycleProgressProps): ReactElement;
+type BillSnapshotSummaryProps = SurfaceProps & Pick<BillLifecycleData, "bill" | "patient" | "injury" | "delivery">;
+declare function BillSnapshotSummary({ bill, patient, injury, delivery, appearance, className, style }: BillSnapshotSummaryProps): ReactElement;
+type BillRemittanceCardProps = SurfaceProps & {
+    remittance: BillRemittanceSummary;
+};
+declare function BillRemittanceCard({ remittance, appearance, className, style }: BillRemittanceCardProps): ReactElement;
+type BillPayerContactCardProps = SurfaceProps & {
+    delivery: BillLifecycleDelivery;
+};
+declare function BillPayerContactCard({ delivery, appearance, className, style }: BillPayerContactCardProps): ReactElement | null;
+type BillPaymentLedgerProps = SurfaceProps & {
+    payments: readonly BillPaymentRecord[];
+};
+declare function BillPaymentLedger({ payments, appearance, className, style }: BillPaymentLedgerProps): ReactElement;
 
 type UseBillLifecycleOptions = BillLifecycleClientOptions & {
-    /** Initial bill snapshot used when no existing `billId` is supplied. */
-    create?: BrowserBillCreateInput;
     refreshInterval?: number;
     enabled?: boolean;
     initialData?: BillLifecycleData | null;
-    onBillCreated?: (billId: string, data: BillLifecycleData) => void | Promise<void>;
-    onBillIdChange?: (billId: string, previousBillId: string | null) => void | Promise<void>;
 };
 type UseBillLifecycleResult = {
-    billId: string | null;
+    billId: string;
     data: BillLifecycleData | null;
     error: Error | null;
     isLoading: boolean;
@@ -458,28 +591,22 @@ type UseBillLifecycleResult = {
     refresh: () => Promise<void>;
     searchClaimsAdministrators: BillLifecycleClient["searchClaimsAdministrators"];
     getDeliveryOptions: BillLifecycleClient["getDeliveryOptions"];
-    saveReview: BillLifecycleClient["saveReview"];
-    submitBill: BillLifecycleClient["submitBill"];
-    addAttachment: BillLifecycleClient["addAttachment"];
-    removeAttachment: BillLifecycleClient["removeAttachment"];
     openAttachment: (attachment: BillReviewAttachment) => Promise<void>;
     openEor: (document: BillEorDocument) => Promise<void>;
     closeBill: BillLifecycleClient["closeBill"];
     postPayment: BillLifecycleClient["postPayment"];
     submitSecondReview: BillLifecycleClient["submitSecondReview"];
-    startCorrection: () => Promise<BillLifecycleData>;
 };
-declare function useBillLifecycle({ billId: providedBillId, create, sessionEndpoint, getSession, apiBaseUrl, refreshInterval, enabled, initialData, onBillCreated, onBillIdChange, fetch: fetchOverride, }: UseBillLifecycleOptions): UseBillLifecycleResult;
+declare function useBillLifecycle({ billId: providedBillId, sessionEndpoint, getSession, apiBaseUrl, refreshInterval, enabled, initialData, fetch: fetchOverride, }: UseBillLifecycleOptions): UseBillLifecycleResult;
 type ConnectedBillLifecycleProps = UseBillLifecycleOptions & {
     appearance?: MindBillReactAppearance;
-    features?: BillReviewFeatures;
     className?: string;
     style?: CSSProperties;
     loadingFallback?: ReactNode;
     errorFallback?: (error: Error, retry: () => Promise<void>) => ReactNode;
     onChanged?: (data: BillLifecycleData) => void;
 };
-declare function ConnectedBillLifecycle({ appearance, features, className, style, loadingFallback, errorFallback, onChanged, ...options }: ConnectedBillLifecycleProps): ReactElement;
+declare function ConnectedBillLifecycle({ appearance, className, style, loadingFallback, errorFallback, onChanged, ...options }: ConnectedBillLifecycleProps): ReactElement;
 
 type MindBillWidgetProps = {
     sessionToken: string;
@@ -493,4 +620,4 @@ type MindBillWidgetProps = {
 declare function MindBillBillTimeline(props: MindBillWidgetProps): ReactElement;
 declare function MindBillBillReview(props: MindBillWidgetProps): ReactElement;
 
-export { type BillActivityEvent, BillActivityTimeline, type BillActivityTimelineProps, BillLifecycleActions, type BillLifecycleActionsProps, 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, type BillStatusAction, type BillStatusClient, type BillStatusClientOptions, type BillStatusData, type BillStatusSession, type BillStatusSessionProvider, type BillStatusSessionRequest, BillStatusSummary, type BillStatusSummaryProps, type BillSubmissionRoute, ConnectedBillLifecycle, type ConnectedBillLifecycleProps, ConnectedBillStatus, type ConnectedBillStatusProps, MindBillBillReview, MindBillBillTimeline, type MindBillReactAppearance, type MindBillThemePreset, type MindBillWidgetProps, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, billActivityEventLabel, buildBillReviewSaveInput, createBillStatusClient, ensureTrailingProcedureLine, mindBillAppearanceStyle, mindBillThemePresets, resolveMindBillAppearance, useBillLifecycle, useBillStatus, 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, 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 };