@startsimpli/auth 0.4.8 → 0.4.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/auth",
-  "version": "0.4.8",
+  "version": "0.4.11",
   "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-functions.test.ts

@@ -213,6 +213,196 @@ 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);

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 {};

package/src/__tests__/useauth-shape-contract.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Type-level contract test for the target useAuth() return shape (bead gkat).
+ *
+ * The goal of bead q6vf is to let raise-simpli replace its forked AuthProvider
+ * with @startsimpli/auth's shared AuthProvider. For that to work, useAuth()
+ * must surface OAuth + registration (currently only exposed through the
+ * standalone functional API).
+ *
+ * This file documents — at the type level — the shape we're committing to.
+ * It fails to compile until UseAuthReturn in use-auth.ts is extended.
+ */
+
+import { describe, it, expect } from 'vitest'
+import type { UseAuthReturn } from '../client/use-auth'
+
+describe('useAuth() shape contract (target API)', () => {
+  it('has existing methods (baseline)', () => {
+    type Baseline = Pick<
+      UseAuthReturn,
+      'user' | 'session' | 'isLoading' | 'isAuthenticated' | 'login' | 'logout' | 'refreshUser' | 'getAccessToken'
+    >
+    const _: Baseline = null as unknown as Baseline
+    expect(true).toBe(true)
+  })
+
+  it('exposes register(payload) returning Promise<void>', () => {
+    type Register = UseAuthReturn['register']
+    // Lock the parameter shape. The AuthProvider-wrapped return is Promise<void>
+    // because the provider updates context state rather than returning Session
+    // (consumers call useAuth().session / user after the promise resolves).
+    const _: (payload: {
+      email: string
+      password: string
+      passwordConfirm: string
+      name?: string
+      firstName?: string
+      lastName?: string
+    }) => Promise<void> = null as unknown as Register
+    expect(_).toBeNull()
+  })
+
+  it('exposes signInWithGoogle(redirectTo?) returning Promise<string> (the auth URL)', () => {
+    type SignIn = UseAuthReturn['signInWithGoogle']
+    const _: (redirectTo?: string) => Promise<string> = null as unknown as SignIn
+    expect(_).toBeNull()
+  })
+
+  it('exposes completeGoogleCallback(code, state) returning Promise<void>', () => {
+    type Callback = UseAuthReturn['completeGoogleCallback']
+    const _: (code: string, state: string) => Promise<void> = null as unknown as Callback
+    expect(_).toBeNull()
+  })
+})
+
+/**
+ * Shape reference (what raise-simpli's forked auth-context currently expects
+ * from its own useAuth; we need the shared hook to cover the same surface
+ * modulo naming — see bead q6vf for the full call-site mapping).
+ *
+ *   useAuth().signIn(email, password)        → useAuth().login(email, password)
+ *   useAuth().signOut()                       → useAuth().logout()
+ *   useAuth().refresh()                       → useAuth().refreshUser()  (semantics differ, see q6vf)
+ *   useAuth().register(payload)               → useAuth().register(payload)          [NEW]
+ *   useAuth().handleOAuthSuccess({access,user}) → useAuth().completeGoogleCallback() [NEW]
+ *   useAuth().user                            → useAuth().user
+ *   useAuth().status                          → useAuth().isLoading + isAuthenticated
+ *   useAuth().accessToken                     → useAuth().getAccessToken()
+ */