howone 0.1.10 → 0.1.12

package/templates/vite/.howone/skills/howone-sdk/references/usage-patterns.md

@@ -1,443 +0,0 @@
-# HowOne SDK Usage Patterns
-
-Working reference for `@howone/sdk` and `@howone/sdk/react`. It covers the SDK surface that generated HowOne apps normally need: client setup, entity bindings, AI action bindings, React provider usage, and the known traps that cause repeated source inspection.
-
-## Reading Strategy
-
-Use this file as the working SDK manual for normal app generation. It intentionally includes the public imports, client shape, entity methods, AI action bindings, React exports, app SDK entry shape, and known validation caveats.
-
-Do not inspect `node_modules/@howone/sdk` for the same information unless:
-
-- This file does not cover the exact API needed.
-- TypeScript or runtime verification contradicts this file.
-- You are intentionally updating the SDK package itself, not an app that consumes it.
-
-When source fallback is necessary, keep it narrow: inspect the exact exported symbol or declaration that is missing, then return to app code. Do not glob or read the whole SDK package to relearn the basic usage below.
-
-## SDK Mental Model
-
-- `createClient(...)` creates the base HowOne client with auth, entity, AI, upload, and user helpers.
-- `client.entity<TRecord, TCreate, TUpdate>('EntityName')` creates one typed entity client.
-- `defineEntities(...)` plus `withEntities(client, entities)` makes `howone.entities.<EntityName>` typed in app code.
-- `defineAiAction(...)` plus `defineAiActions(...)` plus `withAiActions(...)` makes `howone.ai.<actionName>.run|stream|events` typed in app code.
-- `@howone/sdk/react` provides auth/theme/loading UI primitives only. It does not provide entity, query, or AI data hooks.
-- `.howone/database/manifest.json` and `.howone/ai/manifest.json` are the generated contracts. App source should be generated from those manifests, not from memory.
-
-## Import Reference
-
-```ts
-// @howone/sdk — all public exports
-import {
-  createClient,
-  defineAiAction,
-  defineAiActions,
-  defineEntities,
-  withAiActions,
-  withEntities,
-  type CreateClientOptions,
-  type EntityRecord,
-  type EntityClient,
-  type EntityBindings,
-  type QueryOptions,
-  type QueryResult,
-  type PageInfo,
-  type DeleteResult,
-  type AiClient,
-  type AiActionDefinition,
-  type AiActionClient,
-  type AiActionConfig,
-  type AiResult,       // = ExecutionResult
-  type AiSession,      // { result: Promise<AiResult>, cancel(): void, signal: AbortSignal }
-  type AiEvent,        // SSE event payload
-  type AiOptions,
-  type UserProfile,
-  AiSchemaValidationError,
-} from '@howone/sdk'
-
-// @howone/sdk/react — React components and hooks
-import {
-  HowOneProvider,
-  useHowoneContext,
-  FloatingButton,
-  Loading,
-  LoadingSpinner,
-  type HowOneProviderProps,
-  type HowOneAuthMode,
-  type HowOneThemeMode,
-  type HowOneBrandMode,
-} from '@howone/sdk/react'
-
-import { z } from 'zod'
-```
-
----
-
-## createClient
-
-```ts
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,  // required in Vite apps
-  env: import.meta.env.VITE_HOWONE_ENV,               // 'local' | 'dev' | 'prod'
-  // Optional advanced options (rarely needed):
-  // apiUrl, aiUrl, caseStyle ('camel'|'snake'), auth: { mode, getToken }
-})
-
-// client shape:
-client.entity<TRecord, TCreate, TUpdate>(entityName: string): EntityClient<...>
-client.entities: Record<string, EntityClient>
-client.ai: AiClient  // low-level; prefer withAiActions bindings
-client.me(): Promise<UserProfile | null>
-client.requireMe(): Promise<UserProfile>
-client.auth.setToken(t: string | null): void
-client.auth.getToken(): string | null
-client.auth.isAuthenticated(): boolean
-client.auth.login(redirect?: string): void
-client.auth.logout(): void
-client.upload.file(file, options?): Promise<{ url, thumbnailUrl?, id?, size?, mimeType? }>
-client.upload.image(file): Promise<{ url }>
-client.upload.batch({ files, concurrent?, onProgress?, onFileComplete? }): Promise<BatchUploadResponse>
-```
-
----
-
-## EntityClient
-
-```ts
-type EntityClient<TRecord, TCreate, TUpdate> = {
-  name: string
-  // Basic CRUD
-  list(options?: { page?, limit?, sort?, order?, ...filters }): Promise<TRecord[]>
-  get(id: string): Promise<TRecord | null>
-  getOrThrow(id: string): Promise<TRecord>
-  create(data: TCreate): Promise<TRecord>
-  update(id: string, data: TUpdate): Promise<TRecord>
-  delete(id: string): Promise<{ deleted: boolean; id: string; message? }>
-  // Advanced query with filters/pagination
-  query(options?: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
-  query.mine(options?: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
-  bulkCreate(records: TCreate[], options?: { sample?: boolean }): Promise<TRecord[]>
-  aggregate(pipeline: unknown[]): Promise<unknown[]>
-}
-
-// QueryOptions
-type QueryOptions<TRecord> = {
-  where?: { [K in keyof TRecord]?: TRecord[K] | FieldOperator }
-  // FieldOperator: { eq, ne, gt, gte, lt, lte, contains, like, startsWith, endsWith, in, notIn }
-  search?: string
-  page?: { number?: number; size?: number }
-  orderBy?: Partial<Record<keyof TRecord | string, 'asc' | 'desc'>>
-}
-
-// QueryResult
-type QueryResult<T> = {
-  items: T[]
-  page: { number, size, total, totalPages, hasNext, hasPrev }
-}
-
-// EntityRecord base
-type EntityRecord = {
-  id: string
-  createdDate?: string
-  updatedDate?: string
-  createdById?: string
-  isSample?: boolean
-  [key: string]: unknown
-}
-```
-
----
-
-## AI Action
-
-```ts
-// Define a typed action
-defineAiAction(id: string, config?: {
-  inputSchema?: z.ZodType<TInput>
-  outputSchema?: z.ZodType<TOutput>
-  mode?: 'run' | 'stream' | 'events'
-}): AiActionDefinition<TInput, TOutput>
-
-// Group actions
-defineAiActions({ [name]: AiActionDefinition, ... }): actions
-
-// Bind to client
-withAiActions(client, actions): client & { ai: { [name]: AiActionClient } }
-
-// AiActionClient methods
-howone.ai.<actionName>.run(inputs?, options?): Promise<TOutput>
-howone.ai.<actionName>.stream(inputs?, options?): AiSession
-howone.ai.<actionName>.events(inputs?, options?): AsyncIterable<AiEvent>
-
-// AiSession
-type AiSession = {
-  result: Promise<AiResult>
-  cancel(): void
-  signal: AbortSignal
-}
-
-// Reserved names — do NOT use as action names: run, stream, events
-```
-
----
-
-## React: HowOneProvider & hooks
-
-`@howone/sdk/react` exports exactly: `HowOneProvider`, `useHowoneContext`, `FloatingButton`, `Loading`, `LoadingSpinner`.
-
-**There are no `useEntity`, `useQuery`, `useAi`, or other data-fetching hooks.** Entity and AI calls are plain async functions — call them directly in components with `useEffect`/`useState` or any data-fetching library (SWR, React Query, etc.).
-
-```tsx
-// Wrap app root — handles auth, theme, toasts, floating button
-<HowOneProvider
-  projectId={...}           // optional if client is already configured
-  auth="optional"           // 'required' | 'optional' | 'none'
-  brand="visible"           // 'visible' | 'hidden'
-  theme="inherit"           // 'dark' | 'light' | 'system' | 'inherit'
-  showBrandButton={true}
->
-  <App />
-</HowOneProvider>
-
-// Auth context hook — the only hook in the package
-const { user, token, isAuthenticated, logout } = useHowoneContext()
-// user shape: { id, email, name, avatar } | null
-
-// Loading components
-<Loading size="md" tone="brand" label="..." description="..." fullScreen />
-<LoadingSpinner size="sm" tone="neutral" />
-// size: 'sm' | 'md' | 'lg'    tone: 'brand' | 'neutral' | 'inverse'
-```
-
-## App SDK Entry
-
-Preferred Vite app entry shape:
-
-```ts
-import {
-  createClient,
-  defineAiAction,
-  defineAiActions,
-  defineEntities,
-  type EntityRecord,
-  withAiActions,
-  withEntities,
-} from '@howone/sdk'
-import { z } from 'zod'
-
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-})
-
-export const entities = defineEntities({
-  // Todo: client.entity<Todo, TodoCreate, TodoUpdate>('Todo'),
-})
-
-export const ai = defineAiActions({
-  // generateImage: defineAiAction('generateImage', {
-  //   inputSchema: generateImageInputSchema,
-  // }),
-})
-
-const howone = withAiActions(withEntities(client, entities), ai)
-
-export default howone
-```
-
-## Manifest-To-Code Recipe
-
-When backend metadata has been synced, generate app SDK code in this order:
-
-1. Read `src/lib/sdk.ts` to preserve the template's import style and existing bindings.
-2. Read `.howone/database/manifest.json` for entity names and fields. Generate `Record`, `Create`, and `Update` types, then bind each entity with `client.entity<Record, Create, Update>('EntityName')`.
-3. Read `.howone/ai/manifest.json` for AI capability names and JSON schemas. Generate zod input schemas and, only when safe, output schemas.
-4. Export a single default `howone` client built by composing `withEntities` and `withAiActions`.
-5. In UI code, import the default client and call `howone.entities.<Entity>.*` or `howone.ai.<action>.run(...)`.
-
-Basic JSON schema mapping for generated zod:
-
-```ts
-string -> z.string()
-number -> z.number()
-integer -> z.number().int()
-boolean -> z.boolean()
-array -> z.array(...)
-object -> z.object({ ... })
-enum -> z.enum([...])
-missing from required[] -> .optional()
-```
-
-## Entity Types
-
-Prefer explicit payload types:
-
-```ts
-export type StoryRecord = EntityRecord & {
-  title: string
-  content: string
-  prompt: string
-}
-
-export type StoryCreate = {
-  title: string
-  content: string
-  prompt: string
-}
-
-export type StoryUpdate = Partial<StoryCreate>
-
-export const entities = defineEntities({
-  Story: client.entity<StoryRecord, StoryCreate, StoryUpdate>('Story'),
-})
-```
-
-Generated entity app code usually needs only these calls:
-
-```ts
-const result = await howone.entities.Story.query({
-  search,
-  page: { number: 1, size: 20 },
-  orderBy: { createdDate: 'desc' },
-})
-
-await howone.entities.Story.create({ title, content, prompt })
-await howone.entities.Story.update(id, { title })
-await howone.entities.Story.delete(id)
-```
-
-Prefer `query()` for list UIs that need paging/search/sort metadata. Use `list()` only for simple array reads.
-
-Avoid this for generated create payloads:
-
-```ts
-type StoryCreate = Omit<StoryRecord, 'id' | 'createdDate' | 'updatedDate'>
-```
-
-`EntityRecord` has an index signature, so `Omit` can make generated create types looser than intended.
-
-## AI Action Types
-
-Generate zod schemas from `.howone/ai/manifest.json`:
-
-```ts
-export const generateStoryInputSchema = z.object({
-  topic: z.string().min(1),
-  ageRange: z.enum(['3-5', '6-8', '9-12']),
-})
-
-export const generateStoryOutputSchema = z.object({
-  title: z.string(),
-  content: z.string(),
-})
-
-export type GenerateStoryInput = z.infer<typeof generateStoryInputSchema>
-export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
-
-export const ai = defineAiActions({
-  generateStory: defineAiAction('generateStory', {
-    inputSchema: generateStoryInputSchema,
-    mode: 'run',
-  }),
-})
-```
-
-Call from app code:
-
-```ts
-const result = await howone.ai.generateStory.run({
-  topic,
-  ageRange,
-})
-const story = result.finalResult as GenerateStoryOutput
-```
-
-For streaming:
-
-```ts
-const session = howone.ai.generateStory.stream(input)
-session.cancel()
-```
-
-For event iteration:
-
-```ts
-for await (const event of howone.ai.generateStory.events(input)) {
-  console.log(event)
-}
-```
-
-## AI Output Validation
-
-`run()` validates input with `inputSchema`, calls the workflow, then validates the **raw `ExecutionResult`** (the full SSE envelope) with `outputSchema`. It does **not** automatically unwrap `result.finalResult`.
-
-If you want to type the final result only, omit `outputSchema` and unwrap manually:
-
-```ts
-const result = await howone.ai.generateStory.run(input) // returns AiResult
-const finalResult = result.finalResult as GenerateStoryOutput
-```
-
-Only define `outputSchema` when it matches the full `ExecutionResult` envelope or after verifying the SDK has changed to validate `finalResult` directly.
-
-## AI Result Persistence
-
-For AI-generated data that should be saved:
-
-1. Define AI input/output schemas from `.howone/ai/manifest.json`.
-2. Define entity fields from the AI output schema.
-3. Add only needed request metadata fields, such as prompt, selected options, language, status, or timestamps.
-4. Save with `howone.entities.<Entity>.create(...)`.
-
-Example:
-
-```ts
-const story = await howone.ai.generateStory.run(input)
-const finalResult = story.finalResult as GenerateStoryOutput
-
-await howone.entities.Story.create({
-  title: finalResult.title,
-  content: finalResult.content,
-  prompt: input.topic,
-})
-```
-
-## Do Not Generate
-
-Avoid these patterns unless the SDK has explicitly added them:
-
-```ts
-// No data hooks in @howone/sdk/react
-const todos = useEntity('Todo')
-const query = useQuery(...)
-const result = useAi(...)
-
-// Wrong AI binding shape
-await howone.ai.run.generateStory(input)
-
-// Too-loose create payload
-type StoryCreate = Omit<StoryRecord, 'id' | 'createdDate' | 'updatedDate'>
-
-// Generated files do not belong under .howone
-// .howone stores synced manifests only.
-```
-
-## When To Read SDK Source
-
-Read SDK source or declaration files only for details not covered above, for example:
-
-- A newly added public method not listed here.
-- A TypeScript error proving a signature drifted.
-- A runtime error that points to a specific SDK helper.
-- Work that intentionally modifies `packages/sdk` itself.
-
-For app generation, do not inspect SDK source to rediscover `createClient`, entity CRUD, AI action binding shape, React exports, or Vite env setup.
-
-## Generated Code Checklist
-
-- `src/lib/sdk.ts` imports only APIs it uses.
-- `createClient` uses `import.meta.env.VITE_HOWONE_PROJECT_ID` and `import.meta.env.VITE_HOWONE_ENV`.
-- Entity names match `.howone/database/manifest.json`.
-- AI action names and schemas match `.howone/ai/manifest.json`.
-- zod schemas are strict enough for generated UI inputs and backend contracts.
-- UI code calls `howone.ai.<action>.run(input)` and `howone.entities.<Entity>.*`.
-- No generated source file is written under `.howone`.