create-ab-app 0.1.1

package/template/src/lib/sso/auth-screens.tsx

@@ -0,0 +1,152 @@
+import { useNavigate, useParams, useSearchParams } from "react-router-dom"
+import { ForgotPassword, Login, Signup, VerifyEmail } from "ab-ecosystem-sso"
+import { toast } from "sonner"
+
+import { useAuth } from "./auth-context"
+import { ssoProps } from "./config"
+
+/**
+ * The SDK's auth screens, bound once to this project's config, the token store
+ * and the router. The only components that render SDK auth UI.
+ */
+
+/** Narrows the SDK card from its default max-w-md. Restyle the screens here. */
+const authClassNames = { card: "max-w-sm!" }
+
+type AuthPayload = {
+  token?: string
+  accessToken?: string
+  data?: { token?: string; accessToken?: string }
+}
+
+/**
+ * onSuccess receives the raw API envelope — { success, message, data:
+ * { accessToken } } — not the { token, user } the SDK's AuthResponse type
+ * declares. Read every shape so a backend change cannot silently break sign-in.
+ */
+function extractToken(payload: AuthPayload | undefined): string | undefined {
+  return (
+    payload?.data?.accessToken ??
+    payload?.data?.token ??
+    payload?.accessToken ??
+    payload?.token
+  )
+}
+
+/** One shared id, so a retry replaces the toast instead of stacking a second one. */
+const TOAST_ID = "auth"
+
+function notify(message: string) {
+  toast.success(message, { id: TOAST_ID })
+}
+
+/** The screens also render an inline error; the toast is the app-level echo. */
+function reportAuthError(error: Error) {
+  toast.error(error.message || "Something went wrong. Please try again.", {
+    id: TOAST_ID,
+  })
+}
+
+/** Honours ?next= from a guarded route; relative same-origin paths only. */
+function useNextPath() {
+  const [params] = useSearchParams()
+  const next = params.get("next")
+  return next && next.startsWith("/") && !next.startsWith("//") ? next : "/"
+}
+
+export function SsoLogin() {
+  const navigate = useNavigate()
+  const { signIn } = useAuth()
+  const next = useNextPath()
+
+  return (
+    <Login
+      {...ssoProps}
+      classNames={authClassNames}
+      onSuccess={(data) => {
+        const token = extractToken(data)
+        if (!token) {
+          reportAuthError(new Error("Signed in, but no access token was returned."))
+          return
+        }
+        signIn(token)
+        notify("Signed in.")
+        navigate(next, { replace: true })
+      }}
+      onError={reportAuthError}
+      onForgotPassword={() => navigate("/forgot-password")}
+      onSignupClick={() => navigate("/signup")}
+    />
+  )
+}
+
+export function SsoSignup() {
+  const navigate = useNavigate()
+  const { signIn } = useAuth()
+  const next = useNextPath()
+
+  return (
+    <Signup
+      {...ssoProps}
+      classNames={authClassNames}
+      onSuccess={(data) => {
+        const token = extractToken(data)
+        // Projects requiring email verification return no session here.
+        if (!token) {
+          notify("Account created. Check your email to verify it.")
+          navigate("/login", { replace: true })
+          return
+        }
+        signIn(token)
+        notify("Account created.")
+        navigate(next, { replace: true })
+      }}
+      onError={reportAuthError}
+      onLoginClick={() => navigate("/login")}
+    />
+  )
+}
+
+/** Serves /forgot-password and /reset-password/:token — resetToken switches the step. */
+export function SsoForgotPassword() {
+  const navigate = useNavigate()
+  const { token: paramToken } = useParams()
+  const [params] = useSearchParams()
+  const resetToken = paramToken ?? params.get("token") ?? undefined
+
+  return (
+    <ForgotPassword
+      {...ssoProps}
+      classNames={authClassNames}
+      resetToken={resetToken}
+      onResetSuccess={() => {
+        notify("Password updated. Sign in with your new password.")
+        navigate("/login", { replace: true })
+      }}
+      onBackToLogin={() => navigate("/login")}
+      onError={reportAuthError}
+    />
+  )
+}
+
+/** Serves /verify/:token. */
+export function SsoVerifyEmail() {
+  const navigate = useNavigate()
+  const { token: paramToken } = useParams()
+  const [params] = useSearchParams()
+
+  return (
+    <VerifyEmail
+      {...ssoProps}
+      classNames={authClassNames}
+      token={paramToken ?? params.get("token") ?? undefined}
+      onVerified={() => {
+        notify("Email verified. You can sign in now.")
+        navigate("/login", { replace: true })
+      }}
+      onLoginClick={() => navigate("/login")}
+      onSignupClick={() => navigate("/signup")}
+      onError={reportAuthError}
+    />
+  )
+}

package/template/src/lib/sso/config.ts

@@ -0,0 +1,13 @@
+import { env } from "@/config/env"
+
+/** The three inputs every SDK component and function takes, bound once. */
+export const ssoConfig = {
+  projectId: env.authProjectId,
+  apiBaseUrl: env.authApiBaseUrl,
+} as const
+
+/** Spread into any SDK component: <Login {...ssoProps} /> */
+export const ssoProps = {
+  projectId: ssoConfig.projectId,
+  apiBaseUrl: ssoConfig.apiBaseUrl,
+} as const

package/template/src/lib/sso/entitlements.ts

@@ -0,0 +1,101 @@
+import { useMemo } from "react"
+
+import { useRawSubscription } from "./queries"
+
+export type Entitlements = {
+  isActive: boolean
+  planId: string
+  status: string
+  renewsAt: string
+  /** Main plan + packages + add-ons. */
+  subscribedIds: string[]
+  /** How many times each add-on id appears. */
+  packageCounts: Record<string, number>
+}
+
+const EMPTY: Entitlements = {
+  isActive: false,
+  planId: "",
+  status: "",
+  renewsAt: "",
+  subscribedIds: [],
+  packageCounts: {},
+}
+
+const ACTIVE_STATUSES = new Set(["paid", "active", "trialing", "trial"])
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null
+    ? (value as Record<string, unknown>)
+    : {}
+}
+
+function str(source: Record<string, unknown>, ...keys: string[]): string {
+  for (const key of keys) {
+    const value = source[key]
+    if (typeof value === "string" && value) return value
+    if (typeof value === "number") return String(value)
+  }
+  return ""
+}
+
+function ids(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value
+    .map((item) =>
+      typeof item === "string"
+        ? item
+        : str(asRecord(item), "id", "planId", "packageId", "addOnId"),
+    )
+    .filter(Boolean)
+}
+
+/**
+ * `getUserSubscription` returns the API response unmapped, so the field
+ * spellings are guessed here. Fix them HERE once and every gate follows.
+ */
+export function mapSubscription(raw: unknown): Entitlements {
+  const outer = asRecord(raw)
+  const source = "data" in outer ? asRecord(outer.data) : outer
+  if (Object.keys(source).length === 0) return EMPTY
+
+  const planId = str(source, "planId", "plan_id", "plan", "id")
+  const status = str(source, "status", "type", "state").toLowerCase()
+  const renewsAt = str(source, "renewsAt", "renews_at", "expiryDate", "expiry", "endDate")
+
+  const subscribedIds = [
+    ...(planId ? [planId] : []),
+    ...ids(source.packages),
+    ...ids(source.addOns ?? source.addons ?? source.add_ons),
+    ...ids(source.subscribedIds ?? source.subscribed_ids),
+  ]
+
+  const packageCounts: Record<string, number> = {}
+  for (const id of subscribedIds) {
+    packageCounts[id] = (packageCounts[id] ?? 0) + 1
+  }
+
+  const expiry = renewsAt ? Date.parse(renewsAt) : Number.NaN
+  const notExpired = Number.isNaN(expiry) || expiry > Date.now()
+
+  return {
+    isActive: Boolean(planId) && ACTIVE_STATUSES.has(status) && notExpired,
+    planId,
+    status,
+    renewsAt,
+    subscribedIds: [...new Set(subscribedIds)],
+    packageCounts,
+  }
+}
+
+export function useEntitlements() {
+  const query = useRawSubscription()
+  const entitlements = useMemo(() => mapSubscription(query.data), [query.data])
+
+  return {
+    ...entitlements,
+    isLoading: query.isPending,
+    has: (id: string) => entitlements.subscribedIds.includes(id),
+    countOf: (id: string) => entitlements.packageCounts[id] ?? 0,
+  }
+}

package/template/src/lib/sso/index.ts

@@ -0,0 +1,33 @@
+/**
+ * The single entry point for auth and billing. Product code imports from here,
+ * never from "ab-ecosystem-sso" directly.
+ */
+export { ssoConfig, ssoProps } from "./config"
+export { tokenStore } from "./token-store"
+export { AuthProvider } from "./auth-provider"
+export { useAuth, type AuthContextValue } from "./auth-context"
+export { ProtectedRoute, PublicOnlyRoute } from "./protected-route"
+export {
+  SsoLogin,
+  SsoSignup,
+  SsoForgotPassword,
+  SsoVerifyEmail,
+} from "./auth-screens"
+export { useAccountSettings, useRestoreAccountSettings } from "./account-settings"
+export {
+  ssoKeys,
+  useProfile,
+  useWallet,
+  useCreditWallets,
+  useRawSubscription,
+} from "./queries"
+export { useEntitlements, mapSubscription, type Entitlements } from "./entitlements"
+export { RequirePlan } from "./require-plan"
+
+export type {
+  AccountSettingsSection,
+  CreditWallet,
+  MappedProfile,
+  UserWallets,
+  WalletInfo,
+} from "ab-ecosystem-sso"

package/template/src/lib/sso/protected-route.tsx

@@ -0,0 +1,72 @@
+import { useCallback, useEffect, useState } from "react"
+import { Navigate, Outlet, useLocation } from "react-router-dom"
+import { SessionProvider } from "ab-ecosystem-sso"
+
+import { FullPageLoader } from "@/components/full-page-loader"
+import { useAuth } from "./auth-context"
+import { ssoProps } from "./config"
+
+type ProtectedRouteProps = {
+  /** Hard paywall: opens Account Settings on Plans when no subscription is active. */
+  enforceActiveSubscription?: boolean
+}
+
+/**
+ * Reports whether SessionProvider is currently rendering its children. It
+ * renders null while validating, so this is how we know to show the loader.
+ */
+function SessionReady({
+  onChange,
+  children,
+}: {
+  onChange: (ready: boolean) => void
+  children: React.ReactNode
+}) {
+  useEffect(() => {
+    onChange(true)
+    return () => onChange(false)
+  }, [onChange])
+
+  return <>{children}</>
+}
+
+/** No token → redirect without a round-trip. Token → SessionProvider validates it. */
+export function ProtectedRoute({ enforceActiveSubscription }: ProtectedRouteProps) {
+  const { token, signOut } = useAuth()
+  const location = useLocation()
+  const [ready, setReady] = useState(false)
+
+  // Both callbacks must keep a stable identity: onSessionInvalid is in
+  // SessionProvider's validation effect deps, so a new function on every
+  // render would re-validate — and blank the page — on every navigation.
+  const handleSessionInvalid = useCallback(() => void signOut(), [signOut])
+  const handleReadyChange = useCallback((next: boolean) => setReady(next), [])
+
+  if (!token) {
+    const next = encodeURIComponent(`${location.pathname}${location.search}`)
+    return <Navigate to={`/login?next=${next}`} replace />
+  }
+
+  return (
+    <>
+      {!ready && <FullPageLoader label="Checking your session…" />}
+      <SessionProvider
+        {...ssoProps}
+        token={token}
+        enforceActiveSubscription={enforceActiveSubscription}
+        // Clearing the token falls through to the redirect above, keeping ?next=.
+        onSessionInvalid={handleSessionInvalid}
+      >
+        <SessionReady onChange={handleReadyChange}>
+          <Outlet />
+        </SessionReady>
+      </SessionProvider>
+    </>
+  )
+}
+
+/** Keeps signed-in users off the auth screens. */
+export function PublicOnlyRoute() {
+  const { isAuthenticated } = useAuth()
+  return isAuthenticated ? <Navigate to="/" replace /> : <Outlet />
+}

package/template/src/lib/sso/queries.ts

@@ -0,0 +1,55 @@
+import { useQuery } from "@tanstack/react-query"
+import {
+  getUserCreditWallet,
+  getUserProfile,
+  getUserSubscription,
+  getUserWallet,
+} from "ab-ecosystem-sso"
+
+import { useAuth } from "./auth-context"
+import { ssoConfig } from "./config"
+
+/** The SDK's getters, pre-bound and cached. */
+export const ssoKeys = {
+  all: ["sso", ssoConfig.projectId] as const,
+  profile: () => [...ssoKeys.all, "profile"] as const,
+  wallet: () => [...ssoKeys.all, "wallet"] as const,
+  creditWallets: () => [...ssoKeys.all, "credit-wallets"] as const,
+  subscription: () => [...ssoKeys.all, "subscription"] as const,
+}
+
+function useSsoQuery<T>(key: readonly unknown[], fn: (token: string) => Promise<T>) {
+  const { token } = useAuth()
+  return useQuery({
+    queryKey: key,
+    queryFn: () => fn(token as string),
+    enabled: Boolean(token),
+    staleTime: 60_000,
+    retry: 1,
+  })
+}
+
+export function useProfile() {
+  return useSsoQuery(ssoKeys.profile(), (token) =>
+    getUserProfile(ssoConfig.projectId, token, ssoConfig.apiBaseUrl),
+  )
+}
+
+export function useWallet() {
+  return useSsoQuery(ssoKeys.wallet(), (token) =>
+    getUserWallet(ssoConfig.projectId, token, ssoConfig.apiBaseUrl),
+  )
+}
+
+export function useCreditWallets() {
+  return useSsoQuery(ssoKeys.creditWallets(), (token) =>
+    getUserCreditWallet(ssoConfig.projectId, token, ssoConfig.apiBaseUrl),
+  )
+}
+
+/** Raw and unmapped — prefer useEntitlements(). */
+export function useRawSubscription() {
+  return useSsoQuery(ssoKeys.subscription(), (token) =>
+    getUserSubscription(ssoConfig.projectId, token, ssoConfig.apiBaseUrl),
+  )
+}

package/template/src/lib/sso/require-plan.tsx

@@ -0,0 +1,19 @@
+import { useEntitlements } from "./entitlements"
+
+type RequirePlanProps = {
+  /** Item ids that unlock this area. Omit to require any active subscription. */
+  ids?: string[]
+  pending?: React.ReactNode
+  fallback?: React.ReactNode
+  children: React.ReactNode
+}
+
+/** Per-feature gate — the finer-grained version of enforceActiveSubscription. */
+export function RequirePlan({ ids, pending = null, fallback = null, children }: RequirePlanProps) {
+  const { isActive, isLoading, has } = useEntitlements()
+
+  if (isLoading) return <>{pending}</>
+
+  const entitled = ids?.length ? ids.some((id) => has(id)) : isActive
+  return <>{entitled ? children : fallback}</>
+}

package/template/src/lib/sso/token-store.ts

@@ -0,0 +1,62 @@
+/**
+ * The only place that touches token storage. Swap the strategy here and the
+ * whole app follows.
+ */
+const STORAGE_KEY = "authToken"
+
+/** Fallback when localStorage throws (private mode, blocked site data). */
+let memoryToken: string | null = null
+let usingMemory = false
+
+const listeners = new Set<() => void>()
+
+function emit() {
+  for (const listener of listeners) listener()
+}
+
+function read(): string | null {
+  if (usingMemory) return memoryToken
+  try {
+    return window.localStorage.getItem(STORAGE_KEY)
+  } catch {
+    usingMemory = true
+    return memoryToken
+  }
+}
+
+export const tokenStore = {
+  get: read,
+
+  set(token: string) {
+    memoryToken = token
+    try {
+      window.localStorage.setItem(STORAGE_KEY, token)
+    } catch {
+      usingMemory = true
+    }
+    emit()
+  },
+
+  clear() {
+    memoryToken = null
+    try {
+      window.localStorage.removeItem(STORAGE_KEY)
+    } catch {
+      usingMemory = true
+    }
+    emit()
+  },
+
+  /** For useSyncExternalStore. Also fires when another tab signs in or out. */
+  subscribe(listener: () => void) {
+    listeners.add(listener)
+    const onStorage = (event: StorageEvent) => {
+      if (event.key === STORAGE_KEY || event.key === null) listener()
+    }
+    window.addEventListener("storage", onStorage)
+    return () => {
+      listeners.delete(listener)
+      window.removeEventListener("storage", onStorage)
+    }
+  },
+}

package/template/src/lib/utils.ts

@@ -0,0 +1 @@
+export { cn } from "cn"

package/template/src/main.tsx

@@ -0,0 +1,42 @@
+import { StrictMode } from "react"
+import { createRoot } from "react-dom/client"
+import { BrowserRouter } from "react-router-dom"
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
+import { ThemeProvider } from "next-themes"
+
+import App from "@/App"
+import { MissingEnv } from "@/components/missing-env"
+import { Toaster } from "@/components/ui/sonner"
+import { TooltipProvider } from "@/components/ui/tooltip"
+import { missingRequiredEnv } from "@/config/env"
+import { AuthProvider } from "@/lib/sso"
+import "@/index.css"
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { refetchOnWindowFocus: false, retry: 1 },
+  },
+})
+
+const missing = missingRequiredEnv()
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    {missing.length > 0 ? (
+      <MissingEnv missing={missing} />
+    ) : (
+      <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
+        <QueryClientProvider client={queryClient}>
+          <BrowserRouter>
+            <AuthProvider>
+              <TooltipProvider>
+                <App />
+                <Toaster richColors closeButton />
+              </TooltipProvider>
+            </AuthProvider>
+          </BrowserRouter>
+        </QueryClientProvider>
+      </ThemeProvider>
+    )}
+  </StrictMode>,
+)

package/template/src/routes/app/example.tsx

@@ -0,0 +1,125 @@
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card"
+import { Button } from "@/components/ui/button"
+import { Code, Note } from "@/components/docs/doc-primitives"
+import {
+  RequirePlan,
+  useAccountSettings,
+  useCreditWallets,
+  useEntitlements,
+  useProfile,
+  useWallet,
+} from "@/lib/sso"
+
+/** Live data from the SDK — the hooks in the guides, actually running. */
+export default function ExamplePage() {
+  const { data: profile } = useProfile()
+  const { data: wallets } = useWallet()
+  const { data: credits } = useCreditWallets()
+  const { isActive, planId, status, renewsAt } = useEntitlements()
+  const { open } = useAccountSettings()
+
+  return (
+    <div className="mx-auto flex w-full max-w-3xl flex-col gap-6 pb-16">
+      <div>
+        <h1 className="text-2xl font-semibold tracking-tight">
+          Welcome back{profile?.firstName ? `, ${profile.firstName}` : ""}
+        </h1>
+        <p className="text-muted-foreground text-sm">
+          Every value below comes from <Code>@/lib/sso</Code> against your live
+          project.
+        </p>
+      </div>
+
+      <div className="grid gap-4 md:grid-cols-3">
+        <Card>
+          <CardHeader>
+            <CardTitle>Subscription</CardTitle>
+            <CardDescription>
+              {isActive
+                ? `Active${renewsAt ? ` · renews ${renewsAt}` : ""}`
+                : "No active plan"}
+            </CardDescription>
+          </CardHeader>
+          <CardContent className="flex flex-col gap-3">
+            <div className="truncate text-2xl font-semibold">{planId || "—"}</div>
+            <div className="text-muted-foreground text-xs">
+              status: {status || "none"}
+            </div>
+            <Button
+              variant={isActive ? "outline" : "default"}
+              onClick={() => open("plans")}
+            >
+              {isActive ? "Manage plan" : "Choose a plan"}
+            </Button>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>Wallet</CardTitle>
+            <CardDescription>Main balance</CardDescription>
+          </CardHeader>
+          <CardContent className="flex flex-col gap-3">
+            <div className="text-2xl font-semibold">
+              {wallets?.mainWallet?.balanceFormatted ?? "—"}
+            </div>
+            <Button variant="outline" onClick={() => open("wallet")}>
+              Add funds
+            </Button>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>Credits</CardTitle>
+            <CardDescription>{credits?.length ?? 0} wallet(s)</CardDescription>
+          </CardHeader>
+          <CardContent className="flex flex-col gap-3">
+            <div className="text-2xl font-semibold">
+              {credits?.[0]?.balanceFormatted ?? "—"}
+            </div>
+            <Button variant="outline" onClick={() => open("credits")}>
+              Top up
+            </Button>
+          </CardContent>
+        </Card>
+      </div>
+
+      <RequirePlan
+        fallback={
+          <Card>
+            <CardHeader>
+              <CardTitle>Pro reports</CardTitle>
+              <CardDescription>Available on a paid plan.</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Button onClick={() => open("plans")}>Upgrade</Button>
+            </CardContent>
+          </Card>
+        }
+      >
+        <Card>
+          <CardHeader>
+            <CardTitle>Pro reports</CardTitle>
+            <CardDescription>Unlocked by your subscription.</CardDescription>
+          </CardHeader>
+          <CardContent className="text-muted-foreground text-sm">
+            Replace this with real product content.
+          </CardContent>
+        </Card>
+      </RequirePlan>
+
+      <Note>
+        The card above is wrapped in <Code>{"<RequirePlan>"}</Code> with no{" "}
+        <Code>ids</Code>, so it requires any active subscription. Pass{" "}
+        <Code>ids={"{[\"addon-x\"]}"}</Code> to gate on a specific add-on instead.
+      </Note>
+    </div>
+  )
+}

package/template/src/routes/auth/forgot-password.tsx

@@ -0,0 +1,5 @@
+import { SsoForgotPassword } from "@/lib/sso"
+
+export default function ForgotPasswordPage() {
+  return <SsoForgotPassword />
+}