@react-vault/create-app 0.1.0

package/templates/_shared/vite.config.ts

@@ -0,0 +1,47 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react-swc';
+import path from 'node:path';
+
+// Vite config for BFSI starter. Notable:
+//   - SWC for fast transpile
+//   - Path alias '@/' → 'src/'
+//   - Server hardening headers (CSP set at deploy edge; dev runs without)
+//   - HMR exposed only on localhost
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+  server: {
+    port: 5173,
+    strictPort: true,
+    host: 'localhost',
+    headers: {
+      'X-Content-Type-Options': 'nosniff',
+      'X-Frame-Options': 'DENY',
+      'Referrer-Policy': 'strict-origin-when-cross-origin',
+      'Permissions-Policy': 'geolocation=(), camera=(), microphone=()',
+    },
+  },
+  build: {
+    target: 'es2022',
+    sourcemap: true,
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          react: ['react', 'react-dom', 'react-router-dom'],
+          forms: ['react-hook-form', 'zod', '@hookform/resolvers'],
+          i18n: ['react-i18next', 'i18next'],
+        },
+      },
+    },
+  },
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['./tests/setup.ts'],
+    globals: true,
+    include: ['src/**/*.test.{ts,tsx}', 'tests/**/*.test.{ts,tsx}'],
+  },
+});

package/templates/rtk-query/.claude/skills/axios-auth/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: axios-auth
+description: Configure the project's axios instance, response interceptor, and RTK Query baseQuery. Sets the auth token ONCE at login via setAuthToken() (not per-request), with response interceptor for notifications + 401 redirect. Use when the user mentions axios, API client, baseQuery, set token, login flow, 401 handling, response interceptor, error notification.
+---
+
+# Axios + Auth Pattern
+
+The HTTP layer is three files under `src/axiosconfig/` plus the auth-token helper from `@<scope>/core/http`. Tokens are set ONCE at login on the axios instance — not injected per-request via interceptor.
+
+## File map
+
+| File                               | Role                                                                                            |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `src/axiosconfig/axiosInstance.ts` | Single shared `AxiosInstance` from `createAxios()`                                              |
+| `src/axiosconfig/interceptor.ts`   | Response interceptor: notifications + 401 redirect. Side-effect import from `axiosInstance.ts`. |
+| `src/axiosconfig/baseQuery.ts`     | `axiosBaseQuery()` for RTK Query — wraps the instance                                           |
+| `@<scope>/core/http`               | Exports `createAxios`, `setAuthToken`, `clearAuthToken`, `ApiError`                             |
+
+## Workflow
+
+### Step 1 — Set token at login (the canonical place)
+
+Inside your login mutation's success path:
+
+```ts
+import { setAuthToken } from '@<scope>/core/http';
+import axiosInstance from '@/axiosconfig/axiosInstance';
+
+// After login API returns { token, ... }:
+setAuthToken(axiosInstance, response.token);
+```
+
+`setAuthToken` writes to `instance.defaults.headers.common.Authorization` (or whatever `authHeaderName` was set). Every subsequent request carries the header automatically — no per-request interceptor needed.
+
+### Step 2 — Clear on logout / 401
+
+`createAxios()` already wires this: when a response is 401, it auto-calls `clearAuthToken(instance)` then invokes the `onUnauthorized` callback (which redirects to `/login` in the scaffolded template).
+
+Manual logout flow:
+
+```ts
+import { clearAuthToken } from '@<scope>/core/http';
+import axiosInstance from '@/axiosconfig/axiosInstance';
+
+clearAuthToken(axiosInstance);
+// then dispatch any session-cleanup action and navigate
+```
+
+### Step 3 — Wire notification dispatch in the interceptor (optional)
+
+The scaffolded `interceptor.ts` has commented-out placeholders for notification dispatch. When you set up a Notification slice, uncomment + adapt:
+
+```ts
+import store from '@/redux/store';
+import { setNotification } from '@/shared/Notification/slice';
+
+// inside the response error handler:
+store.dispatch(setNotification({ type: 'error', message: extractMessage(err) }));
+```
+
+See [`references/notification-wiring.md`](references/notification-wiring.md) for the full pattern.
+
+### Step 4 — Use `axiosBaseQuery` in feature APIs
+
+```ts
+import { createApi } from '@reduxjs/toolkit/query/react';
+import axiosBaseQuery from '@/axiosconfig/baseQuery';
+
+export const fooApi = createApi({
+  reducerPath: 'fooApi',
+  baseQuery: axiosBaseQuery(),
+  tagTypes: ['Foo'],
+  endpoints: (builder) => ({
+    /* ... */
+  }),
+});
+```
+
+Each endpoint can opt-in to success/error notifications via `showSuccessNotification` / `showFailureNotification` flags on the query object.
+
+## Conventions enforced
+
+- ❌ NEVER inject token via a `request.use` interceptor — use `setAuthToken` at login.
+- ❌ NEVER read token from `localStorage` on every request.
+- ❌ NEVER hardcode `Authorization: Bearer ...` anywhere.
+- ✅ One axios instance per app — exported as the default from `axiosInstance.ts`.
+- ✅ Side-effect import of `'./interceptor.js'` in `axiosInstance.ts` so response interceptors are always registered.
+- ✅ All RTK Query APIs use `axiosBaseQuery()` (never the default `fetchBaseQuery`).
+
+## Quick reference checklist
+
+When adding API auth:
+
+- [ ] Login mutation calls `setAuthToken(axiosInstance, token)` on success
+- [ ] Logout / 401 path calls `clearAuthToken(axiosInstance)`
+- [ ] Token never appears in `localStorage` (memory only, set on the instance)
+- [ ] `onUnauthorized` callback in `axiosInstance.ts` redirects to `/login`
+
+## References
+
+- [`references/full-code-walkthrough.md`](references/full-code-walkthrough.md) — annotated walk through all three files in the scaffolded project
+- [`references/notification-wiring.md`](references/notification-wiring.md) — how to wire `showSuccessNotification` / `showFailureNotification` flags to a Notification slice
+- [`references/error-shape.md`](references/error-shape.md) — backend error contract (`ApiError` kinds, field-error format)

package/templates/rtk-query/.claude/skills/axios-auth/references/error-shape.md

@@ -0,0 +1,84 @@
+# Error shape contract
+
+The HTTP layer normalises errors so feature code can pattern-match instead of digging through raw axios errors.
+
+## `ApiError` (from `@<scope>/core/http`)
+
+```ts
+class ApiError extends Error {
+  readonly kind: ApiErrorKind;
+  readonly status?: number;
+  readonly ref?: string;
+  readonly fieldErrors?: Record<string, string>;
+}
+
+type ApiErrorKind =
+  | 'network' // no response, offline, connection refused
+  | 'timeout' // request exceeded timeout
+  | 'unauthorized' // 401
+  | 'forbidden' // 403
+  | 'not_found' // 404
+  | 'conflict' // 409
+  | 'validation' // 422 — fieldErrors populated
+  | 'rate_limited' // 429
+  | 'server_error' // 5xx
+  | 'cancelled' // user cancelled / abort signal
+  | 'unknown';
+```
+
+`createAxios` attaches an error-mapping interceptor that converts every axios error into `ApiError`. Inside `axiosBaseQuery`, you'll catch this — re-throw is fine; RTK Query stores it in `endpoint.error`.
+
+## Backend error envelope
+
+The starter's `axiosBaseQuery` expects backends to return errors as:
+
+```json
+{
+  "errors": [{ "detail": "Email is already taken" }]
+}
+```
+
+Or for field-level (422):
+
+```json
+{
+  "errors": {
+    "email": ["is already taken"],
+    "password": ["is too short"]
+  }
+}
+```
+
+If your backend uses a different shape, override `extractMessage()` in `interceptor.ts` and adjust `axiosBaseQuery`'s error branch.
+
+## Surfacing errors in containers
+
+```tsx
+import type { ApiError } from '@<scope>/core/http';
+
+const [createFoo, { error, isError }] = useCreateFooMutation();
+
+if (isError && error) {
+  const e = error as ApiError;
+  if (e.kind === 'validation' && e.fieldErrors) {
+    // Set field-level errors on RHF:
+    for (const [field, msg] of Object.entries(e.fieldErrors)) {
+      form.setError(field as keyof FormValues, { message: msg });
+    }
+  } else if (e.kind === 'unauthorized') {
+    // Already handled by axios's onUnauthorized — no action needed.
+  } else {
+    // Generic toast — interceptor handles this if showFailureNotification was true.
+  }
+}
+```
+
+## NEVER expose to UI
+
+Per the `bfsi-error-message` reference skill in the toolkit:
+
+- ❌ `error.message` from raw axios — leaks "Network Error" / stack info
+- ❌ `error.response.data.errors` raw — may contain SQL fragments, DB IDs
+- ❌ HTTP status codes as user copy ("Error 500")
+
+Use the safe-error mapping (`toSafeView` from `@<scope>/core/compliance`) to convert `ApiError.kind` into a user-facing toast title + description + ref code.

package/templates/rtk-query/.claude/skills/axios-auth/references/full-code-walkthrough.md

@@ -0,0 +1,146 @@
+# Axios + Auth — full code walkthrough
+
+Annotated tour of the three files the scaffolder lays down.
+
+## `src/axiosconfig/axiosInstance.ts`
+
+```ts
+import { createAxios } from '@<scope>/core/http';
+import { env } from '../env.js';
+import './interceptor.js'; // side-effect: registers response interceptor
+
+const axiosInstance = createAxios({
+  baseURL: env.VITE_API_BASE_URL,
+  timeoutMs: env.VITE_API_TIMEOUT_MS,
+  authHeaderName: env.VITE_AUTH_HEADER_NAME, // default 'Authorization'
+  snakeCaseBackend: false, // flip true for Rails/Python
+  onUnauthorized: () => {
+    if (typeof window !== 'undefined') {
+      window.location.href = '/login';
+    }
+  },
+});
+
+export default axiosInstance;
+```
+
+Key points:
+
+- `createAxios` (from core) attaches the BFSI-grade interceptors: request-IDs, idempotency keys, error mapping to typed `ApiError`.
+- The `onUnauthorized` callback fires AFTER `clearAuthToken` has already wiped the token off the instance.
+- The side-effect `import './interceptor.js'` is critical — it registers the response interceptor when `axiosInstance` is first imported.
+- `snakeCaseBackend: true` enables automatic snake↔camel transformation on bodies and responses.
+
+## `src/axiosconfig/interceptor.ts`
+
+```ts
+import type { AxiosError, AxiosResponse } from 'axios';
+import axiosInstance from './axiosInstance.js';
+// import store from '../redux/store.js';
+// import { setNotification } from '../shared/Notification/slice.js';
+
+export interface ApiErrorShape {
+  config?: { url?: string };
+  response?: {
+    status?: number;
+    data?: {
+      errors?: Array<{ detail?: string; details?: string }> | Record<string, string[]>;
+      message?: string;
+    };
+  };
+}
+
+axiosInstance.interceptors.response.use(
+  (response: AxiosResponse) => response,
+  (error: AxiosError) => {
+    const err = error as unknown as ApiErrorShape;
+    const status = err.response?.status;
+
+    // Wire to your Notification slice when ready:
+    // store.dispatch(setNotification({ type: 'error', message: extractMessage(err) }));
+
+    if (status === 401) {
+      // createAxios's onUnauthorized has already fired (cleared token + navigated).
+      // Add any additional auth-cleanup here.
+    }
+
+    return Promise.reject(err);
+  },
+);
+```
+
+Notes:
+
+- This file ONLY adds the response side. Request-side concerns (auth header, X-Request-Id, Idempotency-Key) are owned by `createAxios`'s built-in interceptors.
+- 401 is double-handled: once in `createAxios` (clears token) and once here (extra cleanup if needed).
+- The notification dispatch is commented-out scaffolding; wire it when you create the Notification slice.
+
+## `src/axiosconfig/baseQuery.ts`
+
+```ts
+import type { AxiosRequestConfig, AxiosResponse, ResponseType } from 'axios';
+import type { BaseQueryFn } from '@reduxjs/toolkit/query';
+import axiosInstance from './axiosInstance.js';
+import type { ApiErrorShape } from './interceptor.js';
+
+const GET = 'GET' as const;
+
+const axiosBaseQuery =
+  (): BaseQueryFn<
+    {
+      url: string;
+      method?: AxiosRequestConfig['method'];
+      data?: AxiosRequestConfig['data'];
+      params?: AxiosRequestConfig['params'];
+      headers?: AxiosRequestConfig['headers'];
+      showSuccessNotification?: boolean;
+      showFailureNotification?: boolean;
+      responseType?: ResponseType;
+    },
+    unknown,
+    unknown
+  > =>
+  async ({ url, method, data, params, headers, responseType }) => {
+    try {
+      const requestConfig: AxiosRequestConfig =
+        method === GET
+          ? { url, method, params: params ?? data, headers }
+          : { url, method, data, params, headers };
+
+      if (responseType) requestConfig.responseType = responseType;
+
+      const result: AxiosResponse = await axiosInstance(requestConfig);
+      return { data: result.data };
+    } catch (axiosError) {
+      const error = axiosError as ApiErrorShape;
+      return {
+        error: {
+          status: error.response?.status,
+          data: error.response?.data?.errors,
+        },
+      };
+    }
+  };
+
+export default axiosBaseQuery;
+```
+
+Notes:
+
+- Endpoints pass `data` for both GET and non-GET — `axiosBaseQuery` routes it correctly (`params` for GET, `data` for others).
+- `showSuccessNotification` / `showFailureNotification` are flags that get inspected here. Wiring goes to the Notification slice once that's set up.
+- Returns the RTK Query `{ data }` / `{ error }` shape. Error.data is the raw `errors` payload — features format it for display.
+
+## Order of imports matters
+
+```
+axiosInstance.ts ─── imports → interceptor.ts (side-effect)
+       │
+       ▼ (default export)
+baseQuery.ts ─── imports → axiosInstance (same singleton)
+       │
+       ▼ (default export)
+features/<X>/api.ts ─── createApi({ baseQuery: axiosBaseQuery() })
+```
+
+Anyone calling `axiosInstance` (directly or via baseQuery) gets a fully-interceptor-wired instance because of the side-effect import chain.

package/templates/rtk-query/.claude/skills/axios-auth/references/notification-wiring.md

@@ -0,0 +1,141 @@
+# Notification wiring
+
+`axiosBaseQuery` and `interceptor.ts` both have commented-out hooks for dispatching toast notifications. This is how you wire them once you have a Notification slice.
+
+## 1. Create the slice
+
+`src/shared/Notification/slice.ts`:
+
+```ts
+import { createSlice, type PayloadAction } from '@reduxjs/toolkit';
+
+export type NotificationType = 'success' | 'error' | 'info' | 'warning';
+
+interface NotificationState {
+  type: NotificationType | null;
+  message: string;
+}
+
+const initialState: NotificationState = { type: null, message: '' };
+
+const notificationSlice = createSlice({
+  name: 'notification',
+  initialState,
+  reducers: {
+    setNotification: (
+      state,
+      action: PayloadAction<{ type: NotificationType; message: string }>,
+    ) => {
+      state.type = action.payload.type;
+      state.message = action.payload.message;
+    },
+    clearNotification: (state) => {
+      state.type = null;
+      state.message = '';
+    },
+  },
+});
+
+export const { setNotification, clearNotification } = notificationSlice.actions;
+export const notificationReducer = notificationSlice.reducer;
+```
+
+Register it in `src/redux/rootReducer.ts`:
+
+```ts
+import { notificationReducer } from '@/shared/Notification/slice';
+
+const rootReducer = combineReducers({
+  notification: notificationReducer,
+  // ...
+});
+```
+
+## 2. Wire into the response interceptor
+
+Uncomment in `src/axiosconfig/interceptor.ts`:
+
+```ts
+import store from '../redux/store.js';
+import { setNotification } from '../shared/Notification/slice.js';
+
+// inside the response error handler:
+store.dispatch(
+  setNotification({
+    type: 'error',
+    message: extractMessage(err),
+  }),
+);
+```
+
+A typical `extractMessage`:
+
+```ts
+function extractMessage(err: ApiErrorShape): string {
+  const errors = err.response?.data?.errors;
+  if (Array.isArray(errors) && errors[0]) {
+    return errors[0].detail ?? errors[0].details ?? 'Request failed';
+  }
+  if (errors && typeof errors === 'object') {
+    const firstKey = Object.keys(errors)[0];
+    const firstVal = firstKey ? errors[firstKey]?.[0] : undefined;
+    return firstVal ?? 'Validation failed';
+  }
+  return err.response?.data?.message ?? 'Request failed';
+}
+```
+
+## 3. Wire into `axiosBaseQuery`
+
+Each endpoint sets `showSuccessNotification` / `showFailureNotification`. Adapt `baseQuery.ts`:
+
+```ts
+import store from '../redux/store.js';
+import { setNotification } from '../shared/Notification/slice.js';
+
+// success branch:
+if (showSuccessNotification) {
+  store.dispatch(setNotification({ type: 'success', message: result.data?.message }));
+}
+
+// failure branch:
+if (showFailureNotification) {
+  store.dispatch(setNotification({ type: 'error', message: extractMessage(error) }));
+}
+```
+
+## 4. Render the notifications
+
+A small `<Notification />` component listens to the slice and renders toast UI (shadcn `<Toast>`, Sonner, etc.):
+
+```tsx
+import { useEffect } from 'react';
+import { useAppSelector, useAppDispatch } from '@/redux/reduxHooks';
+import { clearNotification } from './slice';
+import { toast } from 'sonner';
+
+export function Notification() {
+  const { type, message } = useAppSelector((s) => s.notification);
+  const dispatch = useAppDispatch();
+
+  useEffect(() => {
+    if (!type) return;
+    toast[type](message);
+    const t = setTimeout(() => dispatch(clearNotification()), 3000);
+    return () => clearTimeout(t);
+  }, [type, message, dispatch]);
+
+  return null;
+}
+```
+
+Mount it once in `App.tsx`:
+
+```tsx
+<Provider store={store}>
+  <Notification />
+  <BrowserRouter>
+    <AppRoutes />
+  </BrowserRouter>
+</Provider>
+```

package/templates/rtk-query/.claude/skills/constants-organization/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: constants-organization
+description: Where each kind of constant lives in the project and how to add a new one. Covers URL endpoint constants, HTTP method constants, route paths, RTK Query tag types, validation regex patterns, and app-wide constants. Use when adding a new endpoint URL, route path, tag type, validation regex, or any other shared constant.
+---
+
+# Constants Organisation
+
+Constants are split across files by purpose. Each kind has one home — don't scatter.
+
+## File map
+
+```
+src/utils/constants/
+├── apiConstants.ts       HTTP method names, API version, base URL helpers
+├── appConstants.ts       App-wide enums (ERROR / SUCCESS, storage keys, etc.)
+├── urlConstants.ts       Every API endpoint URL string
+├── routeConstants.ts     Every router path
+├── tagTypes.ts           RTK Query cache tag type names
+└── regexConstants.ts     Reusable validation regex
+```
+
+## When to use which
+
+| Adding …                     | Goes in             | Naming convention                              |
+| ---------------------------- | ------------------- | ---------------------------------------------- |
+| A backend endpoint URL       | `urlConstants.ts`   | `<FEATURE>_URLS.<ACTION>` or `<FEATURE>_URL`   |
+| A frontend route path        | `routeConstants.ts` | `ROUTES.<feature>.<view>` or `<FEATURE>_ROUTE` |
+| An HTTP method (GET/POST/…)  | `apiConstants.ts`   | `GET`, `POST` constants                        |
+| An RTK Query tag type        | `tagTypes.ts`       | `<Feature>Tag` literal in array                |
+| A validation regex           | `regexConstants.ts` | `<FIELD>_REGEX`                                |
+| A storage key                | `appConstants.ts`   | `<PURPOSE>_KEY`                                |
+| An enum value used > 1 place | `appConstants.ts`   | `<NAME>` (UPPER_SNAKE)                         |
+
+## Workflow — adding a new endpoint
+
+1. Open `src/utils/constants/urlConstants.ts`.
+2. Add to the appropriate feature block (or create one):
+   ```ts
+   export const KYC_URLS = {
+     LIST: '/kyc',
+     DETAIL: (id: string) => `/kyc/${id}`,
+     SUBMIT: '/kyc/submit',
+   } as const;
+   ```
+3. Reference from the feature's `api.ts`:
+   ```ts
+   import { KYC_URLS } from '@/utils/constants/urlConstants';
+   ```
+4. If this endpoint introduces a new tag type, add it to `tagTypes.ts` and to the feature API's `tagTypes` array.
+
+See [`references/example-files.md`](references/example-files.md) for full file templates.
+
+## Workflow — adding a new route
+
+1. Open `src/utils/constants/routeConstants.ts`.
+2. Add the path:
+   ```ts
+   export const ROUTES = {
+     kyc: {
+       list: '/kyc',
+       detail: '/kyc/:id',
+       submit: '/kyc/submit',
+     },
+   } as const;
+   ```
+3. Wire it in `src/routes/index.tsx`:
+   ```tsx
+   <Route
+     path={ROUTES.kyc.list}
+     element={
+       <ProtectedRoute permission="kyc.view">
+         <KycList />
+       </ProtectedRoute>
+     }
+   />
+   ```
+
+## Workflow — adding a validation regex
+
+Always centralise — never inline a regex in a Zod schema.
+
+1. Open `src/utils/constants/regexConstants.ts`.
+2. Add with documentation:
+   ```ts
+   // PAN: 5 letters + 4 digits + 1 letter
+   export const PAN_REGEX = /^[A-Z]{5}[0-9]{4}[A-Z]$/;
+   ```
+3. Use in Zod:
+
+   ```ts
+   import { PAN_REGEX } from '@/utils/constants/regexConstants';
+
+   const schema = z.object({
+     pan: z.string().regex(PAN_REGEX, { message: 'Invalid PAN' }),
+   });
+   ```
+
+The starter's `@<scope>/core/pii` already exports `PII_PATTERNS` with common BFSI regexes (PAN, Aadhaar, IFSC, mobile, email, etc.). Re-export those from `regexConstants.ts` rather than redefining.
+
+## Conventions enforced
+
+- ❌ NEVER hardcode a URL string in `api.ts` — always reference `urlConstants.ts`.
+- ❌ NEVER inline a regex in component code or schema — always via `regexConstants.ts`.
+- ❌ NEVER use a magic string for tag types — always via `tagTypes.ts`.
+- ✅ Group by feature within each constants file (e.g. `KYC_URLS`, `LOAN_URLS`).
+- ✅ Use `as const` on the exported objects so TypeScript infers literal types.
+- ✅ Functions for dynamic paths (`DETAIL: (id) => ...`), strings for static ones.
+
+## References
+
+- [`references/example-files.md`](references/example-files.md) — full templates for each constants file
+- [`references/tag-types-catalog.md`](references/tag-types-catalog.md) — RTK Query tag type naming + when each is invalidated