feat: introduce Polar billing utilities and enhance checkout URLs

- Added a new CLI command for seeding Polar billing plans into the database.
- Updated checkout success and cancel URLs in .env.example and vars.example.yml for improved routing.
- Enhanced the NotFound component to report route not found events for better observability.
- Implemented success alerts in PlanSettingsSection to notify users of subscription updates with confetti celebration.

Author: regenrek

.env.example

@@ -33,8 +33,8 @@ POLAR_PRODUCT_BUSINESS_MONTHLY="prod_..."
 POLAR_PRODUCT_CREDITS_50="prod_..."
 POLAR_PRODUCT_CREDITS_100="prod_..."
 PUBLIC_URL="http://localhost:3000"
-CHECKOUT_SUCCESS_URL="http://localhost:3000/dashboard/billing/success"
-CHECKOUT_CANCEL_URL="http://localhost:3000/dashboard/billing"
+CHECKOUT_SUCCESS_URL="http://localhost:3000/billing/success"
+CHECKOUT_CANCEL_URL="http://localhost:3000/dashboard"
 VITE_ENTERPRISE_DEMO_URL="https://calendly.com/your-team/demo"
 VITE_POLAR_PRODUCT_CREDITS_50="prod_..."
 VITE_POLAR_PRODUCT_CREDITS_100="prod_..."

cli/README.md

@@ -24,6 +24,8 @@ stack (Postgres, Redis, MinIO, Meilisearch, Mailhog) so the app is ready to go.
 - `pnpm run ex0 -- gc` – prune Docker images/volumes managed by the project.
 - `pnpm run ex0 -- testdata <subcommand>` – generate or clear demo data (see
   interactive prompts for choices).
+- `pnpm run ex0 -- polar seed-plans` – upsert billing plans from Polar/config into
+  the database after plan changes.
 
 ### Deployments
 

cli/index.ts

@@ -643,6 +643,21 @@ const testdataCommand = defineCommand({
   }
 })
 
+const polarSeedPlansCommand = defineCommand({
+  meta: { name: 'seed-plans', description: 'Upsert Polar billing plans into the database' },
+  async run() {
+    runCommand('node --import tsx/loader cli/scripts/seed-plans.ts', 'Seed Polar plans')
+  }
+})
+
+const polarCommand = defineCommand({
+  meta: { name: 'polar', description: 'Polar billing utilities' },
+  subCommands: { 'seed-plans': polarSeedPlansCommand },
+  async run() {
+    await polarSeedPlansCommand.run({ args: {}, options: {}, rawArgs: [] })
+  }
+})
+
 const main = defineCommand({
   meta: { name: 'cli', version: '2.0.0', description: 'Project management CLI (Compose-first, Vault-aware)' },
   subCommands: {
@@ -663,6 +678,7 @@ const main = defineCommand({
     // tunnels/services
     tunnel: tunnelCommand,
     services: servicesCommand,
+    polar: polarCommand,
     // vault helpers
     vault: vaultCommand
   }

cli/scripts/seed-plans.ts

@@ -0,0 +1,15 @@
+import 'dotenv/config'
+
+import { seedPlans } from '../../src/server/seed-plans'
+
+async function main() {
+  try {
+    await seedPlans()
+    console.log('Plans seeded successfully')
+  } catch (error) {
+    console.error('Failed to seed plans', error)
+    process.exitCode = 1
+  }
+}
+
+void main()

infra/ansible/group_vars/constructa/vars.example.yml

@@ -97,6 +97,8 @@ constructa_env:
   POLAR_PRODUCT_BUSINESS_MONTHLY: ''
   POLAR_PRODUCT_CREDITS_50: ''
   POLAR_PRODUCT_CREDITS_100: ''
+  CHECKOUT_SUCCESS_URL: 'https://${APP_HOSTNAME}/billing/success'
+  CHECKOUT_CANCEL_URL: 'https://${APP_HOSTNAME}/dashboard'
 
   SENTRY_DSN: ''
   VITE_SENTRY_DSN: ''

src/components/NotFound.tsx

@@ -1,6 +1,19 @@
-import { Link } from "@tanstack/react-router"
+import { useEffect } from "react";
+import { Link, useRouterState } from "@tanstack/react-router";
+import { reportRouteNotFound } from "~/lib/observability/report-not-found";
 
 export function NotFound({ children }: { children?: any }) {
+    const location = useRouterState({ select: (state) => state.location });
+
+    useEffect(() => {
+        if (!location) return;
+        void reportRouteNotFound({
+            pathname: location.pathname,
+            search: typeof window !== "undefined" ? window.location.search : null,
+            href: typeof window !== "undefined" ? window.location.href : location.href,
+        });
+    }, [location?.href, location?.pathname]);
+
     return (
         <div className="space-y-2 p-2">
             <div className="text-gray-600 dark:text-gray-400">
@@ -21,5 +34,5 @@ export function NotFound({ children }: { children?: any }) {
                 </Link>
             </p>
         </div>
-    )
+    );
 }

src/components/settings/sections/PlanSettings.tsx

@@ -1,14 +1,69 @@
 import * as React from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { useRouter, useRouterState } from '@tanstack/react-router';
+import { motion } from 'framer-motion';
+import { CheckCircle2, X } from 'lucide-react';
+
 import { CreditMeter } from '~/components/billing/CreditMeter';
 import { EnterpriseCTA } from '~/components/billing/EnterpriseCTA';
 import { PlanCard } from '~/components/billing/PlanCard';
+import { Alert, AlertDescription, AlertTitle } from '~/components/ui/alert';
 import { Button } from '~/components/ui/button';
 import { useBillingInfo, useOpenPortal, useStartCheckout } from '~/hooks/useBilling';
+import { isClient } from '~/lib/environment';
 
 export function PlanSettingsSection() {
   const { data, isPending, error } = useBillingInfo();
   const startCheckout = useStartCheckout();
   const openPortal = useOpenPortal();
+  const queryClient = useQueryClient();
+  const router = useRouter();
+  const location = useRouterState({ select: (state) => state.location });
+  const search = (location.search as Record<string, unknown>) ?? {};
+  const billingStatus = typeof search.billingStatus === 'string' ? (search.billingStatus as string) : null;
+  const showSuccess = billingStatus === 'success';
+
+  const [alertVisible, setAlertVisible] = React.useState(showSuccess);
+  const [confettiActive, setConfettiActive] = React.useState(false);
+
+  const clearBillingStatusParam = React.useCallback(() => {
+    if (!isClient) return;
+    const params = new URLSearchParams(window.location.search);
+    params.delete('billingStatus');
+    const query = params.toString();
+    const href = `${window.location.pathname}${query ? `?${query}` : ''}${window.location.hash ?? ''}`;
+    void router.navigate({ href, replace: true });
+  }, [router]);
+
+  const dismissSuccessAlert = React.useCallback(() => {
+    setAlertVisible(false);
+    clearBillingStatusParam();
+  }, [clearBillingStatusParam]);
+
+  React.useEffect(() => {
+    if (!showSuccess) return;
+    setAlertVisible(true);
+    void queryClient.invalidateQueries({ queryKey: ['billingInfo'] });
+    if (!isClient) return;
+    setConfettiActive(true);
+    const timeout = window.setTimeout(() => setConfettiActive(false), 2000);
+    return () => window.clearTimeout(timeout);
+  }, [showSuccess, queryClient]);
+
+  React.useEffect(() => {
+    if (!showSuccess || !alertVisible) return;
+    if (!isClient) return;
+    const timeout = window.setTimeout(() => {
+      dismissSuccessAlert();
+    }, 6000);
+    return () => window.clearTimeout(timeout);
+  }, [showSuccess, alertVisible, dismissSuccessAlert]);
+
+  React.useEffect(() => {
+    if (!showSuccess) {
+      setAlertVisible(false);
+    }
+  }, [showSuccess]);
 
   if (isPending) {
     return <div className="text-sm text-muted-foreground">Loading plan details…</div>;
@@ -47,6 +102,10 @@ export function PlanSettingsSection() {
 
   return (
     <div className="space-y-6">
+      {alertVisible && (
+        <SuccessCelebration confettiActive={confettiActive} onDismiss={dismissSuccessAlert} />
+      )}
+
       <CreditMeter
         allotment={data.credits.monthlyAllotment}
         used={data.credits.allotmentUsed}
@@ -123,3 +182,79 @@ export function PlanSettingsSection() {
     </div>
   );
 }
+
+const CONFETTI_COLORS = ['#34d399', '#22d3ee', '#6366f1', '#f97316', '#facc15'];
+
+function SuccessCelebration({
+  confettiActive,
+  onDismiss,
+}: {
+  readonly confettiActive: boolean;
+  readonly onDismiss: () => void;
+}) {
+  return (
+    <div className="relative overflow-hidden">
+      <Alert variant="success" className="pr-12">
+        <CheckCircle2 className="text-emerald-600 dark:text-emerald-200" />
+        <AlertTitle>Subscription updated</AlertTitle>
+        <AlertDescription>
+          Your plan has been refreshed. Give it a moment if credits take a few seconds to sync.
+        </AlertDescription>
+        <button
+          type="button"
+          onClick={onDismiss}
+          className="absolute right-4 top-4 rounded-full p-1 text-emerald-900/60 transition hover:text-emerald-900 dark:text-emerald-50/60 dark:hover:text-emerald-50"
+        >
+          <X className="h-4 w-4" />
+          <span className="sr-only">Dismiss success message</span>
+        </button>
+      </Alert>
+      <ConfettiBurst active={confettiActive} />
+    </div>
+  );
+}
+
+function ConfettiBurst({ active }: { readonly active: boolean }) {
+  const pieces = React.useMemo(
+    () =>
+      Array.from({ length: 28 }).map((_, index) => ({
+        id: index,
+        x: (Math.random() - 0.5) * 260,
+        y: Math.random() * 180 + 40,
+        rotate: Math.random() * 360,
+        delay: Math.random() * 0.3,
+        duration: 1.1 + Math.random() * 0.6,
+        color: CONFETTI_COLORS[index % CONFETTI_COLORS.length],
+      })),
+    []
+  );
+
+  if (!active || !isClient) {
+    return null;
+  }
+
+  return (
+    <div className="pointer-events-none absolute inset-0 overflow-hidden">
+      {pieces.map((piece) => (
+        <motion.span
+          key={piece.id}
+          className="absolute h-2 w-1 rounded-full"
+          style={{
+            backgroundColor: piece.color,
+            left: '50%',
+            top: '0%',
+          }}
+          initial={{ opacity: 0, x: 0, y: 0, scale: 0.75 }}
+          animate={{
+            opacity: [0, 1, 1, 0],
+            x: piece.x,
+            y: piece.y,
+            rotate: piece.rotate,
+            scale: 1,
+          }}
+          transition={{ duration: piece.duration, delay: piece.delay, ease: 'easeOut' }}
+        />
+      ))}
+    </div>
+  );
+}

src/components/ui/alert.tsx

@@ -0,0 +1,49 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "~/lib/utils";
+
+const alertVariants = cva(
+  "relative w-full rounded-lg border p-4 [&>svg~*]:pl-7 [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:size-5 [&>svg]:text-foreground",
+  {
+    variants: {
+      variant: {
+        default: "bg-background text-foreground",
+        success:
+          "border-emerald-500/40 bg-emerald-500/10 text-emerald-900 dark:border-emerald-400/40 dark:bg-emerald-400/10 dark:text-emerald-100",
+        destructive:
+          "border-destructive/50 text-destructive dark:border-destructive [&>svg]:text-destructive",
+        warning:
+          "border-amber-500/40 bg-amber-500/10 text-amber-900 dark:border-amber-400/40 dark:bg-amber-400/10 dark:text-amber-50",
+        subtle: "border-border/60 text-muted-foreground",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+);
+
+const Alert = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof alertVariants>
+>(({ className, variant, ...props }, ref) => (
+  <div ref={ref} role="alert" className={cn(alertVariants({ variant }), className)} {...props} />
+));
+Alert.displayName = "Alert";
+
+const AlertTitle = React.forwardRef<HTMLHeadingElement, React.HTMLAttributes<HTMLHeadingElement>>(
+  ({ className, ...props }, ref) => (
+    <h5 ref={ref} className={cn("mb-1 font-semibold leading-none tracking-tight", className)} {...props} />
+  )
+);
+AlertTitle.displayName = "AlertTitle";
+
+const AlertDescription = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} className={cn("text-sm text-muted-foreground", className)} {...props} />
+  )
+);
+AlertDescription.displayName = "AlertDescription";
+
+export { Alert, AlertDescription, AlertTitle };

src/hooks/useBilling.ts

@@ -3,8 +3,9 @@ import { useQuery } from '@tanstack/react-query';
 import { useRouter } from '@tanstack/react-router';
 import { useServerFn } from '@tanstack/react-start';
 
-import { CREDIT_PACK_PRODUCTS, PLANS } from '~/config/plans';
+import { CREDIT_PACK_PRODUCTS } from '~/config/plans';
 import { authClient } from '~/lib/auth-client';
+import { isClient } from '~/lib/environment';
 import { getBillingInfo as getBillingInfoFn } from '~/server/function/billing-info.server';
 
 type PolarClientResponse<T> = {
@@ -65,6 +66,16 @@ export function useStartCheckout() {
         throw new Error(error?.message ?? 'Checkout failed');
       }
 
+      if (isClient) {
+        const currentHref = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+        try {
+          window.sessionStorage.setItem('billing:returnTo', currentHref);
+          window.sessionStorage.setItem('billing:returnTo:ts', Date.now().toString());
+        } catch {
+          // sessionStorage may be unavailable (Safari private mode etc.)
+        }
+      }
+
       await router.navigate({
         href: data.url,
         replace: true,

src/lib/environment.ts

@@ -0,0 +1,19 @@
+export const isServer = typeof window === 'undefined';
+export const isClient = !isServer;
+
+export function clientOnly<T>(fn: () => T): T | undefined {
+  if (!isClient) return undefined;
+  return fn();
+}
+
+export function serverOnly<T>(fn: () => T): T | undefined {
+  if (isClient) return undefined;
+  return fn();
+}
+
+export function createIsomorphicFn<T extends (...args: any[]) => any>(
+  serverImpl: T,
+  clientImpl: T,
+): T {
+  return ((...args: Parameters<T>) => (isServer ? serverImpl : clientImpl)(...args)) as T;
+}