@react-vault/create-app 0.1.0

package/templates/tanstack-query/.claude/skills/tanstack-services/references/audited-mutation.md

@@ -0,0 +1,144 @@
+# Audited mutation wrapper
+
+Every state-changing API call in a BFSI app should emit an audit event (RBI Annexure I §8, SOC2 CC7.3). Without an `axiosBaseQuery`-style abstraction, we wrap `useMutation` with a custom hook.
+
+## The wrapper
+
+```ts
+// src/services/useAuditedMutation.ts
+import {
+  useMutation,
+  type UseMutationOptions,
+  type UseMutationResult,
+} from '@tanstack/react-query';
+import type { ApiError } from '@<scope>/core/http';
+import { AuditClient, generateEventId } from '@<scope>/core/audit';
+import { env } from '@/env';
+
+const auditClient = new AuditClient({
+  endpoint: env.VITE_AUDIT_ENDPOINT,
+  batchSize: env.VITE_AUDIT_BATCH_SIZE,
+  flushIntervalMs: env.VITE_AUDIT_FLUSH_INTERVAL_MS,
+});
+
+export interface UseAuditedMutationOptions<TData, TVars>
+  extends UseMutationOptions<TData, ApiError, TVars> {
+  /** Audit event name — convention: <feature>.<entity>.<action> */
+  eventName: string;
+  /** Optional toast on success */
+  successMessage?: string;
+  /** Function to extract audit target from variables */
+  getTarget?: (vars: TVars) => { type: string; id?: string };
+}
+
+export function useAuditedMutation<TData, TVars>(
+  options: UseAuditedMutationOptions<TData, TVars>,
+): UseMutationResult<TData, ApiError, TVars> {
+  return useMutation({
+    ...options,
+    onMutate: async (vars) => {
+      // Record audit event (pending)
+      const eventId = generateEventId();
+      const target = options.getTarget?.(vars);
+      auditClient.record({
+        event_id: eventId,
+        event_name: options.eventName,
+        actor_id: getCurrentUserId(), // your auth context
+        target_type: target?.type,
+        target_id: target?.id,
+        timestamp: new Date().toISOString(),
+        outcome: 'pending',
+      });
+      // Pass eventId through context for outcome update on success/error
+      const inherited = await options.onMutate?.(vars);
+      return { eventId, inherited } as never;
+    },
+    onSuccess: (data, vars, ctx) => {
+      const eventId = (ctx as { eventId: string } | undefined)?.eventId;
+      if (eventId) {
+        auditClient.record({
+          event_id: eventId,
+          event_name: options.eventName,
+          actor_id: getCurrentUserId(),
+          timestamp: new Date().toISOString(),
+          outcome: 'success',
+        });
+      }
+      options.onSuccess?.(data, vars, ctx);
+    },
+    onError: (err, vars, ctx) => {
+      const eventId = (ctx as { eventId: string } | undefined)?.eventId;
+      if (eventId) {
+        auditClient.record({
+          event_id: eventId,
+          event_name: options.eventName,
+          actor_id: getCurrentUserId(),
+          timestamp: new Date().toISOString(),
+          outcome: 'failure',
+        });
+      }
+      options.onError?.(err, vars, ctx);
+    },
+  });
+}
+
+function getCurrentUserId(): string {
+  // Wire to your auth context
+  return 'TODO';
+}
+```
+
+## Usage
+
+```tsx
+const submit = useAuditedMutation({
+  mutationFn: submitKyc,
+  eventName: 'kyc.verification.submitted',
+  successMessage: 'KYC submitted successfully',
+  getTarget: (payload) => ({ type: 'kyc_record', id: undefined }), // id assigned on success
+  onSuccess: (record) => {
+    queryClient.invalidateQueries({ queryKey: kycKeys.all });
+    navigate(`/kyc/${record.id}`);
+  },
+});
+```
+
+## Audit event naming
+
+`<feature>.<entity>.<action>` — see `bfsi-feature` skill in the toolkit for full naming convention. Examples:
+
+- `kyc.verification.submitted`
+- `kyc.verification.approved`
+- `transaction.transfer.initiated`
+- `user.session.logged_in`
+- `data.pan.revealed` (when PII is unmasked)
+
+## Why this wraps useMutation
+
+In the RTK variant, audit events flow through the `axiosBaseQuery` because that's the single chokepoint every API call goes through. In TanStack, there's no equivalent — each service call is direct. The wrapper hook brings back the chokepoint for state-changing operations.
+
+You CAN skip the wrapper for read-only queries (no audit needed for reads, by default). Reads via `useQuery` don't get the wrapper.
+
+## Reveal events (separate from mutations)
+
+When a user clicks "reveal PAN" in `<PIIMaskedDisplay>`, you fire an audit event directly:
+
+```tsx
+<PIIMaskedDisplay
+  type="pan"
+  value={user.pan}
+  onReveal={() =>
+    auditClient.record({
+      event_id: generateEventId(),
+      event_name: 'data.pan.revealed',
+      actor_id: getCurrentUserId(),
+      target_type: 'user',
+      target_id: user.id,
+      timestamp: new Date().toISOString(),
+      outcome: 'success',
+    })
+  }
+/>
+```
+
+No mutation involved — just a direct audit call.

package/templates/tanstack-query/.claude/skills/tanstack-services/references/optimistic-update.md

@@ -0,0 +1,102 @@
+# Optimistic updates (TanStack)
+
+Use sparingly. Optimistic updates risk showing stale state to the user; only use when success rate is very high AND latency is meaningful to the user.
+
+## When to use
+
+✅ Good fit:
+
+- Toggling a boolean (favourited, archived, read/unread)
+- Reordering a list (drag-and-drop)
+- Inline editing of a single field
+
+❌ Bad fit:
+
+- Financial transactions (NEVER show success before backend confirms)
+- KYC submissions (regulatory + may be rejected by ML)
+- Anything where failure is plausible
+
+## Pattern — `onMutate` + rollback
+
+```tsx
+const queryClient = useQueryClient();
+
+const toggleFavorite = useMutation({
+  mutationFn: async (args: { id: string; isFavorite: boolean }) => {
+    return PATCH<IKycRecord, { isFavorite: boolean }>(KYC_URLS.FAVORITE(args.id), {
+      isFavorite: args.isFavorite,
+    });
+  },
+  onMutate: async ({ id, isFavorite }) => {
+    // Cancel any outgoing refetches so they don't overwrite our optimistic update
+    await queryClient.cancelQueries({ queryKey: kycKeys.detail(id) });
+
+    // Snapshot the previous value
+    const previous = queryClient.getQueryData<IKycRecord>(kycKeys.detail(id));
+
+    // Optimistic update
+    if (previous) {
+      queryClient.setQueryData<IKycRecord>(kycKeys.detail(id), {
+        ...previous,
+        isFavorite,
+      });
+    }
+
+    // Return rollback context
+    return { previous };
+  },
+  onError: (_err, { id }, context) => {
+    if (context?.previous) {
+      queryClient.setQueryData(kycKeys.detail(id), context.previous);
+    }
+  },
+  onSettled: (_data, _err, { id }) => {
+    // Always refetch to reconcile with server truth
+    queryClient.invalidateQueries({ queryKey: kycKeys.detail(id) });
+  },
+});
+```
+
+## Rules
+
+1. ALWAYS `cancelQueries` first — otherwise an in-flight fetch overwrites the optimistic update on settle.
+2. ALWAYS snapshot the previous value before patching — needed for rollback.
+3. ALWAYS rollback in `onError` using the context returned by `onMutate`.
+4. ALWAYS reconcile in `onSettled` (invalidate or refetch).
+5. NEVER toast "success" optimistically — wait for `onSuccess`.
+6. NEVER optimistically create new entries that need a server-assigned ID — wait for `onSuccess` to know the real ID.
+
+## Optimistic across multiple queries
+
+If a mutation should optimistically update both detail AND a list:
+
+```ts
+onMutate: async ({ id, isFavorite }) => {
+  await queryClient.cancelQueries({ queryKey: kycKeys.detail(id) });
+  await queryClient.cancelQueries({ queryKey: kycKeys.lists() });
+
+  const previousDetail = queryClient.getQueryData<IKycRecord>(kycKeys.detail(id));
+  const previousLists = queryClient.getQueriesData<IKycListResponse>({ queryKey: kycKeys.lists() });
+
+  // Patch detail
+  if (previousDetail) {
+    queryClient.setQueryData<IKycRecord>(kycKeys.detail(id), {
+      ...previousDetail,
+      isFavorite,
+    });
+  }
+
+  // Patch every cached list page
+  for (const [key, list] of previousLists) {
+    if (!list) continue;
+    queryClient.setQueryData<IKycListResponse>(key, {
+      ...list,
+      items: list.items.map((item) =>
+        item.id === id ? { ...item, isFavorite } : item,
+      ),
+    });
+  }
+
+  return { previousDetail, previousLists };
+},
+```

package/templates/tanstack-query/.claude/skills/tanstack-services/references/service-cookbook.md

@@ -0,0 +1,151 @@
+# Service cookbook (TanStack)
+
+Templates for common shapes. Copy + adapt.
+
+## List
+
+```ts
+export const getKycList = async (): Promise<IKycListResponse> => {
+  const raw = await GET<unknown>(KYC_URLS.LIST);
+  return kycListResponseSchema.parse(raw);
+};
+```
+
+## Paginated list
+
+```ts
+export const getKycList = async (params: {
+  page: number;
+  pageSize: number;
+  status?: KycStatus;
+}): Promise<IKycListResponse> => {
+  const raw = await GET<unknown, typeof params>(KYC_URLS.LIST, params);
+  return kycListResponseSchema.parse(raw);
+};
+
+// Component:
+const { data } = useQuery({
+  queryKey: kycKeys.list({ page, pageSize, status }),
+  queryFn: () => getKycList({ page, pageSize, status }),
+  placeholderData: (prev) => prev, // smooth pagination — keep previous data visible
+});
+```
+
+## Detail
+
+```ts
+export const getKycDetail = async (id: string): Promise<IKycRecord> => {
+  const raw = await GET<unknown>(KYC_URLS.DETAIL(id));
+  return kycRecordSchema.parse(raw);
+};
+```
+
+## Create
+
+```ts
+export const submitKyc = async (payload: IKycSubmitRequest): Promise<IKycRecord> => {
+  const raw = await POST<unknown, IKycSubmitRequest>(KYC_URLS.SUBMIT, payload);
+  return kycRecordSchema.parse(raw);
+};
+
+// Component:
+const submit = useMutation({
+  mutationFn: submitKyc,
+  onSuccess: (newRecord) => {
+    queryClient.invalidateQueries({ queryKey: kycKeys.lists() });
+    queryClient.setQueryData(kycKeys.detail(newRecord.id), newRecord);
+  },
+});
+```
+
+## Update
+
+```ts
+export const updateKyc = async (args: {
+  id: string;
+  body: IKycUpdateRequest;
+}): Promise<IKycRecord> => {
+  const raw = await PUT<unknown, IKycUpdateRequest>(KYC_URLS.DETAIL(args.id), args.body);
+  return kycRecordSchema.parse(raw);
+};
+
+// Component:
+const update = useMutation({
+  mutationFn: updateKyc,
+  onSuccess: (updated, { id }) => {
+    queryClient.invalidateQueries({ queryKey: kycKeys.lists() });
+    queryClient.setQueryData(kycKeys.detail(id), updated);
+  },
+});
+```
+
+Pattern: mutations that take both an id and a body wrap them in a single object. Keeps `mutationFn` typed as `(args: {...}) => Promise<...>` rather than overloaded.
+
+## Delete
+
+```ts
+export const deleteKyc = (id: string): Promise<void> => DELETE<void>(KYC_URLS.DETAIL(id));
+
+// Component:
+const del = useMutation({
+  mutationFn: deleteKyc,
+  onSuccess: (_, id) => {
+    queryClient.invalidateQueries({ queryKey: kycKeys.lists() });
+    queryClient.removeQueries({ queryKey: kycKeys.detail(id) });
+  },
+});
+```
+
+## Polling (e.g. async job status)
+
+```ts
+export const getJobStatus = async (jobId: string): Promise<IJobStatus> => {
+  const raw = await GET<unknown>(JOB_URLS.STATUS(jobId));
+  return jobStatusSchema.parse(raw);
+};
+
+// Component:
+const { data } = useQuery({
+  queryKey: jobKeys.status(jobId),
+  queryFn: () => getJobStatus(jobId),
+  refetchInterval: (query) => {
+    const status = query.state.data?.status;
+    return status === 'completed' || status === 'failed' ? false : 3000;
+  },
+});
+```
+
+## File upload
+
+```ts
+export const uploadDocument = async (file: File): Promise<IDocumentRecord> => {
+  const form = new FormData();
+  form.append('file', file);
+  const raw = await POST<unknown, FormData>(DOCS_URLS.UPLOAD, form, {
+    headers: { 'Content-Type': 'multipart/form-data' },
+  });
+  return documentRecordSchema.parse(raw);
+};
+```
+
+## File download
+
+```ts
+export const downloadStatement = (id: string): Promise<Blob> =>
+  GET<Blob, void>(STATEMENT_URLS.DOWNLOAD(id), undefined, { responseType: 'blob' });
+```
+
+## Parallel fetches in one query
+
+```ts
+export const getDashboardData = async (userId: string): Promise<IDashboardData> => {
+  const [profile, accounts, recent] = await Promise.all([
+    GET<unknown>(USER_URLS.PROFILE(userId)),
+    GET<unknown>(ACCOUNT_URLS.LIST_FOR_USER(userId)),
+    GET<unknown>(TX_URLS.RECENT_FOR_USER(userId, { limit: 5 })),
+  ]);
+  return dashboardSchema.parse({ profile, accounts, recent });
+};
+```
+
+Components calling this get one queryKey, one loading state, one error — even though it makes 3 HTTP calls.

package/templates/tanstack-query/README.md

@@ -0,0 +1,63 @@
+# Template: TanStack Query variant
+
+Overlay applied on top of `templates/_shared/` when the user picks **TanStack Query**.
+
+## Adds
+
+- `@tanstack/react-query` + devtools + `zustand` deps
+- `src/api/axiosInstance.ts` — single shared axios instance from `@<projectName>/core/http`
+- `src/api/http.ts` — typed `GET<TRes, TParams>`, `POST<TRes, TReq>`, `PUT`, `PATCH`, `DELETE` helpers
+- `src/api/queryClient.ts` — `QueryClient` with BFSI defaults (30s stale, no focus refetch, no mutation retry)
+- `src/services/example.ts` — reference service showing the `IRequest`/`IResponse` pattern
+- `src/app/App.tsx` — overlays \_shared App with `<QueryClientProvider>`
+
+## Service-method pattern (vs RTK Query's dispatch style)
+
+You call services directly — no hooks, no dispatch:
+
+```ts
+// src/services/kyc.ts
+import { POST, GET } from '@/api/http';
+
+export interface IKycRequest {
+  pan: string;
+  aadhaar: string;
+}
+export interface IKycResponse {
+  id: string;
+  status: 'pending' | 'approved';
+}
+
+export const submitKyc = (payload: IKycRequest): Promise<IKycResponse> =>
+  POST<IKycResponse, IKycRequest>('/kyc', payload);
+
+export const getKyc = (id: string): Promise<IKycResponse> => GET<IKycResponse>(`/kyc/${id}`);
+```
+
+Inside components, wire with hooks:
+
+```tsx
+import { useMutation, useQuery } from '@tanstack/react-query';
+import { submitKyc, getKyc } from '@/services/kyc';
+
+const submit = useMutation({ mutationFn: submitKyc });
+const detail = useQuery({ queryKey: ['kyc', id], queryFn: () => getKyc(id) });
+```
+
+## Auth: set-once at login
+
+The axios instance has no per-request token interceptor. Set the token once at login:
+
+```ts
+import { setAuthToken } from '@react-vault/core/http';
+import axiosInstance from '@/api/axiosInstance';
+
+// inside login mutation onSuccess:
+setAuthToken(axiosInstance, response.token);
+```
+
+On 401, the instance's `onUnauthorized` callback clears the token and redirects to `/login`.
+
+## Why Zustand for client state
+
+TanStack Query owns **server state** (fetches, caches, invalidation). Use Zustand for **client state** (UI state surviving route changes, form drafts, cross-component selections). Don't use Zustand for server data — that's what TanStack Query is for.

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

@@ -0,0 +1,8 @@
+{
+  "_comment": "Partial package.json — CLI merges this with templates/_shared/package.json. Adds TanStack Query + Zustand deps.",
+  "dependencies": {
+    "@tanstack/react-query": "5.32.1",
+    "@tanstack/react-query-devtools": "5.32.1",
+    "zustand": "4.5.2"
+  }
+}

package/templates/tanstack-query/src/api/axiosInstance.ts

@@ -0,0 +1,20 @@
+/**
+ * Single axios instance for the app. Auth token set ONCE at login via
+ * setAuthToken() — not per-request.
+ */
+import { createAxios } from '@react-vault/core/http';
+import { env } from '../env.js';
+
+const axiosInstance = createAxios({
+  baseURL: env.VITE_API_BASE_URL,
+  timeoutMs: env.VITE_API_TIMEOUT_MS,
+  authHeaderName: env.VITE_AUTH_HEADER_NAME,
+  snakeCaseBackend: false,
+  onUnauthorized: () => {
+    if (typeof window !== 'undefined') {
+      window.location.href = '/login';
+    }
+  },
+});
+
+export default axiosInstance;

package/templates/tanstack-query/src/api/http.ts

@@ -0,0 +1,62 @@
+/**
+ * Typed HTTP helpers for TanStack Query feature services.
+ *
+ * Usage:
+ *   import { GET, POST, PUT, PATCH, DELETE } from '@/api/http';
+ *
+ *   interface ILoginRequest { email: string; password: string; }
+ *   interface ILoginResponse { token: string; userId: string; }
+ *
+ *   export const loginService = (payload: ILoginRequest) =>
+ *     POST<ILoginResponse, ILoginRequest>('/auth/login', payload);
+ *
+ * Pair with useMutation / useQuery:
+ *   const m = useMutation({ mutationFn: loginService });
+ *   const q = useQuery({ queryKey: ['kyc', id], queryFn: () => getKyc(id) });
+ */
+import type { AxiosRequestConfig } from 'axios';
+import axiosInstance from './axiosInstance.js';
+
+export async function GET<TResponse, TParams = void>(
+  url: string,
+  params?: TParams,
+  config?: AxiosRequestConfig,
+): Promise<TResponse> {
+  const { data } = await axiosInstance.get<TResponse>(url, { ...config, params });
+  return data;
+}
+
+export async function POST<TResponse, TRequest = void>(
+  url: string,
+  payload?: TRequest,
+  config?: AxiosRequestConfig,
+): Promise<TResponse> {
+  const { data } = await axiosInstance.post<TResponse>(url, payload, config);
+  return data;
+}
+
+export async function PUT<TResponse, TRequest = void>(
+  url: string,
+  payload?: TRequest,
+  config?: AxiosRequestConfig,
+): Promise<TResponse> {
+  const { data } = await axiosInstance.put<TResponse>(url, payload, config);
+  return data;
+}
+
+export async function PATCH<TResponse, TRequest = void>(
+  url: string,
+  payload?: TRequest,
+  config?: AxiosRequestConfig,
+): Promise<TResponse> {
+  const { data } = await axiosInstance.patch<TResponse>(url, payload, config);
+  return data;
+}
+
+export async function DELETE<TResponse = void>(
+  url: string,
+  config?: AxiosRequestConfig,
+): Promise<TResponse> {
+  const { data } = await axiosInstance.delete<TResponse>(url, config);
+  return data;
+}

package/templates/tanstack-query/src/api/queryClient.ts

@@ -0,0 +1,28 @@
+/**
+ * TanStack Query client with BFSI-friendly defaults:
+ *   - 30s stale time (don't thrash refetching)
+ *   - No refetch on focus (user's choice, not surprise)
+ *   - Don't retry 4xx (except 408/429)
+ *   - Mutations never auto-retry (use idempotency-key + explicit retry)
+ */
+import { QueryClient } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 30_000,
+      gcTime: 5 * 60_000,
+      retry: (failureCount, error) => {
+        const status = (error as { status?: number })?.status;
+        if (status && status >= 400 && status < 500 && status !== 408 && status !== 429) {
+          return false;
+        }
+        return failureCount < 2;
+      },
+      refetchOnWindowFocus: false,
+    },
+    mutations: {
+      retry: false,
+    },
+  },
+});

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

@@ -0,0 +1,20 @@
+/**
+ * TanStack variant App.tsx — overlays the _shared App.tsx with QueryClientProvider.
+ */
+import { QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+import { ErrorBoundary } from '../shared/ErrorBoundary.js';
+import { AppRoutes } from '../routes/index.js';
+import { queryClient } from '../api/queryClient.js';
+
+export function App(): JSX.Element {
+  return (
+    <ErrorBoundary>
+      <QueryClientProvider client={queryClient}>
+        <BrowserRouter>
+          <AppRoutes />
+        </BrowserRouter>
+      </QueryClientProvider>
+    </ErrorBoundary>
+  );
+}

package/templates/tanstack-query/src/services/example.ts

@@ -0,0 +1,32 @@
+/**
+ * Example service. Pattern to copy for new features:
+ *
+ *   1. Define IRequest / IResponse interfaces
+ *   2. Export plain async functions that call GET/POST/PUT/PATCH/DELETE
+ *   3. Use them inside React components via useQuery / useMutation
+ *
+ * Keep services in src/services/<feature>.ts or src/features/<Feature>/service.ts —
+ * either works. Don't put TanStack hooks here; this layer is hook-free so
+ * services are easy to unit-test.
+ */
+import { GET, POST } from '../api/http.js';
+
+export interface IExampleListResponse {
+  items: Array<{ id: string; name: string }>;
+  total: number;
+}
+
+export interface IExampleCreateRequest {
+  name: string;
+}
+
+export interface IExampleCreateResponse {
+  id: string;
+  name: string;
+}
+
+export const getExamples = (): Promise<IExampleListResponse> =>
+  GET<IExampleListResponse>('/examples');
+
+export const createExample = (payload: IExampleCreateRequest): Promise<IExampleCreateResponse> =>
+  POST<IExampleCreateResponse, IExampleCreateRequest>('/examples', payload);