@bloodgpt/widgets

Drop-in React widgets that render BloodGPT reports inside your own application.

Status — v0.1.0-alpha. Code-complete on feature/widgets-package: the backend endpoints (/api/v1/widget-sessions, /api/v1/widgets/...) and every widget below are implemented. Not yet published to npm and the branch isn't merged, so WIDGET_SESSION_SECRET must be set in the target environment before the API serves tokens.

Install

npm install @bloodgpt/widgets @tanstack/react-query next-intl

Peer dependencies:

• react ≥ 18
• react-dom ≥ 18
• @tanstack/react-query ≥ 5
• next-intl ≥ 4

Import the stylesheet once in your app entry (e.g. app/layout.tsx):

import "@bloodgpt/widgets/styles.css";

Authentication

The widgets never see your API key. Your backend mints short-lived session tokens scoped to a single patient:

// in your server (Next.js route handler, Express, etc.)
const res = await fetch("https://sandbox.bloodgpt.com/api/v1/widget-sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BLOODGPT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_patient_id: "your-patient-id",
    ttl_seconds: 900, // optional, default 900 (15 min)
  }),
});
const { session_token } = await res.json();

Hand session_token to the browser and pass it to the provider:

import { BloodGPTProvider, TestOverview } from "@bloodgpt/widgets";

export function PatientPage({ token, testId }: Props) {
  return (
    <BloodGPTProvider sessionToken={token}>
      <TestOverview testId={testId} />
    </BloodGPTProvider>
  );
}

Widgets

• <ReportsList externalPatientId> — the patient's reports, newest first
• <TestOverview testId> — patient demographics + scan metrics + narrative summary
• <TestParameters testId> — biomarker panels with filtering, sparklines, and per-parameter trend charts
• <TestFollowUps testId> — follow-up schedule + priority retests
• <TestReport testId> — composite of overview + parameters + follow-ups (the most common embed)

Each widget also exports a hook (useReports, useTestOverview, useTestParameters, useTestFollowUps, useTestTrends) for customers who want raw data plus their own rendering.

Trends

<TestParameters> renders value-over-time charts inline once a parameter has more than one measurement. For a standalone chart, pull the series with useTestTrends(testId, parameterName) and render it with your own chart or with TrendsChart from @repo/analysis-ui:

const { data } = useTestTrends(testId, "Hemoglobin");
// data?.trend is { parameterName, trend: { <ISO date>: number | null }, unit, ... }

Locales

English ships bundled. Pass additional messages via the messages prop on BloodGPTProvider:

import esMessages from "./bloodgpt-es.json";

<BloodGPTProvider
  sessionToken={token}
  locale="es"
  messages={esMessages}
>
  ...
</BloodGPTProvider>;

Internal notes

This package is built from the packages/analysis-ui view components and the public REST surface of apps/b2b-api. The adapter pattern is:

<Widget> = useQuery via the bundled HttpClient → render <View> from @repo/analysis-ui

The package ships its own ~50-line HttpClient rather than depending on a separate SDK — a standalone @bloodgpt/sdk is only worth extracting once a non-React client needs a typed API client without the widgets.

@repo/analysis-ui is bundled into the published artifact (via tsup noExternal) so customers don't need access to monorepo sources. Its chart renderer pulls in chart.js, which is bundled alongside it.