B2B-88: add starter kit structure and elements

app/home/(user)/billing/_components/personal-account-checkout-form.tsx

@@ -0,0 +1,128 @@
+'use client';
+
+import { useState, useTransition } from 'react';
+
+import dynamic from 'next/dynamic';
+
+import { ExclamationTriangleIcon } from '@radix-ui/react-icons';
+
+import { PlanPicker } from '@kit/billing-gateway/components';
+import { useAppEvents } from '@kit/shared/events';
+import { Alert, AlertDescription, AlertTitle } from '@kit/ui/alert';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@kit/ui/card';
+import { If } from '@kit/ui/if';
+import { Trans } from '@kit/ui/trans';
+
+import billingConfig from '~/config/billing.config';
+
+import { createPersonalAccountCheckoutSession } from '../_lib/server/server-actions';
+
+const EmbeddedCheckout = dynamic(
+  async () => {
+    const { EmbeddedCheckout } = await import('@kit/billing-gateway/checkout');
+
+    return {
+      default: EmbeddedCheckout,
+    };
+  },
+  {
+    ssr: false,
+  },
+);
+
+export function PersonalAccountCheckoutForm(props: {
+  customerId: string | null | undefined;
+}) {
+  const [pending, startTransition] = useTransition();
+  const [error, setError] = useState(false);
+  const appEvents = useAppEvents();
+
+  const [checkoutToken, setCheckoutToken] = useState<string | undefined>(
+    undefined,
+  );
+
+  // only allow trial if the user is not already a customer
+  const canStartTrial = !props.customerId;
+
+  // If the checkout token is set, render the embedded checkout component
+  if (checkoutToken) {
+    return (
+      <EmbeddedCheckout
+        checkoutToken={checkoutToken}
+        provider={billingConfig.provider}
+        onClose={() => setCheckoutToken(undefined)}
+      />
+    );
+  }
+
+  // Otherwise, render the plan picker component
+  return (
+    <div>
+      <Card>
+        <CardHeader>
+          <CardTitle>
+            <Trans i18nKey={'common:planCardLabel'} />
+          </CardTitle>
+
+          <CardDescription>
+            <Trans i18nKey={'common:planCardDescription'} />
+          </CardDescription>
+        </CardHeader>
+
+        <CardContent className={'space-y-4'}>
+          <If condition={error}>
+            <ErrorAlert />
+          </If>
+
+          <PlanPicker
+            pending={pending}
+            config={billingConfig}
+            canStartTrial={canStartTrial}
+            onSubmit={({ planId, productId }) => {
+              startTransition(async () => {
+                try {
+                  appEvents.emit({
+                    type: 'checkout.started',
+                    payload: { planId },
+                  });
+
+                  const { checkoutToken } =
+                    await createPersonalAccountCheckoutSession({
+                      planId,
+                      productId,
+                    });
+
+                  setCheckoutToken(checkoutToken);
+                } catch {
+                  setError(true);
+                }
+              });
+            }}
+          />
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+function ErrorAlert() {
+  return (
+    <Alert variant={'destructive'}>
+      <ExclamationTriangleIcon className={'h-4'} />
+
+      <AlertTitle>
+        <Trans i18nKey={'common:planPickerAlertErrorTitle'} />
+      </AlertTitle>
+
+      <AlertDescription>
+        <Trans i18nKey={'common:planPickerAlertErrorDescription'} />
+      </AlertDescription>
+    </Alert>
+  );
+}

app/home/(user)/billing/_lib/schema/personal-account-checkout.schema.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+
+export const PersonalAccountCheckoutSchema = z.object({
+  planId: z.string().min(1),
+  productId: z.string().min(1),
+});

app/home/(user)/billing/_lib/server/personal-account-billing-page.loader.ts

@@ -0,0 +1,47 @@
+import 'server-only';
+
+import { cache } from 'react';
+
+import { z } from 'zod';
+
+import { createAccountsApi } from '@kit/accounts/api';
+import { getSupabaseServerClient } from '@kit/supabase/server-client';
+
+/**
+ * The variable BILLING_MODE represents the billing mode for a service. It can
+ * have either the value 'subscription' or 'one-time'. If not provided, the default
+ * value is 'subscription'. The value can be overridden by the environment variable
+ * BILLING_MODE.
+ *
+ * If the value is 'subscription', we fetch the subscription data for the user.
+ * If the value is 'one-time', we fetch the orders data for the user.
+ * if none of these suits your needs, please override the below function.
+ */
+const BILLING_MODE = z
+  .enum(['subscription', 'one-time'])
+  .default('subscription')
+  .parse(process.env.BILLING_MODE);
+
+/**
+ * Load the personal account billing page data for the given user.
+ * @param userId
+ * @returns The subscription data or the orders data and the billing customer ID.
+ * This function is cached per-request.
+ */
+export const loadPersonalAccountBillingPageData = cache(
+  personalAccountBillingPageDataLoader,
+);
+
+function personalAccountBillingPageDataLoader(userId: string) {
+  const client = getSupabaseServerClient();
+  const api = createAccountsApi(client);
+
+  const data =
+    BILLING_MODE === 'subscription'
+      ? api.getSubscription(userId)
+      : api.getOrder(userId);
+
+  const customerId = api.getCustomerId(userId);
+
+  return Promise.all([data, customerId]);
+}

app/home/(user)/billing/_lib/server/server-actions.ts

@@ -0,0 +1,58 @@
+'use server';
+
+import { redirect } from 'next/navigation';
+
+import { enhanceAction } from '@kit/next/actions';
+import { getSupabaseServerClient } from '@kit/supabase/server-client';
+
+import featureFlagsConfig from '~/config/feature-flags.config';
+
+import { PersonalAccountCheckoutSchema } from '../schema/personal-account-checkout.schema';
+import { createUserBillingService } from './user-billing.service';
+
+/**
+ * @name enabled
+ * @description This feature flag is used to enable or disable personal account billing.
+ */
+const enabled = featureFlagsConfig.enablePersonalAccountBilling;
+
+/**
+ * @name createPersonalAccountCheckoutSession
+ * @description Creates a checkout session for a personal account.
+ */
+export const createPersonalAccountCheckoutSession = enhanceAction(
+  async function (data) {
+    if (!enabled) {
+      throw new Error('Personal account billing is not enabled');
+    }
+
+    const client = getSupabaseServerClient();
+    const service = createUserBillingService(client);
+
+    return await service.createCheckoutSession(data);
+  },
+  {
+    schema: PersonalAccountCheckoutSchema,
+  },
+);
+
+/**
+ * @name createPersonalAccountBillingPortalSession
+ * @description Creates a billing Portal session for a personal account
+ */
+export const createPersonalAccountBillingPortalSession = enhanceAction(
+  async () => {
+    if (!enabled) {
+      throw new Error('Personal account billing is not enabled');
+    }
+
+    const client = getSupabaseServerClient();
+    const service = createUserBillingService(client);
+
+    // get url to billing portal
+    const url = await service.createBillingPortalSession();
+
+    return redirect(url);
+  },
+  {},
+);

app/home/(user)/billing/_lib/server/user-billing.service.ts

@@ -0,0 +1,202 @@
+import 'server-only';
+
+import { SupabaseClient } from '@supabase/supabase-js';
+
+import { z } from 'zod';
+
+import { createAccountsApi } from '@kit/accounts/api';
+import { getProductPlanPair } from '@kit/billing';
+import { getBillingGatewayProvider } from '@kit/billing-gateway';
+import { getLogger } from '@kit/shared/logger';
+import { requireUser } from '@kit/supabase/require-user';
+
+import appConfig from '~/config/app.config';
+import billingConfig from '~/config/billing.config';
+import pathsConfig from '~/config/paths.config';
+import { Database } from '~/lib/database.types';
+
+import { PersonalAccountCheckoutSchema } from '../schema/personal-account-checkout.schema';
+
+export function createUserBillingService(client: SupabaseClient<Database>) {
+  return new UserBillingService(client);
+}
+
+/**
+ * @name UserBillingService
+ * @description Service for managing billing for personal accounts.
+ */
+class UserBillingService {
+  private readonly namespace = 'billing.personal-account';
+
+  constructor(private readonly client: SupabaseClient<Database>) {}
+
+  /**
+   * @name createCheckoutSession
+   * @description Create a checkout session for the user
+   * @param planId
+   * @param productId
+   */
+  async createCheckoutSession({
+    planId,
+    productId,
+  }: z.infer<typeof PersonalAccountCheckoutSchema>) {
+    // get the authenticated user
+    const { data: user, error } = await requireUser(this.client);
+
+    if (error ?? !user) {
+      throw new Error('Authentication required');
+    }
+
+    const service = await getBillingGatewayProvider(this.client);
+
+    // in the case of personal accounts
+    // the account ID is the same as the user ID
+    const accountId = user.id;
+
+    // the return URL for the checkout session
+    const returnUrl = getCheckoutSessionReturnUrl();
+
+    // find the customer ID for the account if it exists
+    // (eg. if the account has been billed before)
+    const api = createAccountsApi(this.client);
+    const customerId = await api.getCustomerId(accountId);
+
+    const product = billingConfig.products.find(
+      (item) => item.id === productId,
+    );
+
+    if (!product) {
+      throw new Error('Product not found');
+    }
+
+    const { plan } = getProductPlanPair(billingConfig, planId);
+    const logger = await getLogger();
+
+    logger.info(
+      {
+        name: `billing.personal-account`,
+        planId,
+        customerId,
+        accountId,
+      },
+      `User requested a personal account checkout session. Contacting provider...`,
+    );
+
+    try {
+      // call the payment gateway to create the checkout session
+      const { checkoutToken } = await service.createCheckoutSession({
+        returnUrl,
+        accountId,
+        customerEmail: user.email,
+        customerId,
+        plan,
+        variantQuantities: [],
+        enableDiscountField: product.enableDiscountField,
+      });
+
+      logger.info(
+        {
+          userId: user.id,
+        },
+        `Checkout session created. Returning checkout token to client...`,
+      );
+
+      // return the checkout token to the client
+      // so we can call the payment gateway to complete the checkout
+      return {
+        checkoutToken,
+      };
+    } catch (error) {
+      logger.error(
+        {
+          name: `billing.personal-account`,
+          planId,
+          customerId,
+          accountId,
+          error,
+        },
+        `Checkout session not created due to an error`,
+      );
+
+      throw new Error(`Failed to create a checkout session`);
+    }
+  }
+
+  /**
+   * @name createBillingPortalSession
+   * @description Create a billing portal session for the user
+   * @returns The URL to redirect the user to the billing portal
+   */
+  async createBillingPortalSession() {
+    const { data, error } = await requireUser(this.client);
+
+    if (error ?? !data) {
+      throw new Error('Authentication required');
+    }
+
+    const service = await getBillingGatewayProvider(this.client);
+    const logger = await getLogger();
+
+    const accountId = data.id;
+    const api = createAccountsApi(this.client);
+    const customerId = await api.getCustomerId(accountId);
+    const returnUrl = getBillingPortalReturnUrl();
+
+    if (!customerId) {
+      throw new Error('Customer not found');
+    }
+
+    const ctx = {
+      name: this.namespace,
+      customerId,
+      accountId,
+    };
+
+    logger.info(
+      ctx,
+      `User requested a Billing Portal session. Contacting provider...`,
+    );
+
+    let url: string;
+
+    try {
+      const session = await service.createBillingPortalSession({
+        customerId,
+        returnUrl,
+      });
+
+      url = session.url;
+    } catch (error) {
+      logger.error(
+        {
+          error,
+          ...ctx,
+        },
+        `Failed to create a Billing Portal session`,
+      );
+
+      throw new Error(
+        `Encountered an error creating the Billing Portal session`,
+      );
+    }
+
+    logger.info(ctx, `Session successfully created.`);
+
+    // redirect user to billing portal
+    return url;
+  }
+}
+
+function getCheckoutSessionReturnUrl() {
+  return new URL(
+    pathsConfig.app.personalAccountBillingReturn,
+    appConfig.url,
+  ).toString();
+}
+
+function getBillingPortalReturnUrl() {
+  return new URL(
+    pathsConfig.app.personalAccountBilling,
+    appConfig.url,
+  ).toString();
+}

app/home/(user)/billing/error.tsx

@@ -0,0 +1,7 @@
+'use client';
+
+// We reuse the page from the billing module
+// as there is no need to create a new one.
+import BillingErrorPage from '~/home/[account]/billing/error';
+
+export default BillingErrorPage;

app/home/(user)/billing/layout.tsx

@@ -0,0 +1,15 @@
+import { notFound } from 'next/navigation';
+
+import featureFlagsConfig from '~/config/feature-flags.config';
+
+function UserBillingLayout(props: React.PropsWithChildren) {
+  const isEnabled = featureFlagsConfig.enablePersonalAccountBilling;
+
+  if (!isEnabled) {
+    notFound();
+  }
+
+  return <>{props.children}</>;
+}
+
+export default UserBillingLayout;

app/home/(user)/billing/page.tsx

@@ -0,0 +1,92 @@
+import {
+  BillingPortalCard,
+  CurrentLifetimeOrderCard,
+  CurrentSubscriptionCard,
+} from '@kit/billing-gateway/components';
+import { AppBreadcrumbs } from '@kit/ui/app-breadcrumbs';
+import { If } from '@kit/ui/if';
+import { PageBody } from '@kit/ui/page';
+import { Trans } from '@kit/ui/trans';
+
+import billingConfig from '~/config/billing.config';
+import { createI18nServerInstance } from '~/lib/i18n/i18n.server';
+import { withI18n } from '~/lib/i18n/with-i18n';
+import { requireUserInServerComponent } from '~/lib/server/require-user-in-server-component';
+
+// local imports
+import { HomeLayoutPageHeader } from '../_components/home-page-header';
+import { createPersonalAccountBillingPortalSession } from '../billing/_lib/server/server-actions';
+import { PersonalAccountCheckoutForm } from './_components/personal-account-checkout-form';
+import { loadPersonalAccountBillingPageData } from './_lib/server/personal-account-billing-page.loader';
+
+export const generateMetadata = async () => {
+  const i18n = await createI18nServerInstance();
+  const title = i18n.t('account:billingTab');
+
+  return {
+    title,
+  };
+};
+
+async function PersonalAccountBillingPage() {
+  const user = await requireUserInServerComponent();
+
+  const [data, customerId] = await loadPersonalAccountBillingPageData(user.id);
+
+  return (
+    <>
+      <HomeLayoutPageHeader
+        title={<Trans i18nKey={'common:routes.billing'} />}
+        description={<AppBreadcrumbs />}
+      />
+
+      <PageBody>
+        <div className={'flex flex-col space-y-4'}>
+          <If condition={!data}>
+            <PersonalAccountCheckoutForm customerId={customerId} />
+
+            <If condition={customerId}>
+              <CustomerBillingPortalForm />
+            </If>
+          </If>
+
+          <If condition={data}>
+            {(data) => (
+              <div className={'flex w-full max-w-2xl flex-col space-y-6'}>
+                {'active' in data ? (
+                  <CurrentSubscriptionCard
+                    subscription={data}
+                    config={billingConfig}
+                  />
+                ) : (
+                  <CurrentLifetimeOrderCard
+                    order={data}
+                    config={billingConfig}
+                  />
+                )}
+
+                <If condition={!data}>
+                  <PersonalAccountCheckoutForm customerId={customerId} />
+                </If>
+
+                <If condition={customerId}>
+                  <CustomerBillingPortalForm />
+                </If>
+              </div>
+            )}
+          </If>
+        </div>
+      </PageBody>
+    </>
+  );
+}
+
+export default withI18n(PersonalAccountBillingPage);
+
+function CustomerBillingPortalForm() {
+  return (
+    <form action={createPersonalAccountBillingPortalSession}>
+      <BillingPortalCard />
+    </form>
+  );
+}

app/home/(user)/billing/return/page.tsx

@@ -0,0 +1,5 @@
+// We reuse the page from the billing module
+// as there is no need to create a new one.
+import ReturnCheckoutSessionPage from '~/home/[account]/billing/return/page';
+
+export default ReturnCheckoutSessionPage;