@patientos/website-kit 0.2.5 → 0.2.6

package/README.md

@@ -36,3 +36,37 @@ 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:
+
+```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 };