@mindbill/react 0.9.4 → 0.11.0

package/README.md

@@ -6,27 +6,43 @@ Native React billing components and connected lifecycle hooks. Install with:
 npm install @mindbill/react @mindbill/node
 ```
 
-## Connected status
+## Connected lifecycle
 
-`ConnectedBillStatus` owns the status API call, loading and error states, session renewal, one-minute polling, and focus refresh.
+`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.
 
 ```tsx
-import { ConnectedBillStatus } from "@mindbill/react";
+import { ConnectedBillLifecycle } from "@mindbill/react";
 
-<ConnectedBillStatus
+<ConnectedBillLifecycle
   billId={billId}
-  appearance={{ accentColor: "#32a9d6", textColor: "#203743" }}
-  actions={[
-    { id: "eor", label: "View EOR", onClick: openEor },
-    { id: "payment", label: "Post payment", onClick: postPayment, primary: true },
-  ]}
+  sessionEndpoint="/api/mindbill/billing-session"
+  appearance={{ preset: "qme-companion" }}
+  onChanged={(lifecycle) => syncBillStatus(lifecycle.bill)}
+/>
+```
+
+## Appearance
+
+Choose a complete preset, then override only the tokens your design system owns. The preset applies to review, payer search, attachments, submission, status, EOR, payment, denial, resubmission, and close states.
+
+```tsx
+<ConnectedBillLifecycle
+  billId={billId}
+  appearance={{
+    preset: "brighterway",
+    accentColor: "#ff4f0a",
+    fontFamily: "Inter, sans-serif",
+    borderRadius: "8px",
+  }}
 />
 ```
 
+Available presets are `mindbill`, `qme-companion`, and `brighterway`. Supported overrides include accent, accent text, background, surface, input background, text, muted text, border, font, panel radius, control radius, shadow, danger, success, and warning colors.
+
 Add one authenticated route to your app. It verifies that the signed-in user may access the bill, then mints an exact-origin, bill-scoped token. The Partner API key stays on the server.
 
 ```ts
-// app/api/mindbill/status-session/route.ts
+// app/api/mindbill/billing-session/route.ts
 import { mindbill } from "@/lib/mindbill";
 
 export async function POST(request: Request) {
@@ -34,8 +50,8 @@ export async function POST(request: Request) {
   const { billId } = await request.json();
   await requireBillAccess(user, billId); // your existing authorization
 
-  const session = await mindbill.createEmbedSession({
-    component: "bill-timeline",
+  const session = await mindbill.createBrowserSession({
+    component: "bill-review",
     billId,
     allowedOrigin: new URL(request.url).origin,
     expiresIn: 900,
@@ -48,22 +64,36 @@ export async function POST(request: Request) {
 }
 ```
 
-Use `useBillStatus({ billId })` when you want to render your own UI. It returns `data`, `error`, `isLoading`, `isRefreshing`, and `refresh`. Use `createBillStatusClient` outside React.
+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.
 
 This is the minimum safe browser integration. A permanent Partner API key must never enter frontend code. A completely serverless partner integration requires MindBill-hosted sign-in/SSO so MindBill can authenticate the end user itself.
 
-## Review and submit
+## Compact status
+
+Use `ConnectedBillStatus` when the partner page only needs a small status and aging surface. Add a second session route using the same server pattern and mint `component: "bill-timeline"`.
+
+```tsx
+import { ConnectedBillStatus } from "@mindbill/react";
+
+<ConnectedBillStatus
+  billId={billId}
+  sessionEndpoint="/api/mindbill/status-session"
+  appearance={{ preset: "qme-companion" }}
+/>
+```
+
+Use `useBillStatus({ billId })` when you want to render custom status UI. It returns `data`, `error`, `isLoading`, `isRefreshing`, and `refresh`. Use `createBillStatusClient` outside React.
 
-`BillReviewForm` is the native, controlled review surface. Known bill values and payer documents remain explicit and editable before submission.
+## Controlled escape hatch
 
-When you use `ConnectedBillLifecycle`, payer selection is batteries-included: the component searches MindBill's claims-administrator directory, sends the current claim number for pattern matching, explains name and claim-number evidence, shows delivery availability, and only preselects a high-confidence exact name or alias match. For a controlled `BillReviewForm`, provide the same behavior with `onSearchClaimsAdministrators={(query, claimNumber) => ...}`; return `BillReviewPayer` records with optional `confidence`, `recommended`, and `signals` fields.
+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.
 
 ```tsx
 import { BillReviewForm } from "@mindbill/react";
 
 <BillReviewForm
   data={billReview}
-  appearance={{ accentColor: "#32a9d6", textColor: "#203743" }}
+  appearance={{ preset: "qme-companion" }}
   onSave={(input) => api.patch("/billing/review", input)}
   onSubmit={(input, route) => api.post("/billing/submit", { input, route })}
   onAddAttachment={(file, documentType, description) =>
@@ -72,6 +102,9 @@ import { BillReviewForm } from "@mindbill/react";
   onRemoveAttachment={(attachmentId) =>
     api.delete(`/billing/attachments/${attachmentId}`)
   }
+  onSearchClaimsAdministrators={(query, claimNumber) =>
+    api.searchPayers({ query, claimNumber })
+  }
 />
 ```
 
@@ -92,6 +125,6 @@ Use `BillStatusSummary` only when your application already owns status loading a
 />
 ```
 
-`HostedBillReview` and `HostedBillTimeline` remain available when a hosted flow is a better fit. Native and hosted UI paths use the same bill ID.
+`MindBillBillReview` and `MindBillBillTimeline` are available when a hosted flow is a better fit. Native and hosted UI paths use the same bill ID.
 
 Never send a Partner API key or long-lived credential to React/browser code.

package/dist/index.d.ts

@@ -2,9 +2,75 @@ import { MindBillAppearance, MindBillEventDetail, MindBillErrorDetail } from '@m
 export { MindBillAppearance, MindBillErrorDetail, MindBillEventDetail } from '@mindbill/embed';
 import { CSSProperties, ReactElement, ReactNode } from 'react';
 
+type MindBillThemePreset = "mindbill" | "qme-companion" | "brighterway";
+type MindBillReactAppearance = MindBillAppearance & {
+    /** A complete starting point. Individual tokens below always win. */
+    preset?: MindBillThemePreset;
+    accentTextColor?: string;
+    inputBackgroundColor?: string;
+    controlRadius?: string;
+    shadow?: string;
+    dangerColor?: string;
+    successColor?: string;
+    warningColor?: string;
+};
+declare const mindBillThemePresets: {
+    readonly mindbill: {
+        readonly accentColor: "#238dbd";
+        readonly accentTextColor: "#ffffff";
+        readonly backgroundColor: "#f3f8fa";
+        readonly surfaceColor: "#ffffff";
+        readonly inputBackgroundColor: "#ffffff";
+        readonly textColor: "#203743";
+        readonly mutedColor: "#657982";
+        readonly borderColor: "#dbe6ea";
+        readonly borderRadius: "14px";
+        readonly controlRadius: "8px";
+        readonly shadow: "0 8px 24px rgba(28,58,72,.04)";
+        readonly dangerColor: "#b63d35";
+        readonly successColor: "#217449";
+        readonly warningColor: "#8a5c17";
+    };
+    readonly "qme-companion": {
+        readonly accentColor: "#53b5dc";
+        readonly accentTextColor: "#173542";
+        readonly backgroundColor: "#f2f8fb";
+        readonly surfaceColor: "#ffffff";
+        readonly inputBackgroundColor: "#ffffff";
+        readonly textColor: "#1d3440";
+        readonly mutedColor: "#617783";
+        readonly borderColor: "#d7e5eb";
+        readonly borderRadius: "12px";
+        readonly controlRadius: "8px";
+        readonly shadow: "0 1px 2px rgba(29,52,64,.05)";
+        readonly dangerColor: "#b83f3a";
+        readonly successColor: "#21835d";
+        readonly warningColor: "#9a6418";
+        readonly fontFamily: "Inter, ui-sans-serif, system-ui, sans-serif";
+    };
+    readonly brighterway: {
+        readonly accentColor: "#ff4f0a";
+        readonly accentTextColor: "#ffffff";
+        readonly backgroundColor: "#fffaf6";
+        readonly surfaceColor: "#ffffff";
+        readonly inputBackgroundColor: "#ffffff";
+        readonly textColor: "#111827";
+        readonly mutedColor: "#626a73";
+        readonly borderColor: "#e5e1dc";
+        readonly borderRadius: "8px";
+        readonly controlRadius: "6px";
+        readonly shadow: "0 4px 18px rgba(17,24,39,.06)";
+        readonly dangerColor: "#b42318";
+        readonly successColor: "#16794f";
+        readonly warningColor: "#9a5b13";
+        readonly fontFamily: "Inter, ui-sans-serif, system-ui, sans-serif";
+    };
+};
+declare function resolveMindBillAppearance(appearance: MindBillReactAppearance | undefined): MindBillReactAppearance;
+declare function mindBillAppearanceStyle(appearance: MindBillReactAppearance | undefined, style?: CSSProperties): CSSProperties;
+
 type BillReviewDocumentType = "final_report" | "letter_of_attestation" | "proof_of_service" | "form_122" | "return_to_work_voucher" | "w9" | "medical_records" | "appeal" | "other";
 type BillReviewBillingProvider = {
-    id?: string;
     name: string;
     taxId: string;
     npi: string;
@@ -16,7 +82,6 @@ type BillReviewBillingProvider = {
     billingZip?: string;
 };
 type BillReviewClinician = {
-    id?: string;
     name: string;
     specialty: string;
     npi: string;
@@ -31,8 +96,6 @@ type BillReviewClinician = {
     active?: boolean;
 };
 type BillReviewLocation = {
-    id?: string;
-    billingProviderId?: string;
     name: string;
     nickname?: string;
     street: string;
@@ -95,10 +158,7 @@ type BillReviewData = {
         transmissionState?: string;
         dos: string;
         dosEnd?: string | null;
-        placeOfServiceId?: string;
         authorizationNumber?: string | null;
-        billingProviderId?: string;
-        renderingProviderId?: string;
         billingSnapshot?: {
             billingProvider?: BillReviewBillingProvider;
             renderingProvider?: BillReviewClinician;
@@ -128,11 +188,6 @@ type BillReviewData = {
         claimsAdminName?: string;
         claimPatternStatus?: BillReviewClaimPatternStatus;
     };
-    options?: {
-        billingProviders?: BillReviewBillingProvider[];
-        renderingProviders?: BillReviewClinician[];
-        locations?: BillReviewLocation[];
-    };
 };
 type BillReviewSaveInput = {
     claimsAdminId: string;
@@ -153,12 +208,9 @@ type BillReviewSaveInput = {
     dos: string;
     dosEnd?: string | null;
     authorizationNumber?: string | null;
-    billingProviderId?: string;
-    billingProvider?: Omit<BillReviewBillingProvider, "id">;
-    renderingProviderId?: string;
-    renderingProvider?: Omit<BillReviewClinician, "id">;
-    placeOfServiceId?: string;
-    placeOfService?: Omit<BillReviewLocation, "id">;
+    billingProvider?: BillReviewBillingProvider;
+    renderingProvider?: BillReviewClinician;
+    placeOfService?: BillReviewLocation;
     lineItems: Array<{
         id?: string;
         code: string;
@@ -177,7 +229,7 @@ type BillReviewFormProps = {
     onSearchClaimsAdministrators?: (query: string, claimNumber?: string) => Promise<BillReviewPayer[]>;
     className?: string;
     style?: CSSProperties;
-    appearance?: MindBillAppearance;
+    appearance?: MindBillReactAppearance;
     features?: BillReviewFeatures;
     disabled?: boolean;
 };
@@ -215,7 +267,7 @@ type BillStatusSummaryProps = {
     actions?: BillStatusAction[];
     className?: string;
     style?: CSSProperties;
-    appearance?: MindBillAppearance;
+    appearance?: MindBillReactAppearance;
 };
 type BillStatusAction = {
     id: string;
@@ -404,7 +456,7 @@ type UseBillLifecycleResult = {
 declare function createBillLifecycleClient({ billId, sessionEndpoint, getSession, apiBaseUrl, fetch: fetchOverride, }: BillLifecycleClientOptions): BillLifecycleClient;
 declare function useBillLifecycle({ billId: providedBillId, sessionEndpoint, getSession, apiBaseUrl, refreshInterval, enabled, initialData, onBillIdChange, fetch: fetchOverride, }: UseBillLifecycleOptions): UseBillLifecycleResult;
 type ConnectedBillLifecycleProps = UseBillLifecycleOptions & {
-    appearance?: MindBillAppearance;
+    appearance?: MindBillReactAppearance;
     features?: BillReviewFeatures;
     className?: string;
     style?: CSSProperties;
@@ -425,13 +477,5 @@ type MindBillWidgetProps = {
 };
 declare function MindBillBillTimeline(props: MindBillWidgetProps): ReactElement;
 declare function MindBillBillReview(props: MindBillWidgetProps): ReactElement;
-declare function MindBillBillFromReport(props: MindBillWidgetProps): ReactElement;
-declare function MindBillCollections(props: MindBillWidgetProps): ReactElement;
-declare function MindBillOnboarding(props: MindBillWidgetProps): ReactElement;
-declare const HostedBillTimeline: typeof MindBillBillTimeline;
-declare const HostedBillReview: typeof MindBillBillReview;
-declare const HostedBillFromReport: typeof MindBillBillFromReport;
-declare const HostedCollections: typeof MindBillCollections;
-declare const HostedOnboarding: typeof MindBillOnboarding;
 
-export { type BillEorDocument, type BillLifecycleAction, type BillLifecycleActionId, type BillLifecycleClient, type BillLifecycleClientOptions, type BillLifecycleData, type BillLifecycleSession, type BillLifecycleSessionProvider, type BillLifecycleSessionRequest, 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, type CloseBillInput, ConnectedBillLifecycle, type ConnectedBillLifecycleProps, ConnectedBillStatus, type ConnectedBillStatusProps, HostedBillFromReport, HostedBillReview, HostedBillTimeline, HostedCollections, HostedOnboarding, MindBillBillFromReport, MindBillBillReview, MindBillBillTimeline, MindBillCollections, MindBillOnboarding, type MindBillWidgetProps, type PostBillPaymentInput, type SubmitSecondReviewInput, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, buildBillReviewSaveInput, createBillLifecycleClient, createBillStatusClient, useBillLifecycle, useBillStatus };
+export { type BillEorDocument, type BillLifecycleAction, type BillLifecycleActionId, type BillLifecycleClient, type BillLifecycleClientOptions, type BillLifecycleData, type BillLifecycleSession, type BillLifecycleSessionProvider, type BillLifecycleSessionRequest, 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, type CloseBillInput, ConnectedBillLifecycle, type ConnectedBillLifecycleProps, ConnectedBillStatus, type ConnectedBillStatusProps, MindBillBillReview, MindBillBillTimeline, type MindBillReactAppearance, type MindBillThemePreset, type MindBillWidgetProps, type PostBillPaymentInput, type SubmitSecondReviewInput, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, buildBillReviewSaveInput, createBillLifecycleClient, createBillStatusClient, mindBillAppearanceStyle, mindBillThemePresets, resolveMindBillAppearance, useBillLifecycle, useBillStatus };