howone 0.2.3 → 0.2.5

package/templates/vite/.howone/skills/howone/04-app-sdk/06-raw-http.md

@@ -1,299 +1,122 @@
 # Raw HTTP
 
-## When to Use
+Use `howone.raw` only for an app-owned endpoint that has no typed entity, auth, upload, or AI
+binding. Do not use it to bypass manifest access rules or recreate `/data` and workflow calls.
 
-Use `client.raw` when you need to call a custom backend endpoint that is **not** covered by `client.entities` or `client.ai`. The raw client is an Axios-based HTTP client that automatically attaches the HowOne auth token and project ID headers.
+## Contract
 
-**Do not use `client.raw` to re-implement entity operations or AI workflows** — use the typed SDK methods instead.
-
----
-
-## The RawHttpClient Interface
+`howone.raw` is a request client whose methods resolve to response **data**, not an AxiosResponse:
 
 ```ts
-type RawHttpClient = {
-  instance: AxiosInstance
-
-  // All methods return Promise<AxiosResponse>
-  request(config: RequestConfig): Promise<AxiosResponse>
-  get(config: RequestConfig): Promise<AxiosResponse>
-  post(config: RequestConfig): Promise<AxiosResponse>
-  put(config: RequestConfig): Promise<AxiosResponse>
-  patch(config: RequestConfig): Promise<AxiosResponse>
-  delete(config: RequestConfig): Promise<AxiosResponse>
-
-  // Cancel an in-flight request by URL
-  cancelRequest(url: string): void
-
-  // Cancel all in-flight requests
-  cancelAllRequests(): void
-}
+const data = await howone.raw.get<Stats>({ url: '/custom/stats' })
+const created = await howone.raw.post<Receipt>({
+  url: '/custom/receipts',
+  data: { orderId },
+})
 ```
 
-### RequestConfig
-
-`RequestConfig` extends `AxiosRequestConfig` with optional interceptors:
-
 ```ts
-type RequestConfig<T = AxiosResponse> = AxiosRequestConfig & {
+type RequestConfig<T = unknown> = AxiosRequestConfig & {
   interceptors?: {
     requestInterceptor?: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig
-    requestInterceptorCatch?: (error: any) => any
-    responseInterceptor?: (res: T) => T
-    responseInterceptorCatch?: (error: any) => any
+    requestInterceptorCatch?: (error: unknown) => unknown
+    responseInterceptor?: (data: T) => T
+    responseInterceptorCatch?: (error: unknown) => unknown
   }
-  showLoading?: boolean
 }
 ```
 
----
+The SDK attaches the current client token to authenticated non-public requests. It does not turn
+an app-owned route into a platform contract; the backend must authenticate and authorize it.
 
-## Basic Usage
+## URL rules
 
-```ts
-import howone from '@/lib/sdk'
-
-// GET
-const response = await howone.raw.get({
-  url: '/api/custom/stats',
-})
-const data = response.data  // untyped AxiosResponse.data
-
-// POST with body
-const response = await howone.raw.post({
-  url: '/api/custom/send-notification',
-  data: {
-    userId: '123',
-    message: 'Hello!',
-  },
-})
-
-// PUT
-const response = await howone.raw.put({
-  url: `/api/custom/profile/${userId}`,
-  data: { displayName: 'Alice' },
-})
-
-// PATCH
-const response = await howone.raw.patch({
-  url: `/api/custom/settings`,
-  data: { theme: 'dark' },
-})
-
-// DELETE
-const response = await howone.raw.delete({
-  url: `/api/custom/sessions/${sessionId}`,
-})
-```
-
----
-
-## Typed Responses
-
-Wrap with generics for type safety:
+The configured REST base already ends in `/api` for hosted environments. Use a path relative to that
+base:
 
 ```ts
-type StatsResponse = {
-  totalUsers: number
-  activeToday: number
-  storageUsed: number
-}
-
-const response = await howone.raw.get<StatsResponse>({
-  url: '/api/custom/stats',
-})
+// Correct: https://api.howone.dev/api/custom/stats
+const stats = await howone.raw.get<Stats>({ url: '/custom/stats' })
 
-const stats = response.data  // typed as StatsResponse
+// Wrong: https://api.howone.dev/api/api/custom/stats
+// howone.raw.get({ url: '/api/custom/stats' })
 ```
 
----
+An absolute URL is an explicit app-owned escape hatch and is not how EAX routing is selected. Do not
+put an EAX URL in a raw request; AI actions already use `env`.
 
-## Query Parameters
+## Query, headers, and cancellation
 
 ```ts
-// Pass query params via the `params` field (Axios serializes them automatically)
-const response = await howone.raw.get({
-  url: '/api/custom/search',
-  params: {
-    q: 'dragons',
-    page: 1,
-    limit: 20,
-    sort: 'createdAt',
-    order: 'desc',
-  },
+const result = await howone.raw.get<SearchResult>({
+  url: '/custom/search',
+  params: { q, page: 1, limit: 20 },
+  headers: { 'X-Request-Source': 'app' },
+  signal: controller.signal,
 })
-// Calls: GET /api/custom/search?q=dragons&page=1&limit=20&sort=createdAt&order=desc
-```
-
----
-
-## Custom Headers
-
-```ts
-const response = await howone.raw.post({
-  url: '/api/custom/webhook',
-  data: payload,
-  headers: {
-    'X-Webhook-Secret': import.meta.env.VITE_WEBHOOK_SECRET,
-    'X-Request-Source': 'app',
-  },
-})
-```
 
----
-
-## Request Cancellation
-
-```ts
-// Cancel a specific request by URL
-howone.raw.cancelRequest('/api/custom/long-running')
-
-// Cancel all in-flight requests (e.g. on page unmount)
+// Cancels every in-flight request with this exact method-independent URL.
+howone.raw.cancelRequest('/custom/search')
 howone.raw.cancelAllRequests()
+```
 
-// Pattern: cancel on component unmount
-import { useEffect } from 'react'
-import howone from '@/lib/sdk'
-
-function DataComponent() {
-  useEffect(() => {
-    howone.raw.get({ url: '/api/custom/data' })
-      .then(res => setData(res.data))
+Prefer an `AbortController` per component operation so a new search does not cancel an unrelated
+request. The SDK links the caller's signal to its internal controller and also supports concurrent
+requests with the same method and URL.
 
-    return () => {
-      howone.raw.cancelRequest('/api/custom/data')
-    }
-  }, [])
-}
+```tsx
+useEffect(() => {
+  const controller = new AbortController()
+  void howone.raw
+    .get<SearchResult>({ url: '/custom/search', params: { q }, signal: controller.signal })
+    .then(setResult)
+    .catch((error) => {
+      if (!controller.signal.aborted) setError(error instanceof Error ? error.message : String(error))
+    })
+  return () => controller.abort()
+}, [q])
 ```
 
----
-
-## Per-Request Interceptors
+## Per-request interceptors
 
-For one-off request/response transforms without modifying the global client:
+The response interceptor sees the already-unwrapped data:
 
 ```ts
-const response = await howone.raw.post({
-  url: '/api/custom/transform',
-  data: payload,
+const data = await howone.raw.get<RawStats>({
+  url: '/custom/stats',
   interceptors: {
     requestInterceptor: (config) => {
-      // Modify request config (e.g. add timestamp)
-      config.headers['X-Timestamp'] = Date.now().toString()
+      config.headers.set('X-Request-Id', crypto.randomUUID())
       return config
     },
-    responseInterceptor: (res) => {
-      // Log response time or transform data
-      console.log('Response status:', res.status)
-      return res
-    },
-    responseInterceptorCatch: (error) => {
-      // Handle specific error codes
-      if (error.response?.status === 503) {
-        console.error('Service temporarily unavailable')
-      }
-      return Promise.reject(error)
-    },
+    responseInterceptor: (value) => ({ ...value, loadedAt: Date.now() }),
+    responseInterceptorCatch: (error) => Promise.reject(error),
   },
 })
 ```
 
----
-
-## Direct Axios Instance Access
-
-For maximum control (multipart forms, streaming responses, etc.):
-
-```ts
-const instance = howone.raw.instance  // Axios instance
-
-// Multipart form data
-const formData = new FormData()
-formData.append('report', file)
-formData.append('meta', JSON.stringify({ type: 'monthly' }))
-
-const response = await instance.post('/api/custom/reports', formData, {
-  headers: { 'Content-Type': 'multipart/form-data' },
-  onUploadProgress: (e) => {
-    const percent = Math.round((e.loaded * 100) / (e.total ?? 1))
-    setProgress(percent)
-  },
-})
-```
-
----
-
-## React Pattern: Data Fetching with Raw HTTP
-
-```tsx
-import { useEffect, useState } from 'react'
-import howone from '@/lib/sdk'
-
-type AnalyticsData = {
-  views: number
-  clicks: number
-  conversions: number
-  period: string
-}
-
-function Analytics({ projectId }: { projectId: string }) {
-  const [data, setData] = useState<AnalyticsData | null>(null)
-  const [loading, setLoading] = useState(true)
-  const [error, setError] = useState<string | null>(null)
-
-  useEffect(() => {
-    let cancelled = false
-
-    howone.raw.get<AnalyticsData>({
-      url: '/api/custom/analytics',
-      params: { projectId, period: '30d' },
-    })
-      .then(res => { if (!cancelled) setData(res.data) })
-      .catch(err => { if (!cancelled) setError(err.message) })
-      .finally(() => { if (!cancelled) setLoading(false) })
-
-    return () => {
-      cancelled = true
-      howone.raw.cancelRequest('/api/custom/analytics')
-    }
-  }, [projectId])
-
-  if (loading) return <div>Loading analytics...</div>
-  if (error) return <div>Error: {error}</div>
-  if (!data) return null
-
-  return (
-    <div>
-      <p>Views: {data.views}</p>
-      <p>Clicks: {data.clicks}</p>
-      <p>Conversions: {data.conversions}</p>
-    </div>
-  )
-}
-```
-
----
+Do not expect `value.status` or `value.data` in `responseInterceptor`; use the direct Axios instance
+only when the installed SDK typings explicitly require a transport-level operation.
 
-## client.raw vs client.entities
+## Choosing the correct surface
 
-| Use Case | Recommended API |
+| Need | Use |
 |---|---|
-| CRUD on a HowOne entity | `howone.entities.<Entity>.*` |
-| Querying with pagination/filter/sort | `howone.entities.<Entity>.query()` |
-| Running an AI workflow | `howone.ai.<action>.run()` |
-| Calling a custom backend route | `howone.raw.get/post/...` |
-| Sending webhooks or notifications | `howone.raw.post()` |
-| Fetching analytics or aggregated data not in entities | `howone.raw.get()` |
-| Uploading files | `howone.upload.*` |
+| Manifest entity CRUD/query | `howone.entities.Entity.*` |
+| Manifest-approved public data | `howone.public.entities.Entity.*` |
+| EAX workflow | `howone.ai.action.run/stream/events` |
+| HowOne storage | `howone.upload.*` |
+| App-owned backend route | `howone.raw.*` |
 
----
+If the endpoint is missing from the platform contract, classify it as an explicit app-owned
+integration. Do not call an internal platform route because it happens to work today.
 
-## Common Mistakes
+## Common mistakes
 
-| Mistake | Correct Pattern |
+| Mistake | Fix |
 |---|---|
-| `howone.raw.get({ url: '/entities/Story' })` to read entities | Use `howone.entities.Story.query()` |
-| Not handling Axios errors (`.response.status`) | Wrap in try/catch and check `error.response?.status` |
-| Calling `cancelAllRequests()` too broadly | Use `cancelRequest(url)` for surgical cancellation |
-| Forgetting that `response.data` is untyped by default | Pass the type parameter: `howone.raw.get<MyType>(...)` |
+| Reading `response.data` | Raw methods already return data. |
+| Prefixing `/api` in a raw path | The REST base already includes `/api`. |
+| Calling raw `/data/...` | Use generated entity bindings. |
+| Passing `'*'` as a cross-window origin | Use explicit origins in the devtools Provider. |
+| Cancelling by a broad substring | Use the exact request path or the caller's AbortSignal. |