@react-vault/create-app 0.1.0

package/templates/rtk-query/.claude/skills/rtk-query-api/references/cache-strategies.md

@@ -0,0 +1,96 @@
+# Cache strategies — when to use which tagging pattern
+
+## Single-entity tag
+
+When a feature has one type of resource:
+
+```ts
+tagTypes: ['Kyc'];
+// queries: providesTags: ['Kyc']
+// mutations: invalidatesTags: ['Kyc']
+```
+
+Simple. Every mutation refetches everything tagged `Kyc`. Fine for small lists.
+
+## Per-record tags (id-scoped)
+
+When the list is large and you want detail updates to NOT refetch the whole list:
+
+```ts
+providesTags: (result) =>
+  result
+    ? [
+        ...result.items.map(({ id }) => ({ type: 'Kyc' as const, id })),
+        { type: 'Kyc' as const, id: 'LIST' },
+      ]
+    : [{ type: 'Kyc' as const, id: 'LIST' }],
+
+// Detail provides one tag:
+providesTags: (_, __, id) => [{ type: 'Kyc', id }],
+
+// Update mutation invalidates that one tag:
+invalidatesTags: (_, __, { id }) => [{ type: 'Kyc', id }],
+
+// Create mutation invalidates only the list:
+invalidatesTags: [{ type: 'Kyc', id: 'LIST' }],
+```
+
+The `LIST` is a synthetic id used as the "any list" tag.
+
+## Tag everything mutating affects (mutation joined with list)
+
+When an update changes a derived list (e.g. updating a transaction affects account balance):
+
+```ts
+updateTransaction: builder.mutation({
+  invalidatesTags: (_, __, { id }) => [
+    { type: 'Transaction', id },
+    { type: 'AccountBalance' },         // tag from a different api
+  ],
+}),
+```
+
+For cross-API invalidations, the target API must also be in the `tagTypes` registry or you need `invalidateCacheMiddleware` instead.
+
+## Stale-while-revalidate
+
+Default RTK Query behaviour — cached data shows immediately, refetch happens in background. To control:
+
+```ts
+getKycList: builder.query({
+  query: ...,
+  keepUnusedDataFor: 60,   // seconds after last subscriber unsubscribes
+  refetchOnMountOrArgChange: 30, // seconds — refetch if cache > 30s old
+}),
+```
+
+For audit-critical lists where staleness is unacceptable, set `keepUnusedDataFor: 0` so cache is wiped on unmount.
+
+## Skip cache (force fresh)
+
+Pass `{ refetchOnMountOrArgChange: true }` to a single hook call:
+
+```tsx
+const { data } = useGetKycListQuery(undefined, { refetchOnMountOrArgChange: true });
+```
+
+Use ONLY for sensitive views (audit log, balance display in transaction flow).
+
+## Pagination + cache
+
+When paginating, key the query by page so each page caches independently:
+
+```ts
+getKycList: builder.query<KycListResponse, { page: number; pageSize: number }>({
+  query: (params) => ({ url: KYC_URLS.LIST, method: GET, data: params }),
+  providesTags: (result, _, arg) =>
+    result
+      ? [
+          ...result.items.map(({ id }) => ({ type: 'Kyc' as const, id })),
+          { type: 'Kyc' as const, id: `PAGE-${arg.page}` },
+        ]
+      : [{ type: 'Kyc' as const, id: `PAGE-${arg.page}` }],
+}),
+```
+
+This way refetching one page doesn't blow away the others.

package/templates/rtk-query/.claude/skills/rtk-query-api/references/endpoint-cookbook.md

@@ -0,0 +1,145 @@
+# Endpoint cookbook
+
+Templates for the common shapes. Copy + adapt.
+
+## List
+
+```ts
+getKycList: builder.query<KycListResponse, void>({
+  query: () => ({ url: KYC_URLS.LIST, method: GET }),
+  transformResponse: (raw: unknown) => kycListResponseSchema.parse(raw),
+  providesTags: ['Kyc'],
+}),
+```
+
+## Paginated list
+
+```ts
+getKycList: builder.query<KycListResponse, { page: number; pageSize: number; status?: KycStatus }>({
+  query: (params) => ({ url: KYC_URLS.LIST, method: GET, data: params }),
+  transformResponse: (raw: unknown) => kycListResponseSchema.parse(raw),
+  providesTags: (result) =>
+    result
+      ? [
+          ...result.items.map(({ id }) => ({ type: 'Kyc' as const, id })),
+          { type: 'Kyc' as const, id: 'LIST' },
+        ]
+      : [{ type: 'Kyc' as const, id: 'LIST' }],
+}),
+```
+
+## Detail
+
+```ts
+getKycDetail: builder.query<KycRecord, string>({
+  query: (id) => ({ url: KYC_URLS.DETAIL(id), method: GET }),
+  transformResponse: (raw: unknown) => kycRecordSchema.parse(raw),
+  providesTags: (_, __, id) => [{ type: 'Kyc', id }],
+}),
+```
+
+## Create (mutation)
+
+```ts
+submitKyc: builder.mutation<KycRecord, KycSubmitRequest>({
+  query: (body) => ({
+    url: KYC_URLS.SUBMIT,
+    method: POST,
+    data: body,
+    showSuccessNotification: true,
+    showFailureNotification: true,
+  }),
+  transformResponse: (raw: unknown) => kycRecordSchema.parse(raw),
+  invalidatesTags: [{ type: 'Kyc', id: 'LIST' }],
+}),
+```
+
+## Update (mutation, per-record + list invalidation)
+
+```ts
+updateKyc: builder.mutation<KycRecord, { id: string; body: KycUpdateRequest }>({
+  query: ({ id, body }) => ({
+    url: KYC_URLS.DETAIL(id),
+    method: PUT,
+    data: body,
+    showFailureNotification: true,
+  }),
+  transformResponse: (raw: unknown) => kycRecordSchema.parse(raw),
+  invalidatesTags: (_, __, { id }) => [
+    { type: 'Kyc', id },
+    { type: 'Kyc', id: 'LIST' },
+  ],
+}),
+```
+
+## Delete
+
+```ts
+deleteKyc: builder.mutation<void, string>({
+  query: (id) => ({
+    url: KYC_URLS.DETAIL(id),
+    method: DELETE,
+    showSuccessNotification: true,
+    showFailureNotification: true,
+  }),
+  invalidatesTags: (_, __, id) => [
+    { type: 'Kyc', id },
+    { type: 'Kyc', id: 'LIST' },
+  ],
+}),
+```
+
+## Polling (e.g. job status)
+
+In the component:
+
+```tsx
+const { data } = useGetJobStatusQuery(jobId, {
+  pollingInterval: data?.status === 'pending' ? 3000 : 0,
+});
+```
+
+Skip polling once a terminal state is reached by setting interval to 0.
+
+## File upload
+
+```ts
+uploadDocument: builder.mutation<DocumentRecord, FormData>({
+  query: (formData) => ({
+    url: DOCS_URLS.UPLOAD,
+    method: POST,
+    data: formData,
+    headers: { 'Content-Type': 'multipart/form-data' },
+    showFailureNotification: true,
+  }),
+  transformResponse: (raw: unknown) => documentRecordSchema.parse(raw),
+  invalidatesTags: ['Document'],
+}),
+```
+
+## File download (responseType blob)
+
+```ts
+downloadStatement: builder.query<Blob, string>({
+  query: (statementId) => ({
+    url: STATEMENT_URLS.DOWNLOAD(statementId),
+    method: GET,
+    responseType: 'blob',
+  }),
+}),
+```
+
+Trigger from component:
+
+```tsx
+const [trigger] = useLazyDownloadStatementQuery();
+const handleDownload = async (id: string) => {
+  const { data: blob } = await trigger(id).unwrap();
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = `statement-${id}.pdf`;
+  a.click();
+  URL.revokeObjectURL(url);
+};
+```

package/templates/rtk-query/.claude/skills/rtk-query-api/references/optimistic-update.md

@@ -0,0 +1,53 @@
+# Optimistic updates
+
+Use sparingly. Optimistic updates risk showing stale state to the user; only use when the success rate is very high (>99%) AND the perceived latency is meaningful.
+
+## When to use
+
+✅ Good fit:
+
+- Toggling a boolean flag (favourited, archived, read/unread)
+- Reordering a list (drag-and-drop)
+- Inline editing of a single field with very low failure rate
+
+❌ Bad fit:
+
+- Financial transactions (NEVER show success before backend confirms)
+- KYC submissions (regulatory + the value MIGHT be rejected by ML)
+- Anything where the failure path is "value also gets rejected for other reasons we can't predict"
+
+## Pattern — `onQueryStarted` with cache patch
+
+```ts
+toggleFavorite: builder.mutation<void, { id: string; isFavorite: boolean }>({
+  query: ({ id, isFavorite }) => ({
+    url: KYC_URLS.FAVORITE(id),
+    method: PATCH,
+    data: { isFavorite },
+  }),
+  async onQueryStarted({ id, isFavorite }, { dispatch, queryFulfilled }) {
+    // Optimistic: patch the cached list entry
+    const patch = dispatch(
+      kycApi.util.updateQueryData('getKycList', undefined, (draft) => {
+        const item = draft.items.find((x) => x.id === id);
+        if (item) (item as { isFavorite: boolean }).isFavorite = isFavorite;
+      }),
+    );
+
+    try {
+      await queryFulfilled;
+    } catch {
+      // Rollback on failure
+      patch.undo();
+    }
+  },
+  invalidatesTags: (_, __, { id }) => [{ type: 'Kyc', id }],
+}),
+```
+
+## Rules
+
+1. ALWAYS roll back on failure (`patch.undo()`)
+2. Still invalidate tags so the server's truth eventually wins
+3. Don't show success toast optimistically — wait for `queryFulfilled`
+4. Don't optimistically create new entries — wait for the server's ID assignment

package/templates/rtk-query/README.md

@@ -0,0 +1,84 @@
+# Template: RTK Query variant
+
+Overlay applied on top of `templates/_shared/` when the user picks **RTK Query**.
+
+## Structure (mirrors rsense-react-org)
+
+```
+src/
+├── axiosconfig/
+│   ├── axiosInstance.ts          # single shared axios instance
+│   ├── interceptor.ts            # response interceptor (notifications, 401)
+│   └── baseQuery.ts              # axiosBaseQuery for RTK Query
+├── redux/
+│   ├── store.ts                  # configureStore + middleware concat
+│   ├── rootReducer.ts            # combineReducers (slices + API reducers)
+│   ├── reduxHooks.ts             # typed useAppDispatch / useAppSelector
+│   └── invalidateCacheMiddleware.ts  # cross-API tag invalidation
+└── app/
+    └── App.tsx                   # overlays _shared App with <Provider>
+```
+
+## Auth: set-once at login
+
+Tokens are set on the axios instance ONCE at login (rsense pattern, not per-request):
+
+```ts
+import { setAuthToken } from '@react-vault/core/http';
+import axiosInstance from '@/axiosconfig/axiosInstance';
+
+// inside loginApi's onQueryStarted or login slice:
+setAuthToken(axiosInstance, response.token);
+```
+
+On 401, the instance's `onUnauthorized` callback clears the token and redirects to `/login`.
+
+## Feature pattern
+
+```ts
+// src/features/Foo/api.ts
+import { createApi } from '@reduxjs/toolkit/query/react';
+import axiosBaseQuery from '@/axiosconfig/baseQuery';
+import { fooResponseSchema } from './schema';
+import type { FooResponse, FooQuery, FooBody } from './types';
+
+const fooApi = createApi({
+  reducerPath: 'fooApi',
+  baseQuery: axiosBaseQuery(),
+  tagTypes: ['Foo'],
+  endpoints: (builder) => ({
+    getFoos: builder.query<FooResponse, FooQuery>({
+      query: (arg) => ({ url: '/foo', method: 'GET', data: arg }),
+      transformResponse: (raw: unknown) => fooResponseSchema.parse(raw),
+      providesTags: ['Foo'],
+    }),
+    createFoo: builder.mutation<FooResponse, FooBody>({
+      query: (body) => ({
+        url: '/foo',
+        method: 'POST',
+        data: body,
+        showSuccessNotification: true,
+        showFailureNotification: true,
+      }),
+      transformResponse: (raw: unknown) => fooResponseSchema.parse(raw),
+      invalidatesTags: ['Foo'],
+    }),
+  }),
+});
+
+export const { useGetFoosQuery, useCreateFooMutation } = fooApi;
+export default fooApi;
+```
+
+Register the API in `src/redux/rootReducer.ts` (reducer) and `src/redux/store.ts` (middleware).
+
+## Bundled skills (when this variant is picked)
+
+The CLI copies a curated set of RTK-pattern skills into the scaffolded project's `.claude/skills/`:
+
+- `axios-auth`
+- `constants-organization`
+- `redux-store-integration`
+- `rtk-query-api`
+
+Use `/bfsi-feature MyFeature` (provided by the inlined toolkit) — it'll generate RTK-style scaffolding aligned with these skills.

package/templates/rtk-query/package.partial.json

@@ -0,0 +1,7 @@
+{
+  "_comment": "Partial package.json — CLI merges this with templates/_shared/package.json. Adds RTK Query deps.",
+  "dependencies": {
+    "@reduxjs/toolkit": "2.2.3",
+    "react-redux": "9.1.2"
+  }
+}

package/templates/rtk-query/src/app/App.tsx

@@ -0,0 +1,23 @@
+/**
+ * RTK variant App.tsx — overlays the _shared App.tsx with Redux Provider.
+ *
+ * If you need to change the global layout / routes / error boundary, do it
+ * here. This file replaces _shared/src/app/App.tsx during scaffold.
+ */
+import { Provider } from 'react-redux';
+import { BrowserRouter } from 'react-router-dom';
+import { ErrorBoundary } from '../shared/ErrorBoundary.js';
+import { AppRoutes } from '../routes/index.js';
+import store from '../redux/store.js';
+
+export function App(): JSX.Element {
+  return (
+    <ErrorBoundary>
+      <Provider store={store}>
+        <BrowserRouter>
+          <AppRoutes />
+        </BrowserRouter>
+      </Provider>
+    </ErrorBoundary>
+  );
+}

package/templates/rtk-query/src/axiosconfig/axiosInstance.ts

@@ -0,0 +1,26 @@
+/**
+ * Single axios instance shared across the app. Auth token is set ONCE at
+ * login via setAuthToken() from @react-vault/core/http (rsense-style,
+ * set-at-login — not injected per-request).
+ *
+ * Side-effect import of `./interceptor` wires the response interceptor for
+ * notifications + 401 handling.
+ */
+import { createAxios } from '@react-vault/core/http';
+import { env } from '../env.js';
+import './interceptor.js';
+
+const axiosInstance = createAxios({
+  baseURL: env.VITE_API_BASE_URL,
+  timeoutMs: env.VITE_API_TIMEOUT_MS,
+  authHeaderName: env.VITE_AUTH_HEADER_NAME,
+  snakeCaseBackend: false, // flip to true if backend uses snake_case
+  onUnauthorized: () => {
+    // Token already cleared by core; route to login here.
+    if (typeof window !== 'undefined') {
+      window.location.href = '/login';
+    }
+  },
+});
+
+export default axiosInstance;

package/templates/rtk-query/src/axiosconfig/baseQuery.ts

@@ -0,0 +1,72 @@
+/**
+ * Custom RTK Query baseQuery built on the shared axios instance.
+ * Mirrors rsense-react-org's baseQuery: same shape, same notification flags.
+ *
+ * Each endpoint passes:
+ *   { url, method, data, params, headers, showSuccessNotification, showFailureNotification }
+ */
+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,
+    showSuccessNotification: _showSuccess = false,
+    showFailureNotification: _showFailure = false,
+    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);
+
+      // Wire notification dispatch here once you have the slice:
+      // if (showSuccessNotification) {
+      //   store.dispatch(setNotification({ type: 'success', message: result.data?.message }));
+      // }
+
+      return { data: result.data };
+    } catch (axiosError) {
+      const error = axiosError as ApiErrorShape;
+      // if (showFailureNotification) {
+      //   store.dispatch(setNotification({ type: 'error', message: ... }));
+      // }
+      return {
+        error: {
+          status: error.response?.status,
+          data: error.response?.data?.errors,
+        },
+      };
+    }
+  };
+
+export default axiosBaseQuery;

package/templates/rtk-query/src/axiosconfig/interceptor.ts

@@ -0,0 +1,42 @@
+/**
+ * Response interceptor for the shared axios instance. Imported for its side
+ * effect from axiosInstance.ts. Pattern mirrors rsense-react-org.
+ *
+ * - 401: clear local auth state (handled by createAxios's onUnauthorized
+ *   callback), dispatch error notification.
+ * - Other 4xx/5xx: surface the server message via the notification slice.
+ */
+import type { AxiosError, AxiosResponse } from 'axios';
+import axiosInstance from './axiosInstance.js';
+// Wire your notification slice + store here. Placeholders below.
+// 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;
+
+    // Hook this up to your notification slice once you wire it.
+    // store.dispatch(setNotification({ type: 'error', message: extractMessage(err) }));
+
+    if (status === 401) {
+      // 401 is also handled by createAxios's onUnauthorized callback (clears token).
+      // Add your own redirect / dispatch here.
+    }
+
+    return Promise.reject(err);
+  },
+);

package/templates/rtk-query/src/redux/invalidateCacheMiddleware.ts

@@ -0,0 +1,20 @@
+/**
+ * Cross-API cache invalidation middleware. Pattern from rsense-react-org:
+ * when one API's mutation fulfills, invalidate tags on related APIs.
+ *
+ * Add invalidation rules below. The default impl is a no-op; specialise as
+ * cross-API relationships emerge.
+ */
+import type { Middleware } from '@reduxjs/toolkit';
+
+const invalidateCacheMiddleware: Middleware = () => (next) => (action) => {
+  // Example pattern (uncomment + adapt):
+  //
+  // if (kycApi.endpoints.submitKyc.matchFulfilled(action)) {
+  //   storeApi.dispatch(userApi.util.invalidateTags(['User']));
+  // }
+
+  return next(action);
+};
+
+export default invalidateCacheMiddleware;

package/templates/rtk-query/src/redux/reduxHooks.ts

@@ -0,0 +1,10 @@
+/**
+ * Typed Redux hooks — use these instead of plain useDispatch / useSelector.
+ * Same pattern as rsense-react-org.
+ */
+import { useDispatch, useSelector } from 'react-redux';
+import type { TypedUseSelectorHook } from 'react-redux';
+import type { RootState, AppDispatch } from './store.js';
+
+export const useAppDispatch: () => AppDispatch = useDispatch;
+export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector;

package/templates/rtk-query/src/redux/rootReducer.ts

@@ -0,0 +1,18 @@
+/**
+ * Root reducer. Compose every slice + every RTK Query API's reducer here.
+ *
+ * As you add features, import the slice/api and add to the object below.
+ */
+import { combineReducers } from '@reduxjs/toolkit';
+
+const rootReducer = combineReducers({
+  // Slices:
+  // login: loginReducer,
+  // notification: notificationReducer,
+  //
+  // RTK Query API reducers (by their reducerPath):
+  // [loginApi.reducerPath]: loginApi.reducer,
+  // [kycApi.reducerPath]: kycApi.reducer,
+});
+
+export default rootReducer;

package/templates/rtk-query/src/redux/store.ts

@@ -0,0 +1,36 @@
+/**
+ * Redux store. Mirrors rsense-react-org's pattern:
+ *   - configureStore with rootReducer
+ *   - middleware concat with each feature API's middleware (add as you create them)
+ *   - setupListeners for RTK Query refetch-on-focus / reconnect
+ *   - devTools enabled
+ *
+ * As you add features, import their api and:
+ *   1. Register the reducer in ./rootReducer.ts
+ *   2. Add the middleware below
+ */
+import { configureStore } from '@reduxjs/toolkit';
+import { setupListeners } from '@reduxjs/toolkit/query';
+import rootReducer from './rootReducer.js';
+
+const store = configureStore({
+  reducer: rootReducer,
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware({
+      serializableCheck: {
+        ignoredActions: [],
+      },
+    }).concat([
+      // Append feature API middleware here, e.g.:
+      // loginApi.middleware,
+      // kycApi.middleware,
+    ]),
+  devTools: true,
+});
+
+setupListeners(store.dispatch);
+
+export type AppDispatch = typeof store.dispatch;
+export type RootState = ReturnType<typeof store.getState>;
+
+export default store;