howone 0.1.11 → 0.1.12

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

@@ -1,215 +0,0 @@
-# HowOne SDK Usage Patterns
-
-This file covers what the type declarations don't: generation recipes, usage examples, and known traps. For the complete public API (all types, method signatures, exports), read `node_modules/@howone/sdk/dist/index.d.ts` and `node_modules/@howone/sdk/dist/react.d.ts` first.
-
-## 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.
-
-## 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,
-})
-```
-
-## 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`.