brainerce 1.59.0 → 1.63.0

package/dist/index.js

@@ -78,6 +78,7 @@ __export(index_exports, {
   jsonLdScriptProps: () => jsonLdScriptProps,
   parseDateFieldValue: () => parseDateFieldValue,
   parseWebhookEvent: () => parseWebhookEvent,
+  resolveRelativeBounds: () => resolveRelativeBounds,
   resolveStoreLocalParts: () => resolveStoreLocalParts,
   safePaymentRedirect: () => safePaymentRedirect,
   stripHtml: () => stripHtml2,
@@ -203,7 +204,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.54.0";
+var SDK_VERSION = "1.60.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -360,6 +361,87 @@ var _BrainerceClient = class _BrainerceClient {
         );
       }
     };
+    // -------------------- Marketing signup (newsletter) --------------------
+    /**
+     * Email marketing signup for a storefront — a newsletter popup, a footer
+     * capture bar, an exit-intent modal.
+     *
+     * **Confirmed opt-in, always.** `subscribe()` creates the contact and mails
+     * them a confirmation link. The address is NOT subscribed and CANNOT receive
+     * a campaign until the recipient clicks that link. This is not a setting:
+     * consent has to come from the mailbox, or anyone could subscribe anyone.
+     *
+     * So do not render "You're subscribed!" on success — render "Check your
+     * email to confirm." The one is a lie until the click lands.
+     *
+     * The response is identical for a brand-new address, one that is already
+     * subscribed, and one suppressed after a bounce, so the form can't be used to
+     * probe who shops here. Show the same message for every success.
+     *
+     * Storefront (public) and vibe-coded modes only. Rate-limited server-side to
+     * 3 requests / 60s per IP, plus one confirmation email per address per 24h.
+     *
+     * **Where the discount goes.** A "10% off your first order" popup needs a
+     * coupon from the dashboard — create one with the `customer_first_order`
+     * condition and show the code after a successful call. Subscribing does not
+     * mint a code on its own.
+     *
+     * @example
+     * ```typescript
+     * // Newsletter popup — hidden honeypot input, Hebrew storefront
+     * await brainerce.marketing.subscribe({
+     *   email: 'jane@example.com',
+     *   locale: 'he',
+     *   source: 'popup',
+     *   honeypot: hiddenFieldValue,
+     * });
+     * // → show "בדקו את המייל שלכם כדי לאשר" — NOT "נרשמת בהצלחה"
+     * ```
+     */
+    this.marketing = {
+      subscribe: async (input) => {
+        if (this.isVibeCodedMode()) {
+          return this.vibeCodedRequest(
+            "POST",
+            "/marketing/subscribe",
+            input
+          );
+        }
+        return this.storefrontRequest(
+          "POST",
+          "/marketing/subscribe",
+          input
+        );
+      }
+    };
+    // -------------------- Stock alerts --------------------
+    /**
+     * "Email me when this is back."
+     *
+     * ⛔ Not a newsletter signup, and must not be worded as one. It grants no
+     * marketing consent, creates no customer account, and the person is never
+     * mailed anything else as a result — exactly one message, about this item,
+     * with a link that stops it. Someone who unsubscribed from marketing can
+     * still use this, so do not gate it on consent.
+     *
+     * Show the affordance only on an item that is out of stock AND cannot be
+     * backordered. Every other case is silently ignored server-side — the
+     * response is uniform on purpose, so it cannot be used to read stock levels
+     * or test who is a customer — which means a button on an in-stock item looks
+     * like it worked and does nothing.
+     *
+     * Pass `variantId` on any product with variants. Without it the alert waits
+     * on the product as a whole, and a shopper who wanted the medium hears when
+     * the small comes back.
+     */
+    this.stockAlerts = {
+      subscribe: async (input) => {
+        if (this.isVibeCodedMode()) {
+          return this.vibeCodedRequest("POST", "/stock-alerts", input);
+        }
+        return this.storefrontRequest("POST", "/stock-alerts", input);
+      }
+    };
     // -------------------- Content (typed merchant content) --------------------
     /**
      * Typed merchant content store: FAQ, Footer, Header, Announcement,
@@ -3134,6 +3216,11 @@ var _BrainerceClient = class _BrainerceClient {
    * Register a new customer with password (creates account)
    * Works in vibe-coded, storefront, and admin mode
    *
+   * `birthMonth`/`birthDay` are optional and must be sent together. When
+   * `getStoreInfo().requireBirthday` is true the merchant made the birthday
+   * mandatory on that sales channel, and a call without both fields is
+   * rejected with HTTP 400.
+   *
    * @example
    * ```typescript
    * const auth = await client.registerCustomer({
@@ -3141,6 +3228,8 @@ var _BrainerceClient = class _BrainerceClient {
    *   password: 'securepassword123',
    *   firstName: 'Jane',
    *   lastName: 'Doe',
+   *   birthMonth: 4, // optional, unless the channel requires a birthday
+   *   birthDay: 17,
    * });
    * ```
    */
@@ -4419,16 +4508,27 @@ var _BrainerceClient = class _BrainerceClient {
    * List visible reviews for a product (storefront / sales-channel modes).
    * Reviews that the merchant has hidden are excluded.
    *
+   * Each review carries `images` — the photos its author attached, already
+   * filtered to the ones shoppers are allowed to see. Always an array.
+   *
+   * Ordering defaults to `photos_first`: reviews carrying photos lead, newest-first
+   * within each group. Pass `sort: 'newest'` for plain chronological order. On a
+   * store with no review photos the two are identical.
+   *
    * @example
    * ```typescript
    * const { data, meta } = await client.listProductReviews('prod_123', { page: 1, limit: 20 });
-   * data.forEach(r => console.log(r.rating, r.body, r.verifiedPurchase));
+   * data.forEach(r => {
+   *   console.log(r.rating, r.body, r.verifiedPurchase);
+   *   r.images.forEach(img => console.log(img.thumbnailUrl ?? img.url));
+   * });
    * ```
    */
   async listProductReviews(productId, params) {
     const queryParams = {};
     if (params?.page) queryParams.page = params.page;
     if (params?.limit) queryParams.limit = params.limit;
+    if (params?.sort) queryParams.sort = params.sort;
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
@@ -4586,6 +4686,37 @@ var _BrainerceClient = class _BrainerceClient {
       storeId ? { storeId } : void 0
     );
   }
+  /**
+   * Admin: hide ONE photo on a review, leaving the review and its other photos
+   * visible. Requires an API key with `reviews:write`.
+   */
+  async hideProductReviewImage(imageId, storeId) {
+    if (!this.apiKey) {
+      throw new BrainerceError("hideProductReviewImage() requires admin (API key) mode", 400);
+    }
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/review-images/${encodePathSegment(imageId)}/hide`,
+      void 0,
+      storeId ? { storeId } : void 0
+    );
+  }
+  /**
+   * Admin: show one review photo. This is also the approve action — a photo that
+   * has never been approved carries no `approvedAt`, and showing it stamps one, so
+   * stores using review-photo approval need no separate verb.
+   */
+  async showProductReviewImage(imageId, storeId) {
+    if (!this.apiKey) {
+      throw new BrainerceError("showProductReviewImage() requires admin (API key) mode", 400);
+    }
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/review-images/${encodePathSegment(imageId)}/show`,
+      void 0,
+      storeId ? { storeId } : void 0
+    );
+  }
   /** Admin: unhide a previously hidden review. */
   async showProductReview(reviewId, storeId) {
     if (!this.apiKey) {
@@ -7241,11 +7372,20 @@ var _BrainerceClient = class _BrainerceClient {
     );
   }
   /**
-   * Update the current customer's profile (requires customerToken)
-   * Only available in storefront mode
+   * Update the current customer's profile (requires customerToken).
+   * Only available in storefront and vibe-coded mode.
    *
-   * `birthMonth`/`birthDay` (1-12 / 1-31, no year — privacy) power the loyalty
-   * birthday gift; they must be provided together.
+   * `birthMonth`/`birthDay` (1-12 / 1-31) power the loyalty birthday gift.
+   * Month and day only, never a year, for privacy. Send both or neither, and
+   * the day has to exist in the month: anything else is rejected with HTTP 400.
+   * Send `null` for both to REMOVE a stored birthday. Leaving the keys out is a
+   * different request and keeps the stored value, so a profile form whose
+   * fields the shopper cleared has to send nulls, not omit them.
+   *
+   * The saved values now come back on the returned `CustomerProfile`, on
+   * `getMyProfile()` and on every customer read type, so a profile form can
+   * re-render the birthday it just saved. Before this, no API returned the two
+   * fields at all and the form always came back blank.
    */
   async updateMyProfile(data) {
     if (!this.customerToken && !this.proxyMode) {
@@ -9422,6 +9562,68 @@ var _BrainerceClient = class _BrainerceClient {
     }
     throw new Error("uploadCustomizationFile requires storefront or vibe-coded mode");
   }
+  /**
+   * Upload one photo to attach to a product review.
+   *
+   * Available in storefront and vibe-coded modes, and — unlike
+   * `uploadCustomizationFile` — it REQUIRES a logged-in customer who has actually
+   * bought the product. Call `setCustomerToken(...)` first. That is the same bar as
+   * writing the review itself, checked here so an ineligible shopper is told before
+   * they wait for the upload rather than after.
+   *
+   * Returns a storage `key`. Collect the keys and pass them as `imageKeys` when you
+   * submit or update the review — the `url` is for a local preview only, and sending
+   * it back instead of the key will be rejected.
+   *
+   * Server rules:
+   * - `image/jpeg|png|webp|gif` only, cross-checked against the file's real bytes.
+   * - Max 5 MB and 40 megapixels per file.
+   * - Throttled to 10 uploads / minute → HTTP 429.
+   * - 403 when the store has review photos turned off, or the customer has not
+   *   bought the product; 400 once the review is already at its photo cap.
+   * - EXIF is stripped (so GPS coordinates never reach the storefront) while the
+   *   orientation tag is applied first, so phone photos stay upright.
+   * - A photo uploaded but never attached to a submitted review is reclaimed after
+   *   7 days.
+   *
+   * Read `photos` from `getMyProductReview()` for the store's live limits rather
+   * than hard-coding them.
+   *
+   * @example
+   * ```ts
+   * const { photos } = await client.getMyProductReview(productId);
+   * if (photos.enabled) {
+   *   const uploads = await Promise.all(
+   *     [...fileInput.files].slice(0, photos.maxPerReview)
+   *       .map(f => client.uploadReviewPhoto(productId, f))
+   *   );
+   *   await client.submitProductReview(productId, {
+   *     rating: 5,
+   *     body: 'Arrived beautifully wrapped.',
+   *     imageKeys: uploads.map(u => u.key),
+   *   });
+   * }
+   * ```
+   */
+  async uploadReviewPhoto(productId, file) {
+    const formData = new FormData();
+    formData.append("file", file);
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "POST",
+        `/products/${encodePathSegment(productId)}/review-photo`,
+        formData
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "POST",
+        `/products/${encodePathSegment(productId)}/review-photo`,
+        formData
+      );
+    }
+    throw new Error("uploadReviewPhoto requires storefront or vibe-coded mode");
+  }
   // -------------------- Team Management (Admin) - DEPRECATED --------------------
   // Account-level team methods. These are the ONLY team endpoints reachable with
   // a `brainerce_*` API key. The store-level equivalents (`getStoreTeam`,
@@ -10109,7 +10311,7 @@ var DATE_TIME_RE = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\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) {
+function validateDateAvailabilityConfig(config, fieldType, surface = "checkout") {
   const errors = [];
   if (!config) return errors;
   if (config.minDate !== void 0 && !DATE_RE.test(config.minDate)) {
@@ -10121,6 +10323,29 @@ function validateDateAvailabilityConfig(config, fieldType) {
   if (config.minDate && config.maxDate && DATE_RE.test(config.minDate) && DATE_RE.test(config.maxDate) && config.minDate > config.maxDate) {
     errors.push("minDate must be on or before maxDate");
   }
+  if (config.leadTimeMinutes !== void 0) {
+    if (!Number.isInteger(config.leadTimeMinutes) || config.leadTimeMinutes < 0) {
+      errors.push("leadTimeMinutes must be a non-negative integer");
+    }
+  }
+  if (config.maxDaysAhead !== void 0) {
+    if (!Number.isInteger(config.maxDaysAhead) || config.maxDaysAhead < 1) {
+      errors.push("maxDaysAhead must be a positive integer");
+    }
+  }
+  if (config.cutoffTime !== void 0 && !TIME_RE.test(config.cutoffTime)) {
+    errors.push("cutoffTime must be in HH:mm format");
+  }
+  if (surface !== "checkout") {
+    const relativeKeys = ["leadTimeMinutes", "cutoffTime", "maxDaysAhead"].filter(
+      (k) => config[k] !== void 0
+    );
+    if (relativeKeys.length > 0) {
+      errors.push(
+        `${relativeKeys.join("/")} only apply to checkout fields, not ${surface} fields`
+      );
+    }
+  }
   if (config.blockedWeekdays) {
     for (const d of config.blockedWeekdays) {
       if (!Number.isInteger(d) || d < 0 || d > 6) {
@@ -10138,22 +10363,37 @@ function validateDateAvailabilityConfig(config, fieldType) {
     }
   }
   if (config.businessHours) {
-    const seenWeekdays = /* @__PURE__ */ new Set();
+    const windowsByWeekday = /* @__PURE__ */ new Map();
     for (const w of config.businessHours) {
       if (!Number.isInteger(w.weekday) || w.weekday < 0 || w.weekday > 6) {
         errors.push(`businessHours.weekday must be an integer 0-6, got ${JSON.stringify(w.weekday)}`);
         continue;
       }
-      if (seenWeekdays.has(w.weekday)) {
-        errors.push(`businessHours has more than one window for weekday ${w.weekday}`);
-      }
-      seenWeekdays.add(w.weekday);
       const openValid = TIME_RE.test(w.open);
       const closeValid = TIME_RE.test(w.close);
       if (!openValid) errors.push(`businessHours.open must be HH:mm, got "${w.open}"`);
       if (!closeValid) errors.push(`businessHours.close must be HH:mm, got "${w.close}"`);
-      if (openValid && closeValid && w.open >= w.close) {
+      if (!openValid || !closeValid) continue;
+      if (w.open >= w.close) {
         errors.push(`businessHours for weekday ${w.weekday}: open must be before close`);
+        continue;
+      }
+      const forDay = windowsByWeekday.get(w.weekday);
+      if (forDay) forDay.push(w);
+      else windowsByWeekday.set(w.weekday, [w]);
+    }
+    const weekdaysWithWindows = Array.from(windowsByWeekday.keys()).sort((a, b) => a - b);
+    for (const weekday of weekdaysWithWindows) {
+      const sorted = [...windowsByWeekday.get(weekday) ?? []].sort(
+        (a, b) => a.open < b.open ? -1 : a.open > b.open ? 1 : 0
+      );
+      for (let i = 1; i < sorted.length; i++) {
+        if (sorted[i].open < sorted[i - 1].close) {
+          errors.push(
+            `businessHours for weekday ${weekday}: ${sorted[i - 1].open}-${sorted[i - 1].close} overlaps ${sorted[i].open}-${sorted[i].close}`
+          );
+          break;
+        }
       }
     }
   }
@@ -10209,6 +10449,32 @@ function resolveStoreLocalParts(instant, timezone) {
     weekday: WEEKDAY_TO_INDEX[get("weekday")] ?? instant.getUTCDay()
   };
 }
+function resolveRelativeBounds(config, clock) {
+  if (!config || !clock) return {};
+  const leadMinutes = typeof config.leadTimeMinutes === "number" && Number.isFinite(config.leadTimeMinutes) ? Math.max(0, Math.floor(config.leadTimeMinutes)) : 0;
+  const cutoff = typeof config.cutoffTime === "string" && TIME_RE.test(config.cutoffTime) ? config.cutoffTime : null;
+  const daysAhead = typeof config.maxDaysAhead === "number" && Number.isFinite(config.maxDaysAhead) && config.maxDaysAhead >= 1 ? Math.floor(config.maxDaysAhead) : null;
+  if (leadMinutes === 0 && !cutoff && daysAhead === null) return {};
+  const now = clock.now ?? /* @__PURE__ */ new Date();
+  const nowLocal = resolveStoreLocalParts(now, clock.timezone);
+  const bounds = {};
+  if (leadMinutes > 0 || cutoff) {
+    const earliestInstant = new Date(now.getTime() + leadMinutes * 6e4);
+    let earliestDate = resolveStoreLocalParts(earliestInstant, clock.timezone).dateYYYYMMDD;
+    if (cutoff && nowLocal.hhmm >= cutoff) earliestDate = addCalendarDays(earliestDate, 1);
+    bounds.earliestDate = earliestDate;
+    if (leadMinutes > 0) bounds.earliestInstant = earliestInstant;
+  }
+  if (daysAhead !== null) {
+    bounds.latestDate = addCalendarDays(nowLocal.dateYYYYMMDD, daysAhead);
+  }
+  return bounds;
+}
+function addCalendarDays(dateYYYYMMDD, days) {
+  const [year, month, day] = dateYYYYMMDD.split("-").map(Number);
+  const shifted = new Date(Date.UTC(year, month - 1, day + days));
+  return `${shifted.getUTCFullYear()}-${pad2(shifted.getUTCMonth() + 1)}-${pad2(shifted.getUTCDate())}`;
+}
 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";
@@ -10304,19 +10570,30 @@ function timezoneOffsetMs(utcMillis, timezone) {
   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) {
+function isCalendarDateAllowed(dateYYYYMMDD, config, clock) {
   if (!config) return true;
   if (config.minDate && dateYYYYMMDD < config.minDate) return false;
   if (config.maxDate && dateYYYYMMDD > config.maxDate) return false;
+  if (relativeBoundFailure(dateYYYYMMDD, config, clock)) return false;
   if (config.blockedDates?.includes(dateYYYYMMDD)) return false;
   if (config.blockedWeekdays?.length) {
     if (config.blockedWeekdays.includes(weekdayOfDateString(dateYYYYMMDD))) return false;
   }
   return true;
 }
-function computeAvailableSlots(config, dateYYYYMMDD) {
+function relativeBoundFailure(dateYYYYMMDD, config, clock) {
+  const bounds = resolveRelativeBounds(config, clock);
+  if (bounds.earliestDate && dateYYYYMMDD < bounds.earliestDate) {
+    return `the earliest available date is ${bounds.earliestDate}`;
+  }
+  if (bounds.latestDate && dateYYYYMMDD > bounds.latestDate) {
+    return `the latest available date is ${bounds.latestDate}`;
+  }
+  return null;
+}
+function computeAvailableSlots(config, dateYYYYMMDD, clock) {
   if (!config) return [];
-  if (!isCalendarDateAllowed(dateYYYYMMDD, config)) return [];
+  if (!isCalendarDateAllowed(dateYYYYMMDD, config, clock)) return [];
   if (!config.businessHours?.length || !config.slotDurationMinutes) return [];
   const weekday = weekdayOfDateString(dateYYYYMMDD);
   const windows = config.businessHours.filter((w) => w.weekday === weekday);
@@ -10329,27 +10606,47 @@ function computeAvailableSlots(config, dateYYYYMMDD) {
       slots.push(minutesToHHMM(t));
     }
   }
-  return slots;
+  const ordered = Array.from(new Set(slots)).sort();
+  const { earliestInstant } = resolveRelativeBounds(config, clock);
+  if (!earliestInstant || !clock) return ordered;
+  return ordered.filter((hhmm) => {
+    const [hour, minute] = hhmm.split(":").map(Number);
+    const start = instantFromStoreLocal(dateYYYYMMDD, hour, minute, 0, 0, clock.timezone);
+    return start.getTime() >= earliestInstant.getTime();
+  });
 }
-function getBusinessHoursForDate(config, dateYYYYMMDD) {
+function getBusinessHoursForDate(config, dateYYYYMMDD, clock) {
   if (!config?.businessHours?.length) return [];
-  if (!isCalendarDateAllowed(dateYYYYMMDD, config)) return [];
+  if (!isCalendarDateAllowed(dateYYYYMMDD, config, clock)) return [];
   const weekday = weekdayOfDateString(dateYYYYMMDD);
   return config.businessHours.filter((w) => w.weekday === weekday);
 }
-function isDateValueAllowed(instant, config, fieldType, timezone) {
+function isDateValueAllowed(instant, config, fieldType, timezone, now) {
   if (!config) return { allowed: true };
+  const clock = { timezone, now };
   if (fieldType === "DATE") {
     const dateYYYYMMDD = `${instant.getUTCFullYear()}-${pad2(instant.getUTCMonth() + 1)}-${pad2(instant.getUTCDate())}`;
-    if (!isCalendarDateAllowed(dateYYYYMMDD, config)) {
+    const relative2 = relativeBoundFailure(dateYYYYMMDD, config, clock);
+    if (relative2) return { allowed: false, reason: relative2 };
+    if (!isCalendarDateAllowed(dateYYYYMMDD, config, clock)) {
       return { allowed: false, reason: "date is outside the allowed range" };
     }
     return { allowed: true };
   }
   const local = resolveStoreLocalParts(instant, timezone);
-  if (!isCalendarDateAllowed(local.dateYYYYMMDD, config)) {
+  const relative = relativeBoundFailure(local.dateYYYYMMDD, config, clock);
+  if (relative) return { allowed: false, reason: relative };
+  if (!isCalendarDateAllowed(local.dateYYYYMMDD, config, clock)) {
     return { allowed: false, reason: "date is outside the allowed range" };
   }
+  const { earliestInstant } = resolveRelativeBounds(config, clock);
+  if (earliestInstant && instant.getTime() < earliestInstant.getTime()) {
+    const earliestLocal = resolveStoreLocalParts(earliestInstant, timezone);
+    return {
+      allowed: false,
+      reason: `the earliest available time is ${earliestLocal.dateYYYYMMDD} ${earliestLocal.hhmm}`
+    };
+  }
   if (!config.businessHours?.length) {
     return { allowed: true };
   }
@@ -10358,7 +10655,7 @@ function isDateValueAllowed(instant, config, fieldType, timezone) {
     return { allowed: false, reason: "no business hours are configured for this day" };
   }
   if (config.slotDurationMinutes) {
-    const slots = computeAvailableSlots(config, local.dateYYYYMMDD);
+    const slots = computeAvailableSlots(config, local.dateYYYYMMDD, clock);
     if (!slots.includes(local.hhmm)) {
       return { allowed: false, reason: "time does not match an available slot" };
     }
@@ -10989,6 +11286,7 @@ function isCouponApplicableToProduct(coupon, productId) {
   jsonLdScriptProps,
   parseDateFieldValue,
   parseWebhookEvent,
+  resolveRelativeBounds,
   resolveStoreLocalParts,
   safePaymentRedirect,
   stripHtml,