brainerce 1.51.0 → 1.53.0

package/dist/index.mjs

@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.51.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;
@@ -171,6 +171,11 @@ var BrainerceClient = class {
      * so the recovered cart shows up with zero per-store code.
      */
     this._pendingRecoverCartId = null;
+    // 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";
     /**
@@ -684,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();
@@ -1081,6 +1095,159 @@ var BrainerceClient = class {
     } catch {
     }
   }
+  /**
+   * Load GA4's `gtag.js` and start resolving the `client_id`/`session_id`
+   * "stitch" ids Google needs to join a later server-side purchase conversion
+   * to this browser's GA4 session (without them, a server-sent purchase event
+   * either gets rejected or creates a phantom user in GA4). Call this once,
+   * as early as possible (app entry / root layout).
+   *
+   * `createCart()`, `addToCart()`, `setCheckoutCustomer()`, and
+   * `setShippingAddress()` all auto-attach the resolved ids once available —
+   * an explicit `analyticsClientId`/`analyticsSessionId` you pass to any of
+   * those always wins over the auto-captured value. You only need to call
+   * this once; every subsequent cart/checkout call benefits automatically.
+   *
+   * Ids are resolved via `gtag('get', measurementId, 'client_id' | 'session_id', cb)`
+   * — Google's documented method — never by parsing the `_ga` cookie, which
+   * is undocumented and breaks silently across cookie-format changes and
+   * Consent Mode v2 states. If the shopper has denied analytics consent,
+   * gtag reports no client_id and the ids are simply omitted — never
+   * synthesized.
+   *
+   * No-op outside the browser (SSR-safe) and never throws — a blocked or
+   * slow gtag just means server-side conversions won't stitch; it never
+   * breaks the storefront or delays checkout by more than `options.timeoutMs`.
+   *
+   * @example
+   * ```typescript
+   * // Call once, e.g. in your root layout / app entry point
+   * client.loadGoogleAnalytics('G-XXXXXXX');
+   *
+   * // Every cart/checkout call from here on auto-forwards the stitch ids —
+   * // no other code changes needed.
+   * const cart = await client.createCart();
+   * await client.addToCart(cart.id, { productId: 'prod_abc', quantity: 1 });
+   * ```
+   */
+  loadGoogleAnalytics(measurementId, options) {
+    if (typeof window === "undefined" || !measurementId) return;
+    if (this._ga4MeasurementId === measurementId && this._ga4StitchPromise) return;
+    this._ga4MeasurementId = measurementId;
+    try {
+      if (!window.gtag) {
+        window.dataLayer = window.dataLayer || [];
+        const gtag = (...args) => {
+          window.dataLayer.push(args);
+        };
+        window.gtag = gtag;
+        gtag("js", /* @__PURE__ */ new Date());
+        const script = document.createElement("script");
+        script.async = true;
+        script.src = `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(measurementId)}`;
+        document.head.appendChild(script);
+      }
+      window.gtag("config", measurementId);
+    } catch {
+    }
+    this._ga4StitchPromise = this.resolveGa4StitchIds(measurementId, options?.timeoutMs ?? 1500);
+  }
+  /**
+   * Resolve GA4's `client_id`/`session_id` via `gtag('get', ...)`, bounded by
+   * `timeoutMs` so a slow/blocked gtag never hangs a cart/checkout call.
+   * Resolves to `{}` (never rejects) on timeout, missing gtag, or denied
+   * consent.
+   */
+  resolveGa4StitchIds(measurementId, timeoutMs) {
+    return new Promise((resolve) => {
+      if (typeof window === "undefined" || !window.gtag) {
+        resolve({});
+        return;
+      }
+      const result = {};
+      let settled = false;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        resolve(result);
+      };
+      const timer = setTimeout(finish, timeoutMs);
+      let pending = 2;
+      const done = () => {
+        pending -= 1;
+        if (pending === 0) {
+          clearTimeout(timer);
+          finish();
+        }
+      };
+      try {
+        window.gtag("get", measurementId, "client_id", (id) => {
+          if (id) result.analyticsClientId = id;
+          done();
+        });
+        window.gtag("get", measurementId, "session_id", (id) => {
+          if (id) result.analyticsSessionId = String(id);
+          done();
+        });
+      } catch {
+        clearTimeout(timer);
+        finish();
+      }
+    });
+  }
+  /**
+   * Merge the resolved GA4 stitch ids onto a request body — only for fields
+   * the caller didn't already set explicitly (explicit values always win).
+   * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
+   * called, or if it hasn't resolved any ids by the time this is awaited.
+   */
+  async withAnalyticsStitchIds(dto) {
+    if (!this._ga4StitchPromise) return dto;
+    try {
+      const ids = await this._ga4StitchPromise;
+      if (!ids.analyticsClientId && !ids.analyticsSessionId) return dto;
+      return {
+        ...dto ?? {},
+        analyticsClientId: dto?.analyticsClientId ?? ids.analyticsClientId,
+        analyticsSessionId: dto?.analyticsSessionId ?? ids.analyticsSessionId
+      };
+    } catch {
+      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
@@ -1801,13 +1968,23 @@ var BrainerceClient = class {
   }
   /**
    * Create a shipping label for an order via the installed App Store shipping app.
-   * Pass the rate ID returned from checkout rate shopping. Billing goes directly
-   * to the merchant's carrier account — Brainerce is not a billing intermediary.
+   * Pass the rate ID returned from rate shopping — treat it as opaque and never
+   * parse it. Billing goes directly to the merchant's carrier account; Brainerce
+   * is not a billing intermediary.
+   *
+   * `labelFormat` defaults to `PDF`. Use `ZPL` or `EPL` for warehouse thermal
+   * printers. If the carrier cannot produce the requested format it returns its
+   * closest match rather than failing the purchase — check the response.
+   *
+   * Once the label exists, tracking updates arrive automatically: the carrier's
+   * webhooks move the shipment through in-transit → delivered and complete the
+   * order. No polling required.
    *
    * @example
    * ```typescript
    * const label = await client.createShippingLabel('order_abc', {
    *   rateId: 'rate_8f123456789abcdef',
+   *   labelFormat: 'ZPL',
    * });
    * console.log('Label URL:', label.labelUrl);
    * console.log('Tracking:', label.trackingNumber);
@@ -1820,6 +1997,37 @@ var BrainerceClient = class {
       data
     );
   }
+  /**
+   * Live carrier rates for an order, from the merchant's installed shipping app.
+   *
+   * Call this immediately before {@link createShippingLabel} and pass the chosen
+   * `id` straight through — the id is opaque and must not be parsed. It is also
+   * short-lived: this call is what creates the shipment at the carrier, so a
+   * rate from an old call may no longer be purchasable.
+   *
+   * Returns `[]` when the store has no shipping app installed, or when the
+   * order has no usable shipping address.
+   *
+   * @example
+   * ```typescript
+   * const rates = await client.getOrderShippingRates('order_abc');
+   * const cheapest = rates[0];
+   * const label = await client.createShippingLabel('order_abc', { rateId: cheapest.id });
+   * ```
+   */
+  async getOrderShippingRates(orderId) {
+    return this.request("GET", `/api/v1/orders/${encodePathSegment(orderId)}/shipments/app-rates`);
+  }
+  /**
+   * Shipments recorded for an order, each with its tracking history.
+   *
+   * History arrives on its own: the carrier's webhooks flow through the
+   * installed shipping app and append events as the parcel moves. Poll this for
+   * display if you need it; do not poll expecting to *drive* anything.
+   */
+  async getOrderShipments(orderId) {
+    return this.request("GET", `/api/v1/orders/${encodePathSegment(orderId)}/shipments`);
+  }
   /**
    * Cancel an order
    * Works for Shopify and WooCommerce orders that haven't been fulfilled
@@ -1834,16 +2042,31 @@ var BrainerceClient = class {
     return this.request("POST", `/api/v1/orders/${encodePathSegment(orderId)}/cancel`);
   }
   /**
-   * Fulfill an order (mark as shipped)
-   * Works for Shopify and WooCommerce orders
+   * Fulfill an order (mark as shipped), or correct the tracking of an order
+   * that has already shipped.
+   *
+   * Pass `trackingUrl` alongside the number — the shipped email only renders
+   * its "Track Your Order" button when a URL is present.
+   *
+   * Calling this again on an order that is already `SHIPPED`/`FULFILLED` with
+   * tracking fields edits only those fields: the status does not move, the
+   * ship date is not rewritten, and no fulfilment event fires. That is the way
+   * to fix a mistyped tracking number.
    *
    * @example
    * ```typescript
-   * const order = await client.fulfillOrder('order_123', {
+   * // First fulfilment — emails the shopper by default.
+   * await client.fulfillOrder('order_123', {
    *   trackingNumber: '1Z999AA10123456784',
    *   trackingCompany: 'UPS',
+   *   trackingUrl: 'https://www.ups.com/track?tracknum=1Z999AA10123456784',
    *   notifyCustomer: true,
    * });
+   *
+   * // Correction — silent unless you opt back in.
+   * await client.fulfillOrder('order_123', {
+   *   trackingNumber: '1Z999AA10123456785',
+   * });
    * ```
    */
   async fulfillOrder(orderId, data) {
@@ -2584,11 +2807,25 @@ var BrainerceClient = class {
    *
    * @param provider - OAuth provider ('GOOGLE', 'FACEBOOK', 'GITHUB')
    * @param options - Optional configuration
-   * @param options.redirectUrl - Full absolute URL to redirect to after OAuth completes (must include origin)
-   *
-   * @example
-   * ```typescript
-   * // Get authorization URL (redirectUrl MUST be absolute with origin)
+   * @param options.redirectUrl - Where to send the browser once OAuth finishes —
+   *   on success *and* on failure. Validated server-side against the sales
+   *   channel's trusted origins, so what is accepted depends on the mode:
+   *   - vibe-coded (`salesChannelId: 'vc_*'`): an absolute URL on the channel's
+   *     registered `domain` or one of its `allowedOrigins`; in TEST mode, any
+   *     `localhost`/`127.0.0.1` port. A relative path (`/auth/callback`) also
+   *     works — it is resolved against the channel's `domain` on the way back,
+   *     so the channel must have one registered.
+   *   - storefront (`storeId`): **social login cannot round-trip in this mode.**
+   *     No channel is bound to the request, so an absolute URL has no
+   *     trusted-origin list to match (400 at this call) and a relative path has
+   *     no origin to resolve against on the way back. Use a `salesChannelId`
+   *     connection for OAuth.
+   *   Anything invalid fails fast here, before the shopper ever reaches the
+   *   provider.
+   *
+   * @example
+   * ```typescript
+   * // Vibe-coded mode — absolute URL on the registered storefront domain
    * const { authorizationUrl } = await client.getOAuthAuthorizeUrl('GOOGLE', {
    *   redirectUrl: window.location.origin + '/auth/callback'
    * });
@@ -2603,9 +2840,25 @@ 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')) {
-   *   // Show error
+   *   // Failures land on this same page, on `redirectUrl` — never on the API
+   *   // host. `oauth_error` is a stable snake_case code (see OAuthErrorCode);
+   *   // `error_description` is English developer detail, not shopper copy.
+   *   const code = params.get('oauth_error') as OAuthErrorCode;
+   *   showMessage(
+   *     code === 'link_blocked_unverified_password_account'
+   *       ? t('auth.verifyEmailFirst')   // send them to email verification
+   *       : code === 'state_expired'
+   *         ? t('auth.sessionExpiredRetry')
+   *         : t('auth.signInFailed')
+   *   );
    * }
    * ```
    */
@@ -2645,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);
@@ -2653,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
    * }
    * ```
    */
@@ -2981,6 +3240,9 @@ var BrainerceClient = class {
    * Create a new cart for a guest user
    * Returns a cart with a sessionToken that identifies this cart
    *
+   * If `loadGoogleAnalytics()` was called and has resolved a GA4 client/session
+   * id, it's auto-attached unless `options` already specifies one.
+   *
    * @example
    * ```typescript
    * const cart = await client.createCart();
@@ -2988,14 +3250,15 @@ var BrainerceClient = class {
    * // Store sessionToken in localStorage or cookie
    * ```
    */
-  async createCart() {
+  async createCart(options) {
+    const body = await this.withAnalyticsStitchIds(options);
     if (this.isVibeCodedMode()) {
-      return this.vibeCodedRequest("POST", "/cart");
+      return this.vibeCodedRequest("POST", "/cart", body);
     }
     if (this.storeId && !this.apiKey) {
-      return this.storefrontRequest("POST", "/cart");
+      return this.storefrontRequest("POST", "/cart", body);
     }
-    return this.adminRequest("POST", "/api/v1/cart");
+    return this.adminRequest("POST", "/api/v1/cart", body);
   }
   /**
    * Get a cart by session token (for guest users)
@@ -3144,20 +3407,21 @@ var BrainerceClient = class {
       });
       return this.withGuards(this.localCartToCart(this.getLocalCart()), "cart");
     }
+    const body = await this.withAnalyticsStitchIds(item);
     if (this.isVibeCodedMode()) {
       return this.withGuards(
-        this.vibeCodedRequest("POST", `/cart/${encodePathSegment(cartId)}/items`, item),
+        this.vibeCodedRequest("POST", `/cart/${encodePathSegment(cartId)}/items`, body),
         "cart"
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.withGuards(
-        this.storefrontRequest("POST", `/cart/${encodePathSegment(cartId)}/items`, item),
+        this.storefrontRequest("POST", `/cart/${encodePathSegment(cartId)}/items`, body),
         "cart"
       );
     }
     return this.withGuards(
-      this.adminRequest("POST", `/api/v1/cart/${encodePathSegment(cartId)}/items`, item),
+      this.adminRequest("POST", `/api/v1/cart/${encodePathSegment(cartId)}/items`, body),
       "cart"
     );
   }
@@ -4749,24 +5013,25 @@ var BrainerceClient = class {
    * ```
    */
   async setCheckoutCustomer(checkoutId, data) {
+    const body = await this.withAnalyticsStitchIds(data);
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
         `/checkout/${encodePathSegment(checkoutId)}/customer`,
-        data
+        body
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "PATCH",
         `/checkout/${encodePathSegment(checkoutId)}/customer`,
-        data
+        body
       );
     }
     return this.adminRequest(
       "PATCH",
       `/api/v1/checkout/${encodePathSegment(checkoutId)}/customer`,
-      data
+      body
     );
   }
   /**
@@ -4820,6 +5085,17 @@ var BrainerceClient = class {
    * should include an optional "Order notes" textarea by default and send its
    * value here (or via `setCheckoutCustomer`). The note lands on the order.
    *
+   * **Pass `placeId` whenever the address came from `addressAutocomplete()`.**
+   * The server re-resolves it to exact coordinates and matches polygon
+   * ("draw on map") shipping zones against those instead of re-geocoding the
+   * 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', {
@@ -4832,29 +5108,34 @@ var BrainerceClient = class {
    *   postalCode: '10001',
    *   country: 'US',
    *   notes: 'Please leave the package at the door', // optional order notes
+   *   placeId: suggestion.placeId,          // from addressAutocomplete()
+   *   placeSessionToken: sessionToken,      // the same token used for it
    * });
    * console.log('Available rates:', rates);
    * ```
    */
   async setShippingAddress(checkoutId, address) {
+    const body = await this.withAnalyticsStitchIds(
+      this.stripResolvedOnlyAddressFields(address)
+    );
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
         `/checkout/${encodePathSegment(checkoutId)}/shipping-address`,
-        address
+        body
       );
     }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "PATCH",
         `/checkout/${encodePathSegment(checkoutId)}/shipping-address`,
-        address
+        body
       );
     }
     return this.adminRequest(
       "PATCH",
       `/api/v1/checkout/${encodePathSegment(checkoutId)}/shipping-address`,
-      address
+      body
     );
   }
   /**
@@ -5149,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
     );
   }
   /**
@@ -6132,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;
     }
@@ -6140,7 +6422,7 @@ var BrainerceClient = class {
       checkout = await this.vibeCodedRequest(
         "PATCH",
         `/checkout/${encodePathSegment(checkoutId)}/billing-address`,
-        data.billingAddress
+        this.stripResolvedOnlyAddressFields(data.billingAddress)
       );
     }
     if (!checkout) {
@@ -8981,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);
@@ -9164,6 +9457,11 @@ function formatAmount(amount, currency, locale) {
 // src/date-availability.ts
 var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 var TIME_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
+var DATE_ONLY_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+var DATE_TIME_RE = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?(?:\.(\d{1,9}))?(Z|z|[+-]\d{2}:\d{2})?$/;
+var MIN_OFFSET_MINUTES = -12 * 60;
+var MAX_OFFSET_MINUTES = 14 * 60;
+var VALID_OFFSET_MINUTE_PARTS = [0, 30, 45];
 function validateDateAvailabilityConfig(config, fieldType) {
   const errors = [];
   if (!config) return errors;
@@ -9264,6 +9562,101 @@ function resolveStoreLocalParts(instant, timezone) {
     weekday: WEEKDAY_TO_INDEX[get("weekday")] ?? instant.getUTCDay()
   };
 }
+function parseDateFieldValue(raw, fieldType, timezone) {
+  const str = raw instanceof Date ? Number.isNaN(raw.getTime()) ? "" : raw.toISOString() : typeof raw === "string" ? raw.trim() : "";
+  const expected = fieldType === "DATE" ? "expected a calendar date in YYYY-MM-DD format" : "expected an ISO-8601 date/time such as 2026-08-13T13:00:00+03:00";
+  if (!str) return { status: "invalid", reason: `"${String(raw)}" is not a valid date \u2014 ${expected}` };
+  const dateOnly = DATE_ONLY_RE.exec(str);
+  const dateTime = dateOnly ? null : DATE_TIME_RE.exec(str);
+  const match = dateOnly ?? dateTime;
+  if (!match) return { status: "invalid", reason: `"${str}" is not a valid date \u2014 ${expected}` };
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  if (!isRealCalendarDate(year, month, day)) {
+    return { status: "invalid", reason: `"${str}" is not a real calendar date` };
+  }
+  const dateYYYYMMDD = `${match[1]}-${match[2]}-${match[3]}`;
+  if (fieldType === "DATE") {
+    return {
+      status: "valid",
+      value: { instant: /* @__PURE__ */ new Date(`${dateYYYYMMDD}T00:00:00.000Z`), normalized: dateYYYYMMDD }
+    };
+  }
+  if (!dateTime) {
+    const instant2 = instantFromStoreLocal(dateYYYYMMDD, 0, 0, 0, 0, timezone);
+    return { status: "valid", value: { instant: instant2, normalized: instant2.toISOString() } };
+  }
+  const hour = Number(dateTime[4]);
+  const minute = Number(dateTime[5]);
+  const second = Number(dateTime[6] ?? "0");
+  const millis = Number((dateTime[7] ?? "").slice(0, 3).padEnd(3, "0") || "0");
+  if (hour > 23 || minute > 59 || second > 59) {
+    return { status: "invalid", reason: `"${str}" has an out-of-range time` };
+  }
+  const offset = dateTime[8];
+  if (!offset) {
+    const instant2 = instantFromStoreLocal(dateYYYYMMDD, hour, minute, second, millis, timezone);
+    return { status: "valid", value: { instant: instant2, normalized: instant2.toISOString() } };
+  }
+  let offsetMinutes = 0;
+  if (offset !== "Z" && offset !== "z") {
+    const offsetHourPart = Number(offset.slice(1, 3));
+    const offsetMinutePart = Number(offset.slice(4, 6));
+    offsetMinutes = (offset[0] === "-" ? -1 : 1) * (offsetHourPart * 60 + offsetMinutePart);
+    if (offsetMinutes < MIN_OFFSET_MINUTES || offsetMinutes > MAX_OFFSET_MINUTES) {
+      return {
+        status: "invalid",
+        reason: `"${str}" ends in "${offset}", which is not a real UTC offset (they run -12:00 to +14:00). A time-slot label such as "13:00-14:00" is not an offset \u2014 ${expected}`
+      };
+    }
+    if (!VALID_OFFSET_MINUTE_PARTS.includes(offsetMinutePart)) {
+      return {
+        status: "invalid",
+        reason: `"${str}" ends in "${offset}", which is not a real UTC offset (the minutes are always :00, :30 or :45). A time-slot label such as "13:00-14:00" is not an offset \u2014 ${expected}`
+      };
+    }
+  }
+  const instant = new Date(
+    Date.UTC(year, month - 1, day, hour, minute, second, millis) - offsetMinutes * 6e4
+  );
+  return { status: "valid", value: { instant, normalized: instant.toISOString() } };
+}
+function isRealCalendarDate(year, month, day) {
+  if (month < 1 || month > 12 || day < 1 || day > 31) return false;
+  const probe = new Date(Date.UTC(year, month - 1, day));
+  return probe.getUTCFullYear() === year && probe.getUTCMonth() === month - 1 && probe.getUTCDate() === day;
+}
+function instantFromStoreLocal(dateYYYYMMDD, hour, minute, second, millis, timezone) {
+  const [year, month, day] = dateYYYYMMDD.split("-").map(Number);
+  const naive = Date.UTC(year, month - 1, day, hour, minute, second, millis);
+  const firstOffset = timezoneOffsetMs(naive, timezone);
+  let instant = naive - firstOffset;
+  const secondOffset = timezoneOffsetMs(instant, timezone);
+  if (secondOffset !== firstOffset) instant = naive - secondOffset;
+  return new Date(instant);
+}
+function timezoneOffsetMs(utcMillis, timezone) {
+  let parts;
+  try {
+    parts = new Intl.DateTimeFormat("en-US", {
+      timeZone: timezone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hour12: false
+    }).formatToParts(new Date(utcMillis));
+  } catch {
+    return 0;
+  }
+  const get = (type) => Number(parts.find((p) => p.type === type)?.value ?? "0");
+  const hour = get("hour") === 24 ? 0 : get("hour");
+  const asIfUtc = Date.UTC(get("year"), get("month") - 1, get("day"), hour, get("minute"), get("second"));
+  return asIfUtc - Math.floor(utcMillis / 1e3) * 1e3;
+}
 function isCalendarDateAllowed(dateYYYYMMDD, config) {
   if (!config) return true;
   if (config.minDate && dateYYYYMMDD < config.minDate) return false;
@@ -9291,6 +9684,12 @@ function computeAvailableSlots(config, dateYYYYMMDD) {
   }
   return slots;
 }
+function getBusinessHoursForDate(config, dateYYYYMMDD) {
+  if (!config?.businessHours?.length) return [];
+  if (!isCalendarDateAllowed(dateYYYYMMDD, config)) return [];
+  const weekday = weekdayOfDateString(dateYYYYMMDD);
+  return config.businessHours.filter((w) => w.weekday === weekday);
+}
 function isDateValueAllowed(instant, config, fieldType, timezone) {
   if (!config) return { allowed: true };
   if (fieldType === "DATE") {
@@ -9839,6 +10238,7 @@ export {
   formatProductPrice,
   formatVariantPrice,
   getBlogSitemapEntries,
+  getBusinessHoursForDate,
   getCartItemImage,
   getCartItemName,
   getCartTotals,
@@ -9863,6 +10263,7 @@ export {
   isHtmlDescription,
   isWebhookEventType,
   jsonLdScriptProps,
+  parseDateFieldValue,
   parseWebhookEvent,
   resolveStoreLocalParts,
   safePaymentRedirect,