From 7f5885589217c36d56e061573597c2ebe06660e3 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Wed, 31 Dec 2025 15:26:15 -0500 Subject: [PATCH 1/5] initial commit with reviews and newsletter update --- .../catalyst/release-notes/1-4-0.mdx | 252 ++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 docs/storefront/catalyst/release-notes/1-4-0.mdx diff --git a/docs/storefront/catalyst/release-notes/1-4-0.mdx b/docs/storefront/catalyst/release-notes/1-4-0.mdx new file mode 100644 index 000000000..6416387dc --- /dev/null +++ b/docs/storefront/catalyst/release-notes/1-4-0.mdx @@ -0,0 +1,252 @@ +# Catalyst version 1.4.0 Release Notes + +We are excited to announce the release of Catalyst v1.4.0, which brings new features including product reviews, newsletter subscriptions, and additional improvements. + +## Product reviews + +Catalyst now supports end-to-end product reviews on the storefront, powered by the Storefront GraphQL API. + +This release includes: + +- New Storefront GraphQL settings for reviews +- Native review submission UI on the product detail page (PDP) +- Behavior that matches Cornerstone 1-to-1 for: + - Whether reviews are enabled + - Whether product ratings are shown + + + There is one difference between Cornerstone and Catalyst due to pre-existing + functionality in the `addProductReview` mutation. When the setting + `onlyAcceptPreviousCustomerReviews` is `false`, email is still a required + field when submitting a product review via GraphQL. + + +### Storefront GraphQL settings + +The Storefront GraphQL API now exposes review-related settings under the site settings object. You can query: + +1. **Whether reviews are globally enabled for the store** + + - Used in Catalyst as `reviewsEnabled` + - When `false`, Catalyst hides: + - The reviews section on PDP + - The review submission UI + - Rating stars on PDP/PLP + +2. **Whether product ratings should be displayed on the storefront** + + - Backed by `site.settings.display.showProductRating` + - Ratings only render when: + - Reviews are enabled **and** + - `showProductRating` is `true` + - When disabled, review submission can still be available, but rating stars are hidden + +3. **Whether review submissions are restricted to previous purchasers** + - Reflects the "Only allow reviews from previous customers" store setting + - When enabled, the Storefront GraphQL API only accepts reviews where the submitted email matches at least one past order for that product + - Catalyst surfaces GraphQL error messages when this validation fails + + + Use this query in your own custom components if you need to make review-aware + UI decisions outside the built-in sections. + + +```gql +query SiteReviewSettings { + site { + settings { + reviews { + enabled + onlyAcceptPreviousCustomerReviews + } + display { + showProductRating + } + } + } +} +``` + +### Storefront behavior + +#### Rating display (PDP, PLP, search, category, brand) + +All product-listing UIs now respect the same review settings as Stencil: + +**When reviews are enabled and `showProductRating` is `true`:** + +- Product cards on search/category/brand pages show star ratings when `rating > 0` +- PDP header shows the product rating +- PDP reviews section is visible (including the review form) + +**When reviews are disabled:** + +- No ratings are shown on PLP or PDP +- PDP reviews section (including submission UI) is hidden +- GraphQL queries still succeed; Catalyst simply does not render review UI + +**Note:** Products with no reviews (`rating` is `0` or `null`) never show rating stars, even when ratings are enabled. This prevents non-reviewed products from appearing as if they have a "0" rating. + +#### Review submission UI + +On the PDP, customers can submit reviews via a dedicated modal form: + +**"Write a review" button:** + +- Appears in the reviews section when reviews exist +- Appears in the reviews empty state +- Implemented via `ProductReviewButton` + +**Review form fields:** + +- Rating +- Title +- Review text +- Name +- Email + +**Form behavior:** + +- Performs client-side validation on required fields +- Calls BigCommerce's Storefront GraphQL API to create the review +- Shows inline error messages for validation and GraphQL errors +- Shows a success toast and closes the modal after a successful submission + +**Note:** The default implementation does **not** include reCAPTCHA. Add custom protection if your storefront requires it. + +#### Logged-in vs guest customers + +**Logged-in customers:** + +- Name and email are read from the auth JWT +- The form is pre-filled with these values to maximize the chance of matching past orders for "verified purchaser only" stores + +**Guest customers:** + +- Name and email are always required +- When "only allow reviews from previous customers" is enabled, the Storefront GraphQL API rejects submissions where the email does not match an order +- Catalyst displays the resulting error message + +## Newsletter Subscriptions + +This release introduces a fully functional, end-to-end newsletter subscription experience in Catalyst, integrated with the BigCommerce Storefront GraphQL API. + +This release enables: + +- Store-controlled visibility of newsletter signup UI +- Real customer subscription via GraphQL mutations +- Customer self-management of newsletter preferences from account settings + +### Features + +1. **Homepage newsletter signup is settings-driven** + + - The homepage `Subscribe` component now renders conditionally based on store configuration + - Visibility is controlled by the Storefront GraphQL field: `site.settings.newsletter.showNewsletterSignup` + - Uses the `Stream` / `Streamable` pattern for progressive loading + - **Result:** + - Stores with newsletter signup disabled will not render the section + - Stores with signup enabled see the newsletter section as before, now controlled by settings + +2. **Newsletter subscription is fully functional** + + - Replaced the mock newsletter subscription with a real Storefront GraphQL mutation: `SubscribeToNewsletterMutation` + - Added comprehensive error handling: + - Invalid email address + - Already subscribed + - Unexpected server errors + - Improved error rendering in `InlineEmailForm` so server-side errors are properly displayed + - Added E2E tests covering the subscription flow + - **User-facing behavior:** + - Success message on subscription + - Clear error messages for common failure cases + +3. **Account settings newsletter toggle** + + - Adds a "Marketing preferences" section to `/account/settings` + - Introduces a toggle allowing customers to: + - Subscribe to newsletters + - Unsubscribe from newsletters + - Uses a new server action: `updateNewsletterSubscription` + - UI is shown only when newsletter signup is enabled at the store level + - **Key characteristics:** + - Toggle state reflects `customer.isSubscribedToNewsletter` + - Submitting updates calls Storefront GraphQL to subscribe or unsubscribe + - Includes E2E tests and translations + +### Storefront GraphQL settings + +This feature relies on Storefront GraphQL for both configuration and customer subscription state. + +#### Fields added + +**`site.settings.newsletter.showNewsletterSignup`** + +- **Type:** `Boolean` +- **Purpose:** Controls whether newsletter subscription UI is displayed in the storefront +- **Used by:** + - Homepage newsletter signup section + - Account settings "Marketing preferences" section + +**`customer.isSubscribedToNewsletter`** + +- **Type:** `Boolean` +- **Purpose:** Indicates whether the authenticated customer is currently subscribed +- **Used by:** + - Account settings toggle initial state + - Determining subscribe vs unsubscribe behavior + +#### GraphQL query example + +```gql +query NewsletterSettingsAndCustomerStatus { + site { + settings { + newsletter { + showNewsletterSignup + } + } + } + customer { + isSubscribedToNewsletter + } +} +``` + + + The `customer` field requires an authenticated shopper context. For homepage + gating only, querying `site.settings.newsletter.showNewsletterSignup` is + sufficient. + + +### Storefront behavior + +#### Homepage newsletter signup section + +- The newsletter signup section no longer renders unconditionally +- Rendering is controlled by `showNewsletterSignup` +- **UX impact:** + - No visual placeholder or empty state when disabled + - When enabled, the section loads progressively and behaves as expected + +#### Newsletter signup subscription flow + +- Email submissions call BigCommerce Storefront GraphQL +- Errors returned from the API are surfaced directly in the UI +- **User-visible outcomes:** + - Success confirmation on subscription + - Friendly error messages for: + - Invalid email + - Already subscribed + - General failures + +#### Account settings: Marketing preferences + +- Customers can manage newsletter preferences directly from `/account/settings` +- Toggle reflects real subscription state +- Submitting changes updates BigCommerce via GraphQL +- **Display rules:** + - Section only appears when `showNewsletterSignup` is enabled +- **UX impact:** + - Customers can opt in or out without re-entering email + - Aligns newsletter management with other account preferences From 040fe6fe1e27389e756a26bf15cccffce215bbc4 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Wed, 31 Dec 2025 15:44:30 -0500 Subject: [PATCH 2/5] added release tags and placeholder for migration guide --- docs/storefront/catalyst/release-notes/1-4-0.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/storefront/catalyst/release-notes/1-4-0.mdx b/docs/storefront/catalyst/release-notes/1-4-0.mdx index 6416387dc..4fc4f7929 100644 --- a/docs/storefront/catalyst/release-notes/1-4-0.mdx +++ b/docs/storefront/catalyst/release-notes/1-4-0.mdx @@ -250,3 +250,17 @@ query NewsletterSettingsAndCustomerStatus { - **UX impact:** - Customers can opt in or out without re-entering email - Aligns newsletter management with other account preferences + +## Migration Guide + +## Release Tags + +We have published new tags for the Core and Makeswift versions of Catalyst. Target these tags to pull the latest code: + +- [**@bigcommerce/catalyst-core@1.4.0**](https://github.com/bigcommerce/catalyst/releases/tag/%40bigcommerce%2Fcatalyst-core%401.4.0) +- [**@bigcommerce/catalyst-makeswift@1.4.0**](https://github.com/bigcommerce/catalyst/releases/tag/%40bigcommerce%2Fcatalyst-makeswift%401.4.0) + +And as always, you can pull the latest stable release with these tags: + +- [**@bigcommerce/catalyst-core@latest**](https://github.com/bigcommerce/catalyst/releases/tag/%40bigcommerce%2Fcatalyst-core%40latest) +- [**@bigcommerce/catalyst-makeswift@latest**](https://github.com/bigcommerce/catalyst/releases/tag/%40bigcommerce%2Fcatalyst-makeswift%40latest) From a2e58c168751a50226ae600de7987985ee3d4fcd Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Wed, 31 Dec 2025 16:29:46 -0500 Subject: [PATCH 3/5] add limitations to newsletter --- docs/storefront/catalyst/release-notes/1-4-0.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/storefront/catalyst/release-notes/1-4-0.mdx b/docs/storefront/catalyst/release-notes/1-4-0.mdx index 4fc4f7929..55138a38a 100644 --- a/docs/storefront/catalyst/release-notes/1-4-0.mdx +++ b/docs/storefront/catalyst/release-notes/1-4-0.mdx @@ -251,6 +251,18 @@ query NewsletterSettingsAndCustomerStatus { - Customers can opt in or out without re-entering email - Aligns newsletter management with other account preferences +### Limitations + +This release does not include support for the following newsletter-related features: + +**Support for Require Consent** + +The Require Consent toggle in the store's Miscellaneous settings, which overrides the Newsletter Checkbox when enabled and allows customers to opt in to receive abandoned cart emails and other marketing emails, is not supported in this release. + +**Support for Newsletter Summary** + +The [Show Newsletter Summary](https://support.bigcommerce.com/s/article/Collecting-Newsletter-Subscriptions?language=en_US#newsletter-settings) field is not supported. + ## Migration Guide ## Release Tags From 8133ed3b239707a9c24a59581906f7eb87e3d995 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Mon, 5 Jan 2026 15:25:58 -0500 Subject: [PATCH 4/5] updated intro and product reviews section --- .../catalyst/release-notes/1-4-0.mdx | 141 ++++-------------- 1 file changed, 25 insertions(+), 116 deletions(-) diff --git a/docs/storefront/catalyst/release-notes/1-4-0.mdx b/docs/storefront/catalyst/release-notes/1-4-0.mdx index 55138a38a..83f30c2fd 100644 --- a/docs/storefront/catalyst/release-notes/1-4-0.mdx +++ b/docs/storefront/catalyst/release-notes/1-4-0.mdx @@ -1,131 +1,40 @@ # Catalyst version 1.4.0 Release Notes -We are excited to announce the release of Catalyst v1.4.0, which brings new features including product reviews, newsletter subscriptions, and additional improvements. +We are excited to announce the release of Catalyst v1.4.0, which brings a few additional improvements as well as new features including: -## Product reviews +* [Product reviews](#product-reviews) +* Newsletter subscriptions +* Open telemetry +* Backorders -Catalyst now supports end-to-end product reviews on the storefront, powered by the Storefront GraphQL API. +## Product Reviews -This release includes: +Catalyst now supports end-to-end product reviews on the storefront, integrated with the Storefront GraphQL API. This release enables: -- New Storefront GraphQL settings for reviews -- Native review submission UI on the product detail page (PDP) -- Behavior that matches Cornerstone 1-to-1 for: - - Whether reviews are enabled - - Whether product ratings are shown +* New Storefront GraphQL setting for enabling reviews (`site.settings.reviews.enabled)` +* New Storefront GraphQL setting for displaying product ratings (`site.settings.display.showProductRating)` +* New Storefront GraphQL setting for only accepting reviews from customers that have purchased the product (`site.settings.display.onlyAcceptPreviousCustomerReviews)` +* Native review submission UI on the product detail page (PDP) - - There is one difference between Cornerstone and Catalyst due to pre-existing - functionality in the `addProductReview` mutation. When the setting - `onlyAcceptPreviousCustomerReviews` is `false`, email is still a required - field when submitting a product review via GraphQL. - - -### Storefront GraphQL settings - -The Storefront GraphQL API now exposes review-related settings under the site settings object. You can query: - -1. **Whether reviews are globally enabled for the store** +Here is an example GraphQL query for the settings related to reviews.. - - Used in Catalyst as `reviewsEnabled` - - When `false`, Catalyst hides: - - The reviews section on PDP - - The review submission UI - - Rating stars on PDP/PLP - -2. **Whether product ratings should be displayed on the storefront** - - - Backed by `site.settings.display.showProductRating` - - Ratings only render when: - - Reviews are enabled **and** - - `showProductRating` is `true` - - When disabled, review submission can still be available, but rating stars are hidden - -3. **Whether review submissions are restricted to previous purchasers** - - Reflects the "Only allow reviews from previous customers" store setting - - When enabled, the Storefront GraphQL API only accepts reviews where the submitted email matches at least one past order for that product - - Catalyst surfaces GraphQL error messages when this validation fails - - - Use this query in your own custom components if you need to make review-aware - UI decisions outside the built-in sections. - - -```gql +```graphql query SiteReviewSettings { - site { - settings { - reviews { - enabled - onlyAcceptPreviousCustomerReviews - } - display { - showProductRating - } - } - } + site { + settings { + reviews { + enabled + onlyAcceptPreviousCustomerReviews + } + display { + showProductRating + } + } + } } ``` -### Storefront behavior - -#### Rating display (PDP, PLP, search, category, brand) - -All product-listing UIs now respect the same review settings as Stencil: - -**When reviews are enabled and `showProductRating` is `true`:** - -- Product cards on search/category/brand pages show star ratings when `rating > 0` -- PDP header shows the product rating -- PDP reviews section is visible (including the review form) - -**When reviews are disabled:** - -- No ratings are shown on PLP or PDP -- PDP reviews section (including submission UI) is hidden -- GraphQL queries still succeed; Catalyst simply does not render review UI - -**Note:** Products with no reviews (`rating` is `0` or `null`) never show rating stars, even when ratings are enabled. This prevents non-reviewed products from appearing as if they have a "0" rating. - -#### Review submission UI - -On the PDP, customers can submit reviews via a dedicated modal form: - -**"Write a review" button:** - -- Appears in the reviews section when reviews exist -- Appears in the reviews empty state -- Implemented via `ProductReviewButton` - -**Review form fields:** - -- Rating -- Title -- Review text -- Name -- Email - -**Form behavior:** - -- Performs client-side validation on required fields -- Calls BigCommerce's Storefront GraphQL API to create the review -- Shows inline error messages for validation and GraphQL errors -- Shows a success toast and closes the modal after a successful submission - -**Note:** The default implementation does **not** include reCAPTCHA. Add custom protection if your storefront requires it. - -#### Logged-in vs guest customers - -**Logged-in customers:** - -- Name and email are read from the auth JWT -- The form is pre-filled with these values to maximize the chance of matching past orders for "verified purchaser only" stores - -**Guest customers:** - -- Name and email are always required -- When "only allow reviews from previous customers" is enabled, the Storefront GraphQL API rejects submissions where the email does not match an order -- Catalyst displays the resulting error message +For more information on managing reviews in the Control Panel, refer to the [Managing Reviews documentation](https://support.bigcommerce.com/s/article/Managing-Reviews?language=en_US). ## Newsletter Subscriptions From 92cf20fb1503db17203ec3ecdcf5151cb50bb637 Mon Sep 17 00:00:00 2001 From: jamesqquick Date: Tue, 6 Jan 2026 13:52:27 -0600 Subject: [PATCH 5/5] refactored and streamlined release notes as well as added bug fix, consent management, and opentelemetry sections --- .../catalyst/release-notes/1-4-0.mdx | 302 +++++++++++------- 1 file changed, 192 insertions(+), 110 deletions(-) diff --git a/docs/storefront/catalyst/release-notes/1-4-0.mdx b/docs/storefront/catalyst/release-notes/1-4-0.mdx index 83f30c2fd..2e3f8d3b5 100644 --- a/docs/storefront/catalyst/release-notes/1-4-0.mdx +++ b/docs/storefront/catalyst/release-notes/1-4-0.mdx @@ -1,24 +1,23 @@ # Catalyst version 1.4.0 Release Notes -We are excited to announce the release of Catalyst v1.4.0, which brings a few additional improvements as well as new features including: +We are excited to announce the release of Catalyst v1.4.0, which brings product reviews, newsletter subscriptions, and more. -* [Product reviews](#product-reviews) -* Newsletter subscriptions -* Open telemetry -* Backorders +For additional details, you can refer to the [Catalyst 1.4 changeset](https://github.com/bigcommerce/catalyst/releases/tag/%40bigcommerce%2Fcatalyst-core%401.4.0). -## Product Reviews +## Product reviews -Catalyst now supports end-to-end product reviews on the storefront, integrated with the Storefront GraphQL API. This release enables: +Catalyst now supports end-to-end product reviews on the storefront, integrated with the Storefront GraphQL API. This release includes: * New Storefront GraphQL setting for enabling reviews (`site.settings.reviews.enabled)` * New Storefront GraphQL setting for displaying product ratings (`site.settings.display.showProductRating)` * New Storefront GraphQL setting for only accepting reviews from customers that have purchased the product (`site.settings.display.onlyAcceptPreviousCustomerReviews)` * Native review submission UI on the product detail page (PDP) -Here is an example GraphQL query for the settings related to reviews.. +### Sample Storefront GraphQL Query -```graphql +Here is an example Storefront GraphQL query for the settings related to product reviews. + +``` query SiteReviewSettings { site { settings { @@ -36,143 +35,226 @@ query SiteReviewSettings { For more information on managing reviews in the Control Panel, refer to the [Managing Reviews documentation](https://support.bigcommerce.com/s/article/Managing-Reviews?language=en_US). -## Newsletter Subscriptions +## Newsletter subscriptions -This release introduces a fully functional, end-to-end newsletter subscription experience in Catalyst, integrated with the BigCommerce Storefront GraphQL API. +Catalyst now supports an end-to-end newsletter subscription experience, integrated with the BigCommerce Storefront GraphQL API. This includes: -This release enables: +* Fully-functioning newsletter subscription UI on the home page that includes success confirmation and error handling +* **Marketing preferences** section in the account settings page for managing newsletter preferences +* New Storefront GraphQL setting for controlling visibility of the signup UI (`site.settings.newsletter.showNewsletterSignup)`on the home page and account settings page +* New Storefront GraphQL setting for determining if a user is already subscribed (`site.customer.isSubscribedToNewsletter`) +* New Storefront GraphQL [newsletter mutations](https://developer.bigcommerce.com/graphql-storefront/reference#definition-NewsletterMutations) for subscribing and unsubscribing +* E2E tests -- Store-controlled visibility of newsletter signup UI -- Real customer subscription via GraphQL mutations -- Customer self-management of newsletter preferences from account settings +### Sample Storefront GraphQL Query -### Features +Here is a sample Storefront GraphQL query that queries the new settings related to newsletter subscriptions. + +``` +query NewsletterSettingsAndCustomerStatus { + site { + settings { + newsletter { + showNewsletterSignup + } + } + } + customer { + isSubscribedToNewsletter + } +} +``` -1. **Homepage newsletter signup is settings-driven** +For more information on newsletter settings in the Control Panel, refer to the [Newsletter and Email Marketing Settings documentation](https://support.bigcommerce.com/s/article/Collecting-Newsletter-Subscriptions?language=en_US). - - The homepage `Subscribe` component now renders conditionally based on store configuration - - Visibility is controlled by the Storefront GraphQL field: `site.settings.newsletter.showNewsletterSignup` - - Uses the `Stream` / `Streamable` pattern for progressive loading - - **Result:** - - Stores with newsletter signup disabled will not render the section - - Stores with signup enabled see the newsletter section as before, now controlled by settings +### What’s not included -2. **Newsletter subscription is fully functional** +The Require Consent toggle in the store’s [Miscellaneous settings](https://support.bigcommerce.com/s/article/Using-the-Abandoned-Cart-Saver?language=en_US#notifications), which overrides the Newsletter Checkbox when enabled and allows customers to opt in to receive abandoned cart emails and other marketing emails, was not implemented in this release. - - Replaced the mock newsletter subscription with a real Storefront GraphQL mutation: `SubscribeToNewsletterMutation` - - Added comprehensive error handling: - - Invalid email address - - Already subscribed - - Unexpected server errors - - Improved error rendering in `InlineEmailForm` so server-side errors are properly displayed - - Added E2E tests covering the subscription flow - - **User-facing behavior:** - - Success message on subscription - - Clear error messages for common failure cases +Additionally, the [Show Newsletter Summary](https://support.bigcommerce.com/s/article/Collecting-Newsletter-Subscriptions?language=en_US#newsletter-settings) field is not supported. -3. **Account settings newsletter toggle** +## Inventory messaging on Product Listings & Product Details - - Adds a "Marketing preferences" section to `/account/settings` - - Introduces a toggle allowing customers to: - - Subscribe to newsletters - - Unsubscribe from newsletters - - Uses a new server action: `updateNewsletterSubscription` - - UI is shown only when newsletter signup is enabled at the store level - - **Key characteristics:** - - Toggle state reflects `customer.isSubscribedToNewsletter` - - Submitting updates calls Storefront GraphQL to subscribe or unsubscribe - - Includes E2E tests and translations +This release adds **store-aware inventory messaging** across both Product Listing Pages (PLPs) and Product Detail Pages (PDPs). Messages are automatically driven by BigCommerce inventory and backorder settings, ensuring consistent customer communication without custom logic. -### Storefront GraphQL settings +### Product Listing Pages (PLPs) -This feature relies on Storefront GraphQL for both configuration and customer subscription state. +Product cards can now display inventory status messages based on store and product configuration. -#### Fields added +An **Out of Stock** message will be displayed when: -**`site.settings.newsletter.showNewsletterSignup`** +* The product is out of stock +* The store is configured to show out-of-stock messaging -- **Type:** `Boolean` -- **Purpose:** Controls whether newsletter subscription UI is displayed in the storefront -- **Used by:** - - Homepage newsletter signup section - - Account settings "Marketing preferences" section -**`customer.isSubscribedToNewsletter`** +A **Backorder** message will be displayed when: -- **Type:** `Boolean` -- **Purpose:** Indicates whether the authenticated customer is currently subscribed -- **Used by:** - - Account settings toggle initial state - - Determining subscribe vs unsubscribe behavior +* The product has no on-hand inventory +* The product is available for backorder +* The store or product is configured to show backorder messaging -#### GraphQL query example +### Product Detail Pages (PDPs) -```gql -query NewsletterSettingsAndCustomerStatus { - site { - settings { - newsletter { - showNewsletterSignup - } - } - } - customer { - isSubscribedToNewsletter - } +Product detail pages now surface richer backorder context when applicable. When a product supports backorders and store settings allow it, the PDP can display: + +* A backorder availability prompt +* The quantity currently on backorder +* A custom backorder message + +## Consent management + +We’ve made several updates to how we handle consent management in Catalyst. + +* Upgraded [`@c15t/nextjs`](https://www.npmjs.com/package/@c15t/nextjs) to version `1.8.2` +* Changed consent manager mode from `custom` to `offline` mode +* Simplified cookie handling and removed custom consent cookie encoder/decoder implementations (`decoder.ts`, `encoder.ts`) +* `CookieBanner` now supports the `privacyPolicyUrl` field from BigCommerce API and will be rendered in the banner description if available. + +### ConsentManagerProvider + +The `ConsentManagerProvider` now uses `offline` mode instead of `custom` mode with endpoint handlers. The provider configuration has been simplified: + +* `mode` changed from `'custom'` to `'offline'` +* Removed `endpointHandlers` \- no longer needed in offline mode +* Added `enabled` prop to control consent manager functionality +* Added `storageConfig` for cookie storage configuration + +**Before:** + +```ts + showConsentBanner(isCookieConsentEnabled), + setConsent, + verifyConsent, + }, + }} +> + + {children} + + +``` + +**After:** + +```ts + + + {children} + + +``` + +### Cookie Handling + +If you have custom code that directly reads or writes consent cookies, you'll need to update it: + +**Before:** The previous implementation used custom encoding/decoding. If you were directly accessing consent cookie values, you would have needed to use the custom decoder. + +**After:** The consent cookie now uses c15t's compact format. The public API for reading cookies remains the same: + +```ts +import { getConsentCookie } from '~/lib/consent-manager/cookies/client'; // client-side +// or +import { getConsentCookie } from '~/lib/consent-manager/cookies/server'; // server-side + +const consent = getConsentCookie(); +``` + +The `getConsentCookie()` function now internally uses `parseCompactFormat()` to parse the compact format cookie string. If you were directly parsing cookie values, you should now use the `getConsentCookie()` helper instead. + +`getConsentCookie` now returns a compact version of the consent values: + +```ts +{ + i.t: 123456789, + c.necessary: true, + c.functionality: true, + c.marketing: false, + c.measurment: false } ``` - - The `customer` field requires an authenticated shopper context. For homepage - gating only, querying `site.settings.newsletter.showNewsletterSignup` is - sufficient. - +Instances where `getConsentCookie` is used have been updated to reflect this new schema. We also removed `setConsentCookie` from server and client since this is now handled by the c15t library. + +### Script Location Support + +`c15t` scripts now support rendering in either the `` or `` based on the `location` field from the BigCommerce API: + +```ts +// Scripts transformer now includes target based on location +target: script.location === 'HEAD' ? 'head' : 'body' +``` + +The `ScriptsFragment` GraphQL query now includes the `location` field, allowing scripts to be placed in the appropriate DOM location. `FOOTER` location is still not supported. -### Storefront behavior +### Privacy Policy -#### Homepage newsletter signup section +The `RootLayoutMetadataQuery` GraphQL query now includes the `privacyPolicyUrl` field, which the `CookieBanner` component now accepts as a prop. Here is an abbreviated version of that query. -- The newsletter signup section no longer renders unconditionally -- Rendering is controlled by `showNewsletterSignup` -- **UX impact:** - - No visual placeholder or empty state when disabled - - When enabled, the section loads progressively and behaves as expected +``` +query RootLayoutMetadataQuery { + site { + settings { + privacy { + cookieConsentEnabled + privacyPolicyUrl + } + } +} + +``` + +This property is then passed to the `privacyPolicyUrl` prop in the `CookieBanner`. + +```ts +const privacyPolicyUrl = rootData.data.site.settings?.privacy?.privacyPolicyUrl; +//... + + +``` -#### Newsletter signup subscription flow +The privacy policy link: -- Email submissions call BigCommerce Storefront GraphQL -- Errors returned from the API are surfaced directly in the UI -- **User-visible outcomes:** - - Success confirmation on subscription - - Friendly error messages for: - - Invalid email - - Already subscribed - - General failures +- Opens in a new tab (`target="_blank"`) +- Only renders if `privacyPolicyUrl` is provided as a non-empty string -#### Account settings: Marketing preferences +Add translatable `privacyPolicy` field to `Components.ConsentManager.CookieBanner` translation namespace for the privacy policy link text. -- Customers can manage newsletter preferences directly from `/account/settings` -- Toggle reflects real subscription state -- Submitting changes updates BigCommerce via GraphQL -- **Display rules:** - - Section only appears when `showNewsletterSignup` is enabled -- **UX impact:** - - Customers can opt in or out without re-entering email - - Aligns newsletter management with other account preferences +## OpenTelemetry Observability -### Limitations +Catalyst now ships with **built-in [OpenTelemetry](https://opentelemetry.io/docs/) (OTel) instrumentation** using [`@vercel/otel`](https://www.npmjs.com/package/@vercel/otel) and Next.js native instrumentation. This enables production-grade observability out of the box: -This release does not include support for the following newsletter-related features: +* Understand **end-to-end request performance** across PLPs, PDPs, cart, and checkout +* Identify **slow API calls, rendering bottlenecks, and N+1 patterns** +* Debug production issues with **trace-level visibility**, without adding custom instrumentation -**Support for Require Consent** +NOTE: Collection of OpenTelemetry data is enabled by default. For testing locally, you can follow the [Testing your instrumentation](https://nextjs.org/docs/app/guides/open-telemetry#testing-your-instrumentation) documentation from Vercel. Additionally, when connecting to a production environment, you’ll want to configure an observability provider. Here is a non-exhaustive [list of vendors who natively support OpenTelemetry](https://opentelemetry.io/ecosystem/vendors/). -The Require Consent toggle in the store's Miscellaneous settings, which overrides the Newsletter Checkbox when enabled and allows customers to opt in to receive abandoned cart emails and other marketing emails, is not supported in this release. +Next.js includes tracing for several spans out of the box. Refer to the [Default Spans in Next.js](https://nextjs.org/docs/app/guides/open-telemetry#default-spans-in-nextjs) documentation for more details. Additionally, if you need to create custom spans, you can find examples in the [`tracer.ts`](https://github.com/bigcommerce/catalyst/blob/44c682ef988030d7500275f3e4e4503a3a1af63c/core/lib/otel/tracer.ts) file. -**Support for Newsletter Summary** +For an introduction to observability, read the [Observability primer doc](https://opentelemetry.io/docs/concepts/observability-primer/) on the OpenTelemetry website. -The [Show Newsletter Summary](https://support.bigcommerce.com/s/article/Collecting-Newsletter-Subscriptions?language=en_US#newsletter-settings) field is not supported. +## Product Level Discounts (bug fix) -## Migration Guide +Previously, automatic discounts to a specific product (not the entire cart) were not being displayed appropriately. Because of this, it wasn’t clear whether or not the promotions were being applied correctly. This has now been fixed, by displaying a strikethrough price for individually discounted products. ## Release Tags