howone 0.1.22 → 0.1.25

package/templates/vite/.howone/skills/howone-sdk/03-sdk/04-react-integration.md

@@ -2,399 +2,190 @@
 
 ## What `@howone/sdk/react` Provides
 
-`@howone/sdk/react` is a **thin UI layer** for auth state, theme, and loading spinners. It does **not** provide entity, query, or AI data hooks.
+Thin integration layer: auth context plus the HowOne floating brand button. **No** entity hooks,
+AI hooks, toast system, redirect overlay, or app-owned UI.
 
 Exports:
-- `HowOneProvider` — all-in-one app provider (auth, theme, toasts, floating button)
-- `useHowoneContext` — access auth state (user, token, isAuthenticated, logout)
-- `FloatingButton` — a floating action button (shows Login when unauthenticated)
-- `Loading` — full-page or inline loading component
-- `LoadingSpinner` — headless spinner for composition
 
----
-
-## Import
-
-```ts
-import {
-  HowOneProvider,
-  useHowoneContext,
-  FloatingButton,
-  Loading,
-  LoadingSpinner,
-} from '@howone/sdk/react'
-```
+- `HowOneProvider`
+- `useHowoneContext`
+- `FloatingButton`
 
 ---
 
-## HowOneProvider
-
-Wrap your entire app. Provides auth, theme, and toast context to all children.
+## Auth: one SDK config + one Provider flag
 
-`HowOneProvider` reads SDK environment and project defaults from `createClient`. Configure
-`projectId` and `env` once in `src/lib/sdk.ts`; do not pass a separate env to the provider.
-
-```tsx
-// main.tsx or app/layout.tsx
-import React from 'react'
-import ReactDOM from 'react-dom/client'
-import { HowOneProvider } from '@howone/sdk/react'
-import './lib/sdk'
-import App from './App'
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <HowOneProvider
-      auth="required"
-      brand="visible"
-      theme="system"
-    >
-      <App />
-    </HowOneProvider>
-  </React.StrictMode>
-)
-```
-
-### HowOneProviderProps
+**Step 1 — `src/lib/sdk.ts` (required):**
 
 ```ts
-type HowOneAuthMode = 'required' | 'optional' | 'none'
-type HowOneThemeMode = 'dark' | 'light' | 'system' | 'inherit'
-type HowOneBrandMode = 'visible' | 'hidden'
-
-interface HowOneProviderProps {
-  children: React.ReactNode
-
-  // Optional override. Prefer configuring projectId once in createClient.
-  projectId?: string
-
-  // Auth behaviour
-  auth?: HowOneAuthMode
-  // 'required' — redirects unauthenticated users to login page
-  // 'optional' — allows both authenticated and unauthenticated users
-  // 'none'     — disables auth entirely
-
-  // Brand button (HowOne branding)
-  brand?: HowOneBrandMode          // default: 'visible'
-  showBrandButton?: boolean        // alias for brand
-
-  // Theme
-  theme?: HowOneThemeMode          // default: 'system'
-  themeStorageKey?: string         // localStorage key for theme preference
-  forceTheme?: boolean             // ignore user preference and force theme
-}
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+})
 ```
 
-### Common provider configurations
+**Step 2 — Provider:**
 
 ```tsx
-// Public app — no auth required
-<HowOneProvider auth="none" theme="system" brand="hidden">
-  <App />
-</HowOneProvider>
-
-// Auth-gated app — redirect to login if not authenticated
-<HowOneProvider auth="required" theme="system">
-  <App />
-</HowOneProvider>
-
-// Optional auth — user can browse without logging in
-<HowOneProvider auth="optional" theme="inherit" brand="visible">
-  <App />
-</HowOneProvider>
+import { HowOneProvider } from '@howone/sdk/react'
+import './lib/sdk' // must import before Provider so auth config is registered
 
-// Dark mode forced
-<HowOneProvider auth="required" theme="dark" forceTheme>
+<HowOneProvider auth="none" brand="visible">
   <App />
 </HowOneProvider>
 ```
 
----
-
-## useHowoneContext
-
-Access auth state inside any component wrapped by `HowOneProvider`.
-
-```ts
-type HowoneContextValue = {
-  user: {
-    id: string       // backend owner id; same as userId when JWT has userId
-    userId?: string  // authenticated backend user id when present in JWT
-    puid?: string    // public UUID; do not use as public ownerId scope
-    email: string
-    name: string
-    avatar: string
-    appId?: string
-  } | null
-  token: string | null
-  isAuthenticated: boolean
-  logout: () => void
-}
-```
+| Layer | Setting | Meaning |
+|-------|---------|---------|
+| `createClient` | `{ projectId, env }` (default **hosted**) | Login/logout → HowOne `/auth` |
+| `createClient` | `auth: 'custom'` | Login/logout → your `loginPath`; APIs still HowOne |
+| `HowOneProvider` | `auth="required"` | Default with hosted — redirect to HowOne login |
+| `HowOneProvider` | `auth="none"` | Use with `auth: 'custom'`; guard routes yourself |
 
-### Usage
+Default (HowOne hosted login):
 
 ```tsx
-import { useHowoneContext } from '@howone/sdk/react'
-
-function UserMenu() {
-  const { user, isAuthenticated, logout } = useHowoneContext()
-
-  if (!isAuthenticated || !user) {
-    return <a href="/login">Login</a>
-  }
-
-  return (
-    <div>
-      <img src={user.avatar} alt={user.name} />
-      <span>{user.name}</span>
-      <button onClick={logout}>Logout</button>
-    </div>
-  )
-}
+createClient({ projectId, env })
+<HowOneProvider auth="required" />
 ```
 
-### Conditional rendering based on auth state
+Custom login page (your UI, HowOne auth APIs, keep HowOne logo unless product asks to hide it):
 
 ```tsx
-function Dashboard() {
-  const { isAuthenticated, user } = useHowoneContext()
-
-  if (!isAuthenticated) {
-    return <div>Please log in to continue.</div>
-  }
-
-  return <div>Welcome, {user?.name}!</div>
-}
+createClient({ projectId, env, auth: 'custom', loginPath: '/login' })
+<HowOneProvider auth="none" brand="visible" />
 ```
 
-### Using token for direct API calls
+---
+
+## HowOneProvider
 
 ```tsx
-import { useHowoneContext } from '@howone/sdk/react'
+<HowOneProvider
+  auth="none"
+  brand="visible"
+  onAuthRedirect={({ mode, returnUrl }) => {
+    // App may set its own loading/redirect state here.
+  }}
+  onAuthStateChange={(state) => {
+    // App may update analytics or local UI state here.
+  }}
+>
+  <App />
+</HowOneProvider>
+```
 
-function DebugPanel() {
-  const { token } = useHowoneContext()
+### HowOneProviderProps
 
-  async function copyToken() {
-    if (token) await navigator.clipboard.writeText(token)
-  }
+```ts
+type HowOneProviderAuth = 'required' | 'optional' | 'none'
 
-  return (
-    <button onClick={copyToken} disabled={!token}>
-      Copy JWT Token
-    </button>
-  )
+interface HowOneProviderProps {
+  children: React.ReactNode
+  projectId?: string // prefer createClient projectId
+  auth?: HowOneProviderAuth
+  brand?: 'visible' | 'hidden'
+  showBrandButton?: boolean
+  theme?: 'dark' | 'light' | 'system' | 'inherit'
+  onAuthStateChange?: (state: AuthState) => void
+  onAuthRedirect?: (info: { mode: 'hosted' | 'custom'; returnUrl: string }) => void
 }
 ```
 
----
-
-## FloatingButton
+**Important:** Provider `auth` is only a **route guard**. Login/logout URLs come from `createClient({ auth: 'custom' })`.
 
-A floating action button that renders in the bottom corner of the screen. When unauthenticated, it shows a "Login" label by default.
+The provider must not render app-owned UI. It does not own toasts, dialogs, pages, custom login UI,
+or redirect overlays. It does keep the bottom-right HowOne logo by default through `FloatingButton`.
+Use `brand="hidden"` or `showBrandButton={false}` only when the product explicitly asks to hide it.
 
-```tsx
-import { FloatingButton } from '@howone/sdk/react'
-
-// Default — shows Login/brand button
-<FloatingButton />
-
-// Custom text and handler
-<FloatingButton
-  text="Get Started"
-  onClick={() => router.push('/signup')}
-/>
-
-// Custom styling
-<FloatingButton
-  text="Support"
-  onClick={() => setShowChat(true)}
-  className="bg-blue-600 hover:bg-blue-700"
-/>
-```
+---
 
-### FloatingButtonProps
+## useHowoneContext
 
 ```ts
-interface FloatingButtonProps {
-  text?: string       // button label (default: 'Login' or brand text)
-  onClick?: () => void
-  className?: string  // additional CSS classes
-}
+const { user, token, isAuthenticated, logout } = useHowoneContext()
 ```
 
----
-
-## Loading Components
-
-### Loading — full-page or inline loading state
+### Logout
 
 ```tsx
-import { Loading } from '@howone/sdk/react'
+<button onClick={() => void logout()}>Sign out</button>
+```
 
-// Full-screen overlay
-<Loading fullScreen label="Loading your workspace..." />
+With `auth: 'custom'`, `logout()` clears session and navigates to `loginPath` — **not** howone.dev.
 
-// Inline with description
-<Loading
-  label="Generating story..."
-  description="This may take a moment"
-  size="lg"
-  tone="brand"
-/>
+Equivalent:
 
-// Minimal
-<Loading />
+```ts
+await howone.auth.logout()
 ```
 
-### LoadingSpinner — headless spinner
+### Custom login page link
 
 ```tsx
-import { LoadingSpinner } from '@howone/sdk/react'
-
-// Sizes: 'sm' | 'md' | 'lg'
-// Tones: 'brand' | 'neutral' | 'inverse'
-
-<LoadingSpinner size="md" tone="brand" />
-<LoadingSpinner size="sm" tone="neutral" className="mr-2" />
-```
+import { useNavigate } from 'react-router-dom'
+import howone from '@/lib/sdk'
 
-### LoadingProps
+function Header() {
+  const navigate = useNavigate()
+  const { isAuthenticated, logout } = useHowoneContext()
 
-```ts
-type LoadingSize = 'sm' | 'md' | 'lg'
-type LoadingTone = 'brand' | 'neutral' | 'inverse'
-
-interface LoadingProps {
-  size?: LoadingSize        // default: 'md'
-  tone?: LoadingTone        // default: 'brand'
-  label?: string            // primary text
-  description?: string      // secondary text
-  className?: string
-  fullScreen?: boolean      // renders over full viewport
-}
+  if (!isAuthenticated) {
+    return <button onClick={() => navigate(howone.auth.loginPath)}>Sign in</button>
+  }
 
-interface LoadingSpinnerProps {
-  size?: LoadingSize
-  tone?: LoadingTone
-  className?: string
+  return <button onClick={() => void logout()}>Sign out</button>
 }
 ```
 
 ---
 
-## Entity and AI Data in React
+## FloatingButton
+
+The bottom-right HowOne logo is part of the SDK React integration and should remain visible by
+default. It does not replace your login page and does not perform app auth. Hide it only with
+`brand="hidden"` or `showBrandButton={false}`.
 
-`@howone/sdk/react` provides **no data hooks**. Use `useEffect`/`useState` or TanStack Query around the plain async SDK calls.
+---
 
-### Pattern: auth-gated data fetch
+## Protected route pattern
 
 ```tsx
-import { useEffect, useState } from 'react'
-import { useHowoneContext } from '@howone/sdk/react'
-import { Loading } from '@howone/sdk/react'
-import howone, { type StoryRecord } from '@/lib/sdk'
-
-function MyStories() {
-  const { isAuthenticated } = useHowoneContext()
-  const [stories, setStories] = useState<StoryRecord[]>([])
-  const [loading, setLoading] = useState(false)
+function ProtectedPage() {
+  const [user, setUser] = useState(null)
+  const navigate = useNavigate()
 
   useEffect(() => {
-    if (!isAuthenticated) return
-
-    setLoading(true)
-    howone.entities.Story.query.mine({ page: { number: 1, size: 20 } })
-      .then(result => setStories(result.items))
-      .finally(() => setLoading(false))
-  }, [isAuthenticated])
-
-  if (!isAuthenticated) return <div>Please log in.</div>
-  if (loading) return <Loading label="Loading your stories..." />
-
-  return (
-    <ul>
-      {stories.map(s => <li key={s.id}>{s.title}</li>)}
-    </ul>
-  )
-}
-```
-
-### Pattern: Full app layout
+    howone.me()
+      .then(setUser)
+      .catch(() => navigate(howone.auth.loginPath, { replace: true }))
+  }, [navigate])
 
-```tsx
-// src/main.tsx
-import React from 'react'
-import ReactDOM from 'react-dom/client'
-import { HowOneProvider } from '@howone/sdk/react'
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import './lib/sdk'
-import App from './App'
-
-const queryClient = new QueryClient()
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <HowOneProvider
-      auth="required"
-      theme="system"
-      brand="visible"
-    >
-      <QueryClientProvider client={queryClient}>
-        <App />
-      </QueryClientProvider>
-    </HowOneProvider>
-  </React.StrictMode>
-)
+  if (!user) return null
+  return <div>Welcome {user.name}</div>
+}
 ```
 
-### Pattern: conditional AI action based on auth
-
-```tsx
-import { useState } from 'react'
-import { useHowoneContext } from '@howone/sdk/react'
-import howone from '@/lib/sdk'
+---
 
-function AIGenerateButton({ topic }: { topic: string }) {
-  const { isAuthenticated } = useHowoneContext()
-  const [loading, setLoading] = useState(false)
-  const [result, setResult] = useState<string | null>(null)
-
-  async function handleGenerate() {
-    if (!isAuthenticated) {
-      howone.auth.login()
-      return
-    }
-    setLoading(true)
-    try {
-      const res = await howone.ai.generateStory.run({ topic, language: 'en' })
-      if (res.success && res.finalResult) {
-        setResult((res.finalResult as any).content)
-      }
-    } finally {
-      setLoading(false)
-    }
-  }
+## Common mistakes
 
-  return (
-    <div>
-      <button onClick={handleGenerate} disabled={loading}>
-        {loading ? 'Generating...' : isAuthenticated ? 'Generate' : 'Login to Generate'}
-      </button>
-      {result && <p>{result}</p>}
-    </div>
-  )
-}
-```
+| Mistake | Fix |
+|---------|-----|
+| Custom UI but no `auth: 'custom'` | Add to `createClient` |
+| `HowOneProvider auth="required"` without custom SDK auth | Hosted redirect to howone.ai |
+| `useHowoneContext` without Provider | Wrap app in `HowOneProvider` |
+| Import Provider before `./lib/sdk` | Import sdk module first |
+| Manual redirect to howone.dev on logout | Use `howone.auth.logout()` |
+| Deleting the bottom-right HowOne logo by default | Keep `brand="visible"` unless explicitly asked to hide it |
+| Expecting SDK toast APIs | Implement visible feedback in the frontend app from callbacks/results |
 
 ---
 
-## Common Mistakes
+## Import map
 
-| Mistake | Correct Pattern |
-|---|---|
-| `import { useHowoneContext } from '@howone/sdk'` | Import from `'@howone/sdk/react'` |
-| Expecting entity data hooks from `useHowoneContext` | Use `useEffect`/`useState` + `howone.entities.*` directly |
-| Placing `<HowOneProvider>` inside a component that re-renders | Place at root level (main.tsx / app layout) |
-| Using `user.id` without null-checking `user` | Guard: `if (!user) return` or use optional chaining `user?.id` |
+| Need | Import |
+|------|--------|
+| Provider, context | `@howone/sdk/react` |
+| Client, OTP, OAuth | `@howone/sdk` |
+| App singleton | `@/lib/sdk` default export |