howone 0.1.11 → 0.1.12

package/templates/vite/.howone/skills/howone-sdk/references/05-file-upload.md

@@ -0,0 +1,319 @@
+# File Upload
+
+## Overview
+
+`client.upload` provides three methods for uploading files to the HowOne storage backend:
+- `upload.file(file, options?)` — general-purpose single file upload with progress and abort support
+- `upload.image(file)` — convenience wrapper for image uploads
+- `upload.batch(options)` — upload multiple files with concurrency control
+
+All upload methods are accessed from the `client` (or `howone`) object directly — they are **not** part of entities or AI.
+
+---
+
+## Types
+
+```ts
+// ── Input ─────────────────────────────────────────────────────
+type UploadableFile = File | Blob | string  // string = URL or base64
+
+// ── Options ───────────────────────────────────────────────────
+type UploadOptions = {
+  onProgress?: (percent: number) => void  // 0–100
+  signal?: AbortSignal                    // for cancellation
+  metadata?: Record<string, any>          // custom metadata to attach
+}
+
+// ── Single upload result ──────────────────────────────────────
+type UploadResponse = {
+  url: string           // CDN URL of the uploaded file
+  thumbnailUrl?: string // thumbnail URL (for images/videos)
+  id?: string           // storage file ID
+  size?: number         // file size in bytes
+  mimeType?: string     // detected MIME type
+}
+
+// ── Batch upload options ──────────────────────────────────────
+type BatchUploadOptions = {
+  files: (File | Blob)[]
+  concurrent?: number                                           // default: 3
+  onProgress?: (completed: number, total: number) => void
+  onFileComplete?: (result: UploadResponse | Error, index: number) => void
+  signal?: AbortSignal
+}
+
+// ── Batch upload result ───────────────────────────────────────
+type BatchUploadResponse = {
+  success: UploadResponse[]
+  failed: Array<{ index: number; error: string }>
+  total: number
+}
+```
+
+---
+
+## upload.file — Single File Upload
+
+```ts
+import howone from '@/lib/sdk'
+
+// Basic upload
+const result = await howone.upload.file(file)
+console.log(result.url)        // 'https://cdn.howone.app/...'
+console.log(result.size)       // 12345 (bytes)
+console.log(result.mimeType)   // 'image/jpeg'
+
+// With progress callback
+const result = await howone.upload.file(file, {
+  onProgress: (percent) => {
+    console.log(`Upload progress: ${percent}%`)
+    setProgress(percent)
+  },
+})
+
+// With cancellation
+const controller = new AbortController()
+const promise = howone.upload.file(file, {
+  signal: controller.signal,
+  onProgress: setProgress,
+})
+
+// Cancel after 5 seconds
+setTimeout(() => controller.abort(), 5000)
+
+const result = await promise
+
+// With metadata
+const result = await howone.upload.file(file, {
+  metadata: {
+    entityId: story.id,
+    uploadedBy: user.id,
+    category: 'cover',
+  },
+})
+```
+
+---
+
+## upload.image — Image Shorthand
+
+```ts
+import howone from '@/lib/sdk'
+
+// Accepts File, Blob, or a URL/base64 string
+const { url } = await howone.upload.image(imageFile)
+console.log(url)  // 'https://cdn.howone.app/images/...'
+
+// Use the URL directly in an img tag or save to an entity
+await howone.entities.Story.update(storyId, { coverUrl: url })
+```
+
+---
+
+## upload.batch — Multiple Files
+
+```ts
+import howone from '@/lib/sdk'
+
+const files: File[] = Array.from(fileInput.files ?? [])
+
+const result = await howone.upload.batch({
+  files,
+  concurrent: 3,        // upload 3 at a time
+
+  onProgress: (completed, total) => {
+    console.log(`${completed} / ${total} files uploaded`)
+    setProgress(Math.round((completed / total) * 100))
+  },
+
+  onFileComplete: (result, index) => {
+    if (result instanceof Error) {
+      console.error(`File ${index} failed:`, result.message)
+    } else {
+      console.log(`File ${index} URL:`, result.url)
+    }
+  },
+})
+
+console.log('Uploaded:', result.success.length)
+console.log('Failed:', result.failed.length)
+
+// Collect all URLs
+const urls = result.success.map(r => r.url)
+
+// With cancellation
+const controller = new AbortController()
+const resultPromise = howone.upload.batch({
+  files,
+  signal: controller.signal,
+  onProgress: (c, t) => console.log(c, '/', t),
+})
+// controller.abort() to cancel
+```
+
+---
+
+## React Patterns
+
+### Single image upload component
+
+```tsx
+import { useRef, useState } from 'react'
+import howone from '@/lib/sdk'
+
+export function ImageUploader({
+  onUpload,
+}: {
+  onUpload: (url: string) => void
+}) {
+  const [uploading, setUploading] = useState(false)
+  const [progress, setProgress] = useState(0)
+  const [error, setError] = useState<string | null>(null)
+  const abortRef = useRef<AbortController | null>(null)
+
+  async function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0]
+    if (!file) return
+
+    setUploading(true)
+    setProgress(0)
+    setError(null)
+    abortRef.current = new AbortController()
+
+    try {
+      const result = await howone.upload.file(file, {
+        signal: abortRef.current.signal,
+        onProgress: setProgress,
+      })
+      onUpload(result.url)
+    } catch (err) {
+      if ((err as Error).name !== 'AbortError') {
+        setError(err instanceof Error ? err.message : 'Upload failed')
+      }
+    } finally {
+      setUploading(false)
+      abortRef.current = null
+    }
+  }
+
+  function handleCancel() {
+    abortRef.current?.abort()
+  }
+
+  return (
+    <div>
+      <input
+        type="file"
+        accept="image/*"
+        onChange={handleChange}
+        disabled={uploading}
+      />
+      {uploading && (
+        <div>
+          <progress value={progress} max={100} />
+          <span>{progress}%</span>
+          <button onClick={handleCancel}>Cancel</button>
+        </div>
+      )}
+      {error && <p className="error">{error}</p>}
+    </div>
+  )
+}
+```
+
+### Multi-file upload with gallery preview
+
+```tsx
+import { useState } from 'react'
+import howone from '@/lib/sdk'
+
+export function MultiFileUploader() {
+  const [files, setFiles] = useState<File[]>([])
+  const [uploading, setUploading] = useState(false)
+  const [progress, setProgress] = useState({ completed: 0, total: 0 })
+  const [uploadedUrls, setUploadedUrls] = useState<string[]>([])
+  const [failedCount, setFailedCount] = useState(0)
+
+  function handleSelect(e: React.ChangeEvent<HTMLInputElement>) {
+    setFiles(Array.from(e.target.files ?? []))
+    setUploadedUrls([])
+    setFailedCount(0)
+  }
+
+  async function handleUpload() {
+    if (!files.length) return
+    setUploading(true)
+    setProgress({ completed: 0, total: files.length })
+
+    const result = await howone.upload.batch({
+      files,
+      concurrent: 3,
+      onProgress: (completed, total) => setProgress({ completed, total }),
+    })
+
+    setUploadedUrls(result.success.map(r => r.url))
+    setFailedCount(result.failed.length)
+    setUploading(false)
+  }
+
+  return (
+    <div>
+      <input type="file" multiple onChange={handleSelect} disabled={uploading} />
+      <button onClick={handleUpload} disabled={uploading || !files.length}>
+        {uploading
+          ? `Uploading ${progress.completed}/${progress.total}...`
+          : `Upload ${files.length} files`}
+      </button>
+      {failedCount > 0 && <p>{failedCount} files failed to upload</p>}
+      <div className="gallery">
+        {uploadedUrls.map((url, i) => (
+          <img key={i} src={url} alt={`Upload ${i}`} />
+        ))}
+      </div>
+    </div>
+  )
+}
+```
+
+### Upload and save to entity
+
+```tsx
+import howone, { type StoryUpdate } from '@/lib/sdk'
+
+async function uploadCoverAndUpdate(storyId: string, coverFile: File) {
+  // 1. Upload image
+  const { url } = await howone.upload.image(coverFile)
+
+  // 2. Update entity with the uploaded URL
+  const updated = await howone.entities.Story.update(storyId, {
+    coverUrl: url,
+  })
+
+  return updated
+}
+```
+
+### Upload from AI output (AI-generated image URL → storage)
+
+```tsx
+import howone from '@/lib/sdk'
+
+async function saveGeneratedImage(aiImageUrl: string, storyId: string) {
+  // Upload by URL (download + re-upload to HowOne storage)
+  const { url } = await howone.upload.image(aiImageUrl)
+
+  await howone.entities.Story.update(storyId, { coverUrl: url })
+  return url
+}
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Correct Pattern |
+|---|---|
+| Assuming `upload.image` returns the same shape as `upload.file` | `upload.image` returns `{ url: string }` only; `upload.file` returns full `UploadResponse` |
+| Not handling partial batch failures | Always check `result.failed.length` and `result.success` separately |
+| Leaking upload after component unmount | Store `AbortController` in a ref and abort on cleanup |
+| Saving a raw blob URL (`blob://...`) to an entity | Always await the upload first, then save the returned CDN `url` |

package/templates/vite/.howone/skills/howone-sdk/references/06-react-integration.md

@@ -0,0 +1,394 @@
+# React Integration
+
+## 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.
+
+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
+
+Wrap your entire app. Provides auth, theme, and toast context to all children.
+
+```tsx
+// main.tsx or app/layout.tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { HowOneProvider } from '@howone/sdk/react'
+import App from './App'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <HowOneProvider
+      projectId={import.meta.env.VITE_HOWONE_PROJECT_ID}
+      auth="optional"
+      brand="visible"
+      theme="system"
+    >
+      <App />
+    </HowOneProvider>
+  </React.StrictMode>
+)
+```
+
+### HowOneProviderProps
+
+```ts
+type HowOneAuthMode = 'required' | 'optional' | 'none'
+type HowOneThemeMode = 'dark' | 'light' | 'system' | 'inherit'
+type HowOneBrandMode = 'visible' | 'hidden'
+
+interface HowOneProviderProps {
+  children: React.ReactNode
+
+  // Project configuration (optional if createClient already set it)
+  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
+}
+```
+
+### Common provider configurations
+
+```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>
+
+// Dark mode forced
+<HowOneProvider auth="optional" theme="dark" forceTheme>
+  <App />
+</HowOneProvider>
+```
+
+---
+
+## useHowoneContext
+
+Access auth state inside any component wrapped by `HowOneProvider`.
+
+```ts
+type HowoneContextValue = {
+  user: {
+    id: string
+    email: string
+    name: string
+    avatar: string
+  } | null
+  token: string | null
+  isAuthenticated: boolean
+  logout: () => void
+}
+```
+
+### Usage
+
+```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>
+  )
+}
+```
+
+### Conditional rendering based on auth state
+
+```tsx
+function Dashboard() {
+  const { isAuthenticated, user } = useHowoneContext()
+
+  if (!isAuthenticated) {
+    return <div>Please log in to continue.</div>
+  }
+
+  return <div>Welcome, {user?.name}!</div>
+}
+```
+
+### Using token for direct API calls
+
+```tsx
+import { useHowoneContext } from '@howone/sdk/react'
+
+function DebugPanel() {
+  const { token } = useHowoneContext()
+
+  async function copyToken() {
+    if (token) await navigator.clipboard.writeText(token)
+  }
+
+  return (
+    <button onClick={copyToken} disabled={!token}>
+      Copy JWT Token
+    </button>
+  )
+}
+```
+
+---
+
+## FloatingButton
+
+A floating action button that renders in the bottom corner of the screen. When unauthenticated, it shows a "Login" label by default.
+
+```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
+
+```ts
+interface FloatingButtonProps {
+  text?: string       // button label (default: 'Login' or brand text)
+  onClick?: () => void
+  className?: string  // additional CSS classes
+}
+```
+
+---
+
+## Loading Components
+
+### Loading — full-page or inline loading state
+
+```tsx
+import { Loading } from '@howone/sdk/react'
+
+// Full-screen overlay
+<Loading fullScreen label="Loading your workspace..." />
+
+// Inline with description
+<Loading
+  label="Generating story..."
+  description="This may take a moment"
+  size="lg"
+  tone="brand"
+/>
+
+// Minimal
+<Loading />
+```
+
+### LoadingSpinner — headless spinner
+
+```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" />
+```
+
+### LoadingProps
+
+```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
+}
+
+interface LoadingSpinnerProps {
+  size?: LoadingSize
+  tone?: LoadingTone
+  className?: string
+}
+```
+
+---
+
+## Entity and AI Data in React
+
+`@howone/sdk/react` provides **no data hooks**. Use `useEffect`/`useState` or TanStack Query around the plain async SDK calls.
+
+### Pattern: auth-gated data fetch
+
+```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)
+
+  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
+
+```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 App from './App'
+
+const queryClient = new QueryClient()
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <HowOneProvider
+      projectId={import.meta.env.VITE_HOWONE_PROJECT_ID}
+      auth="optional"
+      theme="system"
+      brand="visible"
+    >
+      <QueryClientProvider client={queryClient}>
+        <App />
+      </QueryClientProvider>
+    </HowOneProvider>
+  </React.StrictMode>
+)
+```
+
+### 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)
+    }
+  }
+
+  return (
+    <div>
+      <button onClick={handleGenerate} disabled={loading}>
+        {loading ? 'Generating...' : isAuthenticated ? 'Generate' : 'Login to Generate'}
+      </button>
+      {result && <p>{result}</p>}
+    </div>
+  )
+}
+```
+
+---
+
+## Common Mistakes
+
+| 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` |