@stapel/reviews-react 0.1.0

package/dist/model/runtime.d.ts

@@ -0,0 +1,44 @@
+import type { CreateModuleRuntimeOptions, ModuleRuntime } from "@stapel/core";
+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 declare const DEFAULT_RATING_BOUNDS: ReviewRatingBounds;
+/**
+ * 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 declare function createReviewsRuntime(options: CreateReviewsRuntimeOptions): ReviewsRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/model/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/model/runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,0BAA0B,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,sDAAsD;AACtD,eAAO,MAAM,qBAAqB,EAAE,kBAAuC,CAAC;AAE5E;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,CAAC,UAAU,CAAC,GAAG;IACvD,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;CAC3C,CAAC;AAEF,MAAM,WAAW,2BAA4B,SAAQ,0BAA0B;IAC7E,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACrD;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,2BAA2B,GACnC,cAAc,CAShB"}

package/dist/model/runtime.js

@@ -0,0 +1,15 @@
+import { createModuleRuntime } from "@stapel/core";
+import { createReviewsApi } from "../api/reviewsApi.js";
+/** stapel-reviews' own defaults (`conf.DEFAULTS`). */
+export const DEFAULT_RATING_BOUNDS = { min: 1, max: 5 };
+export function createReviewsRuntime(options) {
+    const runtime = createModuleRuntime(createReviewsApi, options);
+    return {
+        ...runtime,
+        ratingBounds: {
+            min: options.ratingBounds?.min ?? DEFAULT_RATING_BOUNDS.min,
+            max: options.ratingBounds?.max ?? DEFAULT_RATING_BOUNDS.max,
+        },
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/model/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/model/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAqBxD,sDAAsD;AACtD,MAAM,CAAC,MAAM,qBAAqB,GAAuB,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;AAyB5E,MAAM,UAAU,oBAAoB,CAClC,OAAoC;IAEpC,MAAM,OAAO,GAAG,mBAAmB,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IAC/D,OAAO;QACL,GAAG,OAAO;QACV,YAAY,EAAE;YACZ,GAAG,EAAE,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,qBAAqB,CAAC,GAAG;YAC3D,GAAG,EAAE,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,qBAAqB,CAAC,GAAG;SAC5D;KACF,CAAC;AACJ,CAAC"}

package/llms.txt

@@ -0,0 +1,80 @@
+# @stapel/reviews-react 0.1.0
+
+Headless React flow pair for stapel-reviews (contract >=0.3 <0.4) — business + state, zero visual opinion.
+Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
+verification-403 interception, i18n engine, analytics facade, TanStack Query layer.
+
+## The one right way (do this, the rest is a review/lint smell)
+- No raw fetch/axios. The client is injected via <ReviewsProvider>/StapelConfigProvider;
+  every hook and flow already carries auth, refresh, and the error envelope.
+- Render errors, never try/catch them: a flow's state carries FlowError{code,params};
+  render `t(code, params)` and branch on `explainReviewsError(code)` remediation.
+- Server state = the use* hooks (query layer); keys come only from reviewsQueryKeys.
+- User strings = i18n keys (registerReviewsI18n); never string literals.
+- Sign-in UI = a headless flow component; copy it (shadcn-style) to restyle.
+
+## Layers
+api (typed client) · model (hooks, session) · flows (machines) · headless · i18n
+
+## Documented flows (flows.json — canonical id, steps, endpoints)
+
+## Operations (typed; use the named op, never a path string)
+Request/response schema names are in manifest.json + the generated types.
+Paths are relative to `/reviews/api/v1/`.
+- reviews_api_v1_reviews_aggregate_retrieve: GET /reviews/aggregate
+- reviews_api_v1_reviews_create: POST /reviews
+- reviews_api_v1_reviews_moderate_create: POST /reviews/{review_id}/moderate
+- reviews_api_v1_reviews_response_create: POST /reviews/{review_id}/response
+- reviews_api_v1_reviews_retrieve: GET /reviews
+
+## Query hooks (server state; keys come only from the key factory)
+- useReviewAggregate (query) → aggregate
+- useSubmitReview (mutation) → createReview
+
+## Errors (render t(code, params); UX from remediation)
+51 keys (full catalog: manifest.json §errors). By remediation: fix_input 22 · retry 16 · verify 5 · wait_and_retry 5 · contact_support 2 · reauthenticate 1.
+Param-bearing keys (interpolation slots matter):
+- error.400.field.blank [400] → fix_input {field}
+- error.400.field.does_not_exist [400] → fix_input {field}
+- error.400.field.invalid [400] → fix_input {field}
+- error.400.field.invalid_choice [400] → fix_input {field}
+- error.400.field.max_length [400] → fix_input {field,max_length}
+- error.400.field.max_value [400] → fix_input {field,max_value}
+- error.400.field.min_length [400] → fix_input {field,min_length}
+- error.400.field.min_value [400] → fix_input {field,min_value}
+- error.400.field.null [400] → fix_input {field}
+- error.400.field.required [400] → fix_input {field}
+- error.400.field.unique [400] → fix_input {field}
+- error.429.rate_limit [429] → wait_and_retry {retry_after_minutes}
+
+## Analytics events (typed; defineEvent → events.json, drift-gated)
+- (no app defineEvent() in this pair — its analytic events are the
+  auto-instrumented flow funnels below)
+
+## Flow funnels (auto-instrumented: flow.<id>.<step> {phase})
+
+```tsx
+// Typed event + tracked() click (the one right way; §3.1).
+const planSelected = defineEvent({
+  name: "pricing.plan.selected",
+  description: "User picked a plan",
+  props: { plan: prop.oneOf(["free", "pro", "team"], "Plan code") },
+});
+const { tracked } = useTracked();
+<Button onClick={tracked(planSelected, { plan }, startCheckout)} />
+// A click that STEPS a flow machine is already instrumented — mark it
+// data-analytics="flow" instead; tracked() on top double-counts (§3.2).
+```
+
+## Demos (defineDemo → manifest.demos; compiled, linted, rendered examples)
+- reviews.aggregate → <ReviewAggregate> [rated|never rated|seller roll-up (supplied)]  demo/ReviewAggregate.demo.tsx
+- reviews.form → <ReviewForm> [post-moderation (published)|pre-moderation (pending)|already rated (400)]  demo/ReviewForm.demo.tsx
+- reviews.list → <ReviewList> [published|moderator (include=all)|empty (reachable by a guest)]  demo/ReviewList.demo.tsx
+Each source file is the canonical usage snippet (open the default variant).
+
+## Snippets
+```tsx
+// Error rendering + remediation branch (one pattern for every pair).
+const r = explainReviewsError(err.code); // 'wait_and_retry' | 'verify' | ...
+return <Alert action={r}>{t(err.code, err.params)}</Alert>;
+```