@patientos/website-kit 0.2.5 → 0.2.7

package/README.md

@@ -36,3 +36,89 @@ For a PatientOS clinic that explicitly registers `http://localhost:*`, the kit c
 verified patient session back to a dynamically allocated localhost dev server. The
 one-time return credential is scrubbed from the URL and exchanged for a tab-scoped
 bearer; deployed sites continue to use host-only patient cookies.
+
+## Store, cart and checkout
+
+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 } 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'
+
+<StoreClient storeApiOrigin={storeApiOrigin} productHandle="vitamin-d" />
+<CartClient storeApiOrigin={storeApiOrigin} />
+<CheckoutClient
+  storeApiOrigin={storeApiOrigin}
+  ordersHref="/account/orders"
+  completionHref="/checkout/complete"
+/>
+```
+
+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
+always sends `credentials: 'include'` and `cache: 'no-store'`; checkout remains patient
+sign-in-required.
+
+The hosting clinic site owns `completionHref`. It defaults to `/checkout/complete`, must
+resolve on that same origin, and receives the paid order ID as its `order` query parameter.
+Cross-origin or malformed destinations safely fall back to the default. Cart lines carry
+package-owned opaque IDs so paid reconciliation removes only the exact line generation
+captured by that checkout attempt.

package/dist/{checkout-block-Cog4H4I4.d.ts → booking-block-D-UOAPx3.d.ts}

@@ -71,52 +71,4 @@ type BookingBlockMarkerProps = {
 };
 declare function BookingBlock({ appointmentTypeId, practitionerId, appointmentTypeIds, heading, className, }: BookingBlockMarkerProps): React.ReactElement;
 
-/** JSON-safe island configuration. Crosses the build→runtime boundary — see `./islands`. */
-type StoreProps = {
-    /** Show one category only. Omitted ⇒ the whole published catalogue. */
-    categoryHandle?: string;
-    /** Heading rendered above the grid. */
-    title?: string;
-    /** Grid columns at the widest breakpoint. */
-    columns?: number;
-};
-/** Marker-only props: the island config plus presentation the page controls. */
-type StoreMarkerProps = StoreProps & {
-    className?: string;
-};
-/**
- * BUILD-TIME marker. Emits the mount point plus a static no-JS fallback — the catalogue
- * itself is fetched at runtime (prices and stock must not be baked into a cached static
- * artifact), so the fallback is a prompt, not a product list.
- */
-declare function Store({ categoryHandle, title, columns, className, }: StoreMarkerProps): React.ReactElement;
-
-/** JSON-safe island configuration. Crosses the build→runtime boundary — see `./islands`. */
-type CartProps = Record<string, never>;
-/** Marker-only props: presentation the page controls (the cart itself takes no config). */
-type CartMarkerProps = {
-    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({ className }: CartMarkerProps): React.ReactElement;
-
-/** JSON-safe island configuration. Crosses the build→runtime boundary — see `./islands`. */
-type CheckoutProps = Record<string, never>;
-/** Marker-only props: presentation the page controls (checkout itself takes no config). */
-type CheckoutMarkerProps = {
-    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({ className }: CheckoutMarkerProps): React.ReactElement;
-
-export { BookingBlock as B, Cart as C, type FunnelPublicApi as F, Store as S, type BookingBlockMarkerProps as a, type BookingBlockProps as b, type BookingTypeOption as c, type CartMarkerProps as d, type CartProps as e, CertificateFunnel as f, type CertificateFunnelMarkerProps as g, type CertificateFunnelProps as h, Checkout as i, type CheckoutMarkerProps as j, type CheckoutProps as k, type FunnelServiceOption as l, type StoreMarkerProps as m, type StoreProps as n };
+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
+};