@stamprally/react 0.9.0 → 0.10.0

package/README.md

@@ -1,102 +1,29 @@
 # @stamprally/react
 
-React 19 integration for [`@stamprally/core`](https://www.npmjs.com/package/@stamprally/core).
-The package provides the `useStampRally` hook with external-store updates,
-optimistic stamp acquisition, persistence, reward redemption, and recovery-code
-support.
-
-## Install
-
-```sh
-npm install @stamprally/core @stamprally/react react
-```
-
-Or with pnpm:
-
-```sh
-pnpm add @stamprally/core @stamprally/react react
-```
-
-This package supports React `>=19.0.0 <20.0.0`.
-
-## Quick start
+React integration for `@stamprally/core`. `useStampRally` subscribes to immutable client state and exposes check-in, reward-claim, synchronization, and user-switching operations.
 
 ```tsx
 import { useMemo } from "react";
-import {
-  LocalStorageAdapter,
-  StampRallyClient,
-  type RallyConfig,
-} from "@stamprally/core";
+import { StampRallyClient, type PublicRallyConfig } from "@stamprally/core";
 import { useStampRally } from "@stamprally/react";
 
-const config: RallyConfig = {
+const config: PublicRallyConfig = {
   id: "city-tour",
-  stamps: [
-    {
-      id: "station",
-      name: "Central Station",
-      condition: { type: "instant" },
-    },
-  ],
+  version: "0.9.1",
+  title: "City Tour",
+  spots: [{ id: "station", orderIndex: 0, name: "Station", conditions: [{ type: "passcode" }] }],
+  rewards: [],
 };
 
 export function Rally() {
-  const client = useMemo(
-    () => new StampRallyClient(config, new LocalStorageAdapter()),
-    [],
-  );
-  const { state, isLoading, isPending, error, acquire } = useStampRally(client);
-
+  const client = useMemo(() => new StampRallyClient(config), []);
+  const { state, isLoading, onCheckIn } = useStampRally(client);
   if (isLoading) return <p>Loading…</p>;
-
-  return (
-    <section>
-      <p>
-        {state?.records.length ?? 0} stamp(s) collected
-      </p>
-      <button
-        disabled={isPending}
-        onClick={() => void acquire("station", { type: "instant" })}
-      >
-        Collect stamp
-      </button>
-      {error !== null && <p role="alert">Could not collect the stamp.</p>}
-    </section>
-  );
+  return <button onClick={() => void onCheckIn("station", "ARRIVED")}>{state?.records.length ?? 0} checked in</button>;
 }
 ```
 
-The hook initializes the client when needed, subscribes to state changes, and
-keeps the UI synchronized with persisted state. Keep the `StampRallyClient`
-instance stable, for example with `useMemo`, so that the hook does not switch
-clients on every render.
-
-## Hook return value
-
-`useStampRally(client)` returns:
-
-- `state`: the current `StampRallyState`, or `null` while it is not initialized.
-- `isLoading`: whether the client is initializing or changing clients.
-- `isPending`: whether an acquisition, reset, redemption, or import is pending.
-- `error`: the latest typed engine/reward error or storage error.
-- `rewardsState`: the current reward states, or an empty array when rewards are not configured.
-- `acquire(stampId, context, now?)`: validates and persists a stamp acquisition.
-- `reset(now?)`: clears the persisted rally state.
-- `redeem(rewardId, options?)`: redeems an available reward, optionally with a staff passcode and ID.
-- `exportRecoveryCode()`: exports confirmed stamp and reward progress.
-- `importRecoveryCode(token)`: restores a rally-scoped recovery code and returns whether it was valid.
-
-Acquisitions are shown optimistically while persistence is pending. Engine
-validation and storage failures roll the optimistic state back and are exposed
-through the returned `error` value and the rejected promise where applicable.
-
-## Browser and server rendering
-
-The hook uses React's external-store API and provides a `null` server snapshot.
-The core package's browser adapters and detectors access browser globals only
-when called, so applications can choose a different `StampStorage` for server
-rendering, tests, or non-browser environments.
+The hook return value includes `state`, `isLoading`, `error`, `onCheckIn`, `onClaimReward`, `onSync`, `switchUser`, and `clearUserState`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stamprally/react",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "React hooks for @stamprally/core.",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,7 @@
     }
   },
   "dependencies": {
-    "@stamprally/core": "0.9.0"
+    "@stamprally/core": "0.10.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",