@dev.smartpricing/platform-layer 0.0.4 → 0.0.6

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,30 +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
-  onRequest?: FetchHook<FetchContext>
-  onResponseError?: FetchHook<FetchContext & { response: Response }>
+  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). |
-| `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. |
+| 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'
 }
 ```
 
@@ -118,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'
 }
 ```
 
@@ -148,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 } });
 ```
 
 ---
@@ -206,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>
 ```
 
@@ -219,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
   }
 }
@@ -250,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>
@@ -280,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;
 }
 ```
 
@@ -323,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>
@@ -352,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>
 ```
@@ -372,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
 
@@ -435,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
   }
 }
@@ -452,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>
@@ -462,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>
 ```
 
@@ -477,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
   }
 }
@@ -502,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>
 ```
@@ -530,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/billingGeo.ts

@@ -0,0 +1,158 @@
+/**
+ * Static geo/billing lists for the legal-entity form dropdowns.
+ *
+ * The three code lists mirror the PostgreSQL enums core-api enforces on
+ * `legal_entities` (see `core-api/packages/db-schema/src/schema/enums.ts`:
+ * `iso_a2_country_code`, `vat_number_prefix_type`, `iso_phone_country_code`).
+ * Anything outside these lists is rejected server-side with a 400, so the
+ * UI must not offer it. Keep them in sync when core-api adds values.
+ */
+
+/** ISO 3166-1 alpha-2 billing countries (`iso_a2_country_code`). Note "IC"
+ * (Canary Islands) is a tax territory with no `Intl.DisplayNames` name —
+ * label it via the fallback. */
+export const ISO_A2_COUNTRY_CODES = [
+  'AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AQ', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ',
+  'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', 'BJ', 'BL', 'BM', 'BN', 'BO', 'BQ', 'BR', 'BS',
+  'BT', 'BV', 'BW', 'BY', 'BZ', 'CA', 'CC', 'CD', 'CF', 'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN',
+  'CO', 'CR', 'CU', 'CV', 'CW', 'CX', 'CY', 'CZ', 'DE', 'DJ', 'DK', 'DM', 'DO', 'DZ', 'EC', 'EE',
+  'EG', 'EH', 'ER', 'ES', 'ET', 'FI', 'FJ', 'FK', 'FM', 'FO', 'FR', 'GA', 'GB', 'GD', 'GE', 'GF',
+  'GG', 'GH', 'GI', 'GL', 'GM', 'GN', 'GP', 'GQ', 'GR', 'GS', 'GT', 'GU', 'GW', 'GY', 'HK', 'HM',
+  'HN', 'HR', 'HT', 'HU', 'IC', 'ID', 'IE', 'IL', 'IM', 'IN', 'IO', 'IQ', 'IR', 'IS', 'IT', 'JE',
+  'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', 'KP', 'KR', 'KW', 'KY', 'KZ', 'LA', 'LB',
+  'LC', 'LI', 'LK', 'LR', 'LS', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'ME', 'MF', 'MG', 'MH',
+  'MK', 'ML', 'MM', 'MN', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT', 'MU', 'MV', 'MW', 'MX', 'MY', 'MZ',
+  'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NL', 'NO', 'NP', 'NR', 'NU', 'NZ', 'OM', 'PA', 'PE', 'PF',
+  'PG', 'PH', 'PK', 'PL', 'PM', 'PN', 'PR', 'PS', 'PT', 'PW', 'PY', 'QA', 'RE', 'RO', 'RS', 'RU',
+  'RW', 'SA', 'SB', 'SC', 'SD', 'SE', 'SG', 'SH', 'SI', 'SJ', 'SK', 'SL', 'SM', 'SN', 'SO', 'SR',
+  'SS', 'ST', 'SV', 'SX', 'SY', 'SZ', 'TC', 'TD', 'TF', 'TG', 'TH', 'TJ', 'TK', 'TL', 'TM', 'TN',
+  'TO', 'TR', 'TT', 'TV', 'TW', 'TZ', 'UA', 'UG', 'UM', 'US', 'UY', 'UZ', 'VA', 'VC', 'VE', 'VG',
+  'VI', 'VN', 'VU', 'WF', 'WS', 'YE', 'YT', 'ZA', 'ZM', 'ZW',
+] as const
+
+/** VAT-number prefixes (`vat_number_prefix_type`): the country list plus the
+ * VAT-only codes "EL" (Greece) and "XI" (Northern Ireland). */
+export const VAT_NUMBER_PREFIXES = [
+  'AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AQ', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ',
+  'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', 'BJ', 'BL', 'BM', 'BN', 'BO', 'BQ', 'BR', 'BS',
+  'BT', 'BV', 'BW', 'BY', 'BZ', 'CA', 'CC', 'CD', 'CF', 'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN',
+  'CO', 'CR', 'CU', 'CV', 'CW', 'CX', 'CY', 'CZ', 'DE', 'DJ', 'DK', 'DM', 'DO', 'DZ', 'EC', 'EE',
+  'EG', 'EH', 'EL', 'ER', 'ES', 'ET', 'FI', 'FJ', 'FK', 'FM', 'FO', 'FR', 'GA', 'GB', 'GD', 'GE',
+  'GF', 'GG', 'GH', 'GI', 'GL', 'GM', 'GN', 'GP', 'GQ', 'GR', 'GS', 'GT', 'GU', 'GW', 'GY', 'HK',
+  'HM', 'HN', 'HR', 'HT', 'HU', 'IC', 'ID', 'IE', 'IL', 'IM', 'IN', 'IO', 'IQ', 'IR', 'IS', 'IT',
+  'JE', 'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', 'KP', 'KR', 'KW', 'KY', 'KZ', 'LA',
+  'LB', 'LC', 'LI', 'LK', 'LR', 'LS', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'ME', 'MF', 'MG',
+  'MH', 'MK', 'ML', 'MM', 'MN', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT', 'MU', 'MV', 'MW', 'MX', 'MY',
+  'MZ', 'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NL', 'NO', 'NP', 'NR', 'NU', 'NZ', 'OM', 'PA', 'PE',
+  'PF', 'PG', 'PH', 'PK', 'PL', 'PM', 'PN', 'PR', 'PS', 'PT', 'PW', 'PY', 'QA', 'RE', 'RO', 'RS',
+  'RU', 'RW', 'SA', 'SB', 'SC', 'SD', 'SE', 'SG', 'SH', 'SI', 'SJ', 'SK', 'SL', 'SM', 'SN', 'SO',
+  'SR', 'SS', 'ST', 'SV', 'SX', 'SY', 'SZ', 'TC', 'TD', 'TF', 'TG', 'TH', 'TJ', 'TK', 'TL', 'TM',
+  'TN', 'TO', 'TR', 'TT', 'TV', 'TW', 'TZ', 'UA', 'UG', 'UM', 'US', 'UY', 'UZ', 'VA', 'VC', 'VE',
+  'VG', 'VI', 'VN', 'VU', 'WF', 'WS', 'XI', 'YE', 'YT', 'ZA', 'ZM', 'ZW',
+] as const
+
+/** International calling codes, digits only — exactly the values
+ * `iso_phone_country_code` accepts ("+39" is rejected server-side). */
+export const PHONE_COUNTRY_CODES = [
+  '1', '7', '20', '27', '30', '31', '32', '33', '34', '36', '39', '40', '41', '43', '44', '45',
+  '46', '47', '48', '49', '51', '52', '53', '54', '55', '56', '57', '58', '60', '61', '62', '63',
+  '64', '65', '66', '81', '82', '84', '86', '90', '91', '92', '93', '94', '95', '98', '211', '212',
+  '213', '216', '218', '220', '221', '222', '223', '224', '225', '226', '227', '228', '229', '230',
+  '231', '232', '233', '234', '235', '236', '237', '238', '239', '240', '241', '242', '243', '244',
+  '245', '246', '247', '248', '249', '250', '251', '252', '253', '254', '255', '256', '257', '258',
+  '260', '261', '262', '263', '264', '265', '266', '267', '268', '269', '290', '291', '297', '298',
+  '299', '350', '351', '352', '353', '354', '355', '356', '357', '358', '359', '370', '371', '372',
+  '373', '374', '375', '376', '377', '378', '380', '381', '382', '383', '385', '386', '387', '389',
+  '420', '421', '423', '500', '501', '502', '503', '504', '505', '506', '507', '508', '509', '590',
+  '591', '592', '593', '594', '595', '596', '597', '598', '599', '670', '672', '673', '674', '675',
+  '676', '677', '678', '679', '680', '681', '682', '683', '685', '686', '687', '688', '689', '690',
+  '691', '692', '850', '852', '853', '855', '856', '880', '886', '960', '961', '962', '963', '964',
+  '965', '966', '967', '968', '970', '971', '972', '973', '974', '975', '976', '977', '992', '993',
+  '994', '995', '996', '998',
+] as const
+
+/**
+ * Representative ISO region per calling code, used ONLY for dropdown labels
+ * ("+39 · Italia"). Shared codes show their main region (libphonenumber's
+ * "main country for code": +1 → US, +7 → RU, ...) without enumerating the
+ * others — the stored value is the calling code, so the ambiguity is purely
+ * cosmetic. "AC" (+247) and "XK" (+383) are not ISO 3166 codes and fall back
+ * to the bare code in `Intl.DisplayNames` lookups.
+ */
+export const PHONE_CODE_PRIMARY_REGION: Record<string, string> = {
+  1: 'US', 7: 'RU', 20: 'EG', 27: 'ZA', 30: 'GR', 31: 'NL', 32: 'BE', 33: 'FR', 34: 'ES',
+  36: 'HU', 39: 'IT', 40: 'RO', 41: 'CH', 43: 'AT', 44: 'GB', 45: 'DK', 46: 'SE', 47: 'NO',
+  48: 'PL', 49: 'DE', 51: 'PE', 52: 'MX', 53: 'CU', 54: 'AR', 55: 'BR', 56: 'CL', 57: 'CO',
+  58: 'VE', 60: 'MY', 61: 'AU', 62: 'ID', 63: 'PH', 64: 'NZ', 65: 'SG', 66: 'TH', 81: 'JP',
+  82: 'KR', 84: 'VN', 86: 'CN', 90: 'TR', 91: 'IN', 92: 'PK', 93: 'AF', 94: 'LK', 95: 'MM',
+  98: 'IR', 211: 'SS', 212: 'MA', 213: 'DZ', 216: 'TN', 218: 'LY', 220: 'GM', 221: 'SN',
+  222: 'MR', 223: 'ML', 224: 'GN', 225: 'CI', 226: 'BF', 227: 'NE', 228: 'TG', 229: 'BJ',
+  230: 'MU', 231: 'LR', 232: 'SL', 233: 'GH', 234: 'NG', 235: 'TD', 236: 'CF', 237: 'CM',
+  238: 'CV', 239: 'ST', 240: 'GQ', 241: 'GA', 242: 'CG', 243: 'CD', 244: 'AO', 245: 'GW',
+  246: 'IO', 247: 'AC', 248: 'SC', 249: 'SD', 250: 'RW', 251: 'ET', 252: 'SO', 253: 'DJ',
+  254: 'KE', 255: 'TZ', 256: 'UG', 257: 'BI', 258: 'MZ', 260: 'ZM', 261: 'MG', 262: 'RE',
+  263: 'ZW', 264: 'NA', 265: 'MW', 266: 'LS', 267: 'BW', 268: 'SZ', 269: 'KM', 290: 'SH',
+  291: 'ER', 297: 'AW', 298: 'FO', 299: 'GL', 350: 'GI', 351: 'PT', 352: 'LU', 353: 'IE',
+  354: 'IS', 355: 'AL', 356: 'MT', 357: 'CY', 358: 'FI', 359: 'BG', 370: 'LT', 371: 'LV',
+  372: 'EE', 373: 'MD', 374: 'AM', 375: 'BY', 376: 'AD', 377: 'MC', 378: 'SM', 380: 'UA',
+  381: 'RS', 382: 'ME', 383: 'XK', 385: 'HR', 386: 'SI', 387: 'BA', 389: 'MK', 420: 'CZ',
+  421: 'SK', 423: 'LI', 500: 'FK', 501: 'BZ', 502: 'GT', 503: 'SV', 504: 'HN', 505: 'NI',
+  506: 'CR', 507: 'PA', 508: 'PM', 509: 'HT', 590: 'GP', 591: 'BO', 592: 'GY', 593: 'EC',
+  594: 'GF', 595: 'PY', 596: 'MQ', 597: 'SR', 598: 'UY', 599: 'CW', 670: 'TL', 672: 'NF',
+  673: 'BN', 674: 'NR', 675: 'PG', 676: 'TO', 677: 'SB', 678: 'VU', 679: 'FJ', 680: 'PW',
+  681: 'WF', 682: 'CK', 683: 'NU', 685: 'WS', 686: 'KI', 687: 'NC', 688: 'TV', 689: 'PF',
+  690: 'TK', 691: 'FM', 692: 'MH', 850: 'KP', 852: 'HK', 853: 'MO', 855: 'KH', 856: 'LA',
+  880: 'BD', 886: 'TW', 960: 'MV', 961: 'LB', 962: 'JO', 963: 'SY', 964: 'IQ', 965: 'KW',
+  966: 'SA', 967: 'YE', 968: 'OM', 970: 'PS', 971: 'AE', 972: 'IL', 973: 'BH', 974: 'QA',
+  975: 'BT', 976: 'MN', 977: 'NP', 992: 'TJ', 993: 'TM', 994: 'AZ', 995: 'GE', 996: 'KG',
+  998: 'UZ',
+}
+
+/**
+ * Countries whose VAT prefix differs from their ISO code. Same mapping as
+ * core-api (`packages/chargebee-schema/src/customers.ts`) and
+ * sp-checkout-frontend: Greece uses "EL" on VATINs.
+ */
+export const COUNTRY_TO_VAT_PREFIX: Record<string, string> = { GR: 'EL' }
+
+/** Derives the VAT prefix to preselect for a billing country (GR → EL). */
+export function countryToVatPrefix(country: string | null | undefined): string | null {
+  if (!country) return null
+  return COUNTRY_TO_VAT_PREFIX[country] ?? country
+}
+
+/**
+ * Normalizes a user-typed phone prefix to the digits-only form the core-api
+ * enum accepts: strips "+", spaces and any other non-digit ("+39 " → "39").
+ * Returns the digits, or '' when nothing is left.
+ */
+export function normalizePhonePrefix(input: string): string {
+  return input.replace(/\D/g, '')
+}
+
+/**
+ * E-invoice routing-code (codice destinatario / `cf_PR_address_code`)
+ * placeholders, mirroring core-api's enforcement matrix
+ * (`normalizeEinvoiceRoutingCodeOrThrow` in `legal-entities/service.ts`):
+ *  - non-IT (any type)        → "XXXXXXX"
+ *  - IT natural_person        → "0000000"
+ *  - IT legal_person          → any 7-char alphanumeric SDI code ("0000000"
+ *                               when invoices are delivered via PEC)
+ */
+export const IT_EINVOICE_PLACEHOLDER = '0000000'
+export const NON_IT_EINVOICE_PLACEHOLDER = 'XXXXXXX'
+export const SDI_CODE_REGEX = /^[A-Za-z0-9]{7}$/
+
+/**
+ * The locked routing-code value for a country/entity-type pair, or null when
+ * the field is freely editable (Italian businesses).
+ */
+export function fixedEinvoiceRoutingCode(
+  countryCode: string | null | undefined,
+  entityType: 'natural_person' | 'legal_person' | null | undefined,
+): string | null {
+  if (!countryCode || !entityType) return null
+  if (countryCode !== 'IT') return NON_IT_EINVOICE_PLACEHOLDER
+  if (entityType === 'natural_person') return IT_EINVOICE_PLACEHOLDER
+  return null
+}

package/_shared/billingLegalEntities.ts

@@ -1,6 +1,29 @@
 import { z } from 'zod'
+import {
+  ISO_A2_COUNTRY_CODES,
+  normalizePhonePrefix,
+  PHONE_COUNTRY_CODES,
+  SDI_CODE_REGEX,
+  VAT_NUMBER_PREFIXES,
+} from './billingGeo.js'
 import { UuidSchema } from './common.js'
 
+const COUNTRY_CODE_SET = new Set<string>(ISO_A2_COUNTRY_CODES)
+const VAT_PREFIX_SET = new Set<string>(VAT_NUMBER_PREFIXES)
+const PHONE_CODE_SET = new Set<string>(PHONE_COUNTRY_CODES)
+
+/** "+39 " → "39", then membership in core-api's `iso_phone_country_code` enum. */
+const PhoneCountryCodeSchema = z
+  .string()
+  .transform(normalizePhonePrefix)
+  .refine(v => PHONE_CODE_SET.has(v), { message: 'Unknown phone country code' })
+const CountryCodeSchema = z
+  .string()
+  .refine(v => COUNTRY_CODE_SET.has(v), { message: 'Unknown country code' })
+const VatNumberPrefixSchema = z
+  .string()
+  .refine(v => VAT_PREFIX_SET.has(v), { message: 'Unknown VAT number prefix' })
+
 export const LegalEntityTypeSchema = z.enum(['natural_person', 'legal_person'])
 
 /**
@@ -54,6 +77,12 @@ export const LegalEntityDetailSchema = z.object({
   einvoiceRoutingCode: z.string(),
   createdAt: z.string(),
   updatedAt: z.string(),
+  /**
+   * PATCH responses only: true when Chargebee/VIES rejected the VAT and
+   * core-api stored it as "unverified" instead of the validated field. The
+   * edit modal surfaces this as a warning toast.
+   */
+  vatNumberUnverified: z.boolean().optional(),
 })
 
 /**
@@ -68,17 +97,21 @@ export const UpdateLegalEntityRequestSchema = z.object({
   companyName: z.string().optional(),
   email: z.string().email().optional(),
   pec: z.string().nullable().optional(),
-  phoneCountryCode: z.string().nullable().optional(),
+  phoneCountryCode: PhoneCountryCodeSchema.nullable().optional(),
   phone: z.string().nullable().optional(),
   address: z.string().optional(),
   postcode: z.string().optional(),
   city: z.string().optional(),
-  state: z.string().optional(),
-  countryCode: z.string().optional(),
-  vatNumberPrefix: z.string().optional(),
+  // Always the 2-character state/province code (TN, NY, 75, …) — core-api
+  // rejects anything else and uppercases on write.
+  state: z.string().regex(/^[A-Za-z0-9]{2}$/).optional(),
+  countryCode: CountryCodeSchema.optional(),
+  vatNumberPrefix: VatNumberPrefixSchema.optional(),
   vatNumber: z.string().optional(),
   taxCode: z.string().optional(),
-  einvoiceRoutingCode: z.string().optional(),
+  // 7 alphanumeric chars: real SDI codes and both placeholders ("0000000",
+  // "XXXXXXX") pass; core-api enforces the full country/type matrix.
+  einvoiceRoutingCode: z.string().regex(SDI_CODE_REGEX).optional(),
 })
 
 /**

package/_shared/billingPaymentMethods.ts

@@ -74,7 +74,13 @@ export const CreatePaymentMethodRequestSchema = z.discriminatedUnion('type', [
 /** One item for a card, one per customer for the IBAN fan-out, plus per-customer failures. */
 export const CreatePaymentMethodsResponseSchema = z.object({
   items: z.array(PaymentMethodSchema),
-  failed: z.array(z.object({ customerId: UuidSchema, reason: z.string() })),
+  failed: z.array(z.object({
+    customerId: UuidSchema,
+    /** Provider message for logs/ops — never shown to the customer. */
+    reason: z.string(),
+    /** Machine-readable failure code (Chargebee api_error_code) the UI maps to localized copy. Optional during core-api rollout. */
+    code: z.string().optional(),
+  })),
 })
 
 export type PaymentMethodType = z.infer<typeof PaymentMethodTypeSchema>

package/_shared/index.ts

@@ -14,6 +14,7 @@ export * from './billingInvoices.js'
 export * from './billingCreditNotes.js'
 export * from './billingPaymentMethods.js'
 export * from './billingLegalEntities.js'
+export * from './billingGeo.js'
 export * from './billingOverview.js'
 export * from './billingDocuments.js'
 export * from './crossSelling.js'

package/_shared/permissions.ts

@@ -1,7 +1,14 @@
 import { z } from 'zod'
 
 const BundleSchema = z.object({
+  /** Has an active or trial billing subscription. */
+  subscribed: z.boolean(),
+  /** Lifecycle product_access capability is on. */
   enabled: z.boolean(),
+  /** Subscribed but blocked by overdue invoices (unpaid past grace). */
+  overdue: z.boolean(),
+  /** Computed: subscribed && enabled — can the user enter the product. */
+  canAccess: z.boolean(),
 })
 
 export const PermissionsResponseSchema = z.object({

package/_shared/products.ts

@@ -15,7 +15,7 @@ export const SuiteLinkSchema = z.object({
 export const OrgProductStatusSchema = z.enum(['active', 'trial', 'not_subscribed'])
 
 /**
- * Billing context surfaced when a paying customer cannot access a product —
+ * Billing context surfaced when a overdue customer cannot access a product —
  * lets the UI explain *why* access is blocked (e.g. an unpaid invoice).
  */
 export const ProductBlockedReasonSchema = z.object({

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,11 @@ export function useApiClient() {
         },
       },
       onRefreshFailed: () => {
-        if (import.meta.client) {
+        if (!import.meta.client) return
+        // An accounting-token exchange is in flight (00.accounting-token
+        // middleware) — redirecting to login now would clobber it.
+        if (new URLSearchParams(window.location.search).has('accounting_token')) return
+        if (!isPublicAuthRoute(window.location.pathname)) {
           window.location.assign(`${PLATFORM_URL}/auth/login`)
         }
       },

package/app/composables/useProductSwitcher.composable.ts

@@ -0,0 +1,114 @@
+import type { PermissionsResponse } from '@package/platform-shared'
+import type { SuiteProduct } from 'nuxt-ui-layer/types';
+import { computed } from 'vue'
+
+type ProductKey = keyof PermissionsResponse['products']
+
+/**
+ * Product access state derived from the subscribed/enabled/overdue matrix
+ * (overdue = subscribed but blocked by unpaid invoices):
+ *
+ * | subscribed | enabled | overdue | state           | action               |
+ * |------------|---------|---------|-----------------|----------------------|
+ * | true       | true    | false   | accessible      | enter product        |
+ * | true       | false   | true    | overdue         | view unpaid invoices |
+ * | true       | false   | false   | blocked         | discovery            |
+ * | false      | true    | false   | not_subscribed  | go to billing        |
+ * | false      | false   | false   | not_subscribed  | discovery            |
+ */
+export type ProductAccessState = 'accessible' | 'overdue' | 'blocked' | 'not_subscribed'
+
+function resolveAccessState(product: { subscribed: boolean; enabled: boolean; overdue: boolean; canAccess: boolean }): ProductAccessState {
+  if (product.canAccess) return 'accessible'
+  if (product.subscribed && product.overdue) return 'overdue'
+  if (product.subscribed && !product.enabled) return 'blocked'
+  if (!product.subscribed && product.enabled) return 'not_subscribed'
+  return 'not_subscribed'
+}
+
+const PRODUCT_KEY_TO_SUITE: Record<ProductKey, SuiteProduct> = {
+  pricing: 'pricing',
+  connect: 'connect',
+  chat: 'chat',
+  smartpms: 'pms',
+}
+
+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,
+  }
+
+  /** Access state for each suite product. */
+  const productStates = computed<Map<SuiteProduct, ProductAccessState>>(() => {
+    const map = new Map<SuiteProduct, ProductAccessState>()
+    if (!permissions.value) return map
+
+    for (const [key, bundle] of Object.entries(permissions.value.products)) {
+      const suite = PRODUCT_KEY_TO_SUITE[key as ProductKey]
+      if (suite) {
+        map.set(suite, resolveAccessState(bundle))
+      }
+    }
+    return map
+  })
+
+  /** Products the user can fully enter (subscribed + enabled). */
+  const enabledProducts = computed<SuiteProduct[]>(() => {
+    const enabled: SuiteProduct[] = ['config' as SuiteProduct]
+
+    for (const [suite, state] of productStates.value) {
+      if (state === 'accessible') {
+        enabled.push(suite)
+      }
+    }
+
+    return enabled
+  })
+
+  const isLoading = computed(() => status.value === 'pending')
+
+  function navigateToProduct(product?: SuiteProduct) {
+    if (!product) return
+
+    const state = productStates.value.get(product) ?? 'not_subscribed'
+
+    switch (state) {
+      case 'accessible': {
+        const url = productUrls[product]
+        if (url) location.assign(url)
+        break
+      }
+      case 'overdue':
+        window.open(`${productUrls.config}/account/overview`, '_blank', 'noopener,noreferrer')
+        break
+      case 'blocked':
+      case 'not_subscribed':
+        window.open(`${productUrls.config}/upgrade`, '_blank', 'noopener,noreferrer')
+        break
+    }
+  }
+
+  function getProductUrl(product: SuiteProduct): string | undefined {
+    return productUrls[product] || undefined
+  }
+
+  function getProductState(product: SuiteProduct): ProductAccessState {
+    return productStates.value.get(product) ?? 'not_subscribed'
+  }
+
+  return {
+    enabledProducts,
+    productStates,
+    isLoading,
+    navigateToProduct,
+    getProductUrl,
+    getProductState,
+  }
+}

package/app/queries/useBillingDocumentPdf.query.ts

@@ -18,5 +18,6 @@ export function useBillingDocumentPdfQuery(
       `/api/orgs/${encodeURIComponent(toValue(orgId))}/billing/documents/${toValue(type)}/${encodeURIComponent(toValue(id))}/pdf`,
     ),
     enabled: () => !!toValue(orgId) && !!toValue(id),
+    staleTime: 0,
   })
 }

package/app/queries/useBillingDocuments.query.ts

@@ -31,5 +31,6 @@ export function useBillingDocumentsQuery(
       { query: toValue(params) },
     ),
     enabled: () => !!toValue(orgId),
+    staleTime: 0,
   })
 }

package/app/queries/useBillingOverview.query.ts

@@ -13,5 +13,6 @@ export function useBillingOverviewQuery(orgId: MaybeRefOrGetter<string>) {
       `/api/orgs/${encodeURIComponent(toValue(orgId))}/billing`,
     ),
     enabled: () => !!toValue(orgId),
+    staleTime: 0,
   })
 }

package/app/queries/useCrossSelling.query.ts

@@ -10,5 +10,6 @@ export function useCrossSellingQuery() {
   return useQuery({
     key: crossSellingKeys.all,
     query: () => client<GetCrossSellingResponse>('/api/me/cross-selling'),
+    staleTime: 0,
   })
 }

package/app/queries/useLegalEntity.query.ts

@@ -16,5 +16,6 @@ export function useLegalEntityQuery(
       `/api/orgs/${encodeURIComponent(toValue(orgId))}/billing/legal-entities/${encodeURIComponent(toValue(id))}`,
     ),
     enabled: () => !!toValue(orgId) && !!toValue(id),
+    staleTime: 0,
   })
 }

package/app/queries/useOrganization.query.ts

@@ -13,5 +13,6 @@ export function useOrganizationQuery(orgId: MaybeRefOrGetter<string>) {
       `/api/orgs/${encodeURIComponent(toValue(orgId))}`,
     ),
     enabled: () => !!toValue(orgId),
+    staleTime: 0,
   })
 }

package/app/queries/usePermissions.query.ts

@@ -10,5 +10,6 @@ export function usePermissionsQuery() {
   return useQuery({
     key: permissionsKeys.all,
     query: () => client<PermissionsResponse>('/api/me/permissions'),
+    staleTime: 0,
   })
 }

package/app/queries/useSession.query.ts

@@ -10,5 +10,6 @@ export function useSessionQuery() {
   return useQuery({
     key: sessionKeys.me,
     query: () => client<MeContextResponse>('/api/me'),
+    staleTime: 0,
   })
 }

package/app/utils/apiClient.utils.ts

@@ -32,12 +32,26 @@ export interface ApiClientOptions {
   onResponseError?: OnResponseErrorHook
 }
 
+function errorCode(data: unknown): string | undefined {
+  return (data as { error?: { code?: string } } | undefined)?.error?.code
+}
+
 function defaultShouldRefresh(status: number, data: unknown): boolean {
   if (status !== 401) return false
-  const code = (data as { error?: { code?: string } } | undefined)?.error?.code
+  const code = errorCode(data)
   return code === 'session.expired' || code === 'session.missing'
 }
 
+/**
+ * Codes that mean the session is dead and can't be recovered by a refresh: a tampered/corrupted or
+ * rotated-secret token (`session.invalid`), or `session.expired`/`session.missing` once a refresh
+ * has already been tried and failed. Distinct from non-session 401s (bad credentials, wrong OTP)
+ * which must NOT trigger a logout redirect.
+ */
+function isDeadSessionCode(code: string | undefined): boolean {
+  return code === 'session.invalid' || code === 'session.expired' || code === 'session.missing'
+}
+
 // Module-level refresh dedup — safe because refresh is client-only
 let refreshPromise: Promise<boolean> | null = null
 
@@ -136,6 +150,17 @@ export function createApiClient(options: ApiClientOptions) {
             serializeAndThrow(retryError)
           }
         }
+      }
+
+      // A dead-session 401 we reach here is unrecoverable: either it wasn't refresh-eligible — a
+      // tampered or rotated-secret token surfaces as `session.invalid`, which never becomes
+      // `session.expired` and so never self-heals — or the refresh above failed. Force re-auth
+      // instead of leaving the client "logged in" while every request 401s (the zombie state: a JWT
+      // secret rotation would drop all active users into it at once). onRefreshFailed does a hard
+      // redirect to login, which reloads the app and discards the stale in-memory auth state; it
+      // self-guards against the accounting-token exchange and public auth routes. Non-session 401s
+      // (bad credentials, wrong OTP) fall through untouched so callers can surface the error.
+      if (status === 401 && isDeadSessionCode(errorCode(data))) {
         auth.onRefreshFailed?.()
       }
 

package/app/utils/auth.utils.ts

@@ -0,0 +1,18 @@
+/**
+ * Auth paths that require an active session despite living under `/auth/`.
+ * Every other `/auth/*` route is public (login, activate, password reset, etc.).
+ */
+const AUTHENTICATED_AUTH_PATHS = ['/auth/otp-step-up', '/auth/products'] as const
+
+/**
+ * Returns `true` for `/auth/*` routes that are reachable without a session
+ * (e.g. login, activate, forgot-password, reset-password).
+ *
+ * Used to:
+ * - skip the boot-time session restore (avoids a guaranteed-to-fail GET /api/me)
+ * - suppress the redirect-to-login on refresh failure
+ */
+export function isPublicAuthRoute(pathname: string): boolean {
+  if (!pathname.startsWith('/auth/')) return false
+  return !AUTHENTICATED_AUTH_PATHS.some(p => pathname.startsWith(p))
+}

package/nuxt.config.ts

@@ -46,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.4",
+  "version": "0.0.6",
   "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.7.1-platform.1",
     "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"
   }
 }