create-ab-app 0.1.1

package/template/src/routes/auth/login.tsx

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

package/template/src/routes/auth/signup.tsx

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

package/template/src/routes/auth/verify-email.tsx

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

package/template/src/routes/docs/api.tsx

@@ -0,0 +1,66 @@
+import {
+  Code,
+  CodeBlock,
+  DocPage,
+  Note,
+  P,
+  Section,
+} from "@/components/docs/doc-primitives"
+
+export default function ApiPage() {
+  return (
+    <DocPage
+      title="Your own API"
+      summary="Calling your product backend with the same session."
+    >
+      <Section title="The client">
+        <P>
+          <Code>src/lib/http.ts</Code> is for your API — the SDK owns the auth
+          backend. It attaches the bearer token from the same store and treats a 401
+          the way the SDK treats an invalid session.
+        </P>
+        <CodeBlock>{`import { api } from "@/lib/http"
+
+const projects = await api<Project[]>("/projects")
+
+await api<Project>("/projects", {
+  method: "POST",
+  body: JSON.stringify({ name: "New project" }),
+})`}</CodeBlock>
+        <P>
+          JSON content-type is set automatically when there is a body, and a
+          non-2xx response throws <Code>HttpError</Code> carrying{" "}
+          <Code>status</Code> and the parsed <Code>body</Code>.
+        </P>
+      </Section>
+
+      <Section title="401 handling">
+        <Note>
+          On a 401 the token is cleared. <Code>useAuth()</Code> is subscribed to the
+          token store, so the guard re-renders and redirects to{" "}
+          <Code>/login?next=…</Code> without any extra wiring at the call site.
+        </Note>
+      </Section>
+
+      <Section title="With TanStack Query">
+        <P>
+          Query is already installed and configured. Follow the pattern in{" "}
+          <Code>src/lib/sso/queries.ts</Code>: key by resource, gate on the token,
+          and let the 401 path handle expiry.
+        </P>
+        <CodeBlock>{`export function useProjects() {
+  const { token } = useAuth()
+  return useQuery({
+    queryKey: ["projects"],
+    queryFn: () => api<Project[]>("/projects"),
+    enabled: Boolean(token),
+  })
+}`}</CodeBlock>
+        <P>
+          Signing out calls <Code>queryClient.clear()</Code>, so cached data from one
+          account can never be shown to the next.
+        </P>
+      </Section>
+    </DocPage>
+  )
+}

package/template/src/routes/docs/auth.tsx

@@ -0,0 +1,145 @@
+import {
+  Cell,
+  Code,
+  CodeBlock,
+  DocPage,
+  List,
+  Note,
+  P,
+  Row,
+  Section,
+  Table,
+} from "@/components/docs/doc-primitives"
+
+export default function AuthPage() {
+  return (
+    <DocPage
+      title="Auth"
+      summary="How a token gets from the login screen into every request."
+    >
+      <Section title="The screens are the API">
+        <P>
+          The SDK exports no <Code>loginApi</Code> or <Code>signupApi</Code>. Sign-in
+          and sign-up are reachable only through its components — which is also what
+          gives you the project's captcha config, the 2FA step and magic-link sign-in
+          for free.
+        </P>
+        <P>
+          So <Code>src/lib/sso/auth-screens.tsx</Code> wraps each SDK screen once,
+          binding it to config, the token store and the router. Route files are one
+          line:
+        </P>
+        <CodeBlock>{`export default function LoginPage() {
+  return <SsoLogin />
+}`}</CodeBlock>
+        <Note>
+          The auth pages have no layout wrapper. Each SDK screen already renders a
+          full-page centered root plus its own card and branding, so wrapping it
+          would double-wrap. Restyle with the <Code>classNames</Code> prop from{" "}
+          <Code>auth-screens.tsx</Code>, or the <Code>--aas-*</Code> theme bridge.
+        </Note>
+      </Section>
+
+      <Section title="The response shape">
+        <P>
+          <Code>onSuccess</Code> receives the raw API envelope, not the{" "}
+          <Code>{"{ token, user }"}</Code> the SDK's <Code>AuthResponse</Code> type
+          declares:
+        </P>
+        <CodeBlock>{`{
+  "success": true,
+  "message": "Login successful",
+  "data": { "accessToken": "eyJhbGciOi…" }
+}`}</CodeBlock>
+        <Note tone="warn" title="TypeScript will not catch this">
+          <Code>onSuccess</Code> is typed <Code>(data: any)</Code>, so reading the
+          wrong field compiles fine and silently does nothing.{" "}
+          <Code>extractToken()</Code> reads <Code>data.accessToken</Code> first and
+          falls back through the other spellings; a response with no token raises an
+          error toast rather than failing quietly.
+        </Note>
+      </Section>
+
+      <Section title="Token lifecycle">
+        <Table head={["Step", "What happens"]}>
+          <Row>
+            <Cell>Sign in</Cell>
+            <Cell>
+              <Code>signIn(token)</Code> writes to <Code>tokenStore</Code> (
+              <Code>localStorage</Code>, key <Code>authToken</Code>).
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>Every render</Cell>
+            <Cell>
+              <Code>useAuth()</Code> reads it via{" "}
+              <Code>useSyncExternalStore</Code>, so a sign-out in another tab updates
+              this one.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>SDK calls</Cell>
+            <Cell>
+              The bound hooks in <Code>queries.ts</Code> pass it to the SDK getters.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>Your API</Cell>
+            <Cell>
+              <Code>api()</Code> attaches <Code>Authorization: Bearer …</Code>.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>Sign out</Cell>
+            <Cell>
+              <Code>logoutApi</Code> is called, then the token and the whole query
+              cache are cleared — local sign-out succeeds even if the network call
+              fails.
+            </Cell>
+          </Row>
+        </Table>
+        <Note tone="warn" title="Two things to know">
+          <List>
+            <li>
+              The token lives in <Code>localStorage</Code>, so an XSS bug exposes it.
+              The SDK has no refresh flow, which makes this the pragmatic choice.
+              Swapping strategy is a one-file change in <Code>token-store.ts</Code>.
+            </li>
+            <li>
+              Tokens are valid for 24 hours. There is no silent refresh — after that
+              the next call 401s and the guard bounces to <Code>/login</Code>.
+            </li>
+          </List>
+        </Note>
+      </Section>
+
+      <Section title="Session validation">
+        <P>
+          <Code>ProtectedRoute</Code> renders the SDK's <Code>SessionProvider</Code>,
+          which validates the token against <Code>/me</Code> and renders its children
+          only when the session is valid.
+        </P>
+        <Note tone="warn" title="Keep the callbacks stable">
+          <Code>onSessionInvalid</Code> is in that provider's validation effect
+          dependencies, and the effect starts by setting <Code>isValidating</Code> —
+          during which it renders <Code>null</Code>. Passing a fresh inline arrow
+          re-validates and blanks the page on every navigation. It is wrapped in{" "}
+          <Code>useCallback</Code> for exactly this reason.
+        </Note>
+      </Section>
+
+      <Section title="What has no callback">
+        <P>
+          Forgot-password (the request-a-link step) exposes only{" "}
+          <Code>onError</Code>, <Code>onResetSuccess</Code> and{" "}
+          <Code>onBackToLogin</Code> — there is no success hook, and no exported
+          function to call directly, so it shows its own inline confirmation.
+        </P>
+        <P>
+          Resending a verification email does not exist in the SDK at all: no
+          exported function, no endpoint, no UI.
+        </P>
+      </Section>
+    </DocPage>
+  )
+}

package/template/src/routes/docs/billing.tsx

@@ -0,0 +1,103 @@
+import {
+  Cell,
+  Code,
+  CodeBlock,
+  DocPage,
+  Note,
+  P,
+  Row,
+  Section,
+  Table,
+} from "@/components/docs/doc-primitives"
+
+export default function BillingPage() {
+  return (
+    <DocPage
+      title="Billing & plans"
+      summary="Plans, add-ons, wallets and credits — and how to gate features on them."
+    >
+      <Section title="There is no billing page">
+        <P>
+          The SDK's Account Settings modal already covers profile, security, plans
+          and add-ons, wallet balance and credit wallets. A dedicated route would
+          either duplicate it or just be a button that opens it — so the user menus
+          in the sidebar and header open it directly.
+        </P>
+        <CodeBlock>{`const { open } = useAccountSettings()
+
+open("plans")     // "general" | "account" | "wallet" | "plans" | "credits"`}</CodeBlock>
+        <P>
+          The modal performs its own API calls. The template passes{" "}
+          <Code>onChangePlan</Code>, <Code>onAddFunds</Code> and{" "}
+          <Code>onSaveProfile</Code> as observers so cached copies — the sidebar
+          balance, feature gates — refresh when something changes inside it.
+        </P>
+      </Section>
+
+      <Section title="Two strengths of gating">
+        <Table head={["Level", "Use"]}>
+          <Row>
+            <Cell>
+              <Code>enforceActiveSubscription</Code>
+            </Cell>
+            <Cell>
+              Hard paywall on the whole shell. Add it to{" "}
+              <Code>{"<ProtectedRoute />"}</Code> in <Code>App.tsx</Code>; the SDK
+              opens Account Settings on Plans when no subscription is active.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>{"<RequirePlan />"}</Code>
+            </Cell>
+            <Cell>Per-feature. Wrap a route, a panel, or a button.</Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>useEntitlements()</Code>
+            </Cell>
+            <Cell>
+              Imperative checks: <Code>isActive</Code>, <Code>has(id)</Code>,{" "}
+              <Code>countOf(id)</Code>.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>requiresIds</Code>
+            </Cell>
+            <Cell>
+              On a nav item in <Code>navigation.ts</Code> — hides the entry unless
+              the user is entitled.
+            </Cell>
+          </Row>
+        </Table>
+        <CodeBlock>{`<RequirePlan ids={["addon-exports"]} fallback={<Upgrade />}>
+  <ExportButton />
+</RequirePlan>`}</CodeBlock>
+      </Section>
+
+      <Section title="Check this first when gates misbehave">
+        <Note tone="warn" title="mapSubscription() is guessing">
+          <Code>getUserSubscription</Code> returns the API response unmapped — the
+          SDK maps its other getters but explicitly not this one. So{" "}
+          <Code>mapSubscription()</Code> in <Code>entitlements.ts</Code> accepts
+          several plausible field spellings (<Code>planId</Code>,{" "}
+          <Code>plan_id</Code>, <Code>renewsAt</Code>, <Code>expiryDate</Code>, …).
+          <br />
+          <br />
+          Log one real payload, correct the readers in that one function, and every
+          gate in the app follows.
+        </Note>
+      </Section>
+
+      <Section title="Credits">
+        <P>
+          Credit wallets are the metered-billing story: each has a balance, a unit, a
+          fund source and whether it can be topped up.{" "}
+          <Code>useCreditWallets()</Code> returns them, and the sidebar footer shows
+          the first one as a shortcut into the Credits section.
+        </P>
+      </Section>
+    </DocPage>
+  )
+}

package/template/src/routes/docs/configuration.tsx

@@ -0,0 +1,113 @@
+import {
+  Cell,
+  Code,
+  CodeBlock,
+  DocPage,
+  Note,
+  P,
+  Row,
+  Section,
+  Table,
+} from "@/components/docs/doc-primitives"
+
+export default function ConfigurationPage() {
+  return (
+    <DocPage
+      title="Configuration"
+      summary="Environment variables, the preflight check, and what to pin."
+    >
+      <Section title="Environment">
+        <CodeBlock>{`# Required — your project id in the partner ecosystem.
+VITE_AUTH_PROJECT_ID=436582-forms.abprojects.com
+
+# Auth-as-a-Service origin. The SDK also reads this var directly.
+VITE_AUTH_API_BASE_URL=https://partner-api.example.com
+
+# Your own product API (src/lib/http.ts). Unrelated to auth.
+VITE_API_BASE_URL=
+
+# Shown in the sidebar header and breadcrumb.
+VITE_APP_NAME=Acme Inc`}</CodeBlock>
+        <P>
+          Copy <Code>.env.example</Code> to <Code>.env.local</Code>. Vite only
+          exposes variables prefixed with <Code>VITE_</Code>, and it reads them at
+          startup — restart the dev server after editing.
+        </P>
+      </Section>
+
+      <Section title="Preflight">
+        <P>
+          <Code>missingRequiredEnv()</Code> in <Code>src/config/env.ts</Code> runs
+          before the app mounts. If <Code>VITE_AUTH_PROJECT_ID</Code> is missing,{" "}
+          <Code>main.tsx</Code> renders a setup screen naming it instead of booting
+          an app whose every request will fail.
+        </P>
+        <P>Add your own required variables to that function as the app grows.</P>
+      </Section>
+
+      <Section title="Where the values are used">
+        <Table head={["Variable", "Read by"]}>
+          <Row>
+            <Cell>
+              <Code>VITE_AUTH_PROJECT_ID</Code>
+            </Cell>
+            <Cell>
+              <Code>ssoConfig</Code> — every SDK component and getter.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>VITE_AUTH_API_BASE_URL</Code>
+            </Cell>
+            <Cell>Passed explicitly to the SDK so the value is traceable.</Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>VITE_API_BASE_URL</Code>
+            </Cell>
+            <Cell>
+              <Code>api()</Code> in <Code>src/lib/http.ts</Code>.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>VITE_APP_NAME</Code>
+            </Cell>
+            <Cell>Sidebar header and breadcrumb root.</Cell>
+          </Row>
+        </Table>
+        <Note>
+          Branding on the auth screens comes from the backend's{" "}
+          <Code>auth-config</Code> (logo, card layout, terms and privacy links) — not
+          from <Code>VITE_APP_NAME</Code>. If those screens look unbranded, it is a
+          backend configuration gap.
+        </Note>
+      </Section>
+
+      <Section title="Version pinning">
+        <Note tone="warn" title="ab-ecosystem-sso is pinned exactly">
+          It is pre-1.0, so minor releases can break. The version in{" "}
+          <Code>package.json</Code> has no caret. Upgrade deliberately, and check the
+          auth screens and the Account Settings modal afterwards.
+        </Note>
+      </Section>
+
+      <Section title="Scripts">
+        <CodeBlock>{`npm run dev        Vite dev server
+npm run build      tsc -b && vite build
+npm run typecheck  tsc -b
+npm run lint       oxlint
+npm run preview    Serve the production build`}</CodeBlock>
+      </Section>
+
+      <Section title="Deploying">
+        <P>
+          This is a single-page app, so deep links need a rewrite to{" "}
+          <Code>index.html</Code>. <Code>public/_redirects</Code> (Netlify) and{" "}
+          <Code>vercel.json</Code> are included; other hosts need the equivalent or
+          every refresh on a nested route 404s.
+        </P>
+      </Section>
+    </DocPage>
+  )
+}

package/template/src/routes/docs/overview.tsx

@@ -0,0 +1,97 @@
+import { Link } from "react-router-dom"
+
+import {
+  Cell,
+  Code,
+  CodeBlock,
+  DocPage,
+  List,
+  Note,
+  P,
+  Row,
+  Section,
+  Table,
+} from "@/components/docs/doc-primitives"
+import { Button } from "@/components/ui/button"
+
+export default function OverviewPage() {
+  return (
+    <DocPage
+      title="Overview"
+      summary="A React + Vite starter with authentication and billing already wired up. This app is the documentation — replace it with your product."
+    >
+      <Section title="What you get">
+        <List>
+          <li>React 19, Vite, TypeScript (strict) and Tailwind v4.</li>
+          <li>
+            shadcn/ui components, with the <Code>sidebar-07</Code> block as the app
+            shell.
+          </li>
+          <li>
+            Auth and billing from <Code>ab-ecosystem-sso</Code> — login, signup, 2FA,
+            magic links, password reset, email verification, plans, wallets and
+            credits.
+          </li>
+          <li>Route guards, entitlement gating, toasts and a theme toggle.</li>
+        </List>
+      </Section>
+
+      <Section title="Start here">
+        <CodeBlock>{`cp .env.example .env.local   # set VITE_AUTH_PROJECT_ID
+npm install
+npm run dev`}</CodeBlock>
+        <P>
+          Without a project id the app renders a setup screen naming the missing
+          variable, rather than failing on an opaque network error.
+        </P>
+      </Section>
+
+      <Section title="The one rule">
+        <Note title="Import from @/lib/sso, never from ab-ecosystem-sso">
+          Every SDK call takes <Code>(projectId, token, apiBaseUrl)</Code>. Those are
+          bound once in <Code>src/lib/sso/config.ts</Code>, so nothing downstream
+          repeats them — and upgrading the SDK is a change to one folder.
+        </Note>
+      </Section>
+
+      <Section title="What to delete first">
+        <P>
+          These docs pages exist to explain the template, not to ship with your
+          product. When you start building:
+        </P>
+        <Table head={["Delete", "Then"]}>
+          <Row>
+            <Cell>
+              <Code>src/routes/docs/</Code>
+            </Cell>
+            <Cell>Point the router at your own pages.</Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>src/routes/app/example.tsx</Code>
+            </Cell>
+            <Cell>Keep it while you learn the hooks; delete it after.</Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>src/config/navigation.ts</Code>
+            </Cell>
+            <Cell>Replace the three groups with your product's nav.</Cell>
+          </Row>
+        </Table>
+      </Section>
+
+      <Section title="Next">
+        <div className="flex flex-wrap gap-2">
+          <Button render={<Link to="/docs/structure" />}>Project structure</Button>
+          <Button variant="outline" render={<Link to="/docs/auth" />}>
+            How auth works
+          </Button>
+          <Button variant="outline" render={<Link to="/example" />}>
+            Live example
+          </Button>
+        </div>
+      </Section>
+    </DocPage>
+  )
+}

package/template/src/routes/docs/routing.tsx

@@ -0,0 +1,126 @@
+import {
+  Cell,
+  Code,
+  CodeBlock,
+  DocPage,
+  Note,
+  P,
+  Row,
+  Section,
+  Table,
+} from "@/components/docs/doc-primitives"
+
+export default function RoutingPage() {
+  return (
+    <DocPage
+      title="Routing & guards"
+      summary="React Router v7, two guards, and the routes the SDK requires."
+    >
+      <Section title="Route map">
+        <Table head={["Route", "Guard", "Renders"]}>
+          <Row>
+            <Cell>
+              <Code>/login</Code>
+            </Cell>
+            <Cell>PublicOnlyRoute</Cell>
+            <Cell>
+              SsoLogin — also consumes a <Code>#access_token</Code> magic-link hash
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>/signup</Code>
+            </Cell>
+            <Cell>PublicOnlyRoute</Cell>
+            <Cell>SsoSignup</Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>/forgot-password</Code>
+            </Cell>
+            <Cell>PublicOnlyRoute</Cell>
+            <Cell>SsoForgotPassword — request a link</Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>/reset-password/:token</Code>
+            </Cell>
+            <Cell>none</Cell>
+            <Cell>SsoForgotPassword — set a new password</Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>/verify/:token</Code>
+            </Cell>
+            <Cell>none</Cell>
+            <Cell>SsoVerifyEmail</Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>/</Code>, <Code>/docs/*</Code>, <Code>/example</Code>
+            </Cell>
+            <Cell>ProtectedRoute</Cell>
+            <Cell>AppLayout shell</Cell>
+          </Row>
+        </Table>
+        <Note>
+          The two token routes sit outside <Code>PublicOnlyRoute</Code> on purpose: a
+          user who just signed up is already signed in, and must still be able to
+          verify or reset. Guarding them would make the emailed links silently
+          redirect to the dashboard.
+        </Note>
+        <P>
+          <Code>/reset-password?token=</Code> and <Code>/verify-email?token=</Code>{" "}
+          are kept as aliases in case a link carries the token as a query string.
+        </P>
+      </Section>
+
+      <Section title="ProtectedRoute">
+        <P>Two layers, deliberately:</P>
+        <CodeBlock>{`// 1. No token at all → redirect immediately, no network round-trip.
+if (!token) return <Navigate to={\`/login?next=\${next}\`} replace />
+
+// 2. Token present → SessionProvider validates it against /me
+//    and renders children only when the session is genuinely valid.`}</CodeBlock>
+        <P>
+          <Code>onSessionInvalid</Code> only calls <Code>signOut()</Code>. Clearing
+          the token falls through to the redirect above, which preserves the
+          attempted path in <Code>?next=</Code> — so there is one redirect path, not
+          two.
+        </P>
+      </Section>
+
+      <Section title="The loading screen">
+        <Note tone="warn" title="SessionProvider renders null while validating">
+          That is a blank page on every protected load unless something covers it.{" "}
+          <Code>ProtectedRoute</Code> renders a full-page loader as a sibling and
+          hides it via a <Code>SessionReady</Code> child that reports mount and
+          unmount — children only mount once the session validates, so no duplicate{" "}
+          <Code>/me</Code> call is needed to know when to hide it.
+        </Note>
+      </Section>
+
+      <Section title="Redirect safety">
+        <P>
+          <Code>?next=</Code> is only honoured for relative same-origin paths —{" "}
+          <Code>useNextPath()</Code> rejects anything not starting with a single{" "}
+          <Code>/</Code>, so the parameter cannot be used as an open redirect.
+        </P>
+      </Section>
+
+      <Section title="Adding a route">
+        <CodeBlock>{`// src/App.tsx — inside the ProtectedRoute / AppLayout block
+<Route path="/reports" element={<ReportsPage />} />
+
+// src/config/navigation.ts — to give it a sidebar entry
+{ title: "Reports", url: "/reports", icon: BarChartIcon,
+  requiresIds: ["addon-reports"] }   // optional gating`}</CodeBlock>
+        <P>
+          Nav items render through the router's <Code>Link</Code>, not{" "}
+          <Code>{"<a href>"}</Code> — a plain anchor would full-page reload and throw
+          away in-memory state on every click.
+        </P>
+      </Section>
+    </DocPage>
+  )
+}