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

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/resolve-auth-login-error-message.ts

@@ -0,0 +1,52 @@
+const GENERIC_AUTH_FAILED_MESSAGES = new Set([
+  'Authentication Failed',
+  'Invalid credentials provided.',
+])
+
+type LoginErrorPayload = {
+  errorCode?: unknown
+  errorMessage?: unknown
+  validationErrors?: unknown
+}
+
+function extractFirstValidationMessage(validationErrors: unknown): string | null {
+  if (validationErrors == null || typeof validationErrors !== 'object') {
+    return null
+  }
+  const first = Object.values(validationErrors as Record<string, unknown>)[0]
+  if (typeof first === 'string') {
+    return first
+  }
+  if (Array.isArray(first) && typeof first[0] === 'string') {
+    return first[0]
+  }
+  return null
+}
+
+export function resolveAuthLoginErrorMessage(error: unknown): string {
+  const fallback = 'Wrong email or password'
+  if (error == null || typeof error !== 'object') {
+    return fallback
+  }
+  const data = (error as { response?: { data?: LoginErrorPayload } }).response?.data
+  if (!data) {
+    return fallback
+  }
+  const validationMessage = extractFirstValidationMessage(data.validationErrors)
+  if (validationMessage) {
+    return validationMessage
+  }
+  const errorCode = typeof data.errorCode === 'string' ? data.errorCode : undefined
+  const errorMessage =
+    typeof data.errorMessage === 'string' ? data.errorMessage.trim() : ''
+  if (!errorMessage) {
+    return fallback
+  }
+  if (
+    errorCode === 'AUTHENTICATION_FAILED' &&
+    GENERIC_AUTH_FAILED_MESSAGES.has(errorMessage)
+  ) {
+    return fallback
+  }
+  return errorMessage
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/resolve-post-login-path.ts

@@ -0,0 +1,21 @@
+import { Routes } from '@/config/routes'
+import { isBlockedPostLoginPath } from '@/features/auth/post-login-path'
+import { normalizeRouterPath } from '@/utils/normalize-router-path'
+import type { SafeAuthRouter } from '@/utils/safe-router-navigation'
+
+export type PostLoginRouter = SafeAuthRouter & {
+  state: {
+    location?: {
+      search?: { r?: string; [key: string]: string | undefined }
+      pathname?: string
+    }
+  }
+}
+
+export function resolvePostLoginPath(router: PostLoginRouter): string {
+  const redirect = router.state.location?.search?.r
+  if (redirect && !isBlockedPostLoginPath(String(redirect))) {
+    return normalizeRouterPath(String(redirect))
+  }
+  return Routes.portal
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/sso-callback.ts

@@ -0,0 +1,120 @@
+import { Routes } from '@/config/routes'
+import { readHashPathname } from '@/features/auth/auth-route-paths'
+import { normalizeRouterPath } from '@/utils/normalize-router-path'
+
+export type SsoCallbackParams = {
+  code: string
+  state: string
+}
+
+export const SSO_CALLBACK_EXCHANGE_TIMEOUT_MS = 30_000
+
+const processedKeys = new Set<string>()
+
+export function buildSsoCallbackKey(code: string, state: string): string {
+  return `${code}:${state}`
+}
+
+export function normalizeOAuthQueryValue(value: unknown): string {
+  if (typeof value === 'string') {
+    return value.trim()
+  }
+  if (Array.isArray(value)) {
+    const first = value.find((entry) => typeof entry === 'string' && entry.trim())
+    return typeof first === 'string' ? first.trim() : ''
+  }
+  return ''
+}
+
+export function parseSsoCallbackParams(
+  routeSearch?: { code?: unknown; state?: unknown },
+): SsoCallbackParams {
+  const fromRoute = {
+    code: normalizeOAuthQueryValue(routeSearch?.code),
+    state: normalizeOAuthQueryValue(routeSearch?.state),
+  }
+  if (fromRoute.code && fromRoute.state) {
+    return fromRoute
+  }
+  if (typeof window === 'undefined') {
+    return { code: '', state: '' }
+  }
+  const hashPart = window.location.hash || ''
+  const queryFromHash = hashPart.includes('?') ? hashPart.split('?')[1] : ''
+  const searchParams = new URLSearchParams(queryFromHash || window.location.search)
+  return {
+    code: searchParams.get('code')?.trim() ?? '',
+    state: searchParams.get('state')?.trim() ?? '',
+  }
+}
+
+export function hasOAuthCallbackInUrl(routeSearch?: { code?: unknown; state?: unknown }): boolean {
+  const { code, state } = parseSsoCallbackParams(routeSearch)
+  return Boolean(code && state)
+}
+
+export function clearPreHashQueryParams(): void {
+  if (typeof window === 'undefined' || !window.location.search) {
+    return
+  }
+  window.history.replaceState(null, '', `${window.location.pathname}${window.location.hash}`)
+}
+
+export function isSsoCallbackAlreadyProcessed(key: string): boolean {
+  return processedKeys.has(key)
+}
+
+export function markSsoCallbackProcessed(key: string): void {
+  processedKeys.add(key)
+}
+
+export async function withSsoCallbackTimeout<T>(promise: Promise<T>): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) => {
+      window.setTimeout(
+        () => reject(new Error('sso_callback_timeout')),
+        SSO_CALLBACK_EXCHANGE_TIMEOUT_MS,
+      )
+    }),
+  ])
+}
+
+const exchangeLocks = new Map<string, Promise<void>>()
+
+export async function runSharedSsoCallbackExchange(
+  key: string,
+  exchange: () => Promise<void>,
+): Promise<void> {
+  const existing = exchangeLocks.get(key)
+  if (existing) {
+    return existing
+  }
+  const run = exchange().finally(() => {
+    exchangeLocks.delete(key)
+  })
+  exchangeLocks.set(key, run)
+  return run
+}
+
+export function ensureSsoCallbackRoute(): boolean {
+  if (typeof window === 'undefined') {
+    return false
+  }
+  const { code, state } = parseSsoCallbackParams()
+  if (!code || !state) {
+    return false
+  }
+  const hashPath = readHashPathname()
+  if (normalizeRouterPath(hashPath) === Routes.ssoLogin) {
+    if (window.location.search) {
+      clearPreHashQueryParams()
+    }
+    return true
+  }
+  if (window.location.search) {
+    clearPreHashQueryParams()
+  }
+  window.location.hash = `#${Routes.ssoLogin}?code=${encodeURIComponent(code)}&state=${encodeURIComponent(state)}`
+  return true
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/use-mfa-login-otp-flow.ts

@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useState } from 'react'
+import { toast } from 'sonner'
+import type { MfaMethod } from '@/integrations/woodsportal-sdk'
+import { api } from '@/integrations/woodsportal-sdk'
+import { getMfaPendingContext } from '@/features/auth/mfa-pending-storage'
+import {
+  getResendSecondsLeft,
+  isValidOtpCode,
+  MFA_OTP_RESEND_COOLDOWN_MS,
+  normalizeOtpCode,
+} from '@/features/auth/mfa-otp-utils'
+import { resolveMfaPortalId } from '@/features/auth/mfa-portal'
+
+export function useMfaLoginOtpFlow() {
+  const pending = getMfaPendingContext()
+  const [method, setMethod] = useState<MfaMethod>(pending?.defaultMethod ?? 'EMAIL_OTP')
+  const [otp, setOtp] = useState('')
+  const [isSending, setIsSending] = useState(false)
+  const [isVerifying, setIsVerifying] = useState(false)
+  const [cooldownUntil, setCooldownUntil] = useState<number | null>(null)
+
+  const resendSecondsLeft = getResendSecondsLeft(cooldownUntil)
+
+  const sendOtp = useCallback(async () => {
+    if (resendSecondsLeft > 0) {
+      return
+    }
+    setIsSending(true)
+    try {
+      const portalId = resolveMfaPortalId()
+      const { sendOtp: send } = api.auth.mfa.sendOtp()
+      await send({ method, portalId })
+      setCooldownUntil(Date.now() + MFA_OTP_RESEND_COOLDOWN_MS)
+      toast.success('Verification code sent')
+    } catch {
+      toast.error('Could not send verification code')
+    } finally {
+      setIsSending(false)
+    }
+  }, [method, resendSecondsLeft])
+
+  useEffect(() => {
+    void sendOtp()
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- auto-send once on MFA gate mount
+  }, [])
+
+  const verifyOtp = async () => {
+    const code = normalizeOtpCode(otp)
+    if (!isValidOtpCode(code)) {
+      toast.error('Enter the 6-digit code')
+      return null
+    }
+    setIsVerifying(true)
+    try {
+      const portalId = resolveMfaPortalId()
+      const { verifyOtp: verify } = api.auth.mfa.verifyOtp()
+      return await verify({ method, otp: code, portalId })
+    } catch {
+      toast.error('Invalid or expired code')
+      return null
+    } finally {
+      setIsVerifying(false)
+    }
+  }
+
+  return {
+    method,
+    setMethod,
+    otp,
+    setOtp,
+    destination: pending?.otpDestination,
+    isSending,
+    isVerifying,
+    resendSecondsLeft,
+    sendOtp,
+    verifyOtp,
+  }
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/use-portal-session.ts

@@ -0,0 +1,25 @@
+import { useEffect, useMemo, useState } from 'react'
+import { AUTH_SESSION_CHANGED } from '@/features/auth/auth-session-events'
+import { isFullyAuthenticatedSession, isMfaPendingSession } from '@/features/auth/auth-session'
+
+function useAuthSessionRevision(): number {
+  const [revision, setRevision] = useState(0)
+  useEffect(() => {
+    const bump = () => setRevision((value) => value + 1)
+    window.addEventListener(AUTH_SESSION_CHANGED, bump)
+    return () => window.removeEventListener(AUTH_SESSION_CHANGED, bump)
+  }, [])
+  return revision
+}
+
+export { useAuthSessionRevision }
+
+export function usePortalSession(): boolean {
+  const revision = useAuthSessionRevision()
+  return useMemo(() => isFullyAuthenticatedSession(), [revision])
+}
+
+export function useIsMfaPendingSession(): boolean {
+  const revision = useAuthSessionRevision()
+  return useMemo(() => isMfaPendingSession(), [revision])
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/use-signed-in-email.ts

@@ -0,0 +1,55 @@
+import { useEffect, useState } from 'react'
+
+import { api } from '@/integrations/woodsportal-sdk'
+import { getStoredLoginEmail } from '@/features/auth/login-email-storage'
+import { usePortalSession } from '@/features/auth/use-portal-session'
+
+function readEmailFromProfile(data: unknown): string | null {
+  if (data == null || typeof data !== 'object') {
+    return null
+  }
+  const root = data as Record<string, unknown>
+  const profile = (root.data ?? root) as Record<string, unknown>
+  const email = profile.email
+  return typeof email === 'string' && email.trim() !== '' ? email.trim() : null
+}
+
+export function useSignedInEmail(): { email: string | null; isLoading: boolean } {
+  const isAuthenticated = usePortalSession()
+  const [email, setEmail] = useState<string | null>(() => getStoredLoginEmail())
+  const [isLoading, setIsLoading] = useState(false)
+
+  useEffect(() => {
+    if (!isAuthenticated) {
+      setEmail(null)
+      setIsLoading(false)
+      return
+    }
+
+    const stored = getStoredLoginEmail()
+    if (stored) {
+      setEmail(stored)
+      return
+    }
+
+    setIsLoading(true)
+    const { me } = api.auth.me({
+      onSuccess: (data) => {
+        setEmail(readEmailFromProfile(data) ?? getStoredLoginEmail())
+        setIsLoading(false)
+      },
+      onError: () => {
+        setEmail(getStoredLoginEmail())
+        setIsLoading(false)
+      },
+      onLoadingChange: (loading) => {
+        if (!loading) {
+          setIsLoading(false)
+        }
+      },
+    })
+    void me()
+  }, [isAuthenticated])
+
+  return { email, isLoading }
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/use-sso-callback-handler.ts

@@ -0,0 +1,92 @@
+import { useEffect, useState } from 'react'
+import type { useRouter } from '@tanstack/react-router'
+import { toast } from 'sonner'
+import { api } from '@/integrations/woodsportal-sdk'
+import { handleAuthLoginResponse } from '@/features/auth/login-session-bridge'
+import {
+  buildSsoCallbackKey,
+  clearPreHashQueryParams,
+  isSsoCallbackAlreadyProcessed,
+  markSsoCallbackProcessed,
+  parseSsoCallbackParams,
+  runSharedSsoCallbackExchange,
+  withSsoCallbackTimeout,
+} from '@/features/auth/sso-callback'
+import { Routes } from '@/config/routes'
+
+type SsoRouter = ReturnType<typeof useRouter>
+
+export function useSsoCallbackHandler(options: {
+  router: SsoRouter
+  routeSearch?: { code?: string; state?: string }
+}): { isLoading: boolean } {
+  const { router, routeSearch } = options
+  const [isLoading, setIsLoading] = useState(true)
+
+  useEffect(() => {
+    let cancelled = false
+
+    const run = async () => {
+      const { code, state } = parseSsoCallbackParams(routeSearch)
+      const callbackKey = buildSsoCallbackKey(code, state)
+
+      try {
+        if (!code || !state) {
+          toast.error('Missing SSO callback parameters.')
+          router.history.replace(Routes.login)
+          return
+        }
+
+        if (isSsoCallbackAlreadyProcessed(callbackKey)) {
+          toast.error('SSO callback already processed. Please try again.')
+          router.history.replace(Routes.login)
+          return
+        }
+
+        await runSharedSsoCallbackExchange(callbackKey, async () => {
+          const { callback: ssoCallback } = api.auth.sso.callback()
+          const response = await withSsoCallbackTimeout(
+            ssoCallback({ queryParams: { code, state } }),
+          )
+
+          if (cancelled) {
+            return
+          }
+
+          const result = await handleAuthLoginResponse(response, router, {
+            clearPreHashQuery: clearPreHashQueryParams,
+          })
+
+          if (!result.success) {
+            toast.error('SSO login failed.')
+            router.history.replace(Routes.login)
+            return
+          }
+
+          markSsoCallbackProcessed(callbackKey)
+          if (!result.mfaRequired) {
+            toast.success(
+              (response as { statusMsg?: string })?.statusMsg || 'Signed in with SSO',
+            )
+          }
+        })
+      } catch {
+        if (!cancelled) {
+          toast.error('SSO login failed.')
+          router.history.replace(Routes.login)
+        }
+      } finally {
+        if (!cancelled) {
+          setIsLoading(false)
+        }
+      }
+    }
+
+    void run()
+    return () => {
+      cancelled = true
+    }
+  }, [router, routeSearch])
+
+  return { isLoading }
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/starter/components/starter-guide-page.tsx

@@ -0,0 +1,210 @@
+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,
+  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>
+        </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/examples/greenfield/module-hybrid-cdn-auth-full/src/features/starter/components/starter-home-page.tsx

@@ -0,0 +1,21 @@
+import { Link } from '@tanstack/react-router'
+
+import { ROUTES } from '@/config/routes'
+
+import { StarterHome } from './starter-home'
+
+export function StarterHomePage() {
+  return (
+    <>
+      <StarterHome />
+      <div className="mx-auto max-w-4xl px-6 pb-10 sm:px-10">
+        <Link
+          to={ROUTES.guide}
+          className="inline-flex items-center rounded-md bg-[#0091ae] px-4 py-2 text-sm font-semibold text-white shadow-sm hover:bg-[#007a8c]"
+        >
+          Open developer guide →
+        </Link>
+      </div>
+    </>
+  )
+}