howone 0.1.16 → 0.1.18

package/package.json

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

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

@@ -12,13 +12,13 @@ This skill is the authoritative source of truth for all `@howone/sdk` usage in g
 | 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 |
+| Entity Operations | `references/02-entity-operations.md` | authenticated CRUD/query, public entity reads/writes, include, pagination, 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` |
+| Manifest Codegen | `references/08-manifest-codegen.md` | Reading `.howone/database` and `.howone/ai`, generating `src/lib/sdk.ts`, public access-aware types |
 
 ## Workflow
 
@@ -52,6 +52,7 @@ export type TodoRecord = EntityRecord & {
 }
 export type TodoCreate = { title: string; completed: boolean }
 export type TodoUpdate = Partial<TodoCreate>
+export type TodoPublicQuery = { completed?: boolean; limit?: number }
 
 // Schemas
 export const summarizeTodoInputSchema = z.object({ title: z.string().min(1) })
@@ -83,7 +84,14 @@ export default howone
 ## 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.
+- **Single SDK config source**: configure `projectId` and `env` only in `createClient`. Do not pass env/project config to `HowOneProvider`; the React provider reads the SDK config set by `createClient`.
+- **Authenticated owner semantics**: authenticated entity APIs derive owner from the JWT. Do not pass `created_by_id`, `created_by_user_id`, `ownerId`, or `puid` to authenticated queries or writes.
+- **Public namespace**: public reads/writes must use `howone.public.entities.*` or `client.public.entity(...)`. Do not call authenticated `howone.entities.*` from public landing pages.
+- **Public scoped queries**: for `access.public.read = "scoped"`, use `queryScoped` / `query.scoped` and pass every `requiredScopes` field such as `ownerId` and `slug`.
+- **Public writes**: only generate public `create` / `update` calls when manifest access explicitly allows them. Public create must include `created_by_user_id` or the schema-defined owner scope.
 - **Explicit types**: define `EntityRecord`, `Create`, and `Update` types explicitly. Never derive create types from `Omit<EntityRecord & ...>` — it widens the payload.
+- **System fields**: never include `id`, `_id`, `created_date`, `updated_date`, `created_by_id`, `schema_version_id`, `schema_version_number`, or `is_sample` in create/update input types.
+- **Schema versions**: treat `schemaVersionId` / `schemaVersionNumber` on records as write-time schema metadata, not business versioning.
 - **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.

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

@@ -67,6 +67,22 @@ client.entity<TRecord, TCreate, TUpdate>(entityName: string): EntityClient
 // Typed entity map (populated via withEntities)
 client.entities: Record<string, EntityClient>
 
+// Public entity namespace (never sends Authorization)
+client.public.entity<TRecord, TPublicCreate, TPublicUpdate>(entityName: string): PublicEntityClient
+client.public.entities: Record<string, PublicEntityClient>
+client.public.raw: RawHttpClient
+
+// Schema contract/version client
+client.schema.listDefinitions()
+client.schema.getDefinition(entityName)
+client.schema.operate(operation)
+client.schema.previewPatch(patch, { expectedVersionId, reason })
+client.schema.applyPatch(patch, { expectedVersionId, reason })
+client.schema.getState()
+client.schema.listVersions()
+client.schema.getVersion(versionId)
+client.schema.restore(versionId, reason?)
+
 // AI action runner (low-level)
 client.ai: AiClient
 
@@ -215,9 +231,12 @@ const client = createClient({
 ```ts
 type UserProfile = {
   id: string
+  userId?: string
+  puid?: string
   email?: string
   name?: string
   avatarUrl?: string
+  appId?: string
   roles?: string[]
   metadata?: Record<string, unknown>
 }
@@ -242,6 +261,15 @@ client.auth.logout()
 
 ---
 
+## Client Namespace Rules
+
+- Use `client.entities.*` / `howone.entities.*` for authenticated app data. The backend derives owner from the JWT; do not pass owner filters or owner fields.
+- Use `client.public.entities.*` / `howone.public.entities.*` for public landing pages, public article lists, scoped QR/profile pages, and public forms.
+- Use `client.schema.*` only for backend contract management: definitions, schema operations, schema patch preview/apply, versions, and restore.
+- Use `client.raw.*` only for custom endpoints not covered by typed SDK methods.
+
+---
+
 ## HowOneAuthError
 
 ```ts

package/templates/vite/.howone/skills/howone-sdk/references/02-entity-operations.md

@@ -18,7 +18,9 @@ type EntityRecord = {
   id: string
   createdDate?: string
   updatedDate?: string
-  createdById?: string
+  createdById?: string  // backend owner id from created_by_id
+  schemaVersionId?: string
+  schemaVersionNumber?: number
   isSample?: boolean
   [key: string]: unknown   // index signature — important for typing
 }
@@ -105,6 +107,25 @@ type DeleteResult = {
 }
 ```
 
+## PublicEntityClient API
+
+Public entity calls use `/api/entities/public/apps/:appId/...` and do not send auth headers.
+Only use them when the entity manifest explicitly allows `access.public.read`,
+`access.public.create`, or `access.public.update`.
+
+```ts
+type PublicEntityClient<TRecord, TPublicCreate, TPublicUpdate> = {
+  name: string
+  query(options?: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
+  query.scoped(options: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
+  queryScoped(options: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
+  get(id: string, options?: QueryOptions<TRecord>): Promise<TRecord | null>
+  getOrThrow(id: string, options?: QueryOptions<TRecord>): Promise<TRecord>
+  create(data: TPublicCreate): Promise<TRecord>
+  update(id: string, data: TPublicUpdate): Promise<TRecord>
+}
+```
+
 ---
 
 ## CRUD Examples
@@ -208,7 +229,12 @@ const result = await howone.entities.Story.query({
 })
 ```
 
-### query.mine — only current user's records
+### query.mine — current authenticated user's records
+
+`query.mine()` is the preferred way to fetch records owned by the authenticated user.
+It requires a valid auth token, then lets the backend derive owner from the JWT. Do not
+manually pass `created_by_id`, `created_by_user_id`, `ownerId`, or `puid` in authenticated
+queries or writes.
 
 ```ts
 const myStories = await howone.entities.Story.query.mine({
@@ -217,6 +243,18 @@ const myStories = await howone.entities.Story.query.mine({
 })
 ```
 
+For public pages that cannot use the current auth session, switch to `howone.public`.
+The public endpoint is controlled by `access.public.allowedFilters` and
+`access.public.requiredScopes`:
+
+```ts
+const result = await howone.public.entities.Story.query({
+  published: true,
+  page: { number: 1, size: 20 },
+  orderBy: { publishedAt: 'desc' },
+})
+```
+
 ### WhereInput — field operators
 
 ```ts
@@ -246,6 +284,18 @@ const result = await howone.entities.Story.query({
 })
 ```
 
+### Include relations
+
+`include` accepts a string or string array. All entities support `include: 'user'`.
+Entity-specific relation names must come from the manifest `relations` contract.
+
+```ts
+const result = await howone.entities.Story.query({
+  include: ['user', 'author'],
+  page: { number: 1, size: 20 },
+})
+```
+
 ---
 
 ## list() — Simple Array Read
@@ -268,6 +318,53 @@ const stories = await howone.entities.Story.list({ limit: 50, sort: 'title' })
 
 ---
 
+## Public Reads
+
+Use public reads for public lists and scoped public pages.
+
+```ts
+const articles = await howone.public.entities.Article.query({
+  published: true,
+  category: 'ai',
+  page: { number: 1, size: 20 },
+  orderBy: { publishedAt: 'desc' },
+})
+```
+
+For `access.public.read = "scoped"`, pass every required scope:
+
+```ts
+const profile = await howone.public.entities.QrProfile.queryScoped({
+  ownerId: ownerSharedUserId,
+  slug: 'wechat',
+  active: true,
+  limit: 1,
+})
+```
+
+Public query fields must be present in `access.public.allowedFilters`, and public sort
+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.
+
+---
+
+## Public Writes
+
+Only generate public writes when `access.public.create` / `access.public.update` allows
+them. Public create must include `created_by_user_id` unless the schema defines a
+different required owner scope.
+
+```ts
+await howone.public.entities.ContactMessage.create({
+  created_by_user_id: projectUserId,
+  name: 'Ada',
+  email: 'ada@example.com',
+  message: 'Please contact me',
+})
+```
+
+---
+
 ## Bulk Create
 
 ```ts

package/templates/vite/.howone/skills/howone-sdk/references/04-auth.md

@@ -45,10 +45,13 @@ import { HowOneAuthError } from '@howone/sdk'
 import howone from '@/lib/sdk'
 
 type UserProfile = {
-  id: string
+  id: string       // backend owner id; same as userId when JWT has userId
+  userId?: string  // authenticated backend user id when present in JWT
+  puid?: string    // public UUID; do not use as public ownerId scope
   email?: string
   name?: string
   avatarUrl?: string
+  appId?: string
   roles?: string[]
   metadata?: Record<string, unknown>
 }
@@ -66,6 +69,18 @@ const user = await howone.session.user()
 const user = await howone.me({ refresh: true })
 ```
 
+### Identity fields
+
+HowOne JWTs may contain both `userId` and `puid`. The SDK preserves both:
+
+- `user.id` / `user.userId` identifies the authenticated backend user.
+- `user.puid` is the public UUID and should not be used for entity owner filters.
+- `query.mine()` requires auth and lets the backend derive ownership from the JWT.
+
+For public share URLs that need scoped owner data, use `howone.public.entities.*`
+and pass the schema-required public scope, usually the shared owner id stored on a record.
+Do not pass `puid` as `ownerId`.
+
 ### Pattern: guard a page
 
 ```tsx

package/templates/vite/.howone/skills/howone-sdk/references/06-react-integration.md

@@ -31,18 +31,21 @@ import {
 
 Wrap your entire app. Provides auth, theme, and toast context to all children.
 
+`HowOneProvider` reads SDK environment and project defaults from `createClient`. Configure
+`projectId` and `env` once in `src/lib/sdk.ts`; do not pass a separate env to the provider.
+
 ```tsx
 // main.tsx or app/layout.tsx
 import React from 'react'
 import ReactDOM from 'react-dom/client'
 import { HowOneProvider } from '@howone/sdk/react'
+import './lib/sdk'
 import App from './App'
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <HowOneProvider
-      projectId={import.meta.env.VITE_HOWONE_PROJECT_ID}
-      auth="optional"
+      auth="required"
       brand="visible"
       theme="system"
     >
@@ -62,7 +65,7 @@ type HowOneBrandMode = 'visible' | 'hidden'
 interface HowOneProviderProps {
   children: React.ReactNode
 
-  // Project configuration (optional if createClient already set it)
+  // Optional override. Prefer configuring projectId once in createClient.
   projectId?: string
 
   // Auth behaviour
@@ -101,7 +104,7 @@ interface HowOneProviderProps {
 </HowOneProvider>
 
 // Dark mode forced
-<HowOneProvider auth="optional" theme="dark" forceTheme>
+<HowOneProvider auth="required" theme="dark" forceTheme>
   <App />
 </HowOneProvider>
 ```
@@ -115,10 +118,13 @@ Access auth state inside any component wrapped by `HowOneProvider`.
 ```ts
 type HowoneContextValue = {
   user: {
-    id: string
+    id: string       // backend owner id; same as userId when JWT has userId
+    userId?: string  // authenticated backend user id when present in JWT
+    puid?: string    // public UUID; do not use as public ownerId scope
     email: string
     name: string
     avatar: string
+    appId?: string
   } | null
   token: string | null
   isAuthenticated: boolean
@@ -323,6 +329,7 @@ import React from 'react'
 import ReactDOM from 'react-dom/client'
 import { HowOneProvider } from '@howone/sdk/react'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import './lib/sdk'
 import App from './App'
 
 const queryClient = new QueryClient()
@@ -330,8 +337,7 @@ const queryClient = new QueryClient()
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <HowOneProvider
-      projectId={import.meta.env.VITE_HOWONE_PROJECT_ID}
-      auth="optional"
+      auth="required"
       theme="system"
       brand="visible"
     >

package/templates/vite/.howone/skills/howone-sdk/references/08-manifest-codegen.md

@@ -62,9 +62,41 @@ Sync tools (`sync_schema_artifacts`, `sync_ai_artifacts`) write the manifests. T
 | `array` (items: object) | `Record<string, unknown>[]` or inline type |
 | `object` | `Record<string, unknown>` |
 | `enum` | `'value1' \| 'value2' \| ...` |
+| `["string", "null"]` | `string \| null` |
 
-- Fields in `required: true` are non-optional in `Record` and `Create` types.
-- Fields in `required: false` (or absent from required list) get `?` in `Record` and are optional in `Create`.
+- Fields in `required: true` are non-optional in `Record` types.
+- In `Create` types, required fields are required only when they do not have `default` or `autoGenerate`.
+- Fields with `default`, `defaultValue`, or `autoGenerate` are optional in `Create`.
+- Nullable fields include `null`.
+- System response fields are never generated into `Create` or `Update`.
+
+### Access-aware generated helpers
+
+Use the manifest `access` block to decide which namespace UI code should call:
+
+```ts
+export type ArticlePublicQuery = {
+  published?: boolean
+  category?: string
+  slug?: string
+  page?: { number?: number; size?: number }
+  orderBy?: { publishedAt?: 'asc' | 'desc'; updatedDate?: 'asc' | 'desc' }
+}
+
+const publicArticles = await howone.public.entities.Article.query({
+  published: true,
+  orderBy: { publishedAt: 'desc' },
+})
+```
+
+Rules:
+
+- `access.authenticated.*` drives `howone.entities.*`.
+- `access.public.read = "list"` allows `howone.public.entities.Entity.query`.
+- `access.public.read = "scoped"` requires `queryScoped` / `query.scoped` and all `requiredScopes`.
+- Public query types must include only `allowedFilters`, `allowedSorts`, `page`, `limit`, `search`, `include`, and `exactCount`.
+- Public create/update types should only be emitted when `access.public.create/update` is not `"none"`.
+- Public create must include `created_by_user_id` when the schema requires public owner assignment.
 
 ### Generated TypeScript from the example manifest
 
@@ -335,7 +367,9 @@ Before finalising generated code, verify:
 
 - [ ] Every entity from `.howone/database/manifest.json` has a `Record`, `Create`, and `Update` type
 - [ ] `Create` types are defined **explicitly** (not via `Omit`)
-- [ ] Optional fields match `required: false` in the manifest
+- [ ] Create optionality accounts for `required`, `default`, `defaultValue`, `autoGenerate`, and nullable types
+- [ ] System fields are not present in create/update input types
+- [ ] Public query/write types are generated only from `access.public.allowedFilters`, `allowedSorts`, `requiredScopes`, and write permissions
 - [ ] Every AI action from `.howone/ai/manifest.json` has an `inputSchema` zod object
 - [ ] Required input fields are not `.optional()` in zod
 - [ ] AI action names match the manifest `id` exactly (case-sensitive)

package/templates/vite/package.json

@@ -14,7 +14,7 @@
   "dependencies": {
     "@base-ui/react": "^1.4.1",
     "@fontsource-variable/inter": "^5.2.8",
-    "@howone/sdk": "2.0.0-beta.9",
+    "@howone/sdk": "2.0.0-beta.15",
     "@tailwindcss/vite": "^4.2.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/templates/vite/src/App.tsx

@@ -2,7 +2,7 @@ import { HowOneProvider } from '@howone/sdk/react'
 
 function App() {
   return (
-    <HowOneProvider auth="optional" brand="visible">
+    <HowOneProvider brand="visible">
       <div className="App">
         <h1>Hello HowOne</h1>
       </div>