howone 0.1.23 → 0.1.26

package/templates/vite/.howone/skills/{howone-sdk → howone}/03-sdk/01-client-setup.md

@@ -22,19 +22,18 @@ type CreateClientOptions = {
   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[]
-    }
+  // ── Auth (one parameter for custom login) ─────────────────
+  auth?: 'custom' | 'hosted' | 'headless' | 'none' | {
+    mode?: 'custom' | 'hosted' | 'headless' | 'none' | 'managed'
+    loginPath?: string   // default '/login' when mode is 'custom'
+    logoutPath?: string
+    guard?: 'required' | 'optional' | 'none'
+    getToken?: () => Promise<string | null>
+    adapter?: AuthAdapter
+    tokenCacheMs?: number
   }
+  loginPath?: string     // shorthand when auth is 'custom'
+  logoutPath?: string
 
   // ── Limit-exceeded callbacks ───────────────────────────────
   limitExceeded?: {
@@ -99,12 +98,16 @@ client.me(options?)        // Promise<UserProfile | null>
 client.requireMe(options?) // Promise<UserProfile>  throws if unauthenticated
 client.session.user()      // alias for client.me()
 
-// Auth helpers
+// Auth helpers (behavior driven by createClient auth mode)
+client.auth.mode          // 'custom' | 'hosted' | 'headless' | 'none'
+client.auth.loginPath     // e.g. '/login'
 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()
+client.auth.login(returnUrl?: string)
+await client.auth.logout()
+await client.auth.clearSession({ redirect?: false | string })
+client.auth.subscribe((state) => { ... }) // auth state callback
 
 // URL utilities
 client.sanitizeUrl(opts?: { clearAll?: boolean; sensitiveParams?: string[] })
@@ -121,6 +124,8 @@ import {
   defineAiAction,
   defineAiActions,
   defineEntities,
+  pickEntityPayload,
+  runAiActionAndPersist,
   type EntityRecord,
   withAiActions,
   withEntities,
@@ -159,6 +164,17 @@ const howone = withAiActions(withEntities(client, entities), ai)
 export default howone
 ```
 
+SDK utility exports that generated apps may use:
+
+| Utility | Use |
+|---|---|
+| `pickEntityPayload(definition, payload)` | Keep only schema-declared business fields before create/update. |
+| `validateEntityPayload(definition, payload)` | Return structured issues for unknown/system/ownership/missing required fields. |
+| `assertEntityPayload(definition, payload)` | Throw structured `EntityPayloadValidationError` before unsafe writes. |
+| `validatePublicEntityQuery(definition, options)` | Check public filters, sorts, scopes, and limits against `access.public`. |
+| `assertPublicEntityQuery(definition, options)` | Throw before generating an invalid public query. |
+| `runAiActionAndPersist(options)` | Standard pending-first AI execution + entity persistence helper. |
+
 ---
 
 ## Environment Variables
@@ -173,40 +189,46 @@ 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.
+- `env` accepts `'local'`, `'dev'`, or `'prod'`. **Auth OTP/OAuth, entities, AI, and uploads all use this same env.**
+- Import `src/lib/sdk.ts` before calling `loginWithEmailCode` / `unifiedAuth` so env is pinned (otherwise auth defaults to prod APIs).
+
+| `env` | API base | Auth API example |
+|-------|----------|------------------|
+| `local` | `http://localhost:3002/api` | `http://localhost:3002/api/auth/email/send-code` |
+| `dev` | `https://api.howone.dev/api` | `https://api.howone.dev/api/auth/email/send-code` |
+| `prod` | `https://api.howone.ai/api` | `https://api.howone.ai/api/auth/email/send-code` |
 
 ---
 
 ## Auth Modes
 
+See `03-sdk/03-auth.md` for the full custom-login playbook.
+
 ```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' },
-})
+// Default — HowOne hosted login (howone.dev / howone.ai)
+createClient({ projectId, env })
 
-// 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,
+// Custom in-app login page; auth APIs still HowOne
+createClient({ projectId, env, auth: 'custom', loginPath: '/login' })
+
+// Headless — external JWT provider
+createClient({
+  projectId,
+  env,
   auth: {
     mode: 'headless',
-    getToken: async () => {
-      // return your JWT or null
-      return localStorage.getItem('my_token')
+    adapter: {
+      getToken: async () => externalAuth.getToken(),
+      setToken: (token) => externalAuth.setToken(token),
+      login: ({ returnUrl } = {}) => router.push(`/login?redirect=${encodeURIComponent(returnUrl ?? '/')}`),
+      logout: () => router.push('/'),
     },
-    tokenCacheMs: 60_000, // cache for 1 minute
+    tokenCacheMs: 60_000,
   },
 })
 
-// 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' },
-})
+// None — public app, no auth
+createClient({ projectId, env, auth: 'none' })
 ```
 
 ---

package/templates/vite/.howone/skills/{howone-sdk → howone}/03-sdk/02-entity-operations.md

@@ -260,7 +260,9 @@ const result = await howone.public.entities.Story.query({
 ```ts
 type FieldOperator<T> = {
   eq?: T           // exact match (same as plain value)
+  equals?: T       // alias for eq
   ne?: T           // not equal
+  not?: T          // not equal alias
   gt?: T           // greater than
   gte?: T          // greater than or equal
   lt?: T           // less than
@@ -268,9 +270,14 @@ type FieldOperator<T> = {
   contains?: string // substring (string fields)
   like?: string     // SQL LIKE pattern
   startsWith?: string
+  starts?: string
   endsWith?: string
+  ends?: string
   in?: T[]          // value in array
   notIn?: T[]       // value not in array
+  null?: boolean    // null / not null
+  empty?: boolean   // empty / not empty
+  exists?: boolean  // field exists / missing
 }
 
 // Examples
@@ -346,6 +353,26 @@ Public query fields must be present in `access.public.allowedFilters`, and publi
 fields must be present in `access.public.allowedSorts`. If a public query is rejected,
 fix the schema access contract instead of falling back to authenticated APIs.
 
+When generated code has the synced entity definition available, validate public queries before
+calling the API:
+
+```ts
+import { assertPublicEntityQuery } from '@howone/sdk'
+import { articleEntityDefinition } from '@/lib/sdk'
+
+const query = {
+  where: { status: 'published' },
+  orderBy: { publishedAt: 'desc' },
+  page: { number: 1, size: 20 },
+}
+
+assertPublicEntityQuery(articleEntityDefinition, query)
+const result = await howone.public.entities.Article.query(query)
+```
+
+Use `validatePublicEntityQuery()` when the app wants to show its own validation UI instead of
+throwing.
+
 ---
 
 ## Public Writes
@@ -365,6 +392,44 @@ await howone.public.entities.ContactMessage.create({
 
 ---
 
+## Payload Contract Utilities
+
+Use these helpers when code maps form state, AI output, or mixed UI state into entity writes.
+They prevent the common mistake of sending UI-only, workflow-envelope, ownership, or system fields.
+
+```ts
+import { pickEntityPayload, assertEntityPayload } from '@howone/sdk'
+import { generationEntityDefinition } from '@/lib/sdk'
+
+const draft = {
+  prompt,
+  status: 'pending',
+  created_by_id: user.id,       // stripped/rejected
+  gradientDirection: 'to right', // stripped/rejected unless schema declares it
+}
+
+const payload = pickEntityPayload(generationEntityDefinition, draft)
+assertEntityPayload(generationEntityDefinition, payload)
+
+await howone.entities.Generation.create(payload)
+```
+
+Rules:
+
+- Use `pickEntityPayload()` when transforming broad UI objects into narrow create/update payloads.
+- Use `validateEntityPayload()` to collect issues for app-owned validation UI.
+- Use `assertEntityPayload()` before writes in generated helper functions.
+- For updates, pass `{ partial: true }` to avoid requiring create-time fields.
+- These helpers do not replace backend validation; they make generated frontend code fail earlier
+  with clearer errors.
+
+```ts
+assertEntityPayload(generationEntityDefinition, update, { partial: true })
+await howone.entities.Generation.update(id, update)
+```
+
+---
+
 ## Bulk Create
 
 ```ts
@@ -474,3 +539,5 @@ function useDeleteStory() {
 | `client.entity('Story')` without generics | `client.entity<StoryRecord, StoryCreate, StoryUpdate>('Story')` |
 | Using `list()` when you need pagination | Use `query()` for paginated UIs |
 | Calling `query()` inside render without guarding re-runs | Wrap in `useEffect` with cancellation or use TanStack Query |
+| Sending form/workflow object directly to `create()` | Use `pickEntityPayload()` and `assertEntityPayload()` |
+| Public query with illegal field/sort | Use `assertPublicEntityQuery()` and fix schema guardrails |

package/templates/vite/.howone/skills/howone/03-sdk/03-auth.md

@@ -0,0 +1,414 @@
+# Auth
+
+## Environment (read this first — dev must not hit prod)
+
+All auth APIs (`sendEmailVerificationCode`, `loginWithEmailCode`, `unifiedAuth.*`, `howone.auth.logout` revoke) use the **same `env` as `createClient`**, not the browser hostname and not a frozen default.
+
+| `VITE_HOWONE_ENV` / `createClient({ env })` | Auth REST API origin | Hosted login root (`auth: 'hosted'`) |
+|---------------------------------------------|----------------------|--------------------------------------|
+| `local` | `http://localhost:3002` | `https://howone.dev` |
+| `dev` | `https://api.howone.dev` | `https://howone.dev` |
+| `prod` | `https://api.howone.ai` | `https://howone.ai` |
+
+```ts
+// src/lib/sdk.ts — canonical (no extra auth fields required)
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+})
+```
+
+Defaults when `auth` is omitted:
+
+- Auth mode: **hosted** — login/logout redirect to HowOne (`howone.dev` / `howone.ai` by `env`)
+- Auth APIs still follow `env` (`dev` → `api.howone.dev`, `prod` → `api.howone.ai`)
+
+Custom in-app login UI is **opt-in**: `auth: 'custom'` (see below).
+
+```ts
+// main.tsx
+import './lib/sdk' // registers env first
+import { sendEmailVerificationCode } from '@howone/sdk'
+```
+
+Rules for agents:
+
+- **Do not** hardcode `api.howone.ai` or `howone.ai` in app code.
+- **Do not** import auth helpers before `./lib/sdk` (env would stay default `prod`).
+- **Do not** rely on `localhost` hostname to pick `local`; use `env: 'local'` or `env: 'dev'` explicitly.
+- Entity, AI, upload, and auth endpoints all follow this single `env` pin.
+
+---
+
+## Custom login (opt-in only)
+
+Add `auth: 'custom'` when the app renders its own `/login` page but still uses HowOne OTP/OAuth APIs:
+
+```ts
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  auth: 'custom',
+  loginPath: '/login',
+})
+```
+
+That wires:
+
+| Behavior | Result |
+|----------|--------|
+| `howone.auth.logout()` | Clears token + revokes server session → stays on your app → navigates to `loginPath` |
+| `howone.auth.login()` | Navigates to `loginPath` (never howone.dev / howone.ai) |
+| `HowOneProvider` `useHowoneContext().logout()` | Same as `howone.auth.logout()` when `createClient` ran first |
+
+Pair with React:
+
+```tsx
+<HowOneProvider auth="none" brand="visible">
+  <App />
+</HowOneProvider>
+```
+
+`auth="none"` on the provider means **no automatic redirect**; route guards call `howone.me()` and `navigate('/login')` yourself. Keep `brand="visible"` unless the user explicitly asks to hide the bottom-right HowOne logo.
+
+| `createClient({ auth })` | Login UI | `auth.login()` | `auth.logout()` default redirect |
+|--------------------------|----------|----------------|----------------------------------|
+| *(omit)* | **HowOne hosted** | → howone `/auth` | → howone `/auth` |
+| `'custom'` | Your `/login` + HowOne APIs | → `loginPath` | → `loginPath` |
+| `'hosted'` | HowOne hosted (same as default) | → howone `/auth` | → howone `/auth` |
+| `'headless'` | External (Clerk, etc.) | no-op | no redirect |
+| `'none'` | N/A (public app) | no-op | no redirect |
+
+Legacy alias: `'managed'` → `'hosted'`.
+
+### Advanced object form
+
+```ts
+auth: {
+  mode: 'custom',
+  loginPath: '/sign-in',
+  logoutPath: '/sign-in', // optional; defaults to loginPath
+  guard: 'required', // optional; use with HowOneProvider auth="required" for auto-redirect to loginPath
+  getToken: async () => null, // only for headless
+}
+```
+
+---
+
+## Two auth layers
+
+1. **`createClient({ auth })`** — strategy for login/logout destinations (hosted vs custom).
+2. **`unifiedAuth` / standalone OTP & OAuth functions** — headless APIs to build your login UI.
+
+React: `HowOneProvider` + `useHowoneContext` — route guard only (`auth="required" | "optional" | "none"`).
+
+The underlying SDK auth state is managed by `AuthManager`. App code normally uses `client.auth`,
+`client.me()`, `client.requireMe()`, and `HowOneProvider`; SDK contributors use `AuthAdapter` when
+custom token ownership is required.
+
+---
+
+## `client.auth` API
+
+```ts
+import howone from '@/lib/sdk'
+
+howone.auth.mode        // 'custom' | 'hosted' | 'headless' | 'none'
+howone.auth.guard       // 'required' | 'optional' | 'none'
+howone.auth.loginPath   // e.g. '/login'
+howone.auth.logoutPath  // e.g. '/login'
+
+howone.auth.setToken(jwt)
+howone.auth.getToken()
+howone.auth.isAuthenticated()
+
+howone.auth.login(returnUrl?)       // respects auth mode
+await howone.auth.logout()          // respects auth mode
+await howone.auth.clearSession()    // clear only; redirect: false
+await howone.auth.clearSession({ redirect: '/goodbye' })
+await howone.auth.logout({ redirect: false })
+howone.auth.subscribe((state) => {
+  // state: { token, user, isAuthenticated, isLoading }
+})
+```
+
+---
+
+## AuthManager / AuthAdapter extension point
+
+Use an adapter when the token is owned outside the default HowOne local session, for example an
+external auth provider, embedded shell, native app bridge, or custom host application.
+
+```ts
+const client = createClient({
+  projectId,
+  env,
+  auth: {
+    mode: 'headless',
+    adapter: {
+      name: 'external-auth',
+      getToken: () => externalAuth.getToken(),
+      setToken: (token) => externalAuth.setToken(token),
+      getUser: async (token) => externalAuth.getUser(token),
+      login: ({ returnUrl } = {}) => {
+        router.push(`/login?redirect=${encodeURIComponent(returnUrl ?? '/')}`)
+      },
+      logout: () => {
+        externalAuth.clear()
+        router.push('/')
+      },
+      subscribe: (listener) => externalAuth.onChange(() => {
+        listener({
+          token: externalAuth.getToken(),
+          user: externalAuth.getUserSync(),
+          isAuthenticated: Boolean(externalAuth.getToken()),
+          isLoading: false,
+        })
+      }),
+    },
+    tokenCacheMs: 30_000,
+  },
+})
+```
+
+Adapter rules:
+
+- Use `mode: 'headless'` for external token providers.
+- Use `mode: 'custom'` for in-app login pages that still call HowOne OTP/OAuth APIs.
+- Do not create extra token storage keys in app code. Route all token writes through `client.auth.setToken()`.
+- Do not implement app UI in the adapter. It may navigate or notify through callbacks, but visible UI belongs to the app.
+- `getToken` may be sync or async; the SDK caches external tokens according to `tokenCacheMs`.
+- `subscribe` is optional but recommended when the external auth provider can change outside SDK calls.
+
+---
+
+## Custom login page (full pattern for AI codegen)
+
+### 1. SDK (`src/lib/sdk.ts`)
+
+```ts
+import { createClient, defineEntities, withEntities } from '@howone/sdk'
+
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+})
+
+export default withEntities(client, defineEntities({ /* ... */ }))
+```
+
+### 2. Provider (`main.tsx`)
+
+```tsx
+import { HowOneProvider } from '@howone/sdk/react'
+import './lib/sdk' // registers auth config
+
+<HowOneProvider auth="none" brand="visible">
+  <App />
+</HowOneProvider>
+```
+
+### 3. Login route (`/login`) — your styles, HowOne APIs
+
+```tsx
+import {
+  sendEmailVerificationCode,
+  loginWithEmailCode,
+  unifiedAuth,
+} from '@howone/sdk'
+import howone from '@/lib/sdk'
+
+// Email OTP
+const send = await sendEmailVerificationCode(email)
+const result = await loginWithEmailCode(email, code)
+if (result.success && result.token) {
+  howone.auth.setToken(result.token)
+  const user = await howone.me({ refresh: true })
+  navigate('/')
+}
+
+// Google (popup — user stays on your page)
+const { token } = await unifiedAuth.initiateGoogleLogin()
+howone.auth.setToken(token)
+
+// GitHub
+const { token } = await unifiedAuth.initiateGitHubLogin()
+howone.auth.setToken(token)
+```
+
+Phone OTP: `sendPhoneVerificationCode` + `loginWithPhoneCode` (E.164, e.g. `+8613800138000`).
+
+OAuth full-page callback (optional route `/auth/callback`):
+
+```ts
+import { unifiedOAuth } from '@howone/sdk'
+
+const result = unifiedOAuth.checkOAuthCallback()
+if (result.success && result.token) {
+  howone.auth.setToken(result.token)
+  navigate('/')
+}
+```
+
+### 4. Protected routes
+
+```tsx
+useEffect(() => {
+  howone.me()
+    .then(setUser)
+    .catch(() => navigate('/login', { replace: true }))
+}, [])
+```
+
+Use `howone.me()`, not `howone.auth.isAuthenticated()`, for first load.
+
+### 5. Logout button
+
+```ts
+await howone.auth.logout()
+// custom mode: already navigates to loginPath; no howone.dev redirect
+```
+
+Do **not** call hosted-only patterns when `auth: 'custom'` is set:
+
+- ~~`howone.auth.login()` expecting howone.ai~~ (goes to `/login` instead — OK)
+- ~~Manual `window.location` to howone.dev~~
+
+---
+
+## Hosted login (default)
+
+Omit `auth` — this is the default for `createClient({ projectId, env })`:
+
+```ts
+createClient({ projectId, env })
+```
+
+```tsx
+<HowOneProvider auth="required">
+  <App />
+</HowOneProvider>
+```
+
+Unauthenticated users redirect to HowOne hosted `/auth`.
+
+---
+
+## Headless external auth
+
+```ts
+createClient({
+  projectId,
+  env,
+  auth: {
+    mode: 'headless',
+    adapter: {
+      getToken: async () => externalAuth.getJwt(),
+      login: ({ returnUrl } = {}) => externalAuth.login({ returnUrl }),
+      logout: () => externalAuth.logout(),
+    },
+    tokenCacheMs: 30_000,
+  },
+})
+```
+
+Do not use `howone.auth.setToken` for Clerk/Supabase unless bridging into HowOne JWT.
+
+Headless mode should not redirect to HowOne hosted auth by default. The external adapter decides
+what `login` and `logout` mean.
+
+---
+
+## Email / phone / OAuth API reference
+
+(Same as before — see sections below for request/response shapes.)
+
+### Email OTP
+
+```ts
+import { sendEmailVerificationCode, loginWithEmailCode } from '@howone/sdk'
+
+await sendEmailVerificationCode(email, appName?)
+const result = await loginWithEmailCode(email, code)
+// result.token on success → howone.auth.setToken(result.token)
+```
+
+### Phone OTP
+
+```ts
+import { sendPhoneVerificationCode, loginWithPhoneCode } from '@howone/sdk'
+```
+
+### OAuth popup
+
+```ts
+import { unifiedAuth } from '@howone/sdk'
+
+await unifiedAuth.initiateGoogleLogin()
+await unifiedAuth.initiateGitHubLogin()
+```
+
+### Server logout
+
+```ts
+import { unifiedAuth } from '@howone/sdk'
+
+const token = howone.auth.getToken()
+if (token) await unifiedAuth.logout(token)
+await howone.auth.logout()
+```
+
+With `auth: 'custom'`, `howone.auth.logout()` already revokes and navigates locally.
+
+---
+
+## User profile
+
+```ts
+const user = await howone.me()
+const user = await howone.requireMe() // throws HowOneAuthError
+```
+
+---
+
+## HowOneAuthError
+
+```ts
+import { HowOneAuthError } from '@howone/sdk'
+
+try {
+  await howone.requireMe()
+} catch (err) {
+  if (err instanceof HowOneAuthError) {
+    howone.auth.login() // custom → /login; hosted → howone.ai
+  }
+}
+```
+
+---
+
+## Common mistakes (AI agents)
+
+| Mistake | Fix |
+|---------|-----|
+| Custom `/login` page with HowOne OTP/OAuth | Add `auth: 'custom'` in `createClient` |
+| `HowOneProvider auth="required"` + custom login | Use `auth="none"`; guard with `howone.me()` |
+| `howone.auth.logout()` expecting no redirect before this change | Now respects `auth: 'custom'` |
+| `auth.isAuthenticated()` on first paint | Use `await howone.me()` |
+| Phone without country code | E.164 `+86...` |
+| JSON Schema in `defineAiAction` | Convert manifest JSON Schema to Zod |
+| Second localStorage key for token | Only `howone.auth.setToken` |
+| Custom external provider wired with `getToken` only but no logout | Add an `adapter.logout` if the host owns session clearing |
+| App UI inside SDK auth adapter | Move UI to frontend components and use callbacks/navigation only |
+
+---
+
+## Non-negotiable for agents
+
+- Default **`createClient({ projectId, env })`** = HowOne hosted login. Add **`auth: 'custom'`** only for in-app login pages.
+- Never hardcode howone.dev / howone.ai URLs in app login/logout when `auth: 'custom'`.
+- Implement login UI with `sendEmailVerificationCode` / `loginWithEmailCode` / `unifiedAuth` — not iframe to hosted auth.
+- After any successful login: `howone.auth.setToken(token)` then `await howone.me({ refresh: true })`.
+- Logout: `await howone.auth.logout()` only (no manual redirect needed when `auth: 'custom'`).
+- For external auth, use `auth.adapter`; do not patch request headers manually.
+- SDK auth exposes state/callbacks only. Visible feedback, loading spinners, account menus, and errors are frontend app code.