@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,418 @@
|
|
|
1
|
+
# Auth
|
|
2
|
+
|
|
3
|
+
## Environment (read this first — dev must not hit prod)
|
|
4
|
+
|
|
5
|
+
All auth APIs (`sendEmailVerificationCode`, `loginWithEmailCode`, `unifiedAuth.*`, `howone.auth.logout` revoke) use the **same `env` as `createClient`**, not the browser hostname and not a frozen default.
|
|
6
|
+
|
|
7
|
+
| `VITE_HOWONE_ENV` / `createClient({ env })` | Auth REST API origin | Hosted login root (`auth: 'hosted'`) |
|
|
8
|
+
|---------------------------------------------|----------------------|--------------------------------------|
|
|
9
|
+
| `local` | `http://localhost:3002` | `https://howone.dev` |
|
|
10
|
+
| `dev` | `https://api.howone.dev` | `https://howone.dev` |
|
|
11
|
+
| `prod` | `https://api.howone.ai` | `https://howone.ai` |
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
// src/lib/sdk.ts — canonical (no extra auth fields required)
|
|
15
|
+
const client = createClient({
|
|
16
|
+
projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
|
|
17
|
+
env: import.meta.env.VITE_HOWONE_ENV,
|
|
18
|
+
})
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Defaults when `auth` is omitted:
|
|
22
|
+
|
|
23
|
+
- Auth mode: **hosted** — login/logout redirect to HowOne (`howone.dev` / `howone.ai` by `env`)
|
|
24
|
+
- Auth APIs still follow `env` (`dev` → `api.howone.dev`, `prod` → `api.howone.ai`)
|
|
25
|
+
|
|
26
|
+
Custom in-app login UI is **opt-in**: `auth: 'custom'` (see below).
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
// main.tsx
|
|
30
|
+
import './lib/sdk' // registers env first
|
|
31
|
+
import { sendEmailVerificationCode } from '@howone/sdk'
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Rules for agents:
|
|
35
|
+
|
|
36
|
+
- **Do not** hardcode `api.howone.ai` or `howone.ai` in app code.
|
|
37
|
+
- **Do not** import auth helpers before `./lib/sdk` (env would stay default `prod`).
|
|
38
|
+
- **Do not** rely on `localhost` hostname to pick `local`; use `env: 'local'` or `env: 'dev'` explicitly.
|
|
39
|
+
- Entity, AI, upload, and auth endpoints all follow this single `env` pin.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Custom login (opt-in only)
|
|
44
|
+
|
|
45
|
+
Add `auth: 'custom'` when the app renders its own `/login` page but still uses HowOne OTP/OAuth APIs:
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
const client = createClient({
|
|
49
|
+
projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
|
|
50
|
+
env: import.meta.env.VITE_HOWONE_ENV,
|
|
51
|
+
auth: 'custom',
|
|
52
|
+
loginPath: '/login',
|
|
53
|
+
})
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
That wires:
|
|
57
|
+
|
|
58
|
+
| Behavior | Result |
|
|
59
|
+
|----------|--------|
|
|
60
|
+
| `howone.auth.logout()` | Clears token + revokes server session → stays on your app → navigates to `loginPath` |
|
|
61
|
+
| `howone.auth.login()` | Navigates to `loginPath` (never howone.dev / howone.ai) |
|
|
62
|
+
| `HowOneProvider` `useHowoneContext().logout()` | Same as `howone.auth.logout()` when `createClient` ran first |
|
|
63
|
+
|
|
64
|
+
Pair with React:
|
|
65
|
+
|
|
66
|
+
```tsx
|
|
67
|
+
<HowOneProvider client={howone} brand="visible">
|
|
68
|
+
<App />
|
|
69
|
+
</HowOneProvider>
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The Provider derives its route guard from `client.auth.guard`; custom/headless clients default to no
|
|
73
|
+
hosted redirect. Override `auth="none"` only when the app deliberately owns route guards. Keep
|
|
74
|
+
`brand="visible"` unless the user explicitly asks to hide the bottom-right HowOne logo.
|
|
75
|
+
|
|
76
|
+
| `createClient({ auth })` | Login UI | `auth.login()` | `auth.logout()` default redirect |
|
|
77
|
+
|--------------------------|----------|----------------|----------------------------------|
|
|
78
|
+
| *(omit)* | **HowOne hosted** | → howone `/auth` | → howone `/auth` |
|
|
79
|
+
| `'custom'` | Your `/login` + HowOne APIs | → `loginPath` | → `loginPath` |
|
|
80
|
+
| `'hosted'` | HowOne hosted (same as default) | → howone `/auth` | → howone `/auth` |
|
|
81
|
+
| `'headless'` | External (Clerk, etc.) | no-op | no redirect |
|
|
82
|
+
| `'none'` | N/A (public app) | no-op | no redirect |
|
|
83
|
+
|
|
84
|
+
Legacy alias: `'managed'` → `'hosted'`.
|
|
85
|
+
|
|
86
|
+
### Advanced object form
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
auth: {
|
|
90
|
+
mode: 'custom',
|
|
91
|
+
loginPath: '/sign-in',
|
|
92
|
+
logoutPath: '/sign-in', // optional; defaults to loginPath
|
|
93
|
+
guard: 'required', // optional; Provider inherits this when passed client={howone}
|
|
94
|
+
getToken: async () => null, // only for headless
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## Two auth layers
|
|
101
|
+
|
|
102
|
+
1. **`createClient({ auth })`** — strategy for login/logout destinations (hosted vs custom).
|
|
103
|
+
2. **`unifiedAuth` / standalone OTP & OAuth functions** — headless APIs to build your login UI.
|
|
104
|
+
|
|
105
|
+
React: `HowOneProvider` + `useHowoneContext` — route guard only (`auth="required" | "optional" | "none"`).
|
|
106
|
+
|
|
107
|
+
The underlying SDK auth state is managed by `AuthManager`. App code normally uses `client.auth`,
|
|
108
|
+
`client.me()`, `client.requireMe()`, and `HowOneProvider`; SDK contributors use `AuthAdapter` when
|
|
109
|
+
custom token ownership is required.
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## `client.auth` API
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
import howone from '@/lib/sdk'
|
|
117
|
+
|
|
118
|
+
howone.auth.mode // 'custom' | 'hosted' | 'headless' | 'none'
|
|
119
|
+
howone.auth.guard // 'required' | 'optional' | 'none'
|
|
120
|
+
howone.auth.loginPath // e.g. '/login'
|
|
121
|
+
howone.auth.logoutPath // e.g. '/login'
|
|
122
|
+
|
|
123
|
+
howone.auth.setToken(jwt)
|
|
124
|
+
howone.auth.getToken()
|
|
125
|
+
howone.auth.isAuthenticated()
|
|
126
|
+
|
|
127
|
+
howone.auth.login(returnUrl?) // respects auth mode
|
|
128
|
+
await howone.auth.logout() // respects auth mode
|
|
129
|
+
await howone.auth.clearSession() // clear only; redirect: false
|
|
130
|
+
await howone.auth.clearSession({ redirect: '/goodbye' })
|
|
131
|
+
await howone.auth.logout({ redirect: false })
|
|
132
|
+
howone.auth.subscribe((state) => {
|
|
133
|
+
// state: { token, user, isAuthenticated, isLoading }
|
|
134
|
+
})
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## AuthManager / AuthAdapter extension point
|
|
140
|
+
|
|
141
|
+
Use an adapter when the token is owned outside the default HowOne local session, for example an
|
|
142
|
+
external auth provider, embedded shell, native app bridge, or custom host application.
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
const client = createClient({
|
|
146
|
+
projectId,
|
|
147
|
+
env,
|
|
148
|
+
auth: {
|
|
149
|
+
mode: 'headless',
|
|
150
|
+
adapter: {
|
|
151
|
+
name: 'external-auth',
|
|
152
|
+
getToken: () => externalAuth.getToken(),
|
|
153
|
+
setToken: (token) => externalAuth.setToken(token),
|
|
154
|
+
getUser: async (token) => externalAuth.getUser(token),
|
|
155
|
+
login: ({ returnUrl } = {}) => {
|
|
156
|
+
router.push(`/login?redirect=${encodeURIComponent(returnUrl ?? '/')}`)
|
|
157
|
+
},
|
|
158
|
+
logout: () => {
|
|
159
|
+
externalAuth.clear()
|
|
160
|
+
router.push('/')
|
|
161
|
+
},
|
|
162
|
+
subscribe: (listener) => externalAuth.onChange(() => {
|
|
163
|
+
listener({
|
|
164
|
+
token: externalAuth.getToken(),
|
|
165
|
+
user: externalAuth.getUserSync(),
|
|
166
|
+
isAuthenticated: Boolean(externalAuth.getToken()),
|
|
167
|
+
isLoading: false,
|
|
168
|
+
})
|
|
169
|
+
}),
|
|
170
|
+
},
|
|
171
|
+
tokenCacheMs: 30_000,
|
|
172
|
+
},
|
|
173
|
+
})
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Adapter rules:
|
|
177
|
+
|
|
178
|
+
- Use `mode: 'headless'` for external token providers.
|
|
179
|
+
- Use `mode: 'custom'` for in-app login pages that still call HowOne OTP/OAuth APIs.
|
|
180
|
+
- Do not create extra token storage keys in app code. Route all token writes through `client.auth.setToken()`.
|
|
181
|
+
- Do not implement app UI in the adapter. It may navigate or notify through callbacks, but visible UI belongs to the app.
|
|
182
|
+
- `getToken` may be sync or async; the SDK caches external tokens according to `tokenCacheMs`.
|
|
183
|
+
- `subscribe` is optional but recommended when the external auth provider can change outside SDK calls.
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## Custom login page (full pattern for AI codegen)
|
|
188
|
+
|
|
189
|
+
### 1. SDK (`src/lib/sdk.ts`)
|
|
190
|
+
|
|
191
|
+
```ts
|
|
192
|
+
import { createClient, defineEntities, withEntities } from '@howone/sdk'
|
|
193
|
+
|
|
194
|
+
const client = createClient({
|
|
195
|
+
projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
|
|
196
|
+
env: import.meta.env.VITE_HOWONE_ENV,
|
|
197
|
+
auth: 'custom',
|
|
198
|
+
loginPath: '/login',
|
|
199
|
+
})
|
|
200
|
+
|
|
201
|
+
export default withEntities(client, defineEntities({ /* ... */ }))
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
### 2. Provider (`main.tsx`)
|
|
205
|
+
|
|
206
|
+
```tsx
|
|
207
|
+
import { HowOneProvider } from '@howone/sdk/react'
|
|
208
|
+
import howone from './lib/sdk'
|
|
209
|
+
|
|
210
|
+
<HowOneProvider client={howone} brand="visible">
|
|
211
|
+
<App />
|
|
212
|
+
</HowOneProvider>
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
### 3. Login route (`/login`) — your styles, HowOne APIs
|
|
216
|
+
|
|
217
|
+
```tsx
|
|
218
|
+
import {
|
|
219
|
+
sendEmailVerificationCode,
|
|
220
|
+
loginWithEmailCode,
|
|
221
|
+
unifiedAuth,
|
|
222
|
+
} from '@howone/sdk'
|
|
223
|
+
import howone from '@/lib/sdk'
|
|
224
|
+
|
|
225
|
+
// Email OTP
|
|
226
|
+
const send = await sendEmailVerificationCode(email)
|
|
227
|
+
const result = await loginWithEmailCode(email, code)
|
|
228
|
+
if (result.success && result.token) {
|
|
229
|
+
howone.auth.setToken(result.token)
|
|
230
|
+
const user = await howone.me({ refresh: true })
|
|
231
|
+
navigate('/')
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
// Google (popup — user stays on your page)
|
|
235
|
+
const { token } = await unifiedAuth.initiateGoogleLogin()
|
|
236
|
+
howone.auth.setToken(token)
|
|
237
|
+
|
|
238
|
+
// GitHub
|
|
239
|
+
const { token } = await unifiedAuth.initiateGitHubLogin()
|
|
240
|
+
howone.auth.setToken(token)
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Phone OTP: `sendPhoneVerificationCode` + `loginWithPhoneCode` (E.164, e.g. `+8613800138000`).
|
|
244
|
+
|
|
245
|
+
OAuth full-page callback (optional route `/auth/callback`):
|
|
246
|
+
|
|
247
|
+
```ts
|
|
248
|
+
import { unifiedOAuth } from '@howone/sdk'
|
|
249
|
+
|
|
250
|
+
const result = unifiedOAuth.checkOAuthCallback()
|
|
251
|
+
if (result.success && result.token) {
|
|
252
|
+
howone.auth.setToken(result.token)
|
|
253
|
+
navigate('/')
|
|
254
|
+
}
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
### 4. Protected routes
|
|
258
|
+
|
|
259
|
+
```tsx
|
|
260
|
+
useEffect(() => {
|
|
261
|
+
howone.me()
|
|
262
|
+
.then(setUser)
|
|
263
|
+
.catch(() => navigate('/login', { replace: true }))
|
|
264
|
+
}, [])
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
Use `howone.me()`, not `howone.auth.isAuthenticated()`, for first load.
|
|
268
|
+
|
|
269
|
+
### 5. Logout button
|
|
270
|
+
|
|
271
|
+
```ts
|
|
272
|
+
await howone.auth.logout()
|
|
273
|
+
// custom mode: already navigates to loginPath; no howone.dev redirect
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
Do **not** call hosted-only patterns when `auth: 'custom'` is set:
|
|
277
|
+
|
|
278
|
+
- ~~`howone.auth.login()` expecting howone.ai~~ (goes to `/login` instead — OK)
|
|
279
|
+
- ~~Manual `window.location` to howone.dev~~
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
## Hosted login (default)
|
|
284
|
+
|
|
285
|
+
Omit `auth` — this is the default for `createClient({ projectId, env })`:
|
|
286
|
+
|
|
287
|
+
```ts
|
|
288
|
+
createClient({ projectId, env })
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
```tsx
|
|
292
|
+
<HowOneProvider client={howone}>
|
|
293
|
+
<App />
|
|
294
|
+
</HowOneProvider>
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
Unauthenticated users redirect to HowOne hosted `/auth`.
|
|
298
|
+
|
|
299
|
+
---
|
|
300
|
+
|
|
301
|
+
## Headless external auth
|
|
302
|
+
|
|
303
|
+
```ts
|
|
304
|
+
createClient({
|
|
305
|
+
projectId,
|
|
306
|
+
env,
|
|
307
|
+
auth: {
|
|
308
|
+
mode: 'headless',
|
|
309
|
+
adapter: {
|
|
310
|
+
getToken: async () => externalAuth.getJwt(),
|
|
311
|
+
login: ({ returnUrl } = {}) => externalAuth.login({ returnUrl }),
|
|
312
|
+
logout: () => externalAuth.logout(),
|
|
313
|
+
},
|
|
314
|
+
tokenCacheMs: 30_000,
|
|
315
|
+
},
|
|
316
|
+
})
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
Do not use `howone.auth.setToken` for Clerk/Supabase unless bridging into HowOne JWT.
|
|
320
|
+
|
|
321
|
+
Headless mode should not redirect to HowOne hosted auth by default. The external adapter decides
|
|
322
|
+
what `login` and `logout` mean.
|
|
323
|
+
|
|
324
|
+
---
|
|
325
|
+
|
|
326
|
+
## Email / phone / OAuth API reference
|
|
327
|
+
|
|
328
|
+
(Same as before — see sections below for request/response shapes.)
|
|
329
|
+
|
|
330
|
+
### Email OTP
|
|
331
|
+
|
|
332
|
+
```ts
|
|
333
|
+
import { sendEmailVerificationCode, loginWithEmailCode } from '@howone/sdk'
|
|
334
|
+
|
|
335
|
+
await sendEmailVerificationCode(email, appName?)
|
|
336
|
+
const result = await loginWithEmailCode(email, code)
|
|
337
|
+
// result.token on success → howone.auth.setToken(result.token)
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
### Phone OTP
|
|
341
|
+
|
|
342
|
+
```ts
|
|
343
|
+
import { sendPhoneVerificationCode, loginWithPhoneCode } from '@howone/sdk'
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
### OAuth popup
|
|
347
|
+
|
|
348
|
+
```ts
|
|
349
|
+
import { unifiedAuth } from '@howone/sdk'
|
|
350
|
+
|
|
351
|
+
await unifiedAuth.initiateGoogleLogin()
|
|
352
|
+
await unifiedAuth.initiateGitHubLogin()
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
### Server logout
|
|
356
|
+
|
|
357
|
+
```ts
|
|
358
|
+
import { unifiedAuth } from '@howone/sdk'
|
|
359
|
+
|
|
360
|
+
const token = howone.auth.getToken()
|
|
361
|
+
if (token) await unifiedAuth.logout(token)
|
|
362
|
+
await howone.auth.logout()
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
With `auth: 'custom'`, `howone.auth.logout()` already revokes and navigates locally.
|
|
366
|
+
|
|
367
|
+
---
|
|
368
|
+
|
|
369
|
+
## User profile
|
|
370
|
+
|
|
371
|
+
```ts
|
|
372
|
+
const user = await howone.me()
|
|
373
|
+
const user = await howone.requireMe() // throws HowOneAuthError
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
---
|
|
377
|
+
|
|
378
|
+
## HowOneAuthError
|
|
379
|
+
|
|
380
|
+
```ts
|
|
381
|
+
import { HowOneAuthError } from '@howone/sdk'
|
|
382
|
+
|
|
383
|
+
try {
|
|
384
|
+
await howone.requireMe()
|
|
385
|
+
} catch (err) {
|
|
386
|
+
if (err instanceof HowOneAuthError) {
|
|
387
|
+
howone.auth.login() // custom → /login; hosted → howone.ai
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
---
|
|
393
|
+
|
|
394
|
+
## Common mistakes (AI agents)
|
|
395
|
+
|
|
396
|
+
| Mistake | Fix |
|
|
397
|
+
|---------|-----|
|
|
398
|
+
| Custom `/login` page with HowOne OTP/OAuth | Add `auth: 'custom'` in `createClient` |
|
|
399
|
+
| Provider without `client={howone}` | Pass the composed client so auth strategy and guard are instance-consistent |
|
|
400
|
+
| `howone.auth.logout()` expecting no redirect before this change | Now respects `auth: 'custom'` |
|
|
401
|
+
| `auth.isAuthenticated()` on first paint | Use `await howone.me()` |
|
|
402
|
+
| Phone without country code | E.164 `+86...` |
|
|
403
|
+
| JSON Schema in `defineAiAction` | Convert manifest JSON Schema to Zod |
|
|
404
|
+
| Second localStorage key for token | Only `howone.auth.setToken` |
|
|
405
|
+
| Custom external provider wired with `getToken` only but no logout | Add an `adapter.logout` if the host owns session clearing |
|
|
406
|
+
| App UI inside SDK auth adapter | Move UI to frontend components and use callbacks/navigation only |
|
|
407
|
+
|
|
408
|
+
---
|
|
409
|
+
|
|
410
|
+
## Non-negotiable for agents
|
|
411
|
+
|
|
412
|
+
- Default **`createClient({ projectId, env })`** = HowOne hosted login. Add **`auth: 'custom'`** only for in-app login pages.
|
|
413
|
+
- Never hardcode howone.dev / howone.ai URLs in app login/logout when `auth: 'custom'`.
|
|
414
|
+
- Implement login UI with `sendEmailVerificationCode` / `loginWithEmailCode` / `unifiedAuth` — not iframe to hosted auth.
|
|
415
|
+
- After any successful login: `howone.auth.setToken(token)` then `await howone.me({ refresh: true })`.
|
|
416
|
+
- Logout: `await howone.auth.logout()` only (no manual redirect needed when `auth: 'custom'`).
|
|
417
|
+
- For external auth, use `auth.adapter`; do not patch request headers manually.
|
|
418
|
+
- SDK auth exposes state/callbacks only. Visible feedback, loading spinners, account menus, and errors are frontend app code.
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
# React Integration
|
|
2
|
+
|
|
3
|
+
Use this track for the application shell, auth context, and optional element-selector devtools.
|
|
4
|
+
Read `01-client-setup.md` first and initialize `src/lib/sdk.ts` before rendering the Provider.
|
|
5
|
+
|
|
6
|
+
## Package boundaries
|
|
7
|
+
|
|
8
|
+
Keep imports on the smallest entry point:
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
import { createClient } from '@howone/sdk' // framework-neutral core
|
|
12
|
+
import { HowOneProvider, useHowoneContext } from '@howone/sdk/react'
|
|
13
|
+
import { ElementSelectorProvider } from '@howone/sdk/devtools' // optional editor tooling
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
The core package must remain usable in workers, tests, and non-React apps. Do not import React
|
|
17
|
+
components from `@howone/sdk` or selector tooling from `/react`.
|
|
18
|
+
|
|
19
|
+
## Root wiring
|
|
20
|
+
|
|
21
|
+
```tsx
|
|
22
|
+
import howone from '@/lib/sdk'
|
|
23
|
+
import { ElementSelectorProvider } from '@howone/sdk/devtools'
|
|
24
|
+
import { HowOneProvider } from '@howone/sdk/react'
|
|
25
|
+
|
|
26
|
+
export function AppRoot() {
|
|
27
|
+
return (
|
|
28
|
+
<ElementSelectorProvider>
|
|
29
|
+
<HowOneProvider client={howone} brand="visible">
|
|
30
|
+
<App />
|
|
31
|
+
</HowOneProvider>
|
|
32
|
+
</ElementSelectorProvider>
|
|
33
|
+
)
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`ElementSelectorProvider` is optional and should be present when the app is edited through the
|
|
38
|
+
HowOne iframe/editor integration. It is independent from auth. `HowOneProvider` is required when
|
|
39
|
+
the app uses any HowOne runtime surface.
|
|
40
|
+
|
|
41
|
+
The Provider waits until its auth URL/cookie check completes. With `auth="required"`, protected
|
|
42
|
+
children are not briefly rendered before redirect. By default it derives the guard from
|
|
43
|
+
`client.auth.guard`:
|
|
44
|
+
|
|
45
|
+
| Client auth | Default Provider guard | Use |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| hosted | required | hosted login protects the app |
|
|
48
|
+
| custom/headless | none | app or adapter owns login UI |
|
|
49
|
+
| none | none | public app |
|
|
50
|
+
|
|
51
|
+
Override deliberately when a single app has a public shell and protected routes:
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
<HowOneProvider client={howone} auth="optional" brand="visible">
|
|
55
|
+
<App />
|
|
56
|
+
</HowOneProvider>
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`auth` is only a route guard. It does not change the client's login strategy. Login/logout
|
|
60
|
+
destinations come from `createClient({ auth, loginPath, logoutPath })`.
|
|
61
|
+
|
|
62
|
+
## Provider props
|
|
63
|
+
|
|
64
|
+
```ts
|
|
65
|
+
type HowOneProviderProps = {
|
|
66
|
+
children: React.ReactNode
|
|
67
|
+
client?: HowOneClient
|
|
68
|
+
auth?: 'required' | 'optional' | 'none'
|
|
69
|
+
brand?: 'visible' | 'hidden'
|
|
70
|
+
showBrandButton?: boolean
|
|
71
|
+
onAuthStateChange?: (state: AuthState) => void
|
|
72
|
+
onAuthRedirect?: (info: { mode: 'hosted' | 'custom'; returnUrl: string }) => void
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`projectId` is retained only as a deprecated compatibility path when no client is passed. New app
|
|
77
|
+
code must pass `client`. Theme ownership belongs to the app's ThemeProvider; the HowOne Provider
|
|
78
|
+
does not accept or silently ignore theme props.
|
|
79
|
+
|
|
80
|
+
The floating HowOne brand button is visible by default. Hide it only when product requirements say
|
|
81
|
+
so:
|
|
82
|
+
|
|
83
|
+
```tsx
|
|
84
|
+
<HowOneProvider client={howone} brand="hidden">
|
|
85
|
+
<App />
|
|
86
|
+
</HowOneProvider>
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The Provider does not own toasts, dialogs, loading overlays, route components, or app-specific login
|
|
90
|
+
screens. Render those in the app and use SDK callbacks/results as signals.
|
|
91
|
+
|
|
92
|
+
## Context and logout
|
|
93
|
+
|
|
94
|
+
```tsx
|
|
95
|
+
import { useHowoneContext } from '@howone/sdk/react'
|
|
96
|
+
|
|
97
|
+
function AccountButton() {
|
|
98
|
+
const { user, isAuthenticated, logout } = useHowoneContext()
|
|
99
|
+
if (!isAuthenticated) return <a href="/login">Sign in</a>
|
|
100
|
+
return <button onClick={() => void logout()}>{user?.name || 'Sign out'}</button>
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`useHowoneContext()` intentionally throws when called outside the Provider. This catches broken
|
|
105
|
+
tree wiring immediately; do not add a global-token fallback.
|
|
106
|
+
|
|
107
|
+
For non-React code, use `howone.auth.*`, `howone.me()`, and `howone.requireMe()` from the singleton.
|
|
108
|
+
`useAuth` remains a compatibility hook on `/react`, but `useHowoneContext` is preferred because it
|
|
109
|
+
is bound to the client instance.
|
|
110
|
+
|
|
111
|
+
## Auth state and routes
|
|
112
|
+
|
|
113
|
+
- Hosted auth: let `HowOneProvider client={howone}` redirect.
|
|
114
|
+
- Custom auth: use `auth: 'custom'`, render the app's login route, obtain OTP/OAuth tokens through
|
|
115
|
+
the SDK or adapter, and call `howone.auth.setToken(token)`.
|
|
116
|
+
- Headless auth: adapter owns token refresh; an opaque token is accepted, while JWT expiration is
|
|
117
|
+
checked by the SDK.
|
|
118
|
+
- Public app: use `auth: 'none'` and do not add a fake login screen.
|
|
119
|
+
|
|
120
|
+
If a custom login page needs a route guard, use `howone.auth.isAuthenticated()` or
|
|
121
|
+
`howone.me()` rather than manually parsing ownership fields.
|
|
122
|
+
|
|
123
|
+
## Element selector security
|
|
124
|
+
|
|
125
|
+
`ElementSelectorProvider` accepts `allowedOrigins` and `targetOrigin` for cross-window messages.
|
|
126
|
+
The default trusts same-origin and the `document.referrer` origin. Use explicit origins in embedded
|
|
127
|
+
multi-tenant deployments; never reintroduce `'*'` for messages carrying selected element data.
|
|
128
|
+
|
|
129
|
+
## Common mistakes
|
|
130
|
+
|
|
131
|
+
| Mistake | Correct pattern |
|
|
132
|
+
|---|---|
|
|
133
|
+
| Provider without `client` | Pass the exported composed singleton. |
|
|
134
|
+
| `auth="required"` on a public client | Let the client guard default to `none`, or explicitly use `auth="optional"`. |
|
|
135
|
+
| Custom login plus hosted redirect | `auth: 'custom'` and Provider `auth="none"`/derived guard. |
|
|
136
|
+
| Importing `ElementSelectorProvider` from `/react` | Import it from `@howone/sdk/devtools`. |
|
|
137
|
+
| Calling `useHowoneContext` above the Provider | Move the component below the root Provider. |
|
|
138
|
+
| Passing `theme`, `themeStorageKey`, or `forceTheme` | Configure the app's own ThemeProvider. |
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# File Upload
|
|
2
|
+
|
|
3
|
+
Use `howone.upload` for HowOne storage. Upload first, then persist the returned CDN URL in an
|
|
4
|
+
entity. Uploads require a real authenticated token unless the backend explicitly exposes a public
|
|
5
|
+
upload contract.
|
|
6
|
+
|
|
7
|
+
## Contract
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
type UploadableFile = File | Blob | string // string = data URL or source URL
|
|
11
|
+
|
|
12
|
+
type UploadOptions = {
|
|
13
|
+
onProgress?: (percent: number) => void
|
|
14
|
+
signal?: AbortSignal
|
|
15
|
+
metadata?: Record<string, unknown>
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
type UploadResponse = {
|
|
19
|
+
url: string
|
|
20
|
+
thumbnailUrl?: string
|
|
21
|
+
id?: string
|
|
22
|
+
size?: number
|
|
23
|
+
mimeType?: string
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
type BatchUploadOptions = {
|
|
27
|
+
files: UploadableFile[]
|
|
28
|
+
concurrent?: number // positive integer; default 3
|
|
29
|
+
onProgress?: (completed: number, total: number) => void
|
|
30
|
+
onFileComplete?: (result: UploadResponse | Error, index: number) => void
|
|
31
|
+
signal?: AbortSignal
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Both data-only responses and `{ data: ... }` envelopes are normalized. The response must contain
|
|
36
|
+
`publicUrl` or `url`; malformed responses throw instead of returning an undefined URL.
|
|
37
|
+
|
|
38
|
+
## Single and image upload
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
const uploaded = await howone.upload.file(file, {
|
|
42
|
+
metadata: { category: 'cover' },
|
|
43
|
+
onProgress: setProgress,
|
|
44
|
+
signal: controller.signal,
|
|
45
|
+
})
|
|
46
|
+
|
|
47
|
+
await howone.entities.Story.update(storyId, { coverUrl: uploaded.url })
|
|
48
|
+
|
|
49
|
+
// image is a convenience alias and returns the same full UploadResponse shape.
|
|
50
|
+
const image = await howone.upload.image(imageFile, { onProgress: setProgress })
|
|
51
|
+
console.log(image.url, image.thumbnailUrl, image.id)
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`onProgress` fires only when the transport reports a total byte count. Keep a separate loading
|
|
55
|
+
state so an upload without a computable total does not appear stuck.
|
|
56
|
+
|
|
57
|
+
```tsx
|
|
58
|
+
const controller = new AbortController()
|
|
59
|
+
try {
|
|
60
|
+
setUploading(true)
|
|
61
|
+
const { url } = await howone.upload.file(file, {
|
|
62
|
+
signal: controller.signal,
|
|
63
|
+
onProgress: setProgress,
|
|
64
|
+
})
|
|
65
|
+
await howone.entities.Asset.create({ url, kind: 'image' })
|
|
66
|
+
} catch (error) {
|
|
67
|
+
if (!controller.signal.aborted) setError(error instanceof Error ? error.message : String(error))
|
|
68
|
+
} finally {
|
|
69
|
+
setUploading(false)
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Batch upload
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
const result = await howone.upload.batch({
|
|
77
|
+
files: Array.from(input.files ?? []),
|
|
78
|
+
concurrent: 3,
|
|
79
|
+
onProgress: (completed, total) => setProgress(Math.round((completed / total) * 100)),
|
|
80
|
+
onFileComplete: (value, index) => {
|
|
81
|
+
if (value instanceof Error) console.error('file failed', index, value.message)
|
|
82
|
+
},
|
|
83
|
+
})
|
|
84
|
+
|
|
85
|
+
const urls = result.success.map((file) => file.url)
|
|
86
|
+
if (result.failed.length) showPartialFailure(result.failed)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`concurrent` must be a positive integer. The result is intentionally partial: successful files are
|
|
90
|
+
kept even when others fail. An aborted batch stops starting later batches and in-flight uploads
|
|
91
|
+
observe the same signal; do not assume every requested file has a corresponding failure entry.
|
|
92
|
+
|
|
93
|
+
## AI image workflow pattern
|
|
94
|
+
|
|
95
|
+
AI output URLs are not automatically HowOne storage records. If the product needs durable storage:
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
const output = await howone.ai.generateImage.run(input)
|
|
99
|
+
const stored = await howone.upload.image(output.imageUrl)
|
|
100
|
+
await howone.entities.Generation.update(generationId, { imageUrl: stored.url })
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Common mistakes
|
|
104
|
+
|
|
105
|
+
| Mistake | Fix |
|
|
106
|
+
|---|---|
|
|
107
|
+
| Saving a `blob:` URL | Persist the returned `UploadResponse.url`. |
|
|
108
|
+
| Assuming `upload.image` returns only `{ url }` | It returns the full upload response; destructuring `{ url }` remains valid. |
|
|
109
|
+
| Passing `metadata` with owner/system fields | Keep metadata app-owned; entity ownership is derived by the backend. |
|
|
110
|
+
| Using `concurrent: 0` | Use a positive integer. |
|
|
111
|
+
| Ignoring `failed` | Batch uploads are partial; handle both arrays. |
|
|
112
|
+
| Forgetting cleanup on unmount | Abort with a controller owned by the component. |
|