brainerce 1.51.0 → 1.53.0

package/README.md

@@ -94,9 +94,9 @@ Violating any of these causes production incidents or broken orders. Read them b
 
 ### Token handling
 
-- Customer auth tokens (`result.token` from `loginCustomer`/`registerCustomer`) should be passed to `client.setCustomerToken(token)`. The SDK stores session state internally.
+- Customer auth tokens (`result.token` from `loginCustomer`/`registerCustomer`) should be passed to `client.setCustomerToken(token)`. The SDK stores session state internally. `setCustomerToken` is a plain setter — always follow it with `await client.syncCartOnLogin()`, or the shopper's guest cart is never attached to their account and identity-keyed features (first-order discounts, per-customer usage caps, abandoned-cart recovery) misbehave.
 - NEVER put the admin API key (`brainerce_*`) in client code. It is a server-only secret.
-- OAuth callbacks arrive with a one-time `auth_code` URL param. Call `client.exchangeOAuthCode(authCode)` to swap it for the JWT and apply via `setCustomerToken`. (The legacy `?token=` URL param is still emitted for backward compatibility but will be removed in the next major release.)
+- OAuth callbacks arrive with a one-time `auth_code` URL param. Call `client.exchangeOAuthCode(authCode)` to swap it for the JWT, apply via `setCustomerToken`, then call `client.syncCartOnLogin()` to claim the guest cart. (The legacy `?token=` URL param is still emitted for backward compatibility but will be removed in the next major release.)
 
 ### i18n
 
@@ -142,6 +142,9 @@ These sequences are non-negotiable. The order of SDK calls matters.
    ```ts
    await client.selectShippingMethod(checkoutId, rateId);
    ```
+   Label each rate with `rate.speedTier` (`'cheapest' | 'balanced' | 'fastest'`) and
+   `rate.estimatedDays` — **not** `rate.name`, which for live carrier rates is the
+   carrier's own service code. Manual zone rates carry no `speedTier`; use their `name`.
 4. Fetch available payment providers:
    ```ts
    const providers = await client.getPaymentProviders();
@@ -164,9 +167,9 @@ These sequences are non-negotiable. The order of SDK calls matters.
    ```
 3. Branch on `result.requiresVerification`:
    - `true` → store token temporarily, route to verify-email UI (do NOT set token yet)
-   - `false` → `client.setCustomerToken(result.token)`, route to account
+   - `false` → `client.setCustomerToken(result.token)`, then `await client.syncCartOnLogin()`, route to account
 4. On verify-email: collect 6-digit code → `client.verifyEmail(code)`. Offer resend via `client.resendVerificationEmail()`.
-5. After `verifyEmail` resolves: `client.setCustomerToken(result.token)`, route to account.
+5. After `verifyEmail` resolves: `client.setCustomerToken(result.token)`, then `await client.syncCartOnLogin()`, route to account.
 
 > Build the verify-email step even if verification is currently disabled — it auto-hides.
 
@@ -179,7 +182,7 @@ These sequences are non-negotiable. The order of SDK calls matters.
    ```
 3. Branch on `result.requiresVerification`:
    - `true` → route to verify-email
-   - `false` → `client.setCustomerToken(result.token)`, route to previous page or account
+   - `false` → `client.setCustomerToken(result.token)`, then `await client.syncCartOnLogin()`, route to previous page or account
 4. Always offer OAuth buttons from `client.getAvailableOAuthProviders()` — render the region even when empty, it auto-populates when a provider is enabled.
 5. Render specific errors (bad credentials, rate limited, disabled) — never swallow them.
 
@@ -230,11 +233,26 @@ the credential, no customer token needed.
    const code = params.get('auth_code');
    if (code) {
      const result = await client.exchangeOAuthCode(code);
-     client.setCustomerToken(result.token); // then redirect to account
+     client.setCustomerToken(result.token);
+     await client.syncCartOnLogin(); // REQUIRED — claims the guest cart
+     // then redirect to account
    }
    ```
    The legacy `?token=` URL param is still emitted for backward compatibility but will be removed in the next major release — migrate to `auth_code` now.
-4. On `oauth_error` query param: redirect to login with an error message.
+4. On failure the browser lands on **the same `redirectUrl`** (never on the API host), carrying `oauth_error` + `error_description`:
+   ```ts
+   const oauthError = params.get('oauth_error') as OAuthErrorCode | null;
+   if (oauthError) {
+     // `oauth_error` is a stable snake_case code — switch on it for localized copy.
+     // `error_description` is English developer detail; do not show it to shoppers.
+     if (oauthError === 'link_blocked_unverified_password_account') {
+       router.push('/verify-email'); // a retry will not help — the address needs verifying
+     } else {
+       router.push(`/login?error=${oauthError}`);
+     }
+   }
+   ```
+   The code list is open — the provider's own codes (`access_denied`, …) pass through, so always handle the default case.
 
 > Build the OAuth button region AND the callback handler even when no providers are configured.
 
@@ -701,6 +719,36 @@ const address: SetShippingAddressDto = {
 };
 ```
 
+**And no coordinates.** The address endpoints validate against a strict
+allow-list — one property that isn't on the DTO rejects the whole call with
+`400 "property lat should not exist"`, which doesn't degrade: it blocks the
+address step for every shopper. `getAddressDetails()` resolves an address
+carrying `lat`, `lng` and `formattedAddress`, so this is the one that bites:
+
+```typescript
+// ❌ WRONG — over raw HTTP, this 400s on every address
+await fetch(`${base}/checkout/${id}/shipping-address`, {
+  method: 'PATCH',
+  body: JSON.stringify({ ...address, email, firstName, lastName }), // lat/lng ride along
+});
+
+// ✅ CORRECT — the SDK (>= 1.53.0) strips lat/lng/formattedAddress for you,
+// so the spread is safe here. Pass `placeId`: that is what reaches zone
+// matching, since the server resolves the coordinates itself and never takes
+// them from the client (zone matching decides which rate gets charged).
+await client.setShippingAddress(checkoutId, {
+  ...address,
+  email,
+  firstName,
+  lastName,
+  placeId: picked.placeId,
+  placeSessionToken: sessionToken,
+});
+```
+
+Use `address.lat` / `address.lng` for your own UI — a map pin, a distance
+readout — and nothing else.
+
 ### 10. OAuth - Use `authorizationUrl`, NOT `url`
 
 ```typescript
@@ -967,9 +1015,23 @@ const suggestions = await client.getAddressSuggestions('Rothschild 1', sessionTo
 // [{ placeId: 'ChIJ...', description: 'Rothschild Blvd 1, Tel Aviv-Yafo' }, ...]
 
 // On picking a suggestion — reuse the SAME sessionToken to end the session
-const { address, inZone } = await client.getAddressDetails(suggestions[0].placeId, sessionToken);
+const picked = suggestions[0];
+const { address, inZone } = await client.getAddressDetails(picked.placeId, sessionToken);
 // address: { line1, city, region, postalCode, country, lat, lng, formattedAddress }
 
+// `country` can come back as an EMPTY STRING, and so can `region`. Google
+// omits the country entirely for places whose sovereignty it declines to
+// attribute — verified live for ordinary residential addresses such as Ramat
+// Shlomo, Giv'at Ze'ev, Modi'in Ilit and Ma'ale Adumim. The API deliberately
+// does not guess one. Ask the shopper to confirm the country in that case; the
+// rest of the address (line1, city, lat/lng, formattedAddress) is still good.
+// Note this also makes `inZone` read false when the store's zones are
+// country-listed — a polygon zone can still match, since the server matches
+// against the coordinates it resolves from `placeId`.
+if (!address.country) {
+  // leave your country <select> for the shopper rather than sending ''
+}
+
 // address.region is Google's own administrative-area code — usually (not
 // guaranteed) the same ISO 3166-2 subdivision code this store's own region
 // lists use. Validate against destinations.regions before trusting it;
@@ -978,11 +1040,26 @@ const destinations = await client.getShippingDestinations();
 const validRegions = destinations.regions[address.country] ?? [];
 const region = validRegions.some((r) => r.code === address.region) ? address.region : '';
 
+// Pass `placeId` through — that, not the coordinates, is what reaches zone
+// matching. The server never accepts `lat`/`lng` from the client, because zone
+// matching decides which shipping rate gets charged; it re-resolves the placeId
+// itself (cached, so no extra billed call) and matches map-drawn zones against
+// those exact coordinates instead of re-geocoding the text. Clear it if the
+// shopper then edits any address field.
+//
+// The `...address` spread below is safe even though `address` carries `lat`,
+// `lng` and `formattedAddress`: the SDK drops those three before sending. The
+// endpoint rejects unknown properties outright (`400 "property lat should not
+// exist"`), so if you call it over raw HTTP instead of the SDK, omit them
+// yourself. Use `address.lat`/`address.lng` for your own UI — a map pin, a
+// distance readout — and nothing else.
 await client.setShippingAddress(checkout.id, {
   firstName: 'John',
   lastName: 'Doe',
   ...address,
   region,
+  placeId: picked.placeId,
+  placeSessionToken: sessionToken,
 });
 
 if (!inZone) {
@@ -1722,7 +1799,10 @@ fields.forEach((field) => {
   // 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
-  //   computeAvailableSlots()/isDateValueAllowed() below
+  //   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
+  //   read as a -14:00 UTC offset and rejected)
   // field.enumValues: CustomizationFieldOption[] for SELECT/MULTI_SELECT
   //   each option: { label: string, value: string, swatchColor?: string, swatchImageUrl?: string }
   //   use option.value for metadata submission, option.label for display
@@ -2144,6 +2224,13 @@ These low-level methods are available for advanced use cases. For most storefron
 const cart = await client.createCart();
 ```
 
+> **GA4 server-side conversions:** if you called `client.loadGoogleAnalytics('G-XXXXXXX')`
+> once at app startup (see [Analytics](#analytics-optional-server-side-ga4-conversions)
+> below), the resolved `client_id`/`session_id` are auto-attached to `createCart`,
+> `addToCart`, `setCheckoutCustomer`, and `setShippingAddress` automatically — no
+> other code changes needed. Pass `analyticsClientId`/`analyticsSessionId`
+> explicitly on any of these calls to override.
+
 #### Get Cart
 
 ```typescript
@@ -2164,6 +2251,8 @@ const cart = await client.addToCart(cartId, {
   variantId: 'variant_id', // Optional: for VARIABLE products
   quantity: 2,
   notes: 'Gift wrap please', // Optional
+  // analyticsClientId / analyticsSessionId: auto-attached if you called
+  // loadGoogleAnalytics() — no need to pass these yourself.
 });
 ```
 
@@ -2214,6 +2303,9 @@ interface Cart {
   couponCode?: string | null;
   items: CartItem[];
   itemCount: number;
+  // GA4 stitch ids, if forwarded — see loadGoogleAnalytics() under Analytics.
+  analyticsClientId?: string | null;
+  analyticsSessionId?: string | null;
   createdAt: string;
   updatedAt: string;
 }
@@ -2340,6 +2432,8 @@ const checkout = await client.setCheckoutCustomer(checkoutId, {
   lastName: 'Doe',
   phone: '+1234567890', // Optional
   notes: 'Please leave the package at the door', // Optional order note (max 2000 chars)
+  // analyticsClientId / analyticsSessionId: auto-attached if you called
+  // loadGoogleAnalytics() — no need to pass these yourself.
 });
 ```
 
@@ -2357,12 +2451,44 @@ const { checkout, rates } = await client.setShippingAddress(checkoutId, {
   country: 'US',
   phone: '+1234567890', // Optional
   notes: 'Please leave the package at the door', // Optional order note (max 2000 chars)
+  placeId: picked.placeId, // Send whenever the address came from the autocomplete
+  placeSessionToken: sessionToken, // Optional — the same token used for it
 });
 
 // rates contains available shipping options
 console.log(rates); // ShippingRate[]
 ```
 
+> **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
+> cover the shopper. Without it the server falls back to geocoding the typed
+> address text, which is materially less precise — a same-named street in a
+> neighbouring city can outrank the right one, quoting the shopper another
+> area's rate or no delivery at all. **Clear `placeId` if the shopper edits any
+> address field after picking** — its coordinates describe the suggestion, not
+> the edited text. There is deliberately no `lat`/`lng` field: zone matching
+> decides which rate is charged, so coordinates are never accepted from the
+> client — the server resolves them from `placeId` itself.
+>
+> The endpoint rejects **any** unknown property with a `400` ("property lat
+> should not exist"), which blocks checkout entirely rather than degrading. So
+> that spreading `getAddressDetails().address` in here can't do that, the SDK
+> drops its `lat`, `lng` and `formattedAddress` before sending (once per client
+> it logs a `console.warn` saying so). Calling the REST endpoint directly
+> instead of through the SDK? Then omit those three yourself.
+
+> **One zone per address:** an address matches exactly ONE shipping zone and you
+> get only that zone's rates. When zones overlap, the lower `priority` wins;
+> otherwise the smaller drawn area does. If you want several options for the
+> same area, put several rates on one zone rather than several zones.
+
+> **Live carrier rates:** render `rate.speedTier` (`'cheapest' | 'balanced' | 'fastest'`)
+> and `rate.estimatedDays`, not `rate.name` — `name` is the carrier's own service
+> identifier and means nothing to a shopper. Rates arrive already narrowed to at most
+> three. Manual zone rates carry no `speedTier`; show their `name` as the merchant wrote
+> it. Full snippet under [Checkout Type Definition](#checkout-type-definition).
+
 > **Order notes:** every checkout page should render an optional **"Order
 > notes"** textarea by default. Send its value via `notes` on either
 > `setCheckoutCustomer` or `setShippingAddress` (whichever call your flow
@@ -2427,25 +2553,58 @@ const updatedCheckout = await client.setCheckoutCustomFields(checkoutId, {
 A `DATE`/`DATETIME` field's `dateAvailability` (blocked weekdays, blocked specific
 dates, min/max date range, and — for `DATETIME` — business hours + time
 slots) is a merchant-configured restriction on which values the customer may
-pick. Use `computeAvailableSlots()` / `isDateValueAllowed()` to drive your own
-date-picker/slot-picker UI — the SDK ships no calendar component, only the
-math (evaluated in the **store's** timezone, never the browser's):
+pick. Use `computeAvailableSlots()` / `getBusinessHoursForDate()` /
+`isDateValueAllowed()` to drive your own date-picker/slot-picker UI — the SDK
+ships no calendar component, only the math (evaluated in the **store's**
+timezone, never the browser's):
 
 ```typescript
-import { computeAvailableSlots, isDateValueAllowed } from 'brainerce';
+import {
+  computeAvailableSlots,
+  getBusinessHoursForDate,
+  isCalendarDateAllowed,
+  isDateValueAllowed,
+} from 'brainerce';
 
 const { timezone } = await client.getStoreInfo(); // IANA string, e.g. "Asia/Jerusalem"
 const deliveryField = fields.find((f) => f.key === 'delivery_slot');
+const availability = deliveryField?.dateAvailability;
+
+// 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) ||
+  (!!availability?.businessHours?.length &&
+    getBusinessHoursForDate(availability, ymd).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 }]
+
+if (slots.length) {
+  // Render slot buttons; the submitted time must equal a slot start exactly.
+} else if (windows.length) {
+  // Render a free time input bounded by [windows[0].open, windows[0].close).
+} else {
+  // Genuinely closed that day.
+}
+```
 
-// Disable dates on your calendar of choice:
-const isDateDisabled = (candidate: Date) => {
-  const result = isDateValueAllowed(candidate, deliveryField?.dateAvailability, deliveryField!.type, timezone);
-  return !result.allowed;
-};
+**Submitting the value.** `DATE` is `"YYYY-MM-DD"`. `DATETIME` is one ISO-8601
+value — `"2026-08-15T09:30:00+03:00"`, or `"2026-08-15T09:30"` to mean the
+store's own timezone (the safest choice: a buyer travelling abroad would
+otherwise book their local hour). Fractional seconds are optional and may carry
+1–9 digits, so `Instant.toString()` / `datetime.isoformat()` output from a
+non-JS backend is accepted as-is. **Never build it by concatenating a slot
+label**: `` `${date}T13:00-14:00` `` is rejected with HTTP 400 because
+`-14:00` parses as a UTC offset, not a time range.
 
-// Once the customer picks a date, list its bookable time slots (DATETIME only):
-const slots = computeAvailableSlots(deliveryField?.dateAvailability, '2026-08-15'); // ["09:00", "09:30", ...]
-```
+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.
 
 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
@@ -2492,9 +2651,36 @@ interface ShippingRate {
   price: string;
   currency: string;
   estimatedDays?: number | null;
+  source?: 'manual' | 'carrier'; // 'manual' = merchant's zone rate, 'carrier' = live quote
+  carrier?: string; // carrier rates only, e.g. 'USPS'
+  service?: string; // carrier rates only, e.g. 'Priority'
+  speedTier?: 'cheapest' | 'balanced' | 'fastest'; // carrier rates only — render this, not `name`
 }
 ```
 
+**Render `speedTier` and `estimatedDays`, not `name`, for live carrier rates.**
+`name` carries the carrier's own service identifier — `USPS PriorityMailInternational`,
+`USAExportPBA USAExportStandard` — which answers a question no shopper asked. They are
+choosing between _how fast_ and _how much_. Label the tiers in your own words and locale:
+
+```typescript
+const LABELS = {
+  cheapest: 'Standard delivery',
+  balanced: 'Express delivery',
+  fastest: 'Priority delivery',
+};
+
+// Manual zone rates carry no speedTier — the merchant named those
+// deliberately, so show their name exactly as written.
+const label = rate.speedTier ? LABELS[rate.speedTier] : rate.name;
+```
+
+Live carrier rates arrive already narrowed to at most three: the cheapest, the fastest,
+and one genuinely in between when it earns its place (cheaper than the fastest _and_
+quicker than the cheapest). You will not receive seven near-identical services to filter
+yourself. The tiers are derived from each quote rather than mapped from service names, so
+a carrier you have never heard of tiers correctly with no lookup table to maintain.
+
 #### Shipping Rates: Complete Flow
 
 The shipping flow involves setting an address and then selecting from available rates:
@@ -2530,7 +2716,14 @@ if (rates.length === 0) {
   );
 }
 
-// Step 3: Display available rates to customer
+// Step 3: Display available rates to customer.
+// Your own words for the carrier tiers — see "Checkout Type Definition" above.
+const LABELS = {
+  cheapest: 'Standard delivery',
+  balanced: 'Express delivery',
+  fastest: 'Priority delivery',
+};
+
 <div className="space-y-2">
   <h3 className="font-medium">Select Shipping Method</h3>
   {rates.map((rate) => (
@@ -2543,7 +2736,8 @@ if (rates.length === 0) {
         onChange={() => setSelectedRateId(rate.id)}
       />
       <div className="flex-1">
-        <span className="font-medium">{rate.name}</span>
+        {/* speedTier for live carrier rates; the merchant's own name for zone rates */}
+        <span className="font-medium">{rate.speedTier ? LABELS[rate.speedTier] : rate.name}</span>
         {rate.description && <p className="text-sm text-gray-500">{rate.description}</p>}
         {rate.estimatedDays && (
           <p className="text-sm text-gray-500">Estimated delivery: {rate.estimatedDays} business days</p>
@@ -3490,14 +3684,17 @@ window.location.href = authorizationUrl;
 
 **Step 2: Create callback page (`/auth/callback`)**
 
-The backend handles the OAuth code exchange automatically and redirects to your callback page with URL params. You do **not** need to call `handleOAuthCallback()` — just read the token from the URL.
+The backend handles the OAuth code exchange automatically and redirects to your callback page with URL params. You do **not** need to call `handleOAuthCallback()`.
+
+Both outcomes land here — success **and** failure. Read `auth_code` and exchange it for the JWT; never read the token from the URL.
 
 ```typescript
 // app/auth/callback/page.tsx
 'use client';
 import { useEffect, useState } from 'react';
 import { useSearchParams } from 'next/navigation';
-import { setCustomerToken } from '@/lib/brainerce';
+import type { OAuthErrorCode } from 'brainerce';
+import { client, setCustomerToken } from '@/lib/brainerce';
 
 export default function AuthCallback() {
   const searchParams = useSearchParams();
@@ -3505,25 +3702,35 @@ export default function AuthCallback() {
 
   useEffect(() => {
     const oauthSuccess = searchParams.get('oauth_success');
-    const token = searchParams.get('token');
-    const oauthError = searchParams.get('oauth_error');
+    const authCode = searchParams.get('auth_code');
+    const oauthError = searchParams.get('oauth_error') as OAuthErrorCode | null;
 
-    // Check for OAuth errors (user cancelled, provider error, etc.)
+    // Failure path: `oauth_error` is a stable snake_case code — switch on it.
+    // `error_description` is English developer detail, NOT shopper-facing copy.
     if (oauthError) {
-      setError(oauthError);
+      setError(
+        oauthError === 'link_blocked_unverified_password_account'
+          ? 'Please verify your email address first, then link your social account.'
+          : oauthError === 'state_expired'
+            ? 'That sign-in link expired. Please try again.'
+            : 'Sign-in could not be completed. Please try again.'
+      );
       return;
     }
 
-    if (oauthSuccess === 'true' && token) {
-      // Save the customer token
-      setCustomerToken(token);
-
-      // Also available in URL params: customer_id, customer_email, is_new
-
-      // Redirect to return URL or home
-      const returnUrl = localStorage.getItem('returnUrl') || '/';
-      localStorage.removeItem('returnUrl');
-      window.location.href = returnUrl;
+    if (oauthSuccess === 'true' && authCode) {
+      // Swap the single-use code for the JWT. It is valid for 2 minutes and
+      // dies on first use, which is why the token never rides in the URL.
+      client
+        .exchangeOAuthCode(authCode)
+        .then((result) => {
+          setCustomerToken(result.token);
+          // Also on `result`: customer, isNewCustomer, linkedToExisting, redirectUrl
+          const returnUrl = localStorage.getItem('returnUrl') || '/';
+          localStorage.removeItem('returnUrl');
+          window.location.href = returnUrl;
+        })
+        .catch(() => setError('Sign-in could not be completed. Please try again.'));
     } else {
       setError('Missing authentication parameters');
     }
@@ -3848,6 +4055,35 @@ client.trackEvent({ eventType: 'engagement', path: '/products/shoes', engagedMs:
 
 ---
 
+### Analytics (optional, server-side GA4 conversions)
+
+If the store has the **Google & YouTube** app installed with a GA4 property connected, Brainerce can send server-side `purchase` conversions via the GA4 Measurement Protocol — recovering the 15-40% of conversions client-side `gtag.js` typically loses to ad-blockers, ITP/Safari cookie capping, and the post-payment redirect dropping the page before the browser beacon fires.
+
+For the server-sent purchase to join the shopper's on-page GA4 session (instead of creating a duplicate/orphan user), it needs the same `client_id`/`session_id` gtag.js is using in the browser. Call `loadGoogleAnalytics()` once and the SDK handles the rest:
+
+```typescript
+// Call once, as early as possible (app entry / root layout)
+client.loadGoogleAnalytics('G-XXXXXXX'); // your GA4 Measurement ID
+
+// Every cart/checkout call from here on auto-forwards the resolved
+// client_id/session_id — no other code changes needed.
+const cart = await client.createCart();
+await client.addToCart(cart.id, { productId: 'prod_abc', quantity: 1 });
+```
+
+What this does:
+
+- Idempotently injects `gtag.js` and initializes `dataLayer` (skips injection if you're already loading `gtag.js` yourself — safe to call either way).
+- Resolves `client_id`/`session_id` via `gtag('get', measurementId, 'client_id' | 'session_id', cb)` — Google's documented method, not `_ga` cookie-parsing (which breaks across cookie-format changes and Consent Mode v2 states).
+- Auto-attaches the resolved ids to `createCart()`, `addToCart()`, `setCheckoutCustomer()`, and `setShippingAddress()`. An explicit `analyticsClientId`/`analyticsSessionId` you pass to any of those calls always wins over the auto-captured value.
+- Never throws and never delays a cart/checkout call by more than ~1.5s (configurable via `{ timeoutMs }`) — a blocked or slow `gtag.js`, or a shopper who denied analytics consent, just means the server-side conversion won't stitch. It never breaks checkout.
+
+You still need to paste the GA4 **Measurement Protocol API secret** once in the dashboard (**Apps → Google & YouTube → Analytics**) — create it in GA4 Admin → Data Streams → your stream → Measurement Protocol API secrets. Without it (or without `loadGoogleAnalytics()` ever being called), the platform simply skips the server-side event — nothing breaks, GA4 just doesn't get the extra signal.
+
+> This is entirely optional and separate from Brainerce's [Traffic Analytics](#traffic-analytics-built-in-no-ga4-needed) above, which needs no GA4 account at all.
+
+---
+
 ## Admin API Reference
 
 > ⛔ **Server-side only.** The `apiKey` (`brainerce_*`) is a privileged secret — NEVER put it in browser code, client bundles, or any code that ships to the user's machine. It belongs in an environment variable on your server. For building the customer-facing storefront, use `salesChannelId` instead (see [Quick Start](#quick-start)).
@@ -4111,26 +4347,89 @@ await client.createZoneShippingRate('zone_id', {
 });
 ```
 
-### App Store Shipping (Shippo)
+### App Store Shipping (live carrier rates)
 
-Once a merchant installs the Shippo app from the Brainerce App Store and connects their own
-Shippo account, live carrier rates appear automatically at checkout. Billing goes directly
-to the merchant's Shippo account.
+Once a merchant installs a shipping app from the Brainerce App Store — EasyPost, Shippo, or any
+future carrier — and connects their own carrier account, live rates appear automatically at
+checkout. Billing goes directly to the merchant's carrier account.
+
+Every carrier app implements the same Brainerce shipping contract, so this code is identical
+regardless of which provider the merchant chose. Checkout rate ids are prefixed `carrier:` and
+must be passed back whole; label rate ids are opaque and must not be parsed.
 
 ```typescript
-// After an order is placed, purchase a shipping label:
+// After an order is placed: quote, then buy.
+const rates = await admin.getOrderShippingRates(orderId);
+
 const label = await admin.createShippingLabel(orderId, {
-  shippoRateObjectId: 'rate_8f123456789abcdef', // Shippo rate.object_id from checkout rates
+  rateId: rates[0].id, // opaque — pass it through, never parse it
+  labelFormat: 'PDF', // 'PDF' | 'PNG' | 'ZPL' | 'EPL' — ZPL/EPL for thermal printers
 });
 
-console.log(label.labelUrl); // PDF label URL for printing
+console.log(label.labelUrl); // Label file URL for printing
 console.log(label.trackingNumber); // Auto-populated on the order
 console.log(label.carrier); // e.g. 'USPS', 'UPS', 'FedEx'
+console.log(label.labelFormat); // What the carrier actually produced
 ```
 
 The `trackingNumber` is stored on the `Order` automatically — customers see it in their
 order history without any extra integration work.
 
+**Buy the service the shopper paid for.** `order.shippingSelection` records the live carrier
+service that was sold at checkout — `{ carrier, service, methodName, amount }` — or `null` when
+the order sold a flat-rate/zone rate and there is nothing to match. Rate ids do not survive a
+re-quote, so re-find it on `carrier` + `service`, trimmed and lower-cased:
+
+```typescript
+const order = await admin.getOrder(orderId);
+const paidFor = order.shippingSelection;
+const norm = (v?: string | null) => (v ?? '').trim().toLowerCase();
+
+const preferred = paidFor
+  ? rates.find(
+      (r) => norm(r.carrier) === norm(paidFor.carrier) && norm(r.service) === norm(paidFor.service)
+    )
+  : undefined;
+```
+
+Buying a cheaper, slower service than the one the shopper was charged for is a silent
+downgrade of what they bought. When the paid-for service is not in the fresh quote, say so and
+let a human choose — do not substitute one automatically.
+
+**Tracking updates are automatic.** Once the label exists, the carrier's tracking webhooks
+flow back through the shipping app and move the shipment through its lifecycle — in transit,
+out for delivery, delivered. On delivery the order is completed and the customer notification
+fires. You never poll for status — read the history when you want to show it:
+
+```typescript
+const shipments = await admin.getOrderShipments(orderId);
+
+for (const s of shipments) {
+  console.log(s.carrier, s.trackingNumber, s.status);
+  // Newest first, capped at the 200 most recent events per shipment
+  for (const e of s.events) {
+    console.log(e.occurredAt, e.message, e.location?.city, e.location?.country);
+  }
+}
+```
+
+**Quote immediately before you buy.** `getOrderShippingRates()` is what creates the shipment
+at the carrier — the rate id points at it — and carriers do not allow amending one afterwards.
+A rate held from an earlier call may no longer be purchasable.
+
+### Cross-border shipments
+
+Customs declarations are handled for you: the platform builds one from the order's line items
+whenever the destination country differs from the merchant's ship-from country. Pass
+`customsContentsType` if the parcel is a gift, sample, document or return rather than
+merchandise.
+
+One case needs the merchant: a US-origin export where any single commodity line exceeds
+**$2,500** cannot use the ordinary EEI exemption. The exporter must file with AES and supply
+the resulting ITN. Brainerce deliberately does **not** assert the exemption on those shipments —
+it is a declaration to US Customs, not a formality — so the carrier will refuse the label until
+a real citation is provided.
+
 ### Tax Configuration
 
 `rate` is a **whole percentage** (`7.25` = 7.25%, not `0.0725`). A rate may target
@@ -4984,6 +5283,9 @@ import { useState, useEffect } from 'react';
 import { client, isLoggedIn, restoreCustomerToken } from '@/lib/brainerce';
 import type { Checkout, ShippingRate } from 'brainerce';
 
+// Live carrier rates carry a speedTier instead of a shopper-readable name.
+const TIER_LABELS = { cheapest: 'Standard delivery', balanced: 'Express delivery', fastest: 'Priority delivery' };
+
 export default function CheckoutPage() {
   const [loading, setLoading] = useState(true);
   const [submitting, setSubmitting] = useState(false);
@@ -5078,7 +5380,8 @@ export default function CheckoutPage() {
       {shippingRates.length > 0 && (
         <select value={selectedRate || ''} onChange={(e) => setSelectedRate(e.target.value)}>
           {shippingRates.map((rate) => (
-            <option key={rate.id} value={rate.id}>{rate.name} - ${rate.price}</option>
+            // 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>
       )}