@seedgrid/fe-billing-user 2026.7.0

package/scaffold/src/app/billing/page.tsx

@@ -0,0 +1,273 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+
+import {
+  SgButton,
+  SgCard,
+  SgConfirmationDialog,
+  SgSkeleton,
+  SgStack,
+  sgWhistle,
+} from "@seedgrid/fe-components";
+
+import { useI18n } from "@/i18n";
+import { PageFrame, RouteGuard } from "@/modules/security";
+import { billingUserConfig } from "@/modules/billing-user";
+
+import type { SubscriptionResponse, UsageSummaryResponse } from "@seedgrid/fe-billing-user";
+
+type BillingMeResponse = {
+  subscription: SubscriptionResponse | null;
+  usage: UsageSummaryResponse | null;
+};
+
+function formatCurrency(value: number | string | null | undefined) {
+  if (value == null) return "-";
+  const numeric = typeof value === "number" ? value : Number.parseFloat(value);
+  if (!Number.isFinite(numeric)) return "-";
+  return new Intl.NumberFormat(undefined, { style: "currency", currency: "BRL" }).format(numeric);
+}
+
+export default function BillingPage() {
+  return (
+    <RouteGuard permissions={["BILLING_READ"]}>
+      <BillingScreen />
+    </RouteGuard>
+  );
+}
+
+function BillingScreen() {
+  const router = useRouter();
+  const { t } = useI18n();
+  const [data, setData] = useState<BillingMeResponse | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [openingPortal, setOpeningPortal] = useState(false);
+  const [busyAction, setBusyAction] = useState(false);
+  const [confirmCancel, setConfirmCancel] = useState(false);
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    try {
+      const response = await fetch("/api/billing/me", { cache: "no-store" });
+      const payload = (await response.json()) as BillingMeResponse;
+      setData(payload);
+    } catch {
+      sgWhistle.error({ message: t("billing.user.load_error") });
+    } finally {
+      setLoading(false);
+    }
+  }, [t]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  async function handleOpenPortal() {
+    setOpeningPortal(true);
+    try {
+      const response = await fetch("/api/billing/portal", { method: "POST" });
+      const payload = (await response.json()) as { portalUrl: string };
+      window.location.assign(payload.portalUrl);
+    } catch {
+      sgWhistle.error({ message: t("billing.user.portal_error") });
+      setOpeningPortal(false);
+    }
+  }
+
+  // Recebe as mensagens JÁ resolvidas (t() é chamado com literais nos call
+  // sites): passar a chave crua como `string` faria o `t()` recusar (a união
+  // de chaves é estrita).
+  async function runAction(path: string, successMessage: string, errorMessage: string) {
+    setBusyAction(true);
+    try {
+      const response = await fetch(path, { method: "POST" });
+      if (!response.ok) throw new Error("action failed");
+      sgWhistle.success({ message: successMessage });
+      await load();
+    } catch {
+      sgWhistle.error({ message: errorMessage });
+    } finally {
+      setBusyAction(false);
+    }
+  }
+
+  const subscription = data?.subscription ?? null;
+  const usage = data?.usage ?? null;
+  const usedPercent =
+    usage && usage.cycle.includedRequests > 0
+      ? Math.min(100, Math.round((usage.cycle.usedRequests / usage.cycle.includedRequests) * 100))
+      : 0;
+
+  return (
+    <PageFrame
+      title={t("billing.user.title")}
+      description={t("billing.user.description")}
+      actions={
+        <SgStack direction="row" gap={8} wrap>
+          <SgButton
+            appearance="outline"
+            severity="secondary"
+            shape="rounded"
+            label={t("billing.user.view_plans")}
+            onClick={() => router.push(billingUserConfig.routes.plans)}
+          />
+          <SgButton
+            appearance="solid"
+            severity="primary"
+            shape="rounded"
+            label={t("billing.user.manage_action")}
+            loading={openingPortal}
+            disabled={loading || !subscription}
+            onClick={() => void handleOpenPortal()}
+          />
+        </SgStack>
+      }
+    >
+      {loading ? (
+        <SgStack gap={16}>
+          <SgSkeleton height={120} />
+          <SgSkeleton height={120} />
+        </SgStack>
+      ) : !subscription ? (
+        <SgCard cardStyle="outlined" title={t("billing.user.no_subscription.title")}>
+          <SgStack gap={12}>
+            <span>{t("billing.user.no_subscription.description")}</span>
+            <div>
+              <SgButton
+                appearance="solid"
+                severity="primary"
+                shape="rounded"
+                label={t("billing.user.no_subscription.action")}
+                onClick={() => router.push(billingUserConfig.routes.plans)}
+              />
+            </div>
+          </SgStack>
+        </SgCard>
+      ) : (
+        <SgStack gap={16}>
+          <SgCard cardStyle="elevated" title={t("billing.user.plan.title")}>
+            <SgStack gap={12}>
+              <SgStack gap={8}>
+                <strong>{subscription.plan?.name ?? "-"}</strong>
+                <span>
+                  {t("billing.user.plan.price", {
+                    price: formatCurrency(subscription.planTerm?.monthlyPrice),
+                  })}
+                </span>
+                {subscription.pendingChange ? (
+                  <span className="text-sm text-slate-500">
+                    {t("billing.user.plan.pending_change", {
+                      planName: subscription.pendingChange.planName ?? "-",
+                    })}
+                  </span>
+                ) : null}
+                {subscription.cancelAtPeriodEnd ? (
+                  <span className="text-sm text-amber-600">
+                    {t("billing.user.plan.cancel_scheduled")}
+                  </span>
+                ) : null}
+              </SgStack>
+
+              <SgStack direction="row" gap={8} wrap>
+                {subscription.pendingChange ? (
+                  <SgButton
+                    appearance="outline"
+                    severity="secondary"
+                    shape="rounded"
+                    label={t("billing.user.actions.cancel_scheduled_change")}
+                    loading={busyAction}
+                    disabled={busyAction}
+                    onClick={() =>
+                      void runAction(
+                        "/api/billing/cancel-scheduled-change",
+                        t("billing.user.actions.cancel_scheduled_change_success"),
+                        t("billing.user.actions.cancel_scheduled_change_error"),
+                      )
+                    }
+                  />
+                ) : null}
+
+                {subscription.cancelAtPeriodEnd ? (
+                  <SgButton
+                    appearance="solid"
+                    severity="success"
+                    shape="rounded"
+                    label={t("billing.user.actions.reactivate")}
+                    loading={busyAction}
+                    disabled={busyAction}
+                    onClick={() =>
+                      void runAction(
+                        "/api/billing/reactivate",
+                        t("billing.user.actions.reactivate_success"),
+                        t("billing.user.actions.reactivate_error"),
+                      )
+                    }
+                  />
+                ) : (
+                  <SgButton
+                    appearance="outline"
+                    severity="danger"
+                    shape="rounded"
+                    label={t("billing.user.actions.cancel")}
+                    disabled={busyAction}
+                    onClick={() => setConfirmCancel(true)}
+                  />
+                )}
+              </SgStack>
+            </SgStack>
+          </SgCard>
+
+          {usage ? (
+            <SgCard cardStyle="elevated" title={t("billing.user.usage.title")}>
+              <SgStack gap={12}>
+                {/* Barra de progresso inline (o fe-components nao expoe um
+                    SgProgressBar hoje): trilho + preenchimento por width%. */}
+                <div
+                  className="h-2 w-full overflow-hidden rounded-full bg-slate-200"
+                  role="progressbar"
+                  aria-valuenow={usedPercent}
+                  aria-valuemin={0}
+                  aria-valuemax={100}
+                >
+                  <div
+                    className="h-full rounded-full bg-emerald-600 transition-all"
+                    style={{ width: `${Math.min(100, Math.max(0, usedPercent))}%` }}
+                  />
+                </div>
+                <span className="text-sm text-slate-600">
+                  {t("billing.user.usage.summary", {
+                    used: usage.cycle.usedRequests,
+                    included: usage.cycle.includedRequests,
+                  })}
+                </span>
+                {usage.cycle.overageRequests > 0 ? (
+                  <span className="text-sm text-amber-600">
+                    {t("billing.user.usage.overage", { overage: usage.cycle.overageRequests })}
+                  </span>
+                ) : null}
+              </SgStack>
+            </SgCard>
+          ) : null}
+        </SgStack>
+      )}
+
+      <SgConfirmationDialog
+        open={confirmCancel}
+        severity="danger"
+        title={t("billing.user.actions.cancel_title")}
+        message={t("billing.user.actions.cancel_message")}
+        onCancel={() => setConfirmCancel(false)}
+        onConfirm={() => {
+          setConfirmCancel(false);
+          void runAction(
+            "/api/billing/cancel",
+            t("billing.user.actions.cancel_success"),
+            t("billing.user.actions.cancel_error"),
+          );
+        }}
+      />
+    </PageFrame>
+  );
+}

package/scaffold/src/app/billing/plans/page.tsx

@@ -0,0 +1,248 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+
+import {
+  SgBadge,
+  SgButton,
+  SgCard,
+  SgConfirmationDialog,
+  SgGrid,
+  SgSkeleton,
+  SgStack,
+  sgWhistle,
+} from "@seedgrid/fe-components";
+
+import { useI18n } from "@/i18n";
+import { PageFrame, RouteGuard } from "@/modules/security";
+import { billingUserConfig } from "@/modules/billing-user";
+import type {
+  ChangePreviewResponse,
+  PlanCatalogItem,
+  PlansCatalogResponse,
+} from "@seedgrid/fe-billing-user";
+
+export default function PlansCatalogPage() {
+  return (
+    <RouteGuard permissions={["BILLING_READ"]}>
+      <PlansCatalogScreen />
+    </RouteGuard>
+  );
+}
+
+function formatCurrency(value: number | string | null | undefined) {
+  if (value == null) return "-";
+  const numeric = typeof value === "number" ? value : Number.parseFloat(value);
+  if (!Number.isFinite(numeric)) return "-";
+  return new Intl.NumberFormat(undefined, { style: "currency", currency: "BRL" }).format(numeric);
+}
+
+function PlansCatalogScreen() {
+  const { t } = useI18n();
+  const [catalog, setCatalog] = useState<PlansCatalogResponse | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [busyPlanId, setBusyPlanId] = useState<string | null>(null);
+  const [pendingChange, setPendingChange] = useState<{
+    item: PlanCatalogItem;
+    preview: ChangePreviewResponse;
+  } | null>(null);
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    try {
+      const response = await fetch("/api/billing/plans", { cache: "no-store" });
+      if (!response.ok) throw new Error("load failed");
+      setCatalog((await response.json()) as PlansCatalogResponse);
+    } catch {
+      sgWhistle.error({ message: t("billing.user.plans_catalog.load_error") });
+    } finally {
+      setLoading(false);
+    }
+  }, [t]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const items = catalog?.items ?? [];
+  const hasSubscription = items.some((item) => item.current);
+
+  async function handleSubscribe(item: PlanCatalogItem) {
+    setBusyPlanId(item.planId);
+    try {
+      const response = await fetch("/api/billing/checkout", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ planId: item.planId }),
+      });
+      if (!response.ok) throw new Error("checkout failed");
+      const payload = (await response.json()) as { checkoutUrl: string };
+      window.location.assign(payload.checkoutUrl);
+    } catch {
+      sgWhistle.error({ message: t("billing.user.plans_catalog.checkout_error") });
+      setBusyPlanId(null);
+    }
+  }
+
+  async function handleRequestChange(item: PlanCatalogItem) {
+    setBusyPlanId(item.planId);
+    try {
+      const response = await fetch(
+        `/api/billing/change-preview?planId=${encodeURIComponent(item.planId)}`,
+        { cache: "no-store" },
+      );
+      if (!response.ok) throw new Error("preview failed");
+      const preview = (await response.json()) as ChangePreviewResponse;
+      setPendingChange({ item, preview });
+    } catch {
+      sgWhistle.error({ message: t("billing.user.plans_catalog.preview_error") });
+    } finally {
+      setBusyPlanId(null);
+    }
+  }
+
+  async function confirmChange() {
+    if (!pendingChange) return;
+    const { item } = pendingChange;
+    setBusyPlanId(item.planId);
+    setPendingChange(null);
+    try {
+      const response = await fetch("/api/billing/change-plan", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ planId: item.planId }),
+      });
+      if (!response.ok) throw new Error("change failed");
+      sgWhistle.success({ message: t("billing.user.plans_catalog.change_success") });
+      await load();
+    } catch {
+      sgWhistle.error({ message: t("billing.user.plans_catalog.change_error") });
+    } finally {
+      setBusyPlanId(null);
+    }
+  }
+
+  const changeMessage = pendingChange
+    ? pendingChange.preview.downgrade
+      ? t("billing.user.plans_catalog.confirm.downgrade")
+      : pendingChange.preview.immediate
+        ? t("billing.user.plans_catalog.confirm.immediate", {
+            amount: formatCurrency(pendingChange.preview.amountDue),
+          })
+        : t("billing.user.plans_catalog.confirm.upgrade")
+    : "";
+
+  return (
+    <PageFrame
+      title={t("billing.user.plans_catalog.title")}
+      description={t("billing.user.plans_catalog.description")}
+    >
+      {loading ? (
+        <SgGrid minItemWidth={280} gap={16}>
+          <SgSkeleton height={220} />
+          <SgSkeleton height={220} />
+          <SgSkeleton height={220} />
+        </SgGrid>
+      ) : (
+        <SgStack gap={16}>
+          {catalog?.pendingChange ? (
+            <SgCard cardStyle="outlined" title={t("billing.user.plans_catalog.pending.title")}>
+              {t("billing.user.plans_catalog.pending.description", {
+                planName: catalog.pendingChange.planName,
+              })}
+            </SgCard>
+          ) : null}
+
+          <SgGrid minItemWidth={280} gap={16}>
+            {items.map((item) => (
+              <SgCard
+                key={item.planId}
+                cardStyle={item.current ? "elevated" : "outlined"}
+                title={item.name}
+              >
+                <SgStack gap={12}>
+                  {item.current ? (
+                    <SgBadge
+                      value={t("billing.user.plans_catalog.current")}
+                      severity="success"
+                      badgeStyle="soft"
+                      size="sm"
+                    />
+                  ) : null}
+                  <div className="text-2xl font-semibold text-slate-900">
+                    {formatCurrency(item.monthlyPrice)}
+                    <span className="text-sm font-normal text-slate-500">
+                      {" "}
+                      {t("billing.user.plans_catalog.per_month")}
+                    </span>
+                  </div>
+                  {item.description ? (
+                    <p className="text-sm text-slate-600">{item.description}</p>
+                  ) : null}
+                  <p className="text-sm text-slate-600">
+                    {t("billing.user.plans_catalog.requests", {
+                      requests: item.monthlyRequests.toLocaleString(),
+                    })}
+                  </p>
+
+                  {item.current ? (
+                    <SgButton
+                      appearance="outline"
+                      severity="secondary"
+                      shape="rounded"
+                      label={t("billing.user.plans_catalog.current_action")}
+                      disabled
+                    />
+                  ) : !item.checkoutEnabled ? (
+                    <SgButton
+                      appearance="outline"
+                      severity="secondary"
+                      shape="rounded"
+                      label={t("billing.user.plans_catalog.unavailable")}
+                      disabled
+                    />
+                  ) : hasSubscription ? (
+                    <SgButton
+                      appearance="solid"
+                      severity="primary"
+                      shape="rounded"
+                      label={t("billing.user.plans_catalog.change_action")}
+                      loading={busyPlanId === item.planId}
+                      disabled={busyPlanId !== null}
+                      onClick={() => void handleRequestChange(item)}
+                    />
+                  ) : (
+                    <SgButton
+                      appearance="solid"
+                      severity="primary"
+                      shape="rounded"
+                      label={t("billing.user.plans_catalog.subscribe_action")}
+                      loading={busyPlanId === item.planId}
+                      disabled={busyPlanId !== null}
+                      onClick={() => void handleSubscribe(item)}
+                    />
+                  )}
+                </SgStack>
+              </SgCard>
+            ))}
+          </SgGrid>
+
+          {!items.length ? (
+            <SgCard cardStyle="outlined" title={t("billing.user.plans_catalog.empty_title")}>
+              {t("billing.user.plans_catalog.empty")}
+            </SgCard>
+          ) : null}
+        </SgStack>
+      )}
+
+      <SgConfirmationDialog
+        open={Boolean(pendingChange)}
+        severity="primary"
+        title={t("billing.user.plans_catalog.confirm.title")}
+        message={changeMessage}
+        onCancel={() => setPendingChange(null)}
+        onConfirm={confirmChange}
+      />
+    </PageFrame>
+  );
+}

package/scaffold/src/modules/billing-user/config.ts

@@ -0,0 +1,7 @@
+export const billingUserConfig = {
+  routes: {
+    overview: "/billing",
+    plans: "/billing/plans",
+    invoices: "/billing/invoices",
+  },
+} as const;

package/scaffold/src/modules/billing-user/index.ts

@@ -0,0 +1,17 @@
+// Barrel do módulo billing-user no app gerado. Config local + nav hook +
+// reexport dos tipos da lib (@seedgrid/fe-billing-user).
+
+export { billingUserConfig } from "./config";
+export { useBillingUserAppShellSections } from "./useBillingUserAppShellSections";
+
+export type {
+  SubscriptionResponse,
+  UsageSummaryResponse,
+  PlanCatalogItem,
+  PlansCatalogResponse,
+  CheckoutSessionResponse,
+  ChangePlanResponse,
+  ChangePreviewResponse,
+  UpcomingInvoiceResponse,
+  BillingInvoiceEnvelope,
+} from "@seedgrid/fe-billing-user";

package/scaffold/src/modules/billing-user/server.ts.hbs

@@ -0,0 +1,34 @@
+"use server";
+
+// Bootstrap do engine de billing do usuário: reaproveita o mesmo motor de
+// sessão do fe-security (createSecurityServer) e compõe com
+// createBillingUserServer por cima. Não existe uma fonte histórica pra essa
+// composição (pacote novo, sem tela anterior — ver scaffold/README.md), mas
+// os nomes de cookie seguem a mesma convenção já usada em
+// modules/security/server/server-api.ts, pra funcionar com a MESMA sessão.
+
+import { createSecurityServer } from "@seedgrid/fe-security/server";
+import { createBillingUserServer } from "@seedgrid/fe-billing-user/server";
+
+import { resolvePublicApiBaseUrl } from "@/modules/security/server/public-api-base-url";
+
+const ACCESS_COOKIE_NAME =
+  process.env.SEEDGRID_SECURITY_ACCESS_COOKIE_NAME?.trim() ||
+  "sg_{{project_slug}}_access_token";
+const REFRESH_COOKIE_NAME =
+  process.env.SEEDGRID_SECURITY_REFRESH_COOKIE_NAME?.trim() ||
+  "sg_{{project_slug}}_refresh_token";
+const PASSWORD_CHANGE_REQUIRED_COOKIE_NAME = "sg_{{project_slug}}_password_change_required";
+
+export async function getBillingUserServer() {
+  const session = createSecurityServer({
+    apiBaseUrl: await resolvePublicApiBaseUrl(),
+    cookies: {
+      token: ACCESS_COOKIE_NAME,
+      refresh: REFRESH_COOKIE_NAME,
+      passwordChangeRequired: PASSWORD_CHANGE_REQUIRED_COOKIE_NAME,
+    },
+  });
+
+  return createBillingUserServer(session);
+}

package/scaffold/src/modules/billing-user/useBillingUserAppShellSections.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import { CreditCard, FileText, LayoutGrid, Receipt } from "lucide-react";
+
+import type { AppShellSection } from "@/components/layout/app-shell-navigation";
+import { useI18n } from "@/i18n";
+import { usePermission } from "@/modules/security";
+
+import { billingUserConfig } from "./config";
+
+// Seção de navegação da assinatura do usuário. Gated por BILLING_READ (mesma
+// permissão que as telas usam no RouteGuard).
+export function useBillingUserAppShellSections(): AppShellSection[] {
+  const { t } = useI18n();
+  const canRead = usePermission("BILLING_READ");
+
+  if (!canRead) {
+    return [];
+  }
+
+  return [
+    {
+      id: "billing",
+      label: t("billing.user.nav.group"),
+      order: 30,
+      items: [
+        {
+          id: "billing-user",
+          label: t("billing.user.nav.group"),
+          icon: <CreditCard size={18} />,
+          order: 10,
+          children: [
+            {
+              id: "billing-overview",
+              label: t("billing.user.nav.overview"),
+              href: billingUserConfig.routes.overview,
+              icon: <LayoutGrid size={16} />,
+              order: 10,
+            },
+            {
+              id: "billing-plans",
+              label: t("billing.user.nav.plans"),
+              href: billingUserConfig.routes.plans,
+              icon: <FileText size={16} />,
+              order: 20,
+            },
+            {
+              id: "billing-invoices",
+              label: t("billing.user.nav.invoices"),
+              href: billingUserConfig.routes.invoices,
+              icon: <Receipt size={16} />,
+              order: 30,
+            },
+          ],
+        },
+      ],
+    },
+  ];
+}