brainerce 1.63.0 → 2.0.0

package/README.md

@@ -55,7 +55,7 @@ Every Brainerce storefront must include **all mandatory features** below. Featur
 | Product detail with variant picker, stock, price         | `client.getProductBySlug()` + helpers                                                                                                                        | ✅          |
 | Buyer customization fields (engraving, uploads, select)  | `product.customizationFields`, `client.uploadCustomizationFile()`                                                                                            | ✅          |
 | Cart (add, update, remove, coupon, totals)               | `client.addToCart()`, `getCartTotals(cart)`                                                                                                                  | ✅          |
-| Inventory reservation countdown                          | Cart expiry timestamp from `client.getCart()`                                                                                                                | ✅          |
+| Inventory reservation countdown                          | Cart expiry timestamp from `client.getCart(cartId)`                                                                                                    | ✅          |
 | Full checkout end-to-end with payment                    | `setShippingAddress → selectShippingMethod → getPaymentProviders → pay → handlePaymentSuccess → waitForOrder`                                                | ✅          |
 | Order confirmation (clear cart + wait for real order)    | `client.handlePaymentSuccess()`, `client.waitForOrder()`                                                                                                     | ✅          |
 | Register + email verification flow                       | `client.registerCustomer()`, `client.verifyEmail()`                                                                                                          | ✅          |
@@ -66,7 +66,7 @@ Every Brainerce storefront must include **all mandatory features** below. Featur
 | Loyalty & rewards (points balance + tiers + redeem)      | `client.getLoyaltyStatus()`, `client.getAvailableRewards()`, `client.getRecommendedReward()`, `client.redeemLoyaltyReward(id)`, `client.reportSocialShare()` | conditional |
 | Loyalty paid membership (premium subscription)           | `client.getMembershipPlans()`, `client.getMySavedPaymentMethods()`, `client.subscribeToMembership(params)`, `client.cancelMembership()`                      | conditional |
 | Embeddable loyalty widget (points + rewards on ANY site) | `client.getLoyaltyWidgetSession()`                                                                                                                           | conditional |
-| Global header: cart count + search autocomplete          | `client.getCart()`, `client.getSearchSuggestions(query)`                                                                                                     | ✅          |
+| Global header: cart count + search autocomplete          | `client.smartGetCart()`, `client.getSearchSuggestions(query)`                                                                                           | ✅          |
 | Discount banners + product badges                        | `client.getDiscountBanners()`, `client.getProductDiscountBadge(productId)`                                                                                   | ✅          |
 | Product reviews on PDP + JSON-LD aggregateRating         | `client.listProductReviews(id)`, `client.submitProductReview(id, …)`                                                                                         | ✅          |
 | Customer photos on reviews                               | `client.uploadReviewPhoto(productId, file)`, then `imageKeys` on submit                                                                                      | conditional |
@@ -172,7 +172,7 @@ These sequences are non-negotiable. The order of SDK calls matters.
 5. Confirm payment using the provider's flow (Stripe Elements `stripe.confirmCardPayment`, PayPal button, redirect, etc.).
 6. On the confirmation page, **always call both**:
    ```ts
-   await client.handlePaymentSuccess(checkoutId); // clears cart
+   client.handlePaymentSuccess(checkoutId); // synchronous, clears cart. Do NOT await it.
    const order = await client.waitForOrder(checkoutId); // polls until order exists
    ```
 7. Display `checkout.lineItems` (not `cart.items`) on the order summary.
@@ -210,7 +210,22 @@ These sequences are non-negotiable. The order of SDK calls matters.
 ### Order confirmation flow
 
 1. Read `checkoutId` from URL or session.
-2. `await client.handlePaymentSuccess(checkoutId)` — mandatory, clears cart so purchased items don't show on next visit.
+2. `client.handlePaymentSuccess(checkoutId)` is mandatory. It clears the cart so purchased items don't show on the next visit. It is **synchronous** and returns a plain object, not a promise, so awaiting it is a no-op that only looks like it did something:
+
+   ```ts
+   const { cleared, mode, userType, itemsRemoved } = client.handlePaymentSuccess(checkoutId);
+   // mode: 'full'    the whole cart went, the normal case
+   // mode: 'partial' a partial checkout, so only the purchased lines went.
+   //                 `itemsRemoved` counts them and the rest stay in the cart
+   // mode: 'none'    nothing to do, because this checkout was already handled
+   //                 in this browser session. React Strict Mode runs effects
+   //                 twice and a refresh re-runs the page, so this is the
+   //                 normal repeat-call answer: SUCCESS, not a failure.
+   //                 `cleared` is false here. Never show an error on it.
+   // userType: 'guest' | 'customer'
+   ```
+
+   Branch on `mode` only for what you render: a `'partial'` result means the shopper still has a cart worth linking to. Never gate `waitForOrder` on `cleared`.
 3. `const result = await client.waitForOrder(checkoutId)` — polls until the webhook writes the order. `result.status.orderNumber` / `result.status.orderId` are available on success.
 4. Show a spinner during step 3 (webhook may lag). On timeout: show "we're still processing, check your email" with a link to order history — the order WILL appear there.
 5. On success: render the order number, or — if your design wants more than that — fetch full details:
@@ -280,7 +295,7 @@ the credential, no customer token needed.
 ### Inventory reservation flow
 
 - Display the countdown from `cart.reservation?.expiresAt` — refresh once per second (`reservation` is optional; only present when a reservation strategy is active).
-- On expiry: call `client.getCart()` to refresh. Items whose reservation expired are flagged server-side.
+- On expiry: call `client.getCart(cartId)` to refresh, or `client.smartGetCart()` when you are not tracking a cart id yourself. `getCart` takes the cart id; there is no no-argument form. Items whose reservation expired are flagged server-side.
 - On the checkout page: if reservation has expired, block payment and show "your cart has expired" with a link back to cart.
 - Do NOT implement your own timer logic — the SDK is the source of truth.
 
@@ -1026,8 +1041,9 @@ await client.setCheckoutCustomer(checkout.id, {
   lastName: 'Doe',
 });
 
-// 5. Set shipping address
+// 5. Set shipping address (email is required here too, even though step 4 sent it)
 await client.setShippingAddress(checkout.id, {
+  email: 'customer@example.com',
   firstName: 'John',
   lastName: 'Doe',
   line1: '123 Main St',
@@ -1116,6 +1132,7 @@ const region = validRegions.some((r) => r.code === address.region) ? address.reg
 // yourself. Use `address.lat`/`address.lng` for your own UI — a map pin, a
 // distance readout — and nothing else.
 await client.setShippingAddress(checkout.id, {
+  email: 'customer@example.com', // required. The resolved address carries no email.
   firstName: 'John',
   lastName: 'Doe',
   ...address,
@@ -2109,6 +2126,160 @@ function ProductDescription({ product }: { product: Product }) {
 
 ---
 
+### Product Reviews
+
+Customer reviews on the product page, with optional customer photos. Reviews
+publish immediately, there is no pending state, and the merchant hides
+individual reviews or photos afterwards (see [Review Moderation](#review-moderation)
+in the Admin API Reference).
+
+Reading reviews is public: `listProductReviews` and the `avgRating` /
+`reviewCount` summary need no login. Writing is not. Only customers who bought
+the product may review it, so `getMyProductReview`, `uploadReviewPhoto`,
+`submitProductReview`, `updateMyProductReview` and `deleteMyProductReview` all
+need a customer token set with `setCustomerToken(...)` and return 401 without
+one. Author name and email come from the customer profile server-side; never
+send them.
+
+The product itself carries `avgRating` and `reviewCount` for the star summary
+and the JSON-LD `aggregateRating`, so a rating badge on a product card costs no
+extra request.
+
+#### List Reviews
+
+```typescript
+const { data, meta } = await client.listProductReviews('prod_123', {
+  page: 1,
+  limit: 20,
+  sort: 'photos_first', // 'photos_first' (default) | 'newest'
+});
+
+data.forEach((review) => {
+  console.log(review.rating, review.body, review.verifiedPurchase, review.authorName);
+  // review.images is ALWAYS an array, already filtered to the photos shoppers
+  // may see. Set width/height on the <img> so the gallery reserves space
+  // instead of shifting as the photos load.
+  review.images.forEach((img) => console.log(img.thumbnailUrl ?? img.url, img.width, img.height));
+});
+
+console.log(meta.total); // total visible reviews
+```
+
+`sort` defaults to `photos_first`: reviews carrying photos lead, newest first
+within each group. Pass `sort: 'newest'` for plain chronological order. On a
+store with no review photos the two orders are identical. Hidden reviews are
+never returned here.
+
+No customer token is needed for this call: it is the one review call a
+signed-out shopper can make.
+
+#### Read the Customer's Own Review State
+
+Requires a customer token. Call it before rendering any review UI: it answers
+all four cases in one request, sign in, not eligible, submit, edit.
+
+```typescript
+const { eligible, reason, myReview, photos, myImages } = await client.getMyProductReview('prod_123');
+
+if (!eligible) {
+  // reason: 'no_eligible_order' | 'reviews_disabled' | 'product_not_found' | null
+  showMessage(reason);
+} else if (myReview) {
+  renderEditForm(myReview);
+} else {
+  renderSubmitForm();
+}
+
+// The store's live photo policy. Read it instead of hardcoding limits.
+photos.enabled; // render the file picker only when true
+photos.maxPerReview; // cap the selection at this
+photos.maxBytes; // reject oversized files before uploading
+photos.requiresApproval; // true = tell the customer their photo waits for the merchant
+
+// The customer's OWN photos, including ones still pending approval, so their
+// upload looks queued rather than failed. `myReview.images` carries only the
+// publicly visible subset.
+myImages.forEach((img) => console.log(img.approvedAt, img.hiddenAt));
+```
+
+#### Upload Photos
+
+Requires a customer token, and the server re-checks the purchase before it
+stores any bytes. Upload each file first, then pass the returned keys on submit.
+Keys, not URLs: the server resolves each one against the store's own assets and
+rejects anything that is not a review photo.
+
+```typescript
+const { photos } = await client.getMyProductReview(productId);
+
+if (photos.enabled) {
+  const uploads = await Promise.all(
+    [...fileInput.files]
+      .slice(0, photos.maxPerReview)
+      .map((file) => client.uploadReviewPhoto(productId, file))
+  );
+
+  // Each upload: { key, url, width, height }. `url` is for a local preview only,
+  // `key` is what you send back.
+  const imageKeys = uploads.map((u) => u.key);
+}
+```
+
+Limits and behaviour:
+
+- JPEG, PNG, WebP or GIF only. Max 5 MB and 40 megapixels per file. The server
+  checks the real bytes, not the declared MIME type, so a renamed file is rejected.
+- Throttled to 10 uploads per minute, so a burst returns HTTP 429.
+- 403 when the store has review photos turned off, or the customer did not buy
+  the product. 400 once the review is already at its photo cap.
+- EXIF is stripped, so GPS coordinates never reach the storefront, and the
+  orientation tag is applied first, so phone photos stay upright.
+- A photo uploaded but never attached to a submitted review is reclaimed after 7
+  days.
+
+#### Submit a Review
+
+Requires a customer token.
+
+```typescript
+const review = await client.submitProductReview('prod_123', {
+  rating: 5, // 1-5
+  body: 'Arrived beautifully wrapped.', // optional
+  imageKeys, // optional, in display order
+});
+```
+
+- 403 `no_eligible_order` when the customer never bought the product. Eligibility
+  is SHIPPED for physical products, PAID for downloadable ones.
+- 409 when they already reviewed this product. Call `updateMyProductReview`
+  instead, which is why you read `getMyProductReview` first.
+
+#### Edit or Delete Their Own Review
+
+Requires a customer token. Both calls act on the caller's own review for that
+product; there is no review id to pass and no way to touch anyone else's.
+
+```typescript
+// Rating, body and photos. authorName and verifiedPurchase are preserved from
+// the original submit and cannot be changed.
+await client.updateMyProductReview('prod_123', {
+  rating: 4,
+  body: 'Still good after a month of use.',
+  imageKeys: ['key_a', 'key_b'],
+});
+
+// Deleting frees the customer to submit a new review, subject to eligibility.
+await client.deleteMyProductReview('prod_123');
+```
+
+> **`imageKeys` REPLACES the photo set on update.** Pass the keys you want to
+> keep, including the existing ones. Omitting the field entirely leaves the
+> current photos untouched; passing `[]` removes them all. The key of an
+> already-attached photo is `assetKey` on each entry of
+> `getMyProductReview().myImages`.
+
+---
+
 ### Cart Operations (All Users)
 
 The `smart*` methods work for both guests and logged-in users. Guests use server-side session carts; logged-in users use server carts linked to their account.
@@ -2120,9 +2291,35 @@ await client.smartAddToCart({
   productId: 'prod_123',
   variantId: 'var_456', // Optional: for products with variants
   quantity: 2,
+
+  // Optional: buyer customization values (engraving text, uploaded photo URL,
+  // SELECT / MULTI_SELECT picks). Keys are the `key` of each entry in
+  // product.customizationFields. See "Product customization fields" above.
+  metadata: {
+    engraving_text: 'Happy Birthday!',
+    frame_color: 'Gold',
+  },
+
+  // Optional: modifier-group picks (toppings, sauce, build-your-own).
+  selections: [
+    { modifierGroupId: 'mg_bread', modifierIds: ['m_thick'] },
+    { modifierGroupId: 'mg_toppings', modifierIds: ['m_olive', 'm_bacon'] },
+  ],
+
+  // Optional: nested combo picks, keyed by the PARENT modifierId. Max 3 levels.
+  nestedByModifierId: {
+    m_side_drink: [{ modifierGroupId: 'mg_size', modifierIds: ['m_large'] }],
+  },
 });
 ```
 
+> `metadata`, `selections` and `nestedByModifierId` are the same three fields the
+> low-level `addToCart(cartId, item)` takes, and they behave identically here.
+> Reach for `smartAddToCart` on a storefront: it resolves the right cart for a
+> guest or a logged-in shopper, so you never need a `cartId` of your own.
+> Validation stays server-side, so a bad modifier set still comes back as a
+> `MODIFIER_VALIDATION_FAILED` envelope on `BrainerceError.details`.
+
 #### Get Cart
 
 ```typescript
@@ -2576,6 +2773,7 @@ const checkout = await client.setCheckoutCustomer(checkoutId, {
 
 ```typescript
 const { checkout, rates } = await client.setShippingAddress(checkoutId, {
+  email: 'customer@example.com', // REQUIRED, on every call
   firstName: 'John',
   lastName: 'Doe',
   line1: '123 Main St',
@@ -2594,6 +2792,11 @@ const { checkout, rates } = await client.setShippingAddress(checkoutId, {
 console.log(rates); // ShippingRate[]
 ```
 
+> **`email` is required, including for logged-in customers and including when
+> you already sent it to `setCheckoutCustomer`.** It is validated before any
+> service code runs, so the server never fills it in from the customer record;
+> omit it or send an empty string and the call fails with a 400.
+
 > **Always pass `placeId` when you use address autocomplete.** The server
 > re-resolves it to the address's exact coordinates, which is how stores that
 > draw their delivery areas on a map ("polygon" zones) decide whether they
@@ -2842,6 +3045,7 @@ The shipping flow involves setting an address and then selecting from available
 ```typescript
 // Step 1: Set shipping address - this returns available rates
 const { checkout, rates } = await client.setShippingAddress(checkoutId, {
+  email: 'customer@example.com', // required
   firstName: 'John',
   lastName: 'Doe',
   line1: '123 Main St',
@@ -5392,6 +5596,56 @@ await client.detachModifierGroup(storeId, productId, attachment.id);
 
 `null` on an override means "inherit from the group default"; any non-null value (including `0` or `false`) wins. `modifierGroupId` and `variantId` are immutable on `updateAttachment` — to swap a group, detach and re-attach.
 
+### Review Moderation
+
+Five admin methods for moderating customer reviews and the photos attached to
+them. Listing needs an API key with `reviews:read`; hiding and showing need
+`reviews:write`. The storefront methods are covered under [Product Reviews](#product-reviews).
+
+`storeId` is optional on every call: pass it when the key can reach more than
+one store.
+
+```typescript
+// Every review on the product, including the hidden ones the storefront omits.
+// visibility: 'visible' | 'hidden' | 'all' (default 'all').
+const { data, meta } = await client.adminListProductReviews('prod_123', {
+  page: 1,
+  limit: 20,
+  visibility: 'hidden',
+  storeId, // optional
+});
+
+// ProductReviewAdmin carries the PII the storefront type does not:
+// customerId, authorEmail, orderId, updatedAt, hiddenAt, plus `images` typed as
+// ProductReviewImageAdmin[] (assetKey, approvedAt, hiddenAt, createdAt).
+data.forEach((review) => {
+  console.log(review.authorEmail, review.orderId, review.hiddenAt);
+});
+```
+
+```typescript
+// Hide a whole review, then put it back. Hiding stamps hiddenAt; showing clears it.
+await client.hideProductReview('rev_123', storeId);
+await client.showProductReview('rev_123', storeId);
+```
+
+```typescript
+// Photo-level moderation: take down ONE photo and leave the review, its rating
+// and its other photos live.
+await client.hideProductReviewImage('revimg_123', storeId);
+
+// Showing a photo is ALSO the approve action. A photo that has never been
+// approved carries `approvedAt: null`, and showing it stamps one, so stores that
+// turned on review-photo approval need no separate verb.
+await client.showProductReviewImage('revimg_123', storeId);
+```
+
+> **Reviews publish immediately.** There is no pending state for the review text
+> itself, so a moderation queue built on "approve each review" has nothing to
+> read. Photos are the only part that can wait on the merchant, and only on
+> stores that turned approval on. Poll `adminListProductReviews(productId, { visibility: 'all' })`
+> and treat any image with `approvedAt: null` as the queue.
+
 ---
 
 ## Complete Page Examples
@@ -5804,12 +6058,14 @@ export default function CheckoutPage() {
   const [checkout, setCheckout] = useState<Checkout | null>(null);
   const [shippingRates, setShippingRates] = useState<ShippingRate[]>([]);
   const [selectedRate, setSelectedRate] = useState<string | null>(null);
+  // Two phases: collect the address, then let the shopper pick a delivery option.
+  const [step, setStep] = useState<'address' | 'shipping'>('address');
   const customerLoggedIn = isLoggedIn();
 
-  // Form state
-  const [email, setEmail] = useState('');
+  // Form state. `email` lives here because setShippingAddress requires it on
+  // every call, logged-in shoppers included.
   const [shippingAddress, setShippingAddress] = useState({
-    firstName: '', lastName: '', line1: '', city: '', postalCode: '', country: 'US'
+    email: '', firstName: '', lastName: '', line1: '', city: '', postalCode: '', country: 'US'
   });
 
   useEffect(() => {
@@ -5839,7 +6095,8 @@ export default function CheckoutPage() {
     initCheckout();
   }, []);
 
-  const handleSubmit = async (e: React.FormEvent) => {
+  // Phase 1: save the customer and the address, then show the rate picker.
+  const handleAddressSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
     if (!checkout) return;
     setSubmitting(true);
@@ -5847,19 +6104,33 @@ export default function CheckoutPage() {
     try {
       // 1. Set customer info
       await client.setCheckoutCustomer(checkout.id, {
-        email,
+        email: shippingAddress.email,
         firstName: shippingAddress.firstName,
         lastName: shippingAddress.lastName,
       });
 
-      // 2. Set shipping address
-      await client.setShippingAddress(checkout.id, shippingAddress);
+      // 2. Set shipping address. The same call returns the rates for that
+      //    address, so store them instead of fetching a second time.
+      const { rates } = await client.setShippingAddress(checkout.id, shippingAddress);
+      setShippingRates(rates);
+      setSelectedRate(rates[0]?.id ?? null); // preselect, the shopper can change it
+      setStep('shipping');
+    } catch (error) {
+      console.error('Could not price shipping:', error);
+      alert('We could not load shipping options for that address.');
+    } finally {
+      setSubmitting(false);
+    }
+  };
 
-      // 3. Get and select shipping rate
-      const rates = await client.getShippingRates(checkout.id);
-      if (rates.length > 0) {
-        await client.selectShippingMethod(checkout.id, selectedRate || rates[0].id);
-      }
+  // Phase 2: the shopper has actually chosen a rate, so persist it and complete.
+  const handlePlaceOrder = async () => {
+    if (!checkout || !selectedRate) return;
+    setSubmitting(true);
+
+    try {
+      // 3. Persist the chosen rate
+      await client.selectShippingMethod(checkout.id, selectedRate);
 
       // 4. Complete checkout
       const { orderId } = await client.completeCheckout(checkout.id);
@@ -5878,28 +6149,42 @@ export default function CheckoutPage() {
 
   if (loading) return <div>Loading checkout...</div>;
 
+  if (step === 'shipping') {
+    return (
+      <div>
+        <h2>Delivery</h2>
+        {shippingRates.length === 0 ? (
+          <p>We cannot ship to that address. Please go back and edit it.</p>
+        ) : (
+          <select value={selectedRate || ''} onChange={(e) => setSelectedRate(e.target.value)}>
+            {shippingRates.map((rate) => (
+              // speedTier for live carrier rates; the merchant's own name for zone rates
+              <option key={rate.id} value={rate.id}>{rate.speedTier ? TIER_LABELS[rate.speedTier] : rate.name} - ${rate.price}</option>
+            ))}
+          </select>
+        )}
+
+        <button type="button" onClick={() => setStep('address')} disabled={submitting}>Edit address</button>
+        <button type="button" onClick={handlePlaceOrder} disabled={submitting || !selectedRate}>
+          {submitting ? 'Processing...' : 'Place Order'}
+        </button>
+      </div>
+    );
+  }
+
   return (
-    <form onSubmit={handleSubmit}>
-      {!customerLoggedIn && (
-        <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Email" required />
-      )}
+    <form onSubmit={handleAddressSubmit}>
+      {/* Always collect the email. setShippingAddress rejects a blank one, and
+          it is validated before any server-side lookup of the logged-in profile. */}
+      <input type="email" value={shippingAddress.email} onChange={(e) => setShippingAddress({...shippingAddress, email: e.target.value})} placeholder="Email" required />
       <input value={shippingAddress.firstName} onChange={(e) => setShippingAddress({...shippingAddress, firstName: e.target.value})} placeholder="First Name" required />
       <input value={shippingAddress.lastName} onChange={(e) => setShippingAddress({...shippingAddress, lastName: e.target.value})} placeholder="Last Name" required />
       <input value={shippingAddress.line1} onChange={(e) => setShippingAddress({...shippingAddress, line1: e.target.value})} placeholder="Address" required />
       <input value={shippingAddress.city} onChange={(e) => setShippingAddress({...shippingAddress, city: e.target.value})} placeholder="City" required />
       <input value={shippingAddress.postalCode} onChange={(e) => setShippingAddress({...shippingAddress, postalCode: e.target.value})} placeholder="Postal Code" required />
 
-      {shippingRates.length > 0 && (
-        <select value={selectedRate || ''} onChange={(e) => setSelectedRate(e.target.value)}>
-          {shippingRates.map((rate) => (
-            // speedTier for live carrier rates; the merchant's own name for zone rates
-            <option key={rate.id} value={rate.id}>{rate.speedTier ? TIER_LABELS[rate.speedTier] : rate.name} - ${rate.price}</option>
-          ))}
-        </select>
-      )}
-
       <button type="submit" disabled={submitting}>
-        {submitting ? 'Processing...' : 'Place Order'}
+        {submitting ? 'Loading delivery options...' : 'Continue to delivery'}
       </button>
     </form>
   );
@@ -5909,6 +6194,9 @@ export default function CheckoutPage() {
 > **Key Points:**
 >
 > - Both guests and logged-in users go through `createCheckout()` → `completeCheckout()`
+> - `setShippingAddress()` returns the rates for the address it just saved. Put them in state; a separate `getShippingRates()` call is not needed.
+> - Split the page into two phases. Fetching rates and completing the order in one submit means the shopper never gets to choose, and you silently charge whichever rate came back first.
+> - `email` is required on `setShippingAddress`, for logged-in shoppers too. It is validated before any service code runs, so the server cannot fill it in from the customer record.
 > - Guest session cart is created automatically by `smart*` methods
 > - Call `client.onCheckoutComplete()` after successful payment to clear the session cart
 > - Call `client.syncCartOnLogin()` when a user logs in to merge their guest cart
@@ -5978,6 +6266,7 @@ export default function CheckoutPage() {
     setSubmitting(true);
     try {
       const { rates } = await client.setShippingAddress(checkout.id, {
+        email, // required on every call, even after setCheckoutCustomer
         firstName, lastName,
         line1: address,
         city, postalCode, country,