@brickflow/http 0.0.14 → 0.0.15

package/README.md

@@ -1,406 +1,425 @@
-# `@brickflow/http`
+# @brickflow/http
 
-Nuxt HTTP module and typed client with:
+Minimal HTTP package used in this repo for:
 
-- `NuxtApp.$http`
-- `useHttp()` auto-import
-- request/response middleware
-- retry and timeout support
-- optional client cache via IndexedDB
-- typed URL literals for `get`, `post`, and `useHttp`
+- low-level HTTP transport via `createHttp`
+- Nuxt async state wrapper via `createUseHttp`
+- reusable endpoint factory via `createGet`
+- project-level typing through `declare module '@brickflow/http'`
 
-## Install
+This package does not know your API schema by default. The schema and error type are configured in the consumer project through `type.d.ts`.
 
-```bash
-pnpm add @brickflow/http
-```
+## Exports
+
+From `@brickflow/http`:
+
+- `createHttp`
+- `createURL`
+- `hashData`
+- HTTP types: `HttpClient`, `HttpError`, `HttpKey`, `HttpParam`, `HttpResponse`, `HttpResponseData`, `HttpSuccessData`
 
-## Nuxt Setup
+From `@brickflow/http/nuxt`:
+
+- `createUseHttp`
+- `createGet`
+- Nuxt types: `UseHttpOptions`, `UseHttpResult`, `UseHttpFn`
+
+## 1. Configure API types in `type.d.ts`
+
+In this repo the typing is configured in `types/http.d.ts`.
 
 ```ts
-export default defineNuxtConfig({
-  modules: ['@brickflow/http'],
-})
+import type { Convention, ConventionKeys } from 'convention'
+
+type BrickHttpError = Exclude<Convention<ConventionKeys>, { status: 'success' }>
+type BrickHttpSchema = {
+  [TKey in ConventionKeys]: Convention<TKey>
+}
+
+declare module '@brickflow/http' {
+  interface HttpTypeConfig {
+    endpoints: BrickHttpSchema
+    error: BrickHttpError
+  }
+}
 ```
 
-With options:
+What this gives:
+
+- `HttpKey` becomes your endpoint union
+- `HttpResponseData<'some/endpoint'>` becomes the response type for that endpoint
+- `HttpSuccessData<'some/endpoint'>` becomes response without the configured error branch
+- `UseHttpResult<T, P>['error']` is inferred from `HttpTypeConfig['error']`
+
+This is the main place where project typing should live.
+
+## 2. Create low-level HTTP client
+
+Real usage from `plugins/01.di.ts`:
 
 ```ts
-export default defineNuxtConfig({
-  modules: ['@brickflow/http'],
-  brickflowHttp: {
-    baseURL: 'https://api.example.com',
-    cache: true,
-    cacheDbName: 'smart-cache-v2',
-    cacheStoreName: 'data',
-    cacheTtlMs: 1000 * 60 * 60 * 24 * 7,
-    clientEnvHeader: true,
-    defaultHeaders: {
-      'X-App-Version': '1.0.0',
-    },
-    disableCacheInDev: true,
-    requestTimeoutMs: 80000,
-    retry: {
-      delay: 300,
-      retries: 3,
-    },
-  },
+import { createHttp } from '@brickflow/http'
+
+const httpClient = createHttp({
+  baseURL: apiUrl,
+  headers: () => ({
+    'Client-Env': config.public.isDev ? 'development' : undefined,
+    'Client-Lang': String(locale.value ?? 'en'),
+    'Client-Socket-Id': socketClient?.io.id || '',
+    'X-Requested-With': 'XMLHttpRequest',
+  }),
+  onResponseError: responseInterceptor,
 })
 ```
 
-## Defaults
+Available options:
 
-`brickflowHttp` defaults:
+- `baseURL`
+- `fetch`
+- `headers`
+- `onResponseError`
+- `requestInit`
+- `timeout`
 
-| Option              | Default            |
-| ------------------- | ------------------ |
-| `baseURL`           | `''`               |
-| `cache`             | `true`             |
-| `cacheDbName`       | `'smart-cache-v2'` |
-| `cacheStoreName`    | `'data'`           |
-| `cacheTtlMs`        | `604800000`        |
-| `clientEnvHeader`   | `true`             |
-| `defaultHeaders`    | `{}`               |
-| `disableCacheInDev` | `true`             |
-| `requestTimeoutMs`  | `80000`            |
-| `retry.delay`       | `300`              |
-| `retry.retries`     | `3`                |
+`createHttp` returns:
 
-Runtime behavior:
+```ts
+interface HttpClient {
+  get(url, config?)
+  post(url, data?, config?)
+}
+```
 
-- `X-Requested-With: XMLHttpRequest` is added automatically
-- in dev, `Client-Env: development` is added when `clientEnvHeader` is enabled
-- `5xx` and `451` responses with `{ status: 'error' }` trigger Nuxt `showError()`
+## 3. Use `HttpClient` directly
 
-## Basic Usage
+Used in domain methods that do not need cached async state.
 
-Use `$http` in components, composables, or plugins:
+Example from `domains/content/use-case.ts`:
 
 ```ts
-const { $http } = useNuxtApp()
-
-const response = await $http.get<{ id: string; name: string }>('/user', {
-  params: {
-    id: '42',
-  },
-})
+async create(title: string, type: string, description?: string) {
+  const { data } = await httpClient.post('content/create', {
+    description,
+    title,
+    type,
+  })
 
-if ('status' in response.data && response.data.status === 'error') {
-  console.error(response.data.message)
-} else {
-  console.log(response.data.name)
+  return data
 }
 ```
 
-POST:
+Another example:
 
 ```ts
-const { $http } = useNuxtApp()
+async updateType(itemId: string, type: string) {
+  const { data } = await httpClient.post('content/update-type', {
+    itemId,
+    type,
+  })
 
-const response = await $http.post<{ ok: true }>(
-  '/posts',
-  {
-    title: 'Hello',
-  },
-  {
-    params: {
-      draft: true,
-    },
-  },
-)
+  return data
+}
 ```
 
-## `useHttp()`
+Use this style when:
 
-`useHttp()` is auto-imported and returns:
+- request is one-shot
+- you do not need `pending`, `hasFirstData`, cache, SSR sync, or `fetch()`
 
-- `data`
-- `error`
-- `pending`
-- `pendingCache`
-- `hasFirstData`
-- `hasFreshData`
-- `fetch()`
+## 4. Create Nuxt `useHttp`
 
-Basic example:
+In this repo the app-level `useHttp` is created once in `core/util.ts`:
 
 ```ts
-const users = await useHttp<Array<{ id: string; name: string }>>({
-  server: true,
-  url: '/users',
+import { createUseHttp } from '@brickflow/http/nuxt'
+
+const useHttp = createUseHttp({
+  getCache: () => ({
+    deleteKeysWithPart: async (part) => await dbDeleteKeysWithPart(part, 'smart-cache-v2', STORE_NAME),
+    get: async (key) => await dbGet(key, 'smart-cache-v2', STORE_NAME),
+    set: async (key, value, ttl) => await dbSafeSet(key, value, 'smart-cache-v2', STORE_NAME, ttl),
+  }),
+  getHttpClient: () => useNuxtApp().$http,
+  isDev: () => useRuntimeConfig().public.isDev,
 })
 ```
 
-With params:
+Dependencies:
 
-```ts
-const users = await useHttp<Array<{ id: string; name: string }>, { page: number }>({
-  initParams: {
-    page: 1,
-  },
-  url: '/users',
-})
+- `getHttpClient`
+- `getCache`
+- `isError`
+- `isDev`
+- `ttl`
+- `channelName`
 
-await users.fetch({
-  page: 2,
-})
-```
+`isError` can be set globally here if your project needs a custom runtime error predicate.
+
+## 5. Bind `createGet` once
 
-With side effects:
+The package exports `createGet(useHttp)`, which builds typed endpoint helpers on top of your local `useHttp`.
+
+Real usage from `core/util.ts`:
 
 ```ts
-const profile = await useHttp<{ id: string; name: string }>({
-  effect(payload, { cached }) {
-    if (!cached) {
-      console.log('fresh profile payload', payload)
-    }
-  },
-  url: '/profile',
-})
+import { createGet as createHttpGet, createUseHttp } from '@brickflow/http/nuxt'
+
+const useHttp = createUseHttp({ ... })
+
+export const createGet = createHttpGet(useHttp)
 ```
 
-## Typed Routes
+After that you can reuse `createGet` in domain files.
+
+## 6. Create typed GET endpoints
 
-If you want `'/users'` and other URL literals to infer `params`, `data`, `error`, and `body` automatically, extend the global `BrickflowHttpRouteMap`.
+### Without params
 
-Create a declaration file, for example `types/brickflow-http.d.ts`:
+Example from `domains/storage/use-case.ts`:
 
 ```ts
-import type { HttpErrorPayload } from '@brickflow/http'
-
-declare global {
-  interface BrickflowHttpRouteMap {
-    '/api/user': {
-      data: { id: string; name: string }
-      error: HttpErrorPayload & { code?: 'NOT_FOUND' }
-      params: { id: string }
-    }
-    '/api/posts': {
-      data: Array<{ id: string; title: string }>
-      params: { page?: number }
-    }
-    '/api/posts/create': {
-      body: { title: string }
-      data: { id: string }
-    }
-  }
-}
+plans: createGet()('storage/plans')
+```
+
+### With params
+
+Example from `domains/feed/use-case.ts`:
 
-export {}
+```ts
+home: createGet<{
+  category?: 'fresh' | 'popular' | 'recommended' | 'updated'
+  limit: number
+  offset: number
+}>()('feed/home')
 ```
 
-After that, `$http` and `useHttp()` infer types from the URL literal automatically.
+### With `ignore`
 
-Typed `get`:
+Example from `domains/content/use-case.ts`:
 
 ```ts
-const { $http } = useNuxtApp()
+analytics: createGet<{
+  itemId: string
+  period: '7d' | '28d' | '90d'
+}>()('content/analytics', {
+  ignore(res) {
+    if (res.data.kind === 'no_auth') {
+      return true
+    }
 
-const response = await $http.get('/api/user', {
-  params: {
-    id: '42',
+    return false
   },
 })
 ```
 
-Typed `post`:
+### With `effect`
+
+Example from `domains/root/use-case.ts`:
 
 ```ts
-const { $http } = useNuxtApp()
+main: createGet()('root/main', {
+  effect(data, config) {
+    if (data.status === 'error') {
+      return
+    }
 
-await $http.post('/api/posts/create', {
-  title: 'New post',
+    if (!config.cached) {
+      userStore.setUser(data.user)
+      userStore.setRegion(data.region)
+    }
+  },
 })
 ```
 
-Typed `useHttp` without generics:
+### With `effect` and success handling
+
+Example from `domains/storage/use-case.ts`:
 
 ```ts
-const posts = await useHttp({
-  initParams: {
-    page: 1,
+current: createGet()('storage/current', {
+  effect(data) {
+    if (data.status === 'success') {
+      storageStore.setCurrentPlan(data.plan)
+    }
   },
-  url: '/api/posts',
-})
-
-await posts.fetch({
-  page: 2,
 })
 ```
 
-## Strict Client
+## 7. Consume endpoint state in components
 
-`$http` keeps a fallback overload for plain `string`, so unknown URLs are still allowed.
+### Create request object
 
-If you want to forbid unknown URLs completely:
+Example from `components/Search/index.vue`:
 
 ```ts
-import { createStrictHttpClient } from '@brickflow/http'
+const searchFastHttp = await app.$di.search.fast({
+  lazy: true,
+  server: false,
+})
+```
 
-const { $http } = useNuxtApp()
-const strictHttp = createStrictHttpClient($http)
+### Trigger fetch manually
 
-await strictHttp.get('/api/user', {
-  params: { id: '42' },
+```ts
+await searchFastHttp.fetch({
+  text: searchQuery.value,
 })
-
-// TypeScript error
-await strictHttp.get('/api/unknown')
 ```
 
-If you want typed overloads on a standalone client while keeping the plain `string` fallback:
+### Read `data`
 
 ```ts
-import { createHttpClient, createTypedHttpClient } from '@brickflow/http'
+const data = searchFastHttp.data
 
-const http = createTypedHttpClient(
-  createHttpClient({
-    baseURL: 'https://api.example.com',
-  }),
-)
+if (data?.status === 'success') {
+  items.value = data.items
+  users.value = data.users
+}
 ```
 
-## Dynamic Base URL
+### Read loading flags
 
-Standalone client supports a dynamic resolver:
+Example from `components/ProfileMyGrid/index.vue`:
 
-```ts
-const tenantStore = useTenantStore()
+```vue
+:loading="myContentHttp.pending || myContentHttp.pendingCache"
+```
 
-const http = createHttpClient({
-  baseURL: () => tenantStore.apiBaseUrl,
-})
+### Use `hasFirstData`
+
+```vue
+v-if="!myContentHttp.pending && myContentHttp.hasFirstData && items.length === 0"
 ```
 
-In Nuxt, the better option is request middleware, because it works for both `$http` and `useHttp()`:
+## 8. `effect` semantics
 
-```ts
-import { addHttpRequestMiddleware } from '@brickflow/http'
+`effect` receives the full response payload.
 
-export default defineNuxtPlugin(() => {
-  const apiBaseUrl = useState('api-base-url', () => 'https://dummyjson.com')
+That means:
 
-  addHttpRequestMiddleware((request) => {
-    if (request.url.startsWith('/products') || request.url.startsWith('/test')) {
-      request.baseURL = apiBaseUrl.value
+- it is called for success
+- it is called for error
+- you can branch on `data.status`
+- `config.cached` tells whether the payload came from cache
+- `config.params` contains mapped params used for the request
+
+Example from `pages/profile/[username].vue`:
+
+```ts
+const profileHttp = await app.$di.profile.info({
+  effect(data) {
+    if (data.status === 'error' && data.kind === 'not_found') {
+      showError(createError({
+        fatal: true,
+        statusCode: 404,
+        statusMessage: 'Page Not Found',
+      }))
     }
-  })
+  },
+  initParams: {
+    username: String(profileParam.value),
+  },
+  server: true,
 })
 ```
 
-Then the same request code can stay relative:
+## 9. `data` and `error`
 
-```ts
-const products = await useHttp({
-  url: '/products',
-})
+`UseHttpResult<T, P>` is split like this:
 
-const { $http } = useNuxtApp()
-await $http.get('/test')
-```
+- `data`: success payload only
+- `error`: configured project error payload only
 
-The playground app contains a live example that switches the same typed requests between:
+Internally the split is done by runtime error predicate:
 
-- direct `https://dummyjson.com`
-- local proxy `/api/dummyjson`
+- global `isError` from `createUseHttp(...)`
+- or per-request `isError`
+- fallback: `payload.status === 'error'`
 
-See:
+Important:
 
-- [apps/playground/app/pages/index.vue](/Users/andrii/Lab/personal/brickme/apps/playground/app/pages/index.vue:1)
-- [apps/playground/app/plugins/http-middleware.ts](/Users/andrii/Lab/personal/brickme/apps/playground/app/plugins/http-middleware.ts:1)
+- runtime error predicate does not reconfigure TypeScript types
+- TypeScript error type comes from `declare module '@brickflow/http'`
 
-## Global Middleware
+## 10. Supported request options
 
-Register middleware once and it will run for every request or response:
+For `useHttp` / `createGet`:
 
-```ts
-import { addHttpRequestMiddleware, addHttpResponseMiddleware } from '@brickflow/http'
+- `url`
+- `initParams`
+- `mapParams`
+- `effect`
+- `ignore`
+- `isError`
+- `lazy`
+- `server`
 
-export default defineNuxtPlugin(() => {
-  addHttpRequestMiddleware((request) => {
-    request.headers.set('X-App-Version', '1.0.0')
-  })
+Example with `initParams`:
 
-  addHttpResponseMiddleware((response, request) => {
-    if (response.status >= 500) {
-      console.error('HTTP error', request.url, response.status)
-    }
-  })
+```ts
+const myContentHttp = await app.$di.content.my({
+  initParams: {
+    limit: props.limit,
+    offset: 0,
+    order: selectedOrder.value,
+    orderColumn: 'date',
+    type: selectedType.value,
+  },
 })
 ```
 
-Request middleware can mutate:
+Example with `fetch(...)` overriding params:
 
-- `baseURL`
-- `url`
-- `method`
-- `headers`
-- `body`
-- `params`
-- `signal`
-- `credentials`
+```ts
+await myContentHttp.fetch({
+  limit: props.limit,
+  offset,
+  order: selectedOrder.value,
+  orderColumn: 'date',
+  type: selectedType.value,
+})
+```
 
-Response middleware receives:
+## 11. Cache behavior
 
-- `response`
-- `request`
+When `getCache` is provided, `createUseHttp`:
 
-You can remove middleware later:
+- tries cached value first
+- calls `effect(..., { cached: true })` for cached payload
+- then performs fresh request
+- stores success response in cache
+- invalidates related keys when response hash changes
 
-```ts
-import { addHttpRequestMiddleware, removeHttpRequestMiddleware } from '@brickflow/http'
+In this repo the cache is backed by IndexedDB in `core/util.ts`.
 
-const middleware = (request: Parameters<typeof addHttpRequestMiddleware>[0]) => {
-  request.headers.set('X-Debug', '1')
-}
+## 12. URL and hash helpers
+
+The package also exports helpers used by the current implementation:
 
-addHttpRequestMiddleware(middleware)
-removeHttpRequestMiddleware(middleware)
+```ts
+import { createURL, hashData } from '@brickflow/http'
 ```
 
-## Standalone Client
+`createURL(url, params)` builds query strings.
 
-You can use the client outside Nuxt injection:
+`hashData(data)` computes response hash for cache invalidation.
 
-```ts
-import { createHttpClient } from '@brickflow/http'
-
-const http = createHttpClient({
-  baseURL: 'https://api.example.com',
-  requestTimeoutMs: 10000,
-  retry: {
-    delay: 250,
-    retries: 2,
-  },
-})
+## 13. Recommended usage in this repo
 
-const response = await http.get<{ ok: true }>('/health')
-```
+Use `createHttp` when:
 
-With custom headers:
+- you need direct `get/post`
+- you are writing mutations or one-shot calls
 
-```ts
-const http = createHttpClient({
-  baseURL: async () => `https://${tenant.value}.api.example.com`,
-  createHeaders: async () => {
-    return {
-      Authorization: `Bearer ${token}`,
-    }
-  },
-})
-```
+Use `createUseHttp` + `createGet` when:
 
-## Exports
+- you need SSR-aware async state
+- you need `pending`, `pendingCache`, `hasFirstData`, `hasFreshData`
+- you need cache integration
+- you want reusable typed endpoint factories in domain modules
+
+Use `type.d.ts` when:
 
-Main exports:
-
-- default Nuxt module
-- `createHttpClient`
-- `createTypedHttpClient`
-- `createStrictHttpClient`
-- `defineHttpRoutes`
-- `addHttpRequestMiddleware`
-- `addHttpResponseMiddleware`
-- `removeHttpRequestMiddleware`
-- `removeHttpResponseMiddleware`
-- public TypeScript types for client, config, middleware, payloads, and typed route maps
+- you want to define endpoint keys
+- you want to define the project-wide error type
+- you want all consumers to infer the same API schema