@cartbase/storefront 0.1.0

package/src/api/reviews.ts

@@ -0,0 +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)
+}

package/src/api/search.ts

@@ -0,0 +1,133 @@
+/**
+ * @cartbase/storefront/api/search — storefront search + related products
+ * (search-discovery card).
+ *
+ * Results are the SAME `StoreProduct` objects the products listing serves —
+ * reuse your product-card renderer as-is. Matching: full-text
+ * (Cyrillic-correct, prefix) ∪ title trigram typo tolerance ∪ SKU prefix ∪
+ * exact tag value; admin synonyms expand bidirectionally one level; admin
+ * pins for the exact query rank first, then global boosts, then relevance.
+ * Docs: docs/storefront/search.md.
+ */
+import type { Query, StorefrontClient } from "./http"
+import type { PricingContextQuery } from "./types"
+import type { StoreProduct } from "./products"
+
+export interface SearchFacetBucket {
+  /** Filter value to send back (id, option value, or "min-max" for price). */
+  value: string
+  label: string
+  count: number
+  /** Range (price) buckets only — pass back as `price_min`/`price_max`. */
+  min?: number
+  max?: number | null
+}
+
+export interface SearchFacet {
+  /** "price" | "availability" | "type" | "tags" | "collection" | "options.<Title>" */
+  key: string
+  label: string
+  type: "value" | "range"
+  buckets: SearchFacetBucket[]
+}
+
+export interface SearchProductsQuery extends PricingContextQuery {
+  /** Required, min 1 char. */
+  q: string
+  collection_id?: string[]
+  category_id?: string[]
+  tag_id?: string[]
+  type_id?: string[]
+  /** Major units in the pricing currency, applied to the cheapest base price. */
+  price_min?: number
+  price_max?: number
+  availability?: "in_stock" | "out_of_stock"
+  /**
+   * Option filters: title → accepted values (OR within an option, AND
+   * across options). Serialized as `option.<Title>=v1,v2` params.
+   */
+  options?: Record<string, string[]>
+  /** 1–100, default 20. */
+  limit?: number
+  offset?: number
+}
+
+export interface SearchProductsResponse {
+  results: StoreProduct[]
+  /**
+   * Per the tenant's Settings → Search & discovery → Filters config.
+   * Counts follow the standard faceting rule: each facet is computed on the
+   * result set filtered by every OTHER active filter (own dimension
+   * excluded). Empty buckets and empty facets are omitted.
+   */
+  facets: SearchFacet[]
+  total: number
+  offset: number
+  limit: number
+}
+
+export interface RelatedProductsQuery extends PricingContextQuery {
+  /** 1–24, default 12. */
+  limit?: number
+}
+
+export interface RelatedProductsResponse {
+  products: StoreProduct[]
+  count: number
+  /** True when any item came from the deterministic fallback chain. */
+  auto_filled: boolean
+}
+
+/** Fold the `options` record into `option.<Title>` wire params. */
+function toSearchParams(query: SearchProductsQuery): Query {
+  const { options, ...rest } = query
+  const out: Query = { ...rest }
+  if (options) {
+    for (const [title, values] of Object.entries(options)) {
+      if (values.length) out[`option.${title}`] = values
+    }
+  }
+  return out
+}
+
+/**
+ * Search published products. Draft products, other tenants, and products
+ * outside the publishable key's channels NEVER appear (pins included).
+ *
+ * Auth: anon (`x-client-id`); optional `x-publishable-api-key` scopes the
+ * catalog to the key's channels (empty results when nothing matches);
+ * optional Bearer JWT makes `calculated_price` group-aware — never cache
+ * price-decorated responses shared.
+ *
+ * Errors: 400 `missing_client_id`, 400 `validation_failed` (missing/empty
+ * `q`, bad enum), 400 `invalid_publishable_key`, 400 `invalid_region`.
+ * Settings: Search & discovery — synonyms, pins/boosts, facet config
+ * (order/enabled, price bucket strategy).
+ */
+export async function searchProducts(
+  client: StorefrontClient,
+  query: SearchProductsQuery
+): Promise<SearchProductsResponse> {
+  return client.get("/api/store/products/search", { query: toSearchParams(query) })
+}
+
+/**
+ * Related products for a PDP: manual admin picks first (position order),
+ * then a deterministic fallback fills to `limit` — same primary collection
+ * (newest first), then most-shared-tags. Accepts a product id or handle.
+ *
+ * Auth: anon (`x-client-id`); optional publishable key — the anchor product
+ * must be visible to the key (404 otherwise) and scoped-away products never
+ * appear as related items. Errors: 404 `not_found` (unknown/draft/
+ * channel-hidden anchor), 400 `validation_failed`, 400 `invalid_region`.
+ * Settings: manual related picks (Admin → Product → Related).
+ */
+export async function listRelatedProducts(
+  client: StorefrontClient,
+  idOrHandle: string,
+  query?: RelatedProductsQuery
+): Promise<RelatedProductsResponse> {
+  return client.get(`/api/store/products/${encodeURIComponent(idOrHandle)}/related`, {
+    query: { ...query },
+  })
+}

package/src/api/types.ts

@@ -0,0 +1,91 @@
+/**
+ * @cartbase/storefront — shared API surface types.
+ *
+ * The envelope + error contract every domain module builds on. Shapes are
+ * the documented store-API contract (docs/contracts/store-api.md and the
+ * per-domain teaching docs under docs/storefront/): single entities come
+ * back as `{ <resource>: {...} }`, lists as `{ <resources>: [...], count,
+ * offset, limit }`, and errors as `{ error, code, details? }`.
+ *
+ * Domain modules own their DTOs; only cross-domain primitives live here.
+ */
+
+/** List envelope every collection endpoint returns. */
+export interface ListEnvelope {
+  count: number
+  offset: number
+  limit: number
+}
+
+/** The wire error body (`{ error, code, details? }`). */
+export interface StoreApiErrorBody {
+  error?: string
+  message?: string
+  code?: string
+  details?: unknown
+}
+
+/**
+ * Thrown for every non-2xx response. `status` + `code` are the stable
+ * programmatic surface (codes are contract-listed per endpoint, e.g.
+ * `invalid_gift_card`, `checkout_method_hidden`, `rate_limited`);
+ * `body` keeps the raw payload for anything else.
+ */
+export class StoreApiError extends Error {
+  readonly status: number
+  readonly code: string | null
+  readonly body: unknown
+
+  constructor(status: number, body: unknown) {
+    const parsed = (body ?? {}) as StoreApiErrorBody
+    super(parsed.error ?? parsed.message ?? `Store API error (${status})`)
+    this.name = "StoreApiError"
+    this.status = status
+    this.code = typeof parsed.code === "string" ? parsed.code : null
+    this.body = body
+  }
+}
+
+/** ISO-8601 timestamp string (the wire format for every date field). */
+export type IsoDateString = string
+
+/**
+ * Money amounts are decimal major units (EUR 45.5, not cents) everywhere in
+ * the store API. Conversion to minor units happens only at provider
+ * boundaries server-side — the SDK never does money math (server truth).
+ */
+export type MajorUnitAmount = number
+
+/** `variant.calculated_price` (b2b-v1 pricing context, store-api.md). */
+export interface CalculatedPrice {
+  calculated_amount: MajorUnitAmount
+  original_amount: MajorUnitAmount
+  currency_code: string
+  is_calculated_price_price_list: boolean
+  price_list_id: string | null
+  price_list_type: "sale" | "override" | null
+}
+
+/** Raw base price row on variants (`product.prices[]` shape detail). */
+export interface PriceRow {
+  amount: MajorUnitAmount
+  currency_code: string
+  min_quantity?: number | null
+  max_quantity?: number | null
+}
+
+/**
+ * Pricing context accepted by every price-decorated listing (products,
+ * collections products, search, related). Server composes the rest
+ * (customer groups from the Bearer JWT, never from params).
+ */
+export interface PricingContextQuery {
+  currency_code?: string
+  region_id?: string
+}
+
+/** Standard pagination query accepted by list endpoints. */
+export interface PaginationQuery {
+  limit?: number
+  offset?: number
+}

package/src/cart-drawer/cart-drawer.tsx

@@ -0,0 +1,86 @@
+"use client"
+
+import { useEffect, useRef, type ReactNode } from "react"
+
+import { cn } from "../lib/utils"
+import { useCartDrawer } from "./context"
+
+/**
+ * Slide-out cart drawer shell. Contains an overlay, a focus-trapped panel
+ * that slides in from the right, an optional left sidebar (desktop only)
+ * for cross-sell, and a main content slot for the drawer body.
+ *
+ * Visual 1:1 with mindpages but colors are token-driven: `bg-card`,
+ * `bg-muted`, `border-border`. Override by setting CSS variables
+ * on the consuming store's :root.
+ *
+ * Ported from `@1click/ui/src/cart-drawer/cart-drawer.tsx` (v2.3.1);
+ * originally extracted from mindpages-storefront
+ * src/modules/cart-drawer/cart-drawer.tsx.
+ */
+
+type CartDrawerProps = {
+  sidebar?: ReactNode
+  children: ReactNode
+  /** Optional className for the main panel (composes with internal styles) */
+  panelClassName?: string
+}
+
+export function CartDrawer({ sidebar, children, panelClassName }: CartDrawerProps) {
+  const { isOpen, close } = useCartDrawer()
+  const panelRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (isOpen && panelRef.current) {
+      panelRef.current.focus()
+    }
+  }, [isOpen])
+
+  const hasSidebar = !!sidebar
+
+  return (
+    <>
+      {/* Overlay */}
+      <div
+        className={cn(
+          "fixed inset-0 bg-black/50 transition-opacity duration-300 z-[60]",
+          isOpen
+            ? "opacity-100 pointer-events-auto"
+            : "opacity-0 pointer-events-none"
+        )}
+        onClick={close}
+        aria-hidden="true"
+      />
+
+      {/* Panel */}
+      <div
+        ref={panelRef}
+        tabIndex={-1}
+        role="dialog"
+        aria-modal="true"
+        aria-label="Shopping cart"
+        className={cn(
+          "fixed top-0 right-0 h-full bg-card z-[61] flex overflow-hidden",
+          "transition-transform duration-300 ease-[cubic-bezier(0.16,1,0.3,1)]",
+          isOpen ? "translate-x-0" : "translate-x-full",
+          hasSidebar ? "w-full md:w-[740px]" : "w-full sm:w-[460px]",
+          panelClassName
+        )}
+        style={{
+          boxShadow: isOpen ? "-20px 0 60px rgba(0,0,0,0.12)" : "none",
+          paddingTop: "env(safe-area-inset-top, 0px)",
+        }}
+      >
+        {/* Sidebar — desktop only */}
+        {hasSidebar && (
+          <div className="hidden md:block w-[280px] flex-shrink-0 bg-muted border-r border-border">
+            {sidebar}
+          </div>
+        )}
+
+        {/* Main cart */}
+        <div className="flex-1 flex flex-col min-w-0 bg-card">{children}</div>
+      </div>
+    </>
+  )
+}