howone 0.1.11 → 0.1.12

package/templates/vite/.howone/skills/howone-sdk/references/07-raw-http.md

@@ -0,0 +1,299 @@
+# Raw HTTP
+
+## When to Use
+
+Use `client.raw` when you need to call a custom backend endpoint that is **not** covered by `client.entities` or `client.ai`. The raw client is an Axios-based HTTP client that automatically attaches the HowOne auth token and project ID headers.
+
+**Do not use `client.raw` to re-implement entity operations or AI workflows** — use the typed SDK methods instead.
+
+---
+
+## The RawHttpClient Interface
+
+```ts
+type RawHttpClient = {
+  instance: AxiosInstance
+
+  // All methods return Promise<AxiosResponse>
+  request(config: RequestConfig): Promise<AxiosResponse>
+  get(config: RequestConfig): Promise<AxiosResponse>
+  post(config: RequestConfig): Promise<AxiosResponse>
+  put(config: RequestConfig): Promise<AxiosResponse>
+  patch(config: RequestConfig): Promise<AxiosResponse>
+  delete(config: RequestConfig): Promise<AxiosResponse>
+
+  // Cancel an in-flight request by URL
+  cancelRequest(url: string): void
+
+  // Cancel all in-flight requests
+  cancelAllRequests(): void
+}
+```
+
+### RequestConfig
+
+`RequestConfig` extends `AxiosRequestConfig` with optional interceptors:
+
+```ts
+type RequestConfig<T = AxiosResponse> = AxiosRequestConfig & {
+  interceptors?: {
+    requestInterceptor?: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig
+    requestInterceptorCatch?: (error: any) => any
+    responseInterceptor?: (res: T) => T
+    responseInterceptorCatch?: (error: any) => any
+  }
+  showLoading?: boolean
+}
+```
+
+---
+
+## Basic Usage
+
+```ts
+import howone from '@/lib/sdk'
+
+// GET
+const response = await howone.raw.get({
+  url: '/api/custom/stats',
+})
+const data = response.data  // untyped AxiosResponse.data
+
+// POST with body
+const response = await howone.raw.post({
+  url: '/api/custom/send-notification',
+  data: {
+    userId: '123',
+    message: 'Hello!',
+  },
+})
+
+// PUT
+const response = await howone.raw.put({
+  url: `/api/custom/profile/${userId}`,
+  data: { displayName: 'Alice' },
+})
+
+// PATCH
+const response = await howone.raw.patch({
+  url: `/api/custom/settings`,
+  data: { theme: 'dark' },
+})
+
+// DELETE
+const response = await howone.raw.delete({
+  url: `/api/custom/sessions/${sessionId}`,
+})
+```
+
+---
+
+## Typed Responses
+
+Wrap with generics for type safety:
+
+```ts
+type StatsResponse = {
+  totalUsers: number
+  activeToday: number
+  storageUsed: number
+}
+
+const response = await howone.raw.get<StatsResponse>({
+  url: '/api/custom/stats',
+})
+
+const stats = response.data  // typed as StatsResponse
+```
+
+---
+
+## Query Parameters
+
+```ts
+// Pass query params via the `params` field (Axios serializes them automatically)
+const response = await howone.raw.get({
+  url: '/api/custom/search',
+  params: {
+    q: 'dragons',
+    page: 1,
+    limit: 20,
+    sort: 'createdAt',
+    order: 'desc',
+  },
+})
+// Calls: GET /api/custom/search?q=dragons&page=1&limit=20&sort=createdAt&order=desc
+```
+
+---
+
+## Custom Headers
+
+```ts
+const response = await howone.raw.post({
+  url: '/api/custom/webhook',
+  data: payload,
+  headers: {
+    'X-Webhook-Secret': import.meta.env.VITE_WEBHOOK_SECRET,
+    'X-Request-Source': 'app',
+  },
+})
+```
+
+---
+
+## Request Cancellation
+
+```ts
+// Cancel a specific request by URL
+howone.raw.cancelRequest('/api/custom/long-running')
+
+// Cancel all in-flight requests (e.g. on page unmount)
+howone.raw.cancelAllRequests()
+
+// Pattern: cancel on component unmount
+import { useEffect } from 'react'
+import howone from '@/lib/sdk'
+
+function DataComponent() {
+  useEffect(() => {
+    howone.raw.get({ url: '/api/custom/data' })
+      .then(res => setData(res.data))
+
+    return () => {
+      howone.raw.cancelRequest('/api/custom/data')
+    }
+  }, [])
+}
+```
+
+---
+
+## Per-Request Interceptors
+
+For one-off request/response transforms without modifying the global client:
+
+```ts
+const response = await howone.raw.post({
+  url: '/api/custom/transform',
+  data: payload,
+  interceptors: {
+    requestInterceptor: (config) => {
+      // Modify request config (e.g. add timestamp)
+      config.headers['X-Timestamp'] = Date.now().toString()
+      return config
+    },
+    responseInterceptor: (res) => {
+      // Log response time or transform data
+      console.log('Response status:', res.status)
+      return res
+    },
+    responseInterceptorCatch: (error) => {
+      // Handle specific error codes
+      if (error.response?.status === 503) {
+        console.error('Service temporarily unavailable')
+      }
+      return Promise.reject(error)
+    },
+  },
+})
+```
+
+---
+
+## Direct Axios Instance Access
+
+For maximum control (multipart forms, streaming responses, etc.):
+
+```ts
+const instance = howone.raw.instance  // Axios instance
+
+// Multipart form data
+const formData = new FormData()
+formData.append('report', file)
+formData.append('meta', JSON.stringify({ type: 'monthly' }))
+
+const response = await instance.post('/api/custom/reports', formData, {
+  headers: { 'Content-Type': 'multipart/form-data' },
+  onUploadProgress: (e) => {
+    const percent = Math.round((e.loaded * 100) / (e.total ?? 1))
+    setProgress(percent)
+  },
+})
+```
+
+---
+
+## React Pattern: Data Fetching with Raw HTTP
+
+```tsx
+import { useEffect, useState } from 'react'
+import howone from '@/lib/sdk'
+
+type AnalyticsData = {
+  views: number
+  clicks: number
+  conversions: number
+  period: string
+}
+
+function Analytics({ projectId }: { projectId: string }) {
+  const [data, setData] = useState<AnalyticsData | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+
+    howone.raw.get<AnalyticsData>({
+      url: '/api/custom/analytics',
+      params: { projectId, period: '30d' },
+    })
+      .then(res => { if (!cancelled) setData(res.data) })
+      .catch(err => { if (!cancelled) setError(err.message) })
+      .finally(() => { if (!cancelled) setLoading(false) })
+
+    return () => {
+      cancelled = true
+      howone.raw.cancelRequest('/api/custom/analytics')
+    }
+  }, [projectId])
+
+  if (loading) return <div>Loading analytics...</div>
+  if (error) return <div>Error: {error}</div>
+  if (!data) return null
+
+  return (
+    <div>
+      <p>Views: {data.views}</p>
+      <p>Clicks: {data.clicks}</p>
+      <p>Conversions: {data.conversions}</p>
+    </div>
+  )
+}
+```
+
+---
+
+## client.raw vs client.entities
+
+| Use Case | Recommended API |
+|---|---|
+| CRUD on a HowOne entity | `howone.entities.<Entity>.*` |
+| Querying with pagination/filter/sort | `howone.entities.<Entity>.query()` |
+| Running an AI workflow | `howone.ai.<action>.run()` |
+| Calling a custom backend route | `howone.raw.get/post/...` |
+| Sending webhooks or notifications | `howone.raw.post()` |
+| Fetching analytics or aggregated data not in entities | `howone.raw.get()` |
+| Uploading files | `howone.upload.*` |
+
+---
+
+## Common Mistakes
+
+| Mistake | Correct Pattern |
+|---|---|
+| `howone.raw.get({ url: '/entities/Story' })` to read entities | Use `howone.entities.Story.query()` |
+| Not handling Axios errors (`.response.status`) | Wrap in try/catch and check `error.response?.status` |
+| Calling `cancelAllRequests()` too broadly | Use `cancelRequest(url)` for surgical cancellation |
+| Forgetting that `response.data` is untyped by default | Pass the type parameter: `howone.raw.get<MyType>(...)` |

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

@@ -0,0 +1,400 @@
+# Manifest Codegen
+
+## Overview
+
+HowOne apps are driven by two backend-synced manifests:
+
+| File | Contents | Drives |
+|---|---|---|
+| `.howone/database/manifest.json` | Entity names, fields, types | Entity type definitions + `client.entity<...>` bindings |
+| `.howone/ai/manifest.json` | AI action IDs, input/output JSON schemas | zod schemas + `defineAiAction` bindings |
+
+**The coding agent should always generate `src/lib/sdk.ts` from these manifest files, not from memory or assumptions.**
+
+Sync tools (`sync_schema_artifacts`, `sync_ai_artifacts`) write the manifests. The coding agent reads the manifests and writes `src/lib/sdk.ts`.
+
+---
+
+## Reading `.howone/database/manifest.json`
+
+### Example manifest
+
+```json
+{
+  "version": "1",
+  "entities": [
+    {
+      "name": "Story",
+      "fields": [
+        { "name": "title", "type": "string", "required": true },
+        { "name": "content", "type": "text", "required": true },
+        { "name": "authorId", "type": "string", "required": true },
+        { "name": "status", "type": "string", "required": true, "enum": ["draft", "published", "archived"] },
+        { "name": "wordCount", "type": "integer", "required": true },
+        { "name": "tags", "type": "array", "items": "string", "required": false },
+        { "name": "coverUrl", "type": "string", "required": false }
+      ]
+    },
+    {
+      "name": "Comment",
+      "fields": [
+        { "name": "storyId", "type": "string", "required": true },
+        { "name": "authorId", "type": "string", "required": true },
+        { "name": "body", "type": "text", "required": true },
+        { "name": "likes", "type": "integer", "required": false }
+      ]
+    }
+  ]
+}
+```
+
+### Field type → TypeScript type mapping
+
+| Manifest type | TypeScript type |
+|---|---|
+| `string` | `string` |
+| `text` | `string` |
+| `integer` | `number` |
+| `number` / `float` | `number` |
+| `boolean` | `boolean` |
+| `date` / `datetime` | `string` (ISO 8601) |
+| `array` (items: string) | `string[]` |
+| `array` (items: object) | `Record<string, unknown>[]` or inline type |
+| `object` | `Record<string, unknown>` |
+| `enum` | `'value1' \| 'value2' \| ...` |
+
+- 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`.
+
+### Generated TypeScript from the example manifest
+
+```ts
+import { type EntityRecord } from '@howone/sdk'
+
+// ── Story ─────────────────────────────────────────────────────
+export type StoryRecord = EntityRecord & {
+  title: string
+  content: string
+  authorId: string
+  status: 'draft' | 'published' | 'archived'
+  wordCount: number
+  tags?: string[]
+  coverUrl?: string
+}
+
+export type StoryCreate = {
+  title: string
+  content: string
+  authorId: string
+  status: 'draft' | 'published' | 'archived'
+  wordCount: number
+  tags?: string[]
+  coverUrl?: string
+}
+
+export type StoryUpdate = Partial<StoryCreate>
+
+// ── Comment ───────────────────────────────────────────────────
+export type CommentRecord = EntityRecord & {
+  storyId: string
+  authorId: string
+  body: string
+  likes?: number
+}
+
+export type CommentCreate = {
+  storyId: string
+  authorId: string
+  body: string
+  likes?: number
+}
+
+export type CommentUpdate = Partial<CommentCreate>
+```
+
+---
+
+## Reading `.howone/ai/manifest.json`
+
+### Example manifest
+
+```json
+{
+  "version": "1",
+  "actions": [
+    {
+      "id": "generateStory",
+      "name": "Generate Story",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "topic": { "type": "string" },
+          "ageRange": { "type": "string", "enum": ["3-5", "6-8", "9-12"] },
+          "language": { "type": "string" }
+        },
+        "required": ["topic", "ageRange"]
+      },
+      "outputSchema": {
+        "type": "object",
+        "properties": {
+          "title": { "type": "string" },
+          "content": { "type": "string" },
+          "summary": { "type": "string" }
+        },
+        "required": ["title", "content"]
+      }
+    },
+    {
+      "id": "translateText",
+      "name": "Translate Text",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "text": { "type": "string" },
+          "targetLang": { "type": "string" },
+          "formality": { "type": "string", "enum": ["formal", "informal"] }
+        },
+        "required": ["text", "targetLang"]
+      }
+    }
+  ]
+}
+```
+
+### JSON Schema → zod mapping
+
+| JSON Schema | zod |
+|---|---|
+| `{ "type": "string" }` | `z.string()` |
+| `{ "type": "number" }` | `z.number()` |
+| `{ "type": "integer" }` | `z.number().int()` |
+| `{ "type": "boolean" }` | `z.boolean()` |
+| `{ "type": "string", "enum": ["a","b"] }` | `z.enum(['a', 'b'])` |
+| `{ "type": "array", "items": { "type": "string" } }` | `z.array(z.string())` |
+| `{ "type": "object", "properties": { ... } }` | `z.object({ ... })` |
+| Field NOT in `required[]` | append `.optional()` |
+
+### Generated zod schemas from the example manifest
+
+```ts
+import { z } from 'zod'
+
+// ── generateStory ─────────────────────────────────────────────
+export const generateStoryInputSchema = z.object({
+  topic: z.string(),
+  ageRange: z.enum(['3-5', '6-8', '9-12']),
+  language: z.string().optional(),
+})
+export type GenerateStoryInput = z.infer<typeof generateStoryInputSchema>
+
+// Output type for manual unwrapping (do NOT put in defineAiAction as outputSchema)
+export type GenerateStoryOutput = {
+  title: string
+  content: string
+  summary?: string
+}
+
+// ── translateText ─────────────────────────────────────────────
+export const translateTextInputSchema = z.object({
+  text: z.string(),
+  targetLang: z.string(),
+  formality: z.enum(['formal', 'informal']).optional(),
+})
+export type TranslateTextInput = z.infer<typeof translateTextInputSchema>
+```
+
+---
+
+## Full Generated `src/lib/sdk.ts`
+
+Combining both manifests from the examples above:
+
+```ts
+// src/lib/sdk.ts
+// Generated from .howone/database/manifest.json and .howone/ai/manifest.json
+import {
+  createClient,
+  defineAiAction,
+  defineAiActions,
+  defineEntities,
+  type EntityRecord,
+  withAiActions,
+  withEntities,
+} from '@howone/sdk'
+import { z } from 'zod'
+
+// ═══════════════════════════════════════════════════════════════
+// ENTITY TYPES
+// ═══════════════════════════════════════════════════════════════
+
+export type StoryRecord = EntityRecord & {
+  title: string
+  content: string
+  authorId: string
+  status: 'draft' | 'published' | 'archived'
+  wordCount: number
+  tags?: string[]
+  coverUrl?: string
+}
+export type StoryCreate = {
+  title: string
+  content: string
+  authorId: string
+  status: 'draft' | 'published' | 'archived'
+  wordCount: number
+  tags?: string[]
+  coverUrl?: string
+}
+export type StoryUpdate = Partial<StoryCreate>
+
+export type CommentRecord = EntityRecord & {
+  storyId: string
+  authorId: string
+  body: string
+  likes?: number
+}
+export type CommentCreate = {
+  storyId: string
+  authorId: string
+  body: string
+  likes?: number
+}
+export type CommentUpdate = Partial<CommentCreate>
+
+// ═══════════════════════════════════════════════════════════════
+// AI SCHEMAS & TYPES
+// ═══════════════════════════════════════════════════════════════
+
+export const generateStoryInputSchema = z.object({
+  topic: z.string(),
+  ageRange: z.enum(['3-5', '6-8', '9-12']),
+  language: z.string().optional(),
+})
+export type GenerateStoryInput = z.infer<typeof generateStoryInputSchema>
+export type GenerateStoryOutput = {
+  title: string
+  content: string
+  summary?: string
+}
+
+export const translateTextInputSchema = z.object({
+  text: z.string(),
+  targetLang: z.string(),
+  formality: z.enum(['formal', 'informal']).optional(),
+})
+export type TranslateTextInput = z.infer<typeof translateTextInputSchema>
+export type TranslateTextOutput = {
+  translatedText: string
+  detectedLang?: string
+}
+
+// ═══════════════════════════════════════════════════════════════
+// CLIENT
+// ═══════════════════════════════════════════════════════════════
+
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+})
+
+// ═══════════════════════════════════════════════════════════════
+// ENTITY BINDINGS
+// ═══════════════════════════════════════════════════════════════
+
+export const entities = defineEntities({
+  Story: client.entity<StoryRecord, StoryCreate, StoryUpdate>('Story'),
+  Comment: client.entity<CommentRecord, CommentCreate, CommentUpdate>('Comment'),
+})
+
+// ═══════════════════════════════════════════════════════════════
+// AI ACTION BINDINGS
+// ═══════════════════════════════════════════════════════════════
+
+export const ai = defineAiActions({
+  generateStory: defineAiAction('generateStory', {
+    inputSchema: generateStoryInputSchema,
+  }),
+  translateText: defineAiAction('translateText', {
+    inputSchema: translateTextInputSchema,
+  }),
+})
+
+// ═══════════════════════════════════════════════════════════════
+// COMPOSED CLIENT
+// ═══════════════════════════════════════════════════════════════
+
+const howone = withAiActions(withEntities(client, entities), ai)
+export default howone
+```
+
+---
+
+## Codegen Checklist
+
+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
+- [ ] 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)
+- [ ] `createClient` uses `import.meta.env.*` only
+- [ ] `withEntities` is applied before `withAiActions` in the composition chain
+- [ ] No generated source files are placed under `.howone/`
+- [ ] Exported types and schemas are importable from `@/lib/sdk`
+
+---
+
+## Incremental Update Pattern
+
+When new entities or actions are added to the manifests, update `src/lib/sdk.ts` by:
+
+1. Reading the current `src/lib/sdk.ts` to preserve existing bindings and import style.
+2. Appending new types, schemas, entity bindings, and action bindings.
+3. Not removing existing bindings unless the manifest explicitly removed them.
+4. Preserving export names for backward compatibility with existing UI code.
+
+```ts
+// Before (existing)
+export const entities = defineEntities({
+  Story: client.entity<StoryRecord, StoryCreate, StoryUpdate>('Story'),
+})
+
+// After (added Comment entity from new manifest)
+export const entities = defineEntities({
+  Story: client.entity<StoryRecord, StoryCreate, StoryUpdate>('Story'),
+  Comment: client.entity<CommentRecord, CommentCreate, CommentUpdate>('Comment'),
+})
+```
+
+---
+
+## AI-First Persistence Pattern
+
+When the app generates data with AI and saves it to an entity:
+
+1. Read `.howone/ai/manifest.json` → determine AI output shape.
+2. Define entity fields that mirror the AI output fields.
+3. Add any app-specific metadata fields (status, userId, createdAt, etc.).
+4. Generate the entity type, then the AI action binding.
+
+```ts
+// AI generates: { title: string, content: string, summary: string }
+// Save it to Story entity which adds: authorId, status, wordCount
+
+async function generateAndSave(input: GenerateStoryInput, authorId: string) {
+  const result = await howone.ai.generateStory.run(input)
+  if (!result.success) throw new Error(result.errors.join(', '))
+
+  const output = result.finalResult as GenerateStoryOutput
+
+  return howone.entities.Story.create({
+    title: output.title,
+    content: output.content,
+    authorId,
+    status: 'draft',
+    wordCount: output.content.split(' ').length,
+  })
+}
+```