@mindbill/react 0.14.2 → 0.16.0

package/README.md

@@ -16,10 +16,10 @@ Procedure entry is keyboard-first: the form always keeps one empty row after the
 import { ConnectedBillLifecycle } from "@mindbill/react";
 
 <ConnectedBillLifecycle
-  billId={billId}
-  sessionEndpoint="/api/mindbill/billing-session"
+  create={knownBillValues}
+  sessionEndpoint="/api/mindbill/session"
   appearance={{ preset: "qme-companion" }}
-  onChanged={(lifecycle) => syncBillStatus(lifecycle.bill)}
+  onBillCreated={(billId) => navigate(`/bills/${billId}`)}
 />
 ```
 
@@ -41,21 +41,19 @@ Choose a complete preset, then override only the tokens your design system owns.
 
 Available presets are `mindbill`, `qme-companion`, `orange-bright`, and `clinical-blue`. Preset names describe visual styles rather than customer or partner brands. 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.
+Add one authenticated route to your app. It maps the signed-in user's role to billing permissions, then mints an exact-origin token for that user in your MindBill organization. The Partner API key stays on the server.
 
 ```ts
-// app/api/mindbill/billing-session/route.ts
+// Any server framework: POST /api/mindbill/session
 import { mindbill } from "@/lib/mindbill";
 
 export async function POST(request: Request) {
   const user = await requireUser(request); // your existing auth
-  const { billId } = await request.json();
-  await requireBillAccess(user, billId); // your existing authorization
 
   const session = await mindbill.createBrowserSession({
-    component: "bill-review",
-    billId,
+    subject: user.id,
     allowedOrigin: new URL(request.url).origin,
+    permissions: billingPermissionsFor(user.role),
     expiresIn: 900,
   });
 
@@ -68,24 +66,59 @@ 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.
 
-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.
+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
 
-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"`.
+Use `ConnectedBillStatus` when the partner page only needs a small status and aging surface. It reuses the same session route.
 
 ```tsx
 import { ConnectedBillStatus } from "@mindbill/react";
 
 <ConnectedBillStatus
   billId={billId}
-  sessionEndpoint="/api/mindbill/status-session"
+  sessionEndpoint="/api/mindbill/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.
 
+## 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.
+
+```tsx
+import { BillLifecycleActions } from "@mindbill/react";
+
+<BillLifecycleActions
+  actions={bill.data.lifecycle.actions}
+  onAction={(action) => {
+    switch (action.id) {
+      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" });
+    }
+  }}
+/>
+```
+
+Disabled actions are hidden by default. Set `showUnavailable` to show them with the reason returned by the API.
+
+## 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.
+
+```tsx
+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.
+
 ## Controlled escape hatch
 
 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.

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 { BillLifecycleClientOptions, BillLifecycleData, BillLifecycleClient, BillEorDocument } from '@mindbill/browser';
-export { BillEorDocument, BillLifecycleAction, BillLifecycleActionId, BillLifecycleClient, BillLifecycleClientOptions, BillLifecycleData, BillLifecycleSession, BillLifecycleSessionProvider, BillLifecycleSessionRequest, CloseBillInput, PostBillPaymentInput, SubmitSecondReviewInput, createBillLifecycleClient } from '@mindbill/browser';
+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';
 
 type MindBillThemePreset = "mindbill" | "qme-companion" | "orange-bright" | "clinical-blue";
 type MindBillReactAppearance = MindBillAppearance & {
@@ -361,13 +361,12 @@ type BillStatusSession = {
     apiBaseUrl?: string;
 };
 type BillStatusSessionRequest = {
-    billId: string;
     signal: AbortSignal;
 };
 type BillStatusSessionProvider = (request: BillStatusSessionRequest) => Promise<BillStatusSession>;
 type BillStatusClientOptions = {
     billId: string;
-    /** Same-origin route that mints a short-lived, bill-scoped browser session. */
+    /** Same-origin route that mints a short-lived organization/user browser session. */
     sessionEndpoint?: string;
     /** Advanced escape hatch for non-HTTP session exchange. */
     getSession?: BillStatusSessionProvider;
@@ -407,14 +406,50 @@ type ConnectedBillStatusProps = UseBillStatusOptions & {
 };
 declare function ConnectedBillStatus({ actions, appearance, className, style, loadingFallback, errorFallback, ...options }: ConnectedBillStatusProps): ReactElement | null;
 
+type BillLifecycleActionsProps = {
+    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[];
+declare function BillLifecycleActions({ actions, onAction, showUnavailable, disabled, appearance, className, style, }: BillLifecycleActionsProps): ReactElement | null;
+type BillActivityEvent = {
+    id: string;
+    type: string;
+    createdAt: string;
+    title?: string;
+    description?: string;
+    actor?: string;
+};
+type BillActivityTimelineProps = {
+    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;
+
 type UseBillLifecycleOptions = BillLifecycleClientOptions & {
+    /** Initial bill snapshot used when no existing `billId` is supplied. */
+    create?: BrowserBillCreateInput;
     refreshInterval?: number;
     enabled?: boolean;
     initialData?: BillLifecycleData | null;
-    onBillIdChange?: (billId: string, previousBillId: string) => void | Promise<void>;
+    onBillCreated?: (billId: string, data: BillLifecycleData) => void | Promise<void>;
+    onBillIdChange?: (billId: string, previousBillId: string | null) => void | Promise<void>;
 };
 type UseBillLifecycleResult = {
-    billId: string;
+    billId: string | null;
     data: BillLifecycleData | null;
     error: Error | null;
     isLoading: boolean;
@@ -434,7 +469,7 @@ type UseBillLifecycleResult = {
     submitSecondReview: BillLifecycleClient["submitSecondReview"];
     startCorrection: () => Promise<BillLifecycleData>;
 };
-declare function useBillLifecycle({ billId: providedBillId, sessionEndpoint, getSession, apiBaseUrl, refreshInterval, enabled, initialData, onBillIdChange, fetch: fetchOverride, }: UseBillLifecycleOptions): UseBillLifecycleResult;
+declare function useBillLifecycle({ billId: providedBillId, create, sessionEndpoint, getSession, apiBaseUrl, refreshInterval, enabled, initialData, onBillCreated, onBillIdChange, fetch: fetchOverride, }: UseBillLifecycleOptions): UseBillLifecycleResult;
 type ConnectedBillLifecycleProps = UseBillLifecycleOptions & {
     appearance?: MindBillReactAppearance;
     features?: BillReviewFeatures;
@@ -458,4 +493,4 @@ type MindBillWidgetProps = {
 declare function MindBillBillTimeline(props: MindBillWidgetProps): ReactElement;
 declare function MindBillBillReview(props: MindBillWidgetProps): ReactElement;
 
-export { 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, buildBillReviewSaveInput, createBillStatusClient, ensureTrailingProcedureLine, mindBillAppearanceStyle, mindBillThemePresets, resolveMindBillAppearance, useBillLifecycle, useBillStatus };
+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 };