@howone/agent-cli 0.0.0-stage → 0.5.1
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.
- package/README.md +34 -2
- package/bin/index.d.mts +1 -0
- package/bin/index.mjs +2450 -0
- package/package.json +55 -4
- package/skills/howone/01-apps.md +29 -0
- package/skills/howone/02-develop.md +107 -0
- package/skills/howone/03-workflows.md +71 -0
- package/skills/howone/04-functions-and-data.md +41 -0
- package/skills/howone/05-capabilities.md +46 -0
- package/skills/howone/SKILL.md +52 -0
- package/templates/vite/.howone/skills/hallmark/SKILL.md +557 -0
- package/templates/vite/.howone/skills/hallmark/references/anti-patterns.md +418 -0
- package/templates/vite/.howone/skills/hallmark/references/assets.md +406 -0
- package/templates/vite/.howone/skills/hallmark/references/color.md +95 -0
- package/templates/vite/.howone/skills/hallmark/references/component-cookbook.md +265 -0
- package/templates/vite/.howone/skills/hallmark/references/components/c1-outlined-chip.md +12 -0
- package/templates/vite/.howone/skills/hallmark/references/components/c2-inline-form-as-cta.md +16 -0
- package/templates/vite/.howone/skills/hallmark/references/components/c3-typographic-link.md +8 -0
- package/templates/vite/.howone/skills/hallmark/references/components/c4-sticky-bottom-bar.md +16 -0
- package/templates/vite/.howone/skills/hallmark/references/components/f1-bento-grid.md +20 -0
- package/templates/vite/.howone/skills/hallmark/references/components/f2-sticky-scroll-stack.md +20 -0
- package/templates/vite/.howone/skills/hallmark/references/components/f3-tabular-spec-sheet.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/f4-step-sequence.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/f5-annotated-screenshot.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/f6-product-card-grid.md +41 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft1-mast-headed.md +13 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft2-inline-rule-single-line.md +10 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft3-index-style-category-list.md +12 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft4-dense-typographic.md +10 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft5-statement.md +21 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft6-letter-close.md +19 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft7-newsletter-first.md +27 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft8-marquee-scroll.md +25 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h1-marquee.md +15 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h2-split-diptych.md +15 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h3-quote-led.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h4-stat-led.md +14 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h5-letter-hero.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h6-photographic-fold.md +16 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h7-demo-video-clipped-by-viewport-edge.md +27 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h8-mockup-split-browser-framed.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h9-custom-illustration-centerpiece.md +27 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n1-wordmark-2-links.md +12 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n10-floating-on-scroll-morph.md +19 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n11-mega-menu.md +40 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n12-banner-retract.md +34 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n13-inline-cmdk-pill.md +39 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n1b-saas-three-section.md +35 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n2-floating-chip.md +14 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n3-side-rail.md +14 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n4-hidden-behind-k.md +9 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n5-floating-pill.md +28 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n6-newspaper-masthead.md +24 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n7-brutal-slab.md +22 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n8-terminal-command.md +21 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n9-edge-aligned-minimal.md +17 -0
- package/templates/vite/.howone/skills/hallmark/references/components/s1-left-margin-numbered.md +15 -0
- package/templates/vite/.howone/skills/hallmark/references/components/s2-hanging.md +13 -0
- package/templates/vite/.howone/skills/hallmark/references/components/s3-sticky-pinned.md +19 -0
- package/templates/vite/.howone/skills/hallmark/references/components/s4-inline-no-break.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/s5-bottom-anchored.md +13 -0
- package/templates/vite/.howone/skills/hallmark/references/components/t1-pull-quote-with-marginalia.md +12 -0
- package/templates/vite/.howone/skills/hallmark/references/components/t2-logo-wall-hairline.md +19 -0
- package/templates/vite/.howone/skills/hallmark/references/components/t3-single-huge-quote.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/t4-numbered-stat-strip.md +14 -0
- package/templates/vite/.howone/skills/hallmark/references/contract.md +24 -0
- package/templates/vite/.howone/skills/hallmark/references/copy.md +182 -0
- package/templates/vite/.howone/skills/hallmark/references/custom-craft.md +626 -0
- package/templates/vite/.howone/skills/hallmark/references/custom-theme.md +367 -0
- package/templates/vite/.howone/skills/hallmark/references/design-md.md +116 -0
- package/templates/vite/.howone/skills/hallmark/references/export-formats.md +328 -0
- package/templates/vite/.howone/skills/hallmark/references/floating-nav.md +89 -0
- package/templates/vite/.howone/skills/hallmark/references/genres/atmospheric.md +69 -0
- package/templates/vite/.howone/skills/hallmark/references/genres/editorial.md +72 -0
- package/templates/vite/.howone/skills/hallmark/references/genres/modern-minimal.md +71 -0
- package/templates/vite/.howone/skills/hallmark/references/genres/playful.md +70 -0
- package/templates/vite/.howone/skills/hallmark/references/hero-enrichment.md +475 -0
- package/templates/vite/.howone/skills/hallmark/references/imagery-kit.md +170 -0
- package/templates/vite/.howone/skills/hallmark/references/interaction-and-states.md +208 -0
- package/templates/vite/.howone/skills/hallmark/references/layout-and-space.md +112 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/01-bento-grid.md +35 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/02-long-document.md +34 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/03-marquee-hero.md +31 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/04-stat-led.md +34 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/05-workbench.md +32 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/06-conversational-faq.md +33 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/07-manifesto.md +32 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/08-photographic.md +34 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/09-quote-led.md +32 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/10-specimen.md +32 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/11-catalogue.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/12-letter.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/13-index-first.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/14-narrative-workflow.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/15-split-studio.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/16-feature-stack.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/17-type-specimen.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/18-portfolio-grid.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/19-map-diagram.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/20-ecosystem-index.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/21-component-playground.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures.md +89 -0
- package/templates/vite/.howone/skills/hallmark/references/microinteractions.md +258 -0
- package/templates/vite/.howone/skills/hallmark/references/motion.md +109 -0
- package/templates/vite/.howone/skills/hallmark/references/preview-examples.md +49 -0
- package/templates/vite/.howone/skills/hallmark/references/responsive.md +138 -0
- package/templates/vite/.howone/skills/hallmark/references/slop-test.md +192 -0
- package/templates/vite/.howone/skills/hallmark/references/structure.md +160 -0
- package/templates/vite/.howone/skills/hallmark/references/study.md +509 -0
- package/templates/vite/.howone/skills/hallmark/references/themes/carnival.md +301 -0
- package/templates/vite/.howone/skills/hallmark/references/themes/cobalt.md +146 -0
- package/templates/vite/.howone/skills/hallmark/references/themes/hum.md +403 -0
- package/templates/vite/.howone/skills/hallmark/references/themes/lumen.md +478 -0
- package/templates/vite/.howone/skills/hallmark/references/typography.md +243 -0
- package/templates/vite/.howone/skills/hallmark/references/verbs/audit.md +25 -0
- package/templates/vite/.howone/skills/hallmark/references/verbs/redesign.md +269 -0
- package/templates/vite/.howone/skills/howone/01-architect/01-app-generation.md +209 -0
- package/templates/vite/.howone/skills/howone/01-architect/02-manifest-codegen.md +194 -0
- package/templates/vite/.howone/skills/howone/02-entity-schema/01-schema-design.md +523 -0
- package/templates/vite/.howone/skills/howone/02-entity-schema/02-schema-operations.md +329 -0
- package/templates/vite/.howone/skills/howone/02-entity-schema/03-access-models.md +151 -0
- package/templates/vite/.howone/skills/howone/02-entity-schema/04-query-contracts.md +123 -0
- package/templates/vite/.howone/skills/howone/02-entity-schema/05-ai-persistence-patterns.md +255 -0
- package/templates/vite/.howone/skills/howone/03-ai-capabilities/01-ai-capability-architecture.md +215 -0
- package/templates/vite/.howone/skills/howone/03-ai-capabilities/02-workflow-contract-rules.md +427 -0
- package/templates/vite/.howone/skills/howone/03-ai-capabilities/03-service-capability-catalog.md +304 -0
- package/templates/vite/.howone/skills/howone/03-ai-capabilities/04-workflow-operations.md +164 -0
- package/templates/vite/.howone/skills/howone/03-ai-capabilities/05-ai-feature-playbooks.md +275 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/01-client-setup.md +162 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/02-entity-operations.md +163 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/03-auth.md +418 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/04-react-integration.md +138 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/05-file-upload.md +112 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/06-raw-http.md +128 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/07-ai-action-calls.md +210 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/08-ai-manifest-handoff.md +90 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/09-extension-boundaries.md +226 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/10-workflow-execute-sse.md +138 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/11-entity-data-access-patterns.md +310 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/12-query-dsl-and-responses.md +237 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/13-credits.md +31 -0
- package/templates/vite/.howone/skills/howone/SKILL.md +256 -0
- package/templates/vite/.howone/skills/howone/agents/openai.yaml +4 -0
- package/templates/vite/.howone/skills/howone/references/audio-generation.md +30 -0
- package/templates/vite/.howone/skills/howone/references/audio-recognition.md +30 -0
- package/templates/vite/.howone/skills/howone/references/common-errors.md +27 -0
- package/templates/vite/.howone/skills/howone/references/finance.md +28 -0
- package/templates/vite/.howone/skills/howone/references/image-editing.md +30 -0
- package/templates/vite/.howone/skills/howone/references/image-generation.md +30 -0
- package/templates/vite/.howone/skills/howone/references/version-evidence.md +47 -0
- package/templates/vite/.howone/skills/howone/references/video-generation.md +35 -0
- package/templates/vite/.howone/skills/howone/scripts/verify-project.mjs +151 -0
- package/templates/vite/.prettierignore +7 -0
- package/templates/vite/.prettierrc +11 -0
- package/templates/vite/AGENTS.md +87 -0
- package/templates/vite/README.md +21 -0
- package/templates/vite/components.json +25 -0
- package/templates/vite/eslint.config.js +23 -0
- package/templates/vite/index.html +12 -0
- package/templates/vite/package.json +58 -0
- package/templates/vite/public/vite.svg +1 -0
- package/templates/vite/src/App.tsx +17 -0
- package/templates/vite/src/assets/react.svg +1 -0
- package/templates/vite/src/components/theme-provider.tsx +230 -0
- package/templates/vite/src/components/ui/accordion.tsx +79 -0
- package/templates/vite/src/components/ui/alert-dialog.tsx +197 -0
- package/templates/vite/src/components/ui/alert.tsx +76 -0
- package/templates/vite/src/components/ui/aspect-ratio.tsx +11 -0
- package/templates/vite/src/components/ui/avatar.tsx +110 -0
- package/templates/vite/src/components/ui/badge.tsx +49 -0
- package/templates/vite/src/components/ui/breadcrumb.tsx +122 -0
- package/templates/vite/src/components/ui/button-group.tsx +83 -0
- package/templates/vite/src/components/ui/button.tsx +67 -0
- package/templates/vite/src/components/ui/calendar.tsx +222 -0
- package/templates/vite/src/components/ui/card.tsx +103 -0
- package/templates/vite/src/components/ui/carousel.tsx +240 -0
- package/templates/vite/src/components/ui/chart.tsx +373 -0
- package/templates/vite/src/components/ui/checkbox.tsx +31 -0
- package/templates/vite/src/components/ui/collapsible.tsx +33 -0
- package/templates/vite/src/components/ui/combobox.tsx +299 -0
- package/templates/vite/src/components/ui/command.tsx +193 -0
- package/templates/vite/src/components/ui/context-menu.tsx +261 -0
- package/templates/vite/src/components/ui/dialog.tsx +168 -0
- package/templates/vite/src/components/ui/direction.tsx +22 -0
- package/templates/vite/src/components/ui/drawer.tsx +132 -0
- package/templates/vite/src/components/ui/dropdown-menu.tsx +269 -0
- package/templates/vite/src/components/ui/empty.tsx +104 -0
- package/templates/vite/src/components/ui/field.tsx +238 -0
- package/templates/vite/src/components/ui/hover-card.tsx +42 -0
- package/templates/vite/src/components/ui/input-group.tsx +154 -0
- package/templates/vite/src/components/ui/input-otp.tsx +87 -0
- package/templates/vite/src/components/ui/input.tsx +19 -0
- package/templates/vite/src/components/ui/item.tsx +196 -0
- package/templates/vite/src/components/ui/kbd.tsx +26 -0
- package/templates/vite/src/components/ui/label.tsx +22 -0
- package/templates/vite/src/components/ui/menubar.tsx +280 -0
- package/templates/vite/src/components/ui/native-select.tsx +61 -0
- package/templates/vite/src/components/ui/navigation-menu.tsx +164 -0
- package/templates/vite/src/components/ui/pagination.tsx +129 -0
- package/templates/vite/src/components/ui/popover.tsx +87 -0
- package/templates/vite/src/components/ui/progress.tsx +31 -0
- package/templates/vite/src/components/ui/radio-group.tsx +42 -0
- package/templates/vite/src/components/ui/resizable.tsx +50 -0
- package/templates/vite/src/components/ui/scroll-area.tsx +53 -0
- package/templates/vite/src/components/ui/select.tsx +192 -0
- package/templates/vite/src/components/ui/separator.tsx +26 -0
- package/templates/vite/src/components/ui/sheet.tsx +145 -0
- package/templates/vite/src/components/ui/sidebar.tsx +700 -0
- package/templates/vite/src/components/ui/skeleton.tsx +13 -0
- package/templates/vite/src/components/ui/slider.tsx +59 -0
- package/templates/vite/src/components/ui/sonner.tsx +47 -0
- package/templates/vite/src/components/ui/spinner.tsx +10 -0
- package/templates/vite/src/components/ui/switch.tsx +33 -0
- package/templates/vite/src/components/ui/table.tsx +114 -0
- package/templates/vite/src/components/ui/tabs.tsx +90 -0
- package/templates/vite/src/components/ui/textarea.tsx +18 -0
- package/templates/vite/src/components/ui/toggle-group.tsx +89 -0
- package/templates/vite/src/components/ui/toggle.tsx +45 -0
- package/templates/vite/src/components/ui/tooltip.tsx +57 -0
- package/templates/vite/src/hooks/use-mobile.ts +19 -0
- package/templates/vite/src/index.css +133 -0
- package/templates/vite/src/lib/sdk.ts +34 -0
- package/templates/vite/src/lib/utils.ts +6 -0
- package/templates/vite/src/main.tsx +14 -0
- package/templates/vite/tsconfig.app.json +32 -0
- package/templates/vite/tsconfig.json +13 -0
- package/templates/vite/tsconfig.node.json +26 -0
- 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`).
|