@howone/agent-cli 0.0.0-stage → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (228) hide show
  1. package/README.md +49 -2
  2. package/bin/index.d.mts +1 -0
  3. package/bin/index.mjs +2397 -0
  4. package/package.json +55 -4
  5. package/skills/howone/01-apps.md +29 -0
  6. package/skills/howone/02-develop.md +107 -0
  7. package/skills/howone/03-workflows.md +71 -0
  8. package/skills/howone/04-functions-and-data.md +41 -0
  9. package/skills/howone/05-capabilities.md +46 -0
  10. package/skills/howone/SKILL.md +52 -0
  11. package/templates/vite/.howone/skills/hallmark/SKILL.md +557 -0
  12. package/templates/vite/.howone/skills/hallmark/references/anti-patterns.md +418 -0
  13. package/templates/vite/.howone/skills/hallmark/references/assets.md +406 -0
  14. package/templates/vite/.howone/skills/hallmark/references/color.md +95 -0
  15. package/templates/vite/.howone/skills/hallmark/references/component-cookbook.md +265 -0
  16. package/templates/vite/.howone/skills/hallmark/references/components/c1-outlined-chip.md +12 -0
  17. package/templates/vite/.howone/skills/hallmark/references/components/c2-inline-form-as-cta.md +16 -0
  18. package/templates/vite/.howone/skills/hallmark/references/components/c3-typographic-link.md +8 -0
  19. package/templates/vite/.howone/skills/hallmark/references/components/c4-sticky-bottom-bar.md +16 -0
  20. package/templates/vite/.howone/skills/hallmark/references/components/f1-bento-grid.md +20 -0
  21. package/templates/vite/.howone/skills/hallmark/references/components/f2-sticky-scroll-stack.md +20 -0
  22. package/templates/vite/.howone/skills/hallmark/references/components/f3-tabular-spec-sheet.md +11 -0
  23. package/templates/vite/.howone/skills/hallmark/references/components/f4-step-sequence.md +11 -0
  24. package/templates/vite/.howone/skills/hallmark/references/components/f5-annotated-screenshot.md +11 -0
  25. package/templates/vite/.howone/skills/hallmark/references/components/f6-product-card-grid.md +41 -0
  26. package/templates/vite/.howone/skills/hallmark/references/components/ft1-mast-headed.md +13 -0
  27. package/templates/vite/.howone/skills/hallmark/references/components/ft2-inline-rule-single-line.md +10 -0
  28. package/templates/vite/.howone/skills/hallmark/references/components/ft3-index-style-category-list.md +12 -0
  29. package/templates/vite/.howone/skills/hallmark/references/components/ft4-dense-typographic.md +10 -0
  30. package/templates/vite/.howone/skills/hallmark/references/components/ft5-statement.md +21 -0
  31. package/templates/vite/.howone/skills/hallmark/references/components/ft6-letter-close.md +19 -0
  32. package/templates/vite/.howone/skills/hallmark/references/components/ft7-newsletter-first.md +27 -0
  33. package/templates/vite/.howone/skills/hallmark/references/components/ft8-marquee-scroll.md +25 -0
  34. package/templates/vite/.howone/skills/hallmark/references/components/h1-marquee.md +15 -0
  35. package/templates/vite/.howone/skills/hallmark/references/components/h2-split-diptych.md +15 -0
  36. package/templates/vite/.howone/skills/hallmark/references/components/h3-quote-led.md +11 -0
  37. package/templates/vite/.howone/skills/hallmark/references/components/h4-stat-led.md +14 -0
  38. package/templates/vite/.howone/skills/hallmark/references/components/h5-letter-hero.md +11 -0
  39. package/templates/vite/.howone/skills/hallmark/references/components/h6-photographic-fold.md +16 -0
  40. package/templates/vite/.howone/skills/hallmark/references/components/h7-demo-video-clipped-by-viewport-edge.md +27 -0
  41. package/templates/vite/.howone/skills/hallmark/references/components/h8-mockup-split-browser-framed.md +23 -0
  42. package/templates/vite/.howone/skills/hallmark/references/components/h9-custom-illustration-centerpiece.md +27 -0
  43. package/templates/vite/.howone/skills/hallmark/references/components/n1-wordmark-2-links.md +12 -0
  44. package/templates/vite/.howone/skills/hallmark/references/components/n10-floating-on-scroll-morph.md +19 -0
  45. package/templates/vite/.howone/skills/hallmark/references/components/n11-mega-menu.md +40 -0
  46. package/templates/vite/.howone/skills/hallmark/references/components/n12-banner-retract.md +34 -0
  47. package/templates/vite/.howone/skills/hallmark/references/components/n13-inline-cmdk-pill.md +39 -0
  48. package/templates/vite/.howone/skills/hallmark/references/components/n1b-saas-three-section.md +35 -0
  49. package/templates/vite/.howone/skills/hallmark/references/components/n2-floating-chip.md +14 -0
  50. package/templates/vite/.howone/skills/hallmark/references/components/n3-side-rail.md +14 -0
  51. package/templates/vite/.howone/skills/hallmark/references/components/n4-hidden-behind-k.md +9 -0
  52. package/templates/vite/.howone/skills/hallmark/references/components/n5-floating-pill.md +28 -0
  53. package/templates/vite/.howone/skills/hallmark/references/components/n6-newspaper-masthead.md +24 -0
  54. package/templates/vite/.howone/skills/hallmark/references/components/n7-brutal-slab.md +22 -0
  55. package/templates/vite/.howone/skills/hallmark/references/components/n8-terminal-command.md +21 -0
  56. package/templates/vite/.howone/skills/hallmark/references/components/n9-edge-aligned-minimal.md +17 -0
  57. package/templates/vite/.howone/skills/hallmark/references/components/s1-left-margin-numbered.md +15 -0
  58. package/templates/vite/.howone/skills/hallmark/references/components/s2-hanging.md +13 -0
  59. package/templates/vite/.howone/skills/hallmark/references/components/s3-sticky-pinned.md +19 -0
  60. package/templates/vite/.howone/skills/hallmark/references/components/s4-inline-no-break.md +11 -0
  61. package/templates/vite/.howone/skills/hallmark/references/components/s5-bottom-anchored.md +13 -0
  62. package/templates/vite/.howone/skills/hallmark/references/components/t1-pull-quote-with-marginalia.md +12 -0
  63. package/templates/vite/.howone/skills/hallmark/references/components/t2-logo-wall-hairline.md +19 -0
  64. package/templates/vite/.howone/skills/hallmark/references/components/t3-single-huge-quote.md +11 -0
  65. package/templates/vite/.howone/skills/hallmark/references/components/t4-numbered-stat-strip.md +14 -0
  66. package/templates/vite/.howone/skills/hallmark/references/contract.md +24 -0
  67. package/templates/vite/.howone/skills/hallmark/references/copy.md +182 -0
  68. package/templates/vite/.howone/skills/hallmark/references/custom-craft.md +626 -0
  69. package/templates/vite/.howone/skills/hallmark/references/custom-theme.md +367 -0
  70. package/templates/vite/.howone/skills/hallmark/references/design-md.md +116 -0
  71. package/templates/vite/.howone/skills/hallmark/references/export-formats.md +328 -0
  72. package/templates/vite/.howone/skills/hallmark/references/floating-nav.md +89 -0
  73. package/templates/vite/.howone/skills/hallmark/references/genres/atmospheric.md +69 -0
  74. package/templates/vite/.howone/skills/hallmark/references/genres/editorial.md +72 -0
  75. package/templates/vite/.howone/skills/hallmark/references/genres/modern-minimal.md +71 -0
  76. package/templates/vite/.howone/skills/hallmark/references/genres/playful.md +70 -0
  77. package/templates/vite/.howone/skills/hallmark/references/hero-enrichment.md +475 -0
  78. package/templates/vite/.howone/skills/hallmark/references/imagery-kit.md +170 -0
  79. package/templates/vite/.howone/skills/hallmark/references/interaction-and-states.md +208 -0
  80. package/templates/vite/.howone/skills/hallmark/references/layout-and-space.md +112 -0
  81. package/templates/vite/.howone/skills/hallmark/references/macrostructures/01-bento-grid.md +35 -0
  82. package/templates/vite/.howone/skills/hallmark/references/macrostructures/02-long-document.md +34 -0
  83. package/templates/vite/.howone/skills/hallmark/references/macrostructures/03-marquee-hero.md +31 -0
  84. package/templates/vite/.howone/skills/hallmark/references/macrostructures/04-stat-led.md +34 -0
  85. package/templates/vite/.howone/skills/hallmark/references/macrostructures/05-workbench.md +32 -0
  86. package/templates/vite/.howone/skills/hallmark/references/macrostructures/06-conversational-faq.md +33 -0
  87. package/templates/vite/.howone/skills/hallmark/references/macrostructures/07-manifesto.md +32 -0
  88. package/templates/vite/.howone/skills/hallmark/references/macrostructures/08-photographic.md +34 -0
  89. package/templates/vite/.howone/skills/hallmark/references/macrostructures/09-quote-led.md +32 -0
  90. package/templates/vite/.howone/skills/hallmark/references/macrostructures/10-specimen.md +32 -0
  91. package/templates/vite/.howone/skills/hallmark/references/macrostructures/11-catalogue.md +23 -0
  92. package/templates/vite/.howone/skills/hallmark/references/macrostructures/12-letter.md +23 -0
  93. package/templates/vite/.howone/skills/hallmark/references/macrostructures/13-index-first.md +23 -0
  94. package/templates/vite/.howone/skills/hallmark/references/macrostructures/14-narrative-workflow.md +23 -0
  95. package/templates/vite/.howone/skills/hallmark/references/macrostructures/15-split-studio.md +23 -0
  96. package/templates/vite/.howone/skills/hallmark/references/macrostructures/16-feature-stack.md +23 -0
  97. package/templates/vite/.howone/skills/hallmark/references/macrostructures/17-type-specimen.md +23 -0
  98. package/templates/vite/.howone/skills/hallmark/references/macrostructures/18-portfolio-grid.md +23 -0
  99. package/templates/vite/.howone/skills/hallmark/references/macrostructures/19-map-diagram.md +23 -0
  100. package/templates/vite/.howone/skills/hallmark/references/macrostructures/20-ecosystem-index.md +23 -0
  101. package/templates/vite/.howone/skills/hallmark/references/macrostructures/21-component-playground.md +23 -0
  102. package/templates/vite/.howone/skills/hallmark/references/macrostructures.md +89 -0
  103. package/templates/vite/.howone/skills/hallmark/references/microinteractions.md +258 -0
  104. package/templates/vite/.howone/skills/hallmark/references/motion.md +109 -0
  105. package/templates/vite/.howone/skills/hallmark/references/preview-examples.md +49 -0
  106. package/templates/vite/.howone/skills/hallmark/references/responsive.md +138 -0
  107. package/templates/vite/.howone/skills/hallmark/references/slop-test.md +192 -0
  108. package/templates/vite/.howone/skills/hallmark/references/structure.md +160 -0
  109. package/templates/vite/.howone/skills/hallmark/references/study.md +509 -0
  110. package/templates/vite/.howone/skills/hallmark/references/themes/carnival.md +301 -0
  111. package/templates/vite/.howone/skills/hallmark/references/themes/cobalt.md +146 -0
  112. package/templates/vite/.howone/skills/hallmark/references/themes/hum.md +403 -0
  113. package/templates/vite/.howone/skills/hallmark/references/themes/lumen.md +478 -0
  114. package/templates/vite/.howone/skills/hallmark/references/typography.md +243 -0
  115. package/templates/vite/.howone/skills/hallmark/references/verbs/audit.md +25 -0
  116. package/templates/vite/.howone/skills/hallmark/references/verbs/redesign.md +269 -0
  117. package/templates/vite/.howone/skills/howone/01-architect/01-app-generation.md +209 -0
  118. package/templates/vite/.howone/skills/howone/01-architect/02-manifest-codegen.md +194 -0
  119. package/templates/vite/.howone/skills/howone/02-entity-schema/01-schema-design.md +523 -0
  120. package/templates/vite/.howone/skills/howone/02-entity-schema/02-schema-operations.md +329 -0
  121. package/templates/vite/.howone/skills/howone/02-entity-schema/03-access-models.md +151 -0
  122. package/templates/vite/.howone/skills/howone/02-entity-schema/04-query-contracts.md +123 -0
  123. package/templates/vite/.howone/skills/howone/02-entity-schema/05-ai-persistence-patterns.md +255 -0
  124. package/templates/vite/.howone/skills/howone/03-ai-capabilities/01-ai-capability-architecture.md +215 -0
  125. package/templates/vite/.howone/skills/howone/03-ai-capabilities/02-workflow-contract-rules.md +427 -0
  126. package/templates/vite/.howone/skills/howone/03-ai-capabilities/03-service-capability-catalog.md +304 -0
  127. package/templates/vite/.howone/skills/howone/03-ai-capabilities/04-workflow-operations.md +164 -0
  128. package/templates/vite/.howone/skills/howone/03-ai-capabilities/05-ai-feature-playbooks.md +275 -0
  129. package/templates/vite/.howone/skills/howone/04-app-sdk/01-client-setup.md +162 -0
  130. package/templates/vite/.howone/skills/howone/04-app-sdk/02-entity-operations.md +163 -0
  131. package/templates/vite/.howone/skills/howone/04-app-sdk/03-auth.md +418 -0
  132. package/templates/vite/.howone/skills/howone/04-app-sdk/04-react-integration.md +138 -0
  133. package/templates/vite/.howone/skills/howone/04-app-sdk/05-file-upload.md +112 -0
  134. package/templates/vite/.howone/skills/howone/04-app-sdk/06-raw-http.md +128 -0
  135. package/templates/vite/.howone/skills/howone/04-app-sdk/07-ai-action-calls.md +210 -0
  136. package/templates/vite/.howone/skills/howone/04-app-sdk/08-ai-manifest-handoff.md +90 -0
  137. package/templates/vite/.howone/skills/howone/04-app-sdk/09-extension-boundaries.md +226 -0
  138. package/templates/vite/.howone/skills/howone/04-app-sdk/10-workflow-execute-sse.md +138 -0
  139. package/templates/vite/.howone/skills/howone/04-app-sdk/11-entity-data-access-patterns.md +310 -0
  140. package/templates/vite/.howone/skills/howone/04-app-sdk/12-query-dsl-and-responses.md +237 -0
  141. package/templates/vite/.howone/skills/howone/04-app-sdk/13-credits.md +31 -0
  142. package/templates/vite/.howone/skills/howone/SKILL.md +256 -0
  143. package/templates/vite/.howone/skills/howone/agents/openai.yaml +4 -0
  144. package/templates/vite/.howone/skills/howone/references/audio-generation.md +30 -0
  145. package/templates/vite/.howone/skills/howone/references/audio-recognition.md +30 -0
  146. package/templates/vite/.howone/skills/howone/references/common-errors.md +27 -0
  147. package/templates/vite/.howone/skills/howone/references/finance.md +28 -0
  148. package/templates/vite/.howone/skills/howone/references/image-editing.md +30 -0
  149. package/templates/vite/.howone/skills/howone/references/image-generation.md +30 -0
  150. package/templates/vite/.howone/skills/howone/references/version-evidence.md +47 -0
  151. package/templates/vite/.howone/skills/howone/references/video-generation.md +35 -0
  152. package/templates/vite/.howone/skills/howone/scripts/verify-project.mjs +151 -0
  153. package/templates/vite/.prettierignore +7 -0
  154. package/templates/vite/.prettierrc +11 -0
  155. package/templates/vite/AGENTS.md +87 -0
  156. package/templates/vite/README.md +21 -0
  157. package/templates/vite/components.json +25 -0
  158. package/templates/vite/eslint.config.js +23 -0
  159. package/templates/vite/index.html +12 -0
  160. package/templates/vite/package.json +58 -0
  161. package/templates/vite/public/vite.svg +1 -0
  162. package/templates/vite/src/App.tsx +17 -0
  163. package/templates/vite/src/assets/react.svg +1 -0
  164. package/templates/vite/src/components/theme-provider.tsx +230 -0
  165. package/templates/vite/src/components/ui/accordion.tsx +79 -0
  166. package/templates/vite/src/components/ui/alert-dialog.tsx +197 -0
  167. package/templates/vite/src/components/ui/alert.tsx +76 -0
  168. package/templates/vite/src/components/ui/aspect-ratio.tsx +11 -0
  169. package/templates/vite/src/components/ui/avatar.tsx +110 -0
  170. package/templates/vite/src/components/ui/badge.tsx +49 -0
  171. package/templates/vite/src/components/ui/breadcrumb.tsx +122 -0
  172. package/templates/vite/src/components/ui/button-group.tsx +83 -0
  173. package/templates/vite/src/components/ui/button.tsx +67 -0
  174. package/templates/vite/src/components/ui/calendar.tsx +222 -0
  175. package/templates/vite/src/components/ui/card.tsx +103 -0
  176. package/templates/vite/src/components/ui/carousel.tsx +240 -0
  177. package/templates/vite/src/components/ui/chart.tsx +373 -0
  178. package/templates/vite/src/components/ui/checkbox.tsx +31 -0
  179. package/templates/vite/src/components/ui/collapsible.tsx +33 -0
  180. package/templates/vite/src/components/ui/combobox.tsx +299 -0
  181. package/templates/vite/src/components/ui/command.tsx +193 -0
  182. package/templates/vite/src/components/ui/context-menu.tsx +261 -0
  183. package/templates/vite/src/components/ui/dialog.tsx +168 -0
  184. package/templates/vite/src/components/ui/direction.tsx +22 -0
  185. package/templates/vite/src/components/ui/drawer.tsx +132 -0
  186. package/templates/vite/src/components/ui/dropdown-menu.tsx +269 -0
  187. package/templates/vite/src/components/ui/empty.tsx +104 -0
  188. package/templates/vite/src/components/ui/field.tsx +238 -0
  189. package/templates/vite/src/components/ui/hover-card.tsx +42 -0
  190. package/templates/vite/src/components/ui/input-group.tsx +154 -0
  191. package/templates/vite/src/components/ui/input-otp.tsx +87 -0
  192. package/templates/vite/src/components/ui/input.tsx +19 -0
  193. package/templates/vite/src/components/ui/item.tsx +196 -0
  194. package/templates/vite/src/components/ui/kbd.tsx +26 -0
  195. package/templates/vite/src/components/ui/label.tsx +22 -0
  196. package/templates/vite/src/components/ui/menubar.tsx +280 -0
  197. package/templates/vite/src/components/ui/native-select.tsx +61 -0
  198. package/templates/vite/src/components/ui/navigation-menu.tsx +164 -0
  199. package/templates/vite/src/components/ui/pagination.tsx +129 -0
  200. package/templates/vite/src/components/ui/popover.tsx +87 -0
  201. package/templates/vite/src/components/ui/progress.tsx +31 -0
  202. package/templates/vite/src/components/ui/radio-group.tsx +42 -0
  203. package/templates/vite/src/components/ui/resizable.tsx +50 -0
  204. package/templates/vite/src/components/ui/scroll-area.tsx +53 -0
  205. package/templates/vite/src/components/ui/select.tsx +192 -0
  206. package/templates/vite/src/components/ui/separator.tsx +26 -0
  207. package/templates/vite/src/components/ui/sheet.tsx +145 -0
  208. package/templates/vite/src/components/ui/sidebar.tsx +700 -0
  209. package/templates/vite/src/components/ui/skeleton.tsx +13 -0
  210. package/templates/vite/src/components/ui/slider.tsx +59 -0
  211. package/templates/vite/src/components/ui/sonner.tsx +47 -0
  212. package/templates/vite/src/components/ui/spinner.tsx +10 -0
  213. package/templates/vite/src/components/ui/switch.tsx +33 -0
  214. package/templates/vite/src/components/ui/table.tsx +114 -0
  215. package/templates/vite/src/components/ui/tabs.tsx +90 -0
  216. package/templates/vite/src/components/ui/textarea.tsx +18 -0
  217. package/templates/vite/src/components/ui/toggle-group.tsx +89 -0
  218. package/templates/vite/src/components/ui/toggle.tsx +45 -0
  219. package/templates/vite/src/components/ui/tooltip.tsx +57 -0
  220. package/templates/vite/src/hooks/use-mobile.ts +19 -0
  221. package/templates/vite/src/index.css +133 -0
  222. package/templates/vite/src/lib/sdk.ts +34 -0
  223. package/templates/vite/src/lib/utils.ts +6 -0
  224. package/templates/vite/src/main.tsx +14 -0
  225. package/templates/vite/tsconfig.app.json +32 -0
  226. package/templates/vite/tsconfig.json +13 -0
  227. package/templates/vite/tsconfig.node.json +26 -0
  228. package/templates/vite/vite.config.ts +14 -0
@@ -0,0 +1,138 @@
1
+ # Workflow Execute SSE
2
+
3
+ Use this reference when an app needs live workflow progress, cancellation, or raw event iteration.
4
+ For ordinary AI actions, start with `07-ai-action-calls.md` and use the typed action methods.
5
+
6
+ ## Environment and endpoint
7
+
8
+ The SDK chooses the EAX base from `createClient({ env })`:
9
+
10
+ | `env` | EAX base |
11
+ |---|---|
12
+ | `local` | `http://eax-dev-orchestrator.default.svc.cluster.local` |
13
+ | `dev` | `http://eax-dev-orchestrator.default.svc.cluster.local` |
14
+ | `prod` | `https://eax-backend-orchestrator-prod.fly.dev` |
15
+
16
+ Do not construct this URL in app code or override it with `aiUrl`. A workflow action calls:
17
+
18
+ ```text
19
+ POST {eaxBase}/workflow/execute/{projectId}/{workflowId}
20
+ ```
21
+
22
+ The request body is `{ inputs: {}, priority?: 'low' | 'normal' | 'high' }` and carries the current
23
+ client token as `Authorization: Bearer ...`.
24
+
25
+ ## Wire protocol
26
+
27
+ Frames are JSON `data:` lines separated by a blank line. The JSON envelope owns the ID and event
28
+ name; there are no separate legacy SSE `id:` or `event:` lines:
29
+
30
+ ```text
31
+ data: {"id":"evt_1","event":"run_start","message":"execution with sse is started"}
32
+
33
+ data: {"id":"evt_2","event":"progress","message":"[DISPLAY] Executing node: Extract"}
34
+
35
+ data: {"id":"evt_3","event":"run_complete","message":{"imageUrl":"https://..."}}
36
+ ```
37
+
38
+ ```ts
39
+ type WorkflowSseEnvelope = {
40
+ id: string
41
+ event: 'run_start' | 'progress' | 'run_complete' | 'run_error' | 'credit_insufficient'
42
+ message: string | Record<string, unknown>
43
+ }
44
+ ```
45
+
46
+ The terminal event is exactly one of `run_complete`, `run_error`, or `credit_insufficient`.
47
+ There is no `stream_end`, `node_start`, `tool_call_end`, or `ai_message_chunk` event in this
48
+ workflow endpoint.
49
+
50
+ ## SDK mapping
51
+
52
+ ```ts
53
+ type AiResult = {
54
+ success: boolean
55
+ runId?: string // X-Run-Id response header
56
+ outcome: 'success' | 'credit_insufficient' | 'run_error' | null
57
+ finalResult: Record<string, unknown> | null
58
+ progressLogs: string[]
59
+ stateData: Record<string, unknown> // deprecated; always empty for this protocol
60
+ nodeExecutions: unknown[] // deprecated; always empty
61
+ toolExecutions: unknown[] // deprecated; always empty
62
+ totalDuration: number
63
+ errors: string[]
64
+ events: AiEvent[]
65
+ }
66
+ ```
67
+
68
+ `run_complete.message` becomes `finalResult`. `progress.message` lines append to `progressLogs`.
69
+ `run_error` and `credit_insufficient` append errors and cause `run()`/`stream.result` to reject with
70
+ `WorkflowExecutionError`; the `events()` iterator yields the terminal event before rejecting.
71
+
72
+ ## UI pattern
73
+
74
+ ```tsx
75
+ function WorkflowProgress({ input }: { input: GenerateInput }) {
76
+ const [logs, setLogs] = useState<string[]>([])
77
+ const [error, setError] = useState<string | null>(null)
78
+
79
+ async function run() {
80
+ const controller = new AbortController()
81
+ try {
82
+ const result = await howone.ai.generate.run(input, {
83
+ signal: controller.signal,
84
+ onMessageChunk: (line) => setLogs((current) => [...current, line]),
85
+ })
86
+ console.log(result)
87
+ } catch (value) {
88
+ setError(value instanceof Error ? value.message : String(value))
89
+ }
90
+ }
91
+
92
+ return <button onClick={() => void run()}>Run workflow</button>
93
+ }
94
+ ```
95
+
96
+ For a cancel button, keep the controller/session in a ref and call `abort()` or `session.cancel()`.
97
+ Treat abort as a user action in UI; do not report it as an EAX `run_error`.
98
+
99
+ ## Callback rules
100
+
101
+ - `onEvent(event, 'workflow')` fires for each parsed envelope.
102
+ - `onRunStart` fires for `run_start`.
103
+ - `onMessageChunk(text, event)` fires for each non-empty progress line.
104
+ - `onProgress(0, message)` is a compatibility callback for progress lines; `onProgress(100)` fires
105
+ on successful completion.
106
+ - `onRunComplete` receives the final object.
107
+ - `onRunError` and `onCreditInsufficient` receive terminal messages.
108
+ - `onComplete` receives the assembled result before a terminal failure is rejected.
109
+ - `onError` receives transport and terminal errors.
110
+
111
+ Callbacks are not a substitute for awaiting `run()` or `session.result`; always handle the promise.
112
+ The SDK retains at most 1,000 events and 500 progress lines by default while still invoking callbacks
113
+ for every event. Configure the bounds for a diagnostic screen rather than retaining unbounded logs.
114
+
115
+ ## Raw event iteration
116
+
117
+ ```ts
118
+ try {
119
+ for await (const event of howone.ai.generate.events(input)) {
120
+ renderEvent(event)
121
+ }
122
+ } catch (error) {
123
+ renderFailure(error)
124
+ }
125
+ ```
126
+
127
+ On a terminal failure, consumers see the `run_error` or `credit_insufficient` event before the
128
+ iterator rejects. Breaking the loop cancels the underlying reader.
129
+
130
+ ## Common mistakes
131
+
132
+ | Mistake | Fix |
133
+ |---|---|
134
+ | Calling the old `/workflow/{appId}/{id}/execute_sse` path | Use the typed SDK action. |
135
+ | Adding `/api` to EAX URL | EAX base is not the REST base; app code should not build it. |
136
+ | Using `onStreamChunk`/`onTextChunk` | Use `onMessageChunk`. |
137
+ | Treating `run_error` as a successful result | Catch `WorkflowExecutionError` and inspect `outcome`. |
138
+ | Parsing `event.payload.result` | Read `event.message`; `run_complete` message is the final object. |
@@ -0,0 +1,310 @@
1
+ # Entity Data Access Patterns (App SDK)
2
+
3
+ Use this reference to connect backend `access` design to frontend SDK calls. It answers:
4
+ **which namespace should the app call, which filters are legal, and what must not be persisted?**
5
+
6
+ For schema design, read `02-entity-schema/01-schema-design.md`. For query syntax details, read
7
+ `12-query-dsl-and-responses.md`.
8
+
9
+ ## Namespace Decision
10
+
11
+ | Schema / page need | SDK namespace | Auth header | Typical method |
12
+ |---|---|---|---|
13
+ | Current user's private records | `howone.entities.Entity` | yes | `query.mine`, `create`, `update`, `delete` |
14
+ | Logged-in shared records | `howone.entities.Entity` | yes | `query`, `get`, CRUD |
15
+ | Public list page | `howone.public.entities.Entity` | no | `query` |
16
+ | Public scoped share/detail | `howone.public.entities.Entity` | no | `queryScoped`, `get` with scope options |
17
+ | Schema tooling | `howone.schema` | yes | `applyPatch`, versions, restore |
18
+ | Low-level fallback | `howone.raw` / `howone.public.raw` | depends | only when typed method missing |
19
+
20
+ Do not mix authenticated and public namespaces for the same page without a clear reason.
21
+
22
+ ## Pattern A: Private Per-User Data
23
+
24
+ Use for todos, notes, journals, saved generations, personal dashboards, private settings.
25
+
26
+ Schema:
27
+
28
+ ```json
29
+ {
30
+ "visibility": "private",
31
+ "access": {
32
+ "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
33
+ "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
34
+ }
35
+ }
36
+ ```
37
+
38
+ Frontend:
39
+
40
+ ```ts
41
+ const list = await howone.entities.Todo.query.mine({
42
+ page: { number: 1, size: 50 },
43
+ orderBy: { updatedDate: 'desc' },
44
+ })
45
+
46
+ await howone.entities.Todo.create({
47
+ text,
48
+ completed: false,
49
+ })
50
+ ```
51
+
52
+ Rules:
53
+
54
+ - Do not pass `ownerId`, `created_by_id`, `createdById`, `created_by_user_id`, or `puid`.
55
+ - Backend derives owner from JWT/session.
56
+ - Use `query.mine()` for owned lists.
57
+ - For first auth load, call `await howone.me()` or `await howone.requireMe()`.
58
+
59
+ ## Pattern B: Authenticated Shared Data
60
+
61
+ Use when logged-in app users can see shared records: team projects, CMS admin, internal catalogs.
62
+
63
+ Schema:
64
+
65
+ ```json
66
+ {
67
+ "visibility": "private",
68
+ "access": {
69
+ "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
70
+ "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
71
+ }
72
+ }
73
+ ```
74
+
75
+ Frontend:
76
+
77
+ ```ts
78
+ const list = await howone.entities.Project.query({
79
+ page: { number: 1, size: 20 },
80
+ orderBy: { updatedDate: 'desc' },
81
+ })
82
+ ```
83
+
84
+ Rules:
85
+
86
+ - Use `query()`, not `query.mine()`.
87
+ - Still require auth.
88
+ - Be conservative with `update: "all"` and `delete: "all"` unless the app has a real role model.
89
+
90
+ ## Pattern C: Public Read-Only Content
91
+
92
+ Use for public articles, templates, products, profiles, published galleries.
93
+
94
+ Schema:
95
+
96
+ ```json
97
+ {
98
+ "visibility": "public",
99
+ "access": {
100
+ "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
101
+ "public": {
102
+ "read": "list",
103
+ "create": "none",
104
+ "update": "none",
105
+ "delete": "none",
106
+ "allowedFilters": ["slug", "status", "category"],
107
+ "allowedSorts": ["publishedAt", "updatedDate"],
108
+ "defaultLimit": 20,
109
+ "maxLimit": 100
110
+ }
111
+ }
112
+ }
113
+ ```
114
+
115
+ Frontend:
116
+
117
+ ```ts
118
+ const list = await howone.public.entities.Article.query({
119
+ where: { status: 'published', category },
120
+ page: { number: 1, size: 20 },
121
+ orderBy: { publishedAt: 'desc' },
122
+ })
123
+ ```
124
+
125
+ Rules:
126
+
127
+ - Public filters must be in `allowedFilters`.
128
+ - Public sorts must be in `allowedSorts`.
129
+ - Never pass tokens or use authenticated namespace for anonymous landing pages.
130
+ - Keep public result fields safe for anonymous users.
131
+
132
+ ## Pattern D: Public Scoped Share Pages
133
+
134
+ Use for public URLs exposing one scoped record: QR profile, public report, resume, invite page.
135
+
136
+ Schema:
137
+
138
+ ```json
139
+ {
140
+ "visibility": "public",
141
+ "access": {
142
+ "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
143
+ "public": {
144
+ "read": "scoped",
145
+ "create": "none",
146
+ "update": "none",
147
+ "delete": "none",
148
+ "requiredScopes": ["ownerId", "slug"],
149
+ "allowedFilters": ["slug", "active"],
150
+ "allowedSorts": ["updatedDate"],
151
+ "defaultLimit": 1,
152
+ "maxLimit": 10
153
+ }
154
+ }
155
+ }
156
+ ```
157
+
158
+ Frontend:
159
+
160
+ ```ts
161
+ const result = await howone.public.entities.QrProfile.queryScoped({
162
+ where: { ownerId, slug, active: true },
163
+ page: { number: 1, size: 1 },
164
+ })
165
+ const profile = result.items[0] ?? null
166
+ ```
167
+
168
+ Rules:
169
+
170
+ - Pass every `requiredScopes` field.
171
+ - Do not use current JWT `puid` as `ownerId` unless schema explicitly stores that as public scope.
172
+ - Do not turn scoped pages into broad list pages.
173
+ - Keep `maxLimit` small.
174
+
175
+ ## Pattern E: Public Create / Anonymous Submission
176
+
177
+ Use only for forms that must accept anonymous/public submissions: waitlist, contact, feedback,
178
+ public RSVP.
179
+
180
+ Schema:
181
+
182
+ ```json
183
+ {
184
+ "visibility": "public",
185
+ "access": {
186
+ "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
187
+ "public": {
188
+ "read": "none",
189
+ "create": "scoped",
190
+ "update": "none",
191
+ "delete": "none",
192
+ "requiredScopes": ["submissionKey"],
193
+ "allowedFilters": [],
194
+ "allowedSorts": [],
195
+ "defaultLimit": 1,
196
+ "maxLimit": 1
197
+ }
198
+ }
199
+ }
200
+ ```
201
+
202
+ Frontend:
203
+
204
+ ```ts
205
+ await howone.public.entities.Feedback.create({
206
+ submissionKey,
207
+ message,
208
+ rating,
209
+ })
210
+ ```
211
+
212
+ Rules:
213
+
214
+ - Public create must use the declared public scope/business fields. Never pass ownership/system
215
+ fields such as `created_by_user_id`; the SDK rejects them and the backend derives ownership/scope.
216
+ - Do not expose public read unless needed.
217
+ - Add anti-abuse UX/server constraints outside the dynamic schema when needed.
218
+ - Never persist UI-only fields from form components.
219
+
220
+ ## Pattern F: AI Workflow Output Persistence
221
+
222
+ Use for generation/analyze/report products that need history and refresh resilience.
223
+
224
+ Recommended flow:
225
+
226
+ ```ts
227
+ const pending = await howone.entities.Generation.create({
228
+ prompt,
229
+ status: 'pending',
230
+ })
231
+
232
+ try {
233
+ const output = await howone.ai.generateImage.run({ prompt })
234
+ await howone.entities.Generation.update(pending.id, {
235
+ status: 'completed',
236
+ resultUrl: output.imageUrl,
237
+ completedAt: new Date().toISOString(),
238
+ })
239
+ } catch (error) {
240
+ await howone.entities.Generation.update(pending.id, {
241
+ status: 'failed',
242
+ errorMessage: error instanceof Error ? error.message : 'Generation failed',
243
+ })
244
+ }
245
+
246
+ const history = await howone.entities.Generation.query.mine({
247
+ orderBy: { updatedDate: 'desc' },
248
+ page: { number: 1, size: 20 },
249
+ })
250
+ ```
251
+
252
+ Rules:
253
+
254
+ - Persist only fields declared in the entity schema.
255
+ - Do not persist raw workflow event streams unless schema defines an object/array field for them.
256
+ - Failure branch must persist failure if the product shows history.
257
+ - Latest result, history list, and detail pages should reload from data API, not only local state.
258
+
259
+ ## Payload Whitelist Rule
260
+
261
+ Before every create/update, mentally compute:
262
+
263
+ ```text
264
+ payload keys ⊆ entity.properties keys
265
+ ```
266
+
267
+ Allowed:
268
+
269
+ ```ts
270
+ await howone.entities.Todo.create({
271
+ text,
272
+ completed: false,
273
+ })
274
+ ```
275
+
276
+ Forbidden:
277
+
278
+ ```ts
279
+ await howone.entities.Todo.create({
280
+ text,
281
+ completed: false,
282
+ gradient_direction: 'to right', // UI-only
283
+ created_by_id: user.id, // system/owner field
284
+ workflowRawResult: output, // undeclared workflow envelope
285
+ })
286
+ ```
287
+
288
+ If the app truly needs a new persisted field, update schema first.
289
+
290
+ ## Access-to-SDK Mapping
291
+
292
+ | Access posture | Read | Create | Update/Delete |
293
+ |---|---|---|---|
294
+ | authenticated `own` | `entities.X.query.mine()` | `entities.X.create()` | `entities.X.update/delete()` |
295
+ | authenticated `all` | `entities.X.query()` | `entities.X.create()` | `entities.X.update/delete()` |
296
+ | public `list` | `public.entities.X.query()` | no | no |
297
+ | public `scoped` | `public.entities.X.queryScoped()` | only if `create: scoped/any` | only if `update: scoped/any` |
298
+ | public `none` | no public call | no public call | no public call |
299
+
300
+ ## Common Mistakes
301
+
302
+ | Mistake | Fix |
303
+ |---|---|
304
+ | Passing `created_by_user_id` for normal private data | Omit owner fields; backend derives owner. |
305
+ | Using `entities.*` on public page | Use `public.entities.*`. |
306
+ | Public filter not in `allowedFilters` | Add filter to schema or remove query. |
307
+ | Public sort not in `allowedSorts` | Add sort to schema or change UI. |
308
+ | Saving workflow output object directly | Map only declared fields. |
309
+ | Rendering history only from local state | Reload via `query.mine()` / public query. |
310
+ | Treating `visibility: "public"` as enough | Always define `access.public`. |
@@ -0,0 +1,237 @@
1
+ # Entity Query DSL And Responses (App SDK)
2
+
3
+ Use this reference when implementing list/detail pages, filters, sorting, pagination, or response
4
+ normalization for HowOne dynamic entities.
5
+
6
+ ## SDK Query Shape
7
+
8
+ ```ts
9
+ await howone.entities.Todo.query({
10
+ where: {
11
+ completed: false,
12
+ priority: { in: ['medium', 'high'] },
13
+ updatedDate: { gte: '2026-01-01T00:00:00.000Z' },
14
+ },
15
+ search: 'invoice',
16
+ page: { number: 1, size: 20 },
17
+ orderBy: { updatedDate: 'desc' },
18
+ include: ['owner'],
19
+ exactCount: true,
20
+ })
21
+ ```
22
+
23
+ Private owner-scoped list:
24
+
25
+ ```ts
26
+ await howone.entities.Todo.query.mine({
27
+ page: { number: 1, size: 50 },
28
+ orderBy: { updatedDate: 'desc' },
29
+ })
30
+ ```
31
+
32
+ Public list:
33
+
34
+ ```ts
35
+ await howone.public.entities.Article.query({
36
+ where: { status: 'published' },
37
+ orderBy: { publishedAt: 'desc' },
38
+ page: { number: 1, size: 20 },
39
+ })
40
+ ```
41
+
42
+ Public scoped:
43
+
44
+ ```ts
45
+ await howone.public.entities.QrProfile.queryScoped({
46
+ where: { ownerId, slug, active: true },
47
+ page: { number: 1, size: 1 },
48
+ })
49
+ ```
50
+
51
+ ## Operators
52
+
53
+ Supported field operators:
54
+
55
+ ```ts
56
+ type FieldOperator<T> = {
57
+ eq?: T
58
+ equals?: T
59
+ ne?: T
60
+ not?: T
61
+ gt?: T
62
+ gte?: T
63
+ lt?: T
64
+ lte?: T
65
+ contains?: string
66
+ like?: string
67
+ startsWith?: string
68
+ starts?: string
69
+ endsWith?: string
70
+ ends?: string
71
+ in?: T[]
72
+ notIn?: T[]
73
+ null?: boolean
74
+ empty?: boolean
75
+ exists?: boolean
76
+ }
77
+ ```
78
+
79
+ Examples:
80
+
81
+ ```ts
82
+ where: { status: 'published' }
83
+ where: { status: { eq: 'published' } }
84
+ where: { score: { gte: 80, lt: 100 } }
85
+ where: { category: { in: ['news', 'guide'] } }
86
+ where: { title: { contains: 'AI' } }
87
+ where: { deletedAt: { null: true } }
88
+ ```
89
+
90
+ ## Pagination
91
+
92
+ Use SDK page object:
93
+
94
+ ```ts
95
+ page: { number: 1, size: 20 }
96
+ ```
97
+
98
+ Response:
99
+
100
+ ```ts
101
+ type QueryResult<T> = {
102
+ items: T[]
103
+ page: {
104
+ number: number
105
+ size: number
106
+ total: number
107
+ totalPages: number
108
+ hasNext: boolean
109
+ hasPrev: boolean
110
+ }
111
+ traceId?: string | number
112
+ raw?: unknown
113
+ }
114
+ ```
115
+
116
+ Always render from a normalized array:
117
+
118
+ ```ts
119
+ const result = await howone.entities.Todo.query.mine(...)
120
+ const items = Array.isArray(result.items) ? result.items : []
121
+ ```
122
+
123
+ ## Sorting
124
+
125
+ SDK uses:
126
+
127
+ ```ts
128
+ orderBy: { updatedDate: 'desc' }
129
+ ```
130
+
131
+ Rules:
132
+
133
+ - Public sort fields must be in `access.public.allowedSorts`.
134
+ - Private sort fields should be in `performance.allowedSorts` and covered by indexes.
135
+ - Prefer `updatedDate` for recently changed lists and `createdDate` for creation history.
136
+ - Do not expose arbitrary public sort fields.
137
+
138
+ ## Include / Relations
139
+
140
+ Use `include` only for relation names declared in schema `relations`.
141
+
142
+ ```ts
143
+ await howone.entities.Article.query({
144
+ include: ['author'],
145
+ })
146
+ ```
147
+
148
+ Rules:
149
+
150
+ - Do not invent include names.
151
+ - Public includes must be safe for anonymous exposure.
152
+ - If a list needs a small display field frequently, consider denormalizing it instead of requiring include on every row.
153
+
154
+ ## Detail Reads
155
+
156
+ Authenticated:
157
+
158
+ ```ts
159
+ const item = await howone.entities.Todo.get(id)
160
+ const item = await howone.entities.Todo.getOrThrow(id)
161
+ ```
162
+
163
+ Public:
164
+
165
+ ```ts
166
+ const item = await howone.public.entities.Article.get(id)
167
+ ```
168
+
169
+ For public scoped detail, prefer `queryScoped` when the route naturally has scope fields like
170
+ `ownerId + slug`.
171
+
172
+ ## Response Field Names
173
+
174
+ SDK defaults to `caseStyle: 'camel'`, so responses are normalized toward camelCase where supported.
175
+ Still know the backend system field meanings:
176
+
177
+ | Backend concept | Common SDK field |
178
+ |---|---|
179
+ | record id | `id` |
180
+ | created date | `createdDate` or `created_date` depending case style |
181
+ | updated date | `updatedDate` or `updated_date` |
182
+ | owner | `createdById` or `created_by_id` |
183
+ | schema version id | `schemaVersionId` or `schema_version_id` |
184
+ | schema version number | `schemaVersionNumber` or `schema_version_number` |
185
+
186
+ Do not use `_id` in app code unless inspecting raw backend payloads.
187
+
188
+ ## Public Guardrails
189
+
190
+ Before writing public query code, check schema:
191
+
192
+ ```json
193
+ "public": {
194
+ "read": "list",
195
+ "allowedFilters": ["status", "slug"],
196
+ "allowedSorts": ["publishedAt"],
197
+ "defaultLimit": 20,
198
+ "maxLimit": 100
199
+ }
200
+ ```
201
+
202
+ Then only use allowed filters and sorts:
203
+
204
+ ```ts
205
+ // OK
206
+ where: { status: 'published' }
207
+ orderBy: { publishedAt: 'desc' }
208
+
209
+ // Not OK unless listed in access.public
210
+ where: { internalReviewState: 'approved' }
211
+ orderBy: { revenue: 'desc' }
212
+ ```
213
+
214
+ ## Search
215
+
216
+ Use `search` for broad text search only when the backend/schema supports the desired behavior:
217
+
218
+ ```ts
219
+ await howone.public.entities.Article.query({
220
+ search: query,
221
+ where: { status: 'published' },
222
+ })
223
+ ```
224
+
225
+ Do not use `search` as a substitute for required public scopes.
226
+
227
+ ## Common Mistakes
228
+
229
+ | Mistake | Fix |
230
+ |---|---|
231
+ | Rendering `res.data.data` from SDK query | SDK returns `QueryResult.items`; render `result.items`. |
232
+ | Using `_id` as record id | Use `id`. |
233
+ | Public query with unlisted filter | Add to `allowedFilters` or remove it. |
234
+ | Public query with unlisted sort | Add to `allowedSorts` or change sorting. |
235
+ | Passing owner filters in authenticated `own` queries | Use `query.mine()` and omit owner fields. |
236
+ | Using include without schema relation | Add relation first or remove include. |
237
+ | No pagination on list pages | Always pass `page` and respect `maxLimit`. |
@@ -0,0 +1,31 @@
1
+ # Credits
2
+
3
+ Use this reference when the app shows the signed-in user's HowOne credit balance or credit history
4
+ (for example a "my credits" panel next to AI features).
5
+
6
+ ## Call
7
+
8
+ ```ts
9
+ import howone from './lib/sdk'
10
+
11
+ const { balance, transactions } = await howone.credits.get({ limit: 20 })
12
+ ```
13
+
14
+ - Requires a signed-in user. Without a token it throws `HowOneAuthError` — send the user to login.
15
+ - `limit` is clamped to 1..100 (default 20).
16
+ - `transactions[]` items carry `type`, a display-ready `typeLabel`, `amount`, `description`,
17
+ and `createdAt`. Render `typeLabel`; do not map `type` to labels yourself.
18
+ - The balance is read-only. Apps never grant, deduct, or top up credits; AI actions consume
19
+ credits on the platform side, and an exhausted balance surfaces as `credit_insufficient`
20
+ from AI action calls (see `07-ai-action-calls.md`).
21
+
22
+ ## Do not
23
+
24
+ - Do **not** build URLs from `howone.runtime.authRoot` (or `VITE_HOWONE_AUTH_URL`) to call
25
+ `/api/credits/*` or any other `/api/*` route. `authRoot` is the platform web app, used only
26
+ for page navigation (login, pricing). Its APIs are private, reject cross-origin requests from
27
+ apps, and would not return this app user's numbers anyway.
28
+ - Do **not** hand-write `howone.raw.get({ url: '/credits/...' })`; use `howone.credits.get()`.
29
+
30
+ Requires `@howone/sdk` 2.0.0-beta.69 or later. Check the installed version before using it
31
+ (`references/version-evidence.md`).