howone 0.1.11 → 0.1.12

package/templates/vite/.howone/skills/howone-sdk/references/04-auth.md

@@ -0,0 +1,484 @@
+# Auth
+
+## Two Auth Layers
+
+HowOne has two distinct auth layers:
+
+1. **Client-level auth** (`client.auth.*`) — low-level token management, login/logout redirects.  
+2. **HowOne Auth service** (`unifiedAuth`, standalone functions) — headless OTP and OAuth flows for building custom login UIs.
+
+For React auth UI, see `references/06-react-integration.md` (`HowOneProvider`, `useHowoneContext`).
+
+---
+
+## client.auth — Token Management
+
+```ts
+import howone from '@/lib/sdk'
+
+// Check if the current user is authenticated
+howone.auth.isAuthenticated() // boolean
+
+// Get the current JWT token (null if not logged in)
+const token = howone.auth.getToken()
+
+// Manually set a token (after a custom login flow)
+howone.auth.setToken(jwtToken)
+
+// Clear the token
+howone.auth.setToken(null)
+
+// Redirect to the HowOne login page
+howone.auth.login()
+howone.auth.login('/dashboard') // optional return path after login
+
+// Log out and clear session
+howone.auth.logout()
+```
+
+---
+
+## User Profile
+
+```ts
+import { HowOneAuthError } from '@howone/sdk'
+import howone from '@/lib/sdk'
+
+type UserProfile = {
+  id: string
+  email?: string
+  name?: string
+  avatarUrl?: string
+  roles?: string[]
+  metadata?: Record<string, unknown>
+}
+
+// Returns null if not authenticated
+const user = await howone.me()
+
+// Returns the profile or throws HowOneAuthError if not authenticated
+const user = await howone.requireMe()
+
+// Alias for me()
+const user = await howone.session.user()
+
+// Force refresh from server (skip cache)
+const user = await howone.me({ refresh: true })
+```
+
+### Pattern: guard a page
+
+```tsx
+import { useEffect, useState } from 'react'
+import { HowOneAuthError } from '@howone/sdk'
+import howone, { type UserProfile } from '@/lib/sdk'
+
+function useCurrentUser() {
+  const [user, setUser] = useState<UserProfile | null>(null)
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    howone.me()
+      .then(setUser)
+      .catch(err => {
+        if (err instanceof HowOneAuthError) {
+          howone.auth.login()
+        }
+      })
+      .finally(() => setLoading(false))
+  }, [])
+
+  return { user, loading }
+}
+```
+
+---
+
+## Email OTP Login
+
+Use `sendEmailVerificationCode` → `loginWithEmailCode` to build a custom email login form.
+
+### Standalone functions (imported directly)
+
+```ts
+import {
+  sendEmailVerificationCode,
+  loginWithEmailCode,
+} from '@howone/sdk'
+
+// Step 1 — send OTP
+const sendResult = await sendEmailVerificationCode(
+  'user@example.com',
+  'MyAppName', // optional, shown in the email
+)
+// sendResult.success: boolean
+// sendResult.expiresIn: number (seconds until expiry)
+// sendResult.message: string (error message if !success)
+// sendResult.code: number (business error code if any)
+
+// Step 2 — verify OTP and get token
+const loginResult = await loginWithEmailCode(
+  'user@example.com',
+  '123456', // 6-digit OTP from email
+)
+// loginResult.success: boolean
+// loginResult.token: string (JWT, present on success)
+// loginResult.user: { email, name? }
+// loginResult.redirect_url: string (if configured)
+// loginResult.message: string
+// loginResult.code: number
+
+if (loginResult.success && loginResult.token) {
+  howone.auth.setToken(loginResult.token)
+  // Now client.auth.isAuthenticated() === true
+}
+```
+
+### Using the unifiedAuth service
+
+```ts
+import { unifiedAuth } from '@howone/sdk'
+
+// Same API as standalone functions
+const sendResult = await unifiedAuth.sendEmailVerificationCode(email, appName)
+const loginResult = await unifiedAuth.loginWithEmailCode(email, code)
+
+// Verify an existing token
+const { valid, user } = await unifiedAuth.verifyToken(token)
+
+// Logout (server-side invalidation)
+await unifiedAuth.logout(token)
+```
+
+### React component — email OTP form
+
+```tsx
+import { useState } from 'react'
+import { sendEmailVerificationCode, loginWithEmailCode } from '@howone/sdk'
+import howone from '@/lib/sdk'
+
+type Step = 'email' | 'code' | 'done'
+
+export function EmailLoginForm({ onSuccess }: { onSuccess: () => void }) {
+  const [step, setStep] = useState<Step>('email')
+  const [email, setEmail] = useState('')
+  const [code, setCode] = useState('')
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  async function handleSendCode(e: React.FormEvent) {
+    e.preventDefault()
+    setLoading(true)
+    setError(null)
+    try {
+      const result = await sendEmailVerificationCode(email)
+      if (!result.success) {
+        setError(result.message ?? 'Failed to send code')
+        return
+      }
+      setStep('code')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  async function handleVerifyCode(e: React.FormEvent) {
+    e.preventDefault()
+    setLoading(true)
+    setError(null)
+    try {
+      const result = await loginWithEmailCode(email, code)
+      if (!result.success || !result.token) {
+        setError(result.message ?? 'Invalid code')
+        return
+      }
+      howone.auth.setToken(result.token)
+      setStep('done')
+      onSuccess()
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  if (step === 'email') {
+    return (
+      <form onSubmit={handleSendCode}>
+        <input
+          type="email"
+          value={email}
+          onChange={e => setEmail(e.target.value)}
+          placeholder="Enter your email"
+          required
+        />
+        {error && <p className="error">{error}</p>}
+        <button type="submit" disabled={loading}>
+          {loading ? 'Sending...' : 'Send Code'}
+        </button>
+      </form>
+    )
+  }
+
+  if (step === 'code') {
+    return (
+      <form onSubmit={handleVerifyCode}>
+        <p>Enter the code sent to {email}</p>
+        <input
+          type="text"
+          value={code}
+          onChange={e => setCode(e.target.value)}
+          placeholder="6-digit code"
+          maxLength={6}
+          required
+        />
+        {error && <p className="error">{error}</p>}
+        <button type="submit" disabled={loading}>
+          {loading ? 'Verifying...' : 'Login'}
+        </button>
+        <button type="button" onClick={() => setStep('email')}>
+          Back
+        </button>
+      </form>
+    )
+  }
+
+  return <p>Login successful!</p>
+}
+```
+
+---
+
+## Phone OTP Login
+
+Same flow as email, using E.164 phone number format (e.g. `+14155552671`).
+
+```ts
+import {
+  sendPhoneVerificationCode,
+  loginWithPhoneCode,
+} from '@howone/sdk'
+
+// Step 1 — send SMS OTP
+const sendResult = await sendPhoneVerificationCode(
+  '+14155552671', // must be E.164 format
+  'MyAppName',    // optional
+)
+// sendResult.success: boolean
+// sendResult.expires_in: number (seconds)
+
+// Step 2 — verify OTP
+const loginResult = await loginWithPhoneCode(
+  '+14155552671',
+  '123456',
+)
+// loginResult.success: boolean
+// loginResult.token: string (JWT on success)
+// loginResult.user: { phone_e164?, email?, name? }
+
+if (loginResult.success && loginResult.token) {
+  howone.auth.setToken(loginResult.token)
+}
+```
+
+### Phone number validation note
+
+The SDK validates that phone numbers are in E.164 format internally. Always pass the number with country code (e.g. `+1`, `+44`, `+86`).
+
+---
+
+## OAuth — Google and GitHub
+
+### Google Login
+
+```ts
+import { unifiedAuth } from '@howone/sdk'
+import howone from '@/lib/sdk'
+
+async function loginWithGoogle() {
+  // Opens a popup window for Google OAuth
+  const result = await unifiedAuth.initiateGoogleLogin()
+  // result.token: string (JWT)
+  // result.user: any
+
+  howone.auth.setToken(result.token)
+}
+```
+
+### GitHub Login
+
+```ts
+import { unifiedAuth } from '@howone/sdk'
+
+async function loginWithGitHub() {
+  const result = await unifiedAuth.initiateGitHubLogin()
+  howone.auth.setToken(result.token)
+}
+```
+
+### Handle OAuth redirect callback
+
+If you redirect instead of using a popup, call `checkOAuthCallback()` on the return page:
+
+```ts
+import { unifiedOAuth } from '@howone/sdk'
+import howone from '@/lib/sdk'
+
+// Call on the OAuth callback page (e.g. /auth/callback)
+function handleOAuthReturn() {
+  const result = unifiedOAuth.checkOAuthCallback()
+  // result.success: boolean
+  // result.token: string (if success)
+  // result.error: string (if failure)
+  // result.user: any
+
+  if (result.success && result.token) {
+    howone.auth.setToken(result.token)
+    window.location.href = '/dashboard'
+  } else {
+    console.error('OAuth failed:', result.error)
+  }
+}
+```
+
+### React — OAuth buttons
+
+```tsx
+import { unifiedAuth } from '@howone/sdk'
+import howone from '@/lib/sdk'
+
+export function OAuthButtons({ onSuccess }: { onSuccess: () => void }) {
+  const [loading, setLoading] = useState<'google' | 'github' | null>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  async function handleGoogle() {
+    setLoading('google')
+    setError(null)
+    try {
+      const { token } = await unifiedAuth.initiateGoogleLogin()
+      howone.auth.setToken(token)
+      onSuccess()
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Google login failed')
+    } finally {
+      setLoading(null)
+    }
+  }
+
+  async function handleGitHub() {
+    setLoading('github')
+    setError(null)
+    try {
+      const { token } = await unifiedAuth.initiateGitHubLogin()
+      howone.auth.setToken(token)
+      onSuccess()
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'GitHub login failed')
+    } finally {
+      setLoading(null)
+    }
+  }
+
+  return (
+    <div>
+      <button onClick={handleGoogle} disabled={loading !== null}>
+        {loading === 'google' ? 'Connecting...' : 'Continue with Google'}
+      </button>
+      <button onClick={handleGitHub} disabled={loading !== null}>
+        {loading === 'github' ? 'Connecting...' : 'Continue with GitHub'}
+      </button>
+      {error && <p className="error">{error}</p>}
+    </div>
+  )
+}
+```
+
+---
+
+## Token Verification
+
+```ts
+import { unifiedAuth } from '@howone/sdk'
+
+async function checkToken(token: string) {
+  const { valid, user } = await unifiedAuth.verifyToken(token)
+  if (valid) {
+    console.log('User:', user)
+  } else {
+    console.log('Token is invalid or expired')
+  }
+}
+```
+
+---
+
+## Logout
+
+```ts
+// Client-side logout (clears local token storage)
+howone.auth.logout()
+
+// Server-side invalidation via unifiedAuth
+await unifiedAuth.logout(token)
+```
+
+---
+
+## HowOneAuthError
+
+```ts
+import { HowOneAuthError } from '@howone/sdk'
+
+try {
+  const user = await howone.requireMe()
+} catch (err) {
+  if (err instanceof HowOneAuthError) {
+    // err.code === 'UNAUTHENTICATED'
+    howone.auth.login('/current-page')
+  }
+}
+```
+
+---
+
+## Auth Mode in createClient
+
+Choose the auth mode that matches your login strategy:
+
+```ts
+// Managed (default) — SDK owns the token lifecycle
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  auth: { mode: 'managed' },
+})
+
+// Headless — you own the token (for Clerk, Supabase, custom JWTs, etc.)
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  auth: {
+    mode: 'headless',
+    getToken: async () => {
+      return localStorage.getItem('auth_token')
+    },
+    tokenCacheMs: 30_000,
+  },
+})
+
+// None — unauthenticated, public API access only
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  auth: { mode: 'none' },
+})
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Correct Pattern |
+|---|---|
+| Phone number without country code: `'13800138000'` | Use E.164: `'+8613800138000'` |
+| Using `loginWithEmailCode` without first calling `sendEmailVerificationCode` | Always send the code first |
+| Setting token manually when using `auth.mode: 'managed'` | Use `managed` mode which handles storage, or switch to `headless` |
+| Calling `unifiedAuth.logout()` without the token argument | Pass `token`: `await unifiedAuth.logout(howone.auth.getToken()!)` |