@howone/agent-cli 0.0.0-stage → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (228) hide show
  1. package/README.md +49 -2
  2. package/bin/index.d.mts +1 -0
  3. package/bin/index.mjs +2397 -0
  4. package/package.json +55 -4
  5. package/skills/howone/01-apps.md +29 -0
  6. package/skills/howone/02-develop.md +107 -0
  7. package/skills/howone/03-workflows.md +71 -0
  8. package/skills/howone/04-functions-and-data.md +41 -0
  9. package/skills/howone/05-capabilities.md +46 -0
  10. package/skills/howone/SKILL.md +52 -0
  11. package/templates/vite/.howone/skills/hallmark/SKILL.md +557 -0
  12. package/templates/vite/.howone/skills/hallmark/references/anti-patterns.md +418 -0
  13. package/templates/vite/.howone/skills/hallmark/references/assets.md +406 -0
  14. package/templates/vite/.howone/skills/hallmark/references/color.md +95 -0
  15. package/templates/vite/.howone/skills/hallmark/references/component-cookbook.md +265 -0
  16. package/templates/vite/.howone/skills/hallmark/references/components/c1-outlined-chip.md +12 -0
  17. package/templates/vite/.howone/skills/hallmark/references/components/c2-inline-form-as-cta.md +16 -0
  18. package/templates/vite/.howone/skills/hallmark/references/components/c3-typographic-link.md +8 -0
  19. package/templates/vite/.howone/skills/hallmark/references/components/c4-sticky-bottom-bar.md +16 -0
  20. package/templates/vite/.howone/skills/hallmark/references/components/f1-bento-grid.md +20 -0
  21. package/templates/vite/.howone/skills/hallmark/references/components/f2-sticky-scroll-stack.md +20 -0
  22. package/templates/vite/.howone/skills/hallmark/references/components/f3-tabular-spec-sheet.md +11 -0
  23. package/templates/vite/.howone/skills/hallmark/references/components/f4-step-sequence.md +11 -0
  24. package/templates/vite/.howone/skills/hallmark/references/components/f5-annotated-screenshot.md +11 -0
  25. package/templates/vite/.howone/skills/hallmark/references/components/f6-product-card-grid.md +41 -0
  26. package/templates/vite/.howone/skills/hallmark/references/components/ft1-mast-headed.md +13 -0
  27. package/templates/vite/.howone/skills/hallmark/references/components/ft2-inline-rule-single-line.md +10 -0
  28. package/templates/vite/.howone/skills/hallmark/references/components/ft3-index-style-category-list.md +12 -0
  29. package/templates/vite/.howone/skills/hallmark/references/components/ft4-dense-typographic.md +10 -0
  30. package/templates/vite/.howone/skills/hallmark/references/components/ft5-statement.md +21 -0
  31. package/templates/vite/.howone/skills/hallmark/references/components/ft6-letter-close.md +19 -0
  32. package/templates/vite/.howone/skills/hallmark/references/components/ft7-newsletter-first.md +27 -0
  33. package/templates/vite/.howone/skills/hallmark/references/components/ft8-marquee-scroll.md +25 -0
  34. package/templates/vite/.howone/skills/hallmark/references/components/h1-marquee.md +15 -0
  35. package/templates/vite/.howone/skills/hallmark/references/components/h2-split-diptych.md +15 -0
  36. package/templates/vite/.howone/skills/hallmark/references/components/h3-quote-led.md +11 -0
  37. package/templates/vite/.howone/skills/hallmark/references/components/h4-stat-led.md +14 -0
  38. package/templates/vite/.howone/skills/hallmark/references/components/h5-letter-hero.md +11 -0
  39. package/templates/vite/.howone/skills/hallmark/references/components/h6-photographic-fold.md +16 -0
  40. package/templates/vite/.howone/skills/hallmark/references/components/h7-demo-video-clipped-by-viewport-edge.md +27 -0
  41. package/templates/vite/.howone/skills/hallmark/references/components/h8-mockup-split-browser-framed.md +23 -0
  42. package/templates/vite/.howone/skills/hallmark/references/components/h9-custom-illustration-centerpiece.md +27 -0
  43. package/templates/vite/.howone/skills/hallmark/references/components/n1-wordmark-2-links.md +12 -0
  44. package/templates/vite/.howone/skills/hallmark/references/components/n10-floating-on-scroll-morph.md +19 -0
  45. package/templates/vite/.howone/skills/hallmark/references/components/n11-mega-menu.md +40 -0
  46. package/templates/vite/.howone/skills/hallmark/references/components/n12-banner-retract.md +34 -0
  47. package/templates/vite/.howone/skills/hallmark/references/components/n13-inline-cmdk-pill.md +39 -0
  48. package/templates/vite/.howone/skills/hallmark/references/components/n1b-saas-three-section.md +35 -0
  49. package/templates/vite/.howone/skills/hallmark/references/components/n2-floating-chip.md +14 -0
  50. package/templates/vite/.howone/skills/hallmark/references/components/n3-side-rail.md +14 -0
  51. package/templates/vite/.howone/skills/hallmark/references/components/n4-hidden-behind-k.md +9 -0
  52. package/templates/vite/.howone/skills/hallmark/references/components/n5-floating-pill.md +28 -0
  53. package/templates/vite/.howone/skills/hallmark/references/components/n6-newspaper-masthead.md +24 -0
  54. package/templates/vite/.howone/skills/hallmark/references/components/n7-brutal-slab.md +22 -0
  55. package/templates/vite/.howone/skills/hallmark/references/components/n8-terminal-command.md +21 -0
  56. package/templates/vite/.howone/skills/hallmark/references/components/n9-edge-aligned-minimal.md +17 -0
  57. package/templates/vite/.howone/skills/hallmark/references/components/s1-left-margin-numbered.md +15 -0
  58. package/templates/vite/.howone/skills/hallmark/references/components/s2-hanging.md +13 -0
  59. package/templates/vite/.howone/skills/hallmark/references/components/s3-sticky-pinned.md +19 -0
  60. package/templates/vite/.howone/skills/hallmark/references/components/s4-inline-no-break.md +11 -0
  61. package/templates/vite/.howone/skills/hallmark/references/components/s5-bottom-anchored.md +13 -0
  62. package/templates/vite/.howone/skills/hallmark/references/components/t1-pull-quote-with-marginalia.md +12 -0
  63. package/templates/vite/.howone/skills/hallmark/references/components/t2-logo-wall-hairline.md +19 -0
  64. package/templates/vite/.howone/skills/hallmark/references/components/t3-single-huge-quote.md +11 -0
  65. package/templates/vite/.howone/skills/hallmark/references/components/t4-numbered-stat-strip.md +14 -0
  66. package/templates/vite/.howone/skills/hallmark/references/contract.md +24 -0
  67. package/templates/vite/.howone/skills/hallmark/references/copy.md +182 -0
  68. package/templates/vite/.howone/skills/hallmark/references/custom-craft.md +626 -0
  69. package/templates/vite/.howone/skills/hallmark/references/custom-theme.md +367 -0
  70. package/templates/vite/.howone/skills/hallmark/references/design-md.md +116 -0
  71. package/templates/vite/.howone/skills/hallmark/references/export-formats.md +328 -0
  72. package/templates/vite/.howone/skills/hallmark/references/floating-nav.md +89 -0
  73. package/templates/vite/.howone/skills/hallmark/references/genres/atmospheric.md +69 -0
  74. package/templates/vite/.howone/skills/hallmark/references/genres/editorial.md +72 -0
  75. package/templates/vite/.howone/skills/hallmark/references/genres/modern-minimal.md +71 -0
  76. package/templates/vite/.howone/skills/hallmark/references/genres/playful.md +70 -0
  77. package/templates/vite/.howone/skills/hallmark/references/hero-enrichment.md +475 -0
  78. package/templates/vite/.howone/skills/hallmark/references/imagery-kit.md +170 -0
  79. package/templates/vite/.howone/skills/hallmark/references/interaction-and-states.md +208 -0
  80. package/templates/vite/.howone/skills/hallmark/references/layout-and-space.md +112 -0
  81. package/templates/vite/.howone/skills/hallmark/references/macrostructures/01-bento-grid.md +35 -0
  82. package/templates/vite/.howone/skills/hallmark/references/macrostructures/02-long-document.md +34 -0
  83. package/templates/vite/.howone/skills/hallmark/references/macrostructures/03-marquee-hero.md +31 -0
  84. package/templates/vite/.howone/skills/hallmark/references/macrostructures/04-stat-led.md +34 -0
  85. package/templates/vite/.howone/skills/hallmark/references/macrostructures/05-workbench.md +32 -0
  86. package/templates/vite/.howone/skills/hallmark/references/macrostructures/06-conversational-faq.md +33 -0
  87. package/templates/vite/.howone/skills/hallmark/references/macrostructures/07-manifesto.md +32 -0
  88. package/templates/vite/.howone/skills/hallmark/references/macrostructures/08-photographic.md +34 -0
  89. package/templates/vite/.howone/skills/hallmark/references/macrostructures/09-quote-led.md +32 -0
  90. package/templates/vite/.howone/skills/hallmark/references/macrostructures/10-specimen.md +32 -0
  91. package/templates/vite/.howone/skills/hallmark/references/macrostructures/11-catalogue.md +23 -0
  92. package/templates/vite/.howone/skills/hallmark/references/macrostructures/12-letter.md +23 -0
  93. package/templates/vite/.howone/skills/hallmark/references/macrostructures/13-index-first.md +23 -0
  94. package/templates/vite/.howone/skills/hallmark/references/macrostructures/14-narrative-workflow.md +23 -0
  95. package/templates/vite/.howone/skills/hallmark/references/macrostructures/15-split-studio.md +23 -0
  96. package/templates/vite/.howone/skills/hallmark/references/macrostructures/16-feature-stack.md +23 -0
  97. package/templates/vite/.howone/skills/hallmark/references/macrostructures/17-type-specimen.md +23 -0
  98. package/templates/vite/.howone/skills/hallmark/references/macrostructures/18-portfolio-grid.md +23 -0
  99. package/templates/vite/.howone/skills/hallmark/references/macrostructures/19-map-diagram.md +23 -0
  100. package/templates/vite/.howone/skills/hallmark/references/macrostructures/20-ecosystem-index.md +23 -0
  101. package/templates/vite/.howone/skills/hallmark/references/macrostructures/21-component-playground.md +23 -0
  102. package/templates/vite/.howone/skills/hallmark/references/macrostructures.md +89 -0
  103. package/templates/vite/.howone/skills/hallmark/references/microinteractions.md +258 -0
  104. package/templates/vite/.howone/skills/hallmark/references/motion.md +109 -0
  105. package/templates/vite/.howone/skills/hallmark/references/preview-examples.md +49 -0
  106. package/templates/vite/.howone/skills/hallmark/references/responsive.md +138 -0
  107. package/templates/vite/.howone/skills/hallmark/references/slop-test.md +192 -0
  108. package/templates/vite/.howone/skills/hallmark/references/structure.md +160 -0
  109. package/templates/vite/.howone/skills/hallmark/references/study.md +509 -0
  110. package/templates/vite/.howone/skills/hallmark/references/themes/carnival.md +301 -0
  111. package/templates/vite/.howone/skills/hallmark/references/themes/cobalt.md +146 -0
  112. package/templates/vite/.howone/skills/hallmark/references/themes/hum.md +403 -0
  113. package/templates/vite/.howone/skills/hallmark/references/themes/lumen.md +478 -0
  114. package/templates/vite/.howone/skills/hallmark/references/typography.md +243 -0
  115. package/templates/vite/.howone/skills/hallmark/references/verbs/audit.md +25 -0
  116. package/templates/vite/.howone/skills/hallmark/references/verbs/redesign.md +269 -0
  117. package/templates/vite/.howone/skills/howone/01-architect/01-app-generation.md +209 -0
  118. package/templates/vite/.howone/skills/howone/01-architect/02-manifest-codegen.md +194 -0
  119. package/templates/vite/.howone/skills/howone/02-entity-schema/01-schema-design.md +523 -0
  120. package/templates/vite/.howone/skills/howone/02-entity-schema/02-schema-operations.md +329 -0
  121. package/templates/vite/.howone/skills/howone/02-entity-schema/03-access-models.md +151 -0
  122. package/templates/vite/.howone/skills/howone/02-entity-schema/04-query-contracts.md +123 -0
  123. package/templates/vite/.howone/skills/howone/02-entity-schema/05-ai-persistence-patterns.md +255 -0
  124. package/templates/vite/.howone/skills/howone/03-ai-capabilities/01-ai-capability-architecture.md +215 -0
  125. package/templates/vite/.howone/skills/howone/03-ai-capabilities/02-workflow-contract-rules.md +427 -0
  126. package/templates/vite/.howone/skills/howone/03-ai-capabilities/03-service-capability-catalog.md +304 -0
  127. package/templates/vite/.howone/skills/howone/03-ai-capabilities/04-workflow-operations.md +164 -0
  128. package/templates/vite/.howone/skills/howone/03-ai-capabilities/05-ai-feature-playbooks.md +275 -0
  129. package/templates/vite/.howone/skills/howone/04-app-sdk/01-client-setup.md +162 -0
  130. package/templates/vite/.howone/skills/howone/04-app-sdk/02-entity-operations.md +163 -0
  131. package/templates/vite/.howone/skills/howone/04-app-sdk/03-auth.md +418 -0
  132. package/templates/vite/.howone/skills/howone/04-app-sdk/04-react-integration.md +138 -0
  133. package/templates/vite/.howone/skills/howone/04-app-sdk/05-file-upload.md +112 -0
  134. package/templates/vite/.howone/skills/howone/04-app-sdk/06-raw-http.md +128 -0
  135. package/templates/vite/.howone/skills/howone/04-app-sdk/07-ai-action-calls.md +210 -0
  136. package/templates/vite/.howone/skills/howone/04-app-sdk/08-ai-manifest-handoff.md +90 -0
  137. package/templates/vite/.howone/skills/howone/04-app-sdk/09-extension-boundaries.md +226 -0
  138. package/templates/vite/.howone/skills/howone/04-app-sdk/10-workflow-execute-sse.md +138 -0
  139. package/templates/vite/.howone/skills/howone/04-app-sdk/11-entity-data-access-patterns.md +310 -0
  140. package/templates/vite/.howone/skills/howone/04-app-sdk/12-query-dsl-and-responses.md +237 -0
  141. package/templates/vite/.howone/skills/howone/04-app-sdk/13-credits.md +31 -0
  142. package/templates/vite/.howone/skills/howone/SKILL.md +256 -0
  143. package/templates/vite/.howone/skills/howone/agents/openai.yaml +4 -0
  144. package/templates/vite/.howone/skills/howone/references/audio-generation.md +30 -0
  145. package/templates/vite/.howone/skills/howone/references/audio-recognition.md +30 -0
  146. package/templates/vite/.howone/skills/howone/references/common-errors.md +27 -0
  147. package/templates/vite/.howone/skills/howone/references/finance.md +28 -0
  148. package/templates/vite/.howone/skills/howone/references/image-editing.md +30 -0
  149. package/templates/vite/.howone/skills/howone/references/image-generation.md +30 -0
  150. package/templates/vite/.howone/skills/howone/references/version-evidence.md +47 -0
  151. package/templates/vite/.howone/skills/howone/references/video-generation.md +35 -0
  152. package/templates/vite/.howone/skills/howone/scripts/verify-project.mjs +151 -0
  153. package/templates/vite/.prettierignore +7 -0
  154. package/templates/vite/.prettierrc +11 -0
  155. package/templates/vite/AGENTS.md +87 -0
  156. package/templates/vite/README.md +21 -0
  157. package/templates/vite/components.json +25 -0
  158. package/templates/vite/eslint.config.js +23 -0
  159. package/templates/vite/index.html +12 -0
  160. package/templates/vite/package.json +58 -0
  161. package/templates/vite/public/vite.svg +1 -0
  162. package/templates/vite/src/App.tsx +17 -0
  163. package/templates/vite/src/assets/react.svg +1 -0
  164. package/templates/vite/src/components/theme-provider.tsx +230 -0
  165. package/templates/vite/src/components/ui/accordion.tsx +79 -0
  166. package/templates/vite/src/components/ui/alert-dialog.tsx +197 -0
  167. package/templates/vite/src/components/ui/alert.tsx +76 -0
  168. package/templates/vite/src/components/ui/aspect-ratio.tsx +11 -0
  169. package/templates/vite/src/components/ui/avatar.tsx +110 -0
  170. package/templates/vite/src/components/ui/badge.tsx +49 -0
  171. package/templates/vite/src/components/ui/breadcrumb.tsx +122 -0
  172. package/templates/vite/src/components/ui/button-group.tsx +83 -0
  173. package/templates/vite/src/components/ui/button.tsx +67 -0
  174. package/templates/vite/src/components/ui/calendar.tsx +222 -0
  175. package/templates/vite/src/components/ui/card.tsx +103 -0
  176. package/templates/vite/src/components/ui/carousel.tsx +240 -0
  177. package/templates/vite/src/components/ui/chart.tsx +373 -0
  178. package/templates/vite/src/components/ui/checkbox.tsx +31 -0
  179. package/templates/vite/src/components/ui/collapsible.tsx +33 -0
  180. package/templates/vite/src/components/ui/combobox.tsx +299 -0
  181. package/templates/vite/src/components/ui/command.tsx +193 -0
  182. package/templates/vite/src/components/ui/context-menu.tsx +261 -0
  183. package/templates/vite/src/components/ui/dialog.tsx +168 -0
  184. package/templates/vite/src/components/ui/direction.tsx +22 -0
  185. package/templates/vite/src/components/ui/drawer.tsx +132 -0
  186. package/templates/vite/src/components/ui/dropdown-menu.tsx +269 -0
  187. package/templates/vite/src/components/ui/empty.tsx +104 -0
  188. package/templates/vite/src/components/ui/field.tsx +238 -0
  189. package/templates/vite/src/components/ui/hover-card.tsx +42 -0
  190. package/templates/vite/src/components/ui/input-group.tsx +154 -0
  191. package/templates/vite/src/components/ui/input-otp.tsx +87 -0
  192. package/templates/vite/src/components/ui/input.tsx +19 -0
  193. package/templates/vite/src/components/ui/item.tsx +196 -0
  194. package/templates/vite/src/components/ui/kbd.tsx +26 -0
  195. package/templates/vite/src/components/ui/label.tsx +22 -0
  196. package/templates/vite/src/components/ui/menubar.tsx +280 -0
  197. package/templates/vite/src/components/ui/native-select.tsx +61 -0
  198. package/templates/vite/src/components/ui/navigation-menu.tsx +164 -0
  199. package/templates/vite/src/components/ui/pagination.tsx +129 -0
  200. package/templates/vite/src/components/ui/popover.tsx +87 -0
  201. package/templates/vite/src/components/ui/progress.tsx +31 -0
  202. package/templates/vite/src/components/ui/radio-group.tsx +42 -0
  203. package/templates/vite/src/components/ui/resizable.tsx +50 -0
  204. package/templates/vite/src/components/ui/scroll-area.tsx +53 -0
  205. package/templates/vite/src/components/ui/select.tsx +192 -0
  206. package/templates/vite/src/components/ui/separator.tsx +26 -0
  207. package/templates/vite/src/components/ui/sheet.tsx +145 -0
  208. package/templates/vite/src/components/ui/sidebar.tsx +700 -0
  209. package/templates/vite/src/components/ui/skeleton.tsx +13 -0
  210. package/templates/vite/src/components/ui/slider.tsx +59 -0
  211. package/templates/vite/src/components/ui/sonner.tsx +47 -0
  212. package/templates/vite/src/components/ui/spinner.tsx +10 -0
  213. package/templates/vite/src/components/ui/switch.tsx +33 -0
  214. package/templates/vite/src/components/ui/table.tsx +114 -0
  215. package/templates/vite/src/components/ui/tabs.tsx +90 -0
  216. package/templates/vite/src/components/ui/textarea.tsx +18 -0
  217. package/templates/vite/src/components/ui/toggle-group.tsx +89 -0
  218. package/templates/vite/src/components/ui/toggle.tsx +45 -0
  219. package/templates/vite/src/components/ui/tooltip.tsx +57 -0
  220. package/templates/vite/src/hooks/use-mobile.ts +19 -0
  221. package/templates/vite/src/index.css +133 -0
  222. package/templates/vite/src/lib/sdk.ts +34 -0
  223. package/templates/vite/src/lib/utils.ts +6 -0
  224. package/templates/vite/src/main.tsx +14 -0
  225. package/templates/vite/tsconfig.app.json +32 -0
  226. package/templates/vite/tsconfig.json +13 -0
  227. package/templates/vite/tsconfig.node.json +26 -0
  228. package/templates/vite/vite.config.ts +14 -0
@@ -0,0 +1,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. |