brainerce 1.25.1 → 1.27.0

package/dist/index.js

@@ -32,14 +32,17 @@ var index_exports = {};
 __export(index_exports, {
   BrainerceClient: () => BrainerceClient,
   BrainerceError: () => BrainerceError,
+  RTL_LOCALES: () => RTL_LOCALES,
   SDK_VERSION: () => SDK_VERSION,
   createWebhookHandler: () => createWebhookHandler,
+  deriveSeoDescription: () => deriveSeoDescription,
   enableDevGuards: () => enableDevGuards,
   formatPrice: () => formatPrice,
   getCartItemImage: () => getCartItemImage,
   getCartItemName: () => getCartItemName,
   getCartTotals: () => getCartTotals,
   getDescriptionContent: () => getDescriptionContent,
+  getDirectionForLocale: () => getDirectionForLocale,
   getPriceDisplay: () => formatPrice,
   getProductCustomizationFields: () => getProductCustomizationFields,
   getProductMetafield: () => getProductMetafield,
@@ -57,6 +60,7 @@ __export(index_exports, {
   isWebhookEventType: () => isWebhookEventType,
   parseWebhookEvent: () => parseWebhookEvent,
   safePaymentRedirect: () => safePaymentRedirect,
+  stripHtml: () => stripHtml,
   verifyWebhook: () => verifyWebhook
 });
 module.exports = __toCommonJS(index_exports);
@@ -183,6 +187,12 @@ var SDK_VERSION = "1.21.0";
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
 var DEFAULT_TIMEOUT = 3e4;
+var RTL_LOCALES = /* @__PURE__ */ new Set(["ar", "he", "fa", "ur", "yi"]);
+function getDirectionForLocale(locale) {
+  if (!locale) return "ltr";
+  const primary = locale.split("-")[0].toLowerCase();
+  return RTL_LOCALES.has(primary) ? "rtl" : "ltr";
+}
 var BrainerceClient = class {
   constructor(options) {
     this.customerToken = null;
@@ -256,6 +266,197 @@ var BrainerceClient = class {
         );
       }
     };
+    // -------------------- Content (typed merchant content) --------------------
+    /**
+     * Typed merchant content store: FAQ, Footer, Header, Announcement,
+     * Rich Text, and Page.
+     *
+     * Works in all three SDK modes (vibe-coded, storefront, admin):
+     *   - **Public reads** (`get`, `list`, `getBySlug`): work in any mode.
+     *   - **Write operations** (`create`, `update`, `publish`, `unpublish`,
+     *     `remove`): admin mode only — they call `/api/v1/content/...` with
+     *     the API key. Calling from storefront / vibe-coded mode throws.
+     *
+     * **Default key:** every type has `'main'` as its universal default key.
+     * Pass no argument to fetch the main entry; pass a custom key (e.g.
+     * `'shipping'`, `'holiday-2026'`) for topical entries.
+     *
+     * **404 contract:** public reads return `null` when no PUBLISHED row
+     * exists. Storefronts should render hard-coded fallbacks on `null` so
+     * the page never crashes when the merchant hasn't seeded yet.
+     *
+     * **Security:** RICH_TEXT, PAGE, and FAQ answers contain raw HTML.
+     * Always sanitize with isomorphic-dompurify (or equivalent) before
+     * rendering. The server does NOT pre-sanitize because some merchants
+     * embed iframes (e.g. YouTube videos).
+     *
+     * @example
+     * ```typescript
+     * // Storefront (public) — fetch the merchant's FAQ in Hebrew
+     * const faq = await client.content.faq.get('main', 'he');
+     * if (faq) {
+     *   faq.data.items.forEach(({ question, answer }) => {
+     *     // sanitize(answer) before injecting via dangerouslySetInnerHTML
+     *   });
+     * }
+     *
+     * // Admin — create a shipping FAQ in DRAFT
+     * await client.content.faq.create({
+     *   key: 'shipping',
+     *   name: 'Shipping FAQ',
+     *   data: { items: [{ question: '…', answer: '…' }] },
+     * });
+     * ```
+     */
+    this.content = (() => {
+      const DEFAULT_KEY = "main";
+      const publicGetPath = (type, key) => `/content/${encodeURIComponent(type)}/${encodeURIComponent(key)}`;
+      const adminBase = () => "/api/v1/content";
+      const publicGet = async (type, key, locale) => {
+        const query = locale ? { locale } : void 0;
+        const path = publicGetPath(type, key);
+        const onNotFound = (err) => {
+          if (err instanceof BrainerceError && err.statusCode === 404) return null;
+          throw err;
+        };
+        if (this.isVibeCodedMode()) {
+          return this.vibeCodedRequest("GET", path, void 0, query).catch(onNotFound);
+        }
+        if (this.storeId && !this.apiKey) {
+          return this.storefrontRequest("GET", path, void 0, query).catch(onNotFound);
+        }
+        throw new BrainerceError(
+          "content.<type>.get(key) is a public-read API. In admin mode, call client.content.list({ type }) and filter by key, or use client.content.findById(id).",
+          400
+        );
+      };
+      const publicList = async (type, locale) => {
+        const query = { type };
+        if (locale) query.locale = locale;
+        if (this.isVibeCodedMode()) {
+          return this.vibeCodedRequest("GET", "/content", void 0, query);
+        }
+        if (this.storeId && !this.apiKey) {
+          return this.storefrontRequest("GET", "/content", void 0, query);
+        }
+        return this.adminRequest(
+          "GET",
+          `${adminBase()}?type=${encodeURIComponent(type)}`
+        );
+      };
+      const requireAdmin = (action) => {
+        if (this.isVibeCodedMode() || this.storeId && !this.apiKey) {
+          throw new BrainerceError(
+            `client.content.${action}() requires admin mode (apiKey). Vibe-coded and storefront modes are read-only.`,
+            403
+          );
+        }
+      };
+      const createByType = async (type, input) => {
+        requireAdmin("create");
+        return this.adminRequest("POST", adminBase(), { ...input, type });
+      };
+      const updateById = async (id, input) => {
+        requireAdmin("update");
+        return this.adminRequest(
+          "PATCH",
+          `${adminBase()}/${encodeURIComponent(id)}`,
+          input
+        );
+      };
+      const publishById = async (id) => {
+        requireAdmin("publish");
+        return this.adminRequest("POST", `${adminBase()}/${encodeURIComponent(id)}/publish`);
+      };
+      const unpublishById = async (id) => {
+        requireAdmin("unpublish");
+        return this.adminRequest(
+          "POST",
+          `${adminBase()}/${encodeURIComponent(id)}/unpublish`
+        );
+      };
+      const removeById = async (id) => {
+        requireAdmin("remove");
+        await this.adminRequest("DELETE", `${adminBase()}/${encodeURIComponent(id)}`);
+      };
+      function makeNamespace(type) {
+        return {
+          /**
+           * Fetch one PUBLISHED entry by key (defaults to `'main'`). Returns
+           * `null` on 404 — render a hard-coded fallback when the merchant
+           * hasn't seeded yet.
+           */
+          get: (key = DEFAULT_KEY, locale) => publicGet(type, key, locale),
+          /** List all PUBLISHED entries of this type. */
+          list: (locale) => publicList(type, locale),
+          /** Create a new entry in DRAFT (admin mode). */
+          create: (input) => createByType(type, input)
+        };
+      }
+      return {
+        faq: makeNamespace("FAQ"),
+        footer: makeNamespace("FOOTER"),
+        header: makeNamespace("HEADER"),
+        announcement: makeNamespace("ANNOUNCEMENT"),
+        richText: makeNamespace("RICH_TEXT"),
+        page: {
+          ...makeNamespace("PAGE"),
+          /**
+           * Fetch a PUBLISHED page by its `data.slug` (e.g. `'about'`).
+           * Returns `null` on 404. Use this from your `app/[slug]/page.tsx`
+           * catch-all route.
+           */
+          getBySlug: async (slug, locale) => {
+            const query = locale ? { locale } : void 0;
+            const path = `/content/pages/by-slug/${encodeURIComponent(slug)}`;
+            const onNotFound = (err) => {
+              if (err instanceof BrainerceError && err.statusCode === 404) return null;
+              throw err;
+            };
+            if (this.isVibeCodedMode()) {
+              return this.vibeCodedRequest("GET", path, void 0, query).catch(
+                onNotFound
+              );
+            }
+            if (this.storeId && !this.apiKey) {
+              return this.storefrontRequest("GET", path, void 0, query).catch(
+                onNotFound
+              );
+            }
+            throw new BrainerceError(
+              "content.page.getBySlug() is a public-read API; not available in admin mode.",
+              400
+            );
+          }
+        },
+        // ---------- Admin operations (cross-type) ----------
+        /** Find a single row by its admin id (admin mode). */
+        findById: async (id) => {
+          requireAdmin("findById");
+          return this.adminRequest("GET", `${adminBase()}/${encodeURIComponent(id)}`);
+        },
+        /** List rows in admin mode with optional filters. */
+        listAdmin: async (filters) => {
+          requireAdmin("listAdmin");
+          const params = new URLSearchParams();
+          if (filters?.type) params.set("type", filters.type);
+          if (filters?.status) params.set("status", filters.status);
+          const qs = params.toString();
+          return this.adminRequest(
+            "GET",
+            qs ? `${adminBase()}?${qs}` : adminBase()
+          );
+        },
+        /** Replace `data` (and optional metadata) on an existing row. */
+        update: updateById,
+        /** Transition status DRAFT → PUBLISHED. */
+        publish: publishById,
+        /** Transition status PUBLISHED → DRAFT. */
+        unpublish: unpublishById,
+        /** Hard delete the row. Admin mode only. */
+        remove: removeById
+      };
+    })();
     // -------------------- Local Cart (Client-Side for Guests) --------------------
     // These methods store cart data in localStorage - NO API calls!
     // Use for guest users in vibe-coded sites
@@ -667,6 +868,19 @@ var BrainerceClient = class {
     }
     return this.adminRequest("GET", "/api/v1/store");
   }
+  /**
+   * Resolve the script direction (`'ltr' | 'rtl'`) for a locale tag.
+   * Use this on `<html dir>` in your root layout — do not maintain a local
+   * RTL set in your storefront.
+   *
+   * @param locale - Optional BCP-47 tag. If omitted, falls back to the SDK
+   *   client's configured locale (`new BrainerceClient({ locale: 'he' })`).
+   * @returns `'rtl'` for Arabic / Hebrew / Persian / Urdu / Yiddish family,
+   *   `'ltr'` for everything else (including unknown locales).
+   */
+  getStoreDirection(locale) {
+    return getDirectionForLocale(locale ?? this.locale);
+  }
   // -------------------- Products --------------------
   /**
    * Get a list of products with pagination and filtering
@@ -780,10 +994,11 @@ var BrainerceClient = class {
    */
   async getProductBySlug(slug, options) {
     const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
+    const encodedSlug = encodeURIComponent(slug);
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/products/slug/${slug}`,
+        `/products/slug/${encodedSlug}`,
         void 0,
         void 0,
         headerOverrides
@@ -792,13 +1007,13 @@ var BrainerceClient = class {
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/products/slug/${slug}`,
+        `/products/slug/${encodedSlug}`,
         void 0,
         void 0,
         headerOverrides
       );
     }
-    return this.adminRequest("GET", `/api/v1/products/by-slug/${slug}`);
+    return this.adminRequest("GET", `/api/v1/products/by-slug/${encodedSlug}`);
   }
   /**
    * Get available categories for filtering products
@@ -7143,6 +7358,26 @@ function getDescriptionContent(product) {
   }
   return { text: product.description };
 }
+function stripHtml(html) {
+  if (!html) return "";
+  return html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/&nbsp;/gi, " ").replace(/&amp;/gi, "&").replace(/&lt;/gi, "<").replace(/&gt;/gi, ">").replace(/&quot;/gi, '"').replace(/&#39;/gi, "'").replace(/&#x27;/gi, "'").replace(/&#x2F;/gi, "/").replace(/\s+/g, " ").trim();
+}
+function deriveSeoDescription(product, options) {
+  if (!product) return "";
+  const maxLength = options?.maxLength ?? 160;
+  const authored = (product.seoDescription ?? product.metaDescription ?? "").trim();
+  if (authored) return authored;
+  const plain = stripHtml(product.description);
+  if (plain) {
+    if (plain.length <= maxLength) return plain;
+    const sliceLength = maxLength - 1;
+    const slice = plain.slice(0, sliceLength);
+    const lastSpace = slice.lastIndexOf(" ");
+    const trimmed = lastSpace > maxLength * 0.5 ? slice.slice(0, lastSpace) : slice;
+    return trimmed.replace(/[\s.,;:!?-]+$/u, "") + "\u2026";
+  }
+  return product.name ?? "";
+}
 function getStockStatus(inventory, options) {
   if (!inventory) {
     return options?.outOfStockText ?? "Out of Stock";
@@ -7350,14 +7585,17 @@ function isCouponApplicableToProduct(coupon, productId) {
 0 && (module.exports = {
   BrainerceClient,
   BrainerceError,
+  RTL_LOCALES,
   SDK_VERSION,
   createWebhookHandler,
+  deriveSeoDescription,
   enableDevGuards,
   formatPrice,
   getCartItemImage,
   getCartItemName,
   getCartTotals,
   getDescriptionContent,
+  getDirectionForLocale,
   getPriceDisplay,
   getProductCustomizationFields,
   getProductMetafield,
@@ -7375,5 +7613,6 @@ function isCouponApplicableToProduct(coupon, productId) {
   isWebhookEventType,
   parseWebhookEvent,
   safePaymentRedirect,
+  stripHtml,
   verifyWebhook
 });

package/dist/index.mjs

@@ -120,6 +120,12 @@ var SDK_VERSION = "1.21.0";
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
 var DEFAULT_TIMEOUT = 3e4;
+var RTL_LOCALES = /* @__PURE__ */ new Set(["ar", "he", "fa", "ur", "yi"]);
+function getDirectionForLocale(locale) {
+  if (!locale) return "ltr";
+  const primary = locale.split("-")[0].toLowerCase();
+  return RTL_LOCALES.has(primary) ? "rtl" : "ltr";
+}
 var BrainerceClient = class {
   constructor(options) {
     this.customerToken = null;
@@ -193,6 +199,197 @@ var BrainerceClient = class {
         );
       }
     };
+    // -------------------- Content (typed merchant content) --------------------
+    /**
+     * Typed merchant content store: FAQ, Footer, Header, Announcement,
+     * Rich Text, and Page.
+     *
+     * Works in all three SDK modes (vibe-coded, storefront, admin):
+     *   - **Public reads** (`get`, `list`, `getBySlug`): work in any mode.
+     *   - **Write operations** (`create`, `update`, `publish`, `unpublish`,
+     *     `remove`): admin mode only — they call `/api/v1/content/...` with
+     *     the API key. Calling from storefront / vibe-coded mode throws.
+     *
+     * **Default key:** every type has `'main'` as its universal default key.
+     * Pass no argument to fetch the main entry; pass a custom key (e.g.
+     * `'shipping'`, `'holiday-2026'`) for topical entries.
+     *
+     * **404 contract:** public reads return `null` when no PUBLISHED row
+     * exists. Storefronts should render hard-coded fallbacks on `null` so
+     * the page never crashes when the merchant hasn't seeded yet.
+     *
+     * **Security:** RICH_TEXT, PAGE, and FAQ answers contain raw HTML.
+     * Always sanitize with isomorphic-dompurify (or equivalent) before
+     * rendering. The server does NOT pre-sanitize because some merchants
+     * embed iframes (e.g. YouTube videos).
+     *
+     * @example
+     * ```typescript
+     * // Storefront (public) — fetch the merchant's FAQ in Hebrew
+     * const faq = await client.content.faq.get('main', 'he');
+     * if (faq) {
+     *   faq.data.items.forEach(({ question, answer }) => {
+     *     // sanitize(answer) before injecting via dangerouslySetInnerHTML
+     *   });
+     * }
+     *
+     * // Admin — create a shipping FAQ in DRAFT
+     * await client.content.faq.create({
+     *   key: 'shipping',
+     *   name: 'Shipping FAQ',
+     *   data: { items: [{ question: '…', answer: '…' }] },
+     * });
+     * ```
+     */
+    this.content = (() => {
+      const DEFAULT_KEY = "main";
+      const publicGetPath = (type, key) => `/content/${encodeURIComponent(type)}/${encodeURIComponent(key)}`;
+      const adminBase = () => "/api/v1/content";
+      const publicGet = async (type, key, locale) => {
+        const query = locale ? { locale } : void 0;
+        const path = publicGetPath(type, key);
+        const onNotFound = (err) => {
+          if (err instanceof BrainerceError && err.statusCode === 404) return null;
+          throw err;
+        };
+        if (this.isVibeCodedMode()) {
+          return this.vibeCodedRequest("GET", path, void 0, query).catch(onNotFound);
+        }
+        if (this.storeId && !this.apiKey) {
+          return this.storefrontRequest("GET", path, void 0, query).catch(onNotFound);
+        }
+        throw new BrainerceError(
+          "content.<type>.get(key) is a public-read API. In admin mode, call client.content.list({ type }) and filter by key, or use client.content.findById(id).",
+          400
+        );
+      };
+      const publicList = async (type, locale) => {
+        const query = { type };
+        if (locale) query.locale = locale;
+        if (this.isVibeCodedMode()) {
+          return this.vibeCodedRequest("GET", "/content", void 0, query);
+        }
+        if (this.storeId && !this.apiKey) {
+          return this.storefrontRequest("GET", "/content", void 0, query);
+        }
+        return this.adminRequest(
+          "GET",
+          `${adminBase()}?type=${encodeURIComponent(type)}`
+        );
+      };
+      const requireAdmin = (action) => {
+        if (this.isVibeCodedMode() || this.storeId && !this.apiKey) {
+          throw new BrainerceError(
+            `client.content.${action}() requires admin mode (apiKey). Vibe-coded and storefront modes are read-only.`,
+            403
+          );
+        }
+      };
+      const createByType = async (type, input) => {
+        requireAdmin("create");
+        return this.adminRequest("POST", adminBase(), { ...input, type });
+      };
+      const updateById = async (id, input) => {
+        requireAdmin("update");
+        return this.adminRequest(
+          "PATCH",
+          `${adminBase()}/${encodeURIComponent(id)}`,
+          input
+        );
+      };
+      const publishById = async (id) => {
+        requireAdmin("publish");
+        return this.adminRequest("POST", `${adminBase()}/${encodeURIComponent(id)}/publish`);
+      };
+      const unpublishById = async (id) => {
+        requireAdmin("unpublish");
+        return this.adminRequest(
+          "POST",
+          `${adminBase()}/${encodeURIComponent(id)}/unpublish`
+        );
+      };
+      const removeById = async (id) => {
+        requireAdmin("remove");
+        await this.adminRequest("DELETE", `${adminBase()}/${encodeURIComponent(id)}`);
+      };
+      function makeNamespace(type) {
+        return {
+          /**
+           * Fetch one PUBLISHED entry by key (defaults to `'main'`). Returns
+           * `null` on 404 — render a hard-coded fallback when the merchant
+           * hasn't seeded yet.
+           */
+          get: (key = DEFAULT_KEY, locale) => publicGet(type, key, locale),
+          /** List all PUBLISHED entries of this type. */
+          list: (locale) => publicList(type, locale),
+          /** Create a new entry in DRAFT (admin mode). */
+          create: (input) => createByType(type, input)
+        };
+      }
+      return {
+        faq: makeNamespace("FAQ"),
+        footer: makeNamespace("FOOTER"),
+        header: makeNamespace("HEADER"),
+        announcement: makeNamespace("ANNOUNCEMENT"),
+        richText: makeNamespace("RICH_TEXT"),
+        page: {
+          ...makeNamespace("PAGE"),
+          /**
+           * Fetch a PUBLISHED page by its `data.slug` (e.g. `'about'`).
+           * Returns `null` on 404. Use this from your `app/[slug]/page.tsx`
+           * catch-all route.
+           */
+          getBySlug: async (slug, locale) => {
+            const query = locale ? { locale } : void 0;
+            const path = `/content/pages/by-slug/${encodeURIComponent(slug)}`;
+            const onNotFound = (err) => {
+              if (err instanceof BrainerceError && err.statusCode === 404) return null;
+              throw err;
+            };
+            if (this.isVibeCodedMode()) {
+              return this.vibeCodedRequest("GET", path, void 0, query).catch(
+                onNotFound
+              );
+            }
+            if (this.storeId && !this.apiKey) {
+              return this.storefrontRequest("GET", path, void 0, query).catch(
+                onNotFound
+              );
+            }
+            throw new BrainerceError(
+              "content.page.getBySlug() is a public-read API; not available in admin mode.",
+              400
+            );
+          }
+        },
+        // ---------- Admin operations (cross-type) ----------
+        /** Find a single row by its admin id (admin mode). */
+        findById: async (id) => {
+          requireAdmin("findById");
+          return this.adminRequest("GET", `${adminBase()}/${encodeURIComponent(id)}`);
+        },
+        /** List rows in admin mode with optional filters. */
+        listAdmin: async (filters) => {
+          requireAdmin("listAdmin");
+          const params = new URLSearchParams();
+          if (filters?.type) params.set("type", filters.type);
+          if (filters?.status) params.set("status", filters.status);
+          const qs = params.toString();
+          return this.adminRequest(
+            "GET",
+            qs ? `${adminBase()}?${qs}` : adminBase()
+          );
+        },
+        /** Replace `data` (and optional metadata) on an existing row. */
+        update: updateById,
+        /** Transition status DRAFT → PUBLISHED. */
+        publish: publishById,
+        /** Transition status PUBLISHED → DRAFT. */
+        unpublish: unpublishById,
+        /** Hard delete the row. Admin mode only. */
+        remove: removeById
+      };
+    })();
     // -------------------- Local Cart (Client-Side for Guests) --------------------
     // These methods store cart data in localStorage - NO API calls!
     // Use for guest users in vibe-coded sites
@@ -604,6 +801,19 @@ var BrainerceClient = class {
     }
     return this.adminRequest("GET", "/api/v1/store");
   }
+  /**
+   * Resolve the script direction (`'ltr' | 'rtl'`) for a locale tag.
+   * Use this on `<html dir>` in your root layout — do not maintain a local
+   * RTL set in your storefront.
+   *
+   * @param locale - Optional BCP-47 tag. If omitted, falls back to the SDK
+   *   client's configured locale (`new BrainerceClient({ locale: 'he' })`).
+   * @returns `'rtl'` for Arabic / Hebrew / Persian / Urdu / Yiddish family,
+   *   `'ltr'` for everything else (including unknown locales).
+   */
+  getStoreDirection(locale) {
+    return getDirectionForLocale(locale ?? this.locale);
+  }
   // -------------------- Products --------------------
   /**
    * Get a list of products with pagination and filtering
@@ -717,10 +927,11 @@ var BrainerceClient = class {
    */
   async getProductBySlug(slug, options) {
     const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
+    const encodedSlug = encodeURIComponent(slug);
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "GET",
-        `/products/slug/${slug}`,
+        `/products/slug/${encodedSlug}`,
         void 0,
         void 0,
         headerOverrides
@@ -729,13 +940,13 @@ var BrainerceClient = class {
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest(
         "GET",
-        `/products/slug/${slug}`,
+        `/products/slug/${encodedSlug}`,
         void 0,
         void 0,
         headerOverrides
       );
     }
-    return this.adminRequest("GET", `/api/v1/products/by-slug/${slug}`);
+    return this.adminRequest("GET", `/api/v1/products/by-slug/${encodedSlug}`);
   }
   /**
    * Get available categories for filtering products
@@ -7080,6 +7291,26 @@ function getDescriptionContent(product) {
   }
   return { text: product.description };
 }
+function stripHtml(html) {
+  if (!html) return "";
+  return html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/&nbsp;/gi, " ").replace(/&amp;/gi, "&").replace(/&lt;/gi, "<").replace(/&gt;/gi, ">").replace(/&quot;/gi, '"').replace(/&#39;/gi, "'").replace(/&#x27;/gi, "'").replace(/&#x2F;/gi, "/").replace(/\s+/g, " ").trim();
+}
+function deriveSeoDescription(product, options) {
+  if (!product) return "";
+  const maxLength = options?.maxLength ?? 160;
+  const authored = (product.seoDescription ?? product.metaDescription ?? "").trim();
+  if (authored) return authored;
+  const plain = stripHtml(product.description);
+  if (plain) {
+    if (plain.length <= maxLength) return plain;
+    const sliceLength = maxLength - 1;
+    const slice = plain.slice(0, sliceLength);
+    const lastSpace = slice.lastIndexOf(" ");
+    const trimmed = lastSpace > maxLength * 0.5 ? slice.slice(0, lastSpace) : slice;
+    return trimmed.replace(/[\s.,;:!?-]+$/u, "") + "\u2026";
+  }
+  return product.name ?? "";
+}
 function getStockStatus(inventory, options) {
   if (!inventory) {
     return options?.outOfStockText ?? "Out of Stock";
@@ -7286,14 +7517,17 @@ function isCouponApplicableToProduct(coupon, productId) {
 export {
   BrainerceClient,
   BrainerceError,
+  RTL_LOCALES,
   SDK_VERSION,
   createWebhookHandler,
+  deriveSeoDescription,
   enableDevGuards,
   formatPrice,
   getCartItemImage,
   getCartItemName,
   getCartTotals,
   getDescriptionContent,
+  getDirectionForLocale,
   formatPrice as getPriceDisplay,
   getProductCustomizationFields,
   getProductMetafield,
@@ -7311,5 +7545,6 @@ export {
   isWebhookEventType,
   parseWebhookEvent,
   safePaymentRedirect,
+  stripHtml,
   verifyWebhook
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.25.1",
+  "version": "1.27.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",