feat(web): trial banner + plumbing

Adds a trial banner to the owner-facing banner stack and the
surrounding plumbing:

- Schema: License.trialEnd, License.hasPaymentMethod, Org.trialUsedAt
  (durable flag that survives license deactivation). Two migrations.
- servicePing persists trialEnd / hasPaymentMethod and flips
  Org.trialUsedAt on first trial sync.
- Trial banner (owner, dismissible, priority 25): title uses
  formatDistance ("Your trial ends in 10 days"); copy + action branch
  on hasPaymentMethod. With-PM variant links to /settings/license;
  no-PM variant opens the Stripe portal via a new
  OpenBillingPortalButton (LoadingButton + createPortalSession).
- currentPlanCard gains a "Trial ends on" fallback column for the
  trial-without-PM case (where nextRenewalAt is null).
- activationCodeCard accepts isTrialEligible and flips its checkout
  button from "Purchase a license" to "Start a free trial" when the
  org hasn't trialed yet, passing requestTrial through to the checkout
  endpoint.
- Types mirror the new lighthouse fields (trialEnd, hasPaymentMethod)
  and the checkout request additions (installId, requestTrial).

Side-trips to Stripe (portal, checkout) now append ?refresh=true so
the license resyncs on return; trial-checkout also appends
?trial_used=true so Org.trialUsedAt flips immediately (closes the UX
gap between checkout completion and activation-code entry). page.tsx
handles both params, preserves any other query params, and redirects
to a clean URL.

Also: fetchWithRetry now only retries 5xx, 408, and 429 — 4xx errors
(e.g. TRIAL_ALREADY_USED at 409) propagate immediately instead of
retrying pointlessly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: brendan-kellam

packages/db/prisma/migrations/20260422203048_add_trial_fields/migration.sql

@@ -0,0 +1,5 @@
+-- AlterTable
+ALTER TABLE "License" ADD COLUMN     "trialEnd" TIMESTAMP(3);
+
+-- AlterTable
+ALTER TABLE "Org" ADD COLUMN     "trialUsedAt" TIMESTAMP(3);

packages/db/prisma/migrations/20260422204809_add_has_payment_method/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "License" ADD COLUMN     "hasPaymentMethod" BOOLEAN;

packages/db/prisma/schema.prisma

@@ -293,6 +293,10 @@ model Org {
   chats Chat[]
 
   license License?
+
+  /// Set the first time this instance is seen to be on a trial subscription.
+  /// Never cleared. Used to gate the "Start trial" CTA in the UI.
+  trialUsedAt DateTime?
 }
 
 model License {
@@ -311,6 +315,8 @@ model License {
   nextRenewalAt     DateTime?
   nextRenewalAmount Int?
   cancelAt          DateTime?
+  trialEnd          DateTime?
+  hasPaymentMethod  Boolean?
   lastSyncAt        DateTime?
   createdAt         DateTime @default(now())
   updatedAt         DateTime @updatedAt

packages/shared/src/entitlements.test.ts

@@ -63,6 +63,8 @@ const makeLicense = (overrides: Partial<License> = {}): License => ({
     nextRenewalAt: null,
     nextRenewalAmount: null,
     cancelAt: null,
+    trialEnd: null,
+    hasPaymentMethod: null,
     lastSyncAt: new Date(),
     createdAt: new Date(),
     updatedAt: new Date(),

packages/web/src/__mocks__/prisma.ts

@@ -20,7 +20,8 @@ export const MOCK_ORG: Org = {
     metadata: null,
     memberApprovalRequired: false,
     inviteLinkEnabled: false,
-    inviteLinkId: null
+    inviteLinkId: null,
+    trialUsedAt: null,
 }
 
 export const MOCK_API_KEY: ApiKey = {

packages/web/src/app/(app)/components/banners/bannerResolver.test.ts

@@ -18,6 +18,7 @@ vi.mock('./licenseExpiredBanner', () => ({ LicenseExpiredBanner: () => null }));
 vi.mock('./licenseExpiryHeadsUpBanner', () => ({ LicenseExpiryHeadsUpBanner: () => null }));
 vi.mock('./invoicePastDueBanner', () => ({ InvoicePastDueBanner: () => null }));
 vi.mock('./servicePingFailedBanner', () => ({ ServicePingFailedBanner: () => null }));
+vi.mock('./trialBanner', () => ({ TrialBanner: () => null }));
 
 import { resolveActiveBanner, type BannerContext } from './bannerResolver';
 
@@ -43,6 +44,8 @@ const makeLicense = (overrides: Partial<License> = {}): License => ({
     nextRenewalAt: null,
     nextRenewalAmount: null,
     cancelAt: null,
+    trialEnd: null,
+    hasPaymentMethod: null,
     lastSyncAt: NOW,
     createdAt: NOW,
     updatedAt: NOW,
@@ -444,6 +447,92 @@ describe('resolveActiveBanner', () => {
         });
     });
 
+    describe('trial', () => {
+        test('status trialing + future trialEnd → trial banner', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({
+                    status: 'trialing',
+                    trialEnd: daysFromNow(10),
+                }),
+            }));
+            expect(result?.id).toBe('trial');
+        });
+
+        test('trialing but trialEnd in past → no banner', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({
+                    status: 'trialing',
+                    trialEnd: hoursFromNow(-1),
+                }),
+            }));
+            expect(result).toBeNull();
+        });
+
+        test('trialing but no trialEnd → no banner', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({ status: 'trialing', trialEnd: null }),
+            }));
+            expect(result).toBeNull();
+        });
+
+        test('hidden from non-owners', () => {
+            const result = resolveActiveBanner(makeContext({
+                role: OrgRole.MEMBER,
+                license: makeLicense({
+                    status: 'trialing',
+                    trialEnd: daysFromNow(5),
+                }),
+            }));
+            expect(result).toBeNull();
+        });
+
+        test('suppressed by offline license', () => {
+            const result = resolveActiveBanner(makeContext({
+                offlineLicense: makeOfflineLicense(),
+                license: makeLicense({
+                    status: 'trialing',
+                    trialEnd: daysFromNow(5),
+                }),
+            }));
+            expect(result).toBeNull();
+        });
+
+        test('dismissible: today cookie filters out', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({
+                    status: 'trialing',
+                    trialEnd: daysFromNow(5),
+                }),
+                dismissals: { trial: TODAY },
+            }));
+            expect(result).toBeNull();
+        });
+
+        test('outranks license expiry heads-up', () => {
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({
+                    status: 'trialing',
+                    trialEnd: daysFromNow(5),
+                    cancelAt: daysFromNow(5),
+                }),
+            }));
+            expect(result?.id).toBe('trial');
+        });
+
+        test('invoice past due outranks trial', () => {
+            // In reality Stripe statuses are mutually exclusive (a sub can't
+            // be trialing AND past_due at once), but the priority ordering
+            // should hold if both descriptors were somehow produced.
+            const result = resolveActiveBanner(makeContext({
+                license: makeLicense({
+                    status: 'past_due',
+                    trialEnd: daysFromNow(5),
+                }),
+            }));
+            expect(result?.id).toBe('invoicePastDue');
+        });
+    });
+
     describe('permission sync', () => {
         test('entitlement + pending → permissionSync', () => {
             const result = resolveActiveBanner(makeContext({

packages/web/src/app/(app)/components/banners/bannerResolver.tsx

@@ -11,6 +11,7 @@ import { LicenseExpiredBanner } from "./licenseExpiredBanner";
 import { LicenseExpiryHeadsUpBanner } from "./licenseExpiryHeadsUpBanner";
 import { InvoicePastDueBanner } from "./invoicePastDueBanner";
 import { ServicePingFailedBanner } from "./servicePingFailedBanner";
+import { TrialBanner } from "./trialBanner";
 
 const EXPIRY_HEADS_UP_WINDOW_MS = 14 * 24 * 60 * 60 * 1000;
 
@@ -65,6 +66,29 @@ function buildCandidates(ctx: BannerContext): BannerDescriptor[] {
         });
     }
 
+    if (
+        !ctx.offlineLicense
+        && ctx.license?.status === 'trialing'
+        && ctx.license.trialEnd
+        && ctx.license.trialEnd.getTime() > ctx.now.getTime()
+    ) {
+        const trialEndIso = ctx.license.trialEnd.toISOString();
+        const hasPaymentMethod = ctx.license.hasPaymentMethod ?? false;
+        banners.push({
+            id: 'trial',
+            priority: BannerPriority.TRIAL,
+            dismissible: true,
+            audience: 'owner',
+            render: (props) => (
+                <TrialBanner
+                    {...props}
+                    trialEnd={trialEndIso}
+                    hasPaymentMethod={hasPaymentMethod}
+                />
+            ),
+        });
+    }
+
     if (!ctx.offlineLicense && ctx.license?.status === 'past_due') {
         banners.push({
             id: 'invoicePastDue',

packages/web/src/app/(app)/components/banners/openBillingPortalButton.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import { useCallback, useState } from "react";
+import { useRouter } from "next/navigation";
+import { ExternalLink } from "lucide-react";
+import { LoadingButton } from "@/components/ui/loading-button";
+import { useToast } from "@/components/hooks/use-toast";
+import { createPortalSession } from "@/ee/features/lighthouse/actions";
+import { isServiceError } from "@/lib/utils";
+
+interface OpenBillingPortalButtonProps {
+    label: string;
+}
+
+export function OpenBillingPortalButton({ label }: OpenBillingPortalButtonProps) {
+    const [isOpeningPortal, setIsOpeningPortal] = useState(false);
+    const router = useRouter();
+    const { toast } = useToast();
+
+    const handleClick = useCallback(() => {
+        setIsOpeningPortal(true);
+        createPortalSession()
+            .then((response) => {
+                if (isServiceError(response)) {
+                    toast({
+                        description: `Failed to open billing portal: ${response.message}`,
+                        variant: "destructive",
+                    });
+                    setIsOpeningPortal(false);
+                } else {
+                    router.push(response.url);
+                }
+            });
+    }, [router, toast]);
+
+    return (
+        <LoadingButton
+            size="sm"
+            variant="outline"
+            onClick={handleClick}
+            loading={isOpeningPortal}
+        >
+            {label}
+            <ExternalLink className="h-3.5 w-3.5" />
+        </LoadingButton>
+    );
+}

packages/web/src/app/(app)/components/banners/trialBanner.tsx

@@ -0,0 +1,39 @@
+import Link from "next/link";
+import { Clock } from "lucide-react";
+import { formatDistance } from "date-fns";
+import { Button } from "@/components/ui/button";
+import { BannerShell } from "./bannerShell";
+import { OpenBillingPortalButton } from "./openBillingPortalButton";
+import type { BannerProps } from "./types";
+
+interface TrialBannerProps extends BannerProps {
+    // ISO 8601 — serializable across the server component boundary.
+    trialEnd: string;
+    hasPaymentMethod: boolean;
+}
+
+export function TrialBanner({ id, dismissible, now, trialEnd, hasPaymentMethod }: TrialBannerProps) {
+    const trialEndDate = new Date(trialEnd);
+    const relative = formatDistance(trialEndDate, now, { addSuffix: true });
+
+    const description = hasPaymentMethod
+        ? "Your subscription will start automatically at the end of the trial."
+        : "Add a payment method to keep enterprise access after your trial ends.";
+
+    return (
+        <BannerShell
+            id={id}
+            dismissible={dismissible}
+            icon={<Clock className="h-4 w-4 mt-0.5" />}
+            title={`Your trial ends ${relative}`}
+            description={description}
+            action={hasPaymentMethod ? (
+                <Button asChild size="sm" variant="outline">
+                    <Link href="/settings/license">Manage subscription</Link>
+                </Button>
+            ) : (
+                <OpenBillingPortalButton label="Add payment method" />
+            )}
+        />
+    );
+}

packages/web/src/app/(app)/components/banners/types.ts

@@ -3,8 +3,8 @@ export const BannerPriority = {
     SERVICE_PING_ENFORCED:     95,
     INVOICE_PAST_DUE:          90,
     PERMISSION_SYNC:           50,
+    TRIAL:                     25,
     LICENSE_EXPIRY_HEADS_UP:   20,
-    TRIAL:                     15,
     SERVICE_PING_FAILED:       10,
 } as const;