brainerce 1.46.2 → 1.47.1

package/dist/index.js

@@ -34,6 +34,12 @@ __export(index_exports, {
   BrainerceError: () => BrainerceError,
   RTL_LOCALES: () => RTL_LOCALES,
   SDK_VERSION: () => SDK_VERSION,
+  buildArticleJsonLd: () => buildArticleJsonLd,
+  buildBreadcrumbJsonLd: () => buildBreadcrumbJsonLd,
+  buildCollectionPageJsonLd: () => buildCollectionPageJsonLd,
+  buildOrganizationJsonLd: () => buildOrganizationJsonLd,
+  buildProductJsonLd: () => buildProductJsonLd,
+  buildWebsiteJsonLd: () => buildWebsiteJsonLd,
   createWebhookHandler: () => createWebhookHandler,
   deriveSeoDescription: () => deriveSeoDescription,
   enableDevGuards: () => enableDevGuards,
@@ -41,9 +47,11 @@ __export(index_exports, {
   formatPrice: () => formatPrice,
   formatProductPrice: () => formatProductPrice,
   formatVariantPrice: () => formatVariantPrice,
+  getBlogSitemapEntries: () => getBlogSitemapEntries,
   getCartItemImage: () => getCartItemImage,
   getCartItemName: () => getCartItemName,
   getCartTotals: () => getCartTotals,
+  getCategorySitemapEntries: () => getCategorySitemapEntries,
   getDescriptionContent: () => getDescriptionContent,
   getDirectionForLocale: () => getDirectionForLocale,
   getPriceDisplay: () => formatPrice,
@@ -61,9 +69,10 @@ __export(index_exports, {
   isCouponApplicableToProduct: () => isCouponApplicableToProduct,
   isHtmlDescription: () => isHtmlDescription,
   isWebhookEventType: () => isWebhookEventType,
+  jsonLdScriptProps: () => jsonLdScriptProps,
   parseWebhookEvent: () => parseWebhookEvent,
   safePaymentRedirect: () => safePaymentRedirect,
-  stripHtml: () => stripHtml,
+  stripHtml: () => stripHtml2,
   verifyWebhook: () => verifyWebhook
 });
 module.exports = __toCommonJS(index_exports);
@@ -1314,6 +1323,34 @@ var BrainerceClient = class {
     }
     throw new BrainerceError("getCategories is only available in vibe-coded mode", 400);
   }
+  /**
+   * Get one category by slug — the payload for a storefront category
+   * (collection) landing page: name, description HTML, meta, breadcrumb and
+   * product count. Fetch the products themselves with
+   * `getProducts({ categories: [category.id] })`. Vibe-coded mode only, like
+   * {@link getCategories}.
+   *
+   * @example
+   * ```typescript
+   * const category = await client.getCategoryBySlug('running-shoes').catch(() => null);
+   * if (!category) notFound();
+   * const { data: products } = await client.getProducts({ categories: [category.id] });
+   * ```
+   */
+  async getCategoryBySlug(slug, options) {
+    const headerOverrides = options?.locale ? { "Accept-Language": options.locale } : void 0;
+    const encodedSlug = encodePathSegment(slug);
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "GET",
+        `/categories/slug/${encodedSlug}`,
+        void 0,
+        void 0,
+        headerOverrides
+      );
+    }
+    throw new BrainerceError("getCategoryBySlug is only available in vibe-coded mode", 400);
+  }
   /**
    * Get available brands for filtering products
    * Works in vibe-coded mode
@@ -6466,15 +6503,18 @@ var BrainerceClient = class {
   // these do NOT branch on isVibeCodedMode() (that would 404 silently).
   /**
    * Get the logged-in customer's loyalty status: enrollment, points balance,
-   * lifetime earned, and the program's display config (requires customerToken).
-   * Only available in storefront mode. `program` is null when the store has no
-   * loyalty program.
+   * lifetime earned, the program's display config, earned milestone `badges`,
+   * and the `paidMembership` subscription state (null for free members).
+   * Requires customerToken. Only available in storefront mode. `program` is
+   * null when the store has no loyalty program.
    *
    * @example
    * ```typescript
    * client.setCustomerToken(auth.token);
    * const status = await client.getLoyaltyStatus();
    * if (status.enrolled) console.log(`${status.pointsBalance} ${status.program?.pointsName}`);
+   * status.badges?.forEach((b) => console.log(`🏅 ${b.name}`));
+   * if (status.paidMembership?.status === 'ACTIVE') showPremiumPerks(status.paidMembership.plan);
    * ```
    */
   async getLoyaltyStatus() {
@@ -6607,6 +6647,144 @@ var BrainerceClient = class {
     }
     throw new BrainerceError("getReferralInfo is only available in storefront mode", 400);
   }
+  /**
+   * AI-recommended reward for the logged-in customer — "recommended for you"
+   * at the top of the rewards list (requires customerToken). The result is
+   * ALWAYS a real reward from the store's catalog (the AI only ranks; a
+   * hallucinated pick falls back to a deterministic choice). Returns
+   * `{ reward: null }` when the catalog is empty. Rate-limited (5/min per
+   * customer — it spends the merchant's AI credits). Only available in
+   * storefront mode.
+   *
+   * @example
+   * ```typescript
+   * const { reward, reason } = await client.getRecommendedReward();
+   * if (reward) showRecommendation(reward, reason);
+   * ```
+   */
+  async getRecommendedReward() {
+    if (!this.customerToken && !this.proxyMode) {
+      throw new BrainerceError(
+        "Customer token required. Call setCustomerToken() after login.",
+        401
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "GET",
+        "/loyalty/rewards/recommended"
+      );
+    }
+    throw new BrainerceError("getRecommendedReward is only available in storefront mode", 400);
+  }
+  /**
+   * List the paid membership plans the customer can subscribe to (requires
+   * customerToken). Empty when the store offers none or the program is not
+   * active. Only available in storefront mode.
+   *
+   * @example
+   * ```typescript
+   * const plans = await client.getMembershipPlans();
+   * ```
+   */
+  async getMembershipPlans() {
+    if (!this.customerToken && !this.proxyMode) {
+      throw new BrainerceError(
+        "Customer token required. Call setCustomerToken() after login.",
+        401
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", "/loyalty/membership/plans");
+    }
+    throw new BrainerceError("getMembershipPlans is only available in storefront mode", 400);
+  }
+  /**
+   * List the customer's saved payment methods (display fields only — brand /
+   * last4 / expiry, never card data) for the membership subscribe flow.
+   * Requires customerToken. Cards are vaulted by checking out with
+   * `saveCard: true`. Only available in storefront mode.
+   *
+   * @example
+   * ```typescript
+   * const methods = await client.getMySavedPaymentMethods();
+   * ```
+   */
+  async getMySavedPaymentMethods() {
+    if (!this.customerToken && !this.proxyMode) {
+      throw new BrainerceError(
+        "Customer token required. Call setCustomerToken() after login.",
+        401
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "GET",
+        "/loyalty/membership/payment-methods"
+      );
+    }
+    throw new BrainerceError(
+      "getMySavedPaymentMethods is only available in storefront mode",
+      400
+    );
+  }
+  /**
+   * Subscribe the customer to a paid membership plan — charges the saved card
+   * IMMEDIATELY and starts the recurring cycle (requires customerToken).
+   * Throws a 409 with a `code` ('card_declined' | 'requires_action' | ...)
+   * when the charge fails; 3D-Secure challenges are not supported off-session
+   * and surface as `requires_action`. Only available in storefront mode.
+   *
+   * @example
+   * ```typescript
+   * const membership = await client.subscribeToMembership({
+   *   planId: plan.id,
+   *   savedPaymentTokenId: method.id,
+   * });
+   * // membership.status === 'ACTIVE'
+   * ```
+   */
+  async subscribeToMembership(params) {
+    if (!this.customerToken && !this.proxyMode) {
+      throw new BrainerceError(
+        "Customer token required. Call setCustomerToken() after login.",
+        401
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "POST",
+        "/loyalty/membership/subscribe",
+        params
+      );
+    }
+    throw new BrainerceError("subscribeToMembership is only available in storefront mode", 400);
+  }
+  /**
+   * Cancel the customer's paid membership (requires customerToken).
+   * End-of-period semantics: perks continue until `nextBillingAt`, then the
+   * subscription ends without another charge (a PAST_DUE membership cancels
+   * immediately). Re-subscribing to the same plan before period end simply
+   * un-cancels. Only available in storefront mode.
+   *
+   * @example
+   * ```typescript
+   * const membership = await client.cancelMembership();
+   * // membership.cancelAtPeriodEnd === true
+   * ```
+   */
+  async cancelMembership() {
+    if (!this.customerToken && !this.proxyMode) {
+      throw new BrainerceError(
+        "Customer token required. Call setCustomerToken() after login.",
+        401
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("POST", "/loyalty/membership/cancel");
+    }
+    throw new BrainerceError("cancelMembership is only available in storefront mode", 400);
+  }
   /**
    * Get the current customer's orders (requires customerToken)
    * Works in vibe-coded and storefront modes
@@ -8892,6 +9070,212 @@ function formatAmount(amount, currency, locale) {
   }
 }
 
+// src/jsonld.ts
+function absoluteUrl(siteUrl, path) {
+  if (!path) return void 0;
+  const base = siteUrl.replace(/\/+$/, "");
+  return path.startsWith("http") ? path : `${base}${path.startsWith("/") ? path : `/${path}`}`;
+}
+function stripHtml(html) {
+  return (html ?? "").replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+}
+function buildArticleJsonLd(post, opts) {
+  const url = absoluteUrl(opts.siteUrl, opts.path ?? `/blog/${post.slug}`);
+  const result = {
+    "@context": "https://schema.org",
+    "@type": "Article",
+    headline: post.seoTitle ?? post.title,
+    name: post.title,
+    ...post.excerpt || post.seoDescription ? { description: post.seoDescription ?? post.excerpt } : {},
+    ...url ? { url, mainEntityOfPage: { "@type": "WebPage", "@id": url } } : {},
+    ...post.coverImageUrl ? { image: [post.coverImageUrl] } : {},
+    ...post.publishedAt ? { datePublished: post.publishedAt } : {},
+    dateModified: post.updatedAt,
+    ...post.author ? { author: { "@type": "Person", name: post.author } } : opts.organizationName ? { author: { "@type": "Organization", name: opts.organizationName } } : {},
+    ...opts.organizationName ? { publisher: { "@type": "Organization", name: opts.organizationName } } : {},
+    ...post.tags.length > 0 ? { keywords: post.tags.join(", ") } : {}
+  };
+  return result;
+}
+function buildProductJsonLd(product, opts) {
+  const url = absoluteUrl(opts.siteUrl, opts.path ?? (product.slug ? `/products/${product.slug}` : void 0));
+  const images = (product.images ?? []).map((img) => img.url).filter(Boolean);
+  const brand = opts.brandName ?? product.brands?.[0]?.name;
+  const description = stripHtml(product.description).slice(0, 5e3);
+  const effectivePrice = product.salePrice ?? product.basePrice;
+  const inStock = product.inventory ? (product.inventory.available ?? 0) > 0 : true;
+  const isVariable = product.type === "VARIABLE" && product.priceMin && product.priceMax;
+  const offer = isVariable ? {
+    "@type": "AggregateOffer",
+    lowPrice: product.priceMin,
+    highPrice: product.priceMax,
+    priceCurrency: opts.currency,
+    availability: inStock ? "https://schema.org/InStock" : "https://schema.org/OutOfStock",
+    ...url ? { url } : {}
+  } : {
+    "@type": "Offer",
+    price: effectivePrice,
+    priceCurrency: opts.currency,
+    availability: inStock ? "https://schema.org/InStock" : "https://schema.org/OutOfStock",
+    ...url ? { url } : {}
+  };
+  return {
+    "@context": "https://schema.org",
+    "@type": "Product",
+    name: product.name,
+    ...description ? { description } : {},
+    ...images.length > 0 ? { image: images } : {},
+    ...url ? { url } : {},
+    sku: product.sku,
+    // Identifiers Google uses to match a product to its catalog — key for
+    // free merchant-listing eligibility without a Merchant Center feed.
+    ...product.gtin ? { gtin: product.gtin } : {},
+    ...product.mpn ? { mpn: product.mpn } : {},
+    ...brand ? { brand: { "@type": "Brand", name: brand } } : {},
+    offers: offer,
+    // Google policy: never emit an empty/zero rating block.
+    ...product.reviewCount && product.reviewCount > 0 && product.avgRating ? {
+      aggregateRating: {
+        "@type": "AggregateRating",
+        ratingValue: product.avgRating,
+        reviewCount: product.reviewCount
+      }
+    } : {}
+  };
+}
+function buildOrganizationJsonLd(store, opts) {
+  const sameAs = Object.values(store.socialLinks ?? {}).filter(Boolean);
+  return {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    name: store.name,
+    url: opts.siteUrl,
+    ...store.logo ? { logo: store.logo } : {},
+    ...store.metaDescription ? { description: store.metaDescription } : {},
+    ...store.contactEmail ? { email: store.contactEmail } : {},
+    ...store.contactPhone ? { telephone: store.contactPhone } : {},
+    ...sameAs.length > 0 ? { sameAs } : {}
+  };
+}
+function buildWebsiteJsonLd(store, opts) {
+  const base = opts.siteUrl.replace(/\/+$/, "");
+  const result = {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    name: store.name,
+    url: opts.siteUrl
+  };
+  if (opts.searchUrlTemplate?.includes("{search_term_string}")) {
+    const tmpl = opts.searchUrlTemplate.startsWith("http") ? opts.searchUrlTemplate : `${base}${opts.searchUrlTemplate.startsWith("/") ? "" : "/"}${opts.searchUrlTemplate}`;
+    result.potentialAction = {
+      "@type": "SearchAction",
+      target: { "@type": "EntryPoint", urlTemplate: tmpl },
+      "query-input": "required name=search_term_string"
+    };
+  }
+  return result;
+}
+function buildCollectionPageJsonLd(category, opts) {
+  const url = absoluteUrl(opts.siteUrl, opts.path);
+  const description = category.metaDescription ?? (stripHtml(category.description) || void 0);
+  return {
+    "@context": "https://schema.org",
+    "@type": "CollectionPage",
+    name: category.name,
+    ...description ? { description } : {},
+    ...url ? { url, mainEntityOfPage: { "@type": "WebPage", "@id": url } } : {},
+    ...category.image ? { image: [category.image] } : {}
+  };
+}
+function buildBreadcrumbJsonLd(items) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: items.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: item.name,
+      item: item.url
+    }))
+  };
+}
+function jsonLdScriptProps(data) {
+  return {
+    type: "application/ld+json",
+    dangerouslySetInnerHTML: { __html: JSON.stringify(data).replace(/</g, "\\u003c") }
+  };
+}
+
+// src/sitemap.ts
+async function getBlogSitemapEntries(client, opts) {
+  const base = opts.siteUrl.replace(/\/+$/, "");
+  const basePath = opts.basePath ?? "/blog";
+  const pageSize = Math.min(opts.pageSize ?? 100, 100);
+  const maxEntries = opts.maxEntries ?? 5e3;
+  const posts = [];
+  let page = 1;
+  for (; ; ) {
+    const res = await client.blog.getPosts({ page, limit: pageSize });
+    posts.push(...res.data.map((p) => ({ slug: p.slug, updatedAt: p.updatedAt })));
+    if (page >= res.meta.totalPages || posts.length >= maxEntries) break;
+    page += 1;
+  }
+  const nonDefaultLocales = opts.locales?.filter((locale) => locale !== opts.defaultLocale) ?? [];
+  const entries = [];
+  entries.push({ url: `${base}${basePath}`, changeFrequency: "daily", priority: 0.7 });
+  for (const locale of nonDefaultLocales) {
+    entries.push({
+      url: `${base}/${locale}${basePath}`,
+      changeFrequency: "daily",
+      priority: 0.7
+    });
+  }
+  for (const post of posts.slice(0, maxEntries)) {
+    const lastModified = new Date(post.updatedAt);
+    entries.push({
+      url: `${base}${basePath}/${post.slug}`,
+      lastModified,
+      changeFrequency: "weekly",
+      priority: 0.6
+    });
+    for (const locale of nonDefaultLocales) {
+      entries.push({
+        url: `${base}/${locale}${basePath}/${post.slug}`,
+        lastModified,
+        changeFrequency: "weekly",
+        priority: 0.5
+      });
+    }
+  }
+  return entries;
+}
+async function getCategorySitemapEntries(client, opts) {
+  const base = opts.siteUrl.replace(/\/+$/, "");
+  const basePath = opts.basePath ?? "/category";
+  const nonDefaultLocales = opts.locales?.filter((l) => l !== opts.defaultLocale) ?? [];
+  const { categories } = await client.getCategories();
+  const slugs = [];
+  const walk = (nodes) => {
+    for (const node of nodes) {
+      if (node.slug) slugs.push(node.slug);
+      if (node.children?.length) walk(node.children);
+    }
+  };
+  walk(categories);
+  const entries = [];
+  for (const slug of slugs) {
+    entries.push({ url: `${base}${basePath}/${slug}`, changeFrequency: "daily", priority: 0.8 });
+    for (const locale of nonDefaultLocales) {
+      entries.push({
+        url: `${base}/${locale}${basePath}/${slug}`,
+        changeFrequency: "daily",
+        priority: 0.7
+      });
+    }
+  }
+  return entries;
+}
+
 // src/types.ts
 function isHtmlDescription(product) {
   if (product?.descriptionFormat === "html") return true;
@@ -8907,7 +9291,7 @@ function getDescriptionContent(product) {
   }
   return { text: product.description };
 }
-function stripHtml(html) {
+function stripHtml2(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();
 }
@@ -8916,7 +9300,7 @@ function deriveSeoDescription(product, options) {
   const maxLength = options?.maxLength ?? 160;
   const authored = (product.seoDescription ?? product.metaDescription ?? "").trim();
   if (authored) return authored;
-  const plain = stripHtml(product.description);
+  const plain = stripHtml2(product.description);
   if (plain) {
     if (plain.length <= maxLength) return plain;
     const sliceLength = maxLength - 1;
@@ -9138,6 +9522,12 @@ function isCouponApplicableToProduct(coupon, productId) {
   BrainerceError,
   RTL_LOCALES,
   SDK_VERSION,
+  buildArticleJsonLd,
+  buildBreadcrumbJsonLd,
+  buildCollectionPageJsonLd,
+  buildOrganizationJsonLd,
+  buildProductJsonLd,
+  buildWebsiteJsonLd,
   createWebhookHandler,
   deriveSeoDescription,
   enableDevGuards,
@@ -9145,9 +9535,11 @@ function isCouponApplicableToProduct(coupon, productId) {
   formatPrice,
   formatProductPrice,
   formatVariantPrice,
+  getBlogSitemapEntries,
   getCartItemImage,
   getCartItemName,
   getCartTotals,
+  getCategorySitemapEntries,
   getDescriptionContent,
   getDirectionForLocale,
   getPriceDisplay,
@@ -9165,6 +9557,7 @@ function isCouponApplicableToProduct(coupon, productId) {
   isCouponApplicableToProduct,
   isHtmlDescription,
   isWebhookEventType,
+  jsonLdScriptProps,
   parseWebhookEvent,
   safePaymentRedirect,
   stripHtml,