brainerce 1.52.0 → 1.53.1

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
 
@@ -167,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.
 
@@ -182,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.
 
@@ -233,7 +233,9 @@ 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.
@@ -717,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
@@ -987,6 +1019,19 @@ 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;
@@ -995,12 +1040,19 @@ 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. The `lat`/`lng` on `address` are for YOUR use (a map
-// pin, say) — the server never accepts coordinates 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.
+// 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',
@@ -2417,7 +2469,14 @@ console.log(rates); // ShippingRate[]
 > 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.
+> 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;
@@ -4512,41 +4571,6 @@ const { region: resolved } = await store.getAutoRegion('DE'); // server-side, on
 > otherwise the checkout is charged in the store base currency. See the Checkout
 > section.
 
-### Price Lists (per-region pricing)
-
-Each region has a **price list** — entries that override a product's or variant's
-catalog price for buyers in that region. Requires `price-lists:read` /
-`price-lists:write`. Prices are in the region's currency.
-
-> ⚠️ **Data-entry only for now.** Region prices are **not yet applied at checkout** —
-> charging a region-currency price through the store-currency cart needs FX
-> conversion (a later phase). These methods let you populate the price book ahead of
-> activation; until then checkout uses the catalog price.
-
-```typescript
-// One entry per product OR variant (variant wins). price > 0; compareAtPrice optional.
-const res = await client.upsertPriceListEntries('region_eu', [
-  { productId: 'prod_tshirt', price: 27, compareAtPrice: 32 },
-  { variantId: 'var_tshirt_l', price: 29 },
-]);
-res.upserted; // 2
-res.warnings; // e.g. ["PL-004: compareAtPrice not greater than price …"] (non-blocking)
-
-// Inspect
-const meta = await client.getPriceList('region_eu'); // { currency, entryCount, … }
-const { data: entries } = await client.listPriceListEntries('region_eu', {
-  productId: 'prod_tshirt',
-});
-
-// Bulk CSV (columns: productSku,variantSku?,price,compareAtPrice?). Unknown SKUs /
-// bad prices are skipped + reported, not fatal.
-const imported = await client.importPrices('region_eu', csvString);
-imported.skipped; // ['row 4: product SKU "NOPE" not found', …]
-const csv = await client.exportPrices('region_eu'); // round-trips with importPrices
-
-await client.deletePriceListEntry('region_eu', 'entry_id'); // line falls back to catalog
-```
-
 ### Metafield Definitions
 
 ```typescript

package/dist/index.d.mts

@@ -3188,8 +3188,12 @@ interface SetShippingAddressDto {
      * which is the correct behaviour once the two no longer agree.
      *
      * Note there is deliberately no `lat`/`lng` field: zone matching decides
-     * which shipping rate is offered and charged, so coordinates are never
-     * accepted from the client.
+     * which shipping rate is offered and charged, so the server resolves the
+     * coordinates itself from this `placeId` and never accepts them from the
+     * client. You can still spread `getAddressDetails().address` in here — the
+     * SDK drops its `lat`/`lng`/`formattedAddress` before sending, because the
+     * endpoint rejects any unknown property with a `400` that would otherwise
+     * block checkout entirely.
      */
     placeId?: string;
     /**
@@ -3288,11 +3292,44 @@ interface AddressDetailsResult {
          */
         region: string;
         postalCode: string;
+        /**
+         * ISO-3166-1 alpha-2, or **an empty string** — Google omits the country
+         * outright for places whose sovereignty it declines to attribute, which in
+         * practice includes ordinary residential addresses (verified live: Ramat
+         * Shlomo, Giv'at Ze'ev, Modi'in Ilit, Ma'ale Adumim all come back with no
+         * country). The API deliberately does not guess one.
+         *
+         * Treat it exactly like `region`: when it's empty, leave your country
+         * field for the shopper to confirm rather than submitting a blank
+         * `SetShippingAddressDto.country`. Everything else on the address
+         * (`line1`, `city`, `lat`/`lng`, `formattedAddress`) is still valid and
+         * should still be filled in.
+         *
+         * Note that `region` is necessarily empty too whenever this is — region
+         * codes are resolved *within* a country, so with no country there is no
+         * region list to match against. Prompt for both.
+         */
         country: string;
+        /**
+         * Resolved coordinates, **for your own use only** — a map pin, a distance
+         * readout. They are not part of any address payload: zone matching decides
+         * which shipping rate is offered and charged, so the server re-resolves
+         * them from `placeId` instead of trusting the client. Sending them is
+         * harmless (the SDK strips `lat`/`lng`/`formattedAddress` from
+         * `setShippingAddress()` / `setBillingAddress()` bodies), but pass
+         * `placeId` — that is what actually reaches zone matching.
+         */
         lat: number;
         lng: number;
         formattedAddress: string;
     };
+    /**
+     * Soft coverage hint, never a rejection. Note it can read `false` purely
+     * because `country` came back empty and the store's zones are country-listed
+     * — a polygon zone can still match this address, since the server matches it
+     * against the coordinates it resolves from `placeId`. Show a "we'll confirm
+     * by phone" banner; do not block the shopper.
+     */
     inZone: boolean;
 }
 interface CompleteCheckoutResponse {
@@ -6303,6 +6340,14 @@ declare class BrainerceClient {
     private _pendingRecoverCartId;
     private _ga4MeasurementId;
     private _ga4StitchPromise;
+    /**
+     * Fields present on `getAddressDetails().address` that the address endpoints
+     * do NOT accept — stripped by `stripResolvedOnlyAddressFields()` so a
+     * `{ ...address }` spread doesn't 400 the whole checkout.
+     */
+    private static readonly RESOLVED_ONLY_ADDRESS_FIELDS;
+    /** One warning per client, not per keystroke-driven address submit. */
+    private _warnedResolvedOnlyAddressFields;
     /** localStorage key for session cart reference (sessionToken + cartId) */
     private readonly SESSION_CART_KEY;
     /**
@@ -6376,10 +6421,19 @@ declare class BrainerceClient {
      * Set the customer authentication token (obtained from login/register).
      * Required for accessing customer-specific data in storefront mode.
      *
+     * This is a plain setter — it authenticates subsequent requests and nothing
+     * else. In particular it does NOT attach the shopper's existing guest cart to
+     * their account. Pair every sign-in with {@link syncCartOnLogin}, or the cart
+     * stays anonymous and every feature keyed on buyer identity degrades quietly:
+     * "first order only" discounts keep applying to returning customers,
+     * per-customer usage caps stop being enforced at cart time, and abandoned-cart
+     * recovery can't identify who to email.
+     *
      * @example
      * ```typescript
      * const auth = await client.loginCustomer('user@example.com', 'password');
      * client.setCustomerToken(auth.token);
+     * await client.syncCartOnLogin(); // claim the guest cart for this account
      *
      * // Now can access customer data
      * const profile = await client.getMyProfile();
@@ -6525,6 +6579,24 @@ declare class BrainerceClient {
      * called, or if it hasn't resolved any ids by the time this is awaited.
      */
     private withAnalyticsStitchIds;
+    /**
+     * Drop the fields `getAddressDetails()` returns that no address endpoint
+     * accepts, so spreading its `address` straight into `setShippingAddress()`
+     * / `setBillingAddress()` works instead of failing the whole request.
+     *
+     * The address endpoints validate against a strict allow-list: ONE unknown
+     * property rejects the call with `400 "property lat should not exist"`, and
+     * the shopper cannot check out at all. `lat`/`lng`/`formattedAddress` are
+     * the only realistic way to hit that — they come out of this SDK's own
+     * resolved-address shape, so this SDK cleans up after itself rather than
+     * making every storefront remember to. Nothing else is stripped: a genuine
+     * typo still reaches the server and still fails loudly.
+     *
+     * Coordinates are dropped rather than forwarded because zone matching picks
+     * which shipping rate is offered and charged — the server resolves them
+     * itself from `placeId`, and never takes them from the caller.
+     */
+    private stripResolvedOnlyAddressFields;
     /**
      * Get a list of products with pagination and filtering
      * Works in vibe-coded, storefront (public), and admin mode
@@ -7643,6 +7715,12 @@ declare class BrainerceClient {
      * if (params.get('oauth_success') === 'true' && params.get('auth_code')) {
      *   const result = await client.exchangeOAuthCode(params.get('auth_code')!);
      *   client.setCustomerToken(result.token);
+     *   // REQUIRED: setCustomerToken only stores the JWT — it does NOT attach the
+     *   // guest cart to the account. Without this call the cart stays anonymous,
+     *   // and anything keyed on the buyer's identity misbehaves: "first order
+     *   // only" discounts re-apply to returning customers, per-customer usage
+     *   // caps go unenforced, and abandoned-cart recovery can't reach them.
+     *   await client.syncCartOnLogin();
      *   // result.customer, result.isNewCustomer, result.redirectUrl, ...
      * } else if (params.get('oauth_error')) {
      *   // Failures land on this same page, on `redirectUrl` — never on the API
@@ -7677,6 +7755,11 @@ declare class BrainerceClient {
      *
      * @param authCode - The single-use code from the `?auth_code=` URL param.
      *
+     * Always follow a successful exchange with `syncCartOnLogin()`. Storing the
+     * token does not claim the guest cart, and an unclaimed cart has no buyer
+     * identity — which silently breaks first-order discounts, per-customer usage
+     * caps, and abandoned-cart recovery for everyone who signs in with OAuth.
+     *
      * @example
      * ```typescript
      * const params = new URLSearchParams(window.location.search);
@@ -7685,6 +7768,7 @@ declare class BrainerceClient {
      *   const { token, customer, isNewCustomer, redirectUrl } =
      *     await client.exchangeOAuthCode(code);
      *   client.setCustomerToken(token);
+     *   await client.syncCartOnLogin(); // attach the guest cart to the account
      * }
      * ```
      */
@@ -8840,6 +8924,11 @@ declare class BrainerceClient {
      * address text — which is materially less accurate and can place the
      * shopper in a neighbouring city's zone, or in none at all.
      *
+     * Spreading `getAddressDetails().address` in here is safe: its `lat`, `lng`
+     * and `formattedAddress` are dropped before the request goes out (the
+     * endpoint rejects unknown properties outright, and coordinates are never
+     * taken from the client — the server resolves them from `placeId`).
+     *
      * @example
      * ```typescript
      * const { checkout, rates } = await client.setShippingAddress('checkout_123', {
@@ -11037,7 +11126,7 @@ declare class BrainerceError extends Error {
     constructor(message: string, statusCode: number, details?: unknown);
 }
 
-declare const SDK_VERSION = "1.52.0";
+declare const SDK_VERSION = "1.53.1";
 
 /**
  * Verify a webhook signature from Brainerce

package/dist/index.d.ts

@@ -3188,8 +3188,12 @@ interface SetShippingAddressDto {
      * which is the correct behaviour once the two no longer agree.
      *
      * Note there is deliberately no `lat`/`lng` field: zone matching decides
-     * which shipping rate is offered and charged, so coordinates are never
-     * accepted from the client.
+     * which shipping rate is offered and charged, so the server resolves the
+     * coordinates itself from this `placeId` and never accepts them from the
+     * client. You can still spread `getAddressDetails().address` in here — the
+     * SDK drops its `lat`/`lng`/`formattedAddress` before sending, because the
+     * endpoint rejects any unknown property with a `400` that would otherwise
+     * block checkout entirely.
      */
     placeId?: string;
     /**
@@ -3288,11 +3292,44 @@ interface AddressDetailsResult {
          */
         region: string;
         postalCode: string;
+        /**
+         * ISO-3166-1 alpha-2, or **an empty string** — Google omits the country
+         * outright for places whose sovereignty it declines to attribute, which in
+         * practice includes ordinary residential addresses (verified live: Ramat
+         * Shlomo, Giv'at Ze'ev, Modi'in Ilit, Ma'ale Adumim all come back with no
+         * country). The API deliberately does not guess one.
+         *
+         * Treat it exactly like `region`: when it's empty, leave your country
+         * field for the shopper to confirm rather than submitting a blank
+         * `SetShippingAddressDto.country`. Everything else on the address
+         * (`line1`, `city`, `lat`/`lng`, `formattedAddress`) is still valid and
+         * should still be filled in.
+         *
+         * Note that `region` is necessarily empty too whenever this is — region
+         * codes are resolved *within* a country, so with no country there is no
+         * region list to match against. Prompt for both.
+         */
         country: string;
+        /**
+         * Resolved coordinates, **for your own use only** — a map pin, a distance
+         * readout. They are not part of any address payload: zone matching decides
+         * which shipping rate is offered and charged, so the server re-resolves
+         * them from `placeId` instead of trusting the client. Sending them is
+         * harmless (the SDK strips `lat`/`lng`/`formattedAddress` from
+         * `setShippingAddress()` / `setBillingAddress()` bodies), but pass
+         * `placeId` — that is what actually reaches zone matching.
+         */
         lat: number;
         lng: number;
         formattedAddress: string;
     };
+    /**
+     * Soft coverage hint, never a rejection. Note it can read `false` purely
+     * because `country` came back empty and the store's zones are country-listed
+     * — a polygon zone can still match this address, since the server matches it
+     * against the coordinates it resolves from `placeId`. Show a "we'll confirm
+     * by phone" banner; do not block the shopper.
+     */
     inZone: boolean;
 }
 interface CompleteCheckoutResponse {
@@ -6303,6 +6340,14 @@ declare class BrainerceClient {
     private _pendingRecoverCartId;
     private _ga4MeasurementId;
     private _ga4StitchPromise;
+    /**
+     * Fields present on `getAddressDetails().address` that the address endpoints
+     * do NOT accept — stripped by `stripResolvedOnlyAddressFields()` so a
+     * `{ ...address }` spread doesn't 400 the whole checkout.
+     */
+    private static readonly RESOLVED_ONLY_ADDRESS_FIELDS;
+    /** One warning per client, not per keystroke-driven address submit. */
+    private _warnedResolvedOnlyAddressFields;
     /** localStorage key for session cart reference (sessionToken + cartId) */
     private readonly SESSION_CART_KEY;
     /**
@@ -6376,10 +6421,19 @@ declare class BrainerceClient {
      * Set the customer authentication token (obtained from login/register).
      * Required for accessing customer-specific data in storefront mode.
      *
+     * This is a plain setter — it authenticates subsequent requests and nothing
+     * else. In particular it does NOT attach the shopper's existing guest cart to
+     * their account. Pair every sign-in with {@link syncCartOnLogin}, or the cart
+     * stays anonymous and every feature keyed on buyer identity degrades quietly:
+     * "first order only" discounts keep applying to returning customers,
+     * per-customer usage caps stop being enforced at cart time, and abandoned-cart
+     * recovery can't identify who to email.
+     *
      * @example
      * ```typescript
      * const auth = await client.loginCustomer('user@example.com', 'password');
      * client.setCustomerToken(auth.token);
+     * await client.syncCartOnLogin(); // claim the guest cart for this account
      *
      * // Now can access customer data
      * const profile = await client.getMyProfile();
@@ -6525,6 +6579,24 @@ declare class BrainerceClient {
      * called, or if it hasn't resolved any ids by the time this is awaited.
      */
     private withAnalyticsStitchIds;
+    /**
+     * Drop the fields `getAddressDetails()` returns that no address endpoint
+     * accepts, so spreading its `address` straight into `setShippingAddress()`
+     * / `setBillingAddress()` works instead of failing the whole request.
+     *
+     * The address endpoints validate against a strict allow-list: ONE unknown
+     * property rejects the call with `400 "property lat should not exist"`, and
+     * the shopper cannot check out at all. `lat`/`lng`/`formattedAddress` are
+     * the only realistic way to hit that — they come out of this SDK's own
+     * resolved-address shape, so this SDK cleans up after itself rather than
+     * making every storefront remember to. Nothing else is stripped: a genuine
+     * typo still reaches the server and still fails loudly.
+     *
+     * Coordinates are dropped rather than forwarded because zone matching picks
+     * which shipping rate is offered and charged — the server resolves them
+     * itself from `placeId`, and never takes them from the caller.
+     */
+    private stripResolvedOnlyAddressFields;
     /**
      * Get a list of products with pagination and filtering
      * Works in vibe-coded, storefront (public), and admin mode
@@ -7643,6 +7715,12 @@ declare class BrainerceClient {
      * if (params.get('oauth_success') === 'true' && params.get('auth_code')) {
      *   const result = await client.exchangeOAuthCode(params.get('auth_code')!);
      *   client.setCustomerToken(result.token);
+     *   // REQUIRED: setCustomerToken only stores the JWT — it does NOT attach the
+     *   // guest cart to the account. Without this call the cart stays anonymous,
+     *   // and anything keyed on the buyer's identity misbehaves: "first order
+     *   // only" discounts re-apply to returning customers, per-customer usage
+     *   // caps go unenforced, and abandoned-cart recovery can't reach them.
+     *   await client.syncCartOnLogin();
      *   // result.customer, result.isNewCustomer, result.redirectUrl, ...
      * } else if (params.get('oauth_error')) {
      *   // Failures land on this same page, on `redirectUrl` — never on the API
@@ -7677,6 +7755,11 @@ declare class BrainerceClient {
      *
      * @param authCode - The single-use code from the `?auth_code=` URL param.
      *
+     * Always follow a successful exchange with `syncCartOnLogin()`. Storing the
+     * token does not claim the guest cart, and an unclaimed cart has no buyer
+     * identity — which silently breaks first-order discounts, per-customer usage
+     * caps, and abandoned-cart recovery for everyone who signs in with OAuth.
+     *
      * @example
      * ```typescript
      * const params = new URLSearchParams(window.location.search);
@@ -7685,6 +7768,7 @@ declare class BrainerceClient {
      *   const { token, customer, isNewCustomer, redirectUrl } =
      *     await client.exchangeOAuthCode(code);
      *   client.setCustomerToken(token);
+     *   await client.syncCartOnLogin(); // attach the guest cart to the account
      * }
      * ```
      */
@@ -8840,6 +8924,11 @@ declare class BrainerceClient {
      * address text — which is materially less accurate and can place the
      * shopper in a neighbouring city's zone, or in none at all.
      *
+     * Spreading `getAddressDetails().address` in here is safe: its `lat`, `lng`
+     * and `formattedAddress` are dropped before the request goes out (the
+     * endpoint rejects unknown properties outright, and coordinates are never
+     * taken from the client — the server resolves them from `placeId`).
+     *
      * @example
      * ```typescript
      * const { checkout, rates } = await client.setShippingAddress('checkout_123', {
@@ -11037,7 +11126,7 @@ declare class BrainerceError extends Error {
     constructor(message: string, statusCode: number, details?: unknown);
 }
 
-declare const SDK_VERSION = "1.52.0";
+declare const SDK_VERSION = "1.53.1";
 
 /**
  * Verify a webhook signature from Brainerce

package/dist/index.js

@@ -201,7 +201,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.52.0";
+var SDK_VERSION = "1.53.1";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -241,7 +241,7 @@ function parseRetryAfterMs(response) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-var BrainerceClient = class {
+var _BrainerceClient = class _BrainerceClient {
   constructor(options) {
     this.customerToken = null;
     this.customerCartId = null;
@@ -260,6 +260,8 @@ var BrainerceClient = class {
     // GA4 stitch state (see `loadGoogleAnalytics()` in the Analytics section).
     this._ga4MeasurementId = null;
     this._ga4StitchPromise = null;
+    /** One warning per client, not per keystroke-driven address submit. */
+    this._warnedResolvedOnlyAddressFields = false;
     /** localStorage key for session cart reference (sessionToken + cartId) */
     this.SESSION_CART_KEY = "brainerce_session";
     /**
@@ -773,10 +775,19 @@ var BrainerceClient = class {
    * Set the customer authentication token (obtained from login/register).
    * Required for accessing customer-specific data in storefront mode.
    *
+   * This is a plain setter — it authenticates subsequent requests and nothing
+   * else. In particular it does NOT attach the shopper's existing guest cart to
+   * their account. Pair every sign-in with {@link syncCartOnLogin}, or the cart
+   * stays anonymous and every feature keyed on buyer identity degrades quietly:
+   * "first order only" discounts keep applying to returning customers,
+   * per-customer usage caps stop being enforced at cart time, and abandoned-cart
+   * recovery can't identify who to email.
+   *
    * @example
    * ```typescript
    * const auth = await client.loginCustomer('user@example.com', 'password');
    * client.setCustomerToken(auth.token);
+   * await client.syncCartOnLogin(); // claim the guest cart for this account
    *
    * // Now can access customer data
    * const profile = await client.getMyProfile();
@@ -1290,6 +1301,39 @@ var BrainerceClient = class {
       return dto;
     }
   }
+  /**
+   * Drop the fields `getAddressDetails()` returns that no address endpoint
+   * accepts, so spreading its `address` straight into `setShippingAddress()`
+   * / `setBillingAddress()` works instead of failing the whole request.
+   *
+   * The address endpoints validate against a strict allow-list: ONE unknown
+   * property rejects the call with `400 "property lat should not exist"`, and
+   * the shopper cannot check out at all. `lat`/`lng`/`formattedAddress` are
+   * the only realistic way to hit that — they come out of this SDK's own
+   * resolved-address shape, so this SDK cleans up after itself rather than
+   * making every storefront remember to. Nothing else is stripped: a genuine
+   * typo still reaches the server and still fails loudly.
+   *
+   * Coordinates are dropped rather than forwarded because zone matching picks
+   * which shipping rate is offered and charged — the server resolves them
+   * itself from `placeId`, and never takes them from the caller.
+   */
+  stripResolvedOnlyAddressFields(address) {
+    if (!address || typeof address !== "object") return address;
+    const present = _BrainerceClient.RESOLVED_ONLY_ADDRESS_FIELDS.filter(
+      (field) => field in address
+    );
+    if (present.length === 0) return address;
+    const cleaned = { ...address };
+    for (const field of present) delete cleaned[field];
+    if (!this._warnedResolvedOnlyAddressFields) {
+      this._warnedResolvedOnlyAddressFields = true;
+      console.warn(
+        `BrainerceClient: dropped ${present.join("/")} from the address payload \u2014 the API does not accept coordinates from the client. Pass \`placeId\` (and \`placeSessionToken\`) instead so the server resolves them itself and matches map-drawn delivery zones against the exact location.`
+      );
+    }
+    return cleaned;
+  }
   // -------------------- Products --------------------
   /**
    * Get a list of products with pagination and filtering
@@ -2882,6 +2926,12 @@ var BrainerceClient = class {
    * if (params.get('oauth_success') === 'true' && params.get('auth_code')) {
    *   const result = await client.exchangeOAuthCode(params.get('auth_code')!);
    *   client.setCustomerToken(result.token);
+   *   // REQUIRED: setCustomerToken only stores the JWT — it does NOT attach the
+   *   // guest cart to the account. Without this call the cart stays anonymous,
+   *   // and anything keyed on the buyer's identity misbehaves: "first order
+   *   // only" discounts re-apply to returning customers, per-customer usage
+   *   // caps go unenforced, and abandoned-cart recovery can't reach them.
+   *   await client.syncCartOnLogin();
    *   // result.customer, result.isNewCustomer, result.redirectUrl, ...
    * } else if (params.get('oauth_error')) {
    *   // Failures land on this same page, on `redirectUrl` — never on the API
@@ -2934,6 +2984,11 @@ var BrainerceClient = class {
    *
    * @param authCode - The single-use code from the `?auth_code=` URL param.
    *
+   * Always follow a successful exchange with `syncCartOnLogin()`. Storing the
+   * token does not claim the guest cart, and an unclaimed cart has no buyer
+   * identity — which silently breaks first-order discounts, per-customer usage
+   * caps, and abandoned-cart recovery for everyone who signs in with OAuth.
+   *
    * @example
    * ```typescript
    * const params = new URLSearchParams(window.location.search);
@@ -2942,6 +2997,7 @@ var BrainerceClient = class {
    *   const { token, customer, isNewCustomer, redirectUrl } =
    *     await client.exchangeOAuthCode(code);
    *   client.setCustomerToken(token);
+   *   await client.syncCartOnLogin(); // attach the guest cart to the account
    * }
    * ```
    */
@@ -5121,6 +5177,11 @@ var BrainerceClient = class {
    * address text — which is materially less accurate and can place the
    * shopper in a neighbouring city's zone, or in none at all.
    *
+   * Spreading `getAddressDetails().address` in here is safe: its `lat`, `lng`
+   * and `formattedAddress` are dropped before the request goes out (the
+   * endpoint rejects unknown properties outright, and coordinates are never
+   * taken from the client — the server resolves them from `placeId`).
+   *
    * @example
    * ```typescript
    * const { checkout, rates } = await client.setShippingAddress('checkout_123', {
@@ -5140,7 +5201,9 @@ var BrainerceClient = class {
    * ```
    */
   async setShippingAddress(checkoutId, address) {
-    const body = await this.withAnalyticsStitchIds(address);
+    const body = await this.withAnalyticsStitchIds(
+      this.stripResolvedOnlyAddressFields(address)
+    );
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -5453,24 +5516,25 @@ var BrainerceClient = class {
    * ```
    */
   async setBillingAddress(checkoutId, address) {
+    const body = this.stripResolvedOnlyAddressFields(address);
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
         `/checkout/${encodePathSegment(checkoutId)}/billing-address`,
-        address
+        body
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "PATCH",
         `/checkout/${encodePathSegment(checkoutId)}/billing-address`,
-        address
+        body
       );
     }
     return this.adminRequest(
       "PATCH",
       `/api/v1/checkout/${encodePathSegment(checkoutId)}/billing-address`,
-      address
+      body
     );
   }
   /**
@@ -6436,7 +6500,7 @@ var BrainerceClient = class {
       const result = await this.vibeCodedRequest(
         "PATCH",
         `/checkout/${encodePathSegment(checkoutId)}/shipping-address`,
-        data.shippingAddress
+        this.stripResolvedOnlyAddressFields(data.shippingAddress)
       );
       checkout = result.checkout;
     }
@@ -6444,7 +6508,7 @@ var BrainerceClient = class {
       checkout = await this.vibeCodedRequest(
         "PATCH",
         `/checkout/${encodePathSegment(checkoutId)}/billing-address`,
-        data.billingAddress
+        this.stripResolvedOnlyAddressFields(data.billingAddress)
       );
     }
     if (!checkout) {
@@ -9285,6 +9349,17 @@ var BrainerceClient = class {
     );
   }
 };
+/**
+ * Fields present on `getAddressDetails().address` that the address endpoints
+ * do NOT accept — stripped by `stripResolvedOnlyAddressFields()` so a
+ * `{ ...address }` spread doesn't 400 the whole checkout.
+ */
+_BrainerceClient.RESOLVED_ONLY_ADDRESS_FIELDS = [
+  "lat",
+  "lng",
+  "formattedAddress"
+];
+var BrainerceClient = _BrainerceClient;
 var BrainerceError = class extends Error {
   constructor(message, statusCode, details) {
     super(message);

package/dist/index.mjs

@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.52.0";
+var SDK_VERSION = "1.53.1";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -155,7 +155,7 @@ function parseRetryAfterMs(response) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-var BrainerceClient = class {
+var _BrainerceClient = class _BrainerceClient {
   constructor(options) {
     this.customerToken = null;
     this.customerCartId = null;
@@ -174,6 +174,8 @@ var BrainerceClient = class {
     // GA4 stitch state (see `loadGoogleAnalytics()` in the Analytics section).
     this._ga4MeasurementId = null;
     this._ga4StitchPromise = null;
+    /** One warning per client, not per keystroke-driven address submit. */
+    this._warnedResolvedOnlyAddressFields = false;
     /** localStorage key for session cart reference (sessionToken + cartId) */
     this.SESSION_CART_KEY = "brainerce_session";
     /**
@@ -687,10 +689,19 @@ var BrainerceClient = class {
    * Set the customer authentication token (obtained from login/register).
    * Required for accessing customer-specific data in storefront mode.
    *
+   * This is a plain setter — it authenticates subsequent requests and nothing
+   * else. In particular it does NOT attach the shopper's existing guest cart to
+   * their account. Pair every sign-in with {@link syncCartOnLogin}, or the cart
+   * stays anonymous and every feature keyed on buyer identity degrades quietly:
+   * "first order only" discounts keep applying to returning customers,
+   * per-customer usage caps stop being enforced at cart time, and abandoned-cart
+   * recovery can't identify who to email.
+   *
    * @example
    * ```typescript
    * const auth = await client.loginCustomer('user@example.com', 'password');
    * client.setCustomerToken(auth.token);
+   * await client.syncCartOnLogin(); // claim the guest cart for this account
    *
    * // Now can access customer data
    * const profile = await client.getMyProfile();
@@ -1204,6 +1215,39 @@ var BrainerceClient = class {
       return dto;
     }
   }
+  /**
+   * Drop the fields `getAddressDetails()` returns that no address endpoint
+   * accepts, so spreading its `address` straight into `setShippingAddress()`
+   * / `setBillingAddress()` works instead of failing the whole request.
+   *
+   * The address endpoints validate against a strict allow-list: ONE unknown
+   * property rejects the call with `400 "property lat should not exist"`, and
+   * the shopper cannot check out at all. `lat`/`lng`/`formattedAddress` are
+   * the only realistic way to hit that — they come out of this SDK's own
+   * resolved-address shape, so this SDK cleans up after itself rather than
+   * making every storefront remember to. Nothing else is stripped: a genuine
+   * typo still reaches the server and still fails loudly.
+   *
+   * Coordinates are dropped rather than forwarded because zone matching picks
+   * which shipping rate is offered and charged — the server resolves them
+   * itself from `placeId`, and never takes them from the caller.
+   */
+  stripResolvedOnlyAddressFields(address) {
+    if (!address || typeof address !== "object") return address;
+    const present = _BrainerceClient.RESOLVED_ONLY_ADDRESS_FIELDS.filter(
+      (field) => field in address
+    );
+    if (present.length === 0) return address;
+    const cleaned = { ...address };
+    for (const field of present) delete cleaned[field];
+    if (!this._warnedResolvedOnlyAddressFields) {
+      this._warnedResolvedOnlyAddressFields = true;
+      console.warn(
+        `BrainerceClient: dropped ${present.join("/")} from the address payload \u2014 the API does not accept coordinates from the client. Pass \`placeId\` (and \`placeSessionToken\`) instead so the server resolves them itself and matches map-drawn delivery zones against the exact location.`
+      );
+    }
+    return cleaned;
+  }
   // -------------------- Products --------------------
   /**
    * Get a list of products with pagination and filtering
@@ -2796,6 +2840,12 @@ var BrainerceClient = class {
    * if (params.get('oauth_success') === 'true' && params.get('auth_code')) {
    *   const result = await client.exchangeOAuthCode(params.get('auth_code')!);
    *   client.setCustomerToken(result.token);
+   *   // REQUIRED: setCustomerToken only stores the JWT — it does NOT attach the
+   *   // guest cart to the account. Without this call the cart stays anonymous,
+   *   // and anything keyed on the buyer's identity misbehaves: "first order
+   *   // only" discounts re-apply to returning customers, per-customer usage
+   *   // caps go unenforced, and abandoned-cart recovery can't reach them.
+   *   await client.syncCartOnLogin();
    *   // result.customer, result.isNewCustomer, result.redirectUrl, ...
    * } else if (params.get('oauth_error')) {
    *   // Failures land on this same page, on `redirectUrl` — never on the API
@@ -2848,6 +2898,11 @@ var BrainerceClient = class {
    *
    * @param authCode - The single-use code from the `?auth_code=` URL param.
    *
+   * Always follow a successful exchange with `syncCartOnLogin()`. Storing the
+   * token does not claim the guest cart, and an unclaimed cart has no buyer
+   * identity — which silently breaks first-order discounts, per-customer usage
+   * caps, and abandoned-cart recovery for everyone who signs in with OAuth.
+   *
    * @example
    * ```typescript
    * const params = new URLSearchParams(window.location.search);
@@ -2856,6 +2911,7 @@ var BrainerceClient = class {
    *   const { token, customer, isNewCustomer, redirectUrl } =
    *     await client.exchangeOAuthCode(code);
    *   client.setCustomerToken(token);
+   *   await client.syncCartOnLogin(); // attach the guest cart to the account
    * }
    * ```
    */
@@ -5035,6 +5091,11 @@ var BrainerceClient = class {
    * address text — which is materially less accurate and can place the
    * shopper in a neighbouring city's zone, or in none at all.
    *
+   * Spreading `getAddressDetails().address` in here is safe: its `lat`, `lng`
+   * and `formattedAddress` are dropped before the request goes out (the
+   * endpoint rejects unknown properties outright, and coordinates are never
+   * taken from the client — the server resolves them from `placeId`).
+   *
    * @example
    * ```typescript
    * const { checkout, rates } = await client.setShippingAddress('checkout_123', {
@@ -5054,7 +5115,9 @@ var BrainerceClient = class {
    * ```
    */
   async setShippingAddress(checkoutId, address) {
-    const body = await this.withAnalyticsStitchIds(address);
+    const body = await this.withAnalyticsStitchIds(
+      this.stripResolvedOnlyAddressFields(address)
+    );
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -5367,24 +5430,25 @@ var BrainerceClient = class {
    * ```
    */
   async setBillingAddress(checkoutId, address) {
+    const body = this.stripResolvedOnlyAddressFields(address);
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
         `/checkout/${encodePathSegment(checkoutId)}/billing-address`,
-        address
+        body
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "PATCH",
         `/checkout/${encodePathSegment(checkoutId)}/billing-address`,
-        address
+        body
       );
     }
     return this.adminRequest(
       "PATCH",
       `/api/v1/checkout/${encodePathSegment(checkoutId)}/billing-address`,
-      address
+      body
     );
   }
   /**
@@ -6350,7 +6414,7 @@ var BrainerceClient = class {
       const result = await this.vibeCodedRequest(
         "PATCH",
         `/checkout/${encodePathSegment(checkoutId)}/shipping-address`,
-        data.shippingAddress
+        this.stripResolvedOnlyAddressFields(data.shippingAddress)
       );
       checkout = result.checkout;
     }
@@ -6358,7 +6422,7 @@ var BrainerceClient = class {
       checkout = await this.vibeCodedRequest(
         "PATCH",
         `/checkout/${encodePathSegment(checkoutId)}/billing-address`,
-        data.billingAddress
+        this.stripResolvedOnlyAddressFields(data.billingAddress)
       );
     }
     if (!checkout) {
@@ -9199,6 +9263,17 @@ var BrainerceClient = class {
     );
   }
 };
+/**
+ * Fields present on `getAddressDetails().address` that the address endpoints
+ * do NOT accept — stripped by `stripResolvedOnlyAddressFields()` so a
+ * `{ ...address }` spread doesn't 400 the whole checkout.
+ */
+_BrainerceClient.RESOLVED_ONLY_ADDRESS_FIELDS = [
+  "lat",
+  "lng",
+  "formattedAddress"
+];
+var BrainerceClient = _BrainerceClient;
 var BrainerceError = class extends Error {
   constructor(message, statusCode, details) {
     super(message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.52.0",
+  "version": "1.53.1",
   "description": "Official SDK for building e-commerce storefronts with Brainerce Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",