@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,128 @@
|
|
|
1
|
+
# Raw HTTP
|
|
2
|
+
|
|
3
|
+
Use `howone.raw` only for an app-owned endpoint that has no typed entity, auth, upload, or AI
|
|
4
|
+
binding. Do not use it to bypass manifest access rules or recreate `/data` and workflow calls.
|
|
5
|
+
|
|
6
|
+
## Contract
|
|
7
|
+
|
|
8
|
+
`howone.raw` is a request client whose methods resolve to response **data**, not an AxiosResponse:
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
const data = await howone.raw.get<Stats>({ url: '/custom/stats' })
|
|
12
|
+
const created = await howone.raw.post<Receipt>({
|
|
13
|
+
url: '/custom/receipts',
|
|
14
|
+
data: { orderId },
|
|
15
|
+
})
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
type RequestConfig<T = unknown> = AxiosRequestConfig & {
|
|
20
|
+
interceptors?: {
|
|
21
|
+
requestInterceptor?: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig
|
|
22
|
+
requestInterceptorCatch?: (error: unknown) => unknown
|
|
23
|
+
responseInterceptor?: (data: T) => T
|
|
24
|
+
responseInterceptorCatch?: (error: unknown) => unknown
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The SDK attaches the current client token to authenticated non-public requests. It does not turn
|
|
30
|
+
an app-owned route into a platform contract; the backend must authenticate and authorize it.
|
|
31
|
+
|
|
32
|
+
## URL rules
|
|
33
|
+
|
|
34
|
+
The configured REST base already ends in `/api` for hosted environments. Use a path relative to that
|
|
35
|
+
base:
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
// Correct: https://api.howone.dev/api/custom/stats
|
|
39
|
+
const stats = await howone.raw.get<Stats>({ url: '/custom/stats' })
|
|
40
|
+
|
|
41
|
+
// Wrong: https://api.howone.dev/api/api/custom/stats
|
|
42
|
+
// howone.raw.get({ url: '/api/custom/stats' })
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Never build a request URL from `howone.runtime.authRoot` / `VITE_HOWONE_AUTH_URL`. That origin is
|
|
46
|
+
the HowOne platform web app, used only for page navigation (login, pricing); its `/api/*` routes are
|
|
47
|
+
private to the platform, reject cross-origin calls from apps, and are not app contracts. Platform data
|
|
48
|
+
an app may read has a typed SDK method instead — for credits use `howone.credits.get()`
|
|
49
|
+
(`13-credits.md`).
|
|
50
|
+
|
|
51
|
+
An absolute URL is an explicit app-owned escape hatch and is not how EAX routing is selected. Do not
|
|
52
|
+
put an EAX URL in a raw request; AI actions already use `env`.
|
|
53
|
+
|
|
54
|
+
## Query, headers, and cancellation
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
const result = await howone.raw.get<SearchResult>({
|
|
58
|
+
url: '/custom/search',
|
|
59
|
+
params: { q, page: 1, limit: 20 },
|
|
60
|
+
headers: { 'X-Request-Source': 'app' },
|
|
61
|
+
signal: controller.signal,
|
|
62
|
+
})
|
|
63
|
+
|
|
64
|
+
// Cancels every in-flight request with this exact method-independent URL.
|
|
65
|
+
howone.raw.cancelRequest('/custom/search')
|
|
66
|
+
howone.raw.cancelAllRequests()
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Prefer an `AbortController` per component operation so a new search does not cancel an unrelated
|
|
70
|
+
request. The SDK links the caller's signal to its internal controller and also supports concurrent
|
|
71
|
+
requests with the same method and URL.
|
|
72
|
+
|
|
73
|
+
```tsx
|
|
74
|
+
useEffect(() => {
|
|
75
|
+
const controller = new AbortController()
|
|
76
|
+
void howone.raw
|
|
77
|
+
.get<SearchResult>({ url: '/custom/search', params: { q }, signal: controller.signal })
|
|
78
|
+
.then(setResult)
|
|
79
|
+
.catch((error) => {
|
|
80
|
+
if (!controller.signal.aborted) setError(error instanceof Error ? error.message : String(error))
|
|
81
|
+
})
|
|
82
|
+
return () => controller.abort()
|
|
83
|
+
}, [q])
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Per-request interceptors
|
|
87
|
+
|
|
88
|
+
The response interceptor sees the already-unwrapped data:
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
const data = await howone.raw.get<RawStats>({
|
|
92
|
+
url: '/custom/stats',
|
|
93
|
+
interceptors: {
|
|
94
|
+
requestInterceptor: (config) => {
|
|
95
|
+
config.headers.set('X-Request-Id', crypto.randomUUID())
|
|
96
|
+
return config
|
|
97
|
+
},
|
|
98
|
+
responseInterceptor: (value) => ({ ...value, loadedAt: Date.now() }),
|
|
99
|
+
responseInterceptorCatch: (error) => Promise.reject(error),
|
|
100
|
+
},
|
|
101
|
+
})
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Do not expect `value.status` or `value.data` in `responseInterceptor`; use the direct Axios instance
|
|
105
|
+
only when the installed SDK typings explicitly require a transport-level operation.
|
|
106
|
+
|
|
107
|
+
## Choosing the correct surface
|
|
108
|
+
|
|
109
|
+
| Need | Use |
|
|
110
|
+
|---|---|
|
|
111
|
+
| Manifest entity CRUD/query | `howone.entities.Entity.*` |
|
|
112
|
+
| Manifest-approved public data | `howone.public.entities.Entity.*` |
|
|
113
|
+
| EAX workflow | `howone.ai.action.run/stream/events` |
|
|
114
|
+
| HowOne storage | `howone.upload.*` |
|
|
115
|
+
| App-owned backend route | `howone.raw.*` |
|
|
116
|
+
|
|
117
|
+
If the endpoint is missing from the platform contract, classify it as an explicit app-owned
|
|
118
|
+
integration. Do not call an internal platform route because it happens to work today.
|
|
119
|
+
|
|
120
|
+
## Common mistakes
|
|
121
|
+
|
|
122
|
+
| Mistake | Fix |
|
|
123
|
+
|---|---|
|
|
124
|
+
| Reading `response.data` | Raw methods already return data. |
|
|
125
|
+
| Prefixing `/api` in a raw path | The REST base already includes `/api`. |
|
|
126
|
+
| Calling raw `/data/...` | Use generated entity bindings. |
|
|
127
|
+
| Passing `'*'` as a cross-window origin | Use explicit origins in the devtools Provider. |
|
|
128
|
+
| Cancelling by a broad substring | Use the exact request path or the caller's AbortSignal. |
|
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
# AI Action Calls
|
|
2
|
+
|
|
3
|
+
Use this track only after the AI capability has been applied, synced, submitted to EAX, and synced
|
|
4
|
+
again. `.howone/ai/manifest.json` is the source for action IDs, JSON schemas, and workflow config
|
|
5
|
+
UUIDs.
|
|
6
|
+
|
|
7
|
+
## Binding order
|
|
8
|
+
|
|
9
|
+
1. Read the current `.howone/ai/manifest.json`.
|
|
10
|
+
2. Convert its input/output JSON Schemas to Zod without weakening required fields.
|
|
11
|
+
3. Copy the exact manifest `workflowId` UUID.
|
|
12
|
+
4. Define and compose the action in `src/lib/sdk.ts`.
|
|
13
|
+
5. Run the project verifier, typecheck, and build.
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { defineAiAction, defineAiActions } from '@howone/sdk'
|
|
17
|
+
import { z } from 'zod'
|
|
18
|
+
|
|
19
|
+
export const generateImageInputSchema = z.object({
|
|
20
|
+
prompt: z.string().min(1),
|
|
21
|
+
aspectRatio: z.enum(['1:1', '16:9']).optional(),
|
|
22
|
+
})
|
|
23
|
+
|
|
24
|
+
export const generateImageOutputSchema = z.object({
|
|
25
|
+
imageUrl: z.string().url(),
|
|
26
|
+
})
|
|
27
|
+
|
|
28
|
+
export const ai = defineAiActions({
|
|
29
|
+
generateImage: defineAiAction('generateImage', {
|
|
30
|
+
workflowId: 'd69ab648-2c00-4d94-928e-01bd7b2a5bb2',
|
|
31
|
+
inputSchema: generateImageInputSchema,
|
|
32
|
+
outputSchema: generateImageOutputSchema,
|
|
33
|
+
}),
|
|
34
|
+
})
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`workflowId` is required and validated as a UUID when the module loads. There is no action-name
|
|
38
|
+
fallback. Never guess, reuse an ID from another project, or continue with a placeholder.
|
|
39
|
+
|
|
40
|
+
Pass Zod schemas, not manifest JSON objects. With an `outputSchema`, `.run()` validates and returns
|
|
41
|
+
`run_complete.message` directly. Without one, `.run()` returns the raw `ExecutionResult`.
|
|
42
|
+
|
|
43
|
+
## Four execution surfaces
|
|
44
|
+
|
|
45
|
+
### `run`: exceptions are control flow
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
try {
|
|
49
|
+
const output = await howone.ai.generateImage.run({ prompt })
|
|
50
|
+
setImageUrl(output.imageUrl)
|
|
51
|
+
} catch (error) {
|
|
52
|
+
if (error instanceof WorkflowExecutionError) {
|
|
53
|
+
console.error(error.outcome, error.runId, error.result.errors)
|
|
54
|
+
} else if (error instanceof AiSchemaValidationError) {
|
|
55
|
+
console.error(error.direction, error.issues)
|
|
56
|
+
}
|
|
57
|
+
throw error
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`run()` rejects for:
|
|
62
|
+
|
|
63
|
+
- input or output schema validation errors;
|
|
64
|
+
- HTTP/network/abort errors;
|
|
65
|
+
- a `run_error` terminal event;
|
|
66
|
+
- a `credit_insufficient` terminal event;
|
|
67
|
+
- a stream that closes without a terminal event.
|
|
68
|
+
|
|
69
|
+
Do not check `result.success` after a failed run; failure does not resolve. A successful typed action
|
|
70
|
+
returns the typed output, not the execution envelope.
|
|
71
|
+
|
|
72
|
+
### `runSafe`: explicit result union
|
|
73
|
+
|
|
74
|
+
Use this when UI code prefers data-flow branching:
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
const result = await howone.ai.generateImage.runSafe({ prompt })
|
|
78
|
+
if (!result.ok) {
|
|
79
|
+
setError(result.error.message)
|
|
80
|
+
return
|
|
81
|
+
}
|
|
82
|
+
setImageUrl(result.value.imageUrl)
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
type AiSafeResult<T> =
|
|
87
|
+
| { ok: true; value: T }
|
|
88
|
+
| { ok: false; error: Error }
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
`runSafe()` catches the same errors that `run()` throws. Do not use it to silently ignore failures.
|
|
92
|
+
|
|
93
|
+
### `stream`: callbacks plus a rejecting result promise
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
const session = howone.ai.generateImage.stream(
|
|
97
|
+
{ prompt },
|
|
98
|
+
{
|
|
99
|
+
onRunStart: () => setPhase('running'),
|
|
100
|
+
onMessageChunk: (line) => appendLog(line),
|
|
101
|
+
onRunComplete: (_event, result) => console.log(result.finalResult),
|
|
102
|
+
onCreditInsufficient: () => setPhase('blocked'),
|
|
103
|
+
onRunError: () => setPhase('failed'),
|
|
104
|
+
onError: (error) => console.error(error),
|
|
105
|
+
},
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
try {
|
|
109
|
+
const execution = await session.result
|
|
110
|
+
console.log(execution.finalResult)
|
|
111
|
+
} finally {
|
|
112
|
+
// cancel is idempotent and safe during cleanup.
|
|
113
|
+
session.cancel()
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
`stream()` starts immediately. `session.result` resolves only on `run_complete`; it rejects on
|
|
118
|
+
terminal workflow errors, transport errors, and abort. For a typed action, `session.result` remains
|
|
119
|
+
the raw execution result because streaming callbacks/events expose protocol data. Use `.run()` when
|
|
120
|
+
the only desired result is the validated typed output.
|
|
121
|
+
|
|
122
|
+
### `events`: ordered async iteration
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
try {
|
|
126
|
+
for await (const event of howone.ai.generateImage.events({ prompt })) {
|
|
127
|
+
if (event.type === 'progress') appendLog(String(event.message))
|
|
128
|
+
if (event.type === 'run_complete') setOutput(event.message)
|
|
129
|
+
}
|
|
130
|
+
} catch (error) {
|
|
131
|
+
// On run_error/credit_insufficient, the terminal event was yielded before this rejection.
|
|
132
|
+
setError(error instanceof Error ? error.message : String(error))
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The iterable owns and cleans up its session. On terminal workflow failure it yields the terminal
|
|
137
|
+
event first, then rejects on the next iteration step. Breaking out of the loop cancels the request.
|
|
138
|
+
|
|
139
|
+
## Callback semantics
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
type AiOptions = {
|
|
143
|
+
onEvent?: (event: AiEvent, channel: 'workflow') => void
|
|
144
|
+
onDisplayEvent?: (event: WorkflowEventDisplay) => void
|
|
145
|
+
onRunStart?: (event: RunStartEvent) => void
|
|
146
|
+
onMessageChunk?: (text: string, event: ProgressEvent) => void
|
|
147
|
+
onProgress?: (percent: number, message?: string) => void
|
|
148
|
+
onRunComplete?: (event: RunCompleteEvent, result: AiResult) => void
|
|
149
|
+
onRunError?: (event: RunErrorEvent) => void
|
|
150
|
+
onCreditInsufficient?: (event: CreditInsufficientEvent) => void
|
|
151
|
+
onComplete?: (result: AiResult) => void
|
|
152
|
+
onError?: (error: Error) => void
|
|
153
|
+
signal?: AbortSignal
|
|
154
|
+
maxRetainedEvents?: number
|
|
155
|
+
maxRetainedProgressLogs?: number
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Use `onMessageChunk`; old names such as `onStreamChunk`, `onTextChunk`, or legacy multi-channel
|
|
160
|
+
callbacks do not exist. `onEvent` observes every event before terminal-specific callbacks and before
|
|
161
|
+
the result promise rejects. `onComplete` means a terminal event was assembled, including an error
|
|
162
|
+
terminal; inspect `result.outcome`. `onError` then receives the structured error.
|
|
163
|
+
|
|
164
|
+
Callbacks receive every event even when retained arrays are bounded. Defaults retain at most 1,000
|
|
165
|
+
raw events and 500 progress log lines, preventing long workflows from growing memory without bound.
|
|
166
|
+
|
|
167
|
+
## Error classes
|
|
168
|
+
|
|
169
|
+
| Error | Meaning |
|
|
170
|
+
|---|---|
|
|
171
|
+
| `AiWorkflowConfigurationError` | binding has a missing/non-UUID workflow ID |
|
|
172
|
+
| `AiSchemaConfigurationError` | schema does not implement Zod `safeParse` |
|
|
173
|
+
| `AiSchemaValidationError` | input or final output violates the schema |
|
|
174
|
+
| `WorkflowExecutionError` | EAX emitted `run_error` or `credit_insufficient` |
|
|
175
|
+
|
|
176
|
+
For credit failures, use `error.outcome === 'credit_insufficient'`. SDK limit callbacks are signals;
|
|
177
|
+
the app owns visible upgrade UI. The SDK does not call `window.confirm` unless legacy
|
|
178
|
+
`showUpgradeToast: true` is explicitly enabled.
|
|
179
|
+
|
|
180
|
+
## Persistence
|
|
181
|
+
|
|
182
|
+
For history-style products, create a pending entity before calling AI and persist completed/failed
|
|
183
|
+
state with `runAiActionAndPersist()`. Keep workflow execution free of database CRUD; entity writes
|
|
184
|
+
belong to app code.
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
await runAiActionAndPersist({
|
|
188
|
+
entity: howone.entities.Generation,
|
|
189
|
+
input,
|
|
190
|
+
createPending: ({ prompt }) => ({ prompt, status: 'pending' }),
|
|
191
|
+
run: (value) => howone.ai.generateImage.run(value),
|
|
192
|
+
mapCompleted: ({ output }) => ({ status: 'completed', imageUrl: output.imageUrl }),
|
|
193
|
+
mapFailed: ({ error }) => ({
|
|
194
|
+
status: 'failed',
|
|
195
|
+
errorMessage: error instanceof Error ? error.message : String(error),
|
|
196
|
+
}),
|
|
197
|
+
})
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
## Common mistakes
|
|
201
|
+
|
|
202
|
+
| Mistake | Fix |
|
|
203
|
+
|---|---|
|
|
204
|
+
| Omitting `workflowId` | Re-read the synced manifest; module initialization now throws. |
|
|
205
|
+
| Adding `mode: 'run'` to the action | Every action exposes run/runSafe/stream/events; no mode option exists. |
|
|
206
|
+
| Reading `.finalResult` from a typed `.run()` | Use the returned typed output directly. |
|
|
207
|
+
| Expecting `stream.result` to be typed output | It is the raw execution result. |
|
|
208
|
+
| Swallowing `session.result` | Always await/catch it to avoid unhandled rejection. |
|
|
209
|
+
| Weakening output Zod after validation fails | Fix the manifest/workflow mismatch. |
|
|
210
|
+
| Writing an EAX URL | Set only client `env`; the SDK owns the endpoint mapping. |
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# AI Manifest Handoff
|
|
2
|
+
|
|
3
|
+
Use this track after `sync_ai_artifacts` and external workflow submission. It is the short handoff
|
|
4
|
+
from `.howone/ai/manifest.json` to `src/lib/sdk.ts`; use `07-ai-action-calls.md` for execution
|
|
5
|
+
semantics and `10-workflow-execute-sse.md` for wire details.
|
|
6
|
+
|
|
7
|
+
## Handoff protocol
|
|
8
|
+
|
|
9
|
+
1. Read the current manifest, not a cached tool response.
|
|
10
|
+
2. Confirm every action has an exact UUID `workflowId`.
|
|
11
|
+
3. Generate Zod input/output schemas from the manifest.
|
|
12
|
+
4. Bind with `defineAiAction` and compose with `withAiActions`.
|
|
13
|
+
5. Run `node .howone/skills/howone/scripts/verify-project.mjs`, typecheck, and build.
|
|
14
|
+
|
|
15
|
+
Workflow create/update can rotate the config UUID. After every successful external workflow
|
|
16
|
+
operation, sync and re-read the manifest before deciding whether the app binding changed.
|
|
17
|
+
|
|
18
|
+
There is no action-name fallback. A missing UUID is a module initialization error, not a server
|
|
19
|
+
request that can be repaired later.
|
|
20
|
+
|
|
21
|
+
## Example
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import { createClient, defineAiAction, defineAiActions, withAiActions } from '@howone/sdk'
|
|
25
|
+
import { z } from 'zod'
|
|
26
|
+
|
|
27
|
+
const client = createClient({
|
|
28
|
+
projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
|
|
29
|
+
env: import.meta.env.VITE_HOWONE_ENV,
|
|
30
|
+
})
|
|
31
|
+
|
|
32
|
+
const inputSchema = z.object({ documentUrl: z.string().url() })
|
|
33
|
+
const outputSchema = z.object({ summary: z.string() })
|
|
34
|
+
|
|
35
|
+
const ai = defineAiActions({
|
|
36
|
+
summarizeDocument: defineAiAction('summarizeDocument', {
|
|
37
|
+
workflowId: '550e8400-e29b-41d4-a716-446655440000',
|
|
38
|
+
inputSchema,
|
|
39
|
+
outputSchema,
|
|
40
|
+
}),
|
|
41
|
+
})
|
|
42
|
+
|
|
43
|
+
const howone = withAiActions(client, ai)
|
|
44
|
+
export default howone
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The UUID above is illustrative only. Copy the real value from the current manifest.
|
|
48
|
+
|
|
49
|
+
## Schema conversion rules
|
|
50
|
+
|
|
51
|
+
| JSON Schema | Zod |
|
|
52
|
+
|---|---|
|
|
53
|
+
| string | `z.string()` |
|
|
54
|
+
| string URI | `z.string().url()` |
|
|
55
|
+
| number/integer | `z.number()` / `z.number().int()` |
|
|
56
|
+
| boolean | `z.boolean()` |
|
|
57
|
+
| array | `z.array(item)` |
|
|
58
|
+
| object | `z.object({ ... })` |
|
|
59
|
+
| enum | `z.enum([...])` |
|
|
60
|
+
| nullable | `z.nullable(...)` |
|
|
61
|
+
| not required | `.optional()` |
|
|
62
|
+
|
|
63
|
+
Do not make required fields optional and do not use `.passthrough()` to conceal a workflow result
|
|
64
|
+
shape mismatch. Typed `.run()` returns the validated final result directly.
|
|
65
|
+
|
|
66
|
+
## Result handoff
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
const output = await howone.ai.summarizeDocument.run({ documentUrl })
|
|
70
|
+
await howone.entities.DocumentSummary.create({
|
|
71
|
+
documentUrl,
|
|
72
|
+
summary: output.summary,
|
|
73
|
+
status: 'completed',
|
|
74
|
+
})
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
For history, use pending-first `runAiActionAndPersist`. The workflow does not perform database CRUD;
|
|
78
|
+
the app persists through generated entity bindings.
|
|
79
|
+
|
|
80
|
+
For streaming, use `onMessageChunk`, await `session.result`, and catch terminal workflow errors.
|
|
81
|
+
For events, a terminal error event is yielded before the iterator rejects.
|
|
82
|
+
|
|
83
|
+
## Final checklist
|
|
84
|
+
|
|
85
|
+
- [ ] Current AI manifest was read after the last sync.
|
|
86
|
+
- [ ] Action IDs and UUIDs match exactly.
|
|
87
|
+
- [ ] Zod requiredness/enums match the manifest.
|
|
88
|
+
- [ ] No `aiUrl`, `aiBaseUrl`, or raw EAX URL was added.
|
|
89
|
+
- [ ] App uses `HowOneProvider client={howone}`.
|
|
90
|
+
- [ ] Verifier, typecheck, and build pass.
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
# SDK Extension Boundaries
|
|
2
|
+
|
|
3
|
+
This reference defines the long-term shape of `@howone/sdk`. Use it whenever changing SDK APIs,
|
|
4
|
+
adding new capabilities, or deciding whether behavior belongs in the SDK or in the generated app.
|
|
5
|
+
|
|
6
|
+
## North Star
|
|
7
|
+
|
|
8
|
+
The SDK is an AI-first runtime, not an app UI framework.
|
|
9
|
+
|
|
10
|
+
It should provide:
|
|
11
|
+
|
|
12
|
+
- stable defaults that work with almost no configuration;
|
|
13
|
+
- typed clients for HowOne platform capabilities;
|
|
14
|
+
- adapters for custom behavior;
|
|
15
|
+
- callbacks/events for app UI;
|
|
16
|
+
- predictable names that AI agents can reuse without guessing.
|
|
17
|
+
|
|
18
|
+
It should not provide:
|
|
19
|
+
|
|
20
|
+
- app-owned pages, modals, toasts, or business UI;
|
|
21
|
+
- hardcoded app flows beyond HowOne platform defaults;
|
|
22
|
+
- hidden persistence side effects;
|
|
23
|
+
- provider-specific branches scattered through feature code.
|
|
24
|
+
|
|
25
|
+
## Default + Adapter Rule
|
|
26
|
+
|
|
27
|
+
Every platform capability should follow the same shape:
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
createClient({
|
|
31
|
+
projectId,
|
|
32
|
+
env,
|
|
33
|
+
auth: 'hosted', // default
|
|
34
|
+
})
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Advanced usage should opt into typed adapters:
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
createClient({
|
|
41
|
+
projectId,
|
|
42
|
+
env,
|
|
43
|
+
auth: {
|
|
44
|
+
mode: 'headless',
|
|
45
|
+
adapter: {
|
|
46
|
+
getToken: () => externalAuth.getToken(),
|
|
47
|
+
setToken: (token) => externalAuth.setToken(token),
|
|
48
|
+
login: ({ returnUrl }) => appRouter.push(`/login?redirect=${encodeURIComponent(returnUrl ?? '/')}`),
|
|
49
|
+
logout: () => appRouter.push('/'),
|
|
50
|
+
},
|
|
51
|
+
},
|
|
52
|
+
})
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Do not add one-off flags when an adapter/callback can express the behavior.
|
|
56
|
+
|
|
57
|
+
## Capability Boundaries
|
|
58
|
+
|
|
59
|
+
| Capability | SDK owns | App owns |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| Auth | token source, session state, login/logout destination policy, hosted HowOne defaults | login page visuals, account menu, loading states, auth error UI |
|
|
62
|
+
| React provider | context, auth callbacks, optional bottom-right HowOne `FloatingButton` logo | layout, toasts, overlays, route components, theme system |
|
|
63
|
+
| Entities | typed CRUD/query clients, public/private routing, payload normalization | forms, list rendering, optimistic UI, field-level UX |
|
|
64
|
+
| Schema | definition operations, apply/version/restore calls | migration approval UI, admin experience |
|
|
65
|
+
| Entity contract utilities | payload whitelisting, public query guardrail validation, structured validation issues | deciding product copy, rendering validation errors |
|
|
66
|
+
| AI workflows | run/stream/events, Zod validation, workflowId binding | progress UI, result rendering, failure surfaces |
|
|
67
|
+
| AI persistence | pending-first orchestration helper, state callbacks, completed/failed mapping hook | choosing schema fields, retry UX, visible state UI |
|
|
68
|
+
| Upload | file/image/batch helpers and callbacks | picker UI, previews, validation copy, uploaded-file placement |
|
|
69
|
+
| Raw HTTP | low-level escape hatch | choosing it only when typed SDK surface does not exist |
|
|
70
|
+
|
|
71
|
+
## React Provider Boundary
|
|
72
|
+
|
|
73
|
+
`HowOneProvider` may render the HowOne bottom-right logo via `FloatingButton`. This is platform
|
|
74
|
+
branding and should remain visible by default.
|
|
75
|
+
|
|
76
|
+
It must not render:
|
|
77
|
+
|
|
78
|
+
- toast notifications;
|
|
79
|
+
- redirect overlays;
|
|
80
|
+
- login/register forms;
|
|
81
|
+
- payment dialogs;
|
|
82
|
+
- app theme wrappers;
|
|
83
|
+
- app-specific navigation.
|
|
84
|
+
|
|
85
|
+
Use callbacks instead:
|
|
86
|
+
|
|
87
|
+
```tsx
|
|
88
|
+
<HowOneProvider
|
|
89
|
+
client={howone}
|
|
90
|
+
brand="visible"
|
|
91
|
+
onAuthRedirect={({ mode, returnUrl }) => {
|
|
92
|
+
setAuthUi({ redirecting: true, mode, returnUrl })
|
|
93
|
+
}}
|
|
94
|
+
onAuthStateChange={(state) => {
|
|
95
|
+
setCurrentUser(state.user)
|
|
96
|
+
}}
|
|
97
|
+
>
|
|
98
|
+
<App />
|
|
99
|
+
</HowOneProvider>
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Hide the logo only when explicitly requested:
|
|
103
|
+
|
|
104
|
+
```tsx
|
|
105
|
+
<HowOneProvider client={howone} brand="hidden" />
|
|
106
|
+
<HowOneProvider client={howone} showBrandButton={false} />
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## UI Feedback Rule
|
|
110
|
+
|
|
111
|
+
Do not add `ClayxToast`, `toast`, or any visible notification API to `@howone/sdk`.
|
|
112
|
+
|
|
113
|
+
Generated apps should write their own UI from SDK results:
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
setStatus({ type: 'loading', message: 'Generating...' })
|
|
117
|
+
|
|
118
|
+
try {
|
|
119
|
+
const output = await howone.ai.generateImage.run({ prompt })
|
|
120
|
+
setStatus({ type: 'success', message: 'Done', output })
|
|
121
|
+
} catch (error) {
|
|
122
|
+
setStatus({
|
|
123
|
+
type: 'error',
|
|
124
|
+
message: error instanceof Error ? error.message : 'Generation failed',
|
|
125
|
+
})
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
For streaming workflows, use callbacks/events:
|
|
130
|
+
|
|
131
|
+
```ts
|
|
132
|
+
const session = howone.ai.generateImage.stream(
|
|
133
|
+
{ prompt },
|
|
134
|
+
{
|
|
135
|
+
onMessageChunk: (delta) => appendLog(delta),
|
|
136
|
+
onProgress: (progress) => setProgress(progress),
|
|
137
|
+
onError: (error) => setStatus({ type: 'error', message: error.message }),
|
|
138
|
+
onComplete: (result) => setResult(result.finalResult),
|
|
139
|
+
},
|
|
140
|
+
)
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
## Auth Adapter Contract
|
|
144
|
+
|
|
145
|
+
Use `AuthAdapter` for custom/headless auth. It is the only supported extension point for token
|
|
146
|
+
ownership outside the SDK defaults.
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
type AuthAdapter = {
|
|
150
|
+
name?: string
|
|
151
|
+
getToken?: () => string | null | Promise<string | null>
|
|
152
|
+
setToken?: (token: string | null) => void | Promise<void>
|
|
153
|
+
getUser?: (token: string | null) => AuthUser | null | Promise<AuthUser | null>
|
|
154
|
+
login?: (options?: { returnUrl?: string }) => void | Promise<void>
|
|
155
|
+
logout?: (options?: { redirect?: false | string | { url: string; external?: boolean } }) => void | Promise<void>
|
|
156
|
+
clearSession?: (options?: { redirect?: false | string | { url: string; external?: boolean } }) => void | Promise<void>
|
|
157
|
+
subscribe?: (listener: (state: AuthState) => void) => (() => void) | void
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Rules:
|
|
162
|
+
|
|
163
|
+
- Default hosted auth must work without an adapter.
|
|
164
|
+
- External providers must use `mode: 'headless'` plus `adapter`.
|
|
165
|
+
- Custom in-app HowOne login should usually use `mode: 'custom'`, `loginPath`, and SDK OTP/OAuth helpers.
|
|
166
|
+
- `client.me()` and `client.requireMe()` are the canonical user APIs.
|
|
167
|
+
- `client.auth.isAuthenticated()` is a quick token check, not a first-load user fetch.
|
|
168
|
+
|
|
169
|
+
## AI Agent Design Rules
|
|
170
|
+
|
|
171
|
+
Generated app code should have one stable SDK singleton:
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
import howone from '@/lib/sdk'
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Agents should prefer:
|
|
178
|
+
|
|
179
|
+
1. `howone.entities.*` for private/authenticated data;
|
|
180
|
+
2. `howone.public.entities.*` for public access;
|
|
181
|
+
3. `pickEntityPayload()` / `assertEntityPayload()` when mapping broad UI or AI objects to entity writes;
|
|
182
|
+
4. `assertPublicEntityQuery()` when generated code has access to the synced definition;
|
|
183
|
+
5. `howone.ai.*` for workflow execution;
|
|
184
|
+
6. `runAiActionAndPersist()` when the product needs durable AI history;
|
|
185
|
+
7. `howone.upload.*` for files;
|
|
186
|
+
8. `howone.schema.*` for schema tools;
|
|
187
|
+
9. `howone.raw` only as escape hatch.
|
|
188
|
+
|
|
189
|
+
Agents must not:
|
|
190
|
+
|
|
191
|
+
- hardcode HowOne URLs;
|
|
192
|
+
- manually build workflow SSE URLs;
|
|
193
|
+
- call workflows by display name instead of UUID;
|
|
194
|
+
- persist UI-only or workflow-extra fields;
|
|
195
|
+
- add frontend UI APIs to the SDK;
|
|
196
|
+
- remove the default HowOne floating logo unless explicitly asked.
|
|
197
|
+
|
|
198
|
+
## Adding New SDK Capabilities
|
|
199
|
+
|
|
200
|
+
When adding a new capability, choose one of these shapes:
|
|
201
|
+
|
|
202
|
+
```ts
|
|
203
|
+
client.capability.method(input, options)
|
|
204
|
+
client.capability.stream(input, callbacks)
|
|
205
|
+
client.capability.configure(adapter)
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
Prefer these names:
|
|
209
|
+
|
|
210
|
+
- `run` for one-shot AI/workflow execution;
|
|
211
|
+
- `stream` for session-based execution with callbacks;
|
|
212
|
+
- `events` for async iterables;
|
|
213
|
+
- `query/list/get/create/update/delete` for entities;
|
|
214
|
+
- `configure` only for adapters, not app UI.
|
|
215
|
+
|
|
216
|
+
Keep returned values serializable and obvious. AI agents should be able to inspect the method name
|
|
217
|
+
and infer the contract.
|
|
218
|
+
|
|
219
|
+
## Compatibility Rule
|
|
220
|
+
|
|
221
|
+
Do not break existing generated apps lightly. Prefer:
|
|
222
|
+
|
|
223
|
+
- add new adapter/callback options;
|
|
224
|
+
- keep old string shorthand (`auth: 'custom'`) working;
|
|
225
|
+
- mark old UI props as deprecated/no-op only when needed;
|
|
226
|
+
- update this skill and the relevant numbered reference in the same change.
|