howone 0.1.23 → 0.1.25

package/templates/vite/.howone/skills/howone-sdk/02-database/03-data-access-patterns.md

@@ -1,103 +1,103 @@
 # Data Access Patterns
 
-Use this reference to connect backend `access` design to frontend SDK calls.
+Use this reference to connect backend `access` design to frontend SDK calls. It answers:
+**which namespace should the app call, which filters are legal, and what must not be persisted?**
 
-## Private Per-User Data
+For schema design, read `01-schema-design.md`. For query syntax details, read
+`04-query-dsl-and-responses.md`.
 
-Use for todos, notes, journals, saved generations, personal files, dashboards, and user-owned
-settings.
+## Namespace Decision
 
-Schema posture:
+| Schema / page need | SDK namespace | Auth header | Typical method |
+|---|---|---|---|
+| Current user's private records | `howone.entities.Entity` | yes | `query.mine`, `create`, `update`, `delete` |
+| Logged-in shared records | `howone.entities.Entity` | yes | `query`, `get`, CRUD |
+| Public list page | `howone.public.entities.Entity` | no | `query` |
+| Public scoped share/detail | `howone.public.entities.Entity` | no | `queryScoped`, `get` with scope options |
+| Schema tooling | `howone.schema` | yes | `previewPatch`, `applyPatch` |
+| Low-level fallback | `howone.raw` / `howone.public.raw` | depends | only when typed method missing |
+
+Do not mix authenticated and public namespaces for the same page without a clear reason.
+
+## Pattern A: Private Per-User Data
+
+Use for todos, notes, journals, saved generations, personal dashboards, private settings.
+
+Schema:
 
 ```json
 {
   "visibility": "private",
   "access": {
-    "authenticated": {
-      "read": "own",
-      "create": "own",
-      "update": "own",
-      "delete": "own"
-    },
-    "public": {
-      "read": "none",
-      "create": "none",
-      "update": "none",
-      "delete": "none"
-    }
+    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+    "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
   }
 }
 ```
 
-Frontend calls:
+Frontend:
 
 ```ts
-const result = await howone.entities.Todo.query.mine({
+const list = await howone.entities.Todo.query.mine({
   page: { number: 1, size: 50 },
   orderBy: { updatedDate: 'desc' },
 })
+
+await howone.entities.Todo.create({
+  text,
+  completed: false,
+})
 ```
 
 Rules:
 
-- Use `query.mine(...)` for list pages.
-- Use authenticated `create/update/delete`.
-- Do not pass owner fields such as `ownerId`, `created_by_id`, `createdById`,
-  `created_by_user_id`, or `puid`.
+- Do not pass `ownerId`, `created_by_id`, `createdById`, `created_by_user_id`, or `puid`.
+- Backend derives owner from JWT/session.
+- Use `query.mine()` for owned lists.
+- For first auth load, call `await howone.me()` or `await howone.requireMe()`.
 
-## Authenticated Shared Data
+## Pattern B: Authenticated Shared Data
 
-Use when logged-in users in the app should see shared records.
+Use when logged-in app users can see shared records: team projects, CMS admin, internal catalogs.
 
-Schema posture:
+Schema:
 
 ```json
 {
   "visibility": "private",
   "access": {
-    "authenticated": {
-      "read": "all",
-      "create": "all",
-      "update": "all",
-      "delete": "all"
-    },
-    "public": {
-      "read": "none",
-      "create": "none",
-      "update": "none",
-      "delete": "none"
-    }
+    "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
+    "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
   }
 }
 ```
 
-Frontend calls:
+Frontend:
 
 ```ts
-const result = await howone.entities.Project.query({
+const list = await howone.entities.Project.query({
   page: { number: 1, size: 20 },
   orderBy: { updatedDate: 'desc' },
 })
 ```
 
-Use `query(...)`, not `query.mine(...)`.
+Rules:
+
+- Use `query()`, not `query.mine()`.
+- Still require auth.
+- Be conservative with `update: "all"` and `delete: "all"` unless the app has a real role model.
 
-## Public Read-Only Content
+## Pattern C: Public Read-Only Content
 
-Use for public articles, templates, catalogs, profiles, or landing-page content.
+Use for public articles, templates, products, profiles, published galleries.
 
-Schema posture:
+Schema:
 
 ```json
 {
   "visibility": "public",
   "access": {
-    "authenticated": {
-      "read": "all",
-      "create": "all",
-      "update": "all",
-      "delete": "all"
-    },
+    "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
     "public": {
       "read": "list",
       "create": "none",
@@ -112,34 +112,34 @@ Schema posture:
 }
 ```
 
-Frontend calls:
+Frontend:
 
 ```ts
-const result = await howone.public.entities.Article.query({
-  where: { status: 'published' },
+const list = await howone.public.entities.Article.query({
+  where: { status: 'published', category },
   page: { number: 1, size: 20 },
   orderBy: { publishedAt: 'desc' },
 })
 ```
 
-Public query types should expose only allowed filters and allowed sorts.
+Rules:
+
+- Public filters must be in `allowedFilters`.
+- Public sorts must be in `allowedSorts`.
+- Never pass tokens or use authenticated namespace for anonymous landing pages.
+- Keep public result fields safe for anonymous users.
 
-## Public Scoped Share Pages
+## Pattern D: Public Scoped Share Pages
 
-Use for public URLs that expose one owner-scoped record, such as QR pages or profile pages.
+Use for public URLs exposing one scoped record: QR profile, public report, resume, invite page.
 
-Schema posture:
+Schema:
 
 ```json
 {
   "visibility": "public",
   "access": {
-    "authenticated": {
-      "read": "own",
-      "create": "own",
-      "update": "own",
-      "delete": "own"
-    },
+    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
     "public": {
       "read": "scoped",
       "create": "none",
@@ -155,18 +155,155 @@ Schema posture:
 }
 ```
 
-Frontend calls:
+Frontend:
 
 ```ts
 const result = await howone.public.entities.QrProfile.queryScoped({
   where: { ownerId, slug, active: true },
   page: { number: 1, size: 1 },
 })
+const profile = result.items[0] ?? null
 ```
 
 Rules:
 
 - Pass every `requiredScopes` field.
-- Do not use current user's `puid` as public owner scope unless schema explicitly stores that
-  value as the public scope.
-- Public scoped reads must stay inside `howone.public.entities.*`.
+- Do not use current JWT `puid` as `ownerId` unless schema explicitly stores that as public scope.
+- Do not turn scoped pages into broad list pages.
+- Keep `maxLimit` small.
+
+## Pattern E: Public Create / Anonymous Submission
+
+Use only for forms that must accept anonymous/public submissions: waitlist, contact, feedback,
+public RSVP.
+
+Schema:
+
+```json
+{
+  "visibility": "public",
+  "access": {
+    "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
+    "public": {
+      "read": "none",
+      "create": "scoped",
+      "update": "none",
+      "delete": "none",
+      "requiredScopes": ["created_by_user_id"],
+      "allowedFilters": [],
+      "allowedSorts": [],
+      "defaultLimit": 1,
+      "maxLimit": 1
+    }
+  }
+}
+```
+
+Frontend:
+
+```ts
+await howone.public.entities.Feedback.create({
+  created_by_user_id: projectUserId,
+  message,
+  rating,
+})
+```
+
+Rules:
+
+- Public create needs a clear `created_by_user_id` source when backend requires ownership mapping.
+- Do not expose public read unless needed.
+- Add anti-abuse UX/server constraints outside the dynamic schema when needed.
+- Never persist UI-only fields from form components.
+
+## Pattern F: AI Workflow Output Persistence
+
+Use for generation/analyze/report products that need history and refresh resilience.
+
+Recommended flow:
+
+```ts
+const pending = await howone.entities.Generation.create({
+  prompt,
+  status: 'pending',
+})
+
+try {
+  const output = await howone.ai.generateImage.run({ prompt })
+  await howone.entities.Generation.update(pending.id, {
+    status: 'completed',
+    resultUrl: output.imageUrl,
+    completedAt: new Date().toISOString(),
+  })
+} catch (error) {
+  await howone.entities.Generation.update(pending.id, {
+    status: 'failed',
+    errorMessage: error instanceof Error ? error.message : 'Generation failed',
+  })
+}
+
+const history = await howone.entities.Generation.query.mine({
+  orderBy: { updatedDate: 'desc' },
+  page: { number: 1, size: 20 },
+})
+```
+
+Rules:
+
+- Persist only fields declared in the entity schema.
+- Do not persist raw workflow event streams unless schema defines an object/array field for them.
+- Failure branch must persist failure if the product shows history.
+- Latest result, history list, and detail pages should reload from data API, not only local state.
+
+## Payload Whitelist Rule
+
+Before every create/update, mentally compute:
+
+```text
+payload keys ⊆ entity.properties keys
+```
+
+Allowed:
+
+```ts
+await howone.entities.Todo.create({
+  text,
+  completed: false,
+})
+```
+
+Forbidden:
+
+```ts
+await howone.entities.Todo.create({
+  text,
+  completed: false,
+  gradient_direction: 'to right', // UI-only
+  created_by_id: user.id,         // system/owner field
+  workflowRawResult: output,      // undeclared workflow envelope
+})
+```
+
+If the app truly needs a new persisted field, update schema first.
+
+## Access-to-SDK Mapping
+
+| Access posture | Read | Create | Update/Delete |
+|---|---|---|---|
+| authenticated `own` | `entities.X.query.mine()` | `entities.X.create()` | `entities.X.update/delete()` |
+| authenticated `all` | `entities.X.query()` | `entities.X.create()` | `entities.X.update/delete()` |
+| public `list` | `public.entities.X.query()` | no | no |
+| public `scoped` | `public.entities.X.queryScoped()` | only if `create: scoped/any` | only if `update: scoped/any` |
+| public `none` | no public call | no public call | no public call |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Passing `created_by_user_id` for normal private data | Omit owner fields; backend derives owner. |
+| Using `entities.*` on public page | Use `public.entities.*`. |
+| Public filter not in `allowedFilters` | Add filter to schema or remove query. |
+| Public sort not in `allowedSorts` | Add sort to schema or change UI. |
+| Saving workflow output object directly | Map only declared fields. |
+| Rendering history only from local state | Reload via `query.mine()` / public query. |
+| Treating `visibility: "public"` as enough | Always define `access.public`. |

package/templates/vite/.howone/skills/howone-sdk/02-database/04-query-dsl-and-responses.md

@@ -0,0 +1,237 @@
+# Query DSL And Responses
+
+Use this reference when implementing list/detail pages, filters, sorting, pagination, or response
+normalization for HowOne dynamic entities.
+
+## SDK Query Shape
+
+```ts
+await howone.entities.Todo.query({
+  where: {
+    completed: false,
+    priority: { in: ['medium', 'high'] },
+    updatedDate: { gte: '2026-01-01T00:00:00.000Z' },
+  },
+  search: 'invoice',
+  page: { number: 1, size: 20 },
+  orderBy: { updatedDate: 'desc' },
+  include: ['owner'],
+  exactCount: true,
+})
+```
+
+Private owner-scoped list:
+
+```ts
+await howone.entities.Todo.query.mine({
+  page: { number: 1, size: 50 },
+  orderBy: { updatedDate: 'desc' },
+})
+```
+
+Public list:
+
+```ts
+await howone.public.entities.Article.query({
+  where: { status: 'published' },
+  orderBy: { publishedAt: 'desc' },
+  page: { number: 1, size: 20 },
+})
+```
+
+Public scoped:
+
+```ts
+await howone.public.entities.QrProfile.queryScoped({
+  where: { ownerId, slug, active: true },
+  page: { number: 1, size: 1 },
+})
+```
+
+## Operators
+
+Supported field operators:
+
+```ts
+type FieldOperator<T> = {
+  eq?: T
+  equals?: T
+  ne?: T
+  not?: T
+  gt?: T
+  gte?: T
+  lt?: T
+  lte?: T
+  contains?: string
+  like?: string
+  startsWith?: string
+  starts?: string
+  endsWith?: string
+  ends?: string
+  in?: T[]
+  notIn?: T[]
+  null?: boolean
+  empty?: boolean
+  exists?: boolean
+}
+```
+
+Examples:
+
+```ts
+where: { status: 'published' }
+where: { status: { eq: 'published' } }
+where: { score: { gte: 80, lt: 100 } }
+where: { category: { in: ['news', 'guide'] } }
+where: { title: { contains: 'AI' } }
+where: { deletedAt: { null: true } }
+```
+
+## Pagination
+
+Use SDK page object:
+
+```ts
+page: { number: 1, size: 20 }
+```
+
+Response:
+
+```ts
+type QueryResult<T> = {
+  items: T[]
+  page: {
+    number: number
+    size: number
+    total: number
+    totalPages: number
+    hasNext: boolean
+    hasPrev: boolean
+  }
+  traceId?: string | number
+  raw?: unknown
+}
+```
+
+Always render from a normalized array:
+
+```ts
+const result = await howone.entities.Todo.query.mine(...)
+const items = Array.isArray(result.items) ? result.items : []
+```
+
+## Sorting
+
+SDK uses:
+
+```ts
+orderBy: { updatedDate: 'desc' }
+```
+
+Rules:
+
+- Public sort fields must be in `access.public.allowedSorts`.
+- Private sort fields should be in `performance.allowedSorts` and covered by indexes.
+- Prefer `updatedDate` for recently changed lists and `createdDate` for creation history.
+- Do not expose arbitrary public sort fields.
+
+## Include / Relations
+
+Use `include` only for relation names declared in schema `relations`.
+
+```ts
+await howone.entities.Article.query({
+  include: ['author'],
+})
+```
+
+Rules:
+
+- Do not invent include names.
+- Public includes must be safe for anonymous exposure.
+- If a list needs a small display field frequently, consider denormalizing it instead of requiring include on every row.
+
+## Detail Reads
+
+Authenticated:
+
+```ts
+const item = await howone.entities.Todo.get(id)
+const item = await howone.entities.Todo.getOrThrow(id)
+```
+
+Public:
+
+```ts
+const item = await howone.public.entities.Article.get(id)
+```
+
+For public scoped detail, prefer `queryScoped` when the route naturally has scope fields like
+`ownerId + slug`.
+
+## Response Field Names
+
+SDK defaults to `caseStyle: 'camel'`, so responses are normalized toward camelCase where supported.
+Still know the backend system field meanings:
+
+| Backend concept | Common SDK field |
+|---|---|
+| record id | `id` |
+| created date | `createdDate` or `created_date` depending case style |
+| updated date | `updatedDate` or `updated_date` |
+| owner | `createdById` or `created_by_id` |
+| schema version id | `schemaVersionId` or `schema_version_id` |
+| schema version number | `schemaVersionNumber` or `schema_version_number` |
+
+Do not use `_id` in app code unless inspecting raw backend payloads.
+
+## Public Guardrails
+
+Before writing public query code, check schema:
+
+```json
+"public": {
+  "read": "list",
+  "allowedFilters": ["status", "slug"],
+  "allowedSorts": ["publishedAt"],
+  "defaultLimit": 20,
+  "maxLimit": 100
+}
+```
+
+Then only use allowed filters and sorts:
+
+```ts
+// OK
+where: { status: 'published' }
+orderBy: { publishedAt: 'desc' }
+
+// Not OK unless listed in access.public
+where: { internalReviewState: 'approved' }
+orderBy: { revenue: 'desc' }
+```
+
+## Search
+
+Use `search` for broad text search only when the backend/schema supports the desired behavior:
+
+```ts
+await howone.public.entities.Article.query({
+  search: query,
+  where: { status: 'published' },
+})
+```
+
+Do not use `search` as a substitute for required public scopes.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Rendering `res.data.data` from SDK query | SDK returns `QueryResult.items`; render `result.items`. |
+| Using `_id` as record id | Use `id`. |
+| Public query with unlisted filter | Add to `allowedFilters` or remove it. |
+| Public query with unlisted sort | Add to `allowedSorts` or change sorting. |
+| Passing owner filters in authenticated `own` queries | Use `query.mine()` and omit owner fields. |
+| Using include without schema relation | Add relation first or remove include. |
+| No pagination on list pages | Always pass `page` and respect `maxLimit`. |