@patientos/website-kit 0.2.6 → 0.2.8

package/README.md

@@ -39,10 +39,15 @@ bearer; deployed sites continue to use host-only patient cookies.
 
 ## Store, cart and checkout
 
-Use the runtime implementations in an ordinary hydrated React site:
+Use the runtime implementations in an ordinary hydrated React site. Import each surface
+from its OWN subpath — the `islands-impl` barrel pulls the payment stack (BPOINT, the
+address picker, Medicare) into every page that touches it:
 
 ```tsx
-import { StoreClient, CartClient, CheckoutClient } from '@patientos/website-kit/islands-impl'
+import { StoreClient } from '@patientos/website-kit/islands-impl/store'
+import { CartClient } from '@patientos/website-kit/islands-impl/cart'
+import { CartButtonClient } from '@patientos/website-kit/islands-impl/cart-button'
+import { CheckoutClient } from '@patientos/website-kit/islands-impl/checkout'
 import '@patientos/website-kit/website-kit.css'
 
 const storeApiOrigin = 'https://my.example-clinic.com'
@@ -59,6 +64,53 @@ const storeApiOrigin = 'https://my.example-clinic.com'
 Use `productHandle` for one exact product or `categoryHandle` for a category-filtered
 catalogue; an exact product takes precedence when both are supplied.
 
+### Server-rendering the shop
+
+Fetch the catalogue in your own **per-request** route loader and pass it as
+`initialCatalog`. The grid then renders on the server — real product markup for a crawler
+and no loading swap — and the island still refreshes in the background, so prices stay
+honest. Never bake a catalogue into a statically built artifact.
+
+```tsx
+import { createStoreClient, fetchStoreCatalog } from '@patientos/website-kit'
+import type { StoreCatalog } from '@patientos/website-kit'
+
+// in the route loader (runs per request, on the server)
+const catalog = await fetchStoreCatalog(createStoreClient({ apiOrigin: storeApiOrigin }))
+
+// in the component
+<StoreClient storeApiOrigin={storeApiOrigin} initialCatalog={catalog} hideCartLink />
+```
+
+`fetchStoreCatalog` returns `null` on any failure, and `StoreClient` then falls back to
+its own client fetch. Pass `hideCartLink` when your site has its own header cart.
+
+### The header cart
+
+`<CartButtonClient/>` is a count badge that opens a cart drawer. It costs **no requests**:
+the count comes from the cart already in the shopper's browser, and the drawer quotes
+`POST /api/store/quote` only when opened. The badge is absent (never `0`) until the client
+effect runs, so it adds nothing to server-rendered HTML and your header stays cacheable.
+
+```tsx
+<CartButtonClient
+  storeApiOrigin={storeApiOrigin}
+  label="Cart"
+  cartHref="/cart"
+  checkoutHref="/checkout"
+/>
+```
+
+To build your own affordance instead, import the cart module directly:
+
+```ts
+import { cartItemCount, readCart, subscribeToCart } from '@patientos/website-kit/cart-storage'
+```
+
+It is browser-only by design (`readCart()` answers empty on the server) and is shared by
+every surface in one page, so a store block adding an item updates your badge with no
+shared React tree.
+
 Omit `storeApiOrigin` when PatientOS serves the clinic website and store on one origin.
 For a separately deployed site it must be the clinic's verified patient/API origin, and
 the site Origin must be registered on that clinic's active web-form channel. The client

package/dist/booking-block-D-UOAPx3.d.ts

@@ -0,0 +1,74 @@
+import * as React from 'react';
+
+/** A service as the funnel offers it. */
+interface FunnelServiceOption {
+    key: string;
+    label: string;
+}
+/** How the runtime half reaches the API — the snapshot's `publicApi`, serialised. */
+interface FunnelPublicApi {
+    publishableKey: string;
+    apiBase: string;
+    turnstileSiteKey?: string;
+    portalUrl?: string;
+    portalOrigin?: string;
+    portalApiOrigin?: string;
+}
+/** JSON-safe island configuration. Crosses the build→runtime boundary — see `./islands`. */
+type CertificateFunnelProps = {
+    /** Start on ONE service, skipping the picker. */
+    serviceKey?: string;
+    /** Heading above the funnel. */
+    heading?: string;
+    publicApi?: FunnelPublicApi;
+    services?: FunnelServiceOption[];
+    clinicName?: string;
+    clinicPhone?: string;
+};
+/** Marker-only props: what a clinic page actually writes. */
+type CertificateFunnelMarkerProps = {
+    /**
+     * Offer only these services, in this order. Omitted ⇒ every certificate service the
+     * clinic has published.
+     */
+    serviceKeys?: string[];
+    /** Start on ONE service, skipping the picker. */
+    serviceKey?: string;
+    /** Per-service copy overriding the configured label, keyed by service key. */
+    serviceCopy?: Record<string, string>;
+    heading?: string;
+    className?: string;
+};
+declare function CertificateFunnel({ serviceKeys, serviceKey, serviceCopy, heading, className, }: CertificateFunnelMarkerProps): React.ReactElement;
+
+/** An appointment type as the block offers it. */
+interface BookingTypeOption {
+    id: string;
+    label: string;
+    durationMinutes: number;
+    modality: 'in_person' | 'telehealth';
+}
+/** JSON-safe island configuration. Crosses the build→runtime boundary — see `./islands`. */
+type BookingBlockProps = {
+    /** Pre-select ONE appointment type, skipping the picker. */
+    appointmentTypeId?: string;
+    /** Pre-select a practitioner (availability is then filtered to them). */
+    practitionerId?: string;
+    heading?: string;
+    publicApi?: FunnelPublicApi;
+    appointmentTypes?: BookingTypeOption[];
+    clinicName?: string;
+    clinicPhone?: string;
+};
+/** Marker-only props: what a clinic page actually writes. */
+type BookingBlockMarkerProps = {
+    appointmentTypeId?: string;
+    practitionerId?: string;
+    /** Offer only these appointment types, by id, in this order. */
+    appointmentTypeIds?: string[];
+    heading?: string;
+    className?: string;
+};
+declare function BookingBlock({ appointmentTypeId, practitionerId, appointmentTypeIds, heading, className, }: BookingBlockMarkerProps): React.ReactElement;
+
+export { BookingBlock as B, CertificateFunnel as C, type FunnelPublicApi as F, type BookingBlockMarkerProps as a, type BookingBlockProps as b, type BookingTypeOption as c, type CertificateFunnelMarkerProps as d, type CertificateFunnelProps as e, type FunnelServiceOption as f };

package/dist/cart-block-B-ytc9us.d.ts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+
+/** JSON-safe island configuration. Crosses the build→runtime boundary — see `./islands`. */
+type CartProps = {
+    /** PatientOS patient/API origin. Omitted keeps the original same-origin contract. */
+    storeApiOrigin?: string;
+};
+/** Marker-only props: runtime config plus presentation the page controls. */
+type CartMarkerProps = CartProps & {
+    className?: string;
+};
+/**
+ * BUILD-TIME marker. Emits the mount point plus a static no-JS fallback.
+ *
+ * The fallback shows NO line items — the static artifact is served to every visitor and
+ * is edge-cacheable, so it must never carry a patient's cart.
+ */
+declare function Cart({ storeApiOrigin, className }: CartMarkerProps): React.ReactElement;
+
+export { Cart as C, type CartMarkerProps as a, type CartProps as b };

package/dist/cart-button-BCLFittB.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+/** JSON-safe island configuration. Crosses the build→runtime boundary — see `./islands`. */
+type CartButtonProps = {
+    /** PatientOS patient/API origin. Omitted keeps the original same-origin contract. */
+    storeApiOrigin?: string;
+    /** Accessible label for the button. Defaults to "Cart". */
+    label?: string;
+    /** Where "View cart" and the no-JS fallback link point. Defaults to `/cart`. */
+    cartHref?: string;
+    /** Where the drawer's checkout action points. Defaults to `/checkout`. */
+    checkoutHref?: string;
+};
+/** Marker-only props: runtime config plus presentation the page controls. */
+type CartButtonMarkerProps = CartButtonProps & {
+    className?: string;
+};
+/**
+ * BUILD-TIME marker. The no-JS fallback is a plain link to the cart page — never a
+ * count, and never a drawer that cannot open.
+ */
+declare function CartButton({ storeApiOrigin, label, cartHref, checkoutHref, className, }: CartButtonMarkerProps): React.ReactElement;
+
+export { CartButton as C, type CartButtonMarkerProps as a, type CartButtonProps as b };

package/dist/cart-storage.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The cart, in the shopper's own browser (PAT-766).
+ *
+ * ── Why localStorage and not a table ──────────────────────────────────────────
+ * A retail cart holds no PHI and no commitment: it is a list of things somebody
+ * is thinking about. Persisting it server-side would buy a cart table, a sweeper
+ * for abandoned rows, a merge story for "signed in on a second device", and an
+ * anonymous-cart identity — all to reproduce what the browser already does for
+ * free. Nothing here is trusted: the server re-derives every price, every stock
+ * fact and every title on each quote and again inside the checkout mint, so the
+ * worst a tampered cart can do is change WHAT is bought, never what it costs.
+ *
+ * ── The `kind` discriminator is a RESERVATION ─────────────────────────────────
+ * The product requirement one-origin exists to serve is ONE cart spanning
+ * medication fills and retail items (docs/one-origin-islands.md §1). v1 sells
+ * retail only — but the storage shape carries `kind` from day one, and every
+ * function here PRESERVES a `fill` line it does not understand rather than
+ * dropping it. That matters: the day fills become purchasable, a patient who added
+ * one to an older build must not find it silently gone. The server refuses to
+ * price a fill line (`not_purchasable`), so a preserved line is inert, visible,
+ * and honest.
+ *
+ * ── Total by construction ─────────────────────────────────────────────────────
+ * Every read is defensive. Absent storage (SSR, private mode, a browser with it
+ * disabled), malformed JSON, a wrong version, a non-array `lines`, a line missing
+ * its variant — each yields an EMPTY cart, never a throw. A shop that white-screens
+ * because a stale key had a stray brace is worse than a shop that has forgotten
+ * your cart.
+ */
+/** The versioned storage key. A future shape change bumps this and starts clean. */
+declare const CART_STORAGE_KEY = "patientos.cart.v1";
+/** 'retail' is purchasable in v1; 'fill' is RESERVED and preserved but not sellable. */
+type CartLineKind = "retail" | "fill";
+type CartLine = {
+    lineId: string;
+    kind: CartLineKind;
+    variantId: string;
+    quantity: number;
+};
+type Cart = {
+    v: 1;
+    lines: CartLine[];
+    settledAttemptTokens?: string[];
+};
+type CartDraft = {
+    v: 1;
+    lines: readonly unknown[];
+    settledAttemptTokens?: string[];
+};
+type CartMutationResult = {
+    cart: Cart;
+    persisted: boolean;
+    status: "updated" | "cart_storage_unavailable" | "not_committed";
+};
+type AddToCartResult = {
+    cart: Cart;
+    status: "added" | "line_limit" | "quantity_limit" | "cart_storage_unavailable";
+};
+/**
+ * A FRESH empty cart, every call.
+ *
+ * Never hand out a shared instance: `addToCart` mutates the cart it reads, so a
+ * module-level singleton would accumulate lines across reads and survive a
+ * `clearCart` — a shop that remembers what you deleted.
+ */
+declare function emptyCart(): Cart;
+/** A frozen empty cart for comparisons. Never mutated, never returned from a read. */
+declare const EMPTY_CART: Readonly<Cart>;
+declare function normalizeCartLines(entries: readonly unknown[]): CartLine[];
+declare function readCart(): Cart;
+declare function mutateCart(mutation: (latest: Cart) => CartDraft, beforePersist?: (proposed: Cart, signal: AbortSignal) => Promise<boolean>): Promise<CartMutationResult>;
+type CartLockResult<T> = {
+    status: "completed";
+    cart: Cart;
+    result: T;
+} | {
+    status: "cart_storage_unavailable";
+    cart: Cart;
+} | {
+    status: "not_completed";
+    cart: Cart;
+};
+declare function withCartLock<T>(operation: (latest: Cart, signal: AbortSignal) => Promise<T>): Promise<CartLockResult<T>>;
+declare function writeCart(cart: CartDraft): Promise<CartMutationResult>;
+declare function addToCart(variantId: string, quantity?: number): Promise<AddToCartResult>;
+declare function setCartQuantity(kind: CartLineKind, variantId: string, quantity: number): Promise<CartMutationResult>;
+declare function adjustCartQuantity(kind: CartLineKind, variantId: string, delta: number, maximumBaseline?: number): Promise<CartMutationResult>;
+declare function removeFromCart(variantId: string, kind?: CartLineKind): Promise<CartMutationResult>;
+declare function clearCart(): Promise<CartMutationResult>;
+declare function subtractPurchasedCartLines(purchasedLines: readonly unknown[], attemptToken?: string): Promise<CartMutationResult>;
+/** Total item count — the header badge. */
+declare function cartItemCount(cart?: Cart): number;
+/** The wire shape posted to `/api/store/quote` and `/checkout/init`. */
+declare function cartToWireLines(cart: {
+    v?: 1;
+    lines: readonly {
+        kind: CartLineKind;
+        variantId: string;
+        quantity: number;
+    }[];
+}): {
+    kind: CartLineKind;
+    variantId: string;
+    quantity: number;
+}[];
+type Listener = (cart: Cart) => void;
+/** Subscribe to cart changes (this tab AND other tabs). Returns an unsubscribe. */
+declare function subscribeToCart(fn: Listener): () => void;
+
+export { type AddToCartResult, CART_STORAGE_KEY, type Cart, type CartLine, type CartLineKind, type CartLockResult, type CartMutationResult, EMPTY_CART, addToCart, adjustCartQuantity, cartItemCount, cartToWireLines, clearCart, emptyCart, mutateCart, normalizeCartLines, readCart, removeFromCart, setCartQuantity, subscribeToCart, subtractPurchasedCartLines, withCartLock, writeCart };

package/dist/cart-storage.js

@@ -0,0 +1,39 @@
+import {
+  CART_STORAGE_KEY,
+  EMPTY_CART,
+  addToCart,
+  adjustCartQuantity,
+  cartItemCount,
+  cartToWireLines,
+  clearCart,
+  emptyCart,
+  mutateCart,
+  normalizeCartLines,
+  readCart,
+  removeFromCart,
+  setCartQuantity,
+  subscribeToCart,
+  subtractPurchasedCartLines,
+  withCartLock,
+  writeCart
+} from "./chunk-4NF7SSIX.js";
+import "./chunk-MLKGABMK.js";
+export {
+  CART_STORAGE_KEY,
+  EMPTY_CART,
+  addToCart,
+  adjustCartQuantity,
+  cartItemCount,
+  cartToWireLines,
+  clearCart,
+  emptyCart,
+  mutateCart,
+  normalizeCartLines,
+  readCart,
+  removeFromCart,
+  setCartQuantity,
+  subscribeToCart,
+  subtractPurchasedCartLines,
+  withCartLock,
+  writeCart
+};

package/dist/checkout-block-BeXwpqYe.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+/** JSON-safe island configuration. Crosses the build→runtime boundary — see `./islands`. */
+type CheckoutProps = {
+    /** PatientOS patient/API origin. Omitted keeps the original same-origin contract. */
+    storeApiOrigin?: string;
+    /** Shopper-facing order history on the hosting site. */
+    ordersHref?: string;
+    /** Same-origin order confirmation route on the hosting clinic site. */
+    completionHref?: string;
+};
+/** Marker-only props: runtime config plus presentation the page controls. */
+type CheckoutMarkerProps = CheckoutProps & {
+    className?: string;
+};
+/**
+ * BUILD-TIME marker. Emits the mount point plus a static no-JS fallback.
+ *
+ * The fallback carries no order, no amount and no payment field: this document is a
+ * static artifact served to every visitor.
+ */
+declare function Checkout({ storeApiOrigin, ordersHref, completionHref, className, }: CheckoutMarkerProps): React.ReactElement;
+
+export { Checkout as C, type CheckoutMarkerProps as a, type CheckoutProps as b };

package/dist/chunk-2CZFJOKK.js

@@ -0,0 +1,79 @@
+import {
+  CartLineList,
+  CartProblemList,
+  CartTotals,
+  UnsupportedCartLineList,
+  quoteSourceQuantities,
+  useCartQuote
+} from "./chunk-IOC6QLB7.js";
+import {
+  createStoreClient
+} from "./chunk-7BUDUYXN.js";
+import {
+  readCart,
+  subscribeToCart
+} from "./chunk-4NF7SSIX.js";
+
+// src/cart-block.client.tsx
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+function CartClient({ storeApiOrigin }) {
+  const client = React.useMemo(
+    () => createStoreClient({ apiOrigin: storeApiOrigin }),
+    [storeApiOrigin]
+  );
+  const [cart, setCart] = React.useState(() => readCart());
+  const [mutationUnavailable, setMutationUnavailable] = React.useState(false);
+  const { quote, quoteSourceCart, failed } = useCartQuote(client, cart);
+  async function runMutation(mutation) {
+    const result = await mutation;
+    setMutationUnavailable(result.status === "cart_storage_unavailable");
+  }
+  React.useEffect(() => subscribeToCart(setCart), []);
+  if (cart.lines.length === 0) {
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("h2", { className: "sk-cart__heading", children: "Your cart" }),
+      /* @__PURE__ */ jsx("p", { className: "sk-cart__placeholder", role: "status", children: "Your cart is empty." }),
+      /* @__PURE__ */ jsx("a", { className: "sk-cart__continue", href: "/store", children: "Browse the shop" })
+    ] });
+  }
+  const quotedVariantIds = new Set(
+    quote?.lines.map((line) => line.variantId) ?? []
+  );
+  const unsupportedLines = cart.lines.filter(
+    (line) => line.kind !== "retail" || quote !== null && !quotedVariantIds.has(line.variantId)
+  );
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("h2", { className: "sk-cart__heading", children: "Your cart" }),
+    quote ? /* @__PURE__ */ jsx(CartProblemList, { problems: quote.problems }) : null,
+    failed ? /* @__PURE__ */ jsx("p", { className: "sk-cart__placeholder", role: "alert", children: "We couldn't price your cart just now. Please try again in a moment." }) : null,
+    mutationUnavailable ? /* @__PURE__ */ jsx("p", { className: "sk-cart__placeholder", role: "alert", children: "This browser can\u2019t safely update the cart. Try a supported browser with site storage enabled." }) : null,
+    /* @__PURE__ */ jsx(
+      UnsupportedCartLineList,
+      {
+        lines: unsupportedLines,
+        onMutate: (m) => void runMutation(m)
+      }
+    ),
+    quote ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(
+        CartLineList,
+        {
+          lines: quote.lines,
+          sourceQuantities: quoteSourceQuantities(quoteSourceCart),
+          onMutate: (m) => void runMutation(m)
+        }
+      ),
+      /* @__PURE__ */ jsx(CartTotals, { quote }),
+      quote.requiresShipping ? /* @__PURE__ */ jsx("p", { className: "sk-cart__note", children: "Delivery details are confirmed at checkout." }) : null,
+      /* @__PURE__ */ jsxs("div", { className: "sk-cart__actions", children: [
+        /* @__PURE__ */ jsx("a", { className: "sk-cart__continue", href: "/store", children: "Keep shopping" }),
+        unsupportedLines.length === 0 && quote.lines.length > 0 ? /* @__PURE__ */ jsx("a", { className: "sk-cart__checkout", href: "/checkout", children: "Checkout" }) : /* @__PURE__ */ jsx("span", { className: "sk-cart__checkout", "aria-disabled": "true", children: "Remove unsupported items to checkout" })
+      ] })
+    ] }) : /* @__PURE__ */ jsx("p", { className: "sk-cart__placeholder", role: "status", children: "Pricing your cart\u2026" })
+  ] });
+}
+
+export {
+  CartClient
+};