howone 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "private": false,
   "description": "HowOne command line tools for creating app templates.",
   "type": "module",

package/templates/vite/.howone/skills/howone-sdk/SKILL.md

@@ -1,30 +1,39 @@
 ---
 name: howone-sdk
-description: Build application code with @howone/sdk correctly. Use when implementing or reviewing HowOne app SDK wiring, src/lib/sdk.ts, dynamic entity bindings, AI action bindings, zod runtime schemas, Vite environment variables, calls like howone.entities.* and howone.ai.*.run, or code generated from .howone/database and .howone/ai manifests.
+description: Build application code with @howone/sdk correctly. Use when implementing or reviewing HowOne app SDK wiring, src/lib/sdk.ts, dynamic entity bindings, AI action bindings, zod runtime schemas, Vite environment variables, calls like howone.entities.* and howone.ai.*.run, file uploads, auth flows, raw HTTP calls, or code generated from .howone/database and .howone/ai manifests.
 ---
 
-# HowOne SDK
+# HowOne SDK Skill
 
-Use this skill when writing app code that consumes `@howone/sdk`. The goal is stable generated code: read backend-synced manifests, define runtime schemas, bind entities and AI actions in the app SDK entry, then call those bindings from UI code.
+This skill is the authoritative source of truth for all `@howone/sdk` usage in generated apps. Every capability is documented in a dedicated reference file — use those files to understand the API. Do not read `node_modules` to rediscover imports or signatures.
 
-This skill is the normal source of truth for HowOne SDK usage in generated apps. Do not inspect `node_modules/@howone/sdk` just to rediscover imports, hook names, entity methods, AI action call shapes, or Vite environment wiring. Use dependency source only for narrow missing details, signature drift proven by verification, or SDK-package development.
+## Module Reference Map
 
-## Workflow
+| Module | File | What It Covers |
+|---|---|---|
+| Client Setup | `references/01-client-setup.md` | `createClient`, env vars, `CreateClientOptions`, all client fields |
+| Entity Operations | `references/02-entity-operations.md` | CRUD, `query`, `list`, `aggregate`, `bulkCreate`, typed records |
+| AI Actions | `references/03-ai-actions.md` | `defineAiAction`, `run`/`stream`/`events`, zod schemas, SSE callbacks |
+| Auth | `references/04-auth.md` | Email OTP, Phone OTP, OAuth (Google/GitHub), token management |
+| File Upload | `references/05-file-upload.md` | `upload.file`, `upload.image`, `upload.batch`, progress, abort |
+| React Integration | `references/06-react-integration.md` | `HowOneProvider`, `useHowoneContext`, `FloatingButton`, `Loading` |
+| Raw HTTP | `references/07-raw-http.md` | `client.raw.*`, custom API calls, interceptors |
+| Manifest Codegen | `references/08-manifest-codegen.md` | Reading `.howone/database` and `.howone/ai`, generating `src/lib/sdk.ts` |
 
-1. Establish the app root. All `.howone/*` metadata and `src/lib/sdk.ts` work belongs inside that app root.
-2. Read `node_modules/@howone/sdk/dist/index.d.ts` and `node_modules/@howone/sdk/dist/react.d.ts` to get the complete, always-up-to-date type signatures and public exports.
-3. Read `references/usage-patterns.md` for generation recipes, usage examples, and known traps that aren't in the type declarations.
-4. Read the existing app SDK entry, usually `src/lib/sdk.ts`, before editing. Preserve its imports and local style.
-5. For Entity bindings, read `.howone/database/manifest.json`.
-6. For AI action bindings, read `.howone/ai/manifest.json`.
-7. Generate source code from the manifests, not from memory or tool-call summaries.
-8. Keep sync tools and app-code edits separate. `sync_schema_artifacts` and `sync_ai_artifacts` write metadata only; the coding agent edits `src/lib/sdk.ts`.
+## Workflow
 
-## Quick SDK Contract
+1. Identify which module(s) the task touches using the map above.
+2. Read the corresponding reference file(s) — they contain complete, runnable code examples.
+3. Read the existing `src/lib/sdk.ts` before editing. Preserve its import style and existing bindings.
+4. For Entity bindings, read `.howone/database/manifest.json`.
+5. For AI action bindings, read `.howone/ai/manifest.json`.
+6. Generate code from the manifests, not from memory.
+7. Keep sync tools (`sync_schema_artifacts`, `sync_ai_artifacts`) separate from app-code edits. Those tools write metadata only; the coding agent edits `src/lib/sdk.ts`.
 
-See `/sdk/dist/index.d.ts` and `/sdk/dist/react.d.ts` for the full type signatures. The minimal app wiring looks like:
+## Minimal App Wiring (Quick Reference)
 
 ```ts
+// src/lib/sdk.ts
 import {
   createClient,
   defineAiAction,
@@ -34,70 +43,51 @@ import {
   withAiActions,
   withEntities,
 } from '@howone/sdk'
-import { HowOneProvider, useHowoneContext } from '@howone/sdk/react'
 import { z } from 'zod'
 
+// Types
+export type TodoRecord = EntityRecord & {
+  title: string
+  completed: boolean
+}
+export type TodoCreate = { title: string; completed: boolean }
+export type TodoUpdate = Partial<TodoCreate>
+
+// Schemas
+export const summarizeTodoInputSchema = z.object({ title: z.string().min(1) })
+export type SummarizeTodoInput = z.infer<typeof summarizeTodoInputSchema>
+
+// Client
 const client = createClient({
   projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
   env: import.meta.env.VITE_HOWONE_ENV,
 })
 
+// Entities
 export const entities = defineEntities({
-  Todo: client.entity<Todo, TodoCreate, TodoUpdate>('Todo'),
+  Todo: client.entity<TodoRecord, TodoCreate, TodoUpdate>('Todo'),
 })
 
+// AI Actions
 export const ai = defineAiActions({
   summarizeTodo: defineAiAction('summarizeTodo', {
-    inputSchema: z.object({ title: z.string() }),
+    inputSchema: summarizeTodoInputSchema,
   }),
 })
 
+// Composed client
 const howone = withAiActions(withEntities(client, entities), ai)
 export default howone
 ```
 
-Entity calls are plain async SDK calls:
-
-```ts
-await howone.entities.Todo.list()
-await howone.entities.Todo.create({ title: 'Ship it', completed: false })
-await howone.entities.Todo.update(id, { completed: true })
-await howone.entities.Todo.delete(id)
-```
-
-AI action calls are bound by action name:
-
-```ts
-const result = await howone.ai.summarizeTodo.run({ title })
-const session = howone.ai.summarizeTodo.stream({ title })
-for await (const event of howone.ai.summarizeTodo.events({ title })) {
-  // handle event
-}
-```
-
-React integration provides provider/auth/loading UI only: `HowOneProvider`, `useHowoneContext`, `FloatingButton`, `Loading`, and `LoadingSpinner`. It does not provide entity/query/AI data hooks. Use `useEffect`/`useState` or a data-fetching library around plain async SDK calls.
-
-## Source Order
-
-Use this order when deciding what to read:
-
-1. `packages/sdk/dist/index.d.ts` and `packages/sdk/dist/react.d.ts` — complete public API.
-2. `references/usage-patterns.md` — generation recipes, examples, traps.
-3. Current app files: `src/lib/sdk.ts`, relevant UI files, and generated manifests.
-
-## Rules
-
-- Use `createClient({ projectId: import.meta.env.VITE_HOWONE_PROJECT_ID, env: import.meta.env.VITE_HOWONE_ENV })` in Vite apps. Do not add `?? 'prod'` or hardcoded project IDs in generated app code.
-- Use zod for AI input/output runtime schemas.
-- Use `defineAiAction` inside `defineAiActions`.
-- Current action binding shape is `howone.ai.<actionName>.run(input)`, `stream(input)`, and `events(input)`. Do not generate `howone.ai.run.<actionName>(input)` unless the SDK implementation has been changed to support that API.
-- Do not name AI actions `run`, `stream`, or `events`; those are reserved.
-- Define entity create/update types explicitly. Avoid deriving create types from `Omit<EntityRecord & ...>` when it widens the payload.
-- React integration does not provide entity/query/AI hooks. Use plain async SDK calls from React state/effects or an app-level data-fetching library.
-- Never make generated SDK/type files under `.howone`. `.howone` stores manifests only.
-- If an AI-first feature persists generated results, create/update AI capability schema first, sync `.howone/ai`, then derive Entity fields from the AI `outputSchema`.
-
-## References
-
-Read `packages/sdk/dist/index.d.ts` and `packages/sdk/dist/react.d.ts` for the full SDK type surface.
-Read `references/usage-patterns.md` for generation recipes, usage examples, and known traps.
+## Hard Rules
+
+- **Vite env only**: use `import.meta.env.VITE_HOWONE_PROJECT_ID` and `import.meta.env.VITE_HOWONE_ENV`. Never hardcode project IDs or add `?? 'prod'` fallbacks.
+- **Explicit types**: define `EntityRecord`, `Create`, and `Update` types explicitly. Never derive create types from `Omit<EntityRecord & ...>` — it widens the payload.
+- **AI action naming**: do not name actions `run`, `stream`, or `events` — those are reserved method names.
+- **Call shape**: `howone.ai.<actionName>.run(input)` / `.stream(input)` / `.events(input)`. Never `howone.ai.run.<actionName>(input)`.
+- **No hooks**: `@howone/sdk/react` provides auth/theme/loading UI only — no entity, query, or AI data hooks.
+- **No codegen under `.howone`**: `.howone/` stores manifests only. Never write generated source files there.
+- **AI-first persistence**: define AI output schema first, sync `.howone/ai`, then derive Entity fields from `outputSchema`.
+- **zod for schemas**: always use zod for AI `inputSchema` / `outputSchema`.
+- **`outputSchema` caution**: `run()` validates the full `ExecutionResult` envelope, not just `finalResult`.

package/templates/vite/.howone/skills/howone-sdk/references/01-client-setup.md

@@ -0,0 +1,278 @@
+# Client Setup
+
+## createClient
+
+`createClient(opts: CreateClientOptions)` is the single factory for everything in the HowOne SDK. Call it once at module level and export the result (or the composed `howone` client).
+
+### CreateClientOptions — full type
+
+```ts
+type Environment = 'local' | 'dev' | 'prod'
+
+type CreateClientOptions = {
+  // ── Required ──────────────────────────────────────────────
+  projectId?: string           // Your HowOne project ID (set via VITE_HOWONE_PROJECT_ID)
+
+  // ── Environment ───────────────────────────────────────────
+  env?: Environment | string   // 'local' | 'dev' | 'prod'  (set via VITE_HOWONE_ENV)
+  apiUrl?: string              // Override the REST API base URL
+  aiUrl?: string               // Override the AI/SSE base URL
+
+  // ── Behaviour ─────────────────────────────────────────────
+  caseStyle?: 'camel' | 'snake' // Default: 'camel'
+  mode?: 'auto' | 'standalone' | 'embedded'
+
+  // ── Auth ──────────────────────────────────────────────────
+  auth?: {
+    mode?: 'none' | 'managed' | 'headless'
+    getToken?: () => Promise<string | null>   // Custom token provider (headless)
+    tokenCacheMs?: number                     // How long to cache the token
+    tokenInjection?: {
+      allowedOrigins?: string[]
+      waitMs?: number
+      clearUrlParamsAfterInjectionMs?: number
+      clearAllUrlParams?: boolean
+      sensitiveParams?: string[]
+    }
+  }
+
+  // ── Limit-exceeded callbacks ───────────────────────────────
+  limitExceeded?: {
+    onLimitExceeded?: (context: LimitExceededContext) => void
+    showUpgradeToast?: boolean
+    upgradeUrl?: string
+  }
+
+  // ── Deprecated — do not use in new code ───────────────────
+  appId?: string        // Use projectId
+  baseUrl?: string      // Use apiUrl / aiUrl
+  apiBaseUrl?: string   // Use apiUrl
+  aiBaseUrl?: string    // Use aiUrl
+  authRequired?: boolean // Use auth.mode
+}
+```
+
+### What createClient returns
+
+```ts
+const client = createClient({ ... })
+
+client.projectId        // string — resolved project ID
+client.appId            // string — alias for projectId
+client.caseStyle        // 'camel' | 'snake'
+
+// Entity factory
+client.entity<TRecord, TCreate, TUpdate>(entityName: string): EntityClient
+
+// Typed entity map (populated via withEntities)
+client.entities: Record<string, EntityClient>
+
+// AI action runner (low-level)
+client.ai: AiClient
+
+// HTTP utilities (low-level — see 07-raw-http.md)
+client.raw: RawHttpClient
+
+// File upload
+client.upload.file(file, options?)
+client.upload.image(file)
+client.upload.batch(options)
+
+// User profile
+client.me(options?)        // Promise<UserProfile | null>
+client.requireMe(options?) // Promise<UserProfile>  throws if unauthenticated
+client.session.user()      // alias for client.me()
+
+// Auth helpers
+client.auth.setToken(token: string | null)
+client.auth.getToken(): string | null
+client.auth.isAuthenticated(): boolean
+client.auth.login(redirect?: string)   // redirects to HowOne login page
+client.auth.logout()
+
+// URL utilities
+client.sanitizeUrl(opts?: { clearAll?: boolean; sensitiveParams?: string[] })
+```
+
+---
+
+## Standard Vite Setup
+
+```ts
+// src/lib/sdk.ts
+import {
+  createClient,
+  defineAiAction,
+  defineAiActions,
+  defineEntities,
+  type EntityRecord,
+  withAiActions,
+  withEntities,
+} from '@howone/sdk'
+import { z } from 'zod'
+
+// ── 1. Create client ─────────────────────────────────────────
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+})
+
+// ── 2. Define entity types & bind ────────────────────────────
+// (see 02-entity-operations.md for full details)
+export type NoteRecord = EntityRecord & { title: string; body: string }
+export type NoteCreate = { title: string; body: string }
+export type NoteUpdate = Partial<NoteCreate>
+
+export const entities = defineEntities({
+  Note: client.entity<NoteRecord, NoteCreate, NoteUpdate>('Note'),
+})
+
+// ── 3. Define AI actions ─────────────────────────────────────
+// (see 03-ai-actions.md for full details)
+export const summarizeInputSchema = z.object({ noteId: z.string() })
+export type SummarizeInput = z.infer<typeof summarizeInputSchema>
+
+export const ai = defineAiActions({
+  summarizeNote: defineAiAction('summarizeNote', {
+    inputSchema: summarizeInputSchema,
+  }),
+})
+
+// ── 4. Compose and export ────────────────────────────────────
+const howone = withAiActions(withEntities(client, entities), ai)
+export default howone
+```
+
+---
+
+## Environment Variables
+
+In Vite apps, these two env vars are mandatory:
+
+```
+VITE_HOWONE_PROJECT_ID=proj_xxxxxxxxxxxxxxxx
+VITE_HOWONE_ENV=prod
+```
+
+Rules:
+- **Do not** add `?? 'prod'` or `?? ''` fallbacks. Missing env vars should surface as misconfiguration errors.
+- **Do not** hardcode project IDs in source. Use the env var.
+- `env` accepts `'local'`, `'dev'`, or `'prod'`. SDK routes API calls to the correct endpoint automatically.
+
+---
+
+## Auth Modes
+
+```ts
+// Managed (default) — SDK handles login redirect and token storage
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  auth: { mode: 'managed' },
+})
+
+// Headless — provide your own token (e.g. Supabase, Clerk, etc.)
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  auth: {
+    mode: 'headless',
+    getToken: async () => {
+      // return your JWT or null
+      return localStorage.getItem('my_token')
+    },
+    tokenCacheMs: 60_000, // cache for 1 minute
+  },
+})
+
+// None — no auth, all requests are unauthenticated
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  auth: { mode: 'none' },
+})
+```
+
+---
+
+## Multi-environment Setup
+
+```ts
+// src/lib/sdk.ts
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  // Override URLs only for special deployments
+  // apiUrl: import.meta.env.VITE_HOWONE_API_URL,
+  // aiUrl: import.meta.env.VITE_HOWONE_AI_URL,
+})
+```
+
+---
+
+## UserProfile Type
+
+```ts
+type UserProfile = {
+  id: string
+  email?: string
+  name?: string
+  avatarUrl?: string
+  roles?: string[]
+  metadata?: Record<string, unknown>
+}
+
+// Usage
+const me = await client.me()           // null if not logged in
+const me = await client.requireMe()    // throws HowOneAuthError if not logged in
+
+// Check auth state programmatically
+const isLoggedIn = client.auth.isAuthenticated()
+const token = client.auth.getToken()
+
+// Manually set a token (e.g. after custom login flow)
+client.auth.setToken(jwtToken)
+
+// Trigger login redirect
+client.auth.login('/dashboard') // optional return path
+
+// Logout
+client.auth.logout()
+```
+
+---
+
+## HowOneAuthError
+
+```ts
+import { HowOneAuthError } from '@howone/sdk'
+
+try {
+  const user = await client.requireMe()
+} catch (err) {
+  if (err instanceof HowOneAuthError) {
+    // err.code === 'UNAUTHENTICATED'
+    client.auth.login()
+  }
+}
+```
+
+---
+
+## LimitExceeded Handling
+
+```ts
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  limitExceeded: {
+    showUpgradeToast: true,
+    upgradeUrl: 'https://howone.app/upgrade',
+    onLimitExceeded: (context) => {
+      console.error('Limit exceeded:', context.source, context.message)
+      // context.source: 'axios-response' | 'workflow-executor-sse' | ...
+      // context.status: HTTP status code (if available)
+    },
+  },
+})
+```