brainerce 1.46.0 → 1.46.2

package/README.md

@@ -892,10 +892,19 @@ const suggestions = await client.getAddressSuggestions('Rothschild 1', sessionTo
 const { address, inZone } = await client.getAddressDetails(suggestions[0].placeId, sessionToken);
 // address: { line1, city, region, postalCode, country, lat, lng, formattedAddress }
 
+// 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;
+// never assign a code the region <select> wouldn't recognize.
+const destinations = await client.getShippingDestinations();
+const validRegions = destinations.regions[address.country] ?? [];
+const region = validRegions.some((r) => r.code === address.region) ? address.region : '';
+
 await client.setShippingAddress(checkout.id, {
   firstName: 'John',
   lastName: 'Doe',
   ...address,
+  region,
 });
 
 if (!inZone) {

package/dist/index.d.mts

@@ -2970,11 +2970,31 @@ interface AddressSuggestion {
  * zones. `inZone: false` doesn't mean the order can't ship there — it's a
  * soft signal for a UI banner like "outside our regular delivery zones,
  * we'll confirm by phone" (see `getAddressDetails()`), never a hard block.
+ *
+ * This check intentionally ignores region-restricted zones (only
+ * country/postal/drawn-shape coverage is considered) — Google's resolved
+ * region text doesn't reliably match a store's own region codes (see
+ * `address.region`'s doc comment below), so factoring it in here could
+ * silently produce a false "outside zone". The authoritative, region-aware
+ * check happens once the shopper picks their actual region from the
+ * dropdown and rates are calculated — this field is a preview, not a
+ * substitute for that.
  */
 interface AddressDetailsResult {
     address: {
         line1: string;
         city: string;
+        /**
+         * Google's own administrative-area code for the resolved place (e.g.
+         * `"D"` for an Israeli address in the Southern District). Usually — but
+         * not guaranteed — the same ISO 3166-2 subdivision code this platform's
+         * own region lists use (`getShippingDestinations()`'s `regions`), since
+         * both ultimately derive from the same standard. Before assigning this
+         * into a `SetShippingAddressDto.region` field, validate it against the
+         * store's own `destinations.regions[country]` list (matching by `code`)
+         * — if it's not one of the known codes, leave the field for the shopper
+         * to pick manually rather than assigning an unrecognized value.
+         */
         region: string;
         postalCode: string;
         country: string;

package/dist/index.d.ts

@@ -2970,11 +2970,31 @@ interface AddressSuggestion {
  * zones. `inZone: false` doesn't mean the order can't ship there — it's a
  * soft signal for a UI banner like "outside our regular delivery zones,
  * we'll confirm by phone" (see `getAddressDetails()`), never a hard block.
+ *
+ * This check intentionally ignores region-restricted zones (only
+ * country/postal/drawn-shape coverage is considered) — Google's resolved
+ * region text doesn't reliably match a store's own region codes (see
+ * `address.region`'s doc comment below), so factoring it in here could
+ * silently produce a false "outside zone". The authoritative, region-aware
+ * check happens once the shopper picks their actual region from the
+ * dropdown and rates are calculated — this field is a preview, not a
+ * substitute for that.
  */
 interface AddressDetailsResult {
     address: {
         line1: string;
         city: string;
+        /**
+         * Google's own administrative-area code for the resolved place (e.g.
+         * `"D"` for an Israeli address in the Southern District). Usually — but
+         * not guaranteed — the same ISO 3166-2 subdivision code this platform's
+         * own region lists use (`getShippingDestinations()`'s `regions`), since
+         * both ultimately derive from the same standard. Before assigning this
+         * into a `SetShippingAddressDto.region` field, validate it against the
+         * store's own `destinations.regions[country]` list (matching by `code`)
+         * — if it's not one of the known codes, leave the field for the shopper
+         * to pick manually rather than assigning an unrecognized value.
+         */
         region: string;
         postalCode: string;
         country: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.46.0",
+  "version": "1.46.2",
   "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",