@woodsportal/hubspot-kit 1.0.41-dev.4 → 1.0.41-dev.6

package/templates/scaffold/auth/_shared/src/features/starter/components/starter-guide-page.tsx

@@ -0,0 +1,218 @@
+import { SectionCard } from '@/components/layout/section-card'
+import { Link } from '@/components/ui/link'
+import { AUTH_SCAFFOLD_TIER } from '@/config/auth-tier'
+import { NAV_SCAFFOLD_MODE } from '@/config/nav-scaffold'
+import { Routes } from '@/config/routes'
+import {
+  AUTH_BOOT_STEPS,
+  AUTH_ENV_VARS,
+  AUTH_INIT_EXAMPLES,
+  AUTH_NAV_EXAMPLES,
+  PAGE_SCAFFOLD_EXAMPLES,
+  AUTH_PROJECT_PATHS,
+  AUTH_TIER_DESCRIPTION,
+  PORTAL_AUTH_VS_HUBSPOT,
+  authRoutesForTier,
+} from '@/features/starter/content/auth-guide-content'
+import {
+  DEV_WORKFLOW,
+  PROJECT_LAYOUT,
+  WOODSCLI_ABOUT,
+  WOODSCLI_COMMANDS,
+} from '@/features/starter/content/woodscli-guide-content'
+import { StarterPageFrame } from '@/features/starter/components/starter-page-frame'
+
+export function StarterGuidePage() {
+  const tier = AUTH_SCAFFOLD_TIER
+  const routes = authRoutesForTier(tier)
+
+  return (
+    <StarterPageFrame
+      className="max-w-4xl"
+      title="Developer guide"
+      description={
+        <>
+          WoodsCLI module with portal auth (<strong>{tier}</strong> tier). Use this page for
+          commands, project layout, and auth wiring — then replace the starter features with your CRM
+          UI under <code className="rounded bg-gray-100 px-1 text-xs">src/features/</code>.
+        </>
+      }
+    >
+      <div className="space-y-6">
+        <SectionCard title={`Portal auth — ${tier} tier`}>
+          <p className="text-sm leading-relaxed text-[#516f90]">{AUTH_TIER_DESCRIPTION[tier]}</p>
+          <ul className="mt-4 list-disc space-y-2 pl-5 text-sm text-[#516f90]">
+            <li>
+              <Link to={Routes.login}>Sign in</Link> at <code className="font-mono text-xs">/#/login</code>{' '}
+              (posts <code className="font-mono text-xs">username</code> + password to{' '}
+              <code className="font-mono text-xs">/api/auth/login</code>).
+            </li>
+            <li>
+              After login, visit the protected sample at{' '}
+              <Link to={Routes.portal}>/portal</Link> — session + profile via{' '}
+              <code className="font-mono text-xs">GET /api/auth/me</code>.
+            </li>
+            <li>
+              Set <code className="font-mono text-xs">VITE_PUBLIC_REST_API_ENDPOINT</code> in{' '}
+              <code className="font-mono text-xs">.env.local</code> after{' '}
+              <code className="font-mono text-xs">wp setup</code>.
+            </li>
+          </ul>
+          <p className="mt-4 text-xs text-[#516f90]">
+            Re-scaffold:{' '}
+            <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono">{AUTH_INIT_EXAMPLES[tier]}</code>
+          </p>
+        </SectionCard>
+
+        <SectionCard title={`Navigation — ${NAV_SCAFFOLD_MODE} shell`}>
+          <p className="text-sm leading-relaxed text-[#516f90]">
+            Menu links come from{' '}
+            <code className="rounded bg-gray-100 px-1 text-xs">src/config/portal-nav.ts</code> — edit
+            once for both top nav and sidebar layouts.
+          </p>
+          <p className="mt-4 text-xs text-[#516f90]">
+            Sidebar init:{' '}
+            <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono">
+              {AUTH_NAV_EXAMPLES.sidebar}
+            </code>
+          </p>
+          <ul className="mt-4 space-y-2 text-xs text-[#516f90]">
+            {PAGE_SCAFFOLD_EXAMPLES.map((cmd) => (
+              <li key={cmd}>
+                <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono">{cmd}</code>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Auth routes (this tier)">
+          <ul className="divide-y divide-[#eaf0f6]">
+            {routes.map(({ path, access }) => (
+              <li key={path} className="flex flex-col gap-1 py-3 first:pt-0 last:pb-0 sm:flex-row sm:gap-4">
+                <code className="shrink-0 rounded bg-[#eaf0f6] px-2 py-1 font-mono text-xs text-[#0091ae]">
+                  {path}
+                </code>
+                <span className="text-sm leading-relaxed text-[#516f90]">{access}</span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Two auth concepts">
+          <ul className="space-y-4">
+            {PORTAL_AUTH_VS_HUBSPOT.map(({ label, cmds, purpose }) => (
+              <li key={label}>
+                <h3 className="text-sm font-medium text-[#33475b]">{label}</h3>
+                <p className="mt-1 font-mono text-xs text-[#0091ae]">{cmds}</p>
+                <p className="mt-1 text-sm leading-relaxed text-[#516f90]">{purpose}</p>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Environment (.env.local)">
+          <ul className="space-y-3">
+            {AUTH_ENV_VARS.map(({ name, note }) => (
+              <li key={name} className="text-sm leading-relaxed">
+                <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono text-xs text-[#33475b]">
+                  {name}
+                </code>
+                <span className="mt-1 block text-[#516f90] sm:mt-0 sm:inline sm:before:content-['—_']">
+                  {note}
+                </span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Session boot order">
+          <ol className="list-decimal space-y-2 pl-5 text-sm leading-relaxed text-[#516f90]">
+            {AUTH_BOOT_STEPS.map((step) => (
+              <li key={step}>{step}</li>
+            ))}
+          </ol>
+        </SectionCard>
+
+        <SectionCard title="About WoodsCLI">
+          <p className="text-sm leading-relaxed text-[#516f90]">{WOODSCLI_ABOUT.tagline}</p>
+          <p className="mt-3 text-sm leading-relaxed text-[#516f90]">{WOODSCLI_ABOUT.docsHint}</p>
+        </SectionCard>
+
+        <SectionCard title="Essential commands">
+          <ul className="divide-y divide-[#eaf0f6]">
+            {WOODSCLI_COMMANDS.map(({ cmd, desc }) => (
+              <li key={cmd} className="flex flex-col gap-1 py-3 first:pt-0 last:pb-0 sm:flex-row sm:gap-4">
+                <code className="shrink-0 rounded bg-[#eaf0f6] px-2 py-1 font-mono text-xs text-[#0091ae]">
+                  {cmd}
+                </code>
+                <span className="text-sm leading-relaxed text-[#516f90]">{desc}</span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Auth-related paths">
+          <ul className="space-y-3">
+            {AUTH_PROJECT_PATHS.map(({ path, note }) => (
+              <li key={path} className="text-sm leading-relaxed">
+                <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono text-xs text-[#33475b]">
+                  {path}
+                </code>
+                <span className="mt-1 block text-[#516f90] sm:mt-0 sm:inline sm:before:content-['—_']">
+                  {note}
+                </span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Project layout">
+          <ul className="space-y-3">
+            {PROJECT_LAYOUT.map(({ path, note }) => (
+              <li key={path} className="text-sm leading-relaxed">
+                <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono text-xs text-[#33475b]">
+                  {path}
+                </code>
+                <span className="mt-1 block text-[#516f90] sm:mt-0 sm:inline sm:before:content-['—_']">
+                  {note}
+                </span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Developer workflow">
+          <ol className="space-y-4">
+            <li>
+              <h3 className="text-sm font-medium text-[#33475b]">0 · Verify portal login</h3>
+              <p className="mt-1 text-sm leading-relaxed text-[#516f90]">
+                Run <code className="font-mono text-xs">wp dev</code>, open{' '}
+                <Link to={Routes.login}>/#/login</Link>, and confirm you reach{' '}
+                <Link to={Routes.portal}>/portal</Link> with an active session before building CRM
+                features.
+              </p>
+            </li>
+            {DEV_WORKFLOW.map(({ title: stepTitle, body }) => (
+              <li key={stepTitle}>
+                <h3 className="text-sm font-medium text-[#33475b]">{stepTitle}</h3>
+                <p className="mt-1 text-sm leading-relaxed text-[#516f90]">{body}</p>
+              </li>
+            ))}
+          </ol>
+        </SectionCard>
+
+        <SectionCard title="Routing & customization">
+          <p className="text-sm leading-relaxed text-[#516f90]">
+            File routes live under <code className="font-mono text-xs">src/routes/</code> and delegate
+            to <code className="font-mono text-xs">src/features/</code>. Hash history is the default
+            for HubSpot CMS embeds. Add protected routes with{' '}
+            <code className="font-mono text-xs">beforeLoad: {'() => ({ requiresAuth: true })'}</code>.
+            Replace <code className="font-mono text-xs">src/features/starter/</code> when you outgrow
+            the demo. Kit docs:{' '}
+            <code className="font-mono text-xs">node_modules/@woodsportal/hubspot-kit/docs/AUTH-SCAFFOLD.md</code>.
+          </p>
+        </SectionCard>
+      </div>
+    </StarterPageFrame>
+  )
+}

package/templates/scaffold/auth/_shared/src/features/starter/components/starter-page-frame.tsx

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react'
+
+type StarterPageFrameProps = {
+  title: string
+  description?: ReactNode
+  children?: ReactNode
+  className?: string
+}
+
+export function StarterPageFrame({
+  title,
+  description,
+  children,
+  className = 'max-w-2xl',
+}: StarterPageFrameProps) {
+  return (
+    <div className={`mx-auto space-y-4 ${className}`}>
+      <div>
+        <h1 className="text-2xl font-semibold text-gray-900">{title}</h1>
+        {description ? <p className="mt-2 text-gray-600">{description}</p> : null}
+      </div>
+      {children}
+    </div>
+  )
+}

package/templates/scaffold/auth/_shared/src/features/starter/components/starter-protected-page.tsx

@@ -0,0 +1,54 @@
+import { useRouter } from '@tanstack/react-router'
+
+import { Button } from '@/components/ui/Button'
+import { Routes } from '@/config/routes'
+import { clearClientAuthSession } from '@/features/auth/clear-client-auth-session'
+import { useSignedInEmail } from '@/features/auth/use-signed-in-email'
+import { usePortalSession } from '@/features/auth/use-portal-session'
+import { StarterPageFrame } from '@/features/starter/components/starter-page-frame'
+import { api } from '@/integrations/woodsportal-sdk'
+
+export function StarterProtectedPage() {
+  const isAuthenticated = usePortalSession()
+  const { email, isLoading } = useSignedInEmail()
+  const router = useRouter()
+
+  const signedInLabel = isLoading ? 'Loading…' : (email ?? 'Signed in')
+
+  const handleLogout = async () => {
+    clearClientAuthSession()
+    try {
+      const { logout } = api.auth.logout({})
+      await logout()
+    } catch {
+      // local state already cleared
+    }
+    router.navigate({ to: Routes.login })
+  }
+
+  return (
+    <StarterPageFrame
+      title="Protected portal"
+      description={
+        <>
+          You reached <code className="rounded bg-gray-100 px-1">/portal</code> — sample authenticated
+          page for the auth scaffold.
+        </>
+      }
+    >
+      <dl className="rounded-lg border border-gray-200 bg-gray-50 p-4 text-sm">
+        <div className="flex justify-between gap-4">
+          <dt className="text-gray-500">Session</dt>
+          <dd className="font-medium text-gray-900">{isAuthenticated ? 'Active' : 'None'}</dd>
+        </div>
+        <div className="mt-2 flex justify-between gap-4">
+          <dt className="text-gray-500">Signed in as</dt>
+          <dd className="font-medium text-gray-900">{signedInLabel}</dd>
+        </div>
+      </dl>
+      <Button variant="outline" onClick={() => void handleLogout()}>
+        Sign out
+      </Button>
+    </StarterPageFrame>
+  )
+}

package/templates/scaffold/auth/_shared/src/features/starter/content/auth-guide-content.ts

@@ -0,0 +1,91 @@
+export type AuthTierName = 'starter' | 'sso' | 'full'
+
+export const AUTH_TIER_DESCRIPTION: Record<AuthTierName, string> = {
+  starter: 'Email + password login with a protected /portal sample page.',
+  sso: 'Starter login plus SSO OAuth callback handling at /login/sso.',
+  full: 'SSO plus MFA gate at /two-fa — recommended when the hub enforces 2FA.',
+}
+
+export const AUTH_ENV_VARS = [
+  {
+    name: 'VITE_PUBLIC_REST_API_ENDPOINT',
+    note: 'woodsportal-api base URL (required for login). Example: https://api.dev.woodsportal.com',
+  },
+  {
+    name: 'VITE_DEV_PORTAL_ID',
+    note: 'Optional local dev portal id — sent as X-Dev-Portal-Id when logging in.',
+  },
+  {
+    name: 'VITE_REFRESH_TOKEN',
+    note: 'Cookie name for the refresh token (not the token value). Default: wp.c.auth.refresh',
+  },
+] as const
+
+export const AUTH_BOOT_STEPS = [
+  'mountPortal → syncSdkHubContextFromRuntime',
+  'configureWoodsPortalSdk (woodsportal-client-sdk HTTP client)',
+  'SSO URL normalization (sso / full tiers)',
+  'App bootstrap refresh (existing refresh cookie)',
+  'TanStack Router + PublicRoute / PrivateRoute guards',
+  'MainLayout → api.auth.me() (GET /api/auth/me) when authenticated',
+] as const
+
+export const AUTH_PROJECT_PATHS = [
+  { path: 'src/config/auth-tier.ts', note: 'Scaffold tier patched by wp init (starter | sso | full)' },
+  { path: 'src/config/portal-nav.ts', note: 'Shared nav links for top nav and sidebar layouts' },
+  { path: 'src/config/nav-scaffold.ts', note: 'Nav shell mode patched by wp init (top | sidebar)' },
+  { path: 'src/features/auth/', note: 'Login UI, session bridge, route guards, email storage' },
+  { path: 'src/integrations/configure-woodsportal-sdk.ts', note: 'SDK HTTP init — API URL, cookies, routes' },
+  { path: 'src/integrations/woodsportal-sdk.ts', note: 'Single import surface for api.auth.* and api.crm.*' },
+  { path: 'src/app.tsx', note: 'Session bootstrap before RouterProvider mounts' },
+  { path: 'src/utils/public-route.tsx', note: 'Redirects authenticated users away from /login' },
+  { path: 'src/utils/private-route.tsx', note: 'Protects routes with requiresAuth: true' },
+] as const
+
+export const AUTH_INIT_EXAMPLES: Record<AuthTierName, string> = {
+  starter:
+    'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth starter -y',
+  sso: 'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth sso -y',
+  full: 'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth full -y',
+}
+
+export const AUTH_NAV_EXAMPLES = {
+  top: 'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth starter -y',
+  sidebar:
+    'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth starter --nav sidebar -y',
+} as const
+
+export const PAGE_SCAFFOLD_EXAMPLES = [
+  'wp page add settings --protected --nav',
+  'wp page add about --public',
+  'wp page add billing --protected --title "Billing" --no-nav',
+] as const
+
+export function authRoutesForTier(tier: AuthTierName): Array<{ path: string; access: string }> {
+  const routes = [
+    { path: '/guide', access: 'Public — this page' },
+    { path: '/login', access: 'Public — email + password' },
+    { path: '/portal', access: 'Protected — sample page after login' },
+    { path: '/unauthorized', access: 'Public' },
+  ]
+  if (tier === 'sso' || tier === 'full') {
+    routes.splice(2, 0, { path: '/login/sso', access: 'Public — SSO OAuth callback' })
+  }
+  if (tier === 'full') {
+    routes.splice(3, 0, { path: '/two-fa', access: 'Public — MFA OTP gate' })
+  }
+  return routes
+}
+
+export const PORTAL_AUTH_VS_HUBSPOT = [
+  {
+    label: 'HubSpot CLI auth',
+    cmds: 'wp auth · wp portal use',
+    purpose: 'Upload/watch module files to Design Manager',
+  },
+  {
+    label: 'Portal user auth',
+    cmds: 'wp init --auth starter|sso|full',
+    purpose: 'End users sign in via woodsportal-api + woodsportal-client-sdk',
+  },
+] as const

package/templates/scaffold/auth/_shared/src/hubspot/is-cms-editor.ts

@@ -0,0 +1,78 @@
+declare global {
+  interface Window {
+    hsInEditor?: boolean
+    hsVars?: {
+      isEditor?: boolean
+      is_edit_mode?: boolean
+      [key: string]: unknown
+    }
+  }
+}
+
+function isInNestedIframe(): boolean {
+  if (typeof window === 'undefined') {
+    return false
+  }
+  return window.self !== window.top
+}
+
+function readHubSpotEditorFlag(): boolean {
+  if (typeof window === 'undefined') {
+    return false
+  }
+  if (window.hubSpotData?.isInEditor === true) {
+    return true
+  }
+  if (window.hsInEditor === true) {
+    return true
+  }
+  if (window.hsVars?.isEditor === true || window.hsVars?.is_edit_mode === true) {
+    return true
+  }
+  return false
+}
+
+function detectEditorFromUrlOrReferrer(): boolean {
+  if (typeof window === 'undefined') {
+    return false
+  }
+  try {
+    const href = window.location.href
+    if (/inpageeditor|page-editor|hs_editor|content-editor/i.test(href)) {
+      return true
+    }
+    if (isInNestedIframe() && /hs_preview|hsCacheBuster/i.test(href)) {
+      return true
+    }
+    const referrer = document.referrer ?? ''
+    if (
+      referrer &&
+      /hubspot\.(com|net)/i.test(referrer) &&
+      /editor|preview|content\/(page|site)/i.test(referrer)
+    ) {
+      return true
+    }
+  } catch {
+    // ignore
+  }
+  return false
+}
+
+export function isHubSpotCmsEditor(): boolean {
+  if (readHubSpotEditorFlag()) {
+    return true
+  }
+  if (detectEditorFromUrlOrReferrer()) {
+    return true
+  }
+  if (isInNestedIframe() && window.hubSpotData?.isInPreviewer === true) {
+    return true
+  }
+  return false
+}
+
+export function isEditorPreviewMode(): boolean {
+  return isHubSpotCmsEditor() && isInNestedIframe()
+}
+
+export {}

package/templates/scaffold/auth/_shared/src/integrations/configure-woodsportal-sdk.ts

@@ -0,0 +1,100 @@
+import type { LogLevel } from 'woodsportal-client-sdk'
+import {
+  initializeHttpClient,
+  isServiceUnavailableError,
+  setSessionLifecycleListener,
+} from '@/integrations/woodsportal-sdk'
+import { AUTH_SCAFFOLD_TIER } from '@/config/auth-tier'
+import { Routes } from '@/config/routes'
+import { syncSdkHubContextFromRuntime } from '@/data/sync-sdk-hub-context'
+import { resolveHubId } from '@/data/hubSpotContext'
+import { env } from '@/env'
+import { isMfaPendingSession } from '@/features/auth/auth-session'
+import { clearClientAuthSession } from '@/features/auth/clear-client-auth-session'
+import { AUTH_SESSION_CHANGED } from '@/features/auth/auth-session-events'
+import { skipCurrentPublicPath } from '@/utils/ValidationSchema'
+import { resolveWoodsPortalApiBaseUrl } from '@/utils/resolve-api-base-url'
+import { isHubSpotCmsEditor } from '@/hubspot/is-cms-editor'
+
+function resolveSdkLogLevel(): LogLevel {
+  const configured = import.meta.env.VITE_SDK_LOG_LEVEL as LogLevel | undefined
+  if (
+    configured === 'debug' ||
+    configured === 'info' ||
+    configured === 'warn' ||
+    configured === 'error' ||
+    configured === 'silent'
+  ) {
+    return configured
+  }
+  return import.meta.env.DEV ? 'debug' : 'info'
+}
+
+/**
+ * Configure woodsportal-client-sdk HTTP before any api.* call.
+ * Tier: {@link AUTH_SCAFFOLD_TIER} (patched by init-auth-scaffold).
+ */
+export function configureWoodsPortalSdk(): void {
+  syncSdkHubContextFromRuntime()
+  const resolvedHubId = resolveHubId()
+  const devPortalId =
+    import.meta.env.DEV && env.VITE_DEV_PORTAL_ID != null && env.VITE_DEV_PORTAL_ID !== ''
+      ? String(env.VITE_DEV_PORTAL_ID)
+      : undefined
+
+  setSessionLifecycleListener(() => {
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(new CustomEvent(AUTH_SESSION_CHANGED))
+    }
+  })
+
+  initializeHttpClient({
+    baseURL: resolveWoodsPortalApiBaseUrl(),
+    timeout: 50_000,
+    hubId: resolvedHubId != null ? String(resolvedHubId) : undefined,
+    devPortalId,
+    storageMode: isHubSpotCmsEditor() ? 'iframe' : 'cookie',
+    skipCurrentPublicPath,
+    shouldHandleUnauthorized: () => {
+      if (isHubSpotCmsEditor()) {
+        return false
+      }
+      // WPHS_AUTH_FULL
+      if (isMfaPendingSession()) {
+        return false
+      }
+      // /WPHS_AUTH_FULL
+      return true
+    },
+    routes: {
+      unauthorized: Routes.unauthorized,
+      login: Routes.login,
+      twoFa: Routes.twoFa,
+      resendEmail: '/resend-email',
+    },
+    onLogout: () => {
+      clearClientAuthSession()
+    },
+    logger: {
+      level: resolveSdkLogLevel(),
+      httpTracing: true,
+    },
+    storageKeys: {
+      loginDetails: env.VITE_LOGIN_DETAILS,
+      refreshToken: env.VITE_REFRESH_TOKEN,
+      portal: env.VITE_PORTAL,
+      subscriptionType: env.VITE_SUBSCRIPTION_TYPE,
+      authUser: env.VITE_AUTH_USER_KEY,
+      pagination: env.VITE_PAGINATION_DATA,
+      routeMenu: env.VITE_ROUTE_MENU_CONFIG_KEY,
+      associationView: env.VITE_ASSOCIATION_VIEW_URL_KEY,
+    },
+    onServiceUnavailable: (error) => {
+      if (isServiceUnavailableError(error)) {
+        console.warn('[WoodsPortal] API unavailable', error)
+      }
+    },
+  })
+
+  void AUTH_SCAFFOLD_TIER
+}

package/templates/scaffold/auth/_shared/src/integrations/tanstack-query/root-provider.tsx

@@ -0,0 +1,18 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      refetchOnWindowFocus: false,
+      retry: false,
+    },
+  },
+})
+
+export function getContext() {
+  return { queryClient }
+}
+
+export function Provider({ children }: { children: React.ReactNode }) {
+  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+}

package/templates/scaffold/auth/_shared/src/integrations/tanstack-router/router.tsx

@@ -0,0 +1,39 @@
+import {
+  createBrowserHistory,
+  createHashHistory,
+  createRouter,
+  type AnyRouter,
+} from '@tanstack/react-router'
+
+import { ROUTER_HISTORY } from '@/config/router'
+import * as TanStackQueryProvider from '@/integrations/tanstack-query/root-provider'
+import { routeTree } from '@/routeTree.gen'
+
+let routerInstance: AnyRouter | null = null
+
+export function getRouter(): AnyRouter {
+  if (!routerInstance) {
+    const history = ROUTER_HISTORY === 'hash' ? createHashHistory() : createBrowserHistory()
+    routerInstance = createRouter({
+      routeTree,
+      context: {
+        ...TanStackQueryProvider.getContext(),
+      },
+      history,
+      defaultPreload: 'intent',
+      scrollRestoration: true,
+      defaultStructuralSharing: true,
+      defaultPreloadStaleTime: 0,
+    })
+  }
+  return routerInstance
+}
+
+/** Eager router export for dev tooling. */
+export const router = getRouter()
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: ReturnType<typeof getRouter>
+  }
+}

package/templates/scaffold/auth/_shared/src/integrations/woodsportal-sdk.ts

@@ -0,0 +1,37 @@
+/**
+ * SDK facade — single import surface for app code.
+ * Dependency: woodsportal-client-sdk ^4.0.7-dev.11 (added by template-auth-deps.ts)
+ */
+export {
+  getHttpErrorMessage,
+  isServiceUnavailableError,
+  initializeHttpClient,
+  setSessionLifecycleListener,
+  recoverMfaGateOnBoot,
+  resolveAuthRouteAction,
+  AuthErrorCode,
+  resolveAuthErrorAction,
+  storeMfaPendingAccessToken,
+  readMfaPendingAccessToken,
+  clearMfaPendingAccessToken,
+  hydrateMfaPendingAccessToken,
+} from 'woodsportal-client-sdk/auth'
+export type {
+  HttpClientConfig,
+  LoginBootstrapResponse,
+  MfaMethod,
+  MfaMethodOption,
+  AuthRouteAction,
+  MfaBootRecoveryResult,
+} from 'woodsportal-client-sdk/auth'
+
+import { api as authApi } from 'woodsportal-client-sdk/auth'
+import { api as crmApi, store } from 'woodsportal-client-sdk/crm'
+
+export const api = {
+  auth: authApi.auth,
+  crm: crmApi.crm,
+  navigation: crmApi.navigation,
+}
+
+export { store }