feat(core): allow customer subscription to Newsletter (#2784)

Author: jorgemoya

.changeset/tall-walls-tan.md

@@ -0,0 +1,85 @@
+---
+"@bigcommerce/catalyst-core": patch
+---
+
+Implement functional newsletter subscription feature with BigCommerce GraphQL API integration.
+
+## What Changed
+
+- Replaced the mock implementation in `subscribe.ts` with a real BigCommerce GraphQL API call using the `SubscribeToNewsletterMutation`.
+- Added comprehensive error handling for invalid emails, already-subscribed users, and unexpected errors.
+- Improved form error handling in `InlineEmailForm` to use `form.errors` instead of field-level errors for better error display.
+- Added comprehensive E2E tests and test fixtures for subscription functionality.
+
+## Migration Guide
+
+Replace the `subscribe` action in `core/components/subscribe/_actions/subscribe.ts` with the latest changes to include:
+- BigCommerce GraphQL mutation for newsletter subscription
+- Error handling for invalid emails, already-subscribed users, and unexpected errors
+- Proper error messages returned via Conform's `submission.reply()`
+
+Update `inline-email-form` to fix issue of not showing server-side error messages from form actions.
+
+**`core/vibes/soul/primitives/inline-email-form/index.tsx`**
+
+1. Add import for `FieldError` component:
+```tsx
+import { FieldError } from '@/vibes/soul/form/field-error';
+```
+
+2. Remove the field errors extraction:
+```tsx
+// Remove: const { errors = [] } = fields.email;
+```
+
+3. Update border styling to check both form and field errors:
+```tsx
+// Changed from:
+errors.length ? 'border-error' : 'border-black',
+
+// Changed to:
+form.errors?.length || fields.email.errors?.length
+  ? 'border-error focus-within:border-error'
+  : 'border-black focus-within:border-primary',
+```
+
+4. Update error rendering to display both field-level and form-level errors:
+```tsx
+// Changed from:
+{errors.map((error, index) => (
+  <FormStatus key={index} type="error">
+    {error}
+  </FormStatus>
+))}
+
+// Changed to:
+{fields.email.errors?.map((error) => (
+  <FieldError key={error}>{error}</FieldError>
+))}
+{form.errors?.map((error, index) => (
+  <FormStatus key={index} type="error">
+    {error}
+  </FormStatus>
+))}
+```
+
+This change ensures that server-side error messages returned from form actions (like `formErrors` from Conform's `submission.reply()`) are now properly displayed to users.
+
+Add the following translation keys to your locale files (e.g., `messages/en.json`):
+```json
+{
+  "Components": {
+    "Subscribe": {
+      "title": "Sign up for our newsletter",
+      "placeholder": "Enter your email",
+      "description": "Stay up to date with the latest news and offers from our store.",
+      "success": "You have been subscribed to our newsletter.",
+      "Errors": {
+        "subcriberAlreadyExists": "You are already subscribed to our newsletter.",
+        "invalidEmail": "Please enter a valid email address.",
+        "somethingWentWrong": "Something went wrong. Please try again later."
+      }
+    }
+  }
+}
+```

core/components/subscribe/_actions/subscribe.ts

@@ -1,10 +1,34 @@
 'use server';
 
+import { BigCommerceGQLError } from '@bigcommerce/catalyst-client';
 import { SubmissionResult } from '@conform-to/react';
 import { parseWithZod } from '@conform-to/zod';
 import { getTranslations } from 'next-intl/server';
 
 import { schema } from '@/vibes/soul/primitives/inline-email-form/schema';
+import { client } from '~/client';
+import { graphql } from '~/client/graphql';
+
+const SubscribeToNewsletterMutation = graphql(`
+  mutation SubscribeToNewsletterMutation($input: CreateSubscriberInput!) {
+    newsletter {
+      subscribe(input: $input) {
+        errors {
+          __typename
+          ... on CreateSubscriberEmailInvalidError {
+            message
+          }
+          ... on CreateSubscriberAlreadyExistsError {
+            message
+          }
+          ... on CreateSubscriberUnexpectedError {
+            message
+          }
+        }
+      }
+    }
+  }
+`);
 
 export const subscribe = async (
   _lastResult: { lastResult: SubmissionResult | null },
@@ -18,8 +42,61 @@ export const subscribe = async (
     return { lastResult: submission.reply() };
   }
 
-  // Simulate a network request
-  await new Promise((resolve) => setTimeout(resolve, 1000));
+  try {
+    const response = await client.fetch({
+      document: SubscribeToNewsletterMutation,
+      variables: {
+        input: {
+          email: submission.value.email,
+        },
+      },
+      fetchOptions: {
+        cache: 'no-store',
+      },
+    });
+
+    const errors = response.data.newsletter.subscribe.errors;
+
+    if (!errors.length) {
+      return { lastResult: submission.reply({ resetForm: true }), successMessage: t('success') };
+    }
+
+    if (errors.length > 0) {
+      return {
+        lastResult: submission.reply({
+          formErrors: errors.map(({ __typename }) => {
+            switch (__typename) {
+              case 'CreateSubscriberAlreadyExistsError':
+                return t('Errors.subcriberAlreadyExists');
+
+              case 'CreateSubscriberEmailInvalidError':
+                return t('Errors.invalidEmail');
 
-  return { lastResult: submission.reply(), successMessage: t('success') };
+              default:
+                return t('Errors.somethingWentWrong');
+            }
+          }),
+        }),
+      };
+    }
+
+    return { lastResult: submission.reply({ formErrors: [t('Errors.somethingWentWrong')] }) };
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error(error);
+
+    if (error instanceof BigCommerceGQLError) {
+      return {
+        lastResult: submission.reply({
+          formErrors: error.errors.map(({ message }) => message),
+        }),
+      };
+    }
+
+    if (error instanceof Error) {
+      return { lastResult: submission.reply({ formErrors: [error.message] }) };
+    }
+
+    return { lastResult: submission.reply({ formErrors: [t('Errors.somethingWentWrong')] }) };
+  }
 };

core/messages/en.json

@@ -504,7 +504,12 @@
       "title": "Sign up for our newsletter",
       "placeholder": "Enter your email",
       "description": "Stay up to date with the latest news and offers from our store.",
-      "success": "Thank you for your interest! Newsletter feature is coming soon!"
+      "success": "You have been subscribed to our newsletter.",
+      "Errors": {
+        "subcriberAlreadyExists": "You are already subscribed to our newsletter.",
+        "invalidEmail": "Please enter a valid email address.",
+        "somethingWentWrong": "Something went wrong. Please try again later."
+      }
     },
     "ConsentManager": {
       "Common": {

core/tests/fixtures/index.ts

@@ -16,6 +16,7 @@ import { extendedPage, toHaveURL } from './page';
 import { PromotionFixture } from './promotion';
 import { RedirectsFixture } from './redirects';
 import { SettingsFixture } from './settings';
+import { SubscribeFixture } from './subscribe';
 import { WebPageFixture } from './webpage';
 
 interface Fixtures {
@@ -27,6 +28,7 @@ interface Fixtures {
   promotion: PromotionFixture;
   redirects: RedirectsFixture;
   settings: SettingsFixture;
+  subscribe: SubscribeFixture;
   webPage: WebPageFixture;
   /**
    * 'reuseCustomerSession' sets the the configuration for the customer fixture and determines whether to reuse the customer session.
@@ -131,6 +133,16 @@ export const test = baseTest.extend<Fixtures>({
     },
     { scope: 'test' },
   ],
+  subscribe: [
+    async ({ page }, use, currentTest) => {
+      const subscribeFixture = new SubscribeFixture(page, currentTest);
+
+      await use(subscribeFixture);
+
+      await subscribeFixture.cleanup();
+    },
+    { scope: 'test' },
+  ],
   webPage: [
     async ({ page }, use, currentTest) => {
       const webPageFixture = new WebPageFixture(page, currentTest);

core/tests/fixtures/subscribe/index.ts

@@ -0,0 +1,17 @@
+import { Fixture } from '~/tests/fixtures/fixture';
+
+export class SubscribeFixture extends Fixture {
+  subscribedEmails: string[] = [];
+
+  trackSubscription(email: string): void {
+    this.subscribedEmails.push(email);
+  }
+
+  async cleanup(): Promise<void> {
+    this.skipIfReadonly();
+
+    await Promise.all(this.subscribedEmails.map((email) => this.api.subscribe.unsubscribe(email)));
+
+    this.subscribedEmails = [];
+  }
+}

core/tests/fixtures/utils/api/index.ts

@@ -6,6 +6,7 @@ import { OrdersApi, ordersHttpClient } from '~/tests/fixtures/utils/api/orders';
 import { PromotionsApi, promotionsHttpClient } from '~/tests/fixtures/utils/api/promotions';
 import { RedirectsApi, redirectsHttpClient } from '~/tests/fixtures/utils/api/redirects';
 import { SettingsApi, settingsHttpClient } from '~/tests/fixtures/utils/api/settings';
+import { SubscribeApi, subscribeHttpClient } from '~/tests/fixtures/utils/api/subscribe';
 import { WebPagesApi, webPagesHttpClient } from '~/tests/fixtures/utils/api/webpages';
 
 export interface ApiClient {
@@ -16,6 +17,7 @@ export interface ApiClient {
   orders: OrdersApi;
   promotions: PromotionsApi;
   settings: SettingsApi;
+  subscribe: SubscribeApi;
   webPages: WebPagesApi;
   redirects: RedirectsApi;
 }
@@ -28,6 +30,7 @@ export const httpApiClient: ApiClient = {
   orders: ordersHttpClient,
   promotions: promotionsHttpClient,
   settings: settingsHttpClient,
+  subscribe: subscribeHttpClient,
   webPages: webPagesHttpClient,
   redirects: redirectsHttpClient,
 };

core/tests/fixtures/utils/api/subscribe/http.ts

@@ -0,0 +1,9 @@
+import { httpClient } from '../client';
+
+import { SubscribeApi } from '.';
+
+export const subscribeHttpClient: SubscribeApi = {
+  unsubscribe: async (email: string) => {
+    await httpClient.delete(`/v3/customers/subscribers?email=${encodeURIComponent(email)}`);
+  },
+};

core/tests/fixtures/utils/api/subscribe/index.ts

@@ -0,0 +1,5 @@
+export interface SubscribeApi {
+  unsubscribe(email: string): Promise<void>;
+}
+
+export { subscribeHttpClient } from './http';

core/tests/ui/e2e/subscribe.spec.ts

@@ -0,0 +1,64 @@
+import { faker } from '@faker-js/faker';
+
+import { expect, test } from '~/tests/fixtures';
+import { getTranslations } from '~/tests/lib/i18n';
+import { TAGS } from '~/tests/tags';
+
+test(
+  'Successfully subscribes a user to the newsletter',
+  { tag: [TAGS.writesData] },
+  async ({ page, subscribe }) => {
+    const t = await getTranslations('Components.Subscribe');
+
+    await page.goto('/');
+    await page.waitForLoadState('networkidle');
+
+    const email = faker.internet.email();
+
+    const emailInput = page.getByPlaceholder(t('placeholder'));
+
+    await emailInput.fill(email);
+
+    const submitButton = page.locator('input[type="email"]').locator('..').getByRole('button');
+
+    await submitButton.click();
+    await page.waitForLoadState('networkidle');
+
+    await expect(page.getByText(t('success'))).toBeVisible();
+
+    subscribe.trackSubscription(email);
+  },
+);
+
+test('Shows error when user tries to subscribe again with the same email', async ({
+  page,
+  subscribe,
+}) => {
+  const t = await getTranslations('Components.Subscribe');
+
+  await page.goto('/');
+  await page.waitForLoadState('networkidle');
+
+  const email = faker.internet.email();
+
+  const emailInput = page.getByPlaceholder(t('placeholder'));
+
+  const submitButton = page.locator('input[type="email"]').locator('..').getByRole('button');
+
+  // Subscribe with the email
+  await emailInput.fill(email);
+  await submitButton.click();
+  await page.waitForLoadState('networkidle');
+
+  await expect(page.getByText(t('success'))).toBeVisible();
+
+  // Try to subscribe again with the same email
+  await emailInput.fill(email);
+  await submitButton.click();
+  await page.waitForLoadState('networkidle');
+
+  await expect(page.getByText(t('Errors.subcriberAlreadyExists'))).toBeVisible();
+
+  // Track that we attempted to subscribe this email
+  subscribe.trackSubscription(email);
+});

core/vibes/soul/primitives/inline-email-form/index.tsx

@@ -6,6 +6,7 @@ import { clsx } from 'clsx';
 import { ArrowRight } from 'lucide-react';
 import { useActionState } from 'react';
 
+import { FieldError } from '@/vibes/soul/form/field-error';
 import { FormStatus } from '@/vibes/soul/form/form-status';
 import { Button } from '@/vibes/soul/primitives/button';
 
@@ -40,14 +41,14 @@ export function InlineEmailForm({
     shouldRevalidate: 'onInput',
   });
 
-  const { errors = [] } = fields.email;
-
   return (
     <form {...getFormProps(form)} action={formAction} className={clsx('space-y-2', className)}>
       <div
         className={clsx(
           'relative rounded-xl border bg-background text-base transition-colors duration-200 focus-within:border-primary focus:outline-none',
-          errors.length ? 'border-error' : 'border-black',
+          form.errors?.length || fields.email.errors?.length
+            ? 'border-error focus-within:border-error'
+            : 'border-black focus-within:border-primary',
         )}
       >
         <input
@@ -70,7 +71,10 @@ export function InlineEmailForm({
           </Button>
         </div>
       </div>
-      {errors.map((error, index) => (
+      {fields.email.errors?.map((error) => (
+        <FieldError key={error}>{error}</FieldError>
+      ))}
+      {form.errors?.map((error, index) => (
         <FormStatus key={index} type="error">
           {error}
         </FormStatus>