@mindbill/react 0.7.0 → 0.9.0

package/README.md

@@ -1,10 +1,60 @@
 # @mindbill/react
 
-Native React billing components plus wrappers for MindBill's secure hosted workflows. See the repository's [10-minute quickstart](https://github.com/incidentfox/mindbill-widgets#add-mindbill-billing-in-10-minutes).
+Native React billing components and connected lifecycle hooks. Install with:
 
-Published on npm as [`@mindbill/react`](https://www.npmjs.com/package/@mindbill/react). Install it with `npm install @mindbill/react @mindbill/embed` or your preferred package manager.
+```bash
+npm install @mindbill/react @mindbill/node
+```
+
+## Connected status
+
+`ConnectedBillStatus` owns the status API call, loading and error states, session renewal, one-minute polling, and focus refresh.
+
+```tsx
+import { ConnectedBillStatus } from "@mindbill/react";
+
+<ConnectedBillStatus
+  billId={billId}
+  appearance={{ accentColor: "#32a9d6", textColor: "#203743" }}
+  actions={[
+    { id: "eor", label: "View EOR", onClick: openEor },
+    { id: "payment", label: "Post payment", onClick: postPayment, primary: true },
+  ]}
+/>
+```
+
+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
+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.createEmbedSession({
+    component: "bill-timeline",
+    billId,
+    allowedOrigin: new URL(request.url).origin,
+    expiresIn: 900,
+  });
+
+  return Response.json({
+    token: session.token,
+    expiresAt: session.expiresAt,
+  });
+}
+```
+
+Use `useBillStatus({ billId })` when you want to render your own UI. It returns `data`, `error`, `isLoading`, `isRefreshing`, and `refresh`. Use `createBillStatusClient` outside React.
+
+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
 
-Use `BillReviewForm` when billing should feel like part of your product. Your server loads and mutates the review model with a short-lived MindBill session; the component remains controlled and never receives a Partner API key.
+`BillReviewForm` is the native, controlled review surface. Known bill values and payer documents remain explicit and editable before submission.
 
 ```tsx
 import { BillReviewForm } from "@mindbill/react";
@@ -23,8 +73,7 @@ import { BillReviewForm } from "@mindbill/react";
 />
 ```
 
-Use `BillStatusSummary` for a compact lifecycle surface with age, last update, balance,
-and state-aware actions:
+Use `BillStatusSummary` only when your application already owns status loading and wants a presentation-only component:
 
 ```tsx
 <BillStatusSummary
@@ -41,7 +90,6 @@ and state-aware actions:
 />
 ```
 
-`HostedBillReview` and `HostedBillTimeline` remain available when an origin-bound hosted
-flow is a better fit. Native and hosted UI paths use the same server API and bill ID.
+`HostedBillReview` and `HostedBillTimeline` remain 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

@@ -1,6 +1,6 @@
 import { MindBillAppearance, MindBillEventDetail, MindBillErrorDetail } from '@mindbill/embed';
 export { MindBillAppearance, MindBillErrorDetail, MindBillEventDetail } from '@mindbill/embed';
-import { CSSProperties, ReactElement } from 'react';
+import { CSSProperties, ReactElement, ReactNode } from 'react';
 
 type BillReviewDocumentType = "final_report" | "letter_of_attestation" | "proof_of_service" | "form_122" | "return_to_work_voucher" | "w9" | "medical_records" | "appeal" | "other";
 type BillReviewBillingProvider = {
@@ -164,6 +164,188 @@ type BillStatusAction = {
 };
 declare function BillStatusSummary({ status, submittedAt, agingDays, updatedAt, totalCharge, totalPaid, balanceDue, actions, className, style, appearance }: BillStatusSummaryProps): ReactElement;
 
+type BillStatusData = {
+    billId: string;
+    state: string;
+    nativeStatus: string;
+    submittedAt: string | null;
+    agingDays: number | null;
+    updatedAt: string | null;
+    totalCharge: number;
+    totalPaid: number;
+    balanceDue: number;
+};
+type BillStatusSession = {
+    token: string;
+    expiresAt?: string;
+    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. */
+    sessionEndpoint?: string;
+    /** Advanced escape hatch for non-HTTP session exchange. */
+    getSession?: BillStatusSessionProvider;
+    apiBaseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+};
+type BillStatusClient = {
+    getStatus: (signal?: AbortSignal) => Promise<BillStatusData>;
+    clearSession: () => void;
+};
+type UseBillStatusOptions = BillStatusClientOptions & {
+    refreshInterval?: number;
+    enabled?: boolean;
+    initialData?: BillStatusData | null;
+};
+type UseBillStatusResult = {
+    data: BillStatusData | null;
+    error: Error | null;
+    isLoading: boolean;
+    isRefreshing: boolean;
+    refresh: () => Promise<void>;
+};
+/**
+ * Browser-safe status client used by useBillStatus. It exchanges the user's
+ * authenticated same-origin session for a short-lived MindBill token, then
+ * reads status directly from MindBill. It never accepts a Partner API key.
+ */
+declare function createBillStatusClient({ billId, sessionEndpoint, getSession, apiBaseUrl, fetch: fetchOverride, }: BillStatusClientOptions): BillStatusClient;
+declare function useBillStatus({ billId, sessionEndpoint, getSession, apiBaseUrl, refreshInterval, enabled, initialData, fetch: fetchOverride, }: UseBillStatusOptions): UseBillStatusResult;
+type ConnectedBillStatusProps = UseBillStatusOptions & {
+    actions?: BillStatusSummaryProps["actions"];
+    appearance?: BillStatusSummaryProps["appearance"];
+    className?: string;
+    style?: BillStatusSummaryProps["style"];
+    loadingFallback?: ReactNode;
+    errorFallback?: (error: Error, retry: () => Promise<void>) => ReactNode;
+};
+declare function ConnectedBillStatus({ actions, appearance, className, style, loadingFallback, errorFallback, ...options }: ConnectedBillStatusProps): ReactElement | null;
+
+type BillLifecycleActionId = "edit_and_submit" | "correct_and_resubmit" | "second_review" | "independent_bill_review" | "view_eor" | "post_payment" | "close";
+type BillLifecycleAction = {
+    id: BillLifecycleActionId;
+    label: string;
+    enabled: boolean;
+    primary?: boolean;
+    reason?: string;
+};
+type BillEorDocument = {
+    id: string;
+    filename: string;
+    description: string | null;
+    addedAt: string;
+    contentUrl: string;
+};
+type BillLifecycleData = BillReviewData & {
+    lifecycle: {
+        state: string;
+        nativeStatus: string;
+        actions: BillLifecycleAction[];
+    };
+    eors: BillEorDocument[];
+};
+type BillLifecycleSession = {
+    token: string;
+    expiresAt?: string;
+    apiBaseUrl?: string;
+};
+type BillLifecycleSessionRequest = {
+    billId: string;
+    component: "bill-review";
+    signal: AbortSignal;
+};
+type BillLifecycleSessionProvider = (request: BillLifecycleSessionRequest) => Promise<BillLifecycleSession>;
+type CloseBillInput = {
+    reason: string;
+};
+type PostBillPaymentInput = {
+    amount: number;
+    method: "check" | "eft";
+    checkNumber?: string;
+    depositDate: string;
+    note?: string;
+};
+type SubmitSecondReviewInput = {
+    reason: string;
+    payerClaimControlNumber: string;
+    disputedAmount: number | undefined;
+    attachmentIds: string[];
+    route: BillSubmissionRoute;
+};
+type BillLifecycleClientOptions = {
+    billId: string;
+    /** Same-origin server route that mints a short-lived, bill-scoped session. */
+    sessionEndpoint?: string | undefined;
+    /** Advanced escape hatch for a custom session exchange. */
+    getSession?: BillLifecycleSessionProvider | undefined;
+    apiBaseUrl?: string | undefined;
+    fetch?: typeof globalThis.fetch | undefined;
+};
+type BillLifecycleClient = {
+    getLifecycle: (signal?: AbortSignal) => Promise<BillLifecycleData>;
+    saveReview: (input: BillReviewSaveInput) => Promise<BillLifecycleData>;
+    submitBill: (input: BillReviewSaveInput, route: BillSubmissionRoute) => Promise<BillLifecycleData>;
+    addAttachment: (file: File, documentType: BillReviewDocumentType, description?: string) => Promise<BillLifecycleData>;
+    removeAttachment: (attachmentId: string) => Promise<BillLifecycleData>;
+    getAttachment: (attachmentId: string) => Promise<Blob>;
+    getEor: (documentId: string) => Promise<Blob>;
+    closeBill: (input: CloseBillInput) => Promise<BillLifecycleData>;
+    postPayment: (input: PostBillPaymentInput) => Promise<BillLifecycleData>;
+    submitSecondReview: (input: SubmitSecondReviewInput) => Promise<BillLifecycleData>;
+    startCorrection: () => Promise<{
+        replacementBillId: string;
+        data: BillLifecycleData;
+    }>;
+    clearSession: () => void;
+};
+type UseBillLifecycleOptions = BillLifecycleClientOptions & {
+    refreshInterval?: number;
+    enabled?: boolean;
+    initialData?: BillLifecycleData | null;
+    onBillIdChange?: (billId: string, previousBillId: string) => void | Promise<void>;
+};
+type UseBillLifecycleResult = {
+    billId: string;
+    data: BillLifecycleData | null;
+    error: Error | null;
+    isLoading: boolean;
+    isRefreshing: boolean;
+    isMutating: boolean;
+    refresh: () => Promise<void>;
+    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>;
+};
+/**
+ * Browser-safe client for the complete bill lifecycle. The only long-lived
+ * secret remains on the partner server; this client uses a short-lived,
+ * origin-bound session scoped to one bill.
+ */
+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;
+    className?: string;
+    style?: CSSProperties;
+    loadingFallback?: ReactNode;
+    errorFallback?: (error: Error, retry: () => Promise<void>) => ReactNode;
+    onChanged?: (data: BillLifecycleData) => void;
+};
+declare function ConnectedBillLifecycle({ appearance, className, style, loadingFallback, errorFallback, onChanged, ...options }: ConnectedBillLifecycleProps): ReactElement;
+
 type MindBillWidgetProps = {
     sessionToken: string;
     embedUrl: string;
@@ -184,4 +366,4 @@ declare const HostedBillFromReport: typeof MindBillBillFromReport;
 declare const HostedCollections: typeof MindBillCollections;
 declare const HostedOnboarding: typeof MindBillOnboarding;
 
-export { type BillReviewAttachment, type BillReviewBillingProvider, type BillReviewClinician, type BillReviewData, type BillReviewDocumentType, type BillReviewDraft, BillReviewForm, type BillReviewFormProps, type BillReviewLineItem, type BillReviewLocation, type BillReviewSaveInput, type BillStatusAction, BillStatusSummary, type BillStatusSummaryProps, type BillSubmissionRoute, HostedBillFromReport, HostedBillReview, HostedBillTimeline, HostedCollections, HostedOnboarding, MindBillBillFromReport, MindBillBillReview, MindBillBillTimeline, MindBillCollections, MindBillOnboarding, type MindBillWidgetProps, buildBillReviewSaveInput };
+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, BillReviewForm, type BillReviewFormProps, type BillReviewLineItem, type BillReviewLocation, 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 };