@stapel/reviews-react 0.1.0

package/src/model/queryKeys.ts

@@ -0,0 +1,45 @@
+/**
+ * Namespaced TanStack Query keys (frontend-standard §2). Everything under the
+ * `"reviews"` root so a host can invalidate the whole module, one target, or
+ * one read.
+ *
+ * THE TARGET IS TWO STRINGS, AND BOTH ARE IN THE KEY. `target_key` alone is
+ * not an identity: the module groups by the PAIR, and two deployments'
+ * registries can key different things with the same opaque string (a listing
+ * `"42"` and a course `"42"`). A key built from `target_key` only would serve
+ * one target's reviews for the other.
+ *
+ * `include` is part of the list key for the same reason: `include=all` is a
+ * DIFFERENT set of rows (pending and hidden ones), and folding it into the
+ * published-only entry would let a moderator's window overwrite what every
+ * other reader sees.
+ */
+import type { ReviewTarget } from "../api/types.js";
+
+const ROOT = "reviews" as const;
+
+export const reviewsQueryKeys: {
+  readonly all: readonly ["reviews"];
+  /** Everything cached about one target. */
+  target(target: ReviewTarget): readonly ["reviews", string, string];
+  /** The anchor-paginated list window for one target and one visibility scope. */
+  list(
+    target: ReviewTarget,
+    include?: "all"
+  ): readonly ["reviews", string, string, "list", string];
+  /** The module-owned aggregate for one target. */
+  aggregate(
+    target: ReviewTarget
+  ): readonly ["reviews", string, string, "aggregate"];
+} = {
+  all: [ROOT],
+  target: (target) => [ROOT, target.targetType, target.targetKey],
+  list: (target, include) => [
+    ROOT,
+    target.targetType,
+    target.targetKey,
+    "list",
+    include ?? "published",
+  ],
+  aggregate: (target) => [ROOT, target.targetType, target.targetKey, "aggregate"],
+};

package/src/model/rating.ts

@@ -0,0 +1,101 @@
+/**
+ * What a rating MEANS, kept in one pure module so a card, a panel and a
+ * seller header cannot each decide differently.
+ *
+ * The whole file exists for one line of the contract: `avg` is `0.0` when
+ * `count` is `0` (`services.aggregate`, and `AggregateResponse`'s own
+ * description says so). Rendered naively that is a zero-star rating — the
+ * worst possible score — printed over a target nobody has rated yet. It is the
+ * same class of defect as `data ?? []`: a value that was never measured
+ * displayed as if it had been measured and found to be nothing.
+ *
+ * So {@link ratingSummary} answers `rated: false` for that case and the star
+ * row has nothing to draw. There is no way to get an `avg` out of this module
+ * without also getting the flag that says whether it means anything.
+ */
+import type { RatingAggregate } from "../api/types.js";
+
+/** An aggregate, read. */
+export type RatingSummary =
+  | {
+      /** Nobody has published a review of this target. */
+      readonly rated: false;
+      readonly count: 0;
+      /** Deliberately absent: there is no average of an empty set. */
+      readonly avg?: undefined;
+      readonly rounded?: undefined;
+    }
+  | {
+      readonly rated: true;
+      readonly count: number;
+      /** Mean over published reviews, as the server computed it (3 decimals). */
+      readonly avg: number;
+      /** The same mean at display precision — one decimal, half-up. */
+      readonly rounded: number;
+    };
+
+/**
+ * Round half-up to one decimal for display. `Math.round` is already half-up
+ * for positives and ratings are positive, but the float dance is written out
+ * so 4.25 → 4.3 rather than 4.2 (binary representation makes
+ * `Math.round(4.25 * 10)` unreliable across engines otherwise).
+ */
+function oneDecimal(value: number): number {
+  return Math.round((value + Number.EPSILON) * 10) / 10;
+}
+
+/**
+ * Read an aggregate — from this module's own `GET /reviews/aggregate`, or from
+ * the composite's `shop.listing_review_summary` projection, which answers the
+ * same two field names on purpose (`stapel_shop/projections.py`: "the owner's
+ * names ARE the contract shape here").
+ *
+ * A `count` of 0 is "not rated", whatever `avg` says. A negative or
+ * non-finite `count` is treated the same way rather than trusted: this is the
+ * one place a bad number can enter the display layer.
+ */
+export function ratingSummary(
+  aggregate: RatingAggregate | null | undefined
+): RatingSummary {
+  const count = aggregate?.count;
+  if (
+    aggregate === null ||
+    aggregate === undefined ||
+    typeof count !== "number" ||
+    !Number.isFinite(count) ||
+    count <= 0
+  ) {
+    return { rated: false, count: 0 };
+  }
+  const avg = Number.isFinite(aggregate.avg) ? aggregate.avg : 0;
+  return { rated: true, count, avg, rounded: oneDecimal(avg) };
+}
+
+/**
+ * How many whole, half and empty stars a `rounded` average draws, for a skin
+ * that renders stars rather than a number.
+ *
+ * `max` is the deployment's `RATING_MAX` (the runtime's `ratingBounds.max`),
+ * not a hardcoded five — a 1..10 deployment draws ten.
+ */
+export interface StarBreakdown {
+  readonly full: number;
+  readonly half: 0 | 1;
+  readonly empty: number;
+}
+
+export function starBreakdown(rounded: number, max: number): StarBreakdown {
+  const clamped = Math.min(Math.max(rounded, 0), max);
+  const full = Math.floor(clamped);
+  const remainder = clamped - full;
+  // A remainder of a quarter or more is a half star; anything less rounds
+  // away. The alternative — a partial-width star — is a skin's business, and
+  // this breakdown stays a count so a non-antd skin can use it too.
+  const half: 0 | 1 = remainder >= 0.25 && remainder < 0.75 ? 1 : 0;
+  const rounded_up = remainder >= 0.75 ? 1 : 0;
+  return {
+    full: full + rounded_up,
+    half,
+    empty: max - full - rounded_up - half,
+  };
+}

package/src/model/refusals.ts

@@ -0,0 +1,114 @@
+/**
+ * The refusals this pair has to tell apart, and the reason they are read by
+ * CODE and never by status.
+ *
+ * ── The trap ───────────────────────────────────────────────────────────────
+ *
+ * "You have already reviewed this" is a **400**
+ * (`ERR_400_DUPLICATE_REVIEW = "error.400.reviews_duplicate_review"`,
+ * `views.ReviewListCreateView.post`), not the 409 the situation reads like.
+ * And the module DOES answer 409 — for something else entirely:
+ * `error.409.reviews_already_responded`, which says the owner's reply already
+ * exists. A form that branched on `status === 409` would therefore miss the
+ * duplicate every time and mis-handle a refusal about a different object.
+ *
+ * That is why every predicate here compares a `FlowError.code`, folded
+ * through core's `toFlowError`, and why the codes are exported as named
+ * constants rather than typed at each call site.
+ *
+ * ── The other one worth naming ─────────────────────────────────────────────
+ *
+ * All four stapel-reviews views are `IsAuthenticated`, so a signed-out
+ * visitor gets 401 on the review LIST and on the AGGREGATE. Read as a
+ * generic failure that becomes "no reviews yet" under any code that defaults
+ * an empty array — a well-reviewed seller shown as unreviewed to exactly the
+ * people who have not signed up yet. {@link isSignInRequired} exists so the
+ * list bag can carry that as its own state and the skin can say the true
+ * thing.
+ */
+import { isErrorCode, toFlowError } from "@stapel/core";
+import type { FlowError } from "@stapel/core";
+
+/** The author already reviewed this target (`one_per_author`). A **400**. */
+export const REVIEWS_ERROR_DUPLICATE = "error.400.reviews_duplicate_review";
+/** `target_type` is not in the host's registry — or one of the pair was missing. */
+export const REVIEWS_ERROR_UNKNOWN_TARGET_TYPE =
+  "error.400.reviews_unknown_target_type";
+/** The rating fell outside `[RATING_MIN, RATING_MAX]`. */
+export const REVIEWS_ERROR_INVALID_RATING = "error.400.reviews_invalid_rating";
+/** The type's `can_review` callback said no. */
+export const REVIEWS_ERROR_CANNOT_REVIEW = "error.403.reviews_cannot_review";
+/** The type's `can_moderate` callback said no (fail-closed when unset). */
+export const REVIEWS_ERROR_CANNOT_MODERATE = "error.403.reviews_cannot_moderate";
+/** No review with that id. */
+export const REVIEWS_ERROR_NOT_FOUND = "error.404.reviews_review_not_found";
+/** Responses are switched off for this target type. */
+export const REVIEWS_ERROR_RESPONSE_NOT_ALLOWED =
+  "error.400.reviews_response_not_allowed";
+/** The review already carries the owner's reply — the module's ONLY 409. */
+export const REVIEWS_ERROR_ALREADY_RESPONDED =
+  "error.409.reviews_already_responded";
+
+/** Core's cross-cutting key for an unauthenticated call. */
+const HTTP_401_KEY = "stapel.http.401";
+
+/**
+ * Named, not inlined — the cdn-react precedent, for the same reason
+ * `stapel/no-adhoc-401` gives: the rule bans a bare `=== 401` because that
+ * shape is how ad hoc refresh/redirect logic gets written outside core's one
+ * seam. What happens here is not that. Nothing is refreshed, retried or
+ * redirected; the status is merely CLASSIFIED so a public page can say "sign
+ * in to read the reviews" instead of "this seller has no reviews". The real
+ * 401 handling stays on the client's `onAuthRefresh` seam and never reaches
+ * this file.
+ */
+const HTTP_UNAUTHORIZED = 401;
+
+/** Fold any thrown value into this pair's error dialect. */
+export function toReviewsError(error: unknown): FlowError {
+  return toFlowError(error, "reviews.error.unknown");
+}
+
+/**
+ * "You have already reviewed this target."
+ *
+ * Only ever true when the target type sets `one_per_author: true` — the
+ * registry default is `false` (`registry.resolve_policy`), and the catalogue
+ * shop preset turns it on for `listing`. A host whose policy allows several
+ * reviews will simply never see this.
+ */
+export function isDuplicateReview(error: unknown): boolean {
+  return isErrorCode(toReviewsError(error), REVIEWS_ERROR_DUPLICATE);
+}
+
+/**
+ * "This read needs a signed-in account." True for the 401 every endpoint of
+ * this module answers to an anonymous caller.
+ *
+ * Both halves are checked: core maps an un-keyed 401 body to
+ * `stapel.http.401`, but a deployment that puts its own `localizable_error`
+ * in a 401 body would arrive with that key instead — and it is still a 401.
+ */
+export function isSignInRequired(error: unknown): boolean {
+  const flow = toReviewsError(error);
+  return flow.status === HTTP_UNAUTHORIZED || isErrorCode(flow, HTTP_401_KEY);
+}
+
+/** The host's `can_review` callback refused this author for this target. */
+export function isReviewingForbidden(error: unknown): boolean {
+  return isErrorCode(toReviewsError(error), REVIEWS_ERROR_CANNOT_REVIEW);
+}
+
+/**
+ * The target type is not registered on this deployment.
+ *
+ * Worth its own predicate because the view answers it for TWO different
+ * situations: an unknown type, and a missing `target_type`/`target_key` on a
+ * GET (`views.py` — "a missing one is ERR_400_UNKNOWN_TARGET_TYPE, not an
+ * empty list/aggregate"). Either way it is a wiring fault in the host, not
+ * something the person reading the page can fix, which is why the skin shows
+ * it as an error rather than as an empty state.
+ */
+export function isUnknownTargetType(error: unknown): boolean {
+  return isErrorCode(toReviewsError(error), REVIEWS_ERROR_UNKNOWN_TARGET_TYPE);
+}

package/src/model/runtime.ts

@@ -0,0 +1,61 @@
+import { createModuleRuntime } from "@stapel/core";
+import type { CreateModuleRuntimeOptions, ModuleRuntime } from "@stapel/core";
+import { createReviewsApi } from "../api/reviewsApi.js";
+import type { ReviewsApi } from "../api/reviewsApi.js";
+
+/**
+ * Inclusive rating bounds. These mirror `STAPEL_REVIEWS["RATING_MIN"]` /
+ * `["RATING_MAX"]`, whose library defaults are 1 and 5 — and they are
+ * OVERRIDABLE here for the same reason cdn-react's size ceilings are: they
+ * are deployment knobs, not constants, and a hardwired client would refuse a
+ * rating the server would have accepted (a 1..10 deployment) or offer one it
+ * would refuse (a 1..3 one).
+ *
+ * There is no endpoint that reports them, so a host that moves the knob tells
+ * this pair too. The mirror is a UI affordance only: the star row draws
+ * `max - min + 1` choices, and the server remains the authority
+ * (`error.400.reviews_invalid_rating`).
+ */
+export interface ReviewRatingBounds {
+  readonly min: number;
+  readonly max: number;
+}
+
+/** stapel-reviews' own defaults (`conf.DEFAULTS`). */
+export const DEFAULT_RATING_BOUNDS: ReviewRatingBounds = { min: 1, max: 5 };
+
+/**
+ * The wired reviews runtime — core's `ModuleRuntime` bound to this pair's API
+ * (slim wave §21/S2), plus the deployment's rating bounds. The returned
+ * `client` is what the host injects into core's `StapelConfigProvider` (as the
+ * default or the `"reviews"` module client), preserving the client-injection
+ * fork seam (frontend-standard §7.2).
+ *
+ * MEMBER-ONLY, AND THE PAIR SAYS SO. Unlike categories-react, every endpoint
+ * behind this runtime is `IsAuthenticated` — a signed-out visitor gets 401 on
+ * the review list and on the aggregate. The read hooks are therefore gated on
+ * `useActiveSessionReady()` (so a bootstrapping session is not mistaken for an
+ * anonymous one) and the 401 is surfaced as a named "sign in to see reviews"
+ * state instead of an empty list.
+ */
+export type ReviewsRuntime = ModuleRuntime<ReviewsApi> & {
+  readonly ratingBounds: ReviewRatingBounds;
+};
+
+export interface CreateReviewsRuntimeOptions extends CreateModuleRuntimeOptions {
+  /** Mirror of the deployment's `RATING_MIN`/`RATING_MAX`. Defaults to 1..5. */
+  readonly ratingBounds?: Partial<ReviewRatingBounds>;
+}
+
+export function createReviewsRuntime(
+  options: CreateReviewsRuntimeOptions
+): ReviewsRuntime {
+  const runtime = createModuleRuntime(createReviewsApi, options);
+  return {
+    ...runtime,
+    ratingBounds: {
+      min: options.ratingBounds?.min ?? DEFAULT_RATING_BOUNDS.min,
+      max: options.ratingBounds?.max ?? DEFAULT_RATING_BOUNDS.max,
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "_comment": "Self-contained on purpose: standalone-buildable per frontend-standard §7. Mirrors the root tsconfig.base.json settings.",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "isolatedModules": true,
+    "isolatedDeclarations": true,
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}