@dev.smartpricing/platform-layer 0.0.2 → 0.0.3

package/README.md

@@ -0,0 +1,568 @@
+# @dev.smartpricing/platform-layer
+
+Nuxt layer providing authentication, API client, and data-fetching composables for the Smartness platform. Built on [`ofetch`](https://github.com/unjs/ofetch) and [`@pinia/colada`](https://pinia-colada.esm.dev). Designed for any Nuxt application that needs to interact with the Smartness backend.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Setup](#setup)
+- [What's Included](#whats-included)
+- [API Client](#api-client)
+  - [`createApiClient()`](#createapiclientoptions)
+  - [`useApiClient()`](#useapiclient)
+- [Authentication](#authentication)
+  - [`useAuth()`](#useauth)
+- [Queries](#queries)
+- [Mutations](#mutations)
+- [Overriding Layer Behavior](#overriding-layer-behavior)
+- [Development](#development)
+
+## Installation
+
+```bash
+pnpm add @dev.smartpricing/platform-layer
+```
+
+### Peer Dependencies
+
+The layer requires the Smartness UI layer:
+
+```bash
+pnpm add nuxt-ui-layer@"github:smartpricing/smartness-nuxt-ui#v1.6.3"
+```
+
+## Setup
+
+### 1. Extend the Layer
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@dev.smartpricing/platform-layer'],
+})
+```
+
+### 2. Configure Runtime Environment
+
+Set these environment variables (or define them in `nuxt.config.ts` under `runtimeConfig.public`):
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NUXT_PUBLIC_BACKEND_BASE_URL` | Backend API base URL | `''` |
+| `NUXT_PUBLIC_ENV_CSRF_COOKIE_NAME` | CSRF cookie name | `smt_csrf` |
+| `NUXT_PUBLIC_PLATFORM_URL` | Platform URL for auth redirects | `''` |
+
+```bash
+# .env
+NUXT_PUBLIC_BACKEND_BASE_URL=https://api.smartpricing.com
+NUXT_PUBLIC_ENV_CSRF_COOKIE_NAME=smt_csrf
+NUXT_PUBLIC_PLATFORM_URL=https://app.smartpricing.com
+```
+
+## What's Included
+
+The layer auto-registers these [Nuxt modules](https://nuxt.com/docs/guide/concepts/modules):
+
+| Module | Purpose | Docs |
+|--------|---------|------|
+| [`@pinia/nuxt`](https://pinia.vuejs.org/ssr/nuxt.html) | State management | [Pinia docs](https://pinia.vuejs.org) |
+| [`@pinia/colada-nuxt`](https://pinia-colada.esm.dev) | Async data caching, queries & mutations | [Pinia Colada docs](https://pinia-colada.esm.dev) |
+| [`@nuxtjs/i18n`](https://i18n.nuxtjs.org) | Internationalization (en, it, de, es) | [Nuxt i18n docs](https://i18n.nuxtjs.org) |
+| [`@vueuse/nuxt`](https://vueuse.org/nuxt/README.html) | Utility composables | [VueUse docs](https://vueuse.org) |
+| [`nuxt-ui-layer`](https://github.com/smartpricing/smartness-nuxt-ui) | Smartness design system | — |
+
+All composables, queries, and mutations are **auto-imported** — no manual imports needed.
+
+---
+
+## API Client
+
+### `createApiClient(options)`
+
+> Factory function that creates a configured [`$fetch`](https://github.com/unjs/ofetch) instance using [`ofetch.create()`](https://github.com/unjs/ofetch#%EF%B8%8F-create-fetch-with-default-options). This is a low-level utility — most apps should use [`useApiClient()`](#useapiclient) instead.
+
+#### Options
+
+```ts
+interface ApiClientOptions {
+  baseURL: string
+  csrf?: ApiClientCsrfConfig
+  auth?: ApiClientAuthConfig
+  errorSerializer?: (context: { status: number; statusText: string; data: unknown }) => unknown
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `baseURL` | `string` | Base URL prepended to all requests. Slash handling is automatic ([ofetch docs](https://github.com/unjs/ofetch#baseurl)). |
+| `csrf` | `ApiClientCsrfConfig` | CSRF token injection config. |
+| `auth` | `ApiClientAuthConfig` | Auth config for token refresh and MFA. When omitted, returns a raw `$fetch` instance with no auth handling. |
+| `errorSerializer` | `(context) => unknown` | Custom error serializer. Receives `{ status, statusText, data }` from [`FetchError`](https://github.com/unjs/ofetch#%EF%B8%8F-access-to-raw-response). |
+
+#### CSRF Config
+
+```ts
+interface ApiClientCsrfConfig {
+  cookieName: string
+  headerName?: string // default: 'X-CSRF-Token'
+}
+```
+
+The client reads the CSRF token from the specified cookie via Nuxt's [`useCookie()`](https://nuxt.com/docs/api/composables/use-cookie) and injects it as a request header on every request using an [`onRequest` interceptor](https://github.com/unjs/ofetch#%EF%B8%8F-interceptors).
+
+#### Auth Config
+
+```ts
+interface ApiClientAuthConfig {
+  refreshBaseURL: string
+  refreshEndpoint?: string  // default: '/api/auth/refresh'
+  platformURL: string
+  shouldRefresh?: (status: number, data: unknown) => boolean
+  onRefreshFailed?: () => void
+  mfa?: ApiClientMfaConfig
+}
+
+interface ApiClientMfaConfig {
+  shouldChallenge: (status: number, data: unknown) => boolean
+  challengePath?: string  // default: '/auth/mfa-challenge'
+}
+```
+
+When `auth` is provided, the client wraps the raw `$fetch` instance with error-handling logic:
+
+1. **MFA challenge** — If `mfa.shouldChallenge()` returns `true`, redirects the user to `{platformURL}{challengePath}?redirect={currentUrl}`.
+2. **Token refresh** — If `shouldRefresh()` returns `true` (default: `401` with `session.expired` or `session.missing` error code), calls `POST {refreshEndpoint}` with [`credentials: 'include'`](https://github.com/unjs/ofetch#%EF%B8%8F-adding-headers). On success, retries the original request once.
+3. **Refresh dedup** — Concurrent 401s share a single refresh call (module-level promise deduplication).
+4. **Refresh failure** — Calls `onRefreshFailed()` if the refresh itself fails.
+5. **Error serialization** — If `errorSerializer` is set, transforms [`FetchError`](https://github.com/unjs/ofetch#%EF%B8%8F-access-to-raw-response) before rethrowing.
+
+#### SSR Cookie Forwarding
+
+On the server, the client reads the incoming request cookies via Nuxt's [`useRequestHeaders()`](https://nuxt.com/docs/api/composables/use-request-headers) and forwards them to the backend, ensuring cookie-based auth works during SSR.
+
+#### Example: Custom Client
+
+```ts
+const client = createApiClient({
+  baseURL: 'https://api.example.com',
+  csrf: { cookieName: 'my_csrf' },
+  auth: {
+    refreshBaseURL: 'https://api.example.com',
+    platformURL: 'https://app.example.com',
+    onRefreshFailed: () => navigateTo('/login'),
+  },
+  errorSerializer: ({ status, data }) => ({
+    code: status,
+    message: (data as any)?.error?.message ?? 'Unknown error',
+  }),
+})
+
+const users = await client<User[]>('/users', { query: { active: true } })
+```
+
+---
+
+### `useApiClient()`
+
+> [Vue composable](https://vuejs.org/guide/reusability/composables.html) that returns a pre-configured `$fetch` instance using the layer's [runtime config](https://nuxt.com/docs/guide/going-further/runtime-config). This is the primary way to make API calls in consuming apps.
+
+Internally calls [`createApiClient()`](#createapiclientoptions) with the runtime config values (`BACKEND_BASE_URL`, `ENV_CSRF_COOKIE_NAME`, `PLATFORM_URL`).
+
+#### Features
+
+- **CSRF token injection** — Reads from the `smt_csrf` cookie, sends as `X-CSRF-Token` header.
+- **Auto token refresh** — On 401 with `session.expired`/`session.missing`, refreshes and retries once.
+- **MFA challenge** — On `otp_required` error code, redirects to `/auth/mfa-challenge`.
+- **SSR cookie forwarding** — Forwards request cookies during server-side rendering.
+- **Auth redirect** — Redirects to `{PLATFORM_URL}/auth/login` when refresh fails.
+
+#### Usage
+
+```vue
+<script setup lang="ts">
+// Auto-imported — no import needed
+const client = useApiClient()
+
+// GET with typed response
+const users = await client<User[]>('/api/users')
+
+// POST with body (auto-serialized as JSON)
+const created = await client<User>('/api/users', {
+  method: 'POST',
+  body: { name: 'Alice', email: 'alice@example.com' },
+})
+
+// GET with query parameters
+const filtered = await client<User[]>('/api/users', {
+  query: { role: 'admin', active: true },
+})
+```
+
+#### Using with Pinia Colada Queries
+
+```vue
+<script setup lang="ts">
+const client = useApiClient()
+
+const { data, status, error } = useQuery({
+  key: ['custom-data'],
+  query: () => client<MyData>('/api/custom-endpoint'),
+})
+</script>
+```
+
+#### Using with Pinia Colada Mutations
+
+```vue
+<script setup lang="ts">
+const client = useApiClient()
+
+const { mutateAsync, status } = useMutation({
+  mutation: (body: CreateItemRequest) =>
+    client<CreateItemResponse>('/api/items', {
+      method: 'POST',
+      body,
+    }),
+})
+
+async function handleSubmit(data: CreateItemRequest) {
+  try {
+    const result = await mutateAsync(data)
+  }
+  catch (error) {
+    // FetchError with parsed body in error.data
+  }
+}
+</script>
+```
+
+---
+
+## Authentication
+
+### `useAuth()`
+
+> [Vue composable](https://vuejs.org/guide/reusability/composables.html) that wraps the [`useLogoutMutation()`](#authentication-mutations) and provides a sign-out flow with redirect.
+
+#### Return Values
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `signOut` | `() => Promise<void>` | Calls `POST /api/auth/logout` then redirects to `{PLATFORM_URL}/auth/login` |
+| `logoutStatus` | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>` | [Mutation status](https://pinia-colada.esm.dev/guide/mutations.html) |
+| `logoutError` | `Ref<Error \| null>` | Error if logout failed |
+
+#### Usage
+
+```vue
+<script setup lang="ts">
+const { signOut, logoutStatus } = useAuth()
+</script>
+
+<template>
+  <button :disabled="logoutStatus === 'pending'" @click="signOut">
+    Sign Out
+  </button>
+</template>
+```
+
+---
+
+## Queries
+
+All queries use [`useQuery()`](https://pinia-colada.esm.dev/guide/queries.html) from Pinia Colada. Each returns reactive `data`, `status`, `error`, `asyncStatus`, `refetch`, and `refresh`.
+
+Each query file also exports a **key factory** (e.g., `sessionKeys`, `billingOverviewKeys`) for use with [`queryCache.invalidateQueries()`](https://pinia-colada.esm.dev/guide/mutations.html#query-invalidation).
+
+### Session & User
+
+| Composable | Endpoint | Response Type | Key Factory |
+|------------|----------|---------------|-------------|
+| `useSessionQuery()` | `GET /api/me` | `MeContextResponse` | `sessionKeys.me()` |
+| `usePermissionsQuery()` | `GET /api/me/permissions` | `PermissionsResponse` | `permissionsKeys.all()` |
+| `useCrossSellingQuery()` | `GET /api/me/cross-selling` | `GetCrossSellingResponse` | `crossSellingKeys.all()` |
+
+### Organization
+
+| Composable | Endpoint | Response Type | Key Factory |
+|------------|----------|---------------|-------------|
+| `useOrganizationQuery(orgId)` | `GET /api/orgs/{orgId}` | `OrganizationContextResponse` | `organizationKeys.byId(orgId)` |
+
+**Params:** `orgId: MaybeRefOrGetter<string>` — enabled only when `orgId` is truthy.
+
+### Billing
+
+| Composable | Endpoint | Response Type | Key Factory |
+|------------|----------|---------------|-------------|
+| `useBillingOverviewQuery(orgId)` | `GET /api/orgs/{orgId}/billing` | `BillingOverviewResponse` | `billingOverviewKeys.byOrg(orgId)` |
+| `useBillingDocumentsQuery(orgId, params?)` | `GET /api/orgs/{orgId}/billing/documents` | `ListBillingDocumentsResponse` | `billingDocumentsKeys.byOrg(orgId, params)` |
+| `useLegalEntityQuery(orgId, id)` | `GET /api/orgs/{orgId}/billing/legal-entities/{id}` | `LegalEntityDetail` | `legalEntityKeys.byId(orgId, id)` |
+| `useBillingDocumentPdfQuery(orgId, type, id)` | `GET /api/orgs/{orgId}/billing/documents/{type}/{id}/pdf` | `BillingDocumentPdfResponse` | `billingDocumentPdfKeys.byId(orgId, type, id)` |
+
+#### Billing Documents Filter Params
+
+```ts
+interface BillingDocumentsQueryParams {
+  legalEntityId?: string
+  customerId?: string
+  limit?: number
+  after?: string
+  before?: string
+  subscriptionIds?: string[]
+  type?: string
+  status?: string
+  search?: string
+}
+```
+
+### Query Usage Examples
+
+```vue
+<script setup lang="ts">
+const route = useRoute()
+
+// Static query — fetches immediately
+const { data: session, status } = useSessionQuery()
+
+// Dynamic query — re-fetches when orgId changes
+const { data: org } = useOrganizationQuery(() => route.params.orgId as string)
+
+// Conditional query with filter params
+const filters = ref<BillingDocumentsQueryParams>({ limit: 20 })
+const { data: docs } = useBillingDocumentsQuery(
+  () => route.params.orgId as string,
+  filters,
+)
+</script>
+
+<template>
+  <div v-if="status === 'pending'">Loading...</div>
+  <div v-else-if="status === 'error'">Error loading session</div>
+  <div v-else>Welcome, {{ session.name }}</div>
+</template>
+```
+
+### Invalidating Queries After Mutations
+
+Use the exported key factories with [`useQueryCache()`](https://pinia-colada.esm.dev/guide/mutations.html#query-invalidation):
+
+```vue
+<script setup lang="ts">
+import { useQueryCache } from '@pinia/colada'
+
+const queryCache = useQueryCache()
+
+const { mutateAsync: updateProfile } = useUpdateProfileMutation()
+
+async function handleSave(data: UpdateProfileRequest) {
+  await updateProfile(data)
+  // Invalidate session to refetch updated user data
+  queryCache.invalidateQueries({ key: sessionKeys.me() })
+}
+</script>
+```
+
+---
+
+## Mutations
+
+All mutations use [`useMutation()`](https://pinia-colada.esm.dev/guide/mutations.html) from Pinia Colada. Each returns:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `mutate` | `(params) => void` | Fire-and-forget — errors handled via `onError` hook |
+| `mutateAsync` | `(params) => Promise<TResult>` | Returns promise — use `try/catch` for errors |
+| `status` | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>` | Overall [mutation status](https://pinia-colada.esm.dev/guide/mutations.html) |
+| `asyncStatus` | `Ref<'idle' \| 'loading'>` | Whether a request is in-flight |
+| `data` | `Ref<TResult \| undefined>` | Last successful response |
+| `error` | `Ref<Error \| null>` | Last error |
+| `variables` | `Ref<TParams \| undefined>` | Last mutation parameters |
+| `reset` | `() => void` | Reset to initial state |
+
+### Authentication Mutations
+
+| Composable | Method | Endpoint | Request | Response |
+|------------|--------|----------|---------|----------|
+| `useLoginMutation()` | `POST` | `/api/auth/login` | `LoginRequest` | `void` |
+| `useLogoutMutation()` | `POST` | `/api/auth/logout` | — | `void` |
+| `useRefreshMutation()` | `POST` | `/api/auth/refresh` | — | `void` |
+| `useActivateMutation()` | `POST` | `/api/auth/activate` | `ActivateRequest` | `void` |
+| `useAccountingLoginMutation()` | `POST` | `/api/auth/accounting-login` | `AccountingLoginRequest` | `void` |
+
+### MFA Mutations
+
+| Composable | Method | Endpoint | Request | Response |
+|------------|--------|----------|---------|----------|
+| `useMfaSetupMutation()` | `POST` | `/api/auth/mfa/setup` | — | `MfaSetupResponse` |
+| `useMfaStepUpMutation()` | `POST` | `/api/auth/otp` | `MfaStepUpRequest` | `MfaStepUpResponse` |
+| `useMfaFinalizeMutation()` | `POST` | `/api/auth/mfa/finalize` | `MfaFinalizeRequest` | `MfaFinalizeResponse` |
+| `useMfaDisableMutation()` | `POST` | `/api/auth/mfa/disable` | `MfaDisableRequest` | `MfaDisableResponse` |
+| `useMfaRegenerateRecoveryCodesMutation()` | `POST` | `/api/auth/mfa/regenerate-recovery-codes` | `MfaRegenerateRecoveryCodesRequest` | `MfaRegenerateRecoveryCodesResponse` |
+
+### Profile Mutations
+
+| Composable | Method | Endpoint | Request | Response |
+|------------|--------|----------|---------|----------|
+| `useUpdateProfileMutation()` | `PATCH` | `/api/me` | `UpdateProfileRequest` | `UpdateProfileResponse` |
+| `useChangePasswordMutation()` | `POST` | `/api/me/change-password` | `ChangePasswordRequest` | `{ ok: true }` |
+| `useRequestPasswordResetMutation()` | `POST` | `/api/auth/request-password-reset` | `ForgotPasswordRequest` | `void` |
+| `useResetPasswordMutation()` | `POST` | `/api/auth/reset-password` | `ResetPasswordRequest` | `void` |
+
+### Billing Mutations
+
+| Composable | Method | Endpoint | Request | Response |
+|------------|--------|----------|---------|----------|
+| `useCreatePaymentMethodMutation()` | `POST` | `/api/orgs/{orgId}/billing/payment-methods` | `{ orgId, body: CreatePaymentMethodRequest }` | `CreatePaymentMethodsResponse` |
+| `useSetPrimaryPaymentMethodMutation()` | `PATCH` | `/api/orgs/{orgId}/billing/payment-methods/primary` | `{ orgId, body: SetPrimaryPaymentMethodRequest }` | `SetPrimaryPaymentMethodResponse` |
+| `useRemovePaymentMethodMutation()` | `DELETE` | `/api/orgs/{orgId}/billing/payment-methods/{paymentMethodId}` | `{ orgId, paymentMethodId }` | `void` |
+| `useCreateSetupIntentMutation()` | `POST` | `/api/orgs/{orgId}/billing/payment-methods/setup-intent` | `{ orgId, body: CreateSetupIntentRequest }` | `CreateSetupIntentResponse` |
+
+### Organization Mutations
+
+| Composable | Method | Endpoint | Request | Response |
+|------------|--------|----------|---------|----------|
+| `useUpdateLegalEntityMutation()` | `PATCH` | `/api/orgs/{orgId}/billing/legal-entities/{id}` | `{ orgId, id, body: UpdateLegalEntityRequest }` | `LegalEntityDetail` |
+| `useRequestLegalEntityChangeMutation()` | `POST` | `/api/orgs/{orgId}/billing/legal-entities/{id}/change-request` | `{ orgId, id, body: RequestLegalEntityChangeRequest }` | `{ emails_status: 'sent' \| 'failed' }` |
+| `useRequestSubscriptionCancellationMutation()` | `POST` | `/api/orgs/{orgId}/subscriptions/request-cancellation` | `{ orgId, body: SubscriptionCancellationRequest }` | `SubscriptionCancellationResponse` |
+
+### Mutation Usage Examples
+
+#### Login Flow
+
+```vue
+<script setup lang="ts">
+const { mutateAsync: login, status, error } = useLoginMutation()
+
+async function handleLogin(email: string, password: string) {
+  try {
+    await login({ email, password })
+    await navigateTo('/dashboard')
+  }
+  catch (err) {
+    // error.value is also set reactively
+  }
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleLogin(email, password)">
+    <p v-if="error">{{ error.message }}</p>
+    <button :disabled="status === 'pending'" type="submit">
+      {{ status === 'pending' ? 'Signing in...' : 'Sign In' }}
+    </button>
+  </form>
+</template>
+```
+
+#### MFA Setup Flow
+
+```vue
+<script setup lang="ts">
+const { mutateAsync: setupMfa } = useMfaSetupMutation()
+const { mutateAsync: finalizeMfa } = useMfaFinalizeMutation()
+
+// Step 1: Get QR code / secret
+const setupData = await setupMfa()
+
+// Step 2: User enters TOTP code, finalize
+await finalizeMfa({ otp: userCode })
+</script>
+```
+
+#### Billing Operations with Query Invalidation
+
+```vue
+<script setup lang="ts">
+import { useQueryCache } from '@pinia/colada'
+
+const queryCache = useQueryCache()
+const orgId = computed(() => route.params.orgId as string)
+
+const { mutateAsync: removeMethod, status } = useRemovePaymentMethodMutation()
+
+async function handleRemove(paymentMethodId: string) {
+  try {
+    await removeMethod({ orgId: orgId.value, paymentMethodId })
+
+    // Refetch billing data after removing payment method
+    queryCache.invalidateQueries({ key: billingOverviewKeys.byOrg(orgId.value) })
+  }
+  catch (err) {
+    // Handle error
+  }
+}
+</script>
+```
+
+#### Fire-and-Forget vs Async
+
+```vue
+<script setup lang="ts">
+const { mutate, mutateAsync, status, error } = useUpdateProfileMutation()
+
+// Fire-and-forget — errors are swallowed, check error ref reactively
+mutate({ name: 'New Name' })
+
+// Async — errors rethrown, use try/catch
+try {
+  const result = await mutateAsync({ name: 'New Name' })
+}
+catch (err) {
+  console.error('Update failed:', err)
+}
+</script>
+```
+
+> All request/response types are imported from `@package/platform-shared`. See the shared package for type definitions.
+
+---
+
+## Overriding Layer Behavior
+
+### Disable Bundled Modules
+
+If your app already provides a module the layer includes, [disable it](https://nuxt.com/docs/getting-started/layers#disable-layer-modules):
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@dev.smartpricing/platform-layer'],
+  i18n: false,    // disable layer's i18n
+  pinia: false,   // disable layer's pinia
+})
+```
+
+### Override i18n Locales
+
+The layer ships with `en`, `it`, `de`, `es`. Your app's [i18n config](https://i18n.nuxtjs.org/docs/options) takes precedence — add or override locales in your own `nuxt.config.ts`.
+
+### Override Layer Components/Composables
+
+Your project files always take [priority over layer files](https://nuxt.com/docs/getting-started/layers#layer-priority). Create a file with the same name in your app to override.
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start playground dev server
+pnpm --filter @dev.smartpricing/platform-layer dev
+
+# Prepare TypeScript
+pnpm --filter @dev.smartpricing/platform-layer dev:prepare
+
+# Build playground
+pnpm --filter @dev.smartpricing/platform-layer build
+```
+
+## Related Resources
+
+- [Nuxt Layers](https://nuxt.com/docs/getting-started/layers) — How Nuxt layers work
+- [ofetch](https://github.com/unjs/ofetch) — Universal fetch library powering `$fetch`
+- [Pinia Colada](https://pinia-colada.esm.dev) — Async data caching for Vue/Nuxt
+- [Pinia](https://pinia.vuejs.org) — State management for Vue
+- [Nuxt i18n](https://i18n.nuxtjs.org) — Internationalization module
+- [VueUse](https://vueuse.org) — Collection of Vue composables

package/app/utils/apiClient.utils.ts

@@ -1,5 +1,9 @@
+import type { FetchContext, FetchHook } from 'ofetch'
 import { FetchError } from 'ofetch'
 
+type OnRequestHook = FetchHook<FetchContext>
+type OnResponseErrorHook = FetchHook<FetchContext & { response: Response }>
+
 export interface ApiClientCsrfConfig {
   cookieName: string
   headerName?: string
@@ -24,6 +28,8 @@ export interface ApiClientOptions {
   csrf?: ApiClientCsrfConfig
   auth?: ApiClientAuthConfig
   errorSerializer?: (context: { status: number; statusText: string; data: unknown }) => unknown
+  onRequest?: OnRequestHook
+  onResponseError?: OnResponseErrorHook
 }
 
 function defaultShouldRefresh(status: number, data: unknown): boolean {
@@ -36,26 +42,33 @@ function defaultShouldRefresh(status: number, data: unknown): boolean {
 let refreshPromise: Promise<boolean> | null = null
 
 export function createApiClient(options: ApiClientOptions) {
-  const client = $fetch.create({
-    baseURL: options.baseURL,
-    credentials: 'include',
-    onRequest({ options: reqOpts }) {
-      // SSR: forward cookies from incoming request
-      if (import.meta.server) {
-        const { cookie } = useRequestHeaders(['cookie'])
-        if (cookie) {
-          reqOpts.headers.set('cookie', cookie)
-        }
+  const builtInOnRequest: OnRequestHook = ({ options: reqOpts }) => {
+    // SSR: forward cookies from incoming request
+    if (import.meta.server) {
+      const { cookie } = useRequestHeaders(['cookie'])
+      if (cookie) {
+        reqOpts.headers.set('cookie', cookie)
       }
+    }
 
-      // CSRF: inject token header
-      if (options.csrf) {
-        const token = useCookie(options.csrf.cookieName).value
-        if (token) {
-          reqOpts.headers.set(options.csrf.headerName ?? 'X-CSRF-Token', token)
-        }
+    // CSRF: inject token header
+    if (options.csrf) {
+      const token = useCookie(options.csrf.cookieName).value
+      if (token) {
+        reqOpts.headers.set(options.csrf.headerName ?? 'X-CSRF-Token', token)
       }
-    },
+    }
+  }
+
+  const onRequestHooks: OnRequestHook[] = [builtInOnRequest]
+  if (options.onRequest) {
+    onRequestHooks.push(...(Array.isArray(options.onRequest) ? options.onRequest : [options.onRequest]))
+  }
+
+  const client = $fetch.create({
+    baseURL: options.baseURL,
+    credentials: 'include',
+    onRequest: onRequestHooks,
   })
 
   // No auth handling needed — return raw $fetch instance
@@ -126,6 +139,14 @@ export function createApiClient(options: ApiClientOptions) {
         auth.onRefreshFailed?.()
       }
 
+      // Call consumer's onResponseError hooks
+      if (options.onResponseError) {
+        const hooks = Array.isArray(options.onResponseError) ? options.onResponseError : [options.onResponseError]
+        for (const hook of hooks) {
+          await hook({ request: url, response: error.response!, options: fetchOptions ?? {} } as FetchContext & { response: Response })
+        }
+      }
+
       serializeAndThrow(error)
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev.smartpricing/platform-layer",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "private": false,
   "main": "./nuxt.config.ts",