@stapel/reviews-react 0.1.0

package/src/i18n/keys.ts

@@ -0,0 +1,133 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { reviewsErrorBundleEn } from "./generated/errors.gen.js";
+
+/**
+ * reviews-react's own translation KEYS (frontend-standard §4.2): headless
+ * components never render literal strings — hosts resolve these through core's
+ * i18n engine (`useT`). Backend error codes flow through the SAME contour: a
+ * `StapelApiError.code` is already a key, so the default bundle below ships
+ * English for both the backend's codes (generated) and the pair's own UI keys.
+ */
+export const REVIEWS_I18N_KEYS = {
+  unknownError: "reviews.error.unknown",
+
+  // The list
+  listHeading: "reviews.list.heading",
+  listEmpty: "reviews.list.empty",
+  listLoadMore: "reviews.list.load_more",
+  listRefresh: "reviews.list.refresh",
+  moreBlockedEnd: "reviews.list.more.blocked.end",
+  moreBlockedPending: "reviews.list.more.blocked.pending",
+
+  // One row. The wire carries `author_id` and NOTHING else about the person —
+  // no name, no avatar — so the skin renders this unless the host passes a
+  // `renderAuthor` slot. Printing the raw id would be both useless and a
+  // gratuitous disclosure.
+  authorFallback: "reviews.review.author_fallback",
+  responseHeading: "reviews.review.response_heading",
+
+  // Visibility, said out loud. A row that is not published is only ever on
+  // screen because a moderator asked for `include=all`, and it must not look
+  // like an ordinary review.
+  statusPending: "reviews.status.pending",
+  statusHidden: "reviews.status.hidden",
+  statusUnknown: "reviews.status.unknown",
+
+  // The rating
+  ratingNone: "reviews.rating.none",
+  ratingValue: "reviews.rating.value",
+  ratingCount: "reviews.rating.count",
+  ratingStarLabel: "reviews.rating.star_label",
+
+  // The form. `formSignInRequired` is the ONLY sign-in key left: since
+  // stapel-reviews 0.3.0 both reads are anonymous and only the POST refuses a
+  // guest, so "sign in" is copy for the write and never a wall in front of
+  // the content.
+  formHeading: "reviews.form.heading",
+  formRatingLabel: "reviews.form.rating_label",
+  formBodyLabel: "reviews.form.body_label",
+  formBodyPlaceholder: "reviews.form.body_placeholder",
+  formSubmit: "reviews.form.submit",
+  formSentPublished: "reviews.form.sent.published",
+  formSentPending: "reviews.form.sent.pending",
+  formSentHidden: "reviews.form.sent.hidden",
+  formSentUnknown: "reviews.form.sent.unknown",
+  formSignInRequired: "reviews.form.sign_in_required",
+
+  // Blocked controls — every one of these is the `code` of an
+  // ActionAvailability, so a switched-off button always has a sentence.
+  submitBlockedNoRating: "reviews.submit.blocked.no_rating",
+  submitBlockedPending: "reviews.submit.blocked.pending",
+  submitBlockedDuplicate: "reviews.submit.blocked.duplicate",
+  submitBlockedSubmitted: "reviews.submit.blocked.submitted",
+  submitBlockedForbidden: "reviews.submit.blocked.forbidden",
+
+  // Backend error keys the pair OWNS the localization of. stapel-reviews ships
+  // English only (no `translations/` directory at all), so its 9 keys are
+  // absent from the generated ru/es bundles and are authored in `./i18n/<lang>`
+  // instead — the stapel-forms/`stapel_attributes` precedent, applied before
+  // this by forms, chat, cdn and categories. Listed here so `i18n-key-exists`
+  // knows them and `test/i18n.test.ts` can prove all three locales carry them.
+  errorDuplicateReview: "error.400.reviews_duplicate_review",
+  errorInvalidModerationAction: "error.400.reviews_invalid_moderation_action",
+  errorInvalidRating: "error.400.reviews_invalid_rating",
+  errorResponseNotAllowed: "error.400.reviews_response_not_allowed",
+  errorUnknownTargetType: "error.400.reviews_unknown_target_type",
+  errorCannotModerate: "error.403.reviews_cannot_moderate",
+  errorCannotReview: "error.403.reviews_cannot_review",
+  errorReviewNotFound: "error.404.reviews_review_not_found",
+  errorAlreadyResponded: "error.409.reviews_already_responded",
+} as const;
+
+/**
+ * The English bundle: the generated backend fallbacks first, this pair's own
+ * UI copy over them. English is INLINE (not a separate subpath) so a host that
+ * registers nothing still renders sentences instead of raw keys.
+ */
+export const reviewsI18nBundleEn: I18nDictionary = {
+  ...reviewsErrorBundleEn,
+
+  "reviews.error.unknown": "Something went wrong with the reviews",
+
+  "reviews.list.heading": "Reviews",
+  "reviews.list.empty": "No reviews yet",
+  "reviews.list.load_more": "Show more",
+  "reviews.list.refresh": "Refresh",
+  "reviews.list.more.blocked.end": "That is all of them",
+  "reviews.list.more.blocked.pending": "Loading…",
+
+  "reviews.review.author_fallback": "A customer",
+  "reviews.review.response_heading": "Reply from the seller",
+
+  "reviews.status.pending": "Awaiting moderation",
+  "reviews.status.hidden": "Hidden by moderation",
+  "reviews.status.unknown": "Unknown state: {status}",
+
+  "reviews.rating.none": "No reviews yet",
+  "reviews.rating.value": "{avg} out of {max}",
+  "reviews.rating.count": "{count} reviews",
+  "reviews.rating.star_label": "{index} out of {max}",
+
+  "reviews.form.heading": "Rate this",
+  "reviews.form.rating_label": "Your rating",
+  "reviews.form.body_label": "Your review",
+  "reviews.form.body_placeholder": "What was the deal like? (optional)",
+  "reviews.form.submit": "Send",
+  "reviews.form.sent.published": "Thank you — your review is published",
+  "reviews.form.sent.pending":
+    "Thank you — your review will appear once it has been checked",
+  "reviews.form.sent.hidden": "Your review was saved but is not shown",
+  "reviews.form.sent.unknown": "Your review was saved",
+  "reviews.form.sign_in_required": "Sign in to leave a review",
+
+  "reviews.submit.blocked.no_rating": "Choose a rating first",
+  "reviews.submit.blocked.pending": "Sending…",
+  "reviews.submit.blocked.duplicate": "You have already rated this",
+  "reviews.submit.blocked.submitted": "Your review has been sent",
+  "reviews.submit.blocked.forbidden": "You cannot review this",
+};
+
+/** Register the English bundle into a core i18n engine. */
+export function registerReviewsI18n(engine: I18nEngine, locale = "en"): void {
+  engine.registerBundle(locale, reviewsI18nBundleEn);
+}

package/src/i18n/ru.ts

@@ -0,0 +1,85 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { reviewsErrorBundleRu } from "./generated/errors.ru.gen.js";
+
+export { reviewsErrorBundleRu } from "./generated/errors.ru.gen.js";
+
+/**
+ * Russian bundle for reviews-react — shipped as the
+ * `@stapel/reviews-react/i18n/ru` subpath (i18n-shipping.md §2) so the locale
+ * is opt-in: hosts that don't register it never carry these strings (the main
+ * entry does not import this module — gated by size-limit and the
+ * bundle-purity test).
+ *
+ * TWO SOURCES, ON PURPOSE. The generated `reviewsErrorBundleRu` covers the 42
+ * cross-cutting keys stapel-core owns and localizes. The 9 keys stapel-reviews
+ * owns are NOT in it, and cannot be: the module ships no `translations/`
+ * directory at all, so the generator emits a `Partial` bundle and says so in
+ * its own header (`ERRORS_LOCALE_EXEMPT_OWNERS`, the stapel-forms precedent).
+ * They are authored below, beside the UI copy. When upstream ships
+ * `translations/errors.ru.json`, these nine lines are deleted and the
+ * generated bundle covers them — the keys and the texts do not move.
+ */
+export const reviewsI18nBundleRu: I18nDictionary = {
+  // Backend error codes — generated ru texts for every key core owns.
+  ...reviewsErrorBundleRu,
+
+  // Backend error codes stapel-reviews owns — authored here (see the note
+  // above).
+  "error.400.reviews_duplicate_review": "Вы уже оценили это",
+  "error.400.reviews_invalid_moderation_action":
+    "Действие модерации должно быть одним из: скрыть, опубликовать",
+  "error.400.reviews_invalid_rating": "Оценка вне допустимого диапазона",
+  "error.400.reviews_response_not_allowed":
+    "Для этого типа объекта ответы отключены",
+  "error.400.reviews_unknown_target_type": "Неизвестный тип объекта отзыва",
+  "error.403.reviews_cannot_moderate":
+    "Вы не можете модерировать отзывы об этом объекте",
+  "error.403.reviews_cannot_review": "Вы не можете оставить отзыв об этом объекте",
+  "error.404.reviews_review_not_found": "Отзыв не найден",
+  "error.409.reviews_already_responded": "На этот отзыв уже есть ответ",
+
+  // UI copy.
+  "reviews.error.unknown": "С отзывами что-то пошло не так",
+
+  "reviews.list.heading": "Отзывы",
+  "reviews.list.empty": "Отзывов пока нет",
+  "reviews.list.load_more": "Показать ещё",
+  "reviews.list.refresh": "Обновить",
+  "reviews.list.more.blocked.end": "Это все отзывы",
+  "reviews.list.more.blocked.pending": "Загружаем…",
+
+  "reviews.review.author_fallback": "Покупатель",
+  "reviews.review.response_heading": "Ответ продавца",
+
+  "reviews.status.pending": "Ожидает модерации",
+  "reviews.status.hidden": "Скрыт модерацией",
+  "reviews.status.unknown": "Неизвестное состояние: {status}",
+
+  "reviews.rating.none": "Отзывов пока нет",
+  "reviews.rating.value": "{avg} из {max}",
+  "reviews.rating.count": "Отзывов: {count}",
+  "reviews.rating.star_label": "{index} из {max}",
+
+  "reviews.form.heading": "Оцените",
+  "reviews.form.rating_label": "Ваша оценка",
+  "reviews.form.body_label": "Ваш отзыв",
+  "reviews.form.body_placeholder": "Как прошла сделка? (необязательно)",
+  "reviews.form.submit": "Отправить",
+  "reviews.form.sent.published": "Спасибо — ваш отзыв опубликован",
+  "reviews.form.sent.pending":
+    "Спасибо — отзыв появится после проверки модератором",
+  "reviews.form.sent.hidden": "Отзыв сохранён, но не показывается",
+  "reviews.form.sent.unknown": "Отзыв сохранён",
+  "reviews.form.sign_in_required": "Войдите, чтобы оставить отзыв",
+
+  "reviews.submit.blocked.no_rating": "Сначала выберите оценку",
+  "reviews.submit.blocked.pending": "Отправляем…",
+  "reviews.submit.blocked.duplicate": "Вы уже оценили это",
+  "reviews.submit.blocked.submitted": "Ваш отзыв отправлен",
+  "reviews.submit.blocked.forbidden": "Вы не можете оставить здесь отзыв",
+};
+
+/** Register the Russian bundle into a core i18n engine. */
+export function registerReviewsI18nRu(engine: I18nEngine, locale = "ru"): void {
+  engine.registerBundle(locale, reviewsI18nBundleRu);
+}

package/src/index.ts

@@ -0,0 +1,161 @@
+/**
+ * `@stapel/reviews-react` — the headless React pair for stapel-reviews
+ * (frontend-standard §2). Business + state only, zero visual opinion; the antd
+ * skin lives behind the `./default` subpath, so a host that renders its own
+ * review block carries none of it.
+ *
+ * ── The one-liner ──────────────────────────────────────────────────────────
+ *
+ * ```tsx
+ * const runtime = createReviewsRuntime({ baseUrl: "/reviews/api/v1" });
+ * const target = { targetType: "listing", targetKey: listingId };
+ * <ReviewsProvider runtime={runtime}>
+ *   <ReviewAggregate target={target}>{(bag) => <YourStars bag={bag} />}</ReviewAggregate>
+ *   <ReviewList target={target}>{(bag) => <YourRows bag={bag} />}</ReviewList>
+ *   <ReviewForm target={target}>{(bag) => <YourForm bag={bag} />}</ReviewForm>
+ * </ReviewsProvider>
+ * ```
+ *
+ * `"listing"` in that snippet is the HOST's registry key, not this library's:
+ * stapel-reviews ships an EMPTY `TARGET_TYPES` registry and this package
+ * exports no target-type constants (see `api/types.ts`, `ReviewTarget`).
+ *
+ * ── The four properties this pair exists to guarantee ──────────────────────
+ *
+ * 1. **A zero average is not a zero rating.** `avg` is `0.0` when `count` is
+ *    `0`, by the module's own contract. `ratingSummary()` answers
+ *    `rated: false` there and gives a skin nothing to draw a star row from, so
+ *    "nobody has rated this yet" can never be rendered as the worst possible
+ *    score. Same class as `data ?? []`.
+ * 2. **The refusal is read by CODE, never by status.** "You have already
+ *    reviewed this" is `error.400.reviews_duplicate_review` — a 400 — while
+ *    the module's only 409 says the owner's reply already exists. Branching on
+ *    the number would miss the first and mishandle the second
+ *    (`model/refusals.ts`).
+ * 3. **A 401 is not an empty list.** Every stapel-reviews endpoint is
+ *    `IsAuthenticated`, including both reads, so a signed-out visitor to a
+ *    public listing page gets 401 — and the empty state would tell them a
+ *    well-reviewed seller has never been reviewed. `signInRequired` is a
+ *    named state on both read bags.
+ * 4. **A review that is not published says so.** `status` is carried to the
+ *    screen (`pending` / `hidden`, plus an explicit `unknown` arm for a state
+ *    a future backend adds), and the submit outcome reports the created row's
+ *    status, so a pre-moderating deployment tells the author their review is
+ *    waiting instead of leaving them to look for it.
+ *
+ * ── What this pair does NOT do ─────────────────────────────────────────────
+ *
+ * No moderation and no owner reply. `POST {id}/moderate` and
+ * `POST {id}/response` are both gated on the target type's fail-closed
+ * `can_moderate` callback and belong to consoles this pair does not ship
+ * (storefront spec §4.4: the reply is DISPLAYED, and the button to write one
+ * does not exist rather than existing switched off). Both stay in
+ * `manifest.json`, which lists the whole contract.
+ *
+ * No seller-wide rating fetch. The product model (spec fork F5) reviews the
+ * SELLER for a specific listing, so a seller's rating is a roll-up across
+ * their listings — which stapel-reviews cannot compute (one
+ * `(target_type, target_key)` per call) and the shop composite can
+ * (`shop.listing_review_summary`). `<ReviewAggregate aggregate={…}>` renders
+ * those two numbers from wherever the host got them; it does not invent an
+ * N+1 loop to fake the roll-up.
+ *
+ * No nav manifest: this pair has no route of its own. It renders INSIDE the
+ * listing detail page and the public seller profile, both of which belong to
+ * other pairs (the cdn-react precedent — a menu entry leading nowhere is
+ * worse than no entry).
+ *
+ * Layers: api → model → headless → i18n. Generated surfaces (the typed schema,
+ * the error map, the manifest, llms.txt) are produced by the monorepo `gen:*`
+ * drivers from stapel-reviews' own `docs/` artifacts and stand under drift
+ * gates.
+ */
+
+// ── api ──────────────────────────────────────────────────────────────────────
+export { createReviewsApi } from "./api/reviewsApi.js";
+export type { ReviewsApi } from "./api/reviewsApi.js";
+export type {
+  RatingAggregate,
+  Review,
+  ReviewAggregate as ReviewAggregateResponse,
+  ReviewAnchorDirection,
+  ReviewCreateRequest,
+  ReviewListParams,
+  ReviewOwnerResponse,
+  ReviewPage,
+  ReviewStatus,
+  ReviewTarget,
+  Schemas,
+} from "./api/types.js";
+
+// ── model ────────────────────────────────────────────────────────────────────
+export { createReviewsRuntime, DEFAULT_RATING_BOUNDS } from "./model/runtime.js";
+export type {
+  CreateReviewsRuntimeOptions,
+  ReviewRatingBounds,
+  ReviewsRuntime,
+} from "./model/runtime.js";
+export {
+  ReviewsRuntimeContext,
+  useReviewsAnalytics,
+  useReviewsApi,
+  useReviewsRuntime,
+} from "./model/context.js";
+export { reviewsQueryKeys } from "./model/queryKeys.js";
+export { REVIEWS_PAGE, useReviewAggregate, useReviewList } from "./model/queries.js";
+export type { UseReviewListOptions } from "./model/queries.js";
+export { useSubmitReview } from "./model/mutations.js";
+export type { SubmitReviewVariables } from "./model/mutations.js";
+export { ratingSummary, starBreakdown } from "./model/rating.js";
+export type { RatingSummary, StarBreakdown } from "./model/rating.js";
+export {
+  findOwnReview,
+  isModeratedOut,
+  reviewsFromPages,
+  reviewVisibility,
+} from "./model/list.js";
+export {
+  isDuplicateReview,
+  isReviewingForbidden,
+  isSignInRequired,
+  isUnknownTargetType,
+  REVIEWS_ERROR_ALREADY_RESPONDED,
+  REVIEWS_ERROR_CANNOT_MODERATE,
+  REVIEWS_ERROR_CANNOT_REVIEW,
+  REVIEWS_ERROR_DUPLICATE,
+  REVIEWS_ERROR_INVALID_RATING,
+  REVIEWS_ERROR_NOT_FOUND,
+  REVIEWS_ERROR_RESPONSE_NOT_ALLOWED,
+  REVIEWS_ERROR_UNKNOWN_TARGET_TYPE,
+  toReviewsError,
+} from "./model/refusals.js";
+
+// ── headless ─────────────────────────────────────────────────────────────────
+export { ReviewsProvider } from "./headless/ReviewsProvider.js";
+export { ReviewList } from "./headless/ReviewList.js";
+export type { ReviewListBag, ReviewListProps } from "./headless/ReviewList.js";
+export { ReviewAggregate } from "./headless/ReviewAggregate.js";
+export type {
+  ReviewAggregateBag,
+  ReviewAggregateProps,
+} from "./headless/ReviewAggregate.js";
+export { ReviewForm } from "./headless/ReviewForm.js";
+export type { ReviewFormBag, ReviewFormProps } from "./headless/ReviewForm.js";
+
+// ── i18n ─────────────────────────────────────────────────────────────────────
+export {
+  REVIEWS_I18N_KEYS,
+  registerReviewsI18n,
+  reviewsI18nBundleEn,
+} from "./i18n/keys.js";
+export {
+  explainReviewsError,
+  REVIEWS_ERROR_CODES,
+  REVIEWS_ERRORS,
+  reviewsErrorBundleEn,
+} from "./i18n/errorsMap.js";
+export type {
+  Remediation,
+  ReviewsErrorCode,
+  ReviewsErrorSpec,
+} from "./i18n/errorsMap.js";

package/src/model/context.tsx

@@ -0,0 +1,28 @@
+import type { Context } from "react";
+import { createModuleContext } from "@stapel/core";
+import type { Analytics, ModuleContextKit } from "@stapel/core";
+import type { ReviewsApi } from "../api/reviewsApi.js";
+import type { ReviewsRuntime } from "./runtime.js";
+
+/**
+ * The wired ReviewsRuntime shared through React context by
+ * `<ReviewsProvider>`. Hooks in `model/` and `headless/` read the singletons
+ * from here. One reviewed copy of this plumbing lives in `@stapel/core`
+ * (`createModuleContext`, slim wave §21/S2); this module binds it under the
+ * pair's public names.
+ */
+const kit: ModuleContextKit<ReviewsRuntime> =
+  createModuleContext<ReviewsRuntime>("Reviews");
+
+export const ReviewsRuntimeContext: Context<ReviewsRuntime | null> =
+  kit.RuntimeContext;
+
+export const useReviewsRuntime: () => ReviewsRuntime = kit.useRuntime;
+
+export const useReviewsApi: () => ReviewsApi = kit.useApi;
+
+export const useReviewsAnalytics: () => Analytics | null = kit.useAnalytics;
+
+/** @internal Re-exported as `<ReviewsProvider>` from `headless/`. */
+export const ModuleProvider: ModuleContextKit<ReviewsRuntime>["Provider"] =
+  kit.Provider;

package/src/model/list.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure readers over a loaded list of reviews — no React, no queries, so a
+ * card, a test and a server-rendered page can all use them.
+ */
+import type { InfiniteData } from "@tanstack/react-query";
+import type { Review, ReviewPage, ReviewStatus } from "../api/types.js";
+
+/**
+ * Flatten the pages of the infinite list into one newest-first run.
+ *
+ * Deliberately takes `InfiniteData | undefined` and answers `undefined` for
+ * "not loaded", never `[]`: an empty array here is a claim that the target
+ * has no reviews, and the caller must get that claim from a READY load state
+ * (`stapel/no-flattened-load-state` — the rule exists because a total outage
+ * once rendered as "you have no workspaces").
+ */
+export function reviewsFromPages(
+  data: InfiniteData<ReviewPage, string | undefined> | undefined
+): readonly Review[] | undefined {
+  if (data === undefined) return undefined;
+  return data.pages.flatMap((page) => page.items);
+}
+
+/**
+ * A review's visibility, narrowed — with a fourth arm for a state this build
+ * does not know.
+ *
+ * `status` is a bare `string` on the wire. A build that met a new upstream
+ * state and silently rendered it as published would be showing something the
+ * server may have hidden; one that crashed on it would take the page down.
+ * `"unknown"` is neither: the skin shows the row with an explicit "this
+ * version does not know this state" badge, the same shape attributes-react
+ * uses for an unsupported feature type.
+ */
+export function reviewVisibility(
+  status: string
+): ReviewStatus | "unknown" {
+  return status === "published" || status === "pending" || status === "hidden"
+    ? status
+    : "unknown";
+}
+
+/** Is this row one a moderator sees only because they asked for `include=all`? */
+export function isModeratedOut(review: Review): boolean {
+  return reviewVisibility(review.status) !== "published";
+}
+
+/**
+ * The viewer's own review of this target, if it is in the loaded rows.
+ *
+ * THIS IS AN OPTIMISTIC PRE-CHECK, AND IT HAS A KNOWN HOLE — recorded here
+ * because the hole is in the contract, not in the code. The list a
+ * non-moderator reads is published-only, so under `moderation: "pre"` the
+ * author's own review is INVISIBLE TO ITS AUTHOR while it waits: this
+ * function answers `undefined`, the form offers itself again, and the server
+ * refuses the second attempt with `error.400.reviews_duplicate_review`.
+ *
+ * That is why the refusal is a first-class outcome of the form
+ * (`headless/ReviewForm.tsx`) rather than something the pre-check was
+ * supposed to prevent. The pre-check saves a pointless round trip in the
+ * common (post-moderation) case; it is never the authority.
+ *
+ * `viewerId` must be the id the backend puts in `author_id` — the user id,
+ * NOT a profile id. A host that passes the wrong one gets `undefined`, i.e.
+ * the form offered where it need not have been, and the server still holds
+ * the line.
+ */
+export function findOwnReview(
+  reviews: readonly Review[] | undefined,
+  viewerId: string | null | undefined
+): Review | undefined {
+  if (reviews === undefined || !viewerId) return undefined;
+  return reviews.find((review) => review.author_id === viewerId);
+}

package/src/model/mutations.ts

@@ -0,0 +1,62 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import type { UseMutationOptions, UseMutationResult } from "@tanstack/react-query";
+import type { StapelApiError } from "@stapel/core";
+import type { Review, ReviewTarget } from "../api/types.js";
+import { useReviewsApi } from "./context.js";
+import { reviewsQueryKeys } from "./queryKeys.js";
+
+/** What {@link useSubmitReview} is called with. */
+export interface SubmitReviewVariables {
+  /** Inside the deployment's `[RATING_MIN, RATING_MAX]`; the server decides. */
+  readonly rating: number;
+  /** Optional — a rating with no words is a complete review here. */
+  readonly body?: string;
+}
+
+/**
+ * Write a review of a target (frontend-standard §2 — mutations invalidate on
+ * success).
+ *
+ * ── Why the answer is invalidated rather than spliced in ───────────────────
+ *
+ * The created row comes back with its `status`, and under the module's
+ * default (`MODERATION_DEFAULT: "post"`) that is `published` — so pushing it
+ * into the cached window would be correct. Under `moderation: "pre"` it is
+ * `pending`, and the SAME row must NOT appear in the list, because the list
+ * this reader sees is published-only and a locally-spliced pending review
+ * would vanish on the next refetch with no explanation.
+ *
+ * One behaviour for both policies, and the policy is not visible to the
+ * client (no endpoint reports it): invalidate, let the server say what is
+ * visible, and carry the created row separately as the SUBMISSION's outcome
+ * (`headless/ReviewForm.tsx` renders "sent, awaiting moderation" off its
+ * `status`). The aggregate moves for the same reason and is invalidated with
+ * it — `avg` and `count` only count published rows.
+ */
+export function useSubmitReview(
+  target: ReviewTarget
+): UseMutationResult<Review, StapelApiError, SubmitReviewVariables> {
+  const api = useReviewsApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<
+    Review,
+    StapelApiError,
+    SubmitReviewVariables
+  > = {
+    mutationFn: (vars) =>
+      api.createReview({
+        targetType: target.targetType,
+        targetKey: target.targetKey,
+        rating: vars.rating,
+        ...(vars.body !== undefined ? { body: vars.body } : {}),
+      }),
+    onSuccess: () => {
+      // Both scopes of the list: a moderator's `include=all` window holds the
+      // pending row this write may just have created.
+      void queryClient.invalidateQueries({
+        queryKey: reviewsQueryKeys.target(target),
+      });
+    },
+  };
+  return useMutation(options);
+}

package/src/model/queries.ts

@@ -0,0 +1,122 @@
+import { useInfiniteQuery, useQuery } from "@tanstack/react-query";
+import type {
+  InfiniteData,
+  UseInfiniteQueryResult,
+  UseQueryResult,
+} from "@tanstack/react-query";
+import { useActiveSessionReady } from "@stapel/core";
+import type { StapelApiError } from "@stapel/core";
+import type {
+  ReviewAggregate,
+  ReviewPage,
+  ReviewTarget,
+} from "../api/types.js";
+import { useReviewsApi } from "./context.js";
+import { reviewsQueryKeys } from "./queryKeys.js";
+
+/**
+ * Read hooks over the reviews API.
+ *
+ * ── Both reads are ANONYMOUS, and both still wait for the session ─────────
+ *
+ * Since stapel-reviews 0.3.0 a guest reads the list (`IsAuthenticatedOrReadOnly`)
+ * and the aggregate (`AllowAny`), so a public listing page shows its reviews
+ * to a visitor who will never sign in. Neither hook carries a
+ * "sign in first" state any more — that is now only true of the write.
+ *
+ * They are still gated on {@link useActiveSessionReady}, and the reason got
+ * STRONGER rather than weaker with the permission change. 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 silently narrowed to
+ * published. A read that races a still-bootstrapping session would therefore
+ * succeed — as a guest — and CACHE that answer under a key that does not
+ * mention identity. Before 0.3.0 the same race produced a 401, which was at
+ * least visible; a silently narrowed page is not. `useActiveSessionReady()`
+ * returns `true` the instant the session settles into any of
+ * authenticated / anonymous / unauthenticated, and immediately when no
+ * session-owning module is mounted at all — so a purely public storefront
+ * waits for nothing.
+ */
+
+/** Default page size for the review list — one screenful. */
+export const REVIEWS_PAGE = 20;
+
+export interface UseReviewListOptions {
+  /**
+   * Ask for pending/hidden rows too — honoured only for a moderator/owner of
+   * the target, and narrowed to published for anyone else WITHOUT an error.
+   * Part of the query key, because it selects a different set of rows.
+   */
+  readonly include?: "all";
+  readonly limit?: number;
+  /** Set `false` to hold the read (e.g. the target id is not resolved yet). */
+  readonly enabled?: boolean;
+}
+
+/**
+ * A target's reviews as an infinite (load-more) list, newest first.
+ *
+ * Pages are core's `AnchorPagination` envelope — which the schema does not
+ * declare (`api/types.ts`) — and the cursor is the previous page's
+ * `next_anchor`, a `created_at` timestamp. `has_next` is the authority on
+ * whether another page exists; a `next_anchor` is only read when it says yes,
+ * because the paginator leaves the anchor `null` on the last page and a
+ * cursor derived from the last row instead would re-request it forever.
+ */
+export function useReviewList(
+  target: ReviewTarget,
+  options: UseReviewListOptions = {}
+): UseInfiniteQueryResult<
+  InfiniteData<ReviewPage, string | undefined>,
+  StapelApiError
+> {
+  const api = useReviewsApi();
+  const sessionReady = useActiveSessionReady();
+  const limit = options.limit ?? REVIEWS_PAGE;
+  const addressable =
+    target.targetType.length > 0 && target.targetKey.length > 0;
+  return useInfiniteQuery({
+    queryKey: reviewsQueryKeys.list(target, options.include),
+    queryFn: ({ pageParam, signal }) =>
+      api.reviews(
+        {
+          ...target,
+          ...(options.include !== undefined ? { include: options.include } : {}),
+          direction: "next",
+          limit,
+          ...(pageParam !== undefined ? { anchor: pageParam } : {}),
+        },
+        { signal }
+      ),
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (last) =>
+      last.has_next ? (last.next_anchor ?? undefined) : undefined,
+    enabled: sessionReady && addressable && (options.enabled ?? true),
+  });
+}
+
+/**
+ * The module-owned aggregate for one target.
+ *
+ * NOT the way to put a rating on every card of a search result: that is one
+ * request per card against an endpoint that computes an `AVG` each time. The
+ * batch read exists (`reviews.aggregates_by_keys`) but it is a comm Function
+ * for a server-side projection, not an HTTP endpoint — a storefront gets
+ * per-card ratings from the composite's projection, embedded in the rows its
+ * catalogue module already serves, and renders them with
+ * {@link ratingSummary} without calling this at all.
+ */
+export function useReviewAggregate(
+  target: ReviewTarget,
+  options: { readonly enabled?: boolean } = {}
+): UseQueryResult<ReviewAggregate, StapelApiError> {
+  const api = useReviewsApi();
+  const sessionReady = useActiveSessionReady();
+  const addressable =
+    target.targetType.length > 0 && target.targetKey.length > 0;
+  return useQuery({
+    queryKey: reviewsQueryKeys.aggregate(target),
+    queryFn: ({ signal }) => api.aggregate(target, { signal }),
+    enabled: sessionReady && addressable && (options.enabled ?? true),
+  });
+}