refactor: replace custom createAuthClient with official better-auth client

- Install better-auth as dependency in @object-ui/auth
- Rewrite createAuthClient.ts to delegate to better-auth/client createAuthClient
- Add resolveAuthURL helper to support both relative and absolute baseURLs
- Update MSW authHandlers to use better-auth endpoint name (forget-password)
- Update createAuthClient tests for new better-auth backed implementation
- All 81 existing tests pass, TypeScript compiles cleanly

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

apps/console/src/mocks/authHandlers.ts

@@ -14,7 +14,7 @@
  *   POST /sign-in/email  — authenticate with email + password
  *   GET  /get-session     — retrieve the current session
  *   POST /sign-out        — clear the session
- *   POST /forgot-password — no-op acknowledgement
+ *   POST /forget-password — no-op acknowledgement (better-auth convention)
  *   POST /reset-password  — no-op acknowledgement
  *   POST /update-user     — update the current user's profile
  */
@@ -163,8 +163,9 @@ export function createAuthHandlers(baseUrl: string): HttpHandler[] {
     }),
 
     // ── Forgot Password (mock acknowledgement) ──────────────────────────
-    http.post(`${p}/forgot-password`, () => {
-      return HttpResponse.json({ success: true });
+    // better-auth uses "forget-password" (not "forgot-password")
+    http.post(`${p}/forget-password`, () => {
+      return HttpResponse.json({ status: true });
     }),
 
     // ── Reset Password (mock acknowledgement) ────────────────────────────

packages/auth/package.json

@@ -34,7 +34,8 @@
     "react": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@object-ui/types": "workspace:*"
+    "@object-ui/types": "workspace:*",
+    "better-auth": "^1.5.4"
   },
   "devDependencies": {
     "@types/react": "19.2.14",

packages/auth/src/__tests__/createAuthClient.test.ts

@@ -1,21 +1,40 @@
 /**
- * Tests for createAuthClient
+ * Tests for createAuthClient (backed by official better-auth client)
  */
 
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { createAuthClient } from '../createAuthClient';
 import type { AuthClient } from '../types';
 
-describe('createAuthClient', () => {
-  let client: AuthClient;
-  let mockFetch: ReturnType<typeof vi.fn>;
-
-  beforeEach(() => {
-    mockFetch = vi.fn();
-    client = createAuthClient({ baseURL: '/api/auth', fetchFn: mockFetch });
+/**
+ * Helper: creates a mock fetch that routes requests based on URL
+ * and records every call for inspection.
+ */
+function createMockFetch(handlers: Record<string, { status?: number; body: unknown }>) {
+  const calls: Array<{ url: string; method: string; body: string | null }> = [];
+  const mockFn = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+    calls.push({ url, method: init?.method ?? 'GET', body: init?.body as string | null });
+    for (const [pattern, handler] of Object.entries(handlers)) {
+      if (url.includes(pattern)) {
+        return new Response(JSON.stringify(handler.body), {
+          status: handler.status ?? 200,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+    }
+    return new Response(JSON.stringify({ message: 'Not found' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
   });
+  return { mockFn, calls };
+}
 
+describe('createAuthClient', () => {
   it('creates a client with all expected methods', () => {
+    const { mockFn } = createMockFetch({});
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
     expect(client).toHaveProperty('signIn');
     expect(client).toHaveProperty('signUp');
     expect(client).toHaveProperty('signOut');
@@ -26,156 +45,150 @@ describe('createAuthClient', () => {
   });
 
   it('signIn sends POST to /sign-in/email', async () => {
-    const mockResponse = {
-      user: { id: '1', name: 'Test', email: 'test@test.com' },
-      session: { token: 'tok123' },
-    };
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve(mockResponse),
+    const { mockFn, calls } = createMockFetch({
+      '/sign-in/email': {
+        body: {
+          user: { id: '1', name: 'Test', email: 'test@test.com' },
+          session: { token: 'tok123', id: 's1', userId: '1', expiresAt: '2025-01-01' },
+        },
+      },
     });
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
 
     const result = await client.signIn({ email: 'test@test.com', password: 'pass123' });
 
-    expect(mockFetch).toHaveBeenCalledWith(
-      '/api/auth/sign-in/email',
-      expect.objectContaining({
-        method: 'POST',
-        credentials: 'include',
-        body: JSON.stringify({ email: 'test@test.com', password: 'pass123' }),
-      }),
-    );
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toContain('/api/auth/sign-in/email');
+    expect(calls[0].method).toBe('POST');
+    expect(JSON.parse(calls[0].body!)).toMatchObject({ email: 'test@test.com', password: 'pass123' });
     expect(result.user.email).toBe('test@test.com');
     expect(result.session.token).toBe('tok123');
   });
 
   it('signUp sends POST to /sign-up/email', async () => {
-    const mockResponse = {
-      user: { id: '2', name: 'New User', email: 'new@test.com' },
-      session: { token: 'tok456' },
-    };
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve(mockResponse),
+    const { mockFn, calls } = createMockFetch({
+      '/sign-up/email': {
+        body: {
+          user: { id: '2', name: 'New User', email: 'new@test.com' },
+          session: { token: 'tok456', id: 's2', userId: '2', expiresAt: '2025-01-01' },
+        },
+      },
     });
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
 
     const result = await client.signUp({ name: 'New User', email: 'new@test.com', password: 'pass123' });
 
-    expect(mockFetch).toHaveBeenCalledWith(
-      '/api/auth/sign-up/email',
-      expect.objectContaining({ method: 'POST' }),
-    );
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toContain('/api/auth/sign-up/email');
+    expect(calls[0].method).toBe('POST');
+    expect(JSON.parse(calls[0].body!)).toMatchObject({ email: 'new@test.com', name: 'New User' });
     expect(result.user.name).toBe('New User');
   });
 
   it('signOut sends POST to /sign-out', async () => {
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve({}),
+    const { mockFn, calls } = createMockFetch({
+      '/sign-out': { body: { success: true } },
     });
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
 
     await client.signOut();
 
-    expect(mockFetch).toHaveBeenCalledWith(
-      '/api/auth/sign-out',
-      expect.objectContaining({ method: 'POST' }),
-    );
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toContain('/api/auth/sign-out');
+    expect(calls[0].method).toBe('POST');
   });
 
   it('getSession sends GET to /get-session', async () => {
-    const mockSession = {
-      user: { id: '1', name: 'Test', email: 'test@test.com' },
-      session: { token: 'tok789' },
-    };
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve(mockSession),
+    const { mockFn, calls } = createMockFetch({
+      '/get-session': {
+        body: {
+          user: { id: '1', name: 'Test', email: 'test@test.com' },
+          session: { token: 'tok789', id: 's1', userId: '1', expiresAt: '2025-01-01' },
+        },
+      },
     });
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
 
     const result = await client.getSession();
 
-    expect(mockFetch).toHaveBeenCalledWith(
-      '/api/auth/get-session',
-      expect.objectContaining({ method: 'GET' }),
-    );
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toContain('/api/auth/get-session');
+    expect(calls[0].method).toBe('GET');
     expect(result?.user.id).toBe('1');
   });
 
   it('getSession returns null on failure', async () => {
-    mockFetch.mockRejectedValueOnce(new Error('Network error'));
+    const { mockFn } = createMockFetch({
+      '/get-session': { status: 401, body: { message: 'Unauthorized' } },
+    });
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
 
     const result = await client.getSession();
     expect(result).toBeNull();
   });
 
-  it('forgotPassword sends POST to /forgot-password', async () => {
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve({}),
+  it('forgotPassword sends POST to /forget-password', async () => {
+    const { mockFn, calls } = createMockFetch({
+      '/forget-password': { body: { status: true } },
     });
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
 
     await client.forgotPassword('test@test.com');
 
-    expect(mockFetch).toHaveBeenCalledWith(
-      '/api/auth/forgot-password',
-      expect.objectContaining({
-        method: 'POST',
-        body: JSON.stringify({ email: 'test@test.com' }),
-      }),
-    );
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toContain('/api/auth/forget-password');
+    expect(calls[0].method).toBe('POST');
+    expect(JSON.parse(calls[0].body!)).toMatchObject({ email: 'test@test.com' });
   });
 
   it('resetPassword sends POST to /reset-password', async () => {
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve({}),
+    const { mockFn, calls } = createMockFetch({
+      '/reset-password': { body: { status: true } },
     });
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
 
     await client.resetPassword('token123', 'newpass');
 
-    expect(mockFetch).toHaveBeenCalledWith(
-      '/api/auth/reset-password',
-      expect.objectContaining({
-        method: 'POST',
-        body: JSON.stringify({ token: 'token123', newPassword: 'newpass' }),
-      }),
-    );
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toContain('/api/auth/reset-password');
+    expect(calls[0].method).toBe('POST');
+    expect(JSON.parse(calls[0].body!)).toMatchObject({ token: 'token123', newPassword: 'newpass' });
   });
 
   it('throws error with server message on non-OK response', async () => {
-    mockFetch.mockResolvedValueOnce({
-      ok: false,
-      status: 401,
-      json: () => Promise.resolve({ message: 'Invalid credentials' }),
+    const { mockFn } = createMockFetch({
+      '/sign-in/email': {
+        status: 401,
+        body: { message: 'Invalid credentials', code: 'INVALID_CREDENTIALS' },
+      },
     });
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
 
     await expect(client.signIn({ email: 'x', password: 'y' })).rejects.toThrow('Invalid credentials');
   });
 
-  it('throws generic error when response has no message', async () => {
-    mockFetch.mockResolvedValueOnce({
-      ok: false,
-      status: 500,
-      json: () => Promise.reject(new Error('parse error')),
+  it('throws error on non-OK response without message', async () => {
+    const { mockFn } = createMockFetch({
+      '/sign-in/email': { status: 500, body: {} },
     });
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
 
-    await expect(client.signIn({ email: 'x', password: 'y' })).rejects.toThrow(
-      'Auth request failed with status 500',
-    );
+    await expect(client.signIn({ email: 'x', password: 'y' })).rejects.toThrow();
   });
 
   it('updateUser sends POST to /update-user and returns user', async () => {
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve({ user: { id: '1', name: 'Updated', email: 'test@test.com' } }),
+    const { mockFn, calls } = createMockFetch({
+      '/update-user': {
+        body: { user: { id: '1', name: 'Updated', email: 'test@test.com' } },
+      },
     });
+    const client = createAuthClient({ baseURL: 'http://localhost/api/auth', fetchFn: mockFn });
 
     const result = await client.updateUser({ name: 'Updated' });
 
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toContain('/api/auth/update-user');
+    expect(calls[0].method).toBe('POST');
     expect(result.name).toBe('Updated');
-    expect(mockFetch).toHaveBeenCalledWith(
-      '/api/auth/update-user',
-      expect.objectContaining({ method: 'POST' }),
-    );
   });
 });