feat(payments-demo): implement payments demo page and related API endpoints

- Added a new Payments Demo page to showcase payment functionalities, including product listing and checkout options.
- Implemented API endpoints for creating checkout URLs, sending test emails, and validating configuration overrides.
- Enhanced user experience with metrics display for email usage and product subscriptions.
- Updated the header component to include a link to the Payments Demo page.

Author: mantrakp04

examples/demo/src/app/payments-demo/api/config-check/route.ts

@@ -0,0 +1,36 @@
+import { branchConfigSchema, getConfigOverrideErrors } from "@stackframe/stack-shared/dist/config/schema";
+import { ITEM_IDS, PLAN_LIMITS } from "@stackframe/stack-shared/dist/plans";
+import { NextResponse } from "next/server";
+import { stackServerApp } from "src/stack";
+
+function readValidationResult(result: Awaited<ReturnType<typeof getConfigOverrideErrors>>) {
+  if (result.status === "ok") {
+    return {
+      accepted: true,
+      error: null,
+    };
+  }
+  return {
+    accepted: false,
+    error: result.error,
+  };
+}
+
+export async function GET() {
+  const project = await stackServerApp.getProject();
+  const includeByDefaultValidation = await getConfigOverrideErrors(branchConfigSchema, {
+    "payments.products.paymentsDemoInvalidFree.prices": "include-by-default",
+  });
+
+  return NextResponse.json({
+    projectId: project.id,
+    includeByDefaultValidation: readValidationResult(includeByDefaultValidation),
+    expected: {
+      freePrice: "0.00",
+      freeInterval: [1, "month"],
+      freeEmailsPerMonth: PLAN_LIMITS.free.emailsPerMonth,
+      emailItemId: ITEM_IDS.emailsPerMonth,
+      emailsPerMonthRepeat: [1, "month"],
+    },
+  });
+}

examples/demo/src/app/payments-demo/api/create-checkout-url/route.ts

@@ -0,0 +1,45 @@
+import { NextResponse } from "next/server";
+import { stackServerApp } from "src/stack";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readBody(value: unknown): { teamId: string, productId: "team" | "growth", returnUrl?: string } {
+  if (!isRecord(value)) {
+    throw new Error("Request body must be an object.");
+  }
+
+  const { teamId, productId, returnUrl } = value;
+  if (typeof teamId !== "string" || teamId === "") {
+    throw new Error("teamId is required.");
+  }
+  if (productId !== "team" && productId !== "growth") {
+    throw new Error("productId must be team or growth.");
+  }
+  if (returnUrl !== undefined && typeof returnUrl !== "string") {
+    throw new Error("returnUrl must be a string.");
+  }
+
+  return { teamId, productId, returnUrl };
+}
+
+export async function POST(request: Request) {
+  const user = await stackServerApp.getUser();
+  if (user == null) {
+    return NextResponse.json({ error: "Sign in before creating a checkout URL." }, { status: 401 });
+  }
+  const body = readBody(await request.json());
+  const teams = await user.listTeams();
+  const team = teams.find((candidate) => candidate.id === body.teamId);
+  if (team == null) {
+    return NextResponse.json({ error: "Current user is not a member of that team." }, { status: 403 });
+  }
+
+  const url = await team.createCheckoutUrl({
+    productId: body.productId,
+    returnUrl: body.returnUrl,
+  });
+
+  return NextResponse.json({ url });
+}

examples/demo/src/app/payments-demo/api/send-test-email/route.ts

@@ -0,0 +1,40 @@
+import { NextResponse } from "next/server";
+import { stackServerApp } from "src/stack";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readCount(value: unknown): number {
+  if (!isRecord(value)) {
+    return 1;
+  }
+
+  const count = value.count;
+  if (count === undefined) {
+    return 1;
+  }
+  if (typeof count !== "number" || !Number.isInteger(count) || count < 1 || count > 10) {
+    throw new Error("count must be an integer between 1 and 10.");
+  }
+  return count;
+}
+
+export async function POST(request: Request) {
+  const user = await stackServerApp.getUser({ or: "throw" });
+  const body: unknown = await request.json();
+  const count = readCount(body);
+
+  for (let i = 0; i < count; i++) {
+    await stackServerApp.sendEmail({
+      userIds: [user.id],
+      subject: `Payments demo quota test ${i + 1}/${count}`,
+      html: `<p>Payments demo quota test email ${i + 1} of ${count}.</p>`,
+    });
+  }
+
+  return NextResponse.json({
+    sent: count,
+    userId: user.id,
+  });
+}