brainerce 1.52.0 → 1.53.0

package/dist/index.mjs

@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.52.0";
+var SDK_VERSION = "1.53.0";
 
 // 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.0",
   "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",