howone 0.1.23 → 0.1.26

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

@@ -0,0 +1,191 @@
+# React Integration
+
+## What `@howone/sdk/react` Provides
+
+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`
+- `useHowoneContext`
+- `FloatingButton`
+
+---
+
+## Auth: one SDK config + one Provider flag
+
+**Step 1 — `src/lib/sdk.ts` (required):**
+
+```ts
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+})
+```
+
+**Step 2 — Provider:**
+
+```tsx
+import { HowOneProvider } from '@howone/sdk/react'
+import './lib/sdk' // must import before Provider so auth config is registered
+
+<HowOneProvider auth="none" brand="visible">
+  <App />
+</HowOneProvider>
+```
+
+| 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 |
+
+Default (HowOne hosted login):
+
+```tsx
+createClient({ projectId, env })
+<HowOneProvider auth="required" />
+```
+
+Custom login page (your UI, HowOne auth APIs, keep HowOne logo unless product asks to hide it):
+
+```tsx
+createClient({ projectId, env, auth: 'custom', loginPath: '/login' })
+<HowOneProvider auth="none" brand="visible" />
+```
+
+---
+
+## HowOneProvider
+
+```tsx
+<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>
+```
+
+### HowOneProviderProps
+
+```ts
+type HowOneProviderAuth = 'required' | 'optional' | 'none'
+
+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
+}
+```
+
+**Important:** Provider `auth` is only a **route guard**. Login/logout URLs come from `createClient({ auth: 'custom' })`.
+
+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.
+
+---
+
+## useHowoneContext
+
+```ts
+const { user, token, isAuthenticated, logout } = useHowoneContext()
+```
+
+### Logout
+
+```tsx
+<button onClick={() => void logout()}>Sign out</button>
+```
+
+With `auth: 'custom'`, `logout()` clears session and navigates to `loginPath` — **not** howone.dev.
+
+Equivalent:
+
+```ts
+await howone.auth.logout()
+```
+
+### Custom login page link
+
+```tsx
+import { useNavigate } from 'react-router-dom'
+import howone from '@/lib/sdk'
+
+function Header() {
+  const navigate = useNavigate()
+  const { isAuthenticated, logout } = useHowoneContext()
+
+  if (!isAuthenticated) {
+    return <button onClick={() => navigate(howone.auth.loginPath)}>Sign in</button>
+  }
+
+  return <button onClick={() => void logout()}>Sign out</button>
+}
+```
+
+---
+
+## 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}`.
+
+---
+
+## Protected route pattern
+
+```tsx
+function ProtectedPage() {
+  const [user, setUser] = useState(null)
+  const navigate = useNavigate()
+
+  useEffect(() => {
+    howone.me()
+      .then(setUser)
+      .catch(() => navigate(howone.auth.loginPath, { replace: true }))
+  }, [navigate])
+
+  if (!user) return null
+  return <div>Welcome {user.name}</div>
+}
+```
+
+---
+
+## Common mistakes
+
+| 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 |
+
+---
+
+## Import map
+
+| Need | Import |
+|------|--------|
+| Provider, context | `@howone/sdk/react` |
+| Client, OTP, OAuth | `@howone/sdk` |
+| App singleton | `@/lib/sdk` default export |

package/templates/vite/.howone/skills/{howone-sdk → howone}/03-sdk/07-ai-action-calls.md

@@ -62,17 +62,23 @@ type AiActionConfig<TInput, TOutput> = {
 ```ts
 type AiResult = {
   success: boolean
-  finalResult: Record<string, unknown> | null  // the workflow output payload
+  /** Terminal outcome of the run */
+  outcome: 'success' | 'credit_insufficient' | 'run_error' | null
+  finalResult: Record<string, unknown> | null  // the workflow output payload (from run_complete)
+  /** Accumulated state data from state_update / state_snapshot events */
+  stateData: Record<string, unknown>
   nodeExecutions: Array<{
     nodeName: string
-    content: string
+    agentName?: string
     timestamp: number
   }>
-  costUpdates: Array<{
-    token: number
-    totalToken: number
-    cost: number
-    totalCost: number
+  toolExecutions: Array<{
+    toolCallId: string
+    toolName: string
+    args?: Record<string, unknown>
+    result?: unknown
+    durationMs?: number
+    cost?: number
     timestamp: number
   }>
   totalDuration: number
@@ -92,14 +98,43 @@ type AiSession = {
 
 ### AiEvent (SSE events)
 
+All events share a common base, then carry a typed `payload`:
+
 ```ts
 type AiEvent = {
-  type: string
-  data?: Record<string, unknown>
-  [key: string]: unknown
+  type: string          // see channel catalog below
+  id: string
+  run_id: string
+  workflow_id: string
+  timestamp: string     // ISO 8601 UTC
+  seq: number           // monotonic ordering within the run
+  // Context fields — present when applicable
+  node_name?: string
+  node_status?: 'pending' | 'running' | 'completed' | 'failed'
+  action_step?: number
+  agent_name?: string
+  action_name?: string
+  agent_loop_step?: number
+  message_id?: string
+  tool_call_id?: string
+  payload?: Record<string, unknown>
 }
 ```
 
+**SSE Channels and event types:**
+
+| Channel | Key event types |
+|---|---|
+| `lifecycle` | `run_start`, `run_complete`, `credit_insufficient`, `run_error` |
+| `node` | `node_scheduled`, `node_start`, `node_complete`, `node_failed` |
+| `action` | `action_scheduled`, `action_start`, `action_complete` |
+| `messages` | `ai_message_start`, `ai_message_chunk`, `ai_message_end`, `action_output` |
+| `tools` | `tool_call_start`, `tool_call_end`, `tool_call_error` |
+| `state` | `state_update`, `state_snapshot` |
+| `metadata` | `progress` |
+
+Stream terminates after exactly one of: `run_complete`, `credit_insufficient`, or `run_error`.
+
 ---
 
 ## Defining AI Actions
@@ -195,17 +230,17 @@ When an action omits `outputSchema`, `run()` returns the raw `AiResult` executio
 
 ```ts
 const result = await howone.ai.generateStory.run(input, {
-  onStreamChunk: (chunk) => {
-    console.log('chunk:', chunk)
+  onMessageChunk: (text) => {
+    console.log('chunk:', text)
   },
-  onNodeStart: (nodeName, content) => {
-    console.log(`Node ${nodeName} started`)
+  onNodeStart: (event) => {
+    console.log(`Node ${event.node_name} started`)
   },
-  onCostUpdate: (cost) => {
-    console.log(`Tokens used: ${cost.totalToken}`)
+  onStateUpdate: (delta) => {
+    console.log('State delta:', delta)
   },
-  onProgress: (progress) => {
-    setProgress(progress)
+  onProgress: (percent) => {
+    setProgress(percent)
   },
   onError: (error) => {
     console.error('SSE error:', error)
@@ -213,13 +248,32 @@ const result = await howone.ai.generateStory.run(input, {
 })
 ```
 
+UI feedback belongs in the frontend app. Do not import or expect SDK toast APIs. Use returned
+promises and callbacks to update app-owned state:
+
+```ts
+setStatus({ type: 'loading', message: 'Generating story...' })
+
+try {
+  const output = await howone.ai.generateStory.run(input, {
+    onProgress: (progress) => setProgress(progress),
+  })
+  setStatus({ type: 'success', message: 'Story ready', output })
+} catch (error) {
+  setStatus({
+    type: 'error',
+    message: error instanceof Error ? error.message : 'Story generation failed',
+  })
+}
+```
+
 ### stream() — start and control a session
 
 ```ts
 function startStream(input: GenerateStoryInput) {
   const session = howone.ai.generateStory.stream(input, {
-    onStreamChunk: (chunk) => {
-      setOutput(prev => prev + chunk)
+    onMessageChunk: (text) => {
+      setOutput(prev => prev + text)
     },
     onComplete: (result) => {
       console.log('Done:', result.finalResult)
@@ -248,17 +302,27 @@ const result = await session.result
 async function consumeEvents(input: GenerateStoryInput) {
   for await (const event of howone.ai.generateStory.events(input)) {
     switch (event.type) {
-      case 'stream_content':
-        setOutput(prev => prev + (event.data?.delta ?? ''))
+      case 'ai_message_chunk':
+        // streaming LLM text delta
+        setOutput(prev => prev + (event.payload?.content_block?.text ?? event.payload?.content ?? ''))
         break
       case 'node_start':
-        console.log('Node started:', event.data?.nodeName)
+        console.log('Node started:', event.node_name)
+        break
+      case 'tool_call_end':
+        console.log('Tool result:', event.tool_call_id, event.payload?.result)
+        break
+      case 'state_update':
+        console.log('State delta:', event.payload?.delta)
         break
-      case 'cost_update':
-        console.log('Cost:', event.data?.totalCost)
+      case 'run_complete':
+        console.log('Final result:', event.payload?.result)
         break
-      case 'complete':
-        console.log('Final result:', event.data)
+      case 'credit_insufficient':
+        showCreditError(event.payload?.details?.reason)
+        break
+      case 'run_error':
+        showExecutionError(event.payload?.details?.reason)
         break
     }
   }
@@ -333,37 +397,43 @@ export const analyzeDataInputSchema = z.object({
 
 ```ts
 type SSEExecutionOptions = {
-  // Called for every raw SSE event
-  onEvent?: (event: { type: string; data?: Record<string, unknown> }) => void
+  // Called for every parsed event with its SSE channel
+  onEvent?: (event: AiEvent, channel: string) => void
 
-  // Called when a workflow node starts executing
-  onNodeStart?: (nodeName: string, content: string) => void
+  // Lifecycle
+  onRunStart?: (event: RunStartEvent) => void
+  onRunComplete?: (event: RunCompleteEvent, result: AiResult) => void
+  /** Credits / quota exhausted — show top-up UI, NOT a generic error */
+  onCreditInsufficient?: (event: CreditInsufficientEvent) => void
+  /** Workflow logic failed — show retry/support UI */
+  onRunError?: (event: RunErrorEvent) => void
 
-  // Called with streaming text delta (for LLM text generation nodes)
-  onStreamContent?: (delta: string) => void
+  // Nodes
+  onNodeStart?: (event: NodeStartEvent) => void
+  onNodeComplete?: (event: NodeCompleteEvent) => void
 
-  // Called with each raw stream chunk
-  onStreamChunk?: (chunk: string) => void
+  // Messages — streaming LLM text
+  onMessageChunk?: (text: string, event: AiMessageChunkEvent) => void
+  onMessageEnd?: (event: AiMessageEndEvent) => void
 
-  // Called when token/cost counters update
-  onCostUpdate?: (cost: {
-    token: number
-    totalToken: number
-    cost: number
-    totalCost: number
-    timestamp: number
-  }) => void
+  // Tools
+  onToolCallStart?: (event: ToolCallStartEvent) => void
+  onToolCallEnd?: (event: ToolCallEndEvent) => void
+  onToolCallError?: (event: ToolCallErrorEvent) => void
 
-  // Called with an estimated progress value (0–100)
-  onProgress?: (progress: number) => void
+  // State — live output panel updates
+  onStateUpdate?: (delta: Record<string, unknown>, event: StateUpdateEvent) => void
 
-  // Called with log messages from workflow nodes
+  // Progress percent 0-100
+  onProgress?: (percent: number, message?: string) => void
+
+  // Internal transport log
   onLog?: (message: string) => void
 
-  // Called if an error occurs
+  // Called on any error (credit or execution)
   onError?: (error: Error) => void
 
-  // Called when the workflow completes with the raw execution envelope
+  // Called when the stream closes (success or error)
   onComplete?: (result: AiResult) => void
 
   // Abort signal — connect to an AbortController for cancellation
@@ -378,6 +448,9 @@ type SSEExecutionOptions = {
 }
 ```
 
+> `onCreditInsufficient` and `onRunError` are **mutually exclusive** terminal events.
+> Do not use a generic `onError` to distinguish them — use the dedicated callbacks.
+
 ---
 
 ## AiSchemaValidationError
@@ -403,28 +476,59 @@ try {
 
 ## AI Result Persistence
 
-When AI-generated content should be saved to an entity:
+When AI-generated content should be saved to an entity, prefer the SDK persistence helper for
+history-style products. It standardizes the pending-first pattern from `02-database/05-ai-persistence-patterns.md`
+without adding UI behavior.
 
 ```ts
-// 1. Run the AI action
-const output = await howone.ai.generateStory.run({
-  topic: 'Dragons and magic',
-  ageRange: '6-8',
-})
+import { runAiActionAndPersist } from '@howone/sdk'
 
-// 2. Save to entity
-const saved = await howone.entities.Story.create({
-  title: output.title,
-  content: output.content,
-  authorId: currentUser.id,
-  status: 'draft',
-  wordCount: output.content.split(' ').length,
-  // Track generation metadata
-  promptTopic: 'Dragons and magic',
-  generatedAt: new Date().toISOString(),
+const result = await runAiActionAndPersist({
+  entity: howone.entities.Generation,
+  input: {
+    prompt: 'Dragons and magic',
+    ageRange: '6-8',
+  },
+  createPending: (input) => ({
+    prompt: input.prompt,
+    ageRange: input.ageRange,
+    status: 'pending',
+    requestedAt: new Date().toISOString(),
+  }),
+  run: (input) => howone.ai.generateStory.run(input),
+  mapCompleted: ({ output }) => ({
+    status: 'completed',
+    title: output.title,
+    content: output.content,
+    completedAt: new Date().toISOString(),
+  }),
+  mapFailed: ({ error }) => ({
+    status: 'failed',
+    errorMessage: error instanceof Error ? error.message : 'Generation failed',
+  }),
+  onStateChange: (state) => {
+    // app-owned UI callback; SDK does not show toasts
+    setGenerationState(state.status)
+  },
 })
 ```
 
+Return shape:
+
+```ts
+type AiPersistenceResult<TRecord, TOutput> =
+  | { status: 'completed'; record: TRecord; output: TOutput }
+  | { status: 'failed'; record: TRecord; error: unknown }
+```
+
+Rules:
+
+- `createPending` must only return fields declared in the entity schema.
+- `mapCompleted` maps durable product fields from AI output to entity update payload.
+- `mapFailed` should persist a failure state if the product shows history or retry.
+- Use `onStateChange` to update app-owned UI; do not add SDK toast behavior.
+- For simple one-shot AI actions that do not need history, call `howone.ai.*.run()` directly.
+
 ---
 
 ## React Patterns