Sync dev branch

README.md

@@ -56,12 +56,12 @@ While the Chargebee [docs](https://chargebee.com/docs) and [apidocs](https://api
 
 | Topic | Status | Last Updated |
 |-------|--------|--------------|
-| [Integrating Chargebee webhooks](./how-to/webhooks.md) | In Review | |
-| [Enforcing entitlement checks](./how-to/entitlement-checks.md) | In Review | |
-| [Sync Chargebee entities](./how-to/sync-chargebee-entities.md) | Draft | |
-| [Usage-based billing](./how-to/usage-based-billing.md) | Draft | |
-| [Usage alerts](./how-to/usage-alerts.md) | In Progress | |
-| [Checkout experience](./how-to/checkout-experience.md) | In Progress | |
+| [Integrating Chargebee webhooks](./how-to/webhooks.md) | Pending Review | |
+| [Enforcing entitlement checks](./how-to/entitlement-checks.md) | Pending Review | |
+| [Sync Chargebee entities](./how-to/sync-chargebee-entities.md) | Pending Review | |
+| [Usage-based billing](./how-to/usage-based-billing.md) | Pending Review | |
+| [Usage alerts](./how-to/usage-alerts.md) | Pending Review | |
+| [Checkout experience](./how-to/checkout-experience.md) | Pending Review | |
 
 ## Reference App
 

pointer/ARCHITECTURE.md

@@ -64,7 +64,7 @@ flowchart TB
 The web and API service is responsible for:
 
 - **Authentication and accounts**: Better Auth with the organization plugin. Personal accounts bill against the individual user; team accounts bill against the organization.
-- **Chargebee provisioning**: On user creation, a Chargebee customer record is created (or reused), its ID is recorded on the `user` table, and an idempotent free subscription is provisioned with `billing_cycles: 0`. The home page waits for the initial subscription webhook before rendering, using free-tier defaults while the queued entitlement snapshot completes.
+- **Chargebee provisioning**: On user creation, a Chargebee customer record is created (or reused), its ID is recorded on the `user` table, and an idempotent free subscription is provisioned with `billing_cycles: 0`. The home page does not wait for the subscription webhook: it pulls the subscription and its entitlements from the Chargebee API and mirrors them, falling back to polling for the webhook if that fails.
 - **Webhook ingress**: The Chargebee webhook endpoint verifies HTTP Basic Auth, parses payloads, and immediately pushes them to AWS SQS. It executes no database operations, preventing webhook traffic spikes from exhausting connection pools or slowing HTTP requests.
 - **Live event stream**: Publishes domain events to a Redis stream, exposed via Server-Sent Events (SSE) for the `/admin/flow` diagnostic visualization.
 

pointer/app/(auth)/sign-up/page.tsx

@@ -40,8 +40,8 @@ function SignUpForm() {
 		const password = String(formData.get("password") ?? "");
 
 		// Email verification is disabled, so Better Auth signs the user in
-		// immediately. The home page waits for the automatically-created free
-		// subscription webhook and entitlement mirror before rendering.
+		// immediately. The home page pulls the automatically-created free
+		// subscription and its entitlements from Chargebee before rendering.
 		const { error: signUpError } = await authClient.signUp.email({
 			name,
 			email,

pointer/app/page.tsx

@@ -3,11 +3,12 @@ import Image from "next/image";
 import Link from "next/link";
 import { redirect } from "next/navigation";
 
-import { auth } from "@/lib/auth";
+import { auth, type Session } from "@/lib/auth";
 import {
 	findSelfServicePlan,
 	selfServicePlans,
 } from "@/lib/self-service-plans";
+import { syncSignupBilling } from "@/lib/signup-sync";
 import { getActiveUserSubscription } from "@/lib/subscriptions";
 
 import { AccountProvisioning } from "./_components/account-provisioning";
@@ -19,10 +20,8 @@ export default async function Home({ searchParams }: PageProps<"/">) {
 	const session = await auth.api.getSession({ headers: requestHeaders });
 	if (!session) return <MarketingHome />;
 
-	// Signing up provisions a free subscription in the background, so a brand
-	// new account lands here before its local record exists.
 	const { provisioning, plan } = await searchParams;
-	const subscription = await getActiveUserSubscription(session.user.id);
+	const subscription = await loadSubscription(session, provisioning);
 	const requestedPlan = findSelfServicePlan(plan);
 
 	// A paid plan picked on the pricing page can only go to checkout once that
@@ -43,6 +42,24 @@ export default async function Home({ searchParams }: PageProps<"/">) {
 	return <SignedInHome />;
 }
 
+/**
+ * A brand-new account lands here before the subscription webhook mirrors its
+ * free plan. Pull it from Chargebee instead; the provisioning page only
+ * covers a failed pull.
+ */
+async function loadSubscription(
+	session: Session,
+	provisioning: string | string[] | undefined,
+) {
+	const subscription = await getActiveUserSubscription(session.user.id);
+	if (subscription || provisioning !== "1") {
+		return subscription;
+	}
+
+	await syncSignupBilling(session);
+	return getActiveUserSubscription(session.user.id);
+}
+
 function SignedInHome() {
 	return (
 		<div className="flex flex-1 flex-col bg-zinc-50 font-sans text-zinc-900 dark:bg-black dark:text-zinc-50">

pointer/lib/entitlements/sync.ts

@@ -77,7 +77,11 @@ async function assertLocalSubscription(
 	}
 }
 
-export type EntitlementSyncTrigger = "webhook" | "checkout" | "reconcile";
+export type EntitlementSyncTrigger =
+	| "webhook"
+	| "checkout"
+	| "signup"
+	| "reconcile";
 
 /**
  * Refetches a subscription's entitlements from Chargebee and rewrites the

pointer/lib/free-subscription.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 
 import type Chargebee from "chargebee";
-import type { Subscription } from "chargebee";
+import type { Customer, Subscription } from "chargebee";
 
 import { itemPriceIdFor } from "@/scripts/catalog";
 
@@ -20,6 +20,24 @@ export type FreeSubscriptionResult = {
 	created: boolean;
 };
 
+export type LiveSubscription = {
+	subscription: Subscription;
+	customer: Customer;
+};
+
+/** The customer's live subscription, with the customer it bills. */
+export async function findLiveSubscription(
+	client: SubscriptionClient,
+	customerId: string,
+): Promise<LiveSubscription | null> {
+	const existing = await client.subscription.list({
+		customer_id: { is: customerId },
+		status: { in: [...LIVE_SUBSCRIPTION_STATUSES] },
+		limit: 1,
+	});
+	return existing.list?.[0] ?? null;
+}
+
 function signupSubscriptionId(userId: string): string {
 	const digest = createHash("sha256").update(userId).digest("hex").slice(0, 32);
 	return `pointer-free-${digest}`;
@@ -37,12 +55,8 @@ export async function ensureFreeSubscription(
 	client: SubscriptionClient,
 	input: { customerId: string; userId: string },
 ): Promise<FreeSubscriptionResult> {
-	const existing = await client.subscription.list({
-		customer_id: { is: input.customerId },
-		status: { in: [...LIVE_SUBSCRIPTION_STATUSES] },
-		limit: 1,
-	});
-	const current = existing.list?.[0]?.subscription;
+	const existing = await findLiveSubscription(client, input.customerId);
+	const current = existing?.subscription;
 	if (current) return { subscription: current, created: false };
 
 	const id = signupSubscriptionId(input.userId);

pointer/lib/signup-sync.test.ts

@@ -0,0 +1,89 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { Session } from "@/lib/auth";
+
+const mocks = vi.hoisted(() => ({
+	chargebeeCustomerId: "cust-1" as string | null,
+	list: vi.fn(),
+	process: vi.fn(async () => undefined),
+	syncEntitlements: vi.fn(async () => undefined),
+}));
+
+vi.mock("@/lib/auth", () => ({ auth: { $context: Promise.resolve({}) } }));
+vi.mock("@chargebee/better-auth", () => ({
+	createChargebeeWebhookProcessor: () => ({ process: mocks.process }),
+}));
+vi.mock("@/plugins/chargebee-plugin", () => ({
+	chargebeeClient: { subscription: { list: mocks.list } },
+	chargebeePluginOptions: {},
+}));
+vi.mock("@/lib/entitlements/subject", () => ({
+	resolveBillingSubject: async () => ({
+		customerType: "user",
+		referenceId: "user-1",
+		chargebeeCustomerId: mocks.chargebeeCustomerId,
+	}),
+}));
+vi.mock("@/lib/entitlements/sync", () => ({
+	syncSubscriptionEntitlements: mocks.syncEntitlements,
+}));
+
+import { syncSignupBilling } from "./signup-sync";
+
+const session = { user: { id: "user-1" }, session: {} } as unknown as Session;
+const live = {
+	subscription: { id: "sub-free", status: "active" },
+	customer: { id: "cust-1" },
+};
+
+describe("syncSignupBilling", () => {
+	beforeEach(() => {
+		mocks.chargebeeCustomerId = "cust-1";
+		mocks.list.mockReset();
+		mocks.list.mockResolvedValue({ list: [live] });
+		mocks.process.mockClear();
+		mocks.syncEntitlements.mockClear();
+	});
+
+	it("mirrors the live subscription and fetches its entitlements", async () => {
+		await syncSignupBilling(session);
+
+		expect(mocks.list).toHaveBeenCalledWith(
+			expect.objectContaining({ customer_id: { is: "cust-1" }, limit: 1 }),
+		);
+		expect(mocks.process).toHaveBeenCalledWith(
+			expect.objectContaining({
+				event_type: "subscription_created",
+				content: live,
+			}),
+		);
+		expect(mocks.syncEntitlements).toHaveBeenCalledWith("sub-free", {
+			trigger: "signup",
+		});
+	});
+
+	it("skips users without a Chargebee customer", async () => {
+		mocks.chargebeeCustomerId = null;
+
+		await syncSignupBilling(session);
+
+		expect(mocks.list).not.toHaveBeenCalled();
+		expect(mocks.syncEntitlements).not.toHaveBeenCalled();
+	});
+
+	it("skips customers without a live subscription", async () => {
+		mocks.list.mockResolvedValue({ list: [] });
+
+		await syncSignupBilling(session);
+
+		expect(mocks.process).not.toHaveBeenCalled();
+		expect(mocks.syncEntitlements).not.toHaveBeenCalled();
+	});
+
+	it("leaves the webhook path in charge when Chargebee fails", async () => {
+		mocks.list.mockRejectedValue(new Error("chargebee down"));
+
+		await expect(syncSignupBilling(session)).resolves.toBeUndefined();
+		expect(mocks.syncEntitlements).not.toHaveBeenCalled();
+	});
+});

pointer/lib/signup-sync.ts

@@ -0,0 +1,70 @@
+import {
+	createChargebeeWebhookProcessor,
+	type ChargebeeWebhookProcessorSource,
+} from "@chargebee/better-auth";
+import type { WebhookEvent } from "chargebee";
+
+import { auth, type Session } from "@/lib/auth";
+import { resolveBillingSubject } from "@/lib/entitlements/subject";
+import { syncSubscriptionEntitlements } from "@/lib/entitlements/sync";
+import {
+	findLiveSubscription,
+	type LiveSubscription,
+} from "@/lib/free-subscription";
+import {
+	chargebeeClient,
+	chargebeePluginOptions,
+} from "@/plugins/chargebee-plugin";
+
+/**
+ * A list entry carries the same `subscription` + `customer` content as the
+ * `subscription_created` webhook, so the plugin's own hook writes the mirror
+ * rows. The real webhook later finds them and skips.
+ */
+async function mirrorSubscription(live: LiveSubscription): Promise<void> {
+	const processor = createChargebeeWebhookProcessor(chargebeePluginOptions, {
+		auth,
+	} as unknown as ChargebeeWebhookProcessorSource);
+	await processor.process({
+		id: `signup-${live.subscription.id}`,
+		event_type: "subscription_created",
+		content: live,
+	} as unknown as WebhookEvent);
+}
+
+/**
+ * Read-your-writes for sign-up. The free subscription was created through the
+ * API moments ago, so its webhook is still in flight. Pull the subscription
+ * and its entitlements from Chargebee instead of waiting for it.
+ *
+ *   sign-up ──► Chargebee: create subscription
+ *   home    ──► Chargebee: list subscription  ──► mirror rows
+ *           ──► Chargebee: fetch entitlements ──► snapshot
+ *   webhook ──► rows exist, skipped
+ */
+export async function syncSignupBilling(session: Session): Promise<void> {
+	try {
+		const subject = await resolveBillingSubject(session, {
+			customerType: "user",
+		});
+		if (!subject.chargebeeCustomerId) {
+			return;
+		}
+
+		const live = await findLiveSubscription(
+			chargebeeClient,
+			subject.chargebeeCustomerId,
+		);
+		if (!live) {
+			return;
+		}
+
+		await mirrorSubscription(live);
+		await syncSubscriptionEntitlements(live.subscription.id, {
+			trigger: "signup",
+		});
+	} catch (error) {
+		// The webhook remains the correctness path; the provisioning page polls.
+		console.error("[signup] direct billing sync failed", error);
+	}
+}