@stapel/reviews-react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @stapel/reviews-react

package/MODULE.md

@@ -0,0 +1,151 @@
+# @stapel/reviews-react — module guide
+
+Pairs with **stapel-reviews 0.3.0** (`>=0.3 <0.4`), 4 paths under
+`/reviews/api/v1/`. Contract sources: the module's own
+`docs/{schema,errors,flows}.json`, pinned in `contract-pins.json` and
+regenerated under `pnpm gen:check`.
+
+## Layers
+
+```
+src/api/          reviewsApi.ts   the three operations a browser may call;
+                                  the one home of path strings
+                  types.ts        wire aliases + the two remaining corrections
+                  generated/      openapi-typescript, drift-gated
+src/model/        runtime · context · queryKeys · queries · mutations
+                  rating.ts       the aggregate, READ (the zero that is not a rating)
+                  list.ts         pure readers over loaded rows
+                  refusals.ts     the refusal vocabulary, keyed by CODE
+src/headless/     ReviewsProvider · ReviewList · ReviewAggregate · ReviewForm
+src/default/      the antd skin, `./default` subpath
+src/i18n/         keys · ru · es · errorsMap + generated/
+```
+
+`rating.ts`, `list.ts` and `refusals.ts` are pure: no React, no fetch, no
+storage. That is what lets the whole "what does this number mean" question be
+tested without a DOM, and what lets an SSR render call them directly.
+
+There is **no `flows/` layer** (`docs/flows.json` is `[]`, the module annotates
+no `@flow_step`) and **no `nav/` layer** (this pair owns no route — see below).
+
+## What 0.3.0 changed here
+
+This pair was built against 0.2.2 and carried two workarounds for it. **Both
+are deleted**, because the release answered both asks:
+
+| Was | Now |
+|---|---|
+| `ReviewPage`, `ReviewListParams`, `ReviewAnchorDirection` hand-declared in `api/types.ts` | projections of `components/ReviewPage` and the generated `reviews_api_v1_reviews_retrieve` query type |
+| `signInRequired` on the list bag, the aggregate bag and the form bag; two sign-in arms in the skin; `reviews.list.sign_in_required` + `reviews.rating.sign_in_required` | `signInRequired` on the **form bag only**; one sign-in key (`reviews.form.sign_in_required`) |
+
+The permission change is `IsAuthenticatedOrReadOnly` on the list class
+(mirroring stapel-listings' `ListingViewSet`: GET open, POST still needs an
+author) and `AllowAny` on the aggregate, both with
+`stapel_anonymous_access = ANONYMOUS_ALLOWED` and both throttled from
+`STAPEL_REVIEWS` (`LIST_THROTTLE` 120/min, `AGGREGATE_THROTTLE` 300/min) rather
+than the project's `DEFAULT_THROTTLE_RATES`. Nothing new became visible to a
+guest: both endpoints were already published-only for a non-moderator.
+
+## The three contract facts this package still absorbs
+
+### 1. The list body is the pagination envelope — now declared
+
+`ReviewListCreateView` is a plain `APIView` that instantiates
+`ReviewAnchorPagination` inside `get()` rather than declaring a
+`pagination_class`, so drf-spectacular's pagination introspection never runs.
+0.3.0 works around its own limitation the right way — a hand-written
+`ReviewPageSerializer` plus explicit `OpenApiParameter`s — so the CONTRACT now
+tells the truth and this package types the envelope from codegen.
+
+Two properties of the paging are load-bearing:
+
+- the anchor is a **`created_at` ISO timestamp**, because
+  `anchor_field = "created_at"` and `ordering = "-created_at"`;
+- `has_next` is the authority. The paginator leaves `next_anchor` `null` on the
+  last page, so a cursor rebuilt from the last row would re-request it forever.
+
+### 2. `avg` is `0.0` when `count` is `0`
+
+`services.aggregate` returns exactly that, and `AggregateResponse` documents
+it. `ratingSummary()` is the single reader, and its type has no `avg` on the
+unrated branch — a skin cannot reach a number to draw there even by accident.
+`starBreakdown(rounded, max)` then splits a real average into full/half/empty
+counts against the DEPLOYMENT's ceiling, not a hardcoded five.
+
+### 3. The duplicate refusal is a 400, and the 409 is about something else
+
+| Code | Status | Means |
+|---|---|---|
+| `error.400.reviews_duplicate_review` | 400 | this author already reviewed this target |
+| `error.409.reviews_already_responded` | 409 | the review already has the **owner's reply** |
+
+`model/refusals.ts` holds a predicate per refusal, each comparing a
+`FlowError.code` folded through core's `toFlowError`. `test/refusals.test.ts`
+asserts both directions, so the trap is documented in the suite.
+
+Note also that the duplicate only exists where the target type sets
+`one_per_author: true` — the registry default is `False`
+(`registry.resolve_policy`), and the shop preset turns it on for `listing`. No
+endpoint reports the policy, so the client cannot pre-compute the rule; it
+handles the answer.
+
+### 4. The reads are anonymous — and the session gate matters MORE for it
+
+The hooks are still gated on `useActiveSessionReady()`, and the reason got
+stronger with the permission change rather than weaker. What the server returns
+depends on who is asking: a moderator of the target gets pending and hidden
+rows for `include=all`, everyone else is narrowed to published *silently*. A
+read that raced a bootstrapping session used to produce a visible 401; now it
+would SUCCEED as a guest and cache that answer under a key that does not
+mention identity. `useActiveSessionReady()` answers `true` the instant the
+session settles into any of authenticated / anonymous / unauthenticated, and
+immediately when no session-owning module is mounted — so a purely public
+storefront waits for nothing.
+
+## The target is two strings, and the pair invents neither
+
+`target_type` is a key the host registered in `STAPEL_REVIEWS["TARGET_TYPES"]`
+(built-ins: `{}`); `target_key` is an opaque host string the module stores and
+groups by but never parses. Both are in every query key, because `target_key`
+alone is not an identity — two registries can key different things with the
+same string.
+
+This package exports no target-type constants. `test/pair.test.ts` asserts the
+absence.
+
+## The seller roll-up
+
+Product model (storefront spec fork F5): a review targets the SELLER for a
+specific listing — `target_type: "listing"`, `unique(author, listing)` — and
+the seller's rating is a roll-up across their listings. stapel-reviews cannot
+compute it; the composite does, as `shop.listing_review_summary`, whose
+`read()` answers `{avg, count}` in both local and remote mode *using the
+owner's field names on purpose*.
+
+`<ReviewAggregate target={…} aggregate={…}>` renders those two numbers with no
+request. Known gap: no HTTP route publishes the roll-up today, so the host's
+own backend must serve it.
+
+## Not on the surface
+
+| Operation | Why not |
+|---|---|
+| `POST /reviews/{id}/moderate` | `can_moderate` is fail-closed; a moderator console, which this pair is not |
+| `POST /reviews/{id}/response` | same gate; the reply is DISPLAYED in the MVP and the write is a seller console (spec §4.4) |
+
+Both remain in `manifest.json`, which lists the whole contract. Adding either
+later is additive.
+
+## Tests
+
+| File | What it pins |
+|---|---|
+| `rating.test.ts` | the zero that is not a rating, in every arm; the projection shape reads the same |
+| `refusals.test.ts` | 400 duplicate vs 409 already-responded; the write's 401 vs 403; a non-API fault |
+| `list.test.tsx` | the envelope, the `created_at` cursor, no page past `has_next`, the anonymous read and its reachable empty state |
+| `submit.test.tsx` | the request body, the duplicate as a named state, the 401 the write still answers, `pending` after submit, the bounds |
+| `skin.test.tsx` | no star row for an unrated target, the moderated badges, a guest seeing rows with no sign-in wall, "sign in to leave a review" on a 401 POST, one list request for the composed panel |
+| `i18n.test.ts` | every registry code and every UI key resolves in en/ru/es |
+| `pair.test.ts` | query keys, the surface's absences (moderate/respond/nav/target constants), the logout hook |
+| `demos.test.tsx` | every demo variant renders |
+| `prodBundlePurity.test.ts` | no showcase/demo code in the tarball |

package/README.md

@@ -0,0 +1,207 @@
+# @stapel/reviews-react
+
+The frontend pair for **stapel-reviews**: ratings and reviews of an opaque
+`(target_type, target_key)` — a listing, a seller, a course, whatever the host
+registered — rendered without any of the four lies the contract makes easy.
+
+Business + state in the main entry, zero visual opinion; the antd skin lives
+behind `./default`. Built on `@stapel/core` (typed client + `StapelApiError`
+envelope, `LoadState`, `ActionAvailability`, i18n engine, TanStack Query).
+
+## Install
+
+```
+pnpm add @stapel/reviews-react @stapel/core @tanstack/react-query react
+# for the default skin:
+pnpm add antd @stapel/tokens-antd
+```
+
+## A review block, in eight lines
+
+```tsx
+import { createReviewsRuntime, ReviewsProvider } from "@stapel/reviews-react";
+import { ReviewsPanel } from "@stapel/reviews-react/default";
+
+const runtime = createReviewsRuntime({ baseUrl: "/reviews/api/v1" });
+
+export function ListingReviews({ listingId, me }) {
+  return (
+    <ReviewsProvider runtime={runtime}>
+      <ReviewsPanel
+        target={{ targetType: "listing", targetKey: listingId }}
+        viewerId={me?.id}
+      />
+    </ReviewsProvider>
+  );
+}
+```
+
+`"listing"` is **your** registry key, not this library's. stapel-reviews ships
+an empty `TARGET_TYPES` registry and knows nothing about listings; the shop
+composite registers that name in `stapel_shop/preset.py`. This package
+therefore exports no target-type constants at all — a guessed one would be
+wrong for every deployment but one.
+
+## Four things this package refuses to get wrong
+
+### 1. A zero average is not a zero rating
+
+`GET /reviews/aggregate` answers `{"avg": 0.0, "count": 0}` for a target nobody
+has rated — the module's own schema says so in the field description. Rendered
+straight into a star row that is **the worst possible score**, printed over a
+brand-new listing.
+
+```ts
+const summary = ratingSummary(aggregate);
+summary.rated; // false — and there is no `avg` on this branch of the type
+```
+
+`<RatingBadge>` renders the "no reviews yet" sentence in that arm and never
+reaches antd's `<Rate>`. Same class of defect as `data ?? []`.
+
+### 2. "You have already reviewed this" is a **400**
+
+```
+error.400.reviews_duplicate_review   ← the duplicate
+error.409.reviews_already_responded  ← the module's only 409, about the seller's REPLY
+```
+
+A form branching on `status === 409` misses the first and mishandles the
+second. `isDuplicateReview(error)` reads the code, and the form turns it into
+"you have already rated this" rather than a red banner. This one is still a
+live trap in 0.3.0 — it is a documented shape, not a defect the release fixed.
+
+The optimistic pre-check (`findOwnReview` over the loaded rows) exists, and its
+hole is documented rather than papered over: the list is published-only, so
+under pre-moderation the author's own pending review is invisible **to its
+author**, the form offers itself again, and the server is the one that says no.
+
+### 3. A guest reads the reviews; only the write asks them to sign in
+
+Both reads are anonymous since **stapel-reviews 0.3.0**:
+`ReviewListCreateView` is `IsAuthenticatedOrReadOnly` (GET open, POST still
+needs an author to attribute the review to) and `AggregateView` is `AllowAny`,
+both throttled from the module's own settings (`LIST_THROTTLE` 120/min,
+`AGGREGATE_THROTTLE` 300/min). Nothing new became visible — both endpoints were
+already published-only for a non-moderator.
+
+So `signInRequired` exists on **one** bag, the form's, where a 401 is still the
+honest answer. The read bags have no such state, and an empty list now means
+what it says to everybody: nobody has reviewed this target.
+
+> Against the 0.2.2 contract this pair carried the opposite: every endpoint was
+> `IsAuthenticated`, a visitor got 401 for the list *and* the aggregate, and
+> both read bags had to name that so the empty state would not tell a
+> not-yet-registered visitor that a well-reviewed seller has never been
+> reviewed. The ask went upstream instead of being worked around, and 0.3.0
+> answered it.
+
+### 4. A review that is not published says so
+
+`status` reaches the screen: `pending` and `hidden` rows (visible only to a
+moderator who asked for `include=all`) carry a badge, and a status this build
+does not know is **named** rather than rendered as an ordinary review. After a
+submit, the created row's status decides the sentence — a pre-moderating
+deployment tells the author their review will appear once checked, instead of
+leaving them to hunt for it.
+
+## The list body, and where its type comes from
+
+`GET /reviews` answers core's `AnchorPagination` envelope:
+
+```jsonc
+{ "items": [...], "next_anchor": "2026-08-19T10:00:00Z", "prev_anchor": null,
+  "has_next": true, "has_prev": false, "count": 20 }
+```
+
+It always did — but `ReviewListCreateView` is a plain `APIView` that
+instantiates its paginator inside `get()` instead of declaring a
+`pagination_class`, so drf-spectacular's introspection never ran and the schema
+declared `200: ReviewResponse[]`; the `anchor` / `limit` / `direction`
+parameters were invisible for the same reason. **0.3.0 declares both**
+(`components/ReviewPage`, and `direction` with an enum), so the copies this
+package maintained in `src/api/types.ts` are **deleted** and `ReviewPage`,
+`ReviewListParams` and `ReviewAnchorDirection` are all projections of the
+generated schema.
+
+Anchors are `created_at` timestamps (`anchor_field = "created_at"`,
+`ordering = "-created_at"`), and paging stops on `has_next`, never on a
+cursor rebuilt from the last row — the paginator leaves `next_anchor` `null`
+on the last page.
+
+## The seller rating is a display, not a fetch
+
+The product model reviews the **seller for a specific listing**:
+`target_type: "listing"`, one review per author per listing. A seller's own
+rating is therefore a roll-up across every listing they own — which
+stapel-reviews cannot compute (one `(target_type, target_key)` per call, and
+`reviews.aggregates_by_keys` is a comm Function for server-side projections,
+not an endpoint) and the shop composite can, as
+`shop.listing_review_summary`.
+
+So the pair renders the two numbers the composite produced:
+
+```tsx
+<RatingBadge
+  target={{ targetType: "seller", targetKey: sellerId }}
+  aggregate={rollup}          // {avg, count} — the projection's own field names
+/>
+```
+
+No request is made. **Known gap**: today no HTTP route publishes that roll-up,
+so a page that wants a seller rating must be served the two numbers by its own
+backend. Publishing them is the composite's job, not this pair's, and inventing
+an N+1 loop over the seller's listings here would be neither correct nor
+affordable.
+
+## What is deliberately not here
+
+- **Moderation and the owner's reply.** `POST {id}/moderate` and
+  `POST {id}/response` are gated on the target type's **fail-closed**
+  `can_moderate` callback and belong to a moderator console and a seller
+  console. The reply is *displayed*; the button to write one does not exist,
+  rather than existing switched off. Both operations stay in `manifest.json`,
+  which lists the whole contract.
+- **A nav manifest.** This pair has no route of its own — it renders inside the
+  listing detail page and the public seller profile. A "Reviews" menu item
+  leading nowhere would be worse than none (the `cdn-react` precedent), and a
+  test asserts the absence.
+- **A `flows/` layer.** `docs/flows.json` is `[]`; the module annotates no
+  `@flow_step`.
+
+## Rating bounds are the deployment's
+
+`RATING_MIN` / `RATING_MAX` are `STAPEL_REVIEWS` settings (library defaults 1
+and 5) and no endpoint reports them, so a host that moved them tells the
+runtime:
+
+```ts
+createReviewsRuntime({ baseUrl: "/reviews/api/v1", ratingBounds: { max: 10 } });
+```
+
+The mirror is a UI affordance only — the star row draws that many stars — and
+the server stays the authority (`error.400.reviews_invalid_rating`).
+
+## i18n
+
+English ships inline. `./i18n/ru` and `./i18n/es` are opt-in subpaths. There is
+exactly one sign-in string left (`reviews.form.sign_in_required`) — the two
+read-side ones went out with the 0.3.0 permission change. The 42
+cross-cutting error keys come from stapel-core's catalogue through the
+generated bundles; the **9 keys stapel-reviews owns are authored by this
+package**, because the module ships no `translations/` directory (the
+stapel-forms precedent). When upstream ships one, those nine lines are deleted
+and nothing else moves.
+
+## Surface
+
+| Layer | Exports |
+|---|---|
+| api | `createReviewsApi`, `ReviewsApi`, `Review`, `ReviewPage`, `ReviewTarget`, `RatingAggregate`, `ReviewStatus`, … |
+| model | `createReviewsRuntime`, `reviewsQueryKeys`, `useReviewList`, `useReviewAggregate`, `useSubmitReview`, `ratingSummary`, `starBreakdown`, `reviewsFromPages`, `findOwnReview`, `reviewVisibility`, `isDuplicateReview`, `isSignInRequired`, … |
+| headless | `ReviewsProvider`, `ReviewList`, `ReviewAggregate`, `ReviewForm` |
+| default | `ReviewsPanel`, `ReviewListPanel`, `ReviewFormCard`, `RatingBadge`, `ReviewsSkinTheme` |
+| i18n | `REVIEWS_I18N_KEYS`, `registerReviewsI18n`, `REVIEWS_ERRORS`, `explainReviewsError` |
+
+More detail: [`MODULE.md`](./MODULE.md), [`llms.txt`](./llms.txt),
+[`manifest.json`](./manifest.json).