@dev.smartpricing/platform-layer 0.0.3 → 0.0.5

package/README.md

@@ -38,24 +38,26 @@ pnpm add nuxt-ui-layer@"github:smartpricing/smartness-nuxt-ui#v1.6.3"
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
-  extends: ['@dev.smartpricing/platform-layer'],
-})
+  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 | `''` |
+| Variable                       | Description                     | Default    |
+| ------------------------------ | ------------------------------- | ---------- |
+| `NUXT_PUBLIC_BACKEND_BASE_URL` | Backend API base URL            | `''`       |
+| `NUXT_PUBLIC_CSRF_COOKIE_NAME` | CSRF cookie name                | `smt_csrf` |
+| `NUXT_PUBLIC_ENVIRONMENT`      | Environment                     | `local`    |
+| `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_CSRF_COOKIE_NAME=smt_csrf
+ENVIRONMENT=local
 NUXT_PUBLIC_PLATFORM_URL=https://app.smartpricing.com
 ```
 
@@ -63,13 +65,13 @@ NUXT_PUBLIC_PLATFORM_URL=https://app.smartpricing.com
 
 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 | — |
+| 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.
 
@@ -85,26 +87,34 @@ All composables, queries, and mutations are **auto-imported** — no manual impo
 
 ```ts
 interface ApiClientOptions {
-  baseURL: string
-  csrf?: ApiClientCsrfConfig
-  auth?: ApiClientAuthConfig
-  errorSerializer?: (context: { status: number; statusText: string; data: unknown }) => unknown
+  baseURL: string;
+  csrf?: ApiClientCsrfConfig;
+  auth?: ApiClientAuthConfig;
+  errorSerializer?: (context: {
+    status: number;
+    statusText: string;
+    data: unknown;
+  }) => unknown;
+  onRequest?: FetchHook<FetchContext>;
+  onResponseError?: FetchHook<FetchContext & { response: Response }>;
 }
 ```
 
-| 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). |
+| 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). |
+| `onRequest`       | `FetchHook<FetchContext>`                          | Custom [`onRequest` interceptor](https://github.com/unjs/ofetch#%EF%B8%8F-interceptors) appended after built-in hooks (cookie forwarding, CSRF).       |
+| `onResponseError` | `FetchHook<FetchContext & { response: Response }>` | Custom [`onResponseError` interceptor](https://github.com/unjs/ofetch#%EF%B8%8F-interceptors) called after auth/MFA handling.                          |
 
 #### CSRF Config
 
 ```ts
 interface ApiClientCsrfConfig {
-  cookieName: string
-  headerName?: string // default: 'X-CSRF-Token'
+  cookieName: string;
+  headerName?: string; // default: 'X-CSRF-Token'
 }
 ```
 
@@ -114,17 +124,17 @@ The client reads the CSRF token from the specified cookie via Nuxt's [`useCookie
 
 ```ts
 interface ApiClientAuthConfig {
-  refreshBaseURL: string
-  refreshEndpoint?: string  // default: '/api/auth/refresh'
-  platformURL: string
-  shouldRefresh?: (status: number, data: unknown) => boolean
-  onRefreshFailed?: () => void
-  mfa?: ApiClientMfaConfig
+  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'
+  shouldChallenge: (status: number, data: unknown) => boolean;
+  challengePath?: string; // default: '/auth/mfa-challenge'
 }
 ```
 
@@ -144,20 +154,20 @@ On the server, the client reads the incoming request cookies via Nuxt's [`useReq
 
 ```ts
 const client = createApiClient({
-  baseURL: 'https://api.example.com',
-  csrf: { cookieName: 'my_csrf' },
+  baseURL: "https://api.example.com",
+  csrf: { cookieName: "my_csrf" },
   auth: {
-    refreshBaseURL: 'https://api.example.com',
-    platformURL: 'https://app.example.com',
-    onRefreshFailed: () => navigateTo('/login'),
+    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',
+    message: (data as any)?.error?.message ?? "Unknown error",
   }),
-})
+});
 
-const users = await client<User[]>('/users', { query: { active: true } })
+const users = await client<User[]>("/users", { query: { active: true } });
 ```
 
 ---
@@ -202,12 +212,12 @@ const filtered = await client<User[]>('/api/users', {
 
 ```vue
 <script setup lang="ts">
-const client = useApiClient()
+const client = useApiClient();
 
 const { data, status, error } = useQuery({
-  key: ['custom-data'],
-  query: () => client<MyData>('/api/custom-endpoint'),
-})
+  key: ["custom-data"],
+  query: () => client<MyData>("/api/custom-endpoint"),
+});
 </script>
 ```
 
@@ -215,21 +225,20 @@ const { data, status, error } = useQuery({
 
 ```vue
 <script setup lang="ts">
-const client = useApiClient()
+const client = useApiClient();
 
 const { mutateAsync, status } = useMutation({
   mutation: (body: CreateItemRequest) =>
-    client<CreateItemResponse>('/api/items', {
-      method: 'POST',
+    client<CreateItemResponse>("/api/items", {
+      method: "POST",
       body,
     }),
-})
+});
 
 async function handleSubmit(data: CreateItemRequest) {
   try {
-    const result = await mutateAsync(data)
-  }
-  catch (error) {
+    const result = await mutateAsync(data);
+  } catch (error) {
     // FetchError with parsed body in error.data
   }
 }
@@ -246,17 +255,17 @@ async function handleSubmit(data: CreateItemRequest) {
 
 #### 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 |
+| 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()
+const { signOut, logoutStatus } = useAuth();
 </script>
 
 <template>
@@ -276,42 +285,42 @@ Each query file also exports a **key factory** (e.g., `sessionKeys`, `billingOve
 
 ### Session & User
 
-| Composable | Endpoint | Response Type | Key Factory |
-|------------|----------|---------------|-------------|
-| `useSessionQuery()` | `GET /api/me` | `MeContextResponse` | `sessionKeys.me()` |
-| `usePermissionsQuery()` | `GET /api/me/permissions` | `PermissionsResponse` | `permissionsKeys.all()` |
+| 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 |
-|------------|----------|---------------|-------------|
+| 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)` |
+| 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
+  legalEntityId?: string;
+  customerId?: string;
+  limit?: number;
+  after?: string;
+  before?: string;
+  subscriptionIds?: string[];
+  type?: string;
+  status?: string;
+  search?: string;
 }
 ```
 
@@ -319,20 +328,20 @@ interface BillingDocumentsQueryParams {
 
 ```vue
 <script setup lang="ts">
-const route = useRoute()
+const route = useRoute();
 
 // Static query — fetches immediately
-const { data: session, status } = useSessionQuery()
+const { data: session, status } = useSessionQuery();
 
 // Dynamic query — re-fetches when orgId changes
-const { data: org } = useOrganizationQuery(() => route.params.orgId as string)
+const { data: org } = useOrganizationQuery(() => route.params.orgId as string);
 
 // Conditional query with filter params
-const filters = ref<BillingDocumentsQueryParams>({ limit: 20 })
+const filters = ref<BillingDocumentsQueryParams>({ limit: 20 });
 const { data: docs } = useBillingDocumentsQuery(
   () => route.params.orgId as string,
   filters,
-)
+);
 </script>
 
 <template>
@@ -348,16 +357,16 @@ Use the exported key factories with [`useQueryCache()`](https://pinia-colada.esm
 
 ```vue
 <script setup lang="ts">
-import { useQueryCache } from '@pinia/colada'
+import { useQueryCache } from "@pinia/colada";
 
-const queryCache = useQueryCache()
+const queryCache = useQueryCache();
 
-const { mutateAsync: updateProfile } = useUpdateProfileMutation()
+const { mutateAsync: updateProfile } = useUpdateProfileMutation();
 
 async function handleSave(data: UpdateProfileRequest) {
-  await updateProfile(data)
+  await updateProfile(data);
   // Invalidate session to refetch updated user data
-  queryCache.invalidateQueries({ key: sessionKeys.me() })
+  queryCache.invalidateQueries({ key: sessionKeys.me() });
 }
 </script>
 ```
@@ -368,62 +377,62 @@ async function handleSave(data: UpdateProfileRequest) {
 
 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 |
+| 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` |
+| 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` |
+| 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` |
+| 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` |
+| 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` |
+| 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
 
@@ -431,14 +440,13 @@ All mutations use [`useMutation()`](https://pinia-colada.esm.dev/guide/mutations
 
 ```vue
 <script setup lang="ts">
-const { mutateAsync: login, status, error } = useLoginMutation()
+const { mutateAsync: login, status, error } = useLoginMutation();
 
 async function handleLogin(email: string, password: string) {
   try {
-    await login({ email, password })
-    await navigateTo('/dashboard')
-  }
-  catch (err) {
+    await login({ email, password });
+    await navigateTo("/dashboard");
+  } catch (err) {
     // error.value is also set reactively
   }
 }
@@ -448,7 +456,7 @@ async function handleLogin(email: string, password: string) {
   <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' }}
+      {{ status === "pending" ? "Signing in..." : "Sign In" }}
     </button>
   </form>
 </template>
@@ -458,14 +466,14 @@ async function handleLogin(email: string, password: string) {
 
 ```vue
 <script setup lang="ts">
-const { mutateAsync: setupMfa } = useMfaSetupMutation()
-const { mutateAsync: finalizeMfa } = useMfaFinalizeMutation()
+const { mutateAsync: setupMfa } = useMfaSetupMutation();
+const { mutateAsync: finalizeMfa } = useMfaFinalizeMutation();
 
 // Step 1: Get QR code / secret
-const setupData = await setupMfa()
+const setupData = await setupMfa();
 
 // Step 2: User enters TOTP code, finalize
-await finalizeMfa({ otp: userCode })
+await finalizeMfa({ otp: userCode });
 </script>
 ```
 
@@ -473,21 +481,22 @@ await finalizeMfa({ otp: userCode })
 
 ```vue
 <script setup lang="ts">
-import { useQueryCache } from '@pinia/colada'
+import { useQueryCache } from "@pinia/colada";
 
-const queryCache = useQueryCache()
-const orgId = computed(() => route.params.orgId as string)
+const queryCache = useQueryCache();
+const orgId = computed(() => route.params.orgId as string);
 
-const { mutateAsync: removeMethod, status } = useRemovePaymentMethodMutation()
+const { mutateAsync: removeMethod, status } = useRemovePaymentMethodMutation();
 
 async function handleRemove(paymentMethodId: string) {
   try {
-    await removeMethod({ orgId: orgId.value, paymentMethodId })
+    await removeMethod({ orgId: orgId.value, paymentMethodId });
 
     // Refetch billing data after removing payment method
-    queryCache.invalidateQueries({ key: billingOverviewKeys.byOrg(orgId.value) })
-  }
-  catch (err) {
+    queryCache.invalidateQueries({
+      key: billingOverviewKeys.byOrg(orgId.value),
+    });
+  } catch (err) {
     // Handle error
   }
 }
@@ -498,17 +507,16 @@ async function handleRemove(paymentMethodId: string) {
 
 ```vue
 <script setup lang="ts">
-const { mutate, mutateAsync, status, error } = useUpdateProfileMutation()
+const { mutate, mutateAsync, status, error } = useUpdateProfileMutation();
 
 // Fire-and-forget — errors are swallowed, check error ref reactively
-mutate({ name: 'New Name' })
+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)
+  const result = await mutateAsync({ name: "New Name" });
+} catch (err) {
+  console.error("Update failed:", err);
 }
 </script>
 ```
@@ -526,10 +534,10 @@ If your app already provides a module the layer includes, [disable it](https://n
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
-  extends: ['@dev.smartpricing/platform-layer'],
-  i18n: false,    // disable layer's i18n
-  pinia: false,   // disable layer's pinia
-})
+  extends: ["@dev.smartpricing/platform-layer"],
+  i18n: false, // disable layer's i18n
+  pinia: false, // disable layer's pinia
+});
 ```
 
 ### Override i18n Locales

package/_shared/mfa.ts

@@ -58,6 +58,30 @@ export const MfaRegenerateRecoveryCodesResponseSchema = z.object({
   recovery_codes: z.array(z.string()),
 })
 
+// ── Send email code ────────────────────────────────────────────────
+
+export const MfaSendEmailCodeRequestSchema = z.object({
+  enrollmentId: z.string(),
+})
+
+export const MfaSendEmailCodeResponseSchema = z.object({
+  sent: z.literal(true),
+  email_masked: z.string(),
+  expires_in_seconds: z.number(),
+  retry_after_seconds: z.number(),
+})
+
+// ── Verify email ───────────────────────────────────────────────────
+
+export const MfaVerifyEmailRequestSchema = z.object({
+  enrollmentId: z.string(),
+  emailCode: z.string(),
+})
+
+export const MfaVerifyEmailResponseSchema = z.object({
+  verified: z.literal(true),
+})
+
 // ── Types ───────────────────────────────────────────────────────────
 
 export type MfaStepUpRequest = z.infer<typeof MfaStepUpRequestSchema>
@@ -73,3 +97,9 @@ export type MfaDisableResponse = z.infer<typeof MfaDisableResponseSchema>
 
 export type MfaRegenerateRecoveryCodesRequest = z.infer<typeof MfaRegenerateRecoveryCodesRequestSchema>
 export type MfaRegenerateRecoveryCodesResponse = z.infer<typeof MfaRegenerateRecoveryCodesResponseSchema>
+
+export type MfaSendEmailCodeRequest = z.infer<typeof MfaSendEmailCodeRequestSchema>
+export type MfaSendEmailCodeResponse = z.infer<typeof MfaSendEmailCodeResponseSchema>
+
+export type MfaVerifyEmailRequest = z.infer<typeof MfaVerifyEmailRequestSchema>
+export type MfaVerifyEmailResponse = z.infer<typeof MfaVerifyEmailResponseSchema>

package/app/components/LayerProductSwitcher.vue

@@ -0,0 +1,25 @@
+<script setup lang="ts">
+import type { SuiteProduct } from 'nuxt-ui-layer/types'
+
+const props = defineProps<{
+  product: SuiteProduct
+  collapsed?: boolean
+}>()
+
+const { enabledProducts, navigateToProduct } = useProductSwitcher()
+
+const selectedProduct = shallowRef<SuiteProduct>(props.product)
+
+watch(selectedProduct, (value) => {
+  if (value !== props.product)
+    navigateToProduct(value)
+})
+</script>
+
+<template>
+  <SNavigationProducts
+    v-model="selectedProduct"
+    :products="enabledProducts"
+    :collapsed="collapsed"
+  />
+</template>

package/app/composables/apiClient.composable.ts

@@ -1,10 +1,15 @@
 export function useApiClient() {
-  const { BACKEND_BASE_URL, ENV_CSRF_COOKIE_NAME, PLATFORM_URL } = useRuntimeConfig().public
+  const { BACKEND_BASE_URL, CSRF_COOKIE_NAME, PLATFORM_URL, ENVIRONMENT } = useRuntimeConfig().public
+
+
+  const baseCsrfName = (CSRF_COOKIE_NAME as string | undefined) || 'smt_csrf'
+  const environment = (ENVIRONMENT as string | undefined) || 'local'
+  const csrfCookieName = environment === 'prod' ? baseCsrfName : `${baseCsrfName}_${environment}`
 
   return createApiClient({
     baseURL: BACKEND_BASE_URL as string,
     csrf: {
-      cookieName: (ENV_CSRF_COOKIE_NAME as string) || 'smt_csrf',
+      cookieName: csrfCookieName
     },
     auth: {
       refreshBaseURL: BACKEND_BASE_URL as string,
@@ -16,7 +21,7 @@ export function useApiClient() {
         },
       },
       onRefreshFailed: () => {
-        if (import.meta.client) {
+        if (import.meta.client && !window.location.pathname.startsWith('/auth/login')) {
           window.location.assign(`${PLATFORM_URL}/auth/login`)
         }
       },

package/app/composables/useProductSwitcher.composable.ts

@@ -0,0 +1,70 @@
+import type { SuiteProduct } from 'nuxt-ui-layer/types'
+import { computed } from 'vue'
+
+export function useProductSwitcher() {
+  const { data: permissions, status } = usePermissionsQuery()
+  const config = useRuntimeConfig().public
+
+  const productUrls: Record<string, string> = {
+    config: config.PLATFORM_APP_URL,
+    pricing: config.PRICING_APP_URL,
+    connect: config.CONNECT_APP_URL,
+    chat: config.CHAT_APP_URL,
+    pms: config.PMS_APP_URL,
+  }
+
+  /** All enabled product keys (from /permission + always-on "config"). */
+  const enabledProducts = computed<SuiteProduct[]>(() => {
+    // "config" is a new SuiteProduct value added in smartness-nuxt-ui — cast
+    // needed until the updated nuxt-ui-layer package is published.
+    const enabled: SuiteProduct[] = ['config' as SuiteProduct]
+
+    if (!permissions.value)
+      return enabled
+
+    const products = permissions.value.products
+    const mapping: Record<string, SuiteProduct> = {
+      pricing: 'pricing',
+      connect: 'connect',
+      chat: 'chat',
+      smartpms: 'pms',
+    }
+
+    for (const [key, product] of Object.entries(products)) {
+      if (product.enabled) {
+        const mapped = mapping[key]
+        if (mapped)
+          enabled.push(mapped)
+      }
+    }
+
+    return enabled
+  })
+
+  const isLoading = computed(() => status.value === 'pending')
+
+  function navigateToProduct(product?: SuiteProduct) {
+    if (!product) return
+
+    const isEnabled = enabledProducts.value.includes(product)
+    if (!isEnabled) {
+      window.open(`${window.location.origin}/upgrade`, '_blank', 'noopener,noreferrer')
+      return
+    }
+
+    const url = productUrls[product]
+    if (url)
+      location.assign(url)
+  }
+
+  function getProductUrl(product: SuiteProduct): string | undefined {
+    return productUrls[product] || undefined
+  }
+
+  return {
+    enabledProducts,
+    isLoading,
+    navigateToProduct,
+    getProductUrl,
+  }
+}

package/app/mutations/useMfaSendEmailCode.mutation.ts

@@ -0,0 +1,10 @@
+import type { MfaSendEmailCodeRequest, MfaSendEmailCodeResponse } from '@package/platform-shared'
+
+export function useMfaSendEmailCodeMutation() {
+  const client = useApiClient()
+
+  return useMutation({
+    mutation: (body: MfaSendEmailCodeRequest) =>
+      client<MfaSendEmailCodeResponse>('/api/auth/mfa/send-email-code', { method: 'POST', body }),
+  })
+}

package/app/mutations/useMfaVerifyEmail.mutation.ts

@@ -0,0 +1,10 @@
+import type { MfaVerifyEmailRequest, MfaVerifyEmailResponse } from '@package/platform-shared'
+
+export function useMfaVerifyEmailMutation() {
+  const client = useApiClient()
+
+  return useMutation({
+    mutation: (body: MfaVerifyEmailRequest) =>
+      client<MfaVerifyEmailResponse>('/api/auth/mfa/verify-email', { method: 'POST', body }),
+  })
+}

package/nuxt.config.ts

@@ -1,13 +1,16 @@
 import { dirname, join } from 'node:path'
+import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
 const currentDir = dirname(fileURLToPath(import.meta.url))
+const sharedDir = join(currentDir, '_shared')
 
 export default defineNuxtConfig({
   extends: ['nuxt-ui-layer'],
 
   alias: {
-    '@package/platform-shared': join(currentDir, '_shared'),
+    // _shared exists only in published tarball (created by prepack script)
+    ...(existsSync(sharedDir) && { '@package/platform-shared': sharedDir }),
   },
 
   modules: [
@@ -43,8 +46,15 @@ export default defineNuxtConfig({
   runtimeConfig: {
     public: {
       BACKEND_BASE_URL: '',
-      ENV_CSRF_COOKIE_NAME: '',
+      CSRF_COOKIE_NAME: '',
       PLATFORM_URL: '',
+      ENVIRONMENT: '',
+      // Standard product URL convention: {PRODUCT}_APP_URL
+      PLATFORM_APP_URL: '',
+      PRICING_APP_URL: '',
+      CONNECT_APP_URL: '',
+      CHAT_APP_URL: '',
+      PMS_APP_URL: '',
     },
   },
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev.smartpricing/platform-layer",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "private": false,
   "main": "./nuxt.config.ts",
@@ -19,7 +19,7 @@
   },
   "devDependencies": {
     "nuxt": "^4.4.2",
-    "nuxt-ui-layer": "github:smartpricing/smartness-nuxt-ui#v1.6.3",
+    "nuxt-ui-layer": "github:smartpricing/smartness-nuxt-ui#v1.6.19-platform.0",
     "vue": "latest"
   },
   "peerDependencies": {
@@ -29,6 +29,6 @@
     "dev": "nuxi dev .playground",
     "dev:prepare": "nuxt prepare .playground",
     "build": "nuxt build .playground",
-    "postinstall": "nuxt prepare"
+    "postinstall": "nuxt prepare .playground"
   }
 }