@opensaas/stack-auth 0.31.1 → 0.32.0

package/src/ui/components/ForgotPasswordForm.tsx

@@ -1,14 +1,15 @@
 'use client'
 
 import React, { useState } from 'react'
-import type { createAuthClient } from 'better-auth/react'
+import { cleanAuthErrorMessage } from '../lib/clean-error-message.js'
+import type { RequestPasswordResetAction } from '../types.js'
 
 export type ForgotPasswordFormProps = {
   /**
-   * Better-auth client instance
-   * Created with createAuthClient from better-auth/react
+   * Server action that requests a password-reset email.
+   * Define it in your app (`'use server'`) against your own auth instance.
    */
-  authClient: ReturnType<typeof createAuthClient>
+  requestPasswordResetAction: RequestPasswordResetAction
   /**
    * Custom CSS class for the form container
    */
@@ -27,18 +28,21 @@ export type ForgotPasswordFormProps = {
  * Forgot password form component
  * Allows users to request a password reset email
  *
+ * Submits through an app-owned server action rather than calling the auth API
+ * from the browser. See the "Auth action" contract in `@opensaas/stack-auth/ui`.
+ *
  * @example
  * ```typescript
  * import { ForgotPasswordForm } from '@opensaas/stack-auth/ui'
- * import { authClient } from '@/lib/auth-client'
+ * import { requestPasswordResetAction } from '@/lib/actions/auth'
  *
  * export default function ForgotPasswordPage() {
- *   return <ForgotPasswordForm authClient={authClient} />
+ *   return <ForgotPasswordForm requestPasswordResetAction={requestPasswordResetAction} />
  * }
  * ```
  */
 export function ForgotPasswordForm({
-  authClient,
+  requestPasswordResetAction,
   className = '',
   onSuccess,
   onError,
@@ -55,19 +59,19 @@ export function ForgotPasswordForm({
     setLoading(true)
 
     try {
-      const result = await authClient.requestPasswordReset({
-        email,
-        redirectTo: '/reset-password',
-      })
+      const result = await requestPasswordResetAction({ email })
 
-      if (result.error) {
-        throw new Error(result.error.message)
+      if (!result.success) {
+        throw new Error(cleanAuthErrorMessage(result.error, 'Failed to send reset email'))
       }
 
       setSuccess(true)
       onSuccess?.()
     } catch (err) {
-      const message = err instanceof Error ? err.message : 'Failed to send reset email'
+      const message = cleanAuthErrorMessage(
+        err instanceof Error ? err.message : undefined,
+        'Failed to send reset email',
+      )
       setError(message)
       onError?.(err instanceof Error ? err : new Error(message))
     } finally {

package/src/ui/components/ResetPasswordForm.tsx

@@ -0,0 +1,182 @@
+'use client'
+
+import React, { useState } from 'react'
+import { useRouter } from 'next/navigation.js'
+import { cleanAuthErrorMessage } from '../lib/clean-error-message.js'
+import type { ResetPasswordAction } from '../types.js'
+
+export type ResetPasswordFormProps = {
+  /**
+   * Server action that completes the password reset.
+   * Define it in your app (`'use server'`) against your own auth instance.
+   */
+  resetPasswordAction: ResetPasswordAction
+  /**
+   * The reset token from the email link. The page reads it from
+   * `searchParams.token` and passes it in. When empty, the form renders an
+   * "invalid or expired link" state instead of a password form.
+   */
+  token: string
+  /**
+   * URL to redirect to after a successful reset
+   * @default '/sign-in'
+   */
+  redirectTo?: string
+  /**
+   * Require password confirmation
+   * @default true
+   */
+  requirePasswordConfirmation?: boolean
+  /**
+   * Custom CSS class for the form container
+   */
+  className?: string
+  /**
+   * Callback when the reset succeeds
+   */
+  onSuccess?: () => void
+  /**
+   * Callback when the reset fails
+   */
+  onError?: (error: Error) => void
+}
+
+/**
+ * Reset password form component
+ * Completes a password reset using the token from the reset email.
+ *
+ * Submits through an app-owned server action rather than calling the auth API
+ * from the browser. See the "Auth action" contract in `@opensaas/stack-auth/ui`.
+ *
+ * @example
+ * ```typescript
+ * import { ResetPasswordForm } from '@opensaas/stack-auth/ui'
+ * import { resetPasswordAction } from '@/lib/actions/auth'
+ *
+ * export default async function ResetPasswordPage({
+ *   searchParams,
+ * }: {
+ *   searchParams: Promise<{ token?: string }>
+ * }) {
+ *   const { token } = await searchParams
+ *   return <ResetPasswordForm resetPasswordAction={resetPasswordAction} token={token ?? ''} />
+ * }
+ * ```
+ */
+export function ResetPasswordForm({
+  resetPasswordAction,
+  token,
+  redirectTo = '/sign-in',
+  requirePasswordConfirmation = true,
+  className = '',
+  onSuccess,
+  onError,
+}: ResetPasswordFormProps) {
+  const router = useRouter()
+  const [password, setPassword] = useState('')
+  const [confirmPassword, setConfirmPassword] = useState('')
+  const [error, setError] = useState('')
+  const [loading, setLoading] = useState(false)
+
+  // Guard: no token means the user hit this page directly or followed a
+  // malformed/expired link. Don't render a form that can't succeed.
+  if (!token) {
+    return (
+      <div className={`w-full max-w-md mx-auto p-6 ${className}`}>
+        <h2 className="text-2xl font-bold mb-6">Reset Password</h2>
+        <div className="bg-red-50 border border-red-200 text-red-700 px-4 py-3 rounded">
+          This password reset link is invalid or has expired. Please request a new one.
+        </div>
+      </div>
+    )
+  }
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setError('')
+
+    if (requirePasswordConfirmation && password !== confirmPassword) {
+      setError('Passwords do not match')
+      return
+    }
+
+    setLoading(true)
+
+    try {
+      const result = await resetPasswordAction({ token, password })
+
+      if (!result.success) {
+        throw new Error(cleanAuthErrorMessage(result.error, 'Failed to reset password'))
+      }
+
+      if (onSuccess) {
+        onSuccess()
+      } else {
+        router.push(redirectTo)
+      }
+    } catch (err) {
+      const message = cleanAuthErrorMessage(
+        err instanceof Error ? err.message : undefined,
+        'Failed to reset password',
+      )
+      setError(message)
+      onError?.(err instanceof Error ? err : new Error(message))
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div className={`w-full max-w-md mx-auto p-6 ${className}`}>
+      <h2 className="text-2xl font-bold mb-6">Reset Password</h2>
+
+      {error && (
+        <div className="bg-red-50 border border-red-200 text-red-700 px-4 py-3 rounded mb-4">
+          {error}
+        </div>
+      )}
+
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <div>
+          <label htmlFor="password" className="block text-sm font-medium mb-2">
+            New Password
+          </label>
+          <input
+            id="password"
+            type="password"
+            value={password}
+            onChange={(e) => setPassword((e.target as HTMLInputElement).value)}
+            required
+            className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+            disabled={loading}
+          />
+        </div>
+
+        {requirePasswordConfirmation && (
+          <div>
+            <label htmlFor="confirmPassword" className="block text-sm font-medium mb-2">
+              Confirm New Password
+            </label>
+            <input
+              id="confirmPassword"
+              type="password"
+              value={confirmPassword}
+              onChange={(e) => setConfirmPassword((e.target as HTMLInputElement).value)}
+              required
+              className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+              disabled={loading}
+            />
+          </div>
+        )}
+
+        <button
+          type="submit"
+          disabled={loading}
+          className="w-full bg-blue-600 text-white py-2 px-4 rounded-md hover:bg-blue-700 disabled:bg-gray-400 disabled:cursor-not-allowed"
+        >
+          {loading ? 'Resetting...' : 'Reset Password'}
+        </button>
+      </form>
+    </div>
+  )
+}

package/src/ui/components/SignInForm.tsx

@@ -2,22 +2,27 @@
 
 import React, { useState } from 'react'
 import { useRouter } from 'next/navigation.js'
-import type { createAuthClient } from 'better-auth/react'
+import { cleanAuthErrorMessage } from '../lib/clean-error-message.js'
+import type { SignInAction, SignInSocialAction } from '../types.js'
 
 export type SignInFormProps = {
   /**
-   * Better-auth client instance
-   * Created with createAuthClient from better-auth/react
-   * Pass your client from lib/auth-client.ts
+   * Server action that signs a user in with email + password.
+   * Define it in your app (`'use server'`) against your own auth instance.
    */
-  authClient: ReturnType<typeof createAuthClient>
+  signInAction: SignInAction
+  /**
+   * Server action that starts an OAuth sign-in and redirects to the provider.
+   * Required to render the social provider buttons; omit to hide them.
+   */
+  signInSocialAction?: SignInSocialAction
   /**
    * URL to redirect to after successful sign in
    * @default '/'
    */
   redirectTo?: string
   /**
-   * Show OAuth provider buttons
+   * Show OAuth provider buttons (requires `signInSocialAction`)
    * @default true
    */
   showSocialProviders?: boolean
@@ -44,18 +49,28 @@ export type SignInFormProps = {
  * Sign in form component
  * Provides email/password sign in and OAuth provider buttons
  *
+ * Submits through app-owned server actions rather than calling the auth API
+ * from the browser. See the "Auth action" contract in `@opensaas/stack-auth/ui`.
+ *
  * @example
  * ```typescript
  * import { SignInForm } from '@opensaas/stack-auth/ui'
- * import { authClient } from '@/lib/auth-client'
+ * import { signInAction, signInSocialAction } from '@/lib/actions/auth'
  *
  * export default function SignInPage() {
- *   return <SignInForm authClient={authClient} redirectTo="/admin" />
+ *   return (
+ *     <SignInForm
+ *       signInAction={signInAction}
+ *       signInSocialAction={signInSocialAction}
+ *       redirectTo="/admin"
+ *     />
+ *   )
  * }
  * ```
  */
 export function SignInForm({
-  authClient,
+  signInAction,
+  signInSocialAction,
   redirectTo = '/',
   showSocialProviders = true,
   socialProviders = ['github', 'google'],
@@ -75,14 +90,10 @@ export function SignInForm({
     setLoading(true)
 
     try {
-      const result = await authClient.signIn.email({
-        email,
-        password,
-        callbackURL: redirectTo,
-      })
-
-      if (result.error) {
-        throw new Error(result.error.message)
+      const result = await signInAction({ email, password })
+
+      if (!result.success) {
+        throw new Error(cleanAuthErrorMessage(result.error, 'Sign in failed'))
       }
 
       // If onSuccess is provided, call it. Otherwise, automatically redirect
@@ -92,7 +103,10 @@ export function SignInForm({
         router.push(redirectTo)
       }
     } catch (err) {
-      const message = err instanceof Error ? err.message : 'Sign in failed'
+      const message = cleanAuthErrorMessage(
+        err instanceof Error ? err.message : undefined,
+        'Sign in failed',
+      )
       setError(message)
       onError?.(err instanceof Error ? err : new Error(message))
     } finally {
@@ -101,25 +115,28 @@ export function SignInForm({
   }
 
   const handleSocialSignIn = async (provider: string) => {
+    if (!signInSocialAction) return
     setError('')
     setLoading(true)
 
     try {
-      await authClient.signIn.social({
-        provider,
-        callbackURL: redirectTo,
-      })
-      // Social sign-in handles its own redirect via OAuth flow
-      // Only call onSuccess if provided
+      // The action performs a server-side redirect to the provider, so on
+      // success control does not return here.
+      await signInSocialAction(provider)
       onSuccess?.()
     } catch (err) {
-      const message = err instanceof Error ? err.message : 'Sign in failed'
+      const message = cleanAuthErrorMessage(
+        err instanceof Error ? err.message : undefined,
+        'Sign in failed',
+      )
       setError(message)
       onError?.(err instanceof Error ? err : new Error(message))
       setLoading(false)
     }
   }
 
+  const canShowSocial = showSocialProviders && socialProviders.length > 0 && !!signInSocialAction
+
   return (
     <div className={`w-full max-w-md mx-auto p-6 ${className}`}>
       <h2 className="text-2xl font-bold mb-6">Sign In</h2>
@@ -170,7 +187,7 @@ export function SignInForm({
         </button>
       </form>
 
-      {showSocialProviders && socialProviders.length > 0 && (
+      {canShowSocial && (
         <>
           <div className="relative my-6">
             <div className="absolute inset-0 flex items-center">

package/src/ui/components/SignUpForm.tsx

@@ -2,21 +2,27 @@
 
 import React, { useState } from 'react'
 import { useRouter } from 'next/navigation.js'
-import type { createAuthClient } from 'better-auth/react'
+import { cleanAuthErrorMessage } from '../lib/clean-error-message.js'
+import type { SignUpAction, SignInSocialAction } from '../types.js'
 
 export type SignUpFormProps = {
   /**
-   * Better-auth client instance
-   * Created with createAuthClient from better-auth/react
+   * Server action that creates an account with email + password.
+   * Define it in your app (`'use server'`) against your own auth instance.
    */
-  authClient: ReturnType<typeof createAuthClient>
+  signUpAction: SignUpAction
+  /**
+   * Server action that starts an OAuth sign-in and redirects to the provider.
+   * Required to render the social provider buttons; omit to hide them.
+   */
+  signInSocialAction?: SignInSocialAction
   /**
    * URL to redirect to after successful sign up
    * @default '/'
    */
   redirectTo?: string
   /**
-   * Show OAuth provider buttons
+   * Show OAuth provider buttons (requires `signInSocialAction`)
    * @default true
    */
   showSocialProviders?: boolean
@@ -48,18 +54,22 @@ export type SignUpFormProps = {
  * Sign up form component
  * Provides email/password registration and OAuth provider buttons
  *
+ * Submits through app-owned server actions rather than calling the auth API
+ * from the browser. See the "Auth action" contract in `@opensaas/stack-auth/ui`.
+ *
  * @example
  * ```typescript
  * import { SignUpForm } from '@opensaas/stack-auth/ui'
- * import { authClient } from '@/lib/auth-client'
+ * import { signUpAction, signInSocialAction } from '@/lib/actions/auth'
  *
  * export default function SignUpPage() {
- *   return <SignUpForm authClient={authClient} redirectTo="/admin" />
+ *   return <SignUpForm signUpAction={signUpAction} redirectTo="/admin" />
  * }
  * ```
  */
 export function SignUpForm({
-  authClient,
+  signUpAction,
+  signInSocialAction,
   redirectTo = '/',
   showSocialProviders = true,
   socialProviders = ['github', 'google'],
@@ -89,18 +99,10 @@ export function SignUpForm({
     setLoading(true)
 
     try {
-      const result = await authClient.signUp.email({
-        email,
-        password,
-        name,
-        callbackURL: redirectTo,
-      })
-
-      if (result.error) {
-        // Strip [body.field] prefixes from better-call validation errors for user-friendly display
-        const rawMessage = result.error.message ?? 'Sign up failed'
-        const cleanMessage = rawMessage.replace(/\[body\.\w+\]\s*/g, '').trim()
-        throw new Error(cleanMessage)
+      const result = await signUpAction({ name, email, password })
+
+      if (!result.success) {
+        throw new Error(cleanAuthErrorMessage(result.error, 'Sign up failed'))
       }
 
       // If onSuccess is provided, call it. Otherwise, automatically redirect
@@ -110,7 +112,10 @@ export function SignUpForm({
         router.push(redirectTo)
       }
     } catch (err) {
-      const message = err instanceof Error ? err.message : 'Sign up failed'
+      const message = cleanAuthErrorMessage(
+        err instanceof Error ? err.message : undefined,
+        'Sign up failed',
+      )
       setError(message)
       onError?.(err instanceof Error ? err : new Error(message))
     } finally {
@@ -119,25 +124,28 @@ export function SignUpForm({
   }
 
   const handleSocialSignUp = async (provider: string) => {
+    if (!signInSocialAction) return
     setError('')
     setLoading(true)
 
     try {
-      await authClient.signIn.social({
-        provider,
-        callbackURL: redirectTo,
-      })
-      // Social sign-in handles its own redirect via OAuth flow
-      // Only call onSuccess if provided
+      // The action performs a server-side redirect to the provider, so on
+      // success control does not return here.
+      await signInSocialAction(provider)
       onSuccess?.()
     } catch (err) {
-      const message = err instanceof Error ? err.message : 'Sign up failed'
+      const message = cleanAuthErrorMessage(
+        err instanceof Error ? err.message : undefined,
+        'Sign up failed',
+      )
       setError(message)
       onError?.(err instanceof Error ? err : new Error(message))
       setLoading(false)
     }
   }
 
+  const canShowSocial = showSocialProviders && socialProviders.length > 0 && !!signInSocialAction
+
   return (
     <div className={`w-full max-w-md mx-auto p-6 ${className}`}>
       <h2 className="text-2xl font-bold mb-6">Sign Up</h2>
@@ -220,7 +228,7 @@ export function SignUpForm({
         </button>
       </form>
 
-      {showSocialProviders && socialProviders.length > 0 && (
+      {canShowSocial && (
         <>
           <div className="relative my-6">
             <div className="absolute inset-0 flex items-center">

package/src/ui/index.ts

@@ -1,7 +1,24 @@
 export { SignInForm } from './components/SignInForm.js'
 export { SignUpForm } from './components/SignUpForm.js'
 export { ForgotPasswordForm } from './components/ForgotPasswordForm.js'
+export { ResetPasswordForm } from './components/ResetPasswordForm.js'
 
 export type { SignInFormProps } from './components/SignInForm.js'
 export type { SignUpFormProps } from './components/SignUpForm.js'
 export type { ForgotPasswordFormProps } from './components/ForgotPasswordForm.js'
+export type { ResetPasswordFormProps } from './components/ResetPasswordForm.js'
+
+// Auth action contract types — the agreement between the forms and the
+// app-owned server actions they invoke.
+export type {
+  AuthActionResult,
+  SignInInput,
+  SignUpInput,
+  RequestPasswordResetInput,
+  ResetPasswordInput,
+  SignInAction,
+  SignUpAction,
+  RequestPasswordResetAction,
+  ResetPasswordAction,
+  SignInSocialAction,
+} from './types.js'

package/src/ui/lib/clean-error-message.ts

@@ -0,0 +1,21 @@
+/**
+ * Strip better-call's `[body.field]` validation prefixes from an auth error
+ * message so forms can display something user-friendly.
+ *
+ * Better-auth surfaces validation errors like `[body.password] Password is too
+ * short`. This removes those bracketed prefixes and normalises whitespace,
+ * falling back to a default when the message is empty or missing.
+ *
+ * Internal to the auth forms — not part of the package's public contract.
+ */
+export function cleanAuthErrorMessage(
+  message: string | null | undefined,
+  fallback = 'Something went wrong',
+): string {
+  if (!message) return fallback
+  const cleaned = message
+    .replace(/\[body\.\w+\]\s*/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return cleaned || fallback
+}

package/src/ui/types.ts

@@ -0,0 +1,49 @@
+/**
+ * Contract types shared between the pre-built auth forms and the app-owned
+ * server actions they invoke.
+ *
+ * The forms live in this package but never own an `auth` instance. Instead each
+ * form receives **Auth actions** as props — `'use server'` functions the app
+ * defines against its own better-auth instance. These types are the agreement
+ * between the two: the app implements actions matching them, the forms call
+ * actions matching them.
+ */
+
+/**
+ * The result an email/password (non-redirecting) auth action returns.
+ * Success carries no payload; failure carries a display-ready message.
+ */
+export type AuthActionResult = { success: true } | { success: false; error: string }
+
+/** Input to the sign-in action. */
+export type SignInInput = { email: string; password: string }
+
+/** Input to the sign-up action. */
+export type SignUpInput = { name: string; email: string; password: string }
+
+/** Input to the request-password-reset action. */
+export type RequestPasswordResetInput = { email: string }
+
+/** Input to the reset-password action. */
+export type ResetPasswordInput = { token: string; password: string }
+
+/** Signs a user in with email + password. */
+export type SignInAction = (input: SignInInput) => Promise<AuthActionResult>
+
+/** Creates an account with email + password. */
+export type SignUpAction = (input: SignUpInput) => Promise<AuthActionResult>
+
+/** Requests a password-reset email. */
+export type RequestPasswordResetAction = (
+  input: RequestPasswordResetInput,
+) => Promise<AuthActionResult>
+
+/** Completes a password reset using a token from the reset email. */
+export type ResetPasswordAction = (input: ResetPasswordInput) => Promise<AuthActionResult>
+
+/**
+ * Starts an OAuth sign-in for the given provider. Unlike the email actions this
+ * one navigates away (it performs a server-side redirect to the provider), so
+ * it resolves to `void` and never returns a result to the form.
+ */
+export type SignInSocialAction = (provider: string) => Promise<void>

package/tests/clean-error-message.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest'
+import { cleanAuthErrorMessage } from '../src/ui/lib/clean-error-message.js'
+
+describe('cleanAuthErrorMessage', () => {
+  it('strips a single [body.field] prefix', () => {
+    expect(cleanAuthErrorMessage('[body.password] Password too short')).toBe('Password too short')
+  })
+
+  it('strips multiple [body.field] prefixes', () => {
+    expect(cleanAuthErrorMessage('[body.email] invalid [body.password] weak')).toBe('invalid weak')
+  })
+
+  it('leaves a clean message untouched', () => {
+    expect(cleanAuthErrorMessage('Invalid email or password')).toBe('Invalid email or password')
+  })
+
+  it('falls back to a default when the message is empty or nullish', () => {
+    expect(cleanAuthErrorMessage('', 'Sign in failed')).toBe('Sign in failed')
+    expect(cleanAuthErrorMessage(undefined, 'Sign in failed')).toBe('Sign in failed')
+  })
+
+  it('uses a generic default when none is provided', () => {
+    expect(cleanAuthErrorMessage(undefined)).toBe('Something went wrong')
+  })
+
+  it('trims surrounding whitespace left after stripping', () => {
+    expect(cleanAuthErrorMessage('  [body.name]   Name is required  ')).toBe('Name is required')
+  })
+})