@startsimpli/auth 0.4.7 → 0.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/auth",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Shared authentication package for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -29,17 +29,18 @@
     "clean": "rm -rf dist"
   },
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "next": "^14.0.0 || ^15.0.0 || ^16.0.0"
+    "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
+    "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@types/node": "^20.17.14",
-    "@types/react": "^18.3.18",
-    "@vitest/ui": "^3.0.0",
-    "happy-dom": "^15.11.7",
+    "@types/node": "^20.19.39",
+    "@types/react": "^19.2.14",
+    "@vitest/ui": "^4.1.5",
+    "jsdom": "^29.0.2",
+    "@types/jsdom": "^21.1.7",
     "tsup": "^8.5.1",
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.0"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   },
   "keywords": [
     "authentication",

package/src/__tests__/auth-client-oauth-register.test.ts

@@ -0,0 +1,264 @@
+/**
+ * Contract tests for AuthClient register + OAuth support (bead gkat).
+ *
+ * These tests define the target API that unblocks raise-simpli's provider
+ * swap (bead q6vf). They are written to fail until the implementation lands.
+ *
+ * Scope of this file:
+ *  - AuthClient.register({ email, password, passwordConfirm, name? })
+ *  - AuthClient.signInWithGoogle(redirectTo?)
+ *  - AuthClient.completeGoogleCallback(code, state)
+ *
+ * A sibling test file (auth-context-oauth-register.test.tsx) covers the same
+ * features through the AuthProvider/useAuth surface.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { AuthClient } from '../client/auth-client'
+
+function makeToken(exp: number): string {
+  const header = btoa(JSON.stringify({ alg: 'HS256', typ: 'JWT' }))
+  const body = btoa(JSON.stringify({ tokenType: 'access', exp, iat: exp - 3600, jti: 'test', userId: '123' }))
+  return `${header}.${body}.signature`
+}
+
+const VALID_TOKEN = makeToken(Math.floor(Date.now() / 1000) + 3600)
+
+function makeConfig() {
+  return { apiBaseUrl: 'http://localhost:8001' }
+}
+
+function userPayload(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'user-1',
+    email: 'new@example.com',
+    first_name: 'New',
+    last_name: 'User',
+    is_email_verified: false,
+    created_at: '2026-04-20T00:00:00Z',
+    updated_at: '2026-04-20T00:00:00Z',
+    ...overrides,
+  }
+}
+
+describe('AuthClient.register (contract)', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('POSTs { email, password, password_confirm, name } to /api/v1/auth/register/ and returns a Session', async () => {
+    const client = new AuthClient(makeConfig())
+    const mockFetch = vi.fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          access: VALID_TOKEN,
+          user: userPayload({ email: 'new@example.com', first_name: 'New', last_name: 'User' }),
+        }),
+      })
+    vi.stubGlobal('fetch', mockFetch)
+
+    const session = await client.register({
+      email: 'new@example.com',
+      password: 'SecurePass1!',
+      passwordConfirm: 'SecurePass1!',
+      name: 'New User',
+    })
+
+    // Request shape
+    const call = mockFetch.mock.calls[0]
+    expect(call[0]).toContain('/api/v1/auth/register/')
+    expect(call[1].method).toBe('POST')
+    const body = JSON.parse(call[1].body as string)
+    expect(body.email).toBe('new@example.com')
+    expect(body.password).toBe('SecurePass1!')
+    // Backend expects snake_case for confirmation field
+    expect(body.password_confirm).toBe('SecurePass1!')
+    expect(body.name).toBe('New User')
+
+    // Return shape
+    expect(session.accessToken).toBe(VALID_TOKEN)
+    expect(session.user.email).toBe('new@example.com')
+    expect(session.user.firstName).toBe('New')
+    expect(session.user.lastName).toBe('User')
+    expect(session.expiresAt).toBeGreaterThan(Date.now())
+  })
+
+  it('throws a readable error when backend rejects (e.g. email already exists)', async () => {
+    const client = new AuthClient(makeConfig())
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValueOnce({
+      ok: false,
+      status: 400,
+      json: async () => ({
+        error: 'VALIDATION_ERROR',
+        detail: { email: ['user with this email already exists.'] },
+      }),
+    }))
+
+    await expect(
+      client.register({ email: 'taken@example.com', password: 'x', passwordConfirm: 'x' })
+    ).rejects.toThrow(/already exists/i)
+  })
+
+  it('fetches /me/ when the register response has no user payload', async () => {
+    const client = new AuthClient(makeConfig())
+    vi.stubGlobal('fetch', vi.fn()
+      // register response: access only, no user
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({ access: VALID_TOKEN }),
+      })
+      // fallback /me/
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({ user: userPayload({ email: 'fetched@example.com' }) }),
+      }))
+
+    const session = await client.register({
+      email: 'fetched@example.com',
+      password: 'SecurePass1!',
+      passwordConfirm: 'SecurePass1!',
+    })
+
+    expect(session.user.email).toBe('fetched@example.com')
+  })
+
+  it('starts the refresh timer on successful register (same as login)', async () => {
+    const client = new AuthClient(makeConfig())
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ access: VALID_TOKEN, user: userPayload() }),
+    }))
+
+    await client.register({ email: 'new@example.com', password: 'x', passwordConfirm: 'x' })
+
+    // The refresh timer is a private member — asserting via internal state
+    // is brittle, but the behavior we care about is observable: getSession
+    // should return a non-null session after register.
+    const session = client.getSession()
+    expect(session).not.toBeNull()
+  })
+
+  it('mirrors the access token into module-level storage (functions.ts getAccessToken)', async () => {
+    const client = new AuthClient(makeConfig())
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ access: VALID_TOKEN, user: userPayload() }),
+    }))
+
+    const { getAccessToken, setAccessToken } = await import('../client/functions')
+    setAccessToken(null) // start clean
+
+    await client.register({ email: 'new@example.com', password: 'x', passwordConfirm: 'x' })
+
+    // @startsimpli/api's FetchWrapper reads via this module-level getter.
+    // Without the mirror, useAuth().session would have a token but API calls
+    // would go out unauthenticated.
+    expect(getAccessToken()).toBe(VALID_TOKEN)
+  })
+})
+
+describe('AuthClient.signInWithGoogle (contract)', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('GETs /api/v1/auth/oauth/google/initiate/ (optionally with redirect_to) and returns the auth URL', async () => {
+    const client = new AuthClient(makeConfig())
+    const mockFetch = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({ auth_url: 'https://accounts.google.com/o/oauth2/v2/auth?...' }),
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    const url = await client.signInWithGoogle('/dashboard')
+
+    const call = mockFetch.mock.calls[0]
+    expect(call[0]).toContain('/api/v1/auth/oauth/google/initiate/')
+    // Method may be GET or POST depending on implementation — just verify it
+    // round-trips the redirect target if the implementation supports it.
+    expect(url).toBe('https://accounts.google.com/o/oauth2/v2/auth?...')
+  })
+
+  it('throws when the backend fails to produce an auth URL', async () => {
+    const client = new AuthClient(makeConfig())
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValueOnce({
+      ok: false,
+      status: 500,
+      json: async () => ({ detail: 'OAuth provider unavailable' }),
+    }))
+
+    await expect(
+      client.signInWithGoogle()
+    ).rejects.toThrow(/OAuth|unavailable/i)
+  })
+})
+
+describe('AuthClient.completeGoogleCallback (contract)', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('exchanges code+state at /api/v1/auth/oauth/google/callback/ and returns a Session', async () => {
+    const client = new AuthClient(makeConfig())
+    const mockFetch = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        access: VALID_TOKEN,
+        user: userPayload({ email: 'oauth@example.com', first_name: 'OAuth', last_name: 'User' }),
+      }),
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    const session = await client.completeGoogleCallback('test-code', 'test-state')
+
+    const call = mockFetch.mock.calls[0]
+    const url = typeof call[0] === 'string' ? call[0] : call[0].url
+    expect(url).toContain('/api/v1/auth/oauth/google/callback/')
+    expect(url).toContain('code=test-code')
+    expect(url).toContain('state=test-state')
+
+    expect(session.accessToken).toBe(VALID_TOKEN)
+    expect(session.user.email).toBe('oauth@example.com')
+    expect(session.expiresAt).toBeGreaterThan(Date.now())
+  })
+
+  it('throws a readable error when Google rejects the exchange (invalid/expired state)', async () => {
+    const client = new AuthClient(makeConfig())
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValueOnce({
+      ok: false,
+      status: 400,
+      json: async () => ({ detail: 'Invalid or expired state parameter' }),
+    }))
+
+    await expect(
+      client.completeGoogleCallback('bad-code', 'bad-state')
+    ).rejects.toThrow(/state|invalid|expired/i)
+  })
+
+  it('populates session from /me/ when callback response has no user payload', async () => {
+    const client = new AuthClient(makeConfig())
+    vi.stubGlobal('fetch', vi.fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({ access: VALID_TOKEN }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({ user: userPayload({ email: 'oauth-me@example.com' }) }),
+      }))
+
+    const session = await client.completeGoogleCallback('ok-code', 'ok-state')
+
+    expect(session.user.email).toBe('oauth-me@example.com')
+  })
+})

package/src/__tests__/auth-fetch.test.ts

@@ -39,21 +39,6 @@ function makeJwt(payload: object): string {
 const VALID_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 3600, userId: '1' });
 const REFRESHED_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 7200, userId: '1' });
 
-// Stub the CSRF token helper so refreshAccessToken() doesn't fail
-vi.mock('../utils/cookies', () => ({
-  getCsrfToken: () => 'test-csrf',
-  setCsrfToken: vi.fn(),
-}));
-
-// Stub fetchCsrfToken (called inside refreshAccessToken)
-vi.mock('../client/functions', async (importOriginal) => {
-  const original = await importOriginal<typeof import('../client/functions')>();
-  return {
-    ...original,
-    fetchCsrfToken: vi.fn().mockResolvedValue(undefined),
-  };
-});
-
 describe('authFetch — concurrent 401 refresh atomicity (uhxu)', () => {
   beforeEach(() => {
     vi.clearAllMocks();

package/src/__tests__/auth-functions.test.ts

@@ -72,6 +72,7 @@ const {
   setAccessToken,
   getAccessToken,
   setOnSessionExpired,
+  notifySessionExpired,
   setRememberMe,
 } = await import('../client/functions');
 
@@ -212,6 +213,236 @@ describe('authFetch session expiration on unrecoverable 401', () => {
   });
 });
 
+describe('verifyEmail error extraction (nested DRF validation shape)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSessionStorage.clear();
+    mockLocalStorage.clear();
+  });
+
+  it('extracts nested detail.token[0] string from validation error', async () => {
+    mockFetch.mockImplementation(() =>
+      Promise.resolve({
+        ok: false,
+        status: 400,
+        json: async () => ({
+          error: 'VALIDATION_ERROR',
+          detail: { token: ['Invalid verification link. Please check the link or request a new one.'] },
+        }),
+      })
+    );
+
+    let caught: Error | null = null;
+    try {
+      const { verifyEmail } = await import('../client/functions');
+      await verifyEmail('bad-token');
+    } catch (err) {
+      caught = err as Error;
+    }
+
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toBe('Invalid verification link. Please check the link or request a new one.');
+    expect(caught!.message).not.toBe('[object Object]');
+  });
+
+  it('falls back to fallback text when body has no extractable string', async () => {
+    mockFetch.mockImplementation(() =>
+      Promise.resolve({
+        ok: false,
+        status: 500,
+        json: async () => ({}),
+      })
+    );
+
+    let caught: Error | null = null;
+    try {
+      const { verifyEmail } = await import('../client/functions');
+      await verifyEmail('bad-token');
+    } catch (err) {
+      caught = err as Error;
+    }
+
+    expect(caught!.message).toBe('Failed to verify email');
+  });
+
+  it('handles string detail (standard DRF shape)', async () => {
+    mockFetch.mockImplementation(() =>
+      Promise.resolve({
+        ok: false,
+        status: 400,
+        json: async () => ({ detail: 'Token has expired.' }),
+      })
+    );
+
+    let caught: Error | null = null;
+    try {
+      const { verifyEmail } = await import('../client/functions');
+      await verifyEmail('expired');
+    } catch (err) {
+      caught = err as Error;
+    }
+
+    expect(caught!.message).toBe('Token has expired.');
+  });
+});
+
+describe('extractApiError prefers human-readable error string over code fields', () => {
+  it('returns "error" message (not "code") for { error, code } shape', async () => {
+    // Re-import so we pick up the current module for each test run
+    const { extractApiError } = await import('../client/functions')
+    const msg = extractApiError(
+      {
+        error: 'No active account found with the given credentials',
+        code: 'unauthorized',
+        statusCode: 401,
+      },
+      'Login failed'
+    )
+    expect(msg).toBe('No active account found with the given credentials')
+  })
+
+  it('prefers detail.string over error', async () => {
+    const { extractApiError } = await import('../client/functions')
+    const msg = extractApiError({ detail: 'Account is locked', error: 'locked' }, 'x')
+    expect(msg).toBe('Account is locked')
+  })
+
+  it('returns nested detail.field[0] when detail is an object', async () => {
+    const { extractApiError } = await import('../client/functions')
+    const msg = extractApiError({ detail: { token: ['Invalid token'] } }, 'x')
+    expect(msg).toBe('Invalid token')
+  })
+
+  it('ignores code/statusCode/timestamp fields when looking for a message', async () => {
+    const { extractApiError } = await import('../client/functions')
+    const msg = extractApiError(
+      { code: 'unauthorized', statusCode: 401, timestamp: '2026-01-01' },
+      'fallback'
+    )
+    expect(msg).toBe('fallback')
+  })
+
+  it('falls back when no message fields exist', async () => {
+    const { extractApiError } = await import('../client/functions')
+    expect(extractApiError({}, 'Login failed')).toBe('Login failed')
+  })
+})
+
+describe('refreshAccessToken — transient vs permanent failures', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockSessionStorage.clear()
+    mockLocalStorage.clear()
+    setAccessToken(VALID_TOKEN)
+  })
+
+  it('returns null and CLEARS the access token on 401 (session dead)', async () => {
+    const { refreshAccessToken } = await import('../client/functions')
+    mockFetch.mockImplementation(() =>
+      Promise.resolve({
+        ok: false,
+        status: 401,
+        json: async () => ({}),
+      })
+    )
+    const result = await refreshAccessToken()
+    expect(result).toBeNull()
+    expect(getAccessToken()).toBeNull()
+  })
+
+  it('returns null and CLEARS the access token on 403 (session rejected)', async () => {
+    const { refreshAccessToken } = await import('../client/functions')
+    mockFetch.mockImplementation(() =>
+      Promise.resolve({
+        ok: false,
+        status: 403,
+        json: async () => ({}),
+      })
+    )
+    const result = await refreshAccessToken()
+    expect(result).toBeNull()
+    expect(getAccessToken()).toBeNull()
+  })
+
+  it('THROWS TransientRefreshError on 500 (backend down) and KEEPS the access token', async () => {
+    const { refreshAccessToken, TransientRefreshError } = await import('../client/functions')
+    mockFetch.mockImplementation(() =>
+      Promise.resolve({
+        ok: false,
+        status: 500,
+        statusText: 'Internal Server Error',
+        json: async () => ({}),
+      })
+    )
+
+    await expect(refreshAccessToken()).rejects.toBeInstanceOf(TransientRefreshError)
+    expect(getAccessToken()).toBe(VALID_TOKEN)
+  })
+
+  it('THROWS TransientRefreshError on 503 (service unavailable) and KEEPS the token', async () => {
+    const { refreshAccessToken, TransientRefreshError } = await import('../client/functions')
+    mockFetch.mockImplementation(() =>
+      Promise.resolve({
+        ok: false,
+        status: 503,
+        statusText: 'Service Unavailable',
+        json: async () => ({}),
+      })
+    )
+
+    await expect(refreshAccessToken()).rejects.toBeInstanceOf(TransientRefreshError)
+    expect(getAccessToken()).toBe(VALID_TOKEN)
+  })
+
+  it('THROWS TransientRefreshError on fetch network failure and KEEPS the token', async () => {
+    const { refreshAccessToken, TransientRefreshError } = await import('../client/functions')
+    mockFetch.mockImplementation(() => Promise.reject(new TypeError('Failed to fetch')))
+
+    await expect(refreshAccessToken()).rejects.toBeInstanceOf(TransientRefreshError)
+    expect(getAccessToken()).toBe(VALID_TOKEN)
+  })
+})
+
+describe('notifySessionExpired cooldown', () => {
+  beforeEach(() => {
+    setOnSessionExpired(null);
+  });
+
+  afterEach(() => {
+    setOnSessionExpired(null);
+  });
+
+  it('fires the registered callback at most once per cooldown window', () => {
+    const onExpired = vi.fn();
+    setOnSessionExpired(onExpired);
+
+    notifySessionExpired();
+    notifySessionExpired();
+    notifySessionExpired();
+    notifySessionExpired();
+    notifySessionExpired();
+
+    expect(onExpired).toHaveBeenCalledTimes(1);
+  });
+
+  it('no-ops when no callback is registered', () => {
+    expect(() => notifySessionExpired()).not.toThrow();
+  });
+
+  it('resets the cooldown when a new callback is registered', () => {
+    const first = vi.fn();
+    setOnSessionExpired(first);
+    notifySessionExpired();
+    expect(first).toHaveBeenCalledTimes(1);
+
+    // re-register: cooldown resets, so next notify should fire the new callback
+    const second = vi.fn();
+    setOnSessionExpired(second);
+    notifySessionExpired();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe('signOut cookie cleanup', () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -258,20 +489,41 @@ describe('refreshAccessToken clears session on failure', () => {
   });
 
   it('clears token when refresh endpoint returns non-ok', async () => {
-    mockFetch.mockImplementation((url: string) => {
-      if (typeof url === 'string' && url.includes('/csrf/')) {
-        return Promise.resolve({ ok: true });
-      }
-      return Promise.resolve({
+    mockFetch.mockImplementation(() =>
+      Promise.resolve({
         ok: false,
         status: 401,
         json: async () => ({ detail: 'Token expired' }),
-      });
-    });
+      })
+    );
 
     const result = await refreshAccessToken();
 
     expect(result).toBeNull();
     expect(getAccessToken()).toBeNull();
   });
+
+  it('does not fetch the CSRF endpoint or send X-CSRFToken', async () => {
+    mockFetch.mockImplementation(() =>
+      Promise.resolve({
+        ok: true,
+        status: 200,
+        json: async () => ({ access: VALID_TOKEN }),
+      })
+    );
+
+    await refreshAccessToken();
+
+    const csrfCall = mockFetch.mock.calls.find(
+      (c: unknown[]) => typeof c[0] === 'string' && (c[0] as string).includes('/csrf/')
+    );
+    expect(csrfCall).toBeUndefined();
+
+    const refreshCall = mockFetch.mock.calls.find(
+      (c: unknown[]) => typeof c[0] === 'string' && (c[0] as string).includes('/auth/token/refresh/')
+    );
+    expect(refreshCall).toBeDefined();
+    const headers = refreshCall![1]?.headers;
+    expect(headers['X-CSRFToken']).toBeUndefined();
+  });
 });

package/src/__tests__/setup.ts

@@ -0,0 +1,38 @@
+// Node 25 installs globalThis.localStorage / sessionStorage = {} (stub with
+// no Storage methods) before jsdom/happy-dom load, and the DOM env can't
+// override an already-defined global. Replace both with working in-memory
+// Storage impls so tests can use bare `localStorage` / `sessionStorage`.
+class MemStorage implements Storage {
+  private store: Record<string, string> = {};
+  get length(): number {
+    return Object.keys(this.store).length;
+  }
+  clear(): void {
+    this.store = {};
+  }
+  getItem(key: string): string | null {
+    return Object.prototype.hasOwnProperty.call(this.store, key) ? this.store[key] : null;
+  }
+  setItem(key: string, value: string): void {
+    this.store[key] = String(value);
+  }
+  removeItem(key: string): void {
+    delete this.store[key];
+  }
+  key(i: number): string | null {
+    return Object.keys(this.store)[i] ?? null;
+  }
+}
+
+Object.defineProperty(globalThis, 'localStorage', {
+  configurable: true,
+  writable: true,
+  value: new MemStorage(),
+});
+Object.defineProperty(globalThis, 'sessionStorage', {
+  configurable: true,
+  writable: true,
+  value: new MemStorage(),
+});
+
+export {};