@stjoseph/prumo 0.2.0 → 0.4.0

package/templates/mobile/test/features/auth/email-flows.spec.tsx

@@ -0,0 +1,86 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { API_URL, fakeTransport, json } from '@test/support/fake-transport'
+import { memoryTokenStore } from '@test/support/memory-token-store'
+import { userEvent } from '@testing-library/react-native'
+import { renderRouter, screen } from 'expo-router/testing-library'
+import type { ReactNode } from 'react'
+import { Text } from 'react-native'
+import { createAuthClient, createClient } from '@/api-contract'
+import ForgotPasswordScreen from '@/app/(auth)/forgot-password'
+import ResetPasswordScreen from '@/app/(auth)/reset-password'
+import SignUpScreen from '@/app/(auth)/sign-up'
+import VerifyEmailScreen from '@/app/(auth)/verify-email'
+import { ClientsProvider } from '@/features/clients/clients-context'
+
+const TOKENS = { accessToken: 'access-1', refreshToken: 'refresh-1', expiresIn: 900 }
+
+async function renderAt(initialUrl: string, routes: Parameters<typeof fakeTransport>[0]) {
+  const transport = fakeTransport(routes)
+  const auth = createAuthClient({ baseUrl: API_URL, fetch: transport, tokens: memoryTokenStore() })
+  const clients = { auth, api: createClient({ baseUrl: API_URL, fetch: auth.fetch }) }
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+
+  function Providers({ children }: { children: ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        <ClientsProvider clients={clients}>{children}</ClientsProvider>
+      </QueryClientProvider>
+    )
+  }
+
+  await renderRouter(
+    {
+      index: () => <Text>Your profile</Text>,
+      '(auth)/sign-up': SignUpScreen,
+      '(auth)/verify-email': VerifyEmailScreen,
+      '(auth)/forgot-password': ForgotPasswordScreen,
+      '(auth)/reset-password': ResetPasswordScreen,
+    },
+    { initialUrl, wrapper: Providers },
+  )
+}
+
+describe('email verification on mobile', () => {
+  it('takes a new account to the code, and in once it is entered', async () => {
+    const user = userEvent.setup()
+
+    await renderAt('/sign-up', {
+      'POST /api/auth/sign-up': () => json(201, { verificationRequired: true }),
+      'POST /api/auth/email/verify': () => json(200, TOKENS),
+    })
+
+    await user.type(screen.getByLabelText('Name'), 'Ana')
+    await user.type(screen.getByLabelText('Email'), 'ana@example.com')
+    await user.type(screen.getByLabelText('Password'), 'correct-horse-battery')
+    await user.press(screen.getByRole('button', { name: 'Create account' }))
+
+    expect(await screen.findByText('Confirm your email')).toBeOnTheScreen()
+
+    await user.type(screen.getByLabelText('Code'), '123456')
+    await user.press(screen.getByRole('button', { name: 'Confirm email' }))
+
+    expect(await screen.findByText('Your profile')).toBeOnTheScreen()
+  })
+})
+
+describe('password reset on mobile', () => {
+  it('goes from forgot to reset and in', async () => {
+    const user = userEvent.setup()
+
+    await renderAt('/forgot-password', {
+      'POST /api/auth/password/forgot': () => new Response(null, { status: 204 }),
+      'POST /api/auth/password/reset': () => json(200, TOKENS),
+    })
+
+    await user.type(screen.getByLabelText('Email'), 'ana@example.com')
+    await user.press(screen.getByRole('button', { name: 'Send a reset code' }))
+
+    expect(await screen.findByText('Choose a new password')).toBeOnTheScreen()
+
+    await user.type(screen.getByLabelText('Code'), '123456')
+    await user.type(screen.getByLabelText('New password'), 'another-good-password')
+    await user.press(screen.getByRole('button', { name: 'Set the new password' }))
+
+    expect(await screen.findByText('Your profile')).toBeOnTheScreen()
+  })
+})

package/templates/mobile/test/features/auth/sign-in-form.spec.tsx

@@ -1,23 +1,24 @@
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { API_URL, fakeTransport, json } from '@test/support/fake-transport'
+import { memoryTokenStore } from '@test/support/memory-token-store'
 import { render, screen, userEvent } from '@testing-library/react-native'
-import { createAuthClient } from 'better-auth/react'
+import { createAuthClient } from '@/api-contract'
 import { SignInForm } from '@/features/auth/sign-in-form'
 
 describe('SignInForm', () => {
   it('shows a rejected sign-in as a form-level error', async () => {
     const onSignedIn = jest.fn()
-    // jest-expo leaves the app manifest empty, and the Expo plugin needs it to build an origin; the form under test
-    // depends only on the error Better Auth returns, which the plugin does not change.
     const auth = createAuthClient({
-      baseURL: API_URL,
-      basePath: '/api/auth',
-      fetchOptions: {
-        customFetchImpl: fakeTransport({
-          'POST /api/auth/sign-in/email': () =>
-            json(401, { message: 'Invalid email or password', code: 'INVALID_EMAIL_OR_PASSWORD' }),
-        }),
-      },
+      baseUrl: API_URL,
+      tokens: memoryTokenStore(),
+      fetch: fakeTransport({
+        'POST /api/auth/sign-in': () =>
+          json(
+            401,
+            { title: 'Unauthorized', status: 401, detail: 'Invalid email or password' },
+            'application/problem+json',
+          ),
+      }),
     })
     const user = userEvent.setup()
 

package/templates/mobile/test/features/auth/sign-out-button.spec.tsx

@@ -1,7 +1,8 @@
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { API_URL, fakeTransport, json } from '@test/support/fake-transport'
+import { API_URL, fakeTransport } from '@test/support/fake-transport'
+import { memoryTokenStore } from '@test/support/memory-token-store'
 import { render, screen, userEvent, waitFor } from '@testing-library/react-native'
-import { createAuthClient } from 'better-auth/react'
+import { createAuthClient } from '@/api-contract'
 import { SignOutButton } from '@/features/auth/sign-out-button'
 import { clearUserData } from '@/features/storage/storage'
 
@@ -11,15 +12,13 @@ jest.mock('@/features/storage/storage', () => ({ clearUserData: jest.fn() }))
 async function signOutWith(signOut: () => Response | Promise<Response>) {
   const queryClient = new QueryClient()
   const onSignedOut = jest.fn()
-  // jest-expo leaves the app manifest empty, and the Expo plugin needs it to build an origin; the button depends only on
-  // signOut resolving or failing, which the plugin does not change.
   const auth = createAuthClient({
-    baseURL: API_URL,
-    basePath: '/api/auth',
-    fetchOptions: { customFetchImpl: fakeTransport({ 'POST /api/auth/sign-out': signOut }) },
+    baseUrl: API_URL,
+    tokens: memoryTokenStore({ accessToken: 'a', refreshToken: 'r', expiresIn: 900 }),
+    fetch: fakeTransport({ 'POST /api/auth/sign-out': signOut }),
   })
 
-  queryClient.setQueryData(['session'], { session: { id: 'session-1' }, user: { id: 'user-1' } })
+  queryClient.setQueryData(['session'], { user: { id: 'user-1', email: 'ana@example.com' } })
   queryClient.setQueryData(['profile', 'me'], { id: 'profile-1', displayName: 'Ana' })
 
   await render(
@@ -38,7 +37,7 @@ describe('SignOutButton', () => {
   beforeEach(() => jest.mocked(clearUserData).mockClear())
 
   it('leaves nothing of the user behind for the next person on the device', async () => {
-    const queryClient = await signOutWith(() => json(200, { success: true }))
+    const queryClient = await signOutWith(() => new Response(null, { status: 204 }))
 
     expect(queryClient.getQueryCache().getAll()).toHaveLength(0)
     expect(clearUserData).toHaveBeenCalledTimes(1)

package/templates/mobile/test/features/auth/social-buttons.spec.tsx

@@ -0,0 +1,77 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { API_URL, fakeTransport, json } from '@test/support/fake-transport'
+import { memoryTokenStore } from '@test/support/memory-token-store'
+import { render, screen, userEvent, waitFor } from '@testing-library/react-native'
+import * as WebBrowser from 'expo-web-browser'
+import { createAuthClient } from '@/api-contract'
+import { SocialButtons } from '@/features/auth/social-buttons'
+
+jest.mock('expo-web-browser', () => ({ openAuthSessionAsync: jest.fn() }))
+// jest-expo leaves the app manifest empty, so expo-linking cannot know the app's scheme; this one stands in for it.
+jest.mock('expo-linking', () => ({
+  ...jest.requireActual('expo-linking'),
+  createURL: (path: string) => `acme://${path}`,
+}))
+
+// Whichever provider the project kept: each button runs the same trip.
+const firstProvider = () => screen.getAllByRole('button', { name: /^Continue with / })[0] as never
+
+const TOKENS = { accessToken: 'access-1', refreshToken: 'refresh-1', expiresIn: 900 }
+
+async function renderButtons(exchange: () => Response) {
+  const tokens = memoryTokenStore()
+  const onSignedIn = jest.fn()
+  const auth = createAuthClient({
+    baseUrl: API_URL,
+    tokens,
+    fetch: fakeTransport({ 'POST /api/auth/social/exchange': exchange }),
+  })
+
+  await render(
+    <QueryClientProvider client={new QueryClient()}>
+      <SocialButtons auth={auth} onSignedIn={onSignedIn} />
+    </QueryClientProvider>,
+  )
+
+  return { tokens, onSignedIn }
+}
+
+describe('SocialButtons', () => {
+  beforeEach(() => jest.mocked(WebBrowser.openAuthSessionAsync).mockReset())
+
+  it('opens the provider through the API and trades the code it comes back with', async () => {
+    jest
+      .mocked(WebBrowser.openAuthSessionAsync)
+      .mockResolvedValue({ type: 'success', url: 'acme://social?code=flow.secret' })
+    const { tokens, onSignedIn } = await renderButtons(() => json(200, TOKENS))
+
+    await userEvent.setup().press(firstProvider())
+
+    await waitFor(() => expect(onSignedIn).toHaveBeenCalled())
+    expect(jest.mocked(WebBrowser.openAuthSessionAsync).mock.calls[0]?.[0]).toMatch(
+      new RegExp(`^${API_URL}/api/auth/social/\\w+\\?client=mobile&returnTo=%2F$`),
+    )
+    expect(await tokens.read()).toEqual(TOKENS)
+  })
+
+  it('does nothing when the browser is closed, and says so when the code is refused', async () => {
+    jest
+      .mocked(WebBrowser.openAuthSessionAsync)
+      .mockResolvedValueOnce({ type: 'cancel' } as Awaited<
+        ReturnType<typeof WebBrowser.openAuthSessionAsync>
+      >)
+    const { onSignedIn } = await renderButtons(() => json(401, {}))
+    const user = userEvent.setup()
+
+    await user.press(firstProvider())
+    expect(screen.queryByRole('alert')).toBeNull()
+
+    jest
+      .mocked(WebBrowser.openAuthSessionAsync)
+      .mockResolvedValueOnce({ type: 'success', url: 'acme://social?code=used' })
+    await user.press(firstProvider())
+
+    expect(await screen.findByRole('alert')).toHaveTextContent(/did not complete/)
+    expect(onSignedIn).not.toHaveBeenCalled()
+  })
+})

package/templates/mobile/test/support/memory-token-store.ts

@@ -0,0 +1,15 @@
+import type { TokenStore, Tokens } from '@/api-contract'
+
+// expo-secure-store needs the native Keychain or Keystore, which Jest does not have.
+export function memoryTokenStore(initial: Tokens | null = null): TokenStore {
+  let current = initial
+
+  return {
+    async read() {
+      return current
+    },
+    async write(tokens) {
+      current = tokens
+    },
+  }
+}

package/templates/site/scripts/ports.mjs

@@ -25,7 +25,7 @@ const APPS = {
 // A port that moves takes these with it: the key to write, in which app, from which app's port.
 const FOLLOWERS = {
   api: [
-    { app: 'api', key: 'BETTER_AUTH_URL' },
+    { app: 'api', key: 'API_URL' },
     { app: 'web', key: 'VITE_API_URL' },
     { app: 'mobile', key: 'EXPO_PUBLIC_API_URL' },
   ],

package/templates/web/package.json

@@ -16,13 +16,10 @@
   },
   "dependencies": {
     "@base-ui/react": "1.8.0",
-    "@better-auth/core": "1.7.7",
-    "@better-auth/oauth-provider": "1.7.7",
     "@fontsource-variable/geist": "5.3.0",
     "@hookform/resolvers": "5.9.1",
     "@tanstack/react-query": "5.102.8",
     "@tanstack/react-router": "1.170.36",
-    "better-auth": "1.7.7",
     "class-variance-authority": "0.7.1",
     "cn": "0.3.0",
     "lucide-react": "1.45.0",

package/templates/web/scripts/ports.mjs

@@ -25,7 +25,7 @@ const APPS = {
 // A port that moves takes these with it: the key to write, in which app, from which app's port.
 const FOLLOWERS = {
   api: [
-    { app: 'api', key: 'BETTER_AUTH_URL' },
+    { app: 'api', key: 'API_URL' },
     { app: 'web', key: 'VITE_API_URL' },
     { app: 'mobile', key: 'EXPO_PUBLIC_API_URL' },
   ],

package/templates/web/src/api-contract/api-error.ts

@@ -5,14 +5,8 @@ type ProblemDocument = {
   status?: number
   detail?: string
   requestId?: string
-  errors?: FieldErrors
-}
-
-type AuthClientError = {
-  status: number
-  statusText: string
-  message?: string
   code?: string
+  errors?: FieldErrors
 }
 
 export class ApiError extends Error {
@@ -22,6 +16,8 @@ export class ApiError extends Error {
     readonly detail: string | undefined,
     readonly requestId: string | undefined,
     readonly errors: FieldErrors,
+    // A stable name for a refusal the client acts on, such as `email_not_verified`.
+    readonly code?: string,
   ) {
     super(detail ?? title)
   }
@@ -42,10 +38,7 @@ export class ApiError extends Error {
       problem.detail,
       problem.requestId ?? requestId,
       problem.errors ?? {},
+      problem.code,
     )
   }
-
-  static fromAuthError(error: AuthClientError): ApiError {
-    return new ApiError(error.status, error.code ?? error.statusText, error.message, undefined, {})
-  }
 }

package/templates/web/src/api-contract/auth.ts

@@ -0,0 +1,221 @@
+import { queryOptions } from '@tanstack/react-query'
+import { ApiError } from './api-error'
+import type { Transport } from './client'
+
+export type Session = { user: { id: string; email: string } }
+
+export type Tokens = { accessToken: string; refreshToken: string; expiresIn: number }
+
+export type SignUpRequest = { name: string; email: string; password: string }
+
+export type SignInRequest = { email: string; password: string }
+
+// prumo:email
+export type VerifyEmailRequest = { email: string; code: string }
+
+export type ResetPasswordRequest = { email: string; code: string; password: string }
+
+// prumo:end-email
+// prumo:social
+export type SocialProvider = 'google' | 'apple'
+
+// prumo:end-social
+// An account that must confirm its email first gets no session from signing up, and says so.
+export type SignUpResult = { verificationRequired: boolean }
+
+// Where a native client keeps its tokens. The web passes none: its tokens live in cookies no script can read.
+export type TokenStore = {
+  read(): Promise<Tokens | null>
+  write(tokens: Tokens | null): Promise<void>
+}
+
+export type AuthClient = ReturnType<typeof createAuthClient>
+
+export function createAuthClient({
+  baseUrl,
+  fetch,
+  tokens,
+}: {
+  baseUrl: string
+  fetch: Transport
+  tokens?: TokenStore
+}) {
+  const url = (path: string) => `${baseUrl}/api/auth${path}`
+
+  function send(path: string, body?: unknown): Promise<Response> {
+    const headers = new Headers()
+
+    // Asking for the tokens in the body is what makes the API leave cookies out.
+    if (tokens !== undefined) {
+      headers.set('x-auth-transport', 'bearer')
+    }
+
+    if (body !== undefined) {
+      headers.set('content-type', 'application/json')
+    }
+
+    return fetch(url(path), {
+      method: 'POST',
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+  }
+
+  async function begin(path: string, body: unknown): Promise<SignUpResult> {
+    const response = await send(path, body)
+
+    if (!response.ok) {
+      throw await ApiError.fromResponse(response)
+    }
+
+    // The web's answer is empty: its session arrived as cookies.
+    const text = await response.text()
+    const answer = text === '' ? {} : (JSON.parse(text) as Partial<Tokens & SignUpResult>)
+
+    if (answer.verificationRequired === true) {
+      return { verificationRequired: true }
+    }
+
+    await tokens?.write(answer as Tokens)
+    return { verificationRequired: false }
+  }
+
+  // prumo:email
+  async function ask(path: string, body: unknown): Promise<void> {
+    const response = await send(path, body)
+
+    if (!response.ok) {
+      throw await ApiError.fromResponse(response)
+    }
+  }
+
+  // prumo:end-email
+
+  let refreshing: Promise<boolean> | undefined
+
+  // Every request that meets a 401 at once waits on the same refresh: a second refresh would present a token the
+  // first has already rotated.
+  function refresh(): Promise<boolean> {
+    refreshing ??= (async () => {
+      try {
+        // The web has no store and sends its cookie; a native client with nothing stored has nothing to send.
+        const stored = tokens === undefined ? undefined : await tokens.read()
+
+        if (stored === null) {
+          return false
+        }
+
+        const response = await send(
+          '/refresh',
+          stored === undefined ? undefined : { refreshToken: stored.refreshToken },
+        )
+
+        // Another tab rotated the token a moment ago, and the browser already holds the new one.
+        if (response.status === 409) {
+          return true
+        }
+
+        if (!response.ok) {
+          await tokens?.write(null)
+          return false
+        }
+
+        await tokens?.write((await response.json()) as Tokens)
+        return true
+      } finally {
+        refreshing = undefined
+      }
+    })()
+
+    return refreshing
+  }
+
+  // Every request to the API goes through here: with a bearer when there is one, and refreshed once on a 401.
+  const authorized: Transport = async (input, init) => {
+    const attempt = async () => {
+      const headers = new Headers(init?.headers)
+      const stored = await tokens?.read()
+
+      if (stored !== null && stored !== undefined) {
+        headers.set('authorization', `Bearer ${stored.accessToken}`)
+      }
+
+      return fetch(input, { ...init, headers })
+    }
+    const response = await attempt()
+
+    if (response.status !== 401 || !(await refresh())) {
+      return response
+    }
+
+    return attempt()
+  }
+
+  return {
+    baseUrl,
+    fetch: authorized,
+    refresh,
+
+    signUp: (request: SignUpRequest) => begin('/sign-up', request),
+
+    signIn: async (request: SignInRequest): Promise<void> => {
+      await begin('/sign-in', request)
+    },
+
+    // prumo:email
+    // Each answers alike for an unknown email, so a form can say "if the account exists, a code is on its way".
+    requestEmailVerification: (email: string) => ask('/email/verification', { email }),
+
+    verifyEmail: async (request: VerifyEmailRequest): Promise<void> => {
+      await begin('/email/verify', request)
+    },
+
+    requestPasswordReset: (email: string) => ask('/password/forgot', { email }),
+
+    resetPassword: async (request: ResetPasswordRequest): Promise<void> => {
+      await begin('/password/reset', request)
+    },
+    // prumo:end-email
+    // prumo:social
+    // Where to send the browser to sign in with a provider: the API takes it there and back. The web comes back
+    // signed in; a mobile app comes back with a code to exchange.
+    socialSignInUrl: (provider: SocialProvider, client: 'web' | 'mobile', returnTo = '/') =>
+      `${url(`/social/${provider}`)}?${new URLSearchParams({ client, returnTo })}`,
+
+    exchangeSocialCode: async (code: string): Promise<void> => {
+      await begin('/social/exchange', { code })
+    },
+    // prumo:end-social
+
+    // The device forgets the tokens whether or not the request arrives: signing out locally is what was asked.
+    async signOut(): Promise<void> {
+      try {
+        const response = await authorized(url('/sign-out'), { method: 'POST' })
+
+        if (!response.ok && response.status !== 401) {
+          throw await ApiError.fromResponse(response)
+        }
+      } finally {
+        await tokens?.write(null)
+      }
+    },
+
+    // A visitor without a session is not an error: the answer is null.
+    async getSession(): Promise<Session | null> {
+      const response = await authorized(url('/session'))
+
+      if (response.status === 401) {
+        return null
+      }
+
+      if (!response.ok) {
+        throw await ApiError.fromResponse(response)
+      }
+
+      return (await response.json()) as Session
+    },
+  }
+}
+
+export const sessionQuery = (auth: Pick<AuthClient, 'getSession'>) =>
+  queryOptions({ queryKey: ['session'], queryFn: () => auth.getSession() })

package/templates/web/src/api-contract/index.ts

@@ -1,4 +1,18 @@
 export { ApiError, type FieldErrors } from './api-error'
+export {
+  type AuthClient,
+  createAuthClient,
+  type ResetPasswordRequest, // prumo:email
+  type Session,
+  type SignInRequest,
+  type SignUpRequest,
+  type SignUpResult,
+  type SocialProvider, // prumo:social
+  sessionQuery,
+  type TokenStore,
+  type Tokens,
+  type VerifyEmailRequest, // prumo:email
+} from './auth'
 export { type ApiClient, createClient, type Transport } from './client'
 export {
   LOCALES,

package/templates/web/src/features/auth/forgot-password-form.tsx

@@ -0,0 +1,52 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import { useNavigate } from '@tanstack/react-router'
+import { useForm } from 'react-hook-form'
+import { z } from 'zod'
+import type { AuthClient } from '@/api-contract'
+import { Button } from '@/components/ui/button'
+import { Field, FieldError, FieldGroup, FieldLabel } from '@/components/ui/field'
+import { Input } from '@/components/ui/input'
+import { FormError } from '@/features/forms/form-error'
+import { applyServerError } from '@/features/forms/server-errors'
+
+const schema = z.object({ email: z.email() })
+
+type ForgotPasswordValues = z.infer<typeof schema>
+
+export function ForgotPasswordForm({ auth }: { auth: Pick<AuthClient, 'requestPasswordReset'> }) {
+  const navigate = useNavigate()
+  const form = useForm<ForgotPasswordValues>({
+    resolver: zodResolver(schema),
+    mode: 'onTouched',
+    defaultValues: { email: '' },
+  })
+  const { errors, isSubmitting } = form.formState
+
+  async function onSubmit(values: ForgotPasswordValues) {
+    try {
+      await auth.requestPasswordReset(values.email)
+    } catch (error) {
+      applyServerError(error, ['email'], form.setError)
+      return
+    }
+
+    // The API answers alike whether the account exists, so the next page cannot tell either.
+    await navigate({ to: '/reset-password', search: { email: values.email } })
+  }
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)} noValidate className="flex flex-col gap-6">
+      <FormError errors={errors} />
+      <FieldGroup>
+        <Field data-invalid={errors.email !== undefined}>
+          <FieldLabel htmlFor="email">Email</FieldLabel>
+          <Input id="email" type="email" autoComplete="email" {...form.register('email')} />
+          <FieldError errors={[errors.email]} />
+        </Field>
+      </FieldGroup>
+      <Button type="submit" disabled={isSubmitting}>
+        Send a reset code
+      </Button>
+    </form>
+  )
+}