@cartbase/storefront 0.17.0 → 0.18.0

package/src/api/reviews.ts

@@ -1,259 +1,259 @@
-/**
- * @cartbase/storefront/api/reviews — verified-purchase reviews (reviews card;
- * shapes mirror alenika/src/lib/reviews-api.ts verbatim).
- *
- * Ground truth: src/app/api/store/reviews/** + src/lib/reviews/*.
- *
- * Model: reviews exist ONLY via a single-use, order-scoped, expiring TOKEN
- * minted by the request scanner and mailed as `<review_link_base>/<token>`.
- * The token IS the auth for every write — no login. All public reads serve
- * `status='visible'` rows only; hidden/pending/deleted never leak.
- *
- * Two-step wizard: submit (consumes the token) → attach photo (reward).
- * Resume rule: token consumed + review.reward_code null → resume at the
- * photo step; reward_code set → fully done, show the code.
- */
-
-import type { StorefrontClient } from "./http"
-import type { IsoDateString } from "./types"
-
-/** One media entry on a review. */
-export interface ReviewMedia {
-  type: "image" | "video"
-  /** Must live on the store's public file host (R2) — see createUploadUrl. */
-  url: string
-  thumb: string
-  w: number
-  h: number
-  bytes: number
-}
-
-/** Public review — EXACTLY these keys (leak guard: no email/order/IP/status). */
-export interface PublicReview {
-  id: string
-  customer_name: string
-  rating: number
-  /** Always null today — the form has no title field. */
-  title: string | null
-  body: string | null
-  /** Moderation-hidden entries are filtered out server-side. */
-  media: ReviewMedia[]
-  admin_response: string | null
-  admin_response_at: IsoDateString | null
-  created_at: IsoDateString
-}
-
-export interface ListReviewsQuery {
-  product_id: string
-  /** default = with-media first then newest; rating uses `order`; date = newest. */
-  sort?: "default" | "rating" | "date"
-  order?: "asc" | "desc"
-  /** ≤ 50, default 10. */
-  limit?: number
-  offset?: number
-}
-
-export interface ReviewListResponse {
-  reviews: PublicReview[]
-  count: number
-  has_more: boolean
-}
-
-/**
- * GET /api/store/reviews — visible reviews for a product.
- *
- * Auth: anon (x-client-id).
- * Errors: 400 validation_failed (missing product_id, bad sort/limit).
- */
-export async function listReviews(
-  client: StorefrontClient,
-  query: ListReviewsQuery
-): Promise<ReviewListResponse> {
-  return client.get("/api/store/reviews", { query: { ...query } })
-}
-
-/** Star-rating stats. distribution keys are "1".."5". */
-export interface ReviewAggregate {
-  product_id: string
-  count: number
-  /** Rounded to 1 decimal; 0 when no reviews. */
-  avg_rating: number
-  distribution: Record<"1" | "2" | "3" | "4" | "5", number>
-}
-
-/**
- * GET /api/store/reviews/aggregate — the PDP star-badge stats. Visible
- * reviews only. Edge-cached 60s (`Cache-Control: public, max-age=60`).
- *
- * Auth: anon (x-client-id).
- * Errors: 400 validation_failed (missing product_id).
- */
-export async function getAggregate(
-  client: StorefrontClient,
-  productId: string
-): Promise<ReviewAggregate> {
-  return client.get("/api/store/reviews/aggregate", { query: { product_id: productId } })
-}
-
-/** Widget payload — aggregate + first page + display options, one call. */
-export interface ReviewWidgetPayload {
-  product_id: string
-  aggregate: ReviewAggregate
-  reviews: PublicReview[]
-  count: number
-  has_more: boolean
-  options: {
-    layout: "masonry" | "list"
-    page_size: number
-    photo_first: boolean
-  }
-}
-
-/**
- * GET /api/store/reviews/widget — everything the product review widget +
- * star badge need in one call (first page sized/sorted per the store's
- * Settings → Reviews display options). Edge-cached 60s.
- *
- * Auth: anon (x-client-id).
- * Errors: 400 validation_failed (missing product_id).
- * Settings: widget_layout / widget_page_size / widget_photo_first.
- */
-export async function getWidget(
-  client: StorefrontClient,
-  productId: string
-): Promise<ReviewWidgetPayload> {
-  return client.get("/api/store/reviews/widget", { query: { product_id: productId } })
-}
-
-/** Token validation — the review-form bootstrap state. */
-export type TokenValidation =
-  | { valid: false; reason: "not_found" | "expired" | "invalid" }
-  | {
-      valid: true
-      already_submitted: boolean
-      /** Present when already_submitted and the review row exists. */
-      review: { id: string; reward_code: string | null } | null
-      product: {
-        id: string
-        handle: string
-        title: string
-        thumbnail: string | null
-      } | null
-      customer_name: string
-      expires_at: IsoDateString
-    }
-
-/**
- * GET /api/store/reviews/token/:token — validate a review token and load
- * the form context (product card, greeting, resume state). ALWAYS 200 —
- * invalid tokens come back as `{valid: false, reason}`. Never cached.
- *
- * Auth: anon (x-client-id); the token is the bearer secret.
- */
-export async function validateToken(
-  client: StorefrontClient,
-  token: string
-): Promise<TokenValidation> {
-  return client.get(`/api/store/reviews/token/${encodeURIComponent(token)}`)
-}
-
-export interface SubmitReviewInput {
-  token: string
-  /** Integer 1–5. */
-  rating: number
-  /** REQUIRED — a rating alone is not a review. HTML stripped; ≤ 2000 chars. */
-  body: string
-  /** ≤ 7 items: ≤ 6 images + ≤ 1 video; URLs must be on the file host. */
-  media?: ReviewMedia[]
-}
-
-export interface SubmitReviewResponse {
-  id: string
-  success: true
-}
-
-/**
- * POST /api/store/reviews — submit the review (wizard step 1). Consumes the
- * token; idempotent on the (order, product) unique — a race returns the
- * existing review. No title field.
- *
- * Auth: anon (x-client-id); the token is the auth.
- * Errors: 400 invalid_data (rating/body/media rules; body empty after
- * sanitize) · 404 not_found (unknown token) · 409 conflict (token already
- * consumed — replay) · 410 gone (expired) · 429 rate_limited (3/h per IP).
- * Settings: moderation_mode `hold` lands the review as pending (not
- * publicly visible until approved).
- */
-export async function submitReview(
-  client: StorefrontClient,
-  input: SubmitReviewInput
-): Promise<SubmitReviewResponse> {
-  return client.post("/api/store/reviews", input)
-}
-
-export interface AttachReviewPhotoInput {
-  /** The SAME review token — consumed is OK (two-step wizard). */
-  token: string
-  /** 1–7 items, ≤ 6 images + ≤ 1 video, file-host URLs only. */
-  media: ReviewMedia[]
-}
-
-/** `{code}` fresh mint · `{code, already_issued}` retry · `{code: null, message}` mint failed (media still saved). */
-export type AttachReviewPhotoResponse =
-  | { code: string }
-  | { code: string; already_issued: true }
-  | { code: null; message: string }
-
-/**
- * POST /api/store/reviews/:id/photo — wizard step 2: attach media and mint
- * the single-use reward code (a real promotion, percentage-off-order; 10%
- * default). The reward is for the PHOTO, never the rating. Idempotent —
- * retries return the same code; a promo failure never loses the media.
- *
- * Auth: anon (x-client-id); token must match the review's (order, product).
- * Errors: 400 invalid_data (missing/invalid media) · 403 forbidden (token
- * does not match this review) · 404 not_found (review or token unknown).
- * Settings: reward_enabled / reward_percentage (Settings → Reviews).
- */
-export async function attachReviewPhoto(
-  client: StorefrontClient,
-  reviewId: string,
-  input: AttachReviewPhotoInput
-): Promise<AttachReviewPhotoResponse> {
-  return client.post(`/api/store/reviews/${encodeURIComponent(reviewId)}/photo`, input)
-}
-
-export interface CreateUploadUrlInput {
-  token: string
-  /** Original filename (informational). */
-  name: string
-  /** MIME: image/jpeg|jpg|png|webp or video/mp4|quicktime. */
-  type: string
-  /** Bytes — pre-checked against the per-type cap when provided. */
-  size?: number
-}
-
-export interface CreateUploadUrlResponse {
-  /** Signed R2 PUT URL — upload the raw file body here. */
-  uploadUrl: string
-  /** The public URL to reference in ReviewMedia.url after upload. */
-  publicUrl: string
-  key: string
-  filename: string
-}
-
-/**
- * POST /api/store/reviews/upload-url — signed R2 upload for the photo step.
- * A consumed token is accepted (step 1 consumed it); expiry still applies.
- * Caps: image ≤ 8MB, video ≤ 50MB.
- *
- * Auth: anon (x-client-id); the token is the auth.
- * Errors: 400 invalid_data (unsupported MIME, file too large) ·
- * 404 not_found (unknown token) · 410 gone (expired token).
- */
-export async function createUploadUrl(
-  client: StorefrontClient,
-  input: CreateUploadUrlInput
-): Promise<CreateUploadUrlResponse> {
-  return client.post("/api/store/reviews/upload-url", input)
-}
+/**
+ * @cartbase/storefront/api/reviews — verified-purchase reviews (reviews card;
+ * shapes mirror alenika/src/lib/reviews-api.ts verbatim).
+ *
+ * Ground truth: src/app/api/store/reviews/** + src/lib/reviews/*.
+ *
+ * Model: reviews exist ONLY via a single-use, order-scoped, expiring TOKEN
+ * minted by the request scanner and mailed as `<review_link_base>/<token>`.
+ * The token IS the auth for every write — no login. All public reads serve
+ * `status='visible'` rows only; hidden/pending/deleted never leak.
+ *
+ * Two-step wizard: submit (consumes the token) → attach photo (reward).
+ * Resume rule: token consumed + review.reward_code null → resume at the
+ * photo step; reward_code set → fully done, show the code.
+ */
+
+import type { StorefrontClient } from "./http"
+import type { IsoDateString } from "./types"
+
+/** One media entry on a review. */
+export interface ReviewMedia {
+  type: "image" | "video"
+  /** Must live on the store's public file host (R2) — see createUploadUrl. */
+  url: string
+  thumb: string
+  w: number
+  h: number
+  bytes: number
+}
+
+/** Public review — EXACTLY these keys (leak guard: no email/order/IP/status). */
+export interface PublicReview {
+  id: string
+  customer_name: string
+  rating: number
+  /** Always null today — the form has no title field. */
+  title: string | null
+  body: string | null
+  /** Moderation-hidden entries are filtered out server-side. */
+  media: ReviewMedia[]
+  admin_response: string | null
+  admin_response_at: IsoDateString | null
+  created_at: IsoDateString
+}
+
+export interface ListReviewsQuery {
+  product_id: string
+  /** default = with-media first then newest; rating uses `order`; date = newest. */
+  sort?: "default" | "rating" | "date"
+  order?: "asc" | "desc"
+  /** ≤ 50, default 10. */
+  limit?: number
+  offset?: number
+}
+
+export interface ReviewListResponse {
+  reviews: PublicReview[]
+  count: number
+  has_more: boolean
+}
+
+/**
+ * GET /api/store/reviews — visible reviews for a product.
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 400 validation_failed (missing product_id, bad sort/limit).
+ */
+export async function listReviews(
+  client: StorefrontClient,
+  query: ListReviewsQuery
+): Promise<ReviewListResponse> {
+  return client.get("/api/store/reviews", { query: { ...query } })
+}
+
+/** Star-rating stats. distribution keys are "1".."5". */
+export interface ReviewAggregate {
+  product_id: string
+  count: number
+  /** Rounded to 1 decimal; 0 when no reviews. */
+  avg_rating: number
+  distribution: Record<"1" | "2" | "3" | "4" | "5", number>
+}
+
+/**
+ * GET /api/store/reviews/aggregate — the PDP star-badge stats. Visible
+ * reviews only. Edge-cached 60s (`Cache-Control: public, max-age=60`).
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 400 validation_failed (missing product_id).
+ */
+export async function getAggregate(
+  client: StorefrontClient,
+  productId: string
+): Promise<ReviewAggregate> {
+  return client.get("/api/store/reviews/aggregate", { query: { product_id: productId } })
+}
+
+/** Widget payload — aggregate + first page + display options, one call. */
+export interface ReviewWidgetPayload {
+  product_id: string
+  aggregate: ReviewAggregate
+  reviews: PublicReview[]
+  count: number
+  has_more: boolean
+  options: {
+    layout: "masonry" | "list"
+    page_size: number
+    photo_first: boolean
+  }
+}
+
+/**
+ * GET /api/store/reviews/widget — everything the product review widget +
+ * star badge need in one call (first page sized/sorted per the store's
+ * Settings → Reviews display options). Edge-cached 60s.
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 400 validation_failed (missing product_id).
+ * Settings: widget_layout / widget_page_size / widget_photo_first.
+ */
+export async function getWidget(
+  client: StorefrontClient,
+  productId: string
+): Promise<ReviewWidgetPayload> {
+  return client.get("/api/store/reviews/widget", { query: { product_id: productId } })
+}
+
+/** Token validation — the review-form bootstrap state. */
+export type TokenValidation =
+  | { valid: false; reason: "not_found" | "expired" | "invalid" }
+  | {
+      valid: true
+      already_submitted: boolean
+      /** Present when already_submitted and the review row exists. */
+      review: { id: string; reward_code: string | null } | null
+      product: {
+        id: string
+        handle: string
+        title: string
+        thumbnail: string | null
+      } | null
+      customer_name: string
+      expires_at: IsoDateString
+    }
+
+/**
+ * GET /api/store/reviews/token/:token — validate a review token and load
+ * the form context (product card, greeting, resume state). ALWAYS 200 —
+ * invalid tokens come back as `{valid: false, reason}`. Never cached.
+ *
+ * Auth: anon (x-client-id); the token is the bearer secret.
+ */
+export async function validateToken(
+  client: StorefrontClient,
+  token: string
+): Promise<TokenValidation> {
+  return client.get(`/api/store/reviews/token/${encodeURIComponent(token)}`)
+}
+
+export interface SubmitReviewInput {
+  token: string
+  /** Integer 1–5. */
+  rating: number
+  /** REQUIRED — a rating alone is not a review. HTML stripped; ≤ 2000 chars. */
+  body: string
+  /** ≤ 7 items: ≤ 6 images + ≤ 1 video; URLs must be on the file host. */
+  media?: ReviewMedia[]
+}
+
+export interface SubmitReviewResponse {
+  id: string
+  success: true
+}
+
+/**
+ * POST /api/store/reviews — submit the review (wizard step 1). Consumes the
+ * token; idempotent on the (order, product) unique — a race returns the
+ * existing review. No title field.
+ *
+ * Auth: anon (x-client-id); the token is the auth.
+ * Errors: 400 invalid_data (rating/body/media rules; body empty after
+ * sanitize) · 404 not_found (unknown token) · 409 conflict (token already
+ * consumed — replay) · 410 gone (expired) · 429 rate_limited (3/h per IP).
+ * Settings: moderation_mode `hold` lands the review as pending (not
+ * publicly visible until approved).
+ */
+export async function submitReview(
+  client: StorefrontClient,
+  input: SubmitReviewInput
+): Promise<SubmitReviewResponse> {
+  return client.post("/api/store/reviews", input)
+}
+
+export interface AttachReviewPhotoInput {
+  /** The SAME review token — consumed is OK (two-step wizard). */
+  token: string
+  /** 1–7 items, ≤ 6 images + ≤ 1 video, file-host URLs only. */
+  media: ReviewMedia[]
+}
+
+/** `{code}` fresh mint · `{code, already_issued}` retry · `{code: null, message}` mint failed (media still saved). */
+export type AttachReviewPhotoResponse =
+  | { code: string }
+  | { code: string; already_issued: true }
+  | { code: null; message: string }
+
+/**
+ * POST /api/store/reviews/:id/photo — wizard step 2: attach media and mint
+ * the single-use reward code (a real promotion, percentage-off-order; 10%
+ * default). The reward is for the PHOTO, never the rating. Idempotent —
+ * retries return the same code; a promo failure never loses the media.
+ *
+ * Auth: anon (x-client-id); token must match the review's (order, product).
+ * Errors: 400 invalid_data (missing/invalid media) · 403 forbidden (token
+ * does not match this review) · 404 not_found (review or token unknown).
+ * Settings: reward_enabled / reward_percentage (Settings → Reviews).
+ */
+export async function attachReviewPhoto(
+  client: StorefrontClient,
+  reviewId: string,
+  input: AttachReviewPhotoInput
+): Promise<AttachReviewPhotoResponse> {
+  return client.post(`/api/store/reviews/${encodeURIComponent(reviewId)}/photo`, input)
+}
+
+export interface CreateUploadUrlInput {
+  token: string
+  /** Original filename (informational). */
+  name: string
+  /** MIME: image/jpeg|jpg|png|webp or video/mp4|quicktime. */
+  type: string
+  /** Bytes — pre-checked against the per-type cap when provided. */
+  size?: number
+}
+
+export interface CreateUploadUrlResponse {
+  /** Signed R2 PUT URL — upload the raw file body here. */
+  uploadUrl: string
+  /** The public URL to reference in ReviewMedia.url after upload. */
+  publicUrl: string
+  key: string
+  filename: string
+}
+
+/**
+ * POST /api/store/reviews/upload-url — signed R2 upload for the photo step.
+ * A consumed token is accepted (step 1 consumed it); expiry still applies.
+ * Caps: image ≤ 8MB, video ≤ 50MB.
+ *
+ * Auth: anon (x-client-id); the token is the auth.
+ * Errors: 400 invalid_data (unsupported MIME, file too large) ·
+ * 404 not_found (unknown token) · 410 gone (expired token).
+ */
+export async function createUploadUrl(
+  client: StorefrontClient,
+  input: CreateUploadUrlInput
+): Promise<CreateUploadUrlResponse> {
+  return client.post("/api/store/reviews/upload-url", input)
+}