@patientos/website-kit 0.2.4 → 0.2.6

package/README.md

@@ -31,3 +31,42 @@ export function CertificateFunnel() {
 
 `publicApi.publishableKey` is public by design and is validated against the consuming
 site's origin by PatientOS. Never put server credentials or patient data in these props.
+
+For a PatientOS clinic that explicitly registers `http://localhost:*`, the kit can carry a
+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:
+
+```tsx
+import { StoreClient, CartClient, CheckoutClient } from '@patientos/website-kit/islands-impl'
+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.
+
+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 → checkout-block-BdpPIuQ5.d.ts}

@@ -75,6 +75,10 @@ declare function BookingBlock({ appointmentTypeId, practitionerId, appointmentTy
 type StoreProps = {
     /** Show one category only. Omitted ⇒ the whole published catalogue. */
     categoryHandle?: string;
+    /** Show exactly one product by its stable handle. Takes precedence over category. */
+    productHandle?: string;
+    /** PatientOS patient/API origin. Omitted keeps the original same-origin contract. */
+    storeApiOrigin?: string;
     /** Heading rendered above the grid. */
     title?: string;
     /** Grid columns at the widest breakpoint. */
@@ -89,12 +93,15 @@ type StoreMarkerProps = StoreProps & {
  * 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;
+declare function Store({ categoryHandle, productHandle, storeApiOrigin, 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 = {
+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;
 };
 /**
@@ -103,12 +110,19 @@ type CartMarkerProps = {
  * 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;
+declare function Cart({ storeApiOrigin, 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 = {
+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;
 };
 /**
@@ -117,6 +131,6 @@ type CheckoutMarkerProps = {
  * 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;
+declare function Checkout({ storeApiOrigin, ordersHref, completionHref, 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 };