create-top-secret-starter 0.12.0 → 0.14.0

package/backend-overlay/remove.json

@@ -1,6 +1,11 @@
 [
   "src/mocks",
   "src/api/notes/schema.ts",
+  "src/api/orders/schema.ts",
+  "src/api/orders/orders.test.ts",
+  "src/api/live/schema.ts",
+  "src/api/live/feed.ts",
+  "src/api/live/live.test.ts",
   "src/api/notes/notes.test.ts",
   "src/routes/_authenticated/notes",
   "src/api/auth/schema.ts",

package/backend-overlay/root/_gitignore

@@ -9,6 +9,8 @@ lerna-debug.log*
 
 node_modules
 dist
+# generated by the router plugin on dev/build and by `tsr generate` in typecheck
+routeTree.gen.ts
 dist-ssr
 *.local
 

package/backend-overlay/web/src/api/index.ts

@@ -1,4 +1,4 @@
-import { treaty } from '@elysia/eden'
+import { EdenFetchError, treaty } from '@elysia/eden'
 
 import type { App } from '@repo/api'
 
@@ -12,3 +12,13 @@ export const api = treaty<App>(baseUrl, {
   fetch: { credentials: 'include' },
   throwHttpError: true
 }).api // the server's `/api` group
+
+// route loaders turn this into `notFound()`; every variant of `api` exports the same helper
+export const isNotFound = (error: unknown) =>
+  error instanceof EdenFetchError && error.status === 404
+
+// `throwHttpError` already turns failures into exceptions, so a null body is a contract break
+export const unwrap = <T>({ data }: { data: T | null }): T => {
+  if (data === null) throw new Error('Empty response')
+  return data
+}

package/backend-overlay/web/src/api/live/index.ts

@@ -0,0 +1,97 @@
+import { queryOptions, useQueryClient, useSuspenseQuery } from '@tanstack/react-query'
+import { useEffect, useState } from 'react'
+
+import { api, unwrap } from '@/api'
+
+// types flow from the Elysia routes through Eden — no schema to keep in sync
+export type LiveSnapshot = Awaited<ReturnType<typeof getLiveSnapshot>>
+export type Metrics = LiveSnapshot['metrics'][number]
+export type Activity = LiveSnapshot['activity'][number]
+type LiveEvent = { type: 'metrics'; data: Metrics } | { type: 'activity'; data: Activity }
+
+// the same bounds the server's ring buffer uses
+const METRICS_WINDOW = 60
+const ACTIVITY_LIMIT = 20
+
+export const getLiveSnapshot = async () => unwrap(await api.live.snapshot.get())
+
+// `Infinity`: the socket keeps this entry fresh; a refetch only happens after a reconnect
+export const liveSnapshotQuery = queryOptions({
+  queryKey: ['live'],
+  queryFn: getLiveSnapshot,
+  staleTime: Infinity
+})
+
+export type LiveStatus = 'connecting' | 'live' | 'reconnecting'
+
+const applyLiveEvent = (snapshot: LiveSnapshot, event: LiveEvent): LiveSnapshot => {
+  switch (event.type) {
+    case 'metrics':
+      return { ...snapshot, metrics: [...snapshot.metrics.slice(1 - METRICS_WINDOW), event.data] }
+    case 'activity':
+      return { ...snapshot, activity: [event.data, ...snapshot.activity].slice(0, ACTIVITY_LIMIT) }
+  }
+}
+
+const BACKOFF_MS = [1_000, 2_000, 5_000, 10_000]
+
+type ConnectOptions = {
+  onEvent: (event: LiveEvent) => void
+  onStatus: (status: LiveStatus, reconnected: boolean) => void
+}
+
+// one socket, reconnecting with backoff; the session cookie authorises the upgrade
+export const connectLive = ({ onEvent, onStatus }: ConnectOptions) => {
+  let socket: ReturnType<typeof api.live.subscribe> | null = null
+  let attempt = 0
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let closed = false
+
+  const open = () => {
+    socket = api.live.subscribe()
+    socket.on('open', () => {
+      onStatus('live', attempt > 0)
+      attempt = 0
+    })
+    socket.subscribe(({ data }) => onEvent(data as LiveEvent))
+    socket.on('close', () => {
+      if (closed) return
+      onStatus('reconnecting', false)
+      timer = setTimeout(open, BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)])
+      attempt += 1
+    })
+  }
+
+  onStatus('connecting', false)
+  open()
+
+  return () => {
+    closed = true
+    clearTimeout(timer)
+    socket?.close()
+  }
+}
+
+export const useLiveFeed = () => {
+  const queryClient = useQueryClient()
+  const { data } = useSuspenseQuery(liveSnapshotQuery)
+  const [status, setStatus] = useState<LiveStatus>('connecting')
+
+  useEffect(
+    () =>
+      connectLive({
+        onEvent: event =>
+          queryClient.setQueryData(liveSnapshotQuery.queryKey, snapshot =>
+            snapshot ? applyLiveEvent(snapshot, event) : snapshot
+          ),
+        onStatus: (next, reconnected) => {
+          setStatus(next)
+          // frames missed while offline: the snapshot fills the gap
+          if (reconnected) void queryClient.invalidateQueries(liveSnapshotQuery)
+        }
+      }),
+    [queryClient]
+  )
+
+  return { ...data, status }
+}

package/backend-overlay/web/src/api/orders/index.ts

@@ -0,0 +1,65 @@
+import { queryOptions, useMutation, useQueryClient, useSuspenseQuery } from '@tanstack/react-query'
+
+import { api, unwrap } from '@/api'
+import type { CreateOrderInput, OrdersSearch, UpdateOrderStatusInput } from '@/api/orders/input'
+
+// types flow from the Elysia routes through Eden — no schema to keep in sync
+export type OrdersPage = Awaited<ReturnType<typeof getOrders>>
+export type Order = OrdersPage['items'][number]
+
+export const getOrders = async (search: OrdersSearch) =>
+  unwrap(await api.orders.get({ query: search }))
+export const getOrder = async (id: string) => unwrap(await api.orders({ id }).get())
+export const createOrder = async (input: CreateOrderInput) => unwrap(await api.orders.post(input))
+export const updateOrderStatus = async ({
+  id,
+  ...input
+}: UpdateOrderStatusInput & { id: string }) => unwrap(await api.orders({ id }).patch(input))
+
+// ['orders', 'list', …] and ['orders', 'detail', …]: one prefix invalidates both
+const ordersKey = ['orders'] as const
+const listKey = [...ordersKey, 'list'] as const
+
+export const ordersQuery = (search: OrdersSearch) =>
+  queryOptions({ queryKey: [...listKey, search], queryFn: () => getOrders(search) })
+export const orderQuery = (id: string) =>
+  queryOptions({ queryKey: [...ordersKey, 'detail', id], queryFn: () => getOrder(id) })
+
+export const useOrders = (search: OrdersSearch) => useSuspenseQuery(ordersQuery(search))
+export const useOrder = (id: string) => useSuspenseQuery(orderQuery(id))
+
+export const useCreateOrder = () => {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: createOrder,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: listKey })
+  })
+}
+
+const patchStatus = (order: Order, id: string, status: Order['status']) =>
+  order.id === id ? { ...order, status } : order
+
+// optimistic: the badge flips at once; a failure rolls every touched page and detail back
+export const useUpdateOrderStatus = () => {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: updateOrderStatus,
+    onMutate: async ({ id, status }) => {
+      await queryClient.cancelQueries({ queryKey: ordersKey })
+      const lists = queryClient.getQueriesData<OrdersPage>({ queryKey: listKey })
+      const detail = queryClient.getQueryData(orderQuery(id).queryKey)
+      queryClient.setQueriesData<OrdersPage>({ queryKey: listKey }, page =>
+        page ? { ...page, items: page.items.map(order => patchStatus(order, id, status)) } : page
+      )
+      queryClient.setQueryData(orderQuery(id).queryKey, order =>
+        order ? patchStatus(order, id, status) : order
+      )
+      return { lists, detail }
+    },
+    onError: (_error, { id }, context) => {
+      for (const [key, page] of context?.lists ?? []) queryClient.setQueryData(key, page)
+      queryClient.setQueryData(orderQuery(id).queryKey, context?.detail)
+    },
+    onSettled: () => queryClient.invalidateQueries({ queryKey: ordersKey })
+  })
+}

package/backend-overlay/web/src/components/header-actions.tsx

@@ -0,0 +1,30 @@
+import { useRouter } from '@tanstack/react-router'
+import { LogOut } from 'lucide-react'
+
+import { useSession, useSignOut } from '@/api/auth'
+import { ThemeToggle } from '@/components/theme-toggle'
+import { Button } from '@/components/ui/button'
+
+export const HeaderActions = () => {
+  const { data: session } = useSession()
+  const signOut = useSignOut()
+  const router = useRouter()
+
+  const onSignOut = async () => {
+    await signOut.mutateAsync()
+    await router.navigate({ to: '/sign-in' })
+  }
+
+  return (
+    <div className='ml-auto flex items-center gap-2 sm:gap-4'>
+      <span className='hidden truncate text-sm text-muted-foreground sm:inline'>
+        {session?.user.email}
+      </span>
+      <ThemeToggle />
+      <Button variant='outline' size='sm' onClick={onSignOut} disabled={signOut.isPending}>
+        <LogOut data-icon='inline-start' />
+        Sign out
+      </Button>
+    </div>
+  )
+}

package/backend-overlay/web/src/components/sidebar-user.tsx

@@ -0,0 +1,33 @@
+import { Link } from '@tanstack/react-router'
+
+import { useSession } from '@/api/auth'
+import { SidebarMenuButton, useSidebar } from '@/components/ui/sidebar'
+
+const initialsOf = (email: string) => email.slice(0, 2).toUpperCase()
+
+// the account row in the sidebar footer, reading the Better Auth session
+export const SidebarUser = () => {
+  const { data: session } = useSession()
+  const { isMobile, setOpenMobile } = useSidebar()
+  if (!session) return null
+
+  const { email } = session.user
+  return (
+    <SidebarMenuButton
+      size='lg'
+      tooltip={email}
+      render={<Link to='/' onClick={() => isMobile && setOpenMobile(false)} />}
+    >
+      <span
+        aria-hidden='true'
+        className='flex size-8 shrink-0 items-center justify-center rounded-lg bg-sidebar-accent text-xs font-medium text-sidebar-accent-foreground'
+      >
+        {initialsOf(email)}
+      </span>
+      <span className='flex min-w-0 flex-col leading-tight'>
+        <span className='truncate text-xs text-muted-foreground'>Signed in as</span>
+        <span className='truncate font-medium'>{email}</span>
+      </span>
+    </SidebarMenuButton>
+  )
+}

package/backend-overlay/web/src/lib/query-client.test.tsx

@@ -60,6 +60,20 @@ it('always toasts a failed mutation', async () => {
   expect(toasts()[0]).toHaveTextContent('nope')
 })
 
+it('stays silent for a mutation that shows its own errors', async () => {
+  await queryClient
+    .getMutationCache()
+    .build(queryClient, {
+      mutationFn: () => Promise.reject(new EdenFetchError(422, { message: 'Email is taken' })),
+      meta: { silentError: true }
+    })
+    .execute(undefined)
+    .catch(() => {})
+  await flushToasts()
+
+  expect(toasts()).toHaveLength(0)
+})
+
 it('does not retry a 4xx query', async () => {
   const queryFn = vi.fn(() => Promise.reject(httpError(404)))
 
@@ -68,6 +82,14 @@ it('does not retry a 4xx query', async () => {
   expect(queryFn).toHaveBeenCalledTimes(1)
 })
 
+it('retries a rate-limited query', async () => {
+  const queryFn = vi.fn(() => Promise.reject(httpError(429)))
+
+  await queryClient.query({ queryKey: ['e'], queryFn, retryDelay: 0 }).catch(() => {})
+
+  expect(queryFn).toHaveBeenCalledTimes(3)
+})
+
 it('retries a 5xx query up to the configured limit', async () => {
   const queryFn = vi.fn(() => Promise.reject(httpError(503)))
 

package/backend-overlay/web/src/lib/query-client.ts

@@ -3,16 +3,32 @@ import { MutationCache, QueryCache, QueryClient } from '@tanstack/react-query'
 
 import { toast } from '@/components/ui/toast'
 
-const isClientError = (error: unknown) =>
-  error instanceof EdenFetchError && error.status >= 400 && error.status < 500
-
-const getErrorMessage = (error: unknown) => {
-  if (error instanceof EdenFetchError) {
-    return (
-      (error.value as { message?: string } | null)?.message ?? `Request failed (${error.status})`
-    )
+declare module '@tanstack/react-query' {
+  interface Register {
+    mutationMeta: { silentError?: boolean }
   }
-  return error instanceof Error ? error.message : 'Something went wrong'
+}
+
+// 408 and 429 are transient despite being 4xx
+const RETRYABLE_CLIENT_ERRORS = new Set([408, 429])
+
+const isFinalError = (error: unknown) => {
+  if (!(error instanceof EdenFetchError)) return false
+  const { status } = error
+  return status >= 400 && status < 500 && !RETRYABLE_CLIENT_ERRORS.has(status)
+}
+
+// the server's `{ message }` beats eden's bare status
+const getErrorMessage = (error: unknown): string => {
+  if (!(error instanceof EdenFetchError)) {
+    return error instanceof Error && error.message.trim() ? error.message : 'Something went wrong'
+  }
+
+  const message = (error.value as { message?: string } | null)?.message
+
+  return typeof message === 'string' && message.trim()
+    ? message
+    : `Request failed (${error.status})`
 }
 
 const notifyError = (error: unknown) => {
@@ -25,11 +41,15 @@ export const queryClient = new QueryClient({
       if (query.state.data !== undefined) notifyError(error)
     }
   }),
-  mutationCache: new MutationCache({ onError: notifyError }),
+  mutationCache: new MutationCache({
+    onError: (error, _variables, _context, mutation) => {
+      if (!mutation.meta?.silentError) notifyError(error)
+    }
+  }),
   defaultOptions: {
     queries: {
       staleTime: 60_000,
-      retry: (failureCount, error) => !isClientError(error) && failureCount < 2
+      retry: (failureCount, error) => !isFinalError(error) && failureCount < 2
     },
     mutations: {
       retry: false

package/backend-overlay/web/src/routes/_authenticated/index.tsx

@@ -1,65 +1,30 @@
 import { createFileRoute } from '@tanstack/react-router'
-import { Trash2 } from 'lucide-react'
-import { useState } from 'react'
 
-import { useCreateNote, useDeleteNote, useNotes, notesQuery } from '@/api/notes'
-import { Button } from '@/components/ui/button'
-import { Input } from '@/components/ui/input'
+import { useSession } from '@/api/auth'
+// realtime:start
+import { liveSnapshotQuery } from '@/api/live'
+import { Dashboard } from '@/components/dashboard/dashboard'
+// realtime:end
 
 export const Route = createFileRoute('/_authenticated/')({
-  loader: ({ context }) => context.queryClient.query({ ...notesQuery, staleTime: 'static' }),
-  component: NotesPage
+  // realtime:start
+  loader: ({ context }) => context.queryClient.query({ ...liveSnapshotQuery, staleTime: 'static' }),
+  // realtime:end
+  component: HomePage
 })
 
-// demo of the Drizzle → Elysia → Eden → React Query path; delete with the notes modules
-function NotesPage() {
-  const notes = useNotes()
-  const createNote = useCreateNote()
-  const deleteNote = useDeleteNote()
-  const [title, setTitle] = useState('')
-
-  const onSubmit = (e: React.SubmitEvent<HTMLFormElement>) => {
-    e.preventDefault()
-    const trimmed = title.trim()
-    if (!trimmed) return
-    createNote.mutate(trimmed, { onSuccess: () => setTitle('') })
-  }
+function HomePage() {
+  const { data: session } = useSession()
 
   return (
-    <main className='w-full max-w-md space-y-4'>
-      <h1 className='text-2xl font-semibold'>PLACEHOLDER</h1>
-
-      <form onSubmit={onSubmit} className='flex gap-2'>
-        <Input
-          aria-label='New note'
-          placeholder='New note…'
-          value={title}
-          onChange={e => setTitle(e.target.value)}
-          maxLength={200}
-        />
-        <Button type='submit' disabled={createNote.isPending}>
-          Add
-        </Button>
-      </form>
-
-      {notes.data?.length === 0 && <p className='text-muted-foreground text-sm'>No notes yet.</p>}
-
-      <ul className='divide-y rounded-lg border'>
-        {notes.data?.map(note => (
-          <li key={note.id} className='flex items-center justify-between px-3 py-2'>
-            <span className='text-sm'>{note.title}</span>
-            <Button
-              variant='ghost'
-              size='icon-sm'
-              aria-label={`Delete ${note.title}`}
-              disabled={deleteNote.isPending}
-              onClick={() => deleteNote.mutate(note.id)}
-            >
-              <Trash2 />
-            </Button>
-          </li>
-        ))}
-      </ul>
+    <main className='flex flex-1 flex-col gap-6'>
+      <div className='flex flex-col gap-1'>
+        <h1 className='text-2xl font-semibold'>PLACEHOLDER</h1>
+        <p className='text-sm text-muted-foreground'>Signed in as {session?.user.email}</p>
+      </div>
+      {/* realtime:start */}
+      <Dashboard />
+      {/* realtime:end */}
     </main>
   )
 }

package/backend-overlay/web/src/routes/_authenticated/notes/index.tsx

@@ -0,0 +1,65 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { Trash2 } from 'lucide-react'
+import { useState } from 'react'
+
+import { useCreateNote, useDeleteNote, useNotes, notesQuery } from '@/api/notes'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+
+export const Route = createFileRoute('/_authenticated/notes/')({
+  loader: ({ context }) => context.queryClient.query({ ...notesQuery, staleTime: 'static' }),
+  component: NotesPage
+})
+
+// demo of the Drizzle → Elysia → Eden → React Query path; delete with the notes modules
+function NotesPage() {
+  const notes = useNotes()
+  const createNote = useCreateNote()
+  const deleteNote = useDeleteNote()
+  const [title, setTitle] = useState('')
+
+  const onSubmit = (e: React.SubmitEvent<HTMLFormElement>) => {
+    e.preventDefault()
+    const trimmed = title.trim()
+    if (!trimmed) return
+    createNote.mutate(trimmed, { onSuccess: () => setTitle('') })
+  }
+
+  return (
+    <main className='mx-auto w-full max-w-md space-y-4'>
+      <h1 className='text-2xl font-semibold'>Notes</h1>
+
+      <form onSubmit={onSubmit} className='flex gap-2'>
+        <Input
+          aria-label='New note'
+          placeholder='New note…'
+          value={title}
+          onChange={e => setTitle(e.target.value)}
+          maxLength={200}
+        />
+        <Button type='submit' disabled={createNote.isPending}>
+          Add
+        </Button>
+      </form>
+
+      {notes.data?.length === 0 && <p className='text-sm text-muted-foreground'>No notes yet.</p>}
+
+      <ul className='divide-y rounded-lg border'>
+        {notes.data?.map(note => (
+          <li key={note.id} className='flex items-center justify-between px-3 py-2'>
+            <span className='text-sm'>{note.title}</span>
+            <Button
+              variant='ghost'
+              size='icon-sm'
+              aria-label={`Delete ${note.title}`}
+              disabled={deleteNote.isPending}
+              onClick={() => deleteNote.mutate(note.id)}
+            >
+              <Trash2 />
+            </Button>
+          </li>
+        ))}
+      </ul>
+    </main>
+  )
+}

package/backend-overlay/web/src/routes/_authenticated.tsx

@@ -25,7 +25,7 @@ function AuthenticatedLayout() {
     <>
       <header className='flex h-14 items-center justify-between border-b px-6'>
         <div className='flex items-center gap-4'>
-          <span className='text-muted-foreground text-sm'>{session?.user.email}</span>
+          <span className='text-sm text-muted-foreground'>{session?.user.email}</span>
           <ThemeToggle />
           <Button variant='outline' size='sm' onClick={onSignOut} disabled={signOut.isPending}>
             <LogOut data-icon='inline-start' />

package/backend-overlay/web-router/src/routes/sign-in.tsx

@@ -16,13 +16,26 @@ const SignInFormSchema = z.object({
 })
 
 const FIELDS = [
-  { name: 'email', label: 'Email', type: 'email', autoComplete: 'email' },
-  { name: 'password', label: 'Password', type: 'password', autoComplete: 'current-password' }
+  {
+    name: 'email',
+    label: 'Email',
+    type: 'email',
+    autoComplete: 'email',
+    placeholder: 'you@example.com'
+  },
+  {
+    name: 'password',
+    label: 'Password',
+    type: 'password',
+    autoComplete: 'current-password',
+    placeholder: '••••••••'
+  }
 ] as const satisfies ReadonlyArray<{
   name: keyof SignInInput
   label: string
   type: string
   autoComplete: string
+  placeholder: string
 }>
 
 export const Route = createFileRoute('/sign-in')({
@@ -61,6 +74,7 @@ function SignInPage() {
                   id={field.name}
                   type={field.type}
                   autoComplete={field.autoComplete}
+                  placeholder={field.placeholder}
                   aria-invalid={Boolean(error)}
                   aria-describedby={error ? `${field.name}-error` : undefined}
                   {...register(field.name)}
@@ -74,7 +88,7 @@ function SignInPage() {
             {formState.isSubmitting ? 'Signing in…' : 'Sign in'}
           </Button>
 
-          <p className='text-muted-foreground text-center text-sm'>
+          <p className='text-center text-sm text-muted-foreground'>
             No account?{' '}
             <Link to='/sign-up' search={{ redirect: redirectTo }} className='underline'>
               Sign up

package/backend-overlay/web-router/src/routes/sign-up.tsx

@@ -18,14 +18,27 @@ const SignUpFormSchema = z.object({
 })
 
 const FIELDS = [
-  { name: 'name', label: 'Name', type: 'text', autoComplete: 'name' },
-  { name: 'email', label: 'Email', type: 'email', autoComplete: 'email' },
-  { name: 'password', label: 'Password', type: 'password', autoComplete: 'new-password' }
+  { name: 'name', label: 'Name', type: 'text', autoComplete: 'name', placeholder: 'Ada Lovelace' },
+  {
+    name: 'email',
+    label: 'Email',
+    type: 'email',
+    autoComplete: 'email',
+    placeholder: 'you@example.com'
+  },
+  {
+    name: 'password',
+    label: 'Password',
+    type: 'password',
+    autoComplete: 'new-password',
+    placeholder: 'At least 8 characters'
+  }
 ] as const satisfies ReadonlyArray<{
   name: keyof SignUpInput
   label: string
   type: string
   autoComplete: string
+  placeholder: string
 }>
 
 export const Route = createFileRoute('/sign-up')({
@@ -64,6 +77,7 @@ function SignUpPage() {
                   id={field.name}
                   type={field.type}
                   autoComplete={field.autoComplete}
+                  placeholder={field.placeholder}
                   aria-invalid={Boolean(error)}
                   aria-describedby={error ? `${field.name}-error` : undefined}
                   {...register(field.name)}
@@ -77,7 +91,7 @@ function SignUpPage() {
             {formState.isSubmitting ? 'Creating…' : 'Sign up'}
           </Button>
 
-          <p className='text-muted-foreground text-center text-sm'>
+          <p className='text-center text-sm text-muted-foreground'>
             Already have an account?{' '}
             <Link to='/sign-in' search={{ redirect: redirectTo }} className='underline'>
               Sign in

package/backend-overlay/web-start/src/api/index.ts

@@ -1,5 +1,5 @@
 // Start override: the SSR runtime has no `window`, so the origin cannot be read there.
-import { treaty } from '@elysia/eden'
+import { EdenFetchError, treaty } from '@elysia/eden'
 
 import type { App } from '@repo/api'
 
@@ -15,3 +15,13 @@ export const api = treaty<App>(baseUrl, {
   fetch: { credentials: 'include' },
   throwHttpError: true
 }).api // the server's `/api` group
+
+// route loaders turn this into `notFound()`; every variant of `api` exports the same helper
+export const isNotFound = (error: unknown) =>
+  error instanceof EdenFetchError && error.status === 404
+
+// `throwHttpError` already turns failures into exceptions, so a null body is a contract break
+export const unwrap = <T>({ data }: { data: T | null }): T => {
+  if (data === null) throw new Error('Empty response')
+  return data
+}