@lockerverse/react 0.2.132 → 0.2.133-dev.1

package/README.md

@@ -1,6 +1,26 @@
 # `@lockerverse/react`
 
-Tree-shakable React UI for Lockerverse payment and signup widgets. The Core SDK is installed automatically as a normal package dependency.
+Tree-shakable React UI for Lockerverse payments, signup, auctions, and public Events. The Core SDK is installed automatically as a normal package dependency.
+
+This README ships with the package and describes that release. For an installed
+project, use its local README, `package.json` exports, and public `.d.ts` files.
+Online examples can describe a newer release. Do not import private `dist`
+modules or copy API details from a different SDK version.
+
+## Usage guide
+
+- [Install](#install) and [payment quick start](#use)
+- [Configuration and environment](#configuration-and-environment)
+- [Server rendering](#server-rendering) and [resource identity](#resource-identity)
+- [Custom product UI](#custom-product-ui) and [live availability](#live-product-availability)
+- [Donate launcher](#donate-launcher)
+- [Signup](#signup)
+- [Styling](#styling)
+- [Payment outcomes](#payment-outcomes) and [recovery](#payment-recovery)
+- [Auctions](#auctions) and [direct auction pages](#direct-auction-pages)
+- [Public event listings](#public-event-listings)
+
+For custom non-React clients, use the README shipped with `@lockerverse/sdk`.
 
 ## Install
 
@@ -35,8 +55,6 @@ export function Checkout() {
       metadata={{ source: "community-site" }}
       onPaymentComplete={(payment: LockerversePaymentCompletion) => {
         console.info("Payment complete", payment.checkoutId);
-        console.info("Customer", payment.email);
-        console.info("Authoritative items", payment.lineItems);
       }}
       onPaymentUncertain={({ paymentReference, reason }) => {
         console.info("Payment needs status recovery", paymentReference, reason);
@@ -165,6 +183,38 @@ cadence and configures Stripe Elements for a subscription:
 Recurring checkout accepts one fixed Product. It does not accept quantities,
 custom amounts, or multiple Products.
 
+### Live product availability
+
+Use the live `widget.catalog` for names, prices, and limits. Find the requested
+product by its `listingId` or `slug`; do not keep a separate static price list.
+Amounts are integer cents. Format them with `catalog.payment.currency`, not a
+currency field on the product.
+
+Before enabling a new purchase, check the selected product's `minimumQuantity`,
+`maximumQuantity`, and `inventoryQuantity`; nullable limits mean no limit.
+For custom amounts, use `getLockerverseMinimumCustomAmountCents(product)` from
+`@lockerverse/sdk/checkout` to include the SDK minimum and the product minimum.
+Also check:
+
+- The matching `catalog.availability.listings` entry: `status`,
+  `maxPurchasableQuantity`, and `remainingQuantity`.
+- Each `catalog.availability.sharedLimits` entry whose `listingIds` includes
+  the selected product's listing: `status` and `remainingQuantity`. Add the
+  quantities of all selected listings in that shared group before checking its
+  remaining quantity.
+
+A missing listing availability entry means no listing-specific limit was
+reported. Other product and shared limits still apply. These checks help the
+host show an unavailable state; the authoritative quote decides whether the
+selection can be purchased. Show loading, retry, and empty states. Keep an
+unresolved payment available for recovery even if a new purchase is unavailable.
+
+If an existing button already selects one product, open its checkout directly.
+Use the donate launcher when the visitor needs a product picker. For a custom
+dialog, use an accessible title, close button, focus handling, and mobile scroll
+area. Keep recovery state in an owner that remains mounted when the dialog
+closes. Closing a dialog does not complete or cancel a payment.
+
 ## Donate launcher
 
 `LockerverseDonateLauncher` turns an existing payment widget into a native
@@ -238,8 +288,19 @@ export function Signup() {
 
 Pass `googlePlacesApiKey` to enable US address suggestions when the signup asks for an address. Manual address entry always remains available.
 
-For a development HTTPS backend, provide `apiBaseUrl` to the hook. The backend
-supplies the correct Stripe public key.
+## Configuration and environment
+
+Production is the default. Payment, signup, auction, and Events hooks accept
+`apiBaseUrl` and `environment` together. A custom URL requires an explicit
+environment; `environment: "development"` also requires a URL. Include `/api`
+in the API base URL. Do not infer the environment from the host website's URL.
+Use the public community and resource slugs from the intended integration.
+Signup uses `signupSlug`; payment uses `widgetSlug`.
+
+The backend supplies the Stripe publishable key and connected account. Do not
+hard-code either value or pass a secret key. The default Stripe loader handles
+initialization. If a host supplies `stripeLoader={loadStripe}`, preserve all
+loader arguments, including the connected-account options.
 
 ```tsx
 const widget = useLockerverseWidget({
@@ -255,6 +316,25 @@ const widget = useLockerverseWidget({
 />
 ```
 
+## Server rendering
+
+Use the host framework's client component or client-only boundary for browser
+payment UI. Keep browser storage access in an effect, not at module scope or
+during server rendering. For TanStack Router, import `ClientOnly` from
+`@tanstack/react-router` and put the component that owns checkout inside it:
+
+```tsx
+import { ClientOnly } from "@tanstack/react-router";
+
+<ClientOnly fallback={<p>Loading checkout...</p>}>
+  <Checkout />
+</ClientOnly>
+```
+
+The host supplies this boundary; TanStack Router is not an SDK dependency.
+Wait for saved recovery state to load before mounting payment. Remount the
+recovery owner when its resource or recovery key changes.
+
 ## Styling
 
 Auction checkout, payment, and signup use common email, phone, field-error, and checkbox controls. Payment and signup share the custom-field renderer. Phone fields use the lightweight payment/signup country list, normalization, and Valibot format validation. The shared phone control is imported directly, with no separate phone chunk or metadata library. Each flow keeps its existing field configuration and backend rules.
@@ -303,31 +383,83 @@ An authoritative `failed` result is retryable and the next submit receives a new
 
 To abandon a locked attempt and intentionally start a new checkout, the host must remount `LockerversePayment` with a new React `key` after resolving the payment status through its own workflow.
 
-Persist `onPaymentRecoveryChange` synchronously before navigation and pass the saved value back through `resumePayment` after a refresh. The recovery value contains a Lockerverse reference and public connected-account ID, never a Stripe secret.
+### Payment recovery
 
-```tsx
-import type { LockerversePaymentRecovery } from "@lockerverse/react";
+Persist `onPaymentRecoveryChange` synchronously before navigation and pass the
+saved value back through `resumePayment` after a refresh. Do not defer the save
+to an effect. A recovery record has only `paymentReference: string` and
+`connectedAccountId: string | null`; it contains no Stripe secret. Scope its
+storage key to the environment, community, widget, and selection.
 
-const recoveryKey = "lockerverse:tailgate-party:payment";
-const savedRecovery = sessionStorage.getItem(recoveryKey);
-const recovery = savedRecovery
-  ? (JSON.parse(savedRecovery) as LockerversePaymentRecovery)
-  : null;
+This hook reads storage after mount, validates the saved record, and keeps an
+in-memory record if storage is unavailable:
 
-<LockerversePayment
-  selection={selection}
-  resumePayment={recovery}
-  onPaymentRecoveryChange={(nextRecovery) => {
-    if (nextRecovery) {
-      sessionStorage.setItem(recoveryKey, JSON.stringify(nextRecovery));
-    } else {
-      sessionStorage.removeItem(recoveryKey);
+```tsx
+import { useEffect, useState } from "react";
+import type { LockerversePaymentRecovery } from "@lockerverse/react/payment";
+
+function usePaymentRecovery(recoveryKey: string) {
+  const [recovery, setRecovery] = useState<LockerversePaymentRecovery | null>(null);
+  const [loaded, setLoaded] = useState(false);
+
+  useEffect(() => {
+    try {
+      const raw = sessionStorage.getItem(recoveryKey);
+      const saved: unknown = raw ? JSON.parse(raw) : null;
+      if (
+        saved !== null && typeof saved === "object" &&
+        "paymentReference" in saved && typeof saved.paymentReference === "string" &&
+        "connectedAccountId" in saved &&
+        (saved.connectedAccountId === null || typeof saved.connectedAccountId === "string")
+      ) {
+        setRecovery({
+          paymentReference: saved.paymentReference,
+          connectedAccountId: saved.connectedAccountId,
+        });
+      }
+    } catch {
+      // Invalid or unavailable storage must not break checkout.
     }
-  }}
-  widget={widget}
-/>
+    setLoaded(true);
+  }, [recoveryKey]);
+
+  function saveRecovery(next: LockerversePaymentRecovery | null) {
+    setRecovery(next);
+    try {
+      if (next) sessionStorage.setItem(recoveryKey, JSON.stringify(next));
+      else sessionStorage.removeItem(recoveryKey);
+    } catch {
+      // Keep the in-memory record if storage is unavailable.
+    }
+  }
+
+  return { loaded, recovery, saveRecovery };
+}
 ```
 
+Use it in the payment owner, keyed by the recovery key. Render checkout only
+after `loaded` is true:
+
+```tsx
+const { loaded, recovery, saveRecovery } = usePaymentRecovery(recoveryKey);
+
+return loaded ? (
+  <LockerversePayment
+    selection={selection}
+    resumePayment={recovery}
+    onPaymentRecoveryChange={saveRecovery}
+    widget={widget}
+  />
+) : <p>Loading checkout...</p>;
+```
+
+Retain the record on `onPaymentUncertain` and let the component recover the
+same payment. Do not create a replacement charge for an unknown result.
+`onPaymentComplete` confirms success; its `paymentRequired` distinguishes a
+paid purchase from a no-charge order. This browser callback does not grant paid
+access; access checks require server verification. Keep private contact and
+payment data out of URLs, analytics, logs, and public metadata.
+
 Malformed host selections and invalid custom tips render customer-safe validation messages and do not call the Lockerverse API. Product selection remains owned by the host application.
 
 ## Auctions
@@ -389,8 +521,8 @@ export function AuctionPage() {
 }
 ```
 
-Production is the default. Set `environment: "development"` on the hook only
-when you intend to use the development backend. Auction data supplies the
+Production is the default. For development, set both `apiBaseUrl` and
+`environment: "development"` as shown in [configuration](#configuration-and-environment). Auction data supplies the
 publishable key and connected account for Stripe initialization. The backend
 must include the auction `payment` configuration to use built-in checkout.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lockerverse/react",
-  "version": "0.2.132",
+  "version": "0.2.133-dev.1",
   "description": "Tree-shakable React payment and signup UI for Lockerverse",
   "repository": {
     "type": "git",
@@ -127,7 +127,7 @@
     "embla-carousel-react": "8.6.0",
     "lucide-react": "0.536.0",
     "valibot": "1.4.2",
-    "@lockerverse/sdk": "0.2.132"
+    "@lockerverse/sdk": "0.2.133-dev.1"
   },
   "devDependencies": {
     "@size-limit/file": "13.0.3",