@mindbill/react 0.22.0 → 0.23.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 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.
+`ConnectedBillLifecycle` starts after `BillSubmissionForm` atomically 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";
@@ -132,7 +132,7 @@ Browser callbacks such as `onChanged` are for immediate UI, navigation, optimist
 
 `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`.
 
-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.
+The partner application only loads initial values and mints a short-lived browser session. Uploaded files stay in the browser until the user submits; the component validates and sends the immutable snapshot and PDF bytes directly to MindBill.
 
 ```tsx
 import { BillSubmissionForm } from "@mindbill/react";
@@ -142,9 +142,7 @@ import { BillSubmissionForm } from "@mindbill/react";
   attachments={bootstrap.attachments}
   getSession={() => fetch("/api/mindbill/session", { method: "POST" }).then(r => r.json())}
   appearance={{ preset: "qme-companion" }}
-  onSubmit={({ bill, sourceAttachmentIds, uploads }) =>
-    submitBill({ bill, sourceAttachmentIds, uploads })
-  }
+  onSubmitted={({ billId }) => saveLocalBillLink(billId)}
 />
 ```
 
@@ -159,11 +157,11 @@ The component includes the interaction model, not just the markup:
 - 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.
 
-Partners supply tenant-specific bootstrap data, one short-lived browser session callback, and the final server submission callback. Required fields, validation, ZIP lookup, ICD-10 and payer directories, service-line behavior, 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.
+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.
 
-`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.
+`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

@@ -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 { 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';
+import { BillReviewData as BillReviewData$1, BillReviewAttachment as BillReviewAttachment$1, BrowserBillSubmissionResult, BillLifecycleSessionProvider, BillReviewPayer as BillReviewPayer$1, BrowserBillSubmissionDocument, 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, BrowserBillSubmissionResult, CloseBillInput, PostBillPaymentInput, ReopenBillInput, SubmitSecondReviewInput, createBillLifecycleClient } from '@mindbill/browser';
 
 type MindBillThemePreset = "mindbill" | "qme-companion" | "orange-bright" | "clinical-blue";
 type MindBillReactAppearance = MindBillAppearance & {
@@ -473,8 +473,14 @@ type BillSubmissionFormValue = {
 type BillSubmissionFormProps = {
     initialBill: BillSubmissionInput;
     attachments?: BillSubmissionSourceAttachment[];
-    onSubmit: (value: BillSubmissionFormValue) => void | Promise<void>;
-    /** Short-lived partner browser session. Enables the built-in canonical payer directory. */
+    /**
+     * Legacy custom submission escape hatch. Connected forms should omit this so
+     * the component owns PDF encoding and the Partner API wire contract.
+     */
+    onSubmit?: (value: BillSubmissionFormValue) => void | Promise<void>;
+    /** Called after the connected component atomically creates and submits the bill. */
+    onSubmitted?: (result: BrowserBillSubmissionResult) => void | Promise<void>;
+    /** Short-lived partner browser session. Enables reference data and direct submission. */
     getSession?: BillLifecycleSessionProvider;
     sessionEndpoint?: string;
     apiBaseUrl?: string;
@@ -503,6 +509,12 @@ type BillSubmissionValidation = {
     valid: boolean;
     fieldErrors: Record<string, string>;
 };
+declare function prepareBillSubmissionDocuments({ attachments, selectedIds, uploads, fetch: fetchOverride, }: {
+    attachments: BillSubmissionSourceAttachment[];
+    selectedIds: string[];
+    uploads: BillSubmissionUpload[];
+    fetch?: typeof globalThis.fetch;
+}): Promise<BrowserBillSubmissionDocument[]>;
 declare function ensureTrailingBillSubmissionLine(lines: BillSubmissionInput["serviceLines"]): BillSubmissionInput["serviceLines"];
 declare function parseBillSubmissionDate(value: string): string | undefined;
 declare function formatBillSubmissionDate(value: string | null | undefined): string;
@@ -516,7 +528,7 @@ declare function BillSubmissionProvidersSection(): ReactElement;
 declare function BillSubmissionServiceLinesSection(): ReactElement;
 declare function BillSubmissionAttachmentsSection(): ReactElement;
 declare function BillSubmissionActions(): 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, children, }: BillSubmissionFormProps): 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;
 
 /** Public-domain and MindBill-owned metadata. CPT descriptions are intentionally limited to the curated catalog. */
 declare const DEFAULT_BILL_SUBMISSION_PROCEDURES: BillSubmissionProcedureOption[];
@@ -778,4 +790,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, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, applyBillSubmissionEvaluationModifiers, billActivityEventLabel, billAgingBucket, billAgingDays, billLifecycleDisplayLabel, billLifecycleStage, buildBillReviewSaveInput, buildBillingReportCsv, buildBillingReportRows, calculateBillSubmissionAllowedAmount, createBillStatusClient, ensureTrailingBillSubmissionLine, ensureTrailingProcedureLine, formatBillSubmissionDate, mindBillAppearanceStyle, mindBillThemePresets, parseBillSubmissionDate, resolveMindBillAppearance, summarizeBillingDashboard, useBillLifecycle, useBillStatus, validateBillSubmission, visibleBillLifecycleActions };
+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, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, applyBillSubmissionEvaluationModifiers, billActivityEventLabel, billAgingBucket, billAgingDays, billLifecycleDisplayLabel, billLifecycleStage, buildBillReviewSaveInput, buildBillingReportCsv, buildBillingReportRows, calculateBillSubmissionAllowedAmount, createBillStatusClient, ensureTrailingBillSubmissionLine, ensureTrailingProcedureLine, formatBillSubmissionDate, mindBillAppearanceStyle, mindBillThemePresets, parseBillSubmissionDate, prepareBillSubmissionDocuments, resolveMindBillAppearance, summarizeBillingDashboard, useBillLifecycle, useBillStatus, validateBillSubmission, visibleBillLifecycleActions };

package/dist/index.js

@@ -1157,7 +1157,8 @@ var READ_ONLY_STYLES = `
 // src/bill-submission-form.tsx
 import { createContext, useCallback, useContext, useEffect as useEffect2, useMemo as useMemo2, useRef as useRef2, useState as useState2 } from "react";
 import {
-  createBillReferenceClient
+  createBillReferenceClient,
+  createBillSubmissionClient
 } from "@mindbill/browser";
 
 // src/billing-catalog.ts
@@ -1322,6 +1323,48 @@ var MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
 var MAX_DOCUMENTS = 25;
 var DIAGNOSIS_PAGE_SIZE = 100;
 var EMPTY_ATTACHMENTS = [];
+function bytesToBase64(bytes) {
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += 32768) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 32768));
+  }
+  return globalThis.btoa(binary);
+}
+async function pdfDocument(blob, input) {
+  if (blob.size > MAX_PDF_BYTES) throw new Error(`${input.filename} is larger than 25 MB.`);
+  const bytes = new Uint8Array(await blob.arrayBuffer());
+  if (bytes.length < 5 || bytes[0] !== 37 || bytes[1] !== 80 || bytes[2] !== 68 || bytes[3] !== 70 || bytes[4] !== 45) {
+    throw new Error(`${input.filename} is not a valid PDF.`);
+  }
+  return { ...input, contentBase64: bytesToBase64(bytes) };
+}
+async function prepareBillSubmissionDocuments({
+  attachments,
+  selectedIds,
+  uploads,
+  fetch: fetchOverride
+}) {
+  const fetcher = fetchOverride ?? globalThis.fetch;
+  if (typeof fetcher !== "function") throw new Error("A Fetch API implementation is required.");
+  const selected = selectedIds.map((id) => attachments.find((item) => item.id === id)).filter((item) => Boolean(item));
+  const sourceDocuments = await Promise.all(selected.map(async (attachment) => {
+    if (!attachment.previewUrl) throw new Error(`${attachment.fileName} cannot be submitted because its document URL is missing.`);
+    const response = await fetcher(attachment.previewUrl, { credentials: "same-origin" });
+    if (!response.ok) throw new Error(`${attachment.fileName} could not be loaded for submission.`);
+    return pdfDocument(await response.blob(), {
+      externalId: attachment.id,
+      filename: attachment.fileName,
+      documentType: attachment.documentType,
+      ...attachment.description ? { description: attachment.description } : {}
+    });
+  }));
+  const uploadedDocuments = await Promise.all(uploads.map(({ file, documentType, description }) => pdfDocument(file, {
+    filename: file.name,
+    documentType,
+    ...description ? { description } : {}
+  })));
+  return [...sourceDocuments, ...uploadedDocuments];
+}
 function previewUploadedPdf(file) {
   const url = URL.createObjectURL(file);
   window.open(url, "_blank", "noopener,noreferrer");
@@ -1559,6 +1602,7 @@ function BillSubmissionForm({
   initialBill,
   attachments = EMPTY_ATTACHMENTS,
   onSubmit,
+  onSubmitted,
   getSession,
   sessionEndpoint,
   apiBaseUrl,
@@ -1602,7 +1646,9 @@ function BillSubmissionForm({
   const procedures = useMemo2(() => mergeOptions(DEFAULT_BILL_SUBMISSION_PROCEDURES, procedureOptions), [procedureOptions]);
   const modifiers = useMemo2(() => mergeOptions(DEFAULT_BILL_SUBMISSION_MODIFIERS, modifierOptions), [modifierOptions]);
   const [evaluationType, setEvaluationType] = useState2(() => initialBill.renderingProvider?.isAme ? "ame" : initialBill.renderingProvider?.specialty?.toLowerCase().includes("psych") ? "psych_qme" : "qme");
-  const referenceClient = useMemo2(() => getSession ? createBillReferenceClient({ getSession, sessionEndpoint, apiBaseUrl, fetch: fetchOverride }) : null, [getSession, sessionEndpoint, apiBaseUrl, fetchOverride]);
+  const connected = !onSubmit;
+  const referenceClient = useMemo2(() => getSession || sessionEndpoint || connected ? createBillReferenceClient({ getSession, sessionEndpoint, apiBaseUrl, fetch: fetchOverride }) : null, [getSession, sessionEndpoint, apiBaseUrl, fetchOverride, connected]);
+  const submissionClient = useMemo2(() => connected ? createBillSubmissionClient({ getSession, sessionEndpoint, apiBaseUrl, fetch: fetchOverride }) : null, [getSession, sessionEndpoint, apiBaseUrl, fetchOverride, connected]);
   const locked = disabled || submitting;
   useEffect2(() => {
     setBill(cloneBill(initialBill));
@@ -1760,7 +1806,19 @@ function BillSubmissionForm({
     if (selectedIds.length + uploads.length > MAX_DOCUMENTS) return setFormError(`A bill can include at most ${MAX_DOCUMENTS} attachments.`);
     setSubmitting(true);
     try {
-      await onSubmit({ bill: clean, sourceAttachmentIds: selectedIds, uploads });
+      if (onSubmit) {
+        await onSubmit({ bill: clean, sourceAttachmentIds: selectedIds, uploads });
+      } else {
+        if (!submissionClient) throw new Error("The connected billing client is unavailable.");
+        const documents = await prepareBillSubmissionDocuments({
+          attachments,
+          selectedIds,
+          uploads,
+          ...fetchOverride ? { fetch: fetchOverride } : {}
+        });
+        const result = await submissionClient.submitBill({ bill: clean, documents });
+        await onSubmitted?.(result);
+      }
     } catch (caught) {
       setFormError(caught instanceof Error ? caught.message : "Unable to submit the bill.");
     } finally {
@@ -3225,6 +3283,7 @@ export {
   mindBillAppearanceStyle,
   mindBillThemePresets,
   parseBillSubmissionDate,
+  prepareBillSubmissionDocuments,
   resolveMindBillAppearance,
   summarizeBillingDashboard,
   useBillLifecycle,