howone 0.1.23 → 0.1.25

package/templates/vite/.howone/skills/howone-sdk/02-database/05-ai-persistence-patterns.md

@@ -0,0 +1,372 @@
+# AI Persistence Patterns
+
+Use this reference when an AI workflow output must become durable product data: generation history,
+saved results, analysis reports, retryable jobs, share pages, or user libraries.
+
+AI workflow contracts describe **how to produce an output**. Entity schemas describe **what the app
+persists, lists, edits, shares, and reloads**. Do not merge those two responsibilities.
+
+## Core Rule
+
+```text
+AI capability outputSchema != database entity schema
+```
+
+The output schema is the workflow return contract. It can contain transient execution details,
+intermediate data, model metadata, or provider-shaped structures. The database schema is a product
+contract. It should store only fields that the app needs after refresh, across sessions, or on public
+pages.
+
+For every AI feature, ask:
+
+| Question | Persist? | Where |
+|---|---:|---|
+| Must the user see this after refresh? | yes | Entity field |
+| Must it appear in history/library/search? | yes | Entity field + index if queried |
+| Is it only needed while streaming/running? | no | Local UI state / runtime event |
+| Is it provider debug data? | usually no | Logs, not entity data |
+| Is it needed to retry or resume? | yes | Entity field |
+| Is it sensitive model/provider metadata? | usually no | Avoid public entity fields |
+
+## Recommended Flow
+
+For long-running or user-visible AI operations, create a pending record before calling the workflow.
+
+```ts
+import { runAiActionAndPersist } from '@howone/sdk'
+
+await runAiActionAndPersist({
+  entity: howone.entities.Generation,
+  input: { prompt },
+  createPending: (input) => ({
+    prompt: input.prompt,
+    status: 'pending',
+    requestedAt: new Date().toISOString(),
+  }),
+  run: (input) => howone.ai.generateImage.run(input),
+  mapCompleted: ({ output }) => ({
+    status: 'completed',
+    resultUrl: output.imageUrl,
+    completedAt: new Date().toISOString(),
+  }),
+  mapFailed: ({ error }) => ({
+    status: 'failed',
+    errorMessage: error instanceof Error ? error.message : 'Generation failed',
+  }),
+})
+```
+
+Why pending-first:
+
+- refresh can show an in-progress item instead of losing the request;
+- failure can be displayed in history;
+- retry can reuse the original prompt/options;
+- support/debug can identify which input produced the failed state;
+- UI can render from persisted data instead of assuming local state survived.
+
+For very fast, disposable AI actions, persistence may be unnecessary. Do not create an entity just
+because an AI workflow exists.
+
+## Status Fields
+
+Every persisted AI job/history entity should have a status field.
+
+Recommended:
+
+```json
+{
+  "status": {
+    "type": "string",
+    "description": "pending | running | completed | failed | canceled",
+    "default": "pending"
+  }
+}
+```
+
+Use stable string values:
+
+| Status | Meaning |
+|---|---|
+| `pending` | Record exists, workflow has not produced final output. |
+| `running` | Optional if the app receives a running state after submission. |
+| `completed` | Output fields are valid for display. |
+| `failed` | `errorMessage` or failure fields explain the failure. |
+| `canceled` | User/system canceled and no final output should be expected. |
+
+Rules:
+
+- Do not infer completion only from `resultUrl` or another output field.
+- Keep failed records when the product has history or retry UX.
+- If the UI shows a spinner from persisted data, it must also handle stale `pending/running` records.
+
+## Minimal Generation History Schema
+
+Use for image/text/report/music/video generation history.
+
+```json
+{
+  "name": "Generation",
+  "type": "object",
+  "visibility": "private",
+  "properties": {
+    "prompt": { "type": "string" },
+    "status": { "type": "string", "default": "pending" },
+    "resultUrl": { "type": ["string", "null"], "default": null },
+    "resultText": { "type": ["string", "null"], "default": null },
+    "errorMessage": { "type": ["string", "null"], "default": null },
+    "requestedAt": { "type": "date" },
+    "completedAt": { "type": ["date", "null"], "default": null }
+  },
+  "required": ["prompt", "status", "requestedAt"],
+  "access": {
+    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+    "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
+  },
+  "indexes": [
+    { "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" },
+    { "name": "owner_status_updated", "fields": ["status", "updatedDate"], "scope": "owner" }
+  ],
+  "performance": {
+    "defaultLimit": 20,
+    "maxLimit": 100,
+    "allowedSorts": ["updatedDate", "requestedAt"]
+  },
+  "presentation": {
+    "titleField": "prompt",
+    "subtitleField": "status"
+  }
+}
+```
+
+Use separate result fields instead of one opaque `result` object when the UI lists or filters them.
+Use an object field only for genuinely nested, product-level structured results.
+
+## Analysis Report Schema
+
+Use when AI returns a structured report that users browse later.
+
+```json
+{
+  "name": "AnalysisReport",
+  "type": "object",
+  "visibility": "private",
+  "properties": {
+    "sourceTitle": { "type": "string" },
+    "sourceUrl": { "type": ["string", "null"], "default": null },
+    "status": { "type": "string", "default": "pending" },
+    "summary": { "type": ["string", "null"], "default": null },
+    "insights": { "type": "array", "default": [] },
+    "score": { "type": ["number", "null"], "default": null },
+    "errorMessage": { "type": ["string", "null"], "default": null },
+    "requestedAt": { "type": "date" },
+    "completedAt": { "type": ["date", "null"], "default": null }
+  },
+  "required": ["sourceTitle", "status", "requestedAt"],
+  "access": {
+    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+    "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
+  }
+}
+```
+
+Mapping rule:
+
+```ts
+const output = await howone.ai.analyzeDocument.run(input)
+
+await howone.entities.AnalysisReport.update(report.id, {
+  status: 'completed',
+  summary: output.summary,
+  insights: output.insights,
+  score: output.score,
+  completedAt: new Date().toISOString(),
+})
+```
+
+Do not save the whole workflow envelope unless the entity has an explicitly designed field for that
+envelope and the product needs it.
+
+## Public AI Result Share Page
+
+Use when a user can share one generated result publicly.
+
+Recommended split:
+
+- private `Generation` entity for user history and edits;
+- public or scoped `SharedGeneration` entity for anonymous viewing.
+
+Why split:
+
+- private history may include prompts, failures, drafts, and internal metadata;
+- public page should expose only curated fields;
+- public access rules stay simple and auditable;
+- unsharing can delete or deactivate the shared record without destroying private history.
+
+Public scoped schema:
+
+```json
+{
+  "name": "SharedGeneration",
+  "type": "object",
+  "visibility": "public",
+  "properties": {
+    "shareId": {
+      "type": "string",
+      "autoGenerate": { "strategy": "uuid" }
+    },
+    "title": { "type": "string" },
+    "resultUrl": { "type": "string" },
+    "active": { "type": "boolean", "default": true },
+    "sourceGenerationId": { "type": "string" }
+  },
+  "required": ["shareId", "title", "resultUrl", "active", "sourceGenerationId"],
+  "access": {
+    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+    "public": {
+      "read": "scoped",
+      "create": "none",
+      "update": "none",
+      "delete": "none",
+      "requiredScopes": ["shareId"],
+      "allowedFilters": ["shareId", "active"],
+      "allowedSorts": ["updatedDate"],
+      "defaultLimit": 1,
+      "maxLimit": 1
+    }
+  },
+  "indexes": [
+    { "name": "share_id_unique", "fields": ["shareId"], "unique": true },
+    { "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" }
+  ]
+}
+```
+
+Public page:
+
+```ts
+const result = await howone.public.entities.SharedGeneration.queryScoped({
+  where: { shareId, active: true },
+  page: { number: 1, size: 1 },
+})
+
+const shared = result.items[0] ?? null
+```
+
+Rules:
+
+- Do not expose private prompt fields unless the product explicitly wants that.
+- Use `active` or a deletion flow for unshare.
+- Keep public `maxLimit` at `1` for one-share pages.
+
+## Retry Design
+
+If the product has retry, store enough input fields to rebuild the workflow request.
+
+Persist:
+
+- user prompt or source content reference;
+- selected mode/model/style options that affect output;
+- uploaded file IDs/URLs needed by the workflow;
+- status and failure message;
+- timestamps.
+
+Do not persist:
+
+- temporary UI component state;
+- auth/session/token values;
+- raw streaming chunks;
+- provider secrets;
+- hidden prompt text that should stay server-side;
+- large binary content when file upload should store a URL or file id.
+
+Retry example:
+
+```ts
+const old = await howone.entities.Generation.getOrThrow(id)
+
+const retry = await howone.entities.Generation.create({
+  prompt: old.prompt,
+  status: 'pending',
+  requestedAt: new Date().toISOString(),
+})
+
+const output = await howone.ai.generateImage.run({
+  prompt: old.prompt,
+})
+
+await howone.entities.Generation.update(retry.id, {
+  status: 'completed',
+  resultUrl: output.imageUrl,
+  completedAt: new Date().toISOString(),
+})
+```
+
+Prefer creating a new retry record when the product is history-oriented. Prefer updating the same
+record only when the product treats retry as replacing the original attempt.
+
+## Resume Design
+
+On page load, query persisted records instead of relying on local state:
+
+```ts
+const history = await howone.entities.Generation.query.mine({
+  where: { status: { in: ['pending', 'running', 'completed', 'failed'] } },
+  orderBy: { updatedDate: 'desc' },
+  page: { number: 1, size: 20 },
+})
+```
+
+Then:
+
+- render `completed` from output fields;
+- render `failed` from `errorMessage`;
+- render `pending/running` as in progress only if the app has a way to poll status;
+- mark stale pending records as failed/canceled when product rules define a timeout.
+
+Do not leave indefinite pending rows with no recovery path.
+
+## Field Mapping Checklist
+
+Before implementing persistence, write the mapping explicitly:
+
+```text
+workflow input.prompt       -> Generation.prompt
+workflow input.style        -> Generation.style
+workflow output.imageUrl    -> Generation.resultUrl
+workflow output.caption     -> Generation.resultText
+workflow error.message      -> Generation.errorMessage
+runtime request started     -> Generation.requestedAt
+runtime request completed   -> Generation.completedAt
+```
+
+If a workflow output field has no mapping, decide whether it is intentionally transient or whether
+the entity schema is missing a product field.
+
+## Access Checklist
+
+Choose access based on product behavior:
+
+| Product behavior | Entity access |
+|---|---|
+| User-only private generation history | authenticated own, public none |
+| Team/shared authenticated library | authenticated all or future role-scoped model |
+| Anonymous public gallery | public list with safe fields only |
+| One public share link | public scoped with share id |
+| Public submission to AI queue | public create only if abuse constraints are handled |
+
+Never make the main generation history public just to support a public share page. Create a scoped
+share entity or a curated public entity.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Treating `outputSchema` as the entity schema | Design product persistence separately. |
+| Saving raw workflow envelopes | Map only fields the product needs after refresh. |
+| No status field | Add `status` and explicit failure fields. |
+| Creating history only after success | Create pending first when history/resume matters. |
+| Losing failures | Persist `failed` state and `errorMessage`. |
+| Publicly exposing private prompt/history | Use a separate public scoped/share entity. |
+| Retrying without stored inputs | Persist the inputs/options needed for retry. |
+| Rendering from local state only | Reload from entity queries on page load. |
+| Leaving stale pending forever | Add timeout/recovery behavior in product logic. |

package/templates/vite/.howone/skills/howone-sdk/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/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 |