@stapel/reviews-react 0.1.0

package/src/api/generated/schema.ts

@@ -0,0 +1,362 @@
+// AUTO-GENERATED by scripts/gen-api.mjs — do not edit by hand.
+// Source: the backend module's own docs/schema.json (§17-native per-module contract).
+// Regenerate: pnpm gen:api   ·   Drift gate: pnpm gen:api:check
+export interface paths {
+    "/reviews/api/v1/reviews": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * @description List a target's reviews (anchor-paginated, published-only for
+         *     non-moderators), or create a review.
+         *
+         *     ``GET`` is anonymously readable (storefront F5 verdict,
+         *     the storefront spec §13.8 note 2) — published-only filtering
+         *     already guarantees a guest sees nothing a moderator would need to hide.
+         *     ``POST`` still requires a real identity (there is an author to attribute
+         *     the review to), so the class gate is DRF's own
+         *     ``IsAuthenticatedOrReadOnly`` (mirrors ``ListingViewSet`` in
+         *     stapel-listings — the fleet's other read-open/write-authenticated view in
+         *     a single class) rather than a per-method override.
+         *
+         *     **Permissions:** `IsAuthenticatedOrReadOnly`
+         */
+        get: operations["reviews_api_v1_reviews_retrieve"];
+        put?: never;
+        /**
+         * @description List a target's reviews (anchor-paginated, published-only for
+         *     non-moderators), or create a review.
+         *
+         *     ``GET`` is anonymously readable (storefront F5 verdict,
+         *     the storefront spec §13.8 note 2) — published-only filtering
+         *     already guarantees a guest sees nothing a moderator would need to hide.
+         *     ``POST`` still requires a real identity (there is an author to attribute
+         *     the review to), so the class gate is DRF's own
+         *     ``IsAuthenticatedOrReadOnly`` (mirrors ``ListingViewSet`` in
+         *     stapel-listings — the fleet's other read-open/write-authenticated view in
+         *     a single class) rather than a per-method override.
+         *
+         *     **Permissions:** `IsAuthenticatedOrReadOnly`
+         */
+        post: operations["reviews_api_v1_reviews_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/reviews/api/v1/reviews/{review_id}/moderate": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * @description Hide or publish a review (moderation; owner/moderator-only via the
+         *     target type's can_moderate callback).
+         *
+         *     **Permissions:** `IsAuthenticated`
+         */
+        post: operations["reviews_api_v1_reviews_moderate_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/reviews/api/v1/reviews/{review_id}/response": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * @description Attach the target owner's single reply to a review (owner-only via the
+         *     target type's can_moderate callback; gated by the allow_response policy).
+         *
+         *     **Permissions:** `IsAuthenticated`
+         */
+        post: operations["reviews_api_v1_reviews_response_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/reviews/api/v1/reviews/aggregate": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * @description The module-owned rating aggregate (avg/count over published reviews)
+         *     for a target.
+         *
+         *     Anonymously readable for the same reason as the list's ``GET``
+         *     (storefront F5 verdict, the storefront spec §13.8 note 2): the
+         *     aggregate is computed over published reviews only, so a guest learns
+         *     nothing a moderator would need withheld.
+         *
+         *     **Permissions:** `AllowAny`
+         */
+        get: operations["reviews_api_v1_reviews_aggregate_retrieve"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        /** @description Rating aggregate for a target over published reviews. */
+        AggregateResponse: {
+            /** @description The host-registered target-type key */
+            target_type: string;
+            /** @description Opaque host-owned target identifier */
+            target_key: string;
+            /**
+             * Format: double
+             * @description Mean rating (0.0 when count is 0)
+             */
+            avg: number;
+            /** @description Number of published reviews */
+            count: number;
+        };
+        /** @description Moderate a review. */
+        ModerateRequest: {
+            /** @description hide or publish */
+            action: string;
+            /** @description Optional moderation reason (carried in the emitted fact) */
+            reason?: string;
+        };
+        /** @description Attach the target owner's reply to a review. */
+        RespondRequest: {
+            /** @description Reply text */
+            body?: string;
+        };
+        /** @description A target owner's reply to a review. */
+        ResponseResponse: {
+            /** @description The responder's user id (the target owner) */
+            author_id: string;
+            /** @description Reply text */
+            body: string;
+            /**
+             * Format: date-time
+             * @description When the reply was written
+             */
+            created_at: string;
+        };
+        /** @description Create a review. */
+        ReviewCreateRequest: {
+            /** @description The host-registered target-type key */
+            target_type: string;
+            /** @description Opaque host-owned target identifier */
+            target_key: string;
+            /** @description Numeric rating (RATING_MIN..RATING_MAX) */
+            rating: number;
+            /** @description Optional review body */
+            body?: string;
+        };
+        /**
+         * @description The envelope ``GET /reviews`` actually returns — ``AnchorPagination``'s
+         *     keys (``stapel_core.django.api.pagination.AnchorPagination.
+         *     get_paginated_response``/``get_paginated_response_schema``) wrapping
+         *     ``items``. Schema-only: ``ReviewListCreateView`` is a bare ``APIView``
+         *     (views.py), so drf-spectacular's pagination auto-introspection — which
+         *     only fires for ``GenericAPIView.pagination_class`` — never sees
+         *     ``ReviewAnchorPagination``, and the envelope has to be declared by hand
+         *     or spectacular renders the response as a bare array
+         *     (the storefront spec §13.8 note 3).
+         */
+        ReviewPage: {
+            items: components["schemas"]["ReviewResponse"][];
+            next_anchor: string | null;
+            prev_anchor: string | null;
+            has_next: boolean;
+            has_prev: boolean;
+            count: number;
+        };
+        /** @description A review of an opaque target. */
+        ReviewResponse: {
+            /** @description Review id (UUID) */
+            id: string;
+            /** @description The host-registered target-type key */
+            target_type: string;
+            /** @description Opaque host-owned target identifier */
+            target_key: string;
+            /** @description Reviewer's user id */
+            author_id: string;
+            /** @description Numeric rating (RATING_MIN..RATING_MAX) */
+            rating: number;
+            /** @description Free-text review body */
+            body: string;
+            /** @description pending/published/hidden */
+            status: string;
+            /**
+             * Format: date-time
+             * @description Creation time
+             */
+            created_at: string;
+            /** @description The owner's reply, if any */
+            response?: components["schemas"]["ResponseResponse"] | null;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    reviews_api_v1_reviews_retrieve: {
+        parameters: {
+            query: {
+                /** @description Opaque cursor: a `next_anchor`/`prev_anchor` from a previous page (the review's `created_at`). Omit for the first page. */
+                anchor?: string;
+                /** @description Which side of `anchor` to page toward. Default `next`. */
+                direction?: "center" | "next" | "prev";
+                /** @description Omit for published-only. `all` additionally asks for pending/hidden reviews, but is honored only for a moderator/owner of the target (the type's can_moderate callback) — a non-moderator asking for `all` is silently narrowed to published, never an error. */
+                include?: string;
+                /** @description Page size, default 20, max 100. */
+                limit?: number;
+                /** @description Opaque host-owned target identifier. */
+                target_key: string;
+                /** @description Host-registered target-type key (registry.py). */
+                target_type: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ReviewPage"];
+                };
+            };
+        };
+    };
+    reviews_api_v1_reviews_create: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ReviewCreateRequest"];
+                "application/x-www-form-urlencoded": components["schemas"]["ReviewCreateRequest"];
+                "multipart/form-data": components["schemas"]["ReviewCreateRequest"];
+            };
+        };
+        responses: {
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ReviewResponse"];
+                };
+            };
+        };
+    };
+    reviews_api_v1_reviews_moderate_create: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                review_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ModerateRequest"];
+                "application/x-www-form-urlencoded": components["schemas"]["ModerateRequest"];
+                "multipart/form-data": components["schemas"]["ModerateRequest"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ReviewResponse"];
+                };
+            };
+        };
+    };
+    reviews_api_v1_reviews_response_create: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                review_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["RespondRequest"];
+                "application/x-www-form-urlencoded": components["schemas"]["RespondRequest"];
+                "multipart/form-data": components["schemas"]["RespondRequest"];
+            };
+        };
+        responses: {
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ReviewResponse"];
+                };
+            };
+        };
+    };
+    reviews_api_v1_reviews_aggregate_retrieve: {
+        parameters: {
+            query: {
+                /** @description Opaque host-owned target identifier. */
+                target_key: string;
+                /** @description Host-registered target-type key (registry.py). */
+                target_type: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AggregateResponse"];
+                };
+            };
+        };
+    };
+}

package/src/api/reviewsApi.ts

@@ -0,0 +1,170 @@
+import type { StapelClient, StapelRequestOptions } from "@stapel/core";
+import type {
+  Review,
+  ReviewAggregate,
+  ReviewListParams,
+  ReviewPage,
+  ReviewTarget,
+} from "./types.js";
+
+/**
+ * CSRF rule for cookie-authenticated browser clients (mirrors auth-react and
+ * chat-react): the simplest SPA rule is to always send
+ * `X-Requested-With: XMLHttpRequest` on mutating requests. Header-token
+ * clients ignore it, so it is harmless there and every mutation carries it.
+ */
+const CSRF_HEADERS: Record<string, string> = {
+  "X-Requested-With": "XMLHttpRequest",
+};
+
+function mutating(
+  options?: Omit<StapelRequestOptions, "method" | "body">
+): Omit<StapelRequestOptions, "method" | "body"> {
+  return { ...options, headers: { ...CSRF_HEADERS, ...options?.headers } };
+}
+
+/** The target pair, as the two endpoints that read it spell it. */
+function targetQuery(target: ReviewTarget): Record<string, string> {
+  return { target_type: target.targetType, target_key: target.targetKey };
+}
+
+/**
+ * The pair's typed operation surface — one method per stapel-reviews endpoint
+ * a buyer's or a seller's browser may call, bound to the injected
+ * {@link StapelClient} (the per-module override seam of frontend-standard
+ * §7.2). Paths are relative to the runtime's `baseUrl` (`/reviews/api/v1`).
+ *
+ * ── The two reads are ANONYMOUS; the write is not ─────────────────────────
+ *
+ * Since stapel-reviews 0.3.0: `ReviewListCreateView` is
+ * `IsAuthenticatedOrReadOnly` (GET open, POST still needs a real identity —
+ * there is an author to attribute the review to) and `AggregateView` is
+ * `AllowAny`. Both declare `stapel_anonymous_access = ANONYMOUS_ALLOWED` and
+ * both are throttled from the module's own settings namespace
+ * (`LIST_THROTTLE` 120/min, `AGGREGATE_THROTTLE` 300/min), not the project's
+ * `DEFAULT_THROTTLE_RATES`.
+ *
+ * Nothing new became visible: both endpoints were already published-only for
+ * a non-moderator. What changed for this pair is that a guest on a public
+ * listing page now READS the reviews instead of being told to sign in — so
+ * `signInRequired` is gone from the two read bags and survives only on the
+ * write, where a 401 is still the honest answer.
+ *
+ * ── The two operations that are NOT here, and why ─────────────────────────
+ *
+ * `POST /reviews/{id}/moderate` (hide/publish) and `POST /reviews/{id}/response`
+ * (the target owner's single reply) are both gated on the target type's
+ * `can_moderate` callback, which is **fail-closed**: a type that names no
+ * callback denies everyone (`registry.check_can_moderate`). They belong to a
+ * seller console and a moderator console, and this pair ships neither
+ * (storefront spec §4.4: the owner's reply is DISPLAYED in the MVP and the
+ * button to write one does not exist, rather than existing switched off).
+ *
+ * Both stay in the generated schema and therefore in `manifest.json`, which
+ * lists the whole contract — nothing is hidden; they are simply not this
+ * pair's surface. Adding them later is additive and needs no change here.
+ *
+ * These operations will be GENERATED from schema.json operationIds by gen-api
+ * v2; until then they are hand-authored here (the ONE legal home of path
+ * strings — `stapel/no-string-paths` §2.3 carve-out).
+ */
+export interface ReviewsApi {
+  readonly client: StapelClient;
+
+  /**
+   * A page of a target's reviews, newest first. Anonymous callers welcome.
+   *
+   * Answers core's `AnchorPagination` envelope — declared as
+   * `components/ReviewPage` since 0.3.0, so the shape is generated rather
+   * than mirrored here. Anchors are `created_at` timestamps.
+   */
+  reviews(
+    params: ReviewListParams,
+    options?: { readonly signal?: AbortSignal }
+  ): Promise<ReviewPage>;
+
+  /**
+   * The module-owned rating aggregate for ONE target — mean and count over
+   * published reviews. `AllowAny`.
+   *
+   * There is no batch form on the HTTP surface: `reviews.aggregates_by_keys`
+   * is a comm Function for server-side projections, not an endpoint. A
+   * storefront that needs a rating per card gets it from the listing rows its
+   * own module serves (fed by the composite's projection), not by firing one
+   * of these per card.
+   */
+  aggregate(
+    target: ReviewTarget,
+    options?: { readonly signal?: AbortSignal }
+  ): Promise<ReviewAggregate>;
+
+  /**
+   * Write a review of a target. The one operation here that needs a real
+   * identity (`IsAuthenticatedOrReadOnly` refuses an anonymous POST).
+   *
+   * Refusals worth knowing by name, because their STATUS is not what a reader
+   * expects: "you have already reviewed this" is
+   * `error.400.reviews_duplicate_review` — a **400**, while the module's only
+   * 409 (`error.409.reviews_already_responded`) is about the owner's reply.
+   * Branching on the status code would therefore catch the wrong refusal;
+   * `model/submit.ts` branches on the code.
+   */
+  createReview(
+    body: {
+      readonly targetType: string;
+      readonly targetKey: string;
+      readonly rating: number;
+      readonly body?: string;
+    },
+    options?: { readonly signal?: AbortSignal }
+  ): Promise<Review>;
+}
+
+const signalOf = (options?: {
+  readonly signal?: AbortSignal;
+}): { signal?: AbortSignal } =>
+  options?.signal !== undefined ? { signal: options.signal } : {};
+
+export function createReviewsApi(client: StapelClient): ReviewsApi {
+  return {
+    client,
+
+    reviews: (params, options) =>
+      client.get("/reviews", {
+        query: {
+          ...targetQuery(params),
+          ...(params.include !== undefined ? { include: params.include } : {}),
+          ...(params.anchor !== undefined ? { anchor: params.anchor } : {}),
+          ...(params.direction !== undefined
+            ? { direction: params.direction }
+            : {}),
+          ...(params.limit !== undefined ? { limit: params.limit } : {}),
+        },
+        ...signalOf(options),
+      }),
+
+    aggregate: (target, options) =>
+      client.get("/reviews/aggregate", {
+        query: targetQuery(target),
+        ...signalOf(options),
+      }),
+
+    createReview: (body, options) =>
+      client.post(
+        "/reviews",
+        {
+          target_type: body.targetType,
+          target_key: body.targetKey,
+          rating: body.rating,
+          // The body defaults to `""` in the request DTO
+          // (`dto.ReviewCreateRequest.body: str = ""`) — a rating with no
+          // words is a complete review here. Send the field only when there
+          // is text, so an empty textarea is not spelled two ways.
+          ...(body.body !== undefined && body.body.length > 0
+            ? { body: body.body }
+            : {}),
+        },
+        mutating(signalOf(options))
+      ),
+  };
+}

package/src/api/types.ts

@@ -0,0 +1,140 @@
+/**
+ * The pair's public wire types — projected from the GENERATED schema
+ * (`api/generated/schema.ts`, emitted by `pnpm gen:api` from stapel-reviews'
+ * own `docs/schema.json`), never re-typed by hand.
+ *
+ * **Two hand-written shapes lived here against the 0.2.2 pin and are gone.**
+ * `ReviewPage` and the list's `anchor`/`limit`/`direction` parameters were
+ * declared by this file because `ReviewListCreateView` is a bare `APIView`
+ * that instantiates its paginator inside `get()`: drf-spectacular's pagination
+ * introspection only fires for `GenericAPIView.pagination_class`, so the
+ * schema declared `200: ReviewResponse[]` and knew nothing of the three query
+ * parameters. **stapel-reviews 0.3.0 declares both** — `components/ReviewPage`
+ * and the parameters, `direction` with an enum — so the copies were deleted
+ * and everything below comes from codegen. The upstream ask that produced this
+ * is recorded in `contract-pins.json`.
+ *
+ * Two corrections remain, and both are widenings of what the wire can say
+ * rather than shapes the schema is missing:
+ *
+ * 1. **`status` is a bare `string` on the wire** and a three-member lifecycle
+ *    in the model (`ReviewStatus`). {@link ReviewStatus} names the three
+ *    WITHOUT narrowing a parsed value: a fourth state added upstream must
+ *    render as an unknown state, not crash a switch.
+ * 2. **`avg` is `0.0` when `count` is `0`.** The type cannot express that, so
+ *    {@link RatingAggregate} exists as the shape both this module's own
+ *    aggregate endpoint AND the shop composite's `shop.listing_review_summary`
+ *    projection answer with — and `model/rating.ts` is the one place allowed
+ *    to decide what a zero means.
+ */
+import type { components, operations } from "./generated/schema.js";
+
+/** Every component schema stapel-reviews declares. */
+export type Schemas = components["schemas"];
+
+/** One review of an opaque target, with the owner's reply when there is one. */
+export type Review = Schemas["ReviewResponse"];
+
+/** The target owner's single reply to a review. */
+export type ReviewOwnerResponse = Schemas["ResponseResponse"];
+
+/** `POST /reviews` request body. */
+export type ReviewCreateRequest = Schemas["ReviewCreateRequest"];
+
+/**
+ * `GET /reviews/aggregate` 200 body — the module-owned aggregate for ONE
+ * target, carrying the target it is about.
+ */
+export type ReviewAggregate = Schemas["AggregateResponse"];
+
+/**
+ * The 200 body of `GET /reviews` — core's `AnchorPagination` envelope,
+ * generated since 0.3.0 (see this module's header).
+ *
+ * `count` is the number of rows in THIS page, not the total; the total number
+ * of published reviews is the aggregate's `count`, which is a different number
+ * computed a different way.
+ */
+export type ReviewPage = Schemas["ReviewPage"];
+
+/** The generated query surface of `GET /reviews`. */
+type ReviewListQuery = NonNullable<
+  operations["reviews_api_v1_reviews_retrieve"]["parameters"]["query"]
+>;
+
+/**
+ * A review's visibility, as `models.ReviewStatus` spells it.
+ *
+ * - `published` — visible to everyone and counted in the aggregate.
+ * - `pending` — created under PRE-moderation; invisible until a moderator
+ *   publishes it, **including to its own author**, who therefore cannot see
+ *   the review they just wrote in the published-only list.
+ * - `hidden` — moderated out; invisible and excluded from the aggregate.
+ *
+ * Only reachable in a list response when the caller asked for `include=all`
+ * AND the target type's `can_moderate` callback said yes; a non-moderator's
+ * `include=all` is silently narrowed to published (`views.py`).
+ */
+export type ReviewStatus = "pending" | "published" | "hidden";
+
+/**
+ * The two halves of the module's opaque address. There is no foreign key
+ * anywhere in stapel-reviews: `target_type` is a key the HOST registered in
+ * `STAPEL_REVIEWS["TARGET_TYPES"]` (the built-in registry is EMPTY) and
+ * `target_key` is a host-owned string the module stores, groups by, and never
+ * parses.
+ *
+ * This package therefore ships no target-type constants — not even
+ * `"listing"`. The catalogue shop composite registers that name in its own
+ * preset (`stapel_shop/preset.py`), a different deployment registers
+ * `"seller"` or `"course"`, and a library that guessed would be wrong for
+ * every host but one.
+ */
+export interface ReviewTarget {
+  readonly targetType: string;
+  readonly targetKey: string;
+}
+
+/** The rating roll-up itself, without the target it belongs to.
+ *
+ * Deliberately the same two field names the composite's projection uses
+ * (`shop.listing_review_summary` → `{avg, count}`, `stapel_shop/models.py`):
+ * a seller-level rating is computed by the composite and handed to this
+ * pair's display as data, because stapel-reviews can only aggregate ONE
+ * `(target_type, target_key)` at a time and has no roll-up endpoint. Same
+ * shape in, same rendering out — see {@link ratingSummary}. */
+export interface RatingAggregate {
+  /** Mean rating over PUBLISHED reviews. `0` when `count` is `0` — which is
+   * "nobody has rated this", never "everyone rated it zero". */
+  readonly avg: number;
+  /** Number of published reviews. */
+  readonly count: number;
+}
+
+/**
+ * Anchor-pagination direction — the enum the schema now carries. The review
+ * list is ordered `-created_at`, so:
+ *
+ * - `next` (default) — reviews OLDER than the anchor (the load-more direction),
+ * - `prev` — reviews NEWER than the anchor,
+ * - `center` — a window around the anchor.
+ */
+export type ReviewAnchorDirection = NonNullable<ReviewListQuery["direction"]>;
+
+/**
+ * Query for `GET /reviews`: the generated parameters, with only the target
+ * pair renamed to this package's camelCase {@link ReviewTarget}. Nothing here
+ * is hand-typed any more — `include`, `anchor`, `limit` and `direction` are
+ * exactly what the contract declares.
+ *
+ * `target_type`/`target_key` are required by the view (a missing one is
+ * `error.400.reviews_unknown_target_type`, not an empty list). `anchor` is a
+ * `created_at` ISO timestamp and exclusive. `include` is typed `string`
+ * because the schema declares no enum for it: the view acts on the literal
+ * `"all"` and treats anything else as published-only, silently — which is why
+ * the hook option that offers it (`UseReviewListOptions.include`) narrows to
+ * the one value the server actually reads.
+ */
+export interface ReviewListParams
+  extends ReviewTarget,
+    Omit<ReviewListQuery, "target_type" | "target_key"> {}