brainerce 1.59.0 → 2.0.0

package/README.md

@@ -55,20 +55,21 @@ 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()`                                                                                                          | ✅          |
 | Login + verification branch                              | `client.loginCustomer()`                                                                                                                                     | ✅          |
 | Forgot / reset password                                  | `client.forgotPassword()`, `client.resetPassword()`                                                                                                          | ✅          |
 | OAuth sign-in buttons + callback handler                 | `client.getAvailableOAuthProviders()`                                                                                                                        | ✅          |
-| Account area (profile + order history)                   | `client.getMyProfile()`, `client.getMyOrders()`                                                                                                              | ✅          |
+| Account area (profile + order history)                   | `client.getMyProfile()`, `client.updateMyProfile()`, `client.getMyOrders()`                                                                                  | ✅          |
 | 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 |
 | Site chrome (header + footer + announcement bar)         | `client.content.header.get()`, `client.content.footer.get()`, `client.content.announcement.list()`                                                           | ✅          |
 | FAQ page                                                 | `client.content.faq.get('main', locale)`                                                                                                                     | conditional |
 | Static pages catch-all (`/pages/[slug]`)                 | `client.content.page.getBySlug(slug, locale)`                                                                                                                | conditional |
@@ -98,6 +99,7 @@ Violating any of these causes production incidents or broken orders. Read them b
 
 - ALWAYS handle the `requiresVerification` flag in `registerCustomer` and `loginCustomer` responses. If true, route to the verify-email step BEFORE treating the user as logged in.
 - ALWAYS build the verify-email, forgot-password, and reset-password flows even when the store currently has email verification disabled. They auto-hide when unused.
+- ALWAYS read `requireBirthday` from `getStoreInfo()` before rendering the signup form. When it is true the merchant made the birthday mandatory on that sales channel, and `registerCustomer` returns HTTP 400 unless you send both `birthMonth` (1-12) and `birthDay` (1-31). Month and day only, never a year.
 - ALWAYS build OAuth button placeholders and a callback handler even when no OAuth provider is configured.
 - NEVER silently swallow auth errors. Render the specific error (invalid credentials, expired token, rate limited).
 
@@ -170,17 +172,19 @@ 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.
 
 ### Registration flow
 
-1. Collect email, password, first name, last name.
+1. Collect email, password, first name, last name. Read `requireBirthday` from `getStoreInfo()`: when it is true, collect a birthday month and day as well, because the register call is rejected without them.
 2. Call `registerCustomer`:
    ```ts
    const result = await client.registerCustomer({ email, password, firstName, lastName });
+   // Channel requires a birthday? Send both fields, never a year:
+   // { email, password, firstName, lastName, birthMonth: 4, birthDay: 17 }
    ```
 3. Branch on `result.requiresVerification`:
    - `true` → store token temporarily, route to verify-email UI (do NOT set token yet)
@@ -206,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:
@@ -276,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.
 
@@ -1022,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',
@@ -1112,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,
@@ -1907,7 +1928,8 @@ fields.forEach((field) => {
   // field.minLength, field.maxLength: validation for text fields
   // field.minValue, field.maxValue: validation for number fields
   // field.dateAvailability: constraints for DATE/DATETIME fields (blocked
-  //   weekdays/dates, min/max date, business hours + slots) — see
+  //   weekdays/dates, min/max date, leadTimeMinutes/cutoffTime/maxDaysAhead,
+  //   business hours + slots) — see
   //   computeAvailableSlots()/getBusinessHoursForDate()/isDateValueAllowed()
   //   below. DATE values are sent as "YYYY-MM-DD"; DATETIME as one ISO-8601
   //   value — never a date with a slot LABEL glued on ("...T13:00-14:00" is
@@ -2104,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.
@@ -2115,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
@@ -2571,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',
@@ -2589,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
@@ -2681,7 +2889,8 @@ const updatedCheckout = await client.setCheckoutCustomFields(checkoutId, {
 **DATE / DATETIME fields with availability constraints**
 
 A `DATE`/`DATETIME` field's `dateAvailability` (blocked weekdays, blocked specific
-dates, min/max date range, and — for `DATETIME` — business hours + time
+dates, min/max date range, the relative bounds `leadTimeMinutes` / `cutoffTime` /
+`maxDaysAhead`, and — for `DATETIME` — business hours + time
 slots) is a merchant-configured restriction on which values the customer may
 pick. Use `computeAvailableSlots()` / `getBusinessHoursForDate()` /
 `isDateValueAllowed()` to drive your own date-picker/slot-picker UI — the SDK
@@ -2700,19 +2909,24 @@ const { timezone } = await client.getStoreInfo(); // IANA string, e.g. "Asia/Jer
 const deliveryField = fields.find((f) => f.key === 'delivery_slot');
 const availability = deliveryField?.dateAvailability;
 
+// The clock. Without it leadTimeMinutes/cutoffTime/maxDaysAhead are SKIPPED and
+// the picker offers days the server refuses; `now` defaults to this instant.
+const clock = { timezone };
+
 // Disable days on your calendar of choice. Note the SECOND condition: once
 // businessHours has any entry it is an ALLOWLIST, so a weekday it doesn't
 // mention is closed all day even though the calendar rules accept it.
 const isDayDisabled = (ymd: string) =>
-  !isCalendarDateAllowed(ymd, availability) ||
+  !isCalendarDateAllowed(ymd, availability, clock) ||
   (!!availability?.businessHours?.length &&
-    getBusinessHoursForDate(availability, ymd).length === 0);
+    getBusinessHoursForDate(availability, ymd, clock).length === 0);
 
 // Once the customer picks a day, offer times. computeAvailableSlots() returns
 // [] when the field has no slotDurationMinutes — that is NOT "day closed",
-// which is why the windows are checked separately.
-const slots = computeAvailableSlots(availability, '2026-08-15'); // ["09:00", "09:30", ...]
-const windows = getBusinessHoursForDate(availability, '2026-08-15'); // [{ weekday, open, close }]
+// which is why the windows are checked separately. A day with two windows
+// (mornings and evenings) yields both, in chronological order.
+const slots = computeAvailableSlots(availability, '2026-08-15', clock); // ["09:00", "09:30", ...]
+const windows = getBusinessHoursForDate(availability, '2026-08-15', clock); // [{ weekday, open, close }]
 
 if (slots.length) {
   // Render slot buttons; the submitted time must equal a slot start exactly.
@@ -2736,6 +2950,19 @@ What you read back is normalized, not the string you sent: `YYYY-MM-DD` for
 `DATE`, an ISO-8601 UTC instant for `DATETIME`. Use `parseDateFieldValue()` if
 you want to apply the exact same parse client-side before submitting.
 
+**Relative bounds.** `leadTimeMinutes` puts the earliest bookable moment at
+`now + leadTime`. `cutoffTime` ("HH:mm", store-local) pushes the earliest
+bookable DATE on by a further day once the store clock reaches it, which is how
+"order by 14:00 for tomorrow" is expressed. `maxDaysAhead` is a rolling ceiling
+counted from today. All three are re-resolved on every call, so unlike an
+absolute `minDate` they never go stale, and all three apply to plain `DATE`
+fields as well. They are accepted on **checkout** custom fields only: a product
+metafield and an order custom field are written by an admin rather than picked
+by a shopper, so there is no ordering moment to measure them from and the API
+rejects them there. `resolveRelativeBounds(availability, clock)` returns the
+concrete dates they currently mean, which is what to show a shopper who asked
+for something too soon.
+
 The backend independently re-validates every submitted value against the same
 constraints at write time — this is a client-side UX aid, not the source of
 enforcement.
@@ -2818,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',
@@ -3481,12 +3709,24 @@ if (intent.clientSdk?.renderType === 'sandbox') {
 > characters" produces a 400 the shopper cannot explain, and render the server's
 > message verbatim when one comes back.
 
+> **Birthday fields.** `birthMonth` (1-12) and `birthDay` (1-31) are optional,
+> month and day only, never a year. Send both or neither: one on its own is
+> rejected with HTTP 400, and so is a day the month does not have. When
+> `getStoreInfo().requireBirthday` is true the merchant made the birthday
+> mandatory on that sales channel and a register call without it fails with
+> HTTP 400. That flag only reaches sales-channel mode (`salesChannelId`); a
+> `storeId`-mode storefront never receives it and its register route never
+> enforces it.
+
 ```typescript
 const auth = await client.registerCustomer({
   email: 'customer@example.com',
   password: 'SecurePass123!',
   firstName: 'John',
   lastName: 'Doe',
+  // Optional, unless getStoreInfo().requireBirthday is true. Both or neither.
+  birthMonth: 4,
+  birthDay: 17,
 });
 
 // Check if email verification is required
@@ -3557,6 +3797,12 @@ console.log(profile.firstName);
 console.log(profile.email);
 console.log(profile.addresses);
 
+// Birthday the customer saved: month and day only, never a year. Both fields
+// arrive together or neither does, so testing one is enough.
+if (profile.birthMonth && profile.birthDay) {
+  console.log(`Birthday: ${profile.birthDay}/${profile.birthMonth}`);
+}
+
 // profile.role is a free-form segment the merchant sets from the dashboard
 // (e.g. "wholesale", "vip") — not customer-editable. Use it to gate custom
 // storefront features/UI: wholesale pricing, a VIP section, etc.
@@ -3565,6 +3811,30 @@ if (profile.role === 'wholesale') {
 }
 ```
 
+#### Update Customer Profile
+
+Storefront or vibe-coded mode, requires `customerToken`. The call returns the
+saved `CustomerProfile`, so re-render the form from the response instead of
+from what you sent. `email` and `role` are not customer-editable and are not
+accepted here.
+
+```typescript
+const updated = await client.updateMyProfile({
+  firstName: 'John',
+  lastName: 'Doe',
+  phone: '+15550100',
+  acceptsMarketing: true,
+  // Birthday: month and day only, never a year. Send both or neither, and the
+  // day has to exist in the month (day 31 in February is rejected with 400).
+  birthMonth: 4,
+  birthDay: 17,
+});
+
+// The saved birthday comes back on the response and on getMyProfile(), so the
+// profile form shows what the customer stored instead of two empty fields.
+console.log(updated.birthMonth, updated.birthDay);
+```
+
 #### Get Customer Orders
 
 ```typescript
@@ -3646,10 +3916,15 @@ await client.registerCustomer({ email, password, referralCode: refFromQuery });
 // bonus (held through the program's pending window, like order points).
 ```
 
-Birthday gifts need no SDK calls beyond profile data: set the customer's
-`birthMonth`/`birthDay` (1-12 / 1-31, no year) via `updateMyProfile()` and the
-platform emails a one-time gift coupon ahead of their birthday automatically
-(when the store has it enabled).
+Birthday gifts need no SDK calls beyond profile data: save the customer's
+`birthMonth`/`birthDay` (1-12 / 1-31, month and day only, never a year) via
+`updateMyProfile()` and the platform emails a one-time gift coupon ahead of
+their birthday automatically (when the store has it enabled). Both values come
+back on `getMyProfile()`, on `getCheckoutPrefillData()` and on the `Customer`
+read types, so a profile form renders the birthday the customer already gave
+you rather than an empty pair of fields. `registerCustomer()` accepts the same
+two fields, and a channel with `requireBirthday` turned on insists on them at
+signup.
 
 #### Paid Loyalty Membership
 
@@ -3741,6 +4016,8 @@ const auth = await client.registerCustomer({
   email: 'customer@example.com',
   password: 'SecurePass123!',
   firstName: 'John',
+  // Add birthMonth + birthDay here too when getStoreInfo().requireBirthday is
+  // true, or this call fails with HTTP 400 before any email is sent.
 });
 
 if (auth.requiresVerification) {
@@ -5146,12 +5423,17 @@ is what stops an API key from escalating its own team permissions. Pointing the
 the correct path would earn a `403` instead of a `404`. Invite, re-scope and remove
 members in the dashboard.
 
-> **The older account-level methods are not the workaround.** `getTeamMembers`,
+> **The older account-level methods are not a substitute for this.** `getTeamMembers`,
 > `getTeamInvitations`, `inviteTeamMember`, `resendTeamInvitation`, `revokeTeamInvitation`,
 > `updateTeamMemberRole` and `removeTeamMember` do still reach `/api/v1/team/…` — but they
-> manage the **account** team, not a store's, and all seven are `@deprecated`. Their JSDoc
-> tells you to migrate to the store-level methods named above; ignore that advice, because
-> those methods 404. Don't build new integrations on either family.
+> manage the **account** team, not a store's. They will not invite anyone to a store or
+> scope a member to a sales channel; only the dashboard does that.
+>
+> **For the account team, they remain the supported call.** All seven are tagged
+> `@deprecated`, which records an intent to retire them — not a migration you can perform
+> today. There is no API-key replacement: the store-level methods named above are
+> dashboard-only. Keep using these until an API-key route ships, and expect the tag to
+> outlive this note.
 
 ### Email Settings & Templates
 
@@ -5314,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
@@ -5726,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(() => {
@@ -5761,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);
@@ -5769,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);
@@ -5800,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>
   );
@@ -5831,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
@@ -5900,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,
@@ -6082,6 +6449,8 @@ export default function RegisterPage() {
     setLoading(true);
     setError('');
     try {
+      // Add birthMonth + birthDay to this call (both, never a year) when
+      // getStoreInfo().requireBirthday is true for the channel.
       const auth = await client.registerCustomer({ email, password, firstName, lastName });
 
       // Check if email verification is required
@@ -6183,6 +6552,9 @@ export default function AccountPage() {
           <h2 className="text-xl font-bold mb-4">Profile</h2>
           <p><strong>Name:</strong> {profile.firstName} {profile.lastName}</p>
           <p><strong>Email:</strong> {profile.email}</p>
+          {profile.birthMonth && profile.birthDay && (
+            <p><strong>Birthday:</strong> {profile.birthDay}/{profile.birthMonth}</p>
+          )}
         </div>
 
         <div className="border rounded p-6">
@@ -6304,6 +6676,89 @@ const forms = await brainerce.contactForms.list();
 
 **Rate limit:** 3 submissions per 60 seconds per IP. Include a hidden honeypot field (and do not submit it) — bots that auto-fill every input will be rejected.
 
+**A form keyed `newsletter` is still an inquiry.** The key is a label, not a behaviour: the submission files a message and never touches marketing consent, so that address can never receive a campaign. For a mailing list, use [Newsletter Signup](#newsletter-signup-marketing-opt-in).
+
+---
+
+## Newsletter Signup (marketing opt-in)
+
+**SDK >= 1.60.** The email-capture popup, the footer subscribe bar, the exit-intent modal.
+
+```typescript
+await brainerce.marketing.subscribe({
+  email: 'jane@example.com',
+  locale: 'he', // language of the confirmation email
+  source: 'popup', // free-form, for the merchant's reporting
+  honeypot: hiddenFieldValue, // must be empty
+});
+// → { ok: true }
+```
+
+Also accepts `firstName`, `lastName`, and `sourceMetadata` (referrer, UTM params, the page the popup fired on).
+
+**⛔ It does not subscribe anyone.** The contact is created and mailed a confirmation link; the address is unmailable — and invisible to every campaign audience — until the recipient clicks it. Render **"Check your email to confirm — including your spam folder"** on success, never "You're subscribed". The spam-folder half matters: a confirmation filtered there is the commonest reason a signup never converts, and the 24-hour resend cooldown means no second copy arrives. Single opt-in is not available: without the click, anyone could subscribe anyone else's address.
+
+**⛔ The response carries no information.** `{ ok: true }` is returned identically for a brand-new address, one that confirmed months ago, one inside its 24-hour resend cooldown, and one suppressed after a hard bounce — otherwise the form would become a way to test who shops at this store. Show one message for every success; there is no branch to write.
+
+**Rate limit:** 3 requests per 60 seconds per IP, plus one confirmation email per address per store per 24 hours. A submission inside that cooldown still returns `{ ok: true }` and silently sends nothing — do not treat it as a failure or retry it.
+
+**Locale:** pass it on a multi-language storefront, or the confirmation email falls back to the store's language. `he` and `en` are written; anything else gets English.
+
+**No discount code is minted.** For a "10% off your first order" popup, the merchant creates one coupon with the `customer_first_order` condition and you display that fixed code after a successful call.
+
+The contact appears at `Customers` in the dashboard immediately, with **Accepts marketing** off; it flips on at confirmation. It is an ordinary guest customer record — no password, no account — and is the same row if that person later registers or checks out.
+
+---
+
+## Back-in-Stock Alerts
+
+**SDK >= 1.61.** The "email me when this is back" button on a sold-out product.
+
+```typescript
+await brainerce.stockAlerts.subscribe({
+  email: 'jane@example.com',
+  productId: product.id,
+  variantId: selectedVariant.id, // pass on ANY product with variants
+  locale: 'he', // language of the alert email
+  honeypot: hiddenFieldValue, // must be empty
+});
+// → { ok: true }
+```
+
+**⛔ It is not a subscription.** One email, about one item, carrying a link that stops it. No customer account is created and no marketing consent is granted. Label the button **"Email me when it's back"**, never "Subscribe" — and because it grants no consent, never hide it from a shopper who unsubscribed from your marketing.
+
+**⛔ Render it only when `getStoreInfo().stockAlertsEnabled !== false`, the item is out of stock, AND it cannot be backordered.** Requests for anything else — a storefront whose merchant switched the feature off, an in-stock item, a backorderable one, an untracked one, an unknown product id — are silently ignored, so a button in the wrong place looks like it worked and does nothing.
+
+```typescript
+const store = await brainerce.getStoreInfo();
+// `inv` is the SELECTED VARIANT's inventory when there is one, else the product's.
+const inv = selectedVariant?.inventory ?? product.inventory;
+
+const canOfferStockAlert =
+  store.stockAlertsEnabled !== false &&
+  inv?.trackingMode === 'TRACKED' &&
+  !inv.canPurchase &&
+  (inv.backorderMode ?? 'NONE') === 'NONE';
+```
+
+`backorderMode` is on `InventoryInfo` from SDK 1.61; older backends omit it, so treat `undefined` as `'NONE'`.
+
+The merchant controls the switch — and how many people are emailed per unit restocked — under **Channel settings → Inventory**, alongside the low-stock warning.
+
+**⛔ Pass `variantId` on every variable product.** Without it the alert waits on the product as a whole, so a shopper who wanted the medium is mailed when the small returns and arrives to find their size still gone.
+
+**⛔ The response carries no information.** `{ ok: true }` is returned identically for a new request, a duplicate, an unknown product, an item already in stock, and an address suppressed after a hard bounce — otherwise the button would become a way to read the store's stock levels. Show one message for every success; there is no branch to write.
+
+**Sending is not immediate, and not to everyone.** Availability is `total - reserved`, so an expiring cart briefly lifts a sold-out item above zero; the alert waits for stock to hold for a few minutes, then goes out in waves sized to the units that came back (500 waiting and 3 units restocked is roughly 9 emails, oldest request first). A shopper can therefore sit through a restock without hearing, so never promise "you'll be the first to know".
+
+**Rate limit:** 5 requests per 60 seconds per IP, at most 25 open alerts per address per store, and a 90-day life on an unfired alert. A duplicate request is a no-op, not a second alert; once an alert has fired the person can ask again the next time that item sells out.
+
+**Locale:** pass it on a multi-language storefront, or the alert falls back to the store's language. `he` and `en` are written; anything else gets English.
+
+**What it does not do:** no SMS or WhatsApp, no price-drop alerts, and no merchant-editable template — the body is fixed so it can never start carrying a discount code, which would turn a transactional message into a marketing one needing an unsubscribe link it does not have.
+
+The merchant reads the demand at `Products → Back-in-Stock Waitlist`: products ranked by how many people are waiting, with the addresses behind each number. There is no way to mail those people anything else from there, by design.
+
 ---
 
 ## Storefront Bot (AI chat widget)
@@ -6383,16 +6838,62 @@ export async function POST(req: Request) {
 
 ### Webhook Events
 
-| Event                | Description                     |
-| -------------------- | ------------------------------- |
-| `product.created`    | New product created             |
-| `product.updated`    | Product details changed         |
-| `product.deleted`    | Product removed                 |
-| `inventory.updated`  | Stock levels changed            |
-| `order.created`      | New order received              |
-| `order.updated`      | Order status changed            |
-| `cart.abandoned`     | Cart abandoned (no activity)    |
-| `checkout.completed` | Checkout completed successfully |
+**These 21 event types are what a subscription can actually register.** The
+backend validates the `events` array on create against exactly this list, so
+anything outside it is rejected rather than silently accepted.
+
+| Event                 | Description                                                                                                                                                                                              |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `order.created`       | New order placed (any payment status)                                                                                                                                                                    |
+| `order.updated`       | Order metadata changed (status, address, items)                                                                                                                                                          |
+| `order.paid`          | Order is paid — provider capture **or** a merchant-recorded out-of-band payment (cash on delivery, bank transfer). Never assume a provider was involved; `payment.succeeded` does **not** fire for these |
+| `order.fulfilled`     | All items marked shipped/delivered                                                                                                                                                                       |
+| `order.cancelled`     | Order cancelled (by merchant or customer)                                                                                                                                                                |
+| `order.refunded`      | Order fully or partially refunded                                                                                                                                                                        |
+| `customer.created`    | New customer account created                                                                                                                                                                             |
+| `customer.updated`    | Customer profile or contact details changed                                                                                                                                                              |
+| `customer.deleted`    | Customer account deleted                                                                                                                                                                                 |
+| `product.created`     | New product added to catalog                                                                                                                                                                             |
+| `product.updated`     | Product attributes, variants, or pricing changed                                                                                                                                                         |
+| `product.deleted`     | Product removed from catalog                                                                                                                                                                             |
+| `inventory.updated`   | Stock level changed (any reason)                                                                                                                                                                         |
+| `inventory.low`       | Stock fell below the low-stock threshold                                                                                                                                                                 |
+| `checkout.completed`  | Checkout completed (synonym of `order.created` for now)                                                                                                                                                  |
+| `checkout.abandoned`  | Cart inactive for 1+ hours with no completion                                                                                                                                                            |
+| `payment.succeeded`   | Payment provider confirmed funds captured                                                                                                                                                                |
+| `payment.failed`      | Payment provider rejected the transaction                                                                                                                                                                |
+| `payment.refunded`    | Refund posted to the customer                                                                                                                                                                            |
+| `blog.post.published` | Post went live (manual, scheduled, or SEO Autopilot)                                                                                                                                                     |
+| `blog.post.updated`   | Published post content changed                                                                                                                                                                           |
+
+Payload shapes for each are in the
+[Event Catalogue](https://brainerce.com/docs/webhooks/events).
+
+`customer.created` now fires for **shopper self-signup on your storefront**, not
+just merchant-created customers, so a storefront that registers customers will
+start seeing it.
+
+> **⚠️ The `WebhookEventType` type does not match this table yet — in both
+> directions.** Treat the table, not the type, as the truth about what you can
+> subscribe to.
+>
+> **14 subscribable events are missing from the type:** `order.paid`,
+> `order.fulfilled`, `order.cancelled`, `order.refunded`, `customer.created`,
+> `customer.updated`, `customer.deleted`, `inventory.low`, `checkout.abandoned`,
+> `payment.succeeded`, `payment.failed`, `payment.refunded`,
+> `blog.post.published`, `blog.post.updated`. So
+> `isWebhookEventType(event, 'customer.created')` and a
+> `createWebhookHandler({ 'order.paid': … })` key **fail to compile**, even
+> though both deliver correctly at runtime. Cast the name
+> (`'customer.created' as WebhookEventType`) or read `event.event` as a
+> `string` and switch on it yourself. Do not conclude the event does not exist.
+>
+> **8 names in the type cannot be subscribed to at all:** `coupon.created`,
+> `coupon.updated`, `coupon.deleted`, `cart.created`, `cart.updated`,
+> `cart.abandoned`, `checkout.started`, `checkout.failed`. These compile
+> cleanly and then fail at subscription time. `cart.abandoned` in particular
+> was listed as a supported event here for a long time — use
+> `checkout.abandoned` instead.
 
 ---